AI导哈

教育资源协议服务器

OpenEdu MCP Server是一个为教育工作者提供教育资源和支持课程规划的模型上下文协议服务器，集成多个教育API，提供书籍、文章、定义和研究论文的智能教育过滤和年级适应性访问。

  • by Cicatriiz
  • Python
  • 本地部署
  • 13 星标
  • 更新于
在 GitHub 查看 Cicatriiz/openedu-mcp

使用说明

OpenEdu MCP服务器

一个全面的模型上下文协议（MCP）服务器，旨在为教育工作者提供教育资源和支持课程规划。此服务器与多个教育API集成，通过智能教育过滤和年级适当性提供对书籍、文章、定义和研究论文的访问。

🎓 特性

完整的API集成套件

  • 📚 开放式图书馆集成：教育书籍搜索、推荐和元数据
  • 🌐 维基百科集成：带年级过滤的教育文章分析
  • 📖 词典集成：词汇分析和语言学习支持
  • 🔬 arXiv集成：具有教育相关性评分的学术论文搜索

教育智慧

  • 等级过滤：K-2、3-5、6-8、9-12，大学水平的内容
  • 主题分类：数学、科学、ELA、社会研究、艺术、体育、技术
  • 课程调整：通用核心、NGSS、国家标准支持
  • 教育元数据：复杂性评分、阅读水平、教育价值评估

性能和可靠性

  • 智能高速缓存：基于SQLite的缓存，支持TTL
  • 速率限制：遵守API配额的内置速率限制
  • 使用情况分析：全面的使用情况跟踪和性能指标
  • 错误处理：强大的错误处理和教育背景保护

🚀 快速开始

先决条件

  • Python 3.9或更高版本
  • pip包管理器

安装

  1. 克隆存储库：
git clone https://github.com/Cicatriiz/openedu-mcp.git
cd openedu-mcp
  1. 安装依赖项：
pip install -r requirements.txt
  1. 设置配置：
cp .env.example .env
# Edit .env with your preferred settings if needed
  1. 运行服务器：
python -m src.main
  1. 测试安装：
   python run_validation_tests.py

开发设置

对于开发，请安装其他依赖项：

pip install -r requirements-dev.txt

运行测试：

# Unit tests
pytest tests/

# Integration tests
pytest tests/test_integration/

# Performance tests
pytest tests/test_performance.py

格式代码：

black src tests
isort src tests

🛠️ MCP工具参考

教育MCP服务器提供 21+MCP工具 跨越四个API集成：

📚 打开库工具（4个工具）

search_educational_books

使用年级和学科过滤搜索教育书籍。

search_educational_books(
    query="mathematics",
    subject="Mathematics", 
    grade_level="6-8",
    limit=10
)

get_book_details_by_isbn

通过ISBN和教育元数据获取详细的图书信息。

get_book_details_by_isbn(
    isbn="9780134685991",
    include_cover=True
)

search_books_by_subject

按课程对齐的教育科目搜索书籍。

search_books_by_subject(
    subject="Science",
    grade_level="3-5",
    limit=10
)

get_book_recommendations

获取针对特定年级的精选书籍推荐。

get_book_recommendations(
    grade_level="9-12",
    subject="Physics",
    limit=5
)

🌐 维基百科工具（5个工具）

search_educational_articles

使用教育过滤和分析搜索维基百科文章。

search_educational_articles(
    query="photosynthesis",
    grade_level="3-5",
    subject="Science",
    limit=5
)

get_article_summary

获取包含教育元数据和复杂性分析的文章摘要。

get_article_summary(
    title="Solar System",
    include_educational_analysis=True
)

get_article_content

通过教育丰富获得完整的文章内容。

get_article_content(
    title="Photosynthesis",
    include_images=True
)

get_featured_article

获取维基百科的教育分析专题文章。

get_featured_article(
    date="2024/01/15",
    language="en"
)

get_articles_by_subject

通过年级过滤按教育主题获取文章。

get_articles_by_subject(
    subject="Mathematics",
    grade_level="6-8",
    limit=10
)

