OpenEdu MCP Server

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

🎓 功能

完整的API集成套件

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

教育智能

• 年级过滤：K-2、3-5、6-8、9-12、大学水平内容
• 科目分类：数学、科学、英语语言艺术、社会研究、艺术、体育、技术
• 课程对齐：支持共同核心标准、NGSS、州标准
• 教育元数据：复杂度评分、阅读级别、教育价值评估

性能与可靠性

• 智能缓存：基于SQLite的缓存，支持TTL
• 速率限制：内置速率限制以尊重API配额
• 使用分析：全面的使用跟踪和性能指标
• 错误处理：强大的错误处理，保留教育上下文

🚀 快速开始

先决条件

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

安装

1. 克隆仓库：

git clone https://github.com/Cicatriiz/openedu-mcp.git
cd openedu-mcp

2. 安装依赖项：

pip install -r requirements.txt

3. 设置配置：

cp .env.example .env
# 如需修改，请编辑 .env 文件

4. 运行服务器：

python -m src.main

5. 测试安装：

python run_validation_tests.py

开发环境设置

对于开发，安装额外的依赖项：

pip install -r requirements-dev.txt

运行测试：

# 单元测试
pytest tests/

# 集成测试
pytest tests/test_integration/

# 性能测试
pytest tests/test_performance.py

格式化代码：

black src tests
isort src tests

🛠️ MCP 工具参考

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

📚 Open Library 工具 (4个工具)

search_educational_books

按年级和科目筛选教育书籍。

search_educational_books(
    query="数学",
    subject="数学",
    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="科学",
    grade_level="3-5",
    limit=1
)

get_book_recommendations

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

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

🌐 维基百科工具 (5个工具)

search_educational_articles

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

search_educational_articles(
    query="光合作用",
    grade_level="3-5",
    subject="科学",
    limit=5
)

get_article_summary

获取文章摘要，带教育元数据和复杂度分析。

get_article_summary(
    title="太阳系",
    include_educational_analysis=True
)

get_article_content

获取全文内容，带教育丰富内容。

get_article_content(
    title="光合作用",
    include_images=True
)

get_featured_article

获取维基百科特色文章，带教育分析。

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

get_articles_by_subject

按教育科目获取文章，带年级过滤。

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

📖 字典工具 (5个工具)

get_word_definition

获取适合年级的教育词汇定义。

get_word_definition(
    word="生态系统",
    grade_level="6-8",
    include_pronunciation=True
)

get_vocabulary_analysis

分析词汇复杂度和教育价值。

get_vocabulary_analysis(
    word="光合作用",
    context="植物生物学课程"
)

get_word_examples

获取词汇的教育示例和使用情境。

get_word_examples(
    word="分数",
    grade_level="3-5",
    subject="数学"
)

get_pronunciation_guide

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

get_pronunciation_guide(
    word="光合作用",
    include_audio=True
)

get_related_vocabulary

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

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

🔬 arXiv 工具 (5个工具)

search_academic_papers

搜索学术论文，带教育相关性过滤。

search_academic_papers(
    query="机器学习教育",
    academic_level="本科",
    subject="计算机科学",
    max_results=10
)

get_paper_summary

获取论文摘要，带教育分析和可访问性评分。

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

get_recent_research

获取最近的研究论文，按教育科目。

get_recent_research(
    subject="物理",
    days=30,
    academic_level="高中",
    max_results=5
)

get_research_by_level

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

get_research_by_level(
    academic_level="研究生",
    subject="数学",
    max_results=10
)

analyze_research_trends

分析研究趋势，获取教育洞察。

analyze_research_trends(
    subject="人工智能",
    days=90
)

🖥️ 服务器工具 (1个工具)

get_server_status

获取综合服务器状态和性能指标。

get_server_status()

🔌 连接端点

本节详细介绍了如何通过各种接口与 OpenEdu MCP 服务器进行交互，包括直接标准 I/O、HTTP 执行工具以及用于实时更新的 Server-Sent Events。

标准 I/O 工具 (handle_stdio_input)

服务器包含一个工具，设计用于直接命令行或管道输入。

• 工具名称：handle_stdio_input
• 描述：处理单行文本输入并返回转换后的版本。如果配置为监听标准输入，这对于基本交互或脚本与 MCP 服务器的交互非常有用。
• 签名：async def handle_stdio_input(ctx: Context, input_string: str) -> str
• 示例交互：

  工具：handle_stdio_input
  输入："此处为您的文本"
  输出："Processed: 您的文本"
  

HTTP 端点用于 MCP 工具

所有注册的 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": "来自http的问候"}, "id": 1}' \
       http://localhost:8000/mcp
  

• 预期响应：

  {
      "jsonrpc": "2.0",
      "result": "Processed: 来自HTTP的问候",
      "id": 1
  }
  

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

Server-Sent Events (SSE) 端点

服务器提供 SSE 端点用于实时通知。这对于需要与服务器发起事件保持同步的客户端非常有用。

• 端点：GET /events

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

• 事件格式：每个事件作为一段文本发送：

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

  （注意：空行分隔事件）

• 已知事件：

  • connected：当客户端成功连接到 SSE 流时发送一次。
    • data：{"message": "成功连接到 SSE 流"}
  • ping：定期发送心跳信号以保持连接活跃并指示服务器健康状况。
    • data：{"heartbeat": <loop_count>, "message": "ping"}（loop_count 增加）
  • error：在 SSE 生成流中发生错误时发送。
    • data：{"error": "<错误消息>"}

• 示例：使用 JavaScript 的 EventSource 连接：

  const evtSource = new EventSource("http://localhost:8000/events");
  
  evtSource.onopen = function() {
      console.log("连接到 SSE 已打开。");
  };
  
  evtSource.onmessage = function(event) {
      // 如果没有匹配特定事件类型，则通用消息处理器
      console.log("通用消息：", event.data);
      try {
          const parsedData = JSON.parse(event.data);
          console.log("解析的通用数据：", parsedData);
      } catch (e) {
          // 数据可能不是 JSON
      }
  };
  
  evtSource.addEventListener("connected", function(event) {
      console.log("事件：connected");
      console.log("数据：", JSON.parse(event.data));
  });
  
  evtSource.addEventListener("ping", function(event) {
      console.log("事件：ping");
      console.log("数据：", JSON.parse(event.data));
  });
  
  evtSource.addEventListener("error", function(event) {
      if (event.target.readyState === EventSource.CLOSED) {
          console.error("SSE 连接已关闭。", event);
      } else if (event.target.readyState === EventSource.CONNECTING) {
          console.error("SSE 连接正在重新连接...", event);
      } else {
          // 在流式传输过程中发生了错误，数据可能可用
          console.error("SSE 错误：", event);
          if (event.data) {
              try {
                  console.error("错误数据：", JSON.parse(event.data));
              } catch (e) {
                  console.error("错误数据（原始）：", 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

要将此服务器添加到 Cursor IDE：

1. 转到 Cursor 设置 > MCP。
2. 点击 + 添加新的全局 MCP 服务器。
3. 或者，将以下配置添加到您的全局 .cursor/mcp.json 文件中（确保 cwd 指向此项目的根目录）：

{
  "mcpServers": {
    "openedu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "/path/to/your/openedu-mcp" // 替换为此项目根的实际路径
    }
  }
}

参阅 Cursor 文档以获取更多详细信息。

Windsurf

要在 Windsurf（原名 Cascade）中设置 MCP：

1. 导航到 Windsurf - 设置 > 高级设置 或使用命令面板 打开 Windsurf 设置页面。
2. 向下滚动到 Cascade 部分，并在 mcp_config.json 中直接添加 OpenEdu MCP 服务器（确保 cwd 指向此项目的根目录）：

{
  "mcpServers": {
    "openedu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "/path/to/your/openedu-mcp" // 替换为此项目根的实际路径
    }
  }
}

Cline

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

{
  "mcpServers": {
    "openedu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "/path/to/your/openedu-mcp" // 替换为此项目根的实际路径
    }
  }
}

Roo Code

通过点击 Roo Code 设置中的 编辑 MCP 设置 或使用 VS Code 命令面板中的 Roo Code: 打开 MCP 配置 命令来访问 MCP 设置（确保 cwd 指向此项目的根目录）：

{
  "mcpServers": {
    "openedu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "/path/to/your/openedu-mcp" // 替换为此项目根的实际路径
    }
  }
}

Claude

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

{
  "mcpServers": {
    "openedu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "/path/to/your/openedu-mcp" // 替换为此项目根的实际路径
    }
  }
}

参阅 Claude Desktop 文档以获取更多详细信息（如有）。

📋 教育用途案例

小学教育 (K-2)

# 查找适合年龄的书籍
books = await search_educational_books(
    query="动物",
    grade_level="K-2",
    subject="科学"
)

# 获取简单定义
definition = await get_word_definition(
    word="栖息地",
    grade_level="K-2"
)

# 查找教育文章
articles = await search_educational_articles(
    query="动物家园",
    grade_level="K-2"
)

中学STEM (6-8)

# 获取数学教科书
books = await search_books_by_subject(
    subject="数学",
    grade_level="6-8"
)

# 分析词汇复杂度
analysis = await get_vocabulary_analysis(
    word="方程",
    context="解决数学问题"
)

# 查找相关术语
related = await get_related_vocabulary(
    word="代数",
    grade_level="6-8"
)

高中高级 (9-12)

# 获取物理推荐
books = await get_book_recommendations(
    grade_level="9-12",
    subject="物理"
)

# 获取详细文章
article = await get_article_content(
    title="量子力学"
)

# 查找可访问的研究
papers = await search_academic_papers(
    query="气候变化",
    academic_level="高中"
)

大学研究

# 查找学术教科书
books = await search_educational_books(
    query="微积分",
    grade_level="大学"
)

# 获取最新研究
research = await get_recent_research(
    subject="计算机科学",
    academic_level="研究生"
)

# 分析趋势
trends = await analyze_research_trends(
    subject="机器学习"
)

⚙️ 配置

配置文件

服务器使用位于 config/ 目录下的 YAML 配置文件：

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

education:
  grade_levels:
    - "K-2"
    - "3-5"
    - "6-8"
    - "9-12"
    - "大学"
  
  subjects: