OpenEdu MCP Server

OpenEdu MCP 服务

一个功能全面的模型上下文协议（MCP）服务，旨在为教育工作者提供教育资源并支持课程规划。此服务集成了多个教育 API，可访问书籍、文章、定义和研究论文，并提供智能教育筛选和年级适宜性判断。

🎓 功能

完整的 API 集成套件

• 📚 Open Library 集成：教育类图书搜索、推荐和元数据
• 🌐 Wikipedia 集成：支持按年级筛选的教育类文章分析
• 📖 Dictionary 集成：词汇分析和语言学习支持
• 🔬 arXiv 集成：提供教育相关性评分的学术论文搜索

教育智能

• 年级筛选：K-2、3-5、6-8、9-12、大学阶段内容
• 学科分类：数学、科学、英语语言艺术（ELA）、社会研究、艺术、体育、技术
• 课程标准对齐：支持 Common Core、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
# Edit .env with your preferred settings if needed

4. 运行服务：

python -m src.main

5. 测试安装：

   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 工具参考

Education MCP 服务通过四种 API 集成提供 21+ 个 MCP 工具：

📚 Open Library 工具（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
)

🌐 Wikipedia 工具（5 个工具）

search_educational_articles

搜索 Wikipedia 文章，并进行教育筛选和分析。

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

获取 Wikipedia 每日特色文章并进行教育分析。

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
)

📖 Dictionary 工具（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 服务交互，包括直接使用标准输入/输出、通过 HTTP 执行工具，以及使用服务器发送事件获取实时更新。

Stdio 工具（handle_stdio_input）

服务端包含一个工具，可用于直接接收命令行输入或管道输入。

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

  工具：handle_stdio_input
  输入："your text here"
  输出："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"
  }
  

• 调用 handle_stdio_input 的 curl 示例：

  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 字段将替换为包含 code 和 message 的 error 对象。

服务器发送事件（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"}（loop_count 会递增）
  • 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 Server 集成到各种 AI 辅助编码工具和 IDE 插件中。这样，这些工具便可在开发环境中直接利用服务器的教育功能。配置通常需要告知编辑器如何启动 OpenEdu MCP 服务并与之通信。可在项目根目录下使用 python -m src.main 运行服务器。

以下是一些常用工具的配置示例。你可能需要根据本地设置调整路径（例如 cwd，或使用特定 Python 环境时的路径）。

Cursor

将此服务器添加到 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

要为 Windsurf（原 Cascade）设置 MCP：

1. 前往 Windsurf - Settings > Advanced Settings，或使用命令面板执行 Open Windsurf Settings Page。
2. 向下滚动到 Cascade 部分，并直接在 mcp_config.json 中添加 OpenEdu 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
    }
  }
}

Cline

通过 Cline 的 MCP Server 设置，将以下 JSON 手动添加到 cline_mcp_settings.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
    }
  }
}

Roo Code

在 Roo Code 设置中点击 Edit MCP Settings，或在 VS Code 的命令面板中使用 Roo Code: Open MCP Config 命令访问 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
    }
  }
}

Claude

将以下内容添加到 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/ 目录中的 YAML 配置文件：

# 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 管理：根据内容类型智能设置过期时间

速率限制

• Open Library：100 次请求/分钟
• Wikipedia：200 次请求/分钟
• Dictionary：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 集成（Open Library、Wikipedia、Dictionary、arXiv）
2. 验证教育工作流：
   • 小学教育（K-2）
   • 高中 STEM（9-12）
   • 大学研究
   • 教育工作者资源
3. 衡量性能指标：
   • 各 API 的响应时间
   • 缓存命中/未命中率
   • 速率限制效果
   • 教育筛选处理时间
4. 生成详细的 JSON 报告，其中包含测试结果和性能统计信息

测试用例

1. Open Library：

   • 搜索“Harry Potter”，并按年级筛选
   • 根据 ISBN 获取图书详情（例如，9780439064866）
   • 查询已知图书的可用情况
   • 验证教育元数据的补充情况

2. Wikipedia：

   • 搜索“Quantum Mechanics”，并按学术级别筛选
   • 获取“Albert Einstein”的文章摘要
   • 获取每日精选文章
   • 验证内容分析和复杂度评分

3. Dictionary API：

   • 获取“photosynthesis”的释义，并提供教育背景信息
   • 测试“quinoa”的发音指南
   • 验证 STEM 术语的词汇分析
   • 测试符合年级水平的释义

4. arXiv：

   • 搜索“machine learning”论文，并进行教育筛选
   • 获取近期 AI 研究论文
   • 验证学术级别评估
   • 测试研究趋势分析

📚 文档

• 教育功能指南：完整的教育功能介绍
• API 参考：MCP 工具的详细文档
• 性能基准测试：真实测试结果和指标
• 部署指南：生产环境部署说明
• 性能指南：优化和监控

🔧 开发状态

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

核心基础设施 ✅

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

API 集成 ✅

• Open Library API 集成（4 个工具）
• Wikipedia API 集成（5 个工具）
• Dictionary API 集成（5 个工具）
• arXiv API 集成（5 个工具）
• 教育内容筛选
• 跨 API 教育工作流

测试和文档 ✅

• 全面的单元测试
• 集成测试套件
• 性能基准测试
• 涵盖所有功能的演示脚本
• 完整文档
• API 参考指南

🤝 贡献

1. Fork 此代码仓库
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. 发起 Pull Request

开发指南

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

📄 许可证

本项目采用 MIT License 许可。

🆘 支持

如有问题、遇到故障或想要贡献：

• 问题：在代码仓库中提交问题
• 文档：查看 docs/ 目录
• 讨论：在 GitHub Discussions 中提问
• 电子邮件：联系维护者

🙏 致谢

• 使用 FastMCP 框架构建
• 集成 Open Library、Wikipedia、Dictionary API 和 arXiv
• 面向教育应用场景和课程规划设计
• 灵感源于对普及教育技术的需求

---

OpenEdu MCP Server —— 为教育工作者提供智能教育资源发现和课程规划工具。