📖 词典工具（5个工具）

get_word_definition

获得具有适当等级复杂性的教育性单词定义。

get_word_definition(
    word="ecosystem",
    grade_level="6-8",
    include_pronunciation=True
)

get_vocabulary_analysis

分析单词的复杂性和教育价值。

get_vocabulary_analysis(
    word="photosynthesis",
    context="plant biology lesson"
)

get_word_examples

获取词汇的教育示例和使用背景。

get_word_examples(
    word="fraction",
    grade_level="3-5",
    subject="Mathematics"
)

get_pronunciation_guide

获取语音信息和发音指南。

get_pronunciation_guide(
    word="photosynthesis",
    include_audio=True
)

get_related_vocabulary

获取同义词、反义词和相关教育术语。

get_related_vocabulary(
    word="democracy",
    relationship_type="related",
    grade_level="9-12",
    limit=10
)

🔬 arXiv工具（5个工具）

search_academic_papers

使用教育相关性过滤搜索学术论文。

search_academic_papers(
    query="machine learning education",
    academic_level="Undergraduate",
    subject="Computer Science",
    max_results=10
)

get_paper_summary

获取包含教育分析和可访问性评分的论文摘要。

get_paper_summary(
    paper_id="2301.00001",
    include_educational_analysis=True
)

get_recent_research

按教育主题获取最新研究论文。

get_recent_research(
    subject="Physics",
    days=30,
    academic_level="High School",
    max_results=5
)

get_research_by_level

获得适合特定学术水平的研究论文。

get_research_by_level(
    academic_level="Graduate",
    subject="Mathematics",
    max_results=10
)

analyze_research_trends

分析研究趋势以获得教育见解。

analyze_research_trends(
    subject="Artificial Intelligence",
    days=90
)

🖥️ 服务器工具（1个工具）

get_server_status

获取全面的服务器状态和性能指标。

get_server_status()

🔌 连接端点

本节详细介绍如何通过各种接口与OpenEdu MCP服务器交互，包括直接标准I/O、用于工具执行的HTTP和用于实时更新的服务器发送事件。

标准工具(handle_stdio_input)

该服务器包括一个专为直接命令行或管道输入而设计的工具。

  • 工具名称: handle_stdio_input
  • 描述：处理单行文本输入并返回转换后的版本。如果配置为侦听stdin，这对于与MCP服务器的基本交互或脚本编写非常有用。
  • 签名: async def handle_stdio_input(ctx: Context, input_string: str) -> str
  • 交互示例:
    Tool: handle_stdio_input
Input: "your text here"
Output: "Processed: YOUR TEXT HERE"

MCP工具的HTTP端点

所有注册的MCP工具（包括 handle_stdio_input 以及上面列出的20多种工具）可以通过HTTP访问。这允许与各种应用程序和服务集成。服务器可能使用JSON RPC样式进行这些交互。

  • 端点: POST /mcp （这是支持JSON RPC的FastMCP服务器的常见约定）

  • 请求方法: POST

  • 标头: Content-Type: application/json

  • 请求体结构（JSON RPC）:

    {
    "jsonrpc": "2.0",
    "method": "<tool_name>",
    "params": {"param1": "value1", ...},
    "id": "your_request_id"
}

  • 示例 curl 呼吁 handle_stdio_input:

    curl -X POST -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "method": "handle_stdio_input", "params": {"input_string": "hello from http"}, "id": 1}' \
     http://localhost:8000/mcp

  • 预期响应:

    {
    "jsonrpc": "2.0",
    "result": "Processed: HELLO FROM HTTP",
    "id": 1
}

    如果发生错误 result 字段将被替换为 error 对象包含 code 和 message.

服务器发送事件（SSE）终结点

服务器为实时通知提供SSE端点。这对于需要随时了解服务器启动事件的客户端非常有用。

  • 端点: GET /events

  • 描述：将事件从服务器流式传输到客户端。

  • 事件格式：每个事件都以文本块的形式发送：

    event: <event_type>
data: <json_payload_of_the_event_data>
id: <optional_event_id>

    （注意：事件之间用空行分隔。）

  • 已知事件:

    • connected：客户端成功连接到SSE流时发送一次。
      • data: {"message": "Successfully connected to SSE stream"}
    • ping：作为心跳定期发送，以保持连接畅通并指示服务器运行状况。
      • data: {"heartbeat": <loop_count>, "message": "ping"} （循环计数增量）
    • error：如果SSE生成流中发生错误，则发送。
      • data: {"error": "<error_message>"}

  • 示例：连接JavaScript EventSource:

    const evtSource = new EventSource("http://localhost:8000/events");

evtSource.onopen = function() {
    console.log("Connection to SSE opened.");
};

evtSource.onmessage = function(event) {
    // Generic message handler if no specific event type is matched
    console.log("Generic message:", event.data);
    try {
        const parsedData = JSON.parse(event.data);
        console.log("Parsed generic data:", parsedData);
    } catch (e) {
        // Data might not be JSON
    }
};

evtSource.addEventListener("connected", function(event) {
    console.log("Event: connected");
    console.log("Data:", JSON.parse(event.data));
});

evtSource.addEventListener("ping", function(event) {
    console.log("Event: ping");
    console.log("Data:", JSON.parse(event.data));
});

evtSource.addEventListener("error", function(event) {
    if (event.target.readyState === EventSource.CLOSED) {
        console.error("SSE Connection was closed.", event);
    } else if (event.target.readyState === EventSource.CONNECTING) {
        console.error("SSE Connection is reconnecting...", event);
    } else {
        // An error occurred while streaming, data might be available
        console.error("SSE Error:", event);
         if (event.data) {
            try {
                console.error("Error Data:", JSON.parse(event.data));
            } catch (e) {
                console.error("Error Data (raw):", event.data);
            }
        }
    }
});

  • 示例：连接 curl:

    curl -N -H "Accept:text/event-stream" http://localhost:8000/events

    （注： curl 将保持连接打开，并在事件到达时打印事件。)

💻 编辑器和AI工具集成

您可以将OpenEdu MCP服务器与各种AI辅助编码工具和IDE插件集成。这允许这些工具在您的开发环境中直接利用服务器的教育功能。配置通常涉及告诉编辑器如何启动OpenEdu MCP服务器并与之通信。服务器运行时使用 python -m src.main 从这个项目的根源。

下面是一些流行工具的示例配置。您可能需要调整路径（例如 cwd 或者如果你有一个特定的Python环境）。

光标

要将此服务器添加到Cursor IDE，请执行以下操作：

  1. 首选 Cursor Settings > MCP.
  2. 点击 + Add new Global MCP Server.
  3. 或者，将以下配置添加到全局 .cursor/mcp.json 文件（确保 cwd 指向此项目的根目录）：
{
  "mcpServers": {
    "openedu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "/path/to/your/openedu-mcp" // Replace with the actual path to this project's root
    }
  }
}

有关更多详细信息，请参阅Cursor文档。

帆板运动

要使用Windsurf（前身为Cascade）设置MCP：

  1. 引导到 Windsurf - Settings > Advanced Settings 或使用命令面板 Open Windsurf Settings Page.
  2. 向下滚动到Cascade部分，并将OpenEdu MCP服务器直接添加到 mcp_config.json （确保 cwd 指向此项目的根目录）：
{
  "mcpServers": {
    "openedu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "/path/to/your/openedu-mcp" // Replace with the actual path to this project's root
    }
  }
}

克莱恩

手动将以下JSON添加到您的 cline_mcp_settings.json 通过Cline的MCP服务器设置（确保 cwd 指向此项目的根目录）：

{
  "mcpServers": {
    "openedu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "/path/to/your/openedu-mcp" // Replace with the actual path to this project's root
    }
  }
}

Roo代码

通过单击访问MCP设置 Edit MCP Settings 在Roo Code设置中或使用 Roo Code: Open MCP Config VS Code命令面板中的命令（确保 cwd 指向此项目的根目录）：

{
  "mcpServers": {
    "openedu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "/path/to/your/openedu-mcp" // Replace with the actual path to this project's root
    }
  }
}

克劳德

将以下内容添加到您的 claude_desktop_config.json 文件（确保 cwd 指向此项目的根目录）：

{
  "mcpServers": {
    "openedu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "/path/to/your/openedu-mcp" // Replace with the actual path to this project's root
    }
  }
}

有关更多详细信息，请参阅Claude Desktop文档（如果可用）。

📋 教育用例

基础教育（K-2）

# Find age-appropriate books
books = await search_educational_books(
    query="animals", 
    grade_level="K-2", 
    subject="Science"
)

# Get simple definitions
definition = await get_word_definition(
    word="habitat", 
    grade_level="K-2"
)

# Find educational articles
articles = await search_educational_articles(
    query="animal homes", 
    grade_level="K-2"
)

中学STEM（6-8）

# Get math textbooks
books = await search_books_by_subject(
    subject="Mathematics", 
    grade_level="6-8"
)

# Analyze vocabulary complexity
analysis = await get_vocabulary_analysis(
    word="equation", 
    context="solving math problems"
)

# Find related terms
related = await get_related_vocabulary(
    word="algebra", 
    grade_level="6-8"
)

高中高级（9-12）

# Get physics recommendations
books = await get_book_recommendations(
    grade_level="9-12", 
    subject="Physics"
)

# Get detailed articles
article = await get_article_content(
    title="Quantum mechanics"
)

# Find accessible research
papers = await search_academic_papers(
    query="climate change", 
    academic_level="High School"
)

大学研究

# Find academic textbooks
books = await search_educational_books(
    query="calculus", 
    grade_level="College"
)

# Get recent research
research = await get_recent_research(
    subject="Computer Science", 
    academic_level="Graduate"
)

# Analyze trends
trends = await analyze_research_trends(
    subject="Machine Learning"
)

⚙️ 配置

配置文件

服务器在 config/ 目录：

# config/default.yaml
server:
  name: "openedu-mcp-server"
  version: "1.0.0"

education:
  grade_levels:
    - "K-2"
    - "3-5" 
    - "6-8"
    - "9-12"
    - "College"
  
  subjects:
    - "Mathematics"
    - "Science"
    - "English Language Arts"
    - "Social Studies"
    - "Arts"
    - "Physical Education"
    - "Technology"

apis:
  open_library:
    rate_limit: 100  # requests per minute
  wikipedia:
    rate_limit: 200  # requests per minute
  dictionary:
    rate_limit: 450  # requests per hour
  arxiv:
    rate_limit: 3    # requests per second

环境变量

用环境变量覆盖配置：

export OPENEDU_MCP_CACHE_TTL=7200
export OPENEDU_MCP_LOG_LEVEL=DEBUG
export OPENEDU_MCP_RATE_LIMIT_WIKIPEDIA=300

🏗️ 建筑

Education MCP Server
├── API Layer (FastMCP)
│   ├── 20+ MCP Tools
│   └── Request/Response Handling
├── Service Layer
│   ├── Cache Service (SQLite)
│   ├── Rate Limiting Service
│   └── Usage Tracking Service
├── Tool Layer
│   ├── Open Library Tools
│   ├── Wikipedia Tools
│   ├── Dictionary Tools
│   └── arXiv Tools
├── API Layer
│   ├── Open Library API
│   ├── Wikipedia API
│   ├── Dictionary API
│   └── arXiv API
└── Data Layer
    ├── Educational Models
    ├── Cache Database
    └── Usage Analytics

📊 演出

缓存策略

  • 缓存命中率：重复查询率>70%
  • 响应时间：缓存请求<500ms，未缓存请求<2000ms
  • 缓存大小：可配置自动清理功能
  • TTL管理：基于内容类型的智能过期

速率限制

  • 开放图书馆：100个请求/分钟
  • 维基百科：200个请求/分钟
  • 词典：450个请求/小时
  • arXiv：3个请求/秒

并发处理

  • 异步操作：所有API调用的非阻塞I/O
  • 连接池：高效的HTTP连接管理
  • 资源限制：可配置的内存和磁盘使用限制

🧪 测试

运行所有测试

# Unit tests
pytest tests/test_tools/ -v

# Integration tests
pytest tests/test_integration/ -v

# Performance tests
pytest tests/test_performance.py -v

# Real API tests (requires internet)
make validate

测试覆盖率

pytest --cov=src --cov-report=html
open htmlcov/index.html

验证测试

make validate

🧪 真正的API验证测试

我们已经实施了全面的实际验证测试，以确保生产准备就绪。这些测试根据实时服务验证功能，而不是模拟。

特性

  • 根据各自的实时API测试所有20+MCP工具
  • 验证不同年级的教育工作流程
  • 衡量性能指标（响应时间、缓存率、错误率）
  • 测试无效输入和边缘情况下的错误处理
  • 使用真实的API响应验证缓存行为

运行验证测试

python run_validation_tests.py

脚本将：

  1. 测试所有API集成（开放库、维基百科、词典、arXiv）
  2. 验证教育工作流程：
    • 基础教育（K-2）
    • 高中STEM（9-12）
    • 大学研究
    • 教育者资源
  3. 衡量绩效指标：
    • 每个API的响应时间
    • 缓存命中率/未命中率
    • 限速有效性
    • 教育过滤处理时间
  4. 生成包含测试结果和性能统计信息的详细JSON报告

测试用例

  1. 开放图书馆:

    • 使用年级过滤搜索“哈利波特”
    • 按ISBN获取图书详细信息（例如，9780439064866）
    • 查看已知书籍的可用性
    • 验证教育元数据的丰富性

  2. 维基百科:

    • 用学术水平过滤搜索“量子力学”
    • 获取“阿尔伯特·爱因斯坦”的文章摘要
    • 检索当天的特色文章
    • 验证内容分析和复杂性评分

  3. 词典API:

    • 从教育背景中获得“光合作用”的定义
    • 藜麦发音测试指南
    • 验证STEM术语的词汇分析
    • 测试等级的适当定义

  4. arXiv:

    • 使用教育过滤搜索“机器学习”论文
    • 获取最近的AI研究论文
    • 验证学术水平评估
    • 测试研究趋势分析

📚 文档

🔧 开发状态

✅ 完成-所有功能均已实现

核心基础设施✅

  • [x] 项目结构和配置
  • [x] 核心服务（缓存、速率限制、使用情况跟踪）
  • [x] 基础模型和验证
  • [x] FastMCP服务器设置
  • [x] 教育过滤框架

API集成✅

  • [x] 开放库API集成（4个工具）
  • [x] 维基百科API集成（5个工具）
  • [x] 词典API集成（5个工具）
  • [x] arXiv API集成（5个工具）
  • [x] 教育内容过滤
  • [x] 跨API教育工作流程

测试和文件✅

  • [x] 综合单元测试
  • [x] 集成测试套件
  • [x] 性能基准
  • [x] 具有所有功能的演示脚本
  • [x] 完整的文档
  • [x] API参考指南

🤝 贡献

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 进行更改
  4. 添加新功能的测试
  5. 运行测试套件(pytest)
  6. 提交您的更改(git commit -m 'Add amazing feature')
  7. 推到分支(git push origin feature/amazing-feature)
  8. 打开拉取请求

开发指南

  • 遵循PEP 8风格指南
  • 为所有函数添加类型提示
  • 包含所有公共方法的文档字符串
  • 为新功能编写测试
  • 根据需要更新文档

📄 许可证

该项目根据MIT许可证获得许可。

🆘 支持

对于问题、议题或贡献：

  • 问题：在存储库中创建问题
  • 文档：检查 docs/ 目录
  • 讨论：使用GitHub讨论提问
  • 电子邮件：联系维护人员

🙏 致谢

  • 内置于 FastMCP 框架
  • 与开放库、维基百科、词典API和arXiv集成
  • 专为教育用例和课程规划而设计
  • 受无障碍教育技术需求的启发

OpenEdu MCP服务器 -为教育工作者提供智能教育资源发现和课程规划工具。

相关 MCP