Openedu MCP

🚀 OpenEdu MCP Server

OpenEdu MCP Server 是一个全面的模型上下文协议（MCP）服务器，旨在为教育工作者提供教育资源并支持课程规划。该服务器与多个教育 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

✨ 主要特性

完整的 API 集成套件

• 📚 开放图书馆集成：提供教育书籍搜索、推荐和元数据查询功能。
• 🌐 维基百科集成：对教育文章进行分析，并支持年级过滤。
• 📖 词典集成：提供词汇分析和语言学习支持。
• 🔬 arXiv 集成：支持学术论文搜索，并具备教育相关性评分功能。

教育智能

• 年级过滤：支持 K - 2、3 - 5、6 - 8、9 - 12 和大学等不同年级的内容过滤。
• 学科分类：涵盖数学、科学、英语语言艺术、社会研究、艺术、体育和技术等学科。
• 课程对齐：支持共同核心标准、下一代科学标准（NGSS）和州标准。
• 教育元数据：提供复杂度评分、阅读水平评估和教育价值评估等功能。

性能与可靠性

• 智能缓存：基于 SQLite 的缓存，支持 TTL（Time-To-Live）机制。
• 速率限制：内置速率限制功能，以遵守 API 配额。
• 使用分析：提供全面的使用跟踪和性能指标。
• 错误处理：具备强大的错误处理能力，同时保留教育上下文信息。

🛠️ MCP 工具参考

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

📚 开放图书馆工具（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 服务器进行交互，包括直接标准输入输出、用于工具执行的 HTTP 接口以及用于实时更新的服务器发送事件（Server-Sent Events）接口。

标准输入输出工具 (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": "<工具名称>",
    "params": {"参数1": "值1", ...},
    "id": "你的请求 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 字段将被 error 对象替换，其中包含 code 和 message。

服务器发送事件（SSE）端点

服务器提供一个 SSE 端点，用于实时通知。这对于需要实时更新服务器发起事件的客户端非常有用。

• 端点：GET /events
• 描述：将事件从服务器流式传输到客户端。
• 事件格式：每个事件作为一段文本块发送：

event: <事件类型>
data: <事件数据的 JSON 有效负载>
id: <可选的事件 ID>

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

• 已知事件：

  • connected：客户端成功连接到 SSE 流时发送一次。
    • data：{"message": "Successfully connected to SSE stream"}
  • ping：定期发送，作为心跳以保持连接活动并指示服务器健康状况。
    • data：{"heartbeat": <循环计数>, "message": "ping"}（循环计数递增）
  • error：如果在 SSE 生成流中发生错误，则发送此事件。
    • data：{"error": "<错误消息>"}

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

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

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

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

通过 Cline 的 MCP 服务器设置手动将以下 JSON 添加到你的 cline_mcp_settings.json 文件中（确保 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 桌面文档，请参阅该文档以获取更多详细信息。

📋 教育用例

小学教育（K - 2）

# 查找适合年龄段的书籍
books = await search_educational_books(
    query="animals", 
    grade_level="K-2", 
    subject="Science"
)

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

# 查找教育文章
articles = await search_educational_articles(
    query="animal homes", 
    grade_level="K-2"
)

中学 STEM 教育（6 - 8）

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

# 分析词汇复杂度
analysis = await get_vocabulary_analysis(
    word="equation", 
    context="solving math problems"
)

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

高中高级课程（9 - 12）

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

# 获取详细文章
article = await get_article_content(
    title="Quantum mechanics"
)

# 查找可访问的研究论文
papers = await search_academic_papers(
    query="climate change", 
    academic_level="High School"
)

大学研究

# 查找学术教科书
books = await search_educational_books(
    query="calculus", 
    grade_level="College"
)

# 获取近期研究
research = await get_recent_research(
    subject="Computer Science", 
    academic_level="Graduate"
)

# 分析研究趋势
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  # 每分钟请求数
  wikipedia:
    rate_limit: 200  # 每分钟请求数
  dictionary:
    rate_limit: 450  # 每小时请求数
  arxiv:
    rate_limit: 3    # 每秒请求数

环境变量

可以使用环境变量覆盖配置：

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

🏗️ 架构

教育 MCP 服务器
├── API 层 (FastMCP)
│   ├── 20 + 个 MCP 工具
│   └── 请求/响应处理
├── 服务层
│   ├── 缓存服务 (SQLite)
│   ├── 速率限制服务
│   └── 使用跟踪服务
├── 工具层
│   ├── 开放图书馆工具
│   ├── 维基百科工具
│   ├── 词典工具
│   └── arXiv 工具
├── API 层
│   ├── 开放图书馆 API
│   ├── 维基百科 API
│   ├── 词典 API
│   └── arXiv API
└── 数据层
    ├── 教育模型
    ├── 缓存数据库
    └── 使用分析

📊 性能

缓存策略

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

速率限制

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

并发处理

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

🧪 测试

运行所有测试

# 单元测试
pytest tests/test_tools/ -v

# 集成测试
pytest tests/test_integration/ -v

# 性能测试
pytest tests/test_performance.py -v

# 真实 API 测试（需要联网）
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. 开放图书馆：
   • 使用年级过滤搜索 "Harry Potter"。
   • 根据 ISBN 获取书籍详细信息（例如，9780439064866）。
   • 检查已知书籍的可用性。
   • 验证教育元数据增强。
2. 维基百科：
   • 使用学术水平过滤搜索 "Quantum Mechanics"。
   • 获取 "Albert Einstein" 的文章摘要。
   • 检索当日特色文章。
   • 验证内容分析和复杂度评分。
3. 词典 API：
   • 获取 "photosynthesis" 的定义并包含教育上下文。
   • 测试 "quinoa" 的发音指南。
   • 验证 STEM 术语的词汇分析。
   • 测试适合特定年级的定义。
4. arXiv：
   • 使用教育过滤搜索 "machine learning" 论文。
   • 获取近期的 AI 研究论文。
   • 验证学术水平评估。
   • 测试研究趋势分析。

📚 文档

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

🔧 开发状态

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

核心基础架构 ✅

• [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 Discussions 进行提问。
• 邮件联系：联系维护者。

🙏 致谢

• 基于 FastMCP 框架构建。
• 与开放图书馆、维基百科、词典 API 和 arXiv 进行集成。
• 专为教育用例和课程规划而设计。
• 受对可访问教育技术的需求启发。

---

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