OpenEdu MCP服务器

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

🎓 特性

完整的API集成套件

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

教育智慧

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

性能和可靠性

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

🚀 快速开始

先决条件

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

安装

克隆存储库：

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

安装依赖项：

pip install -r requirements.txt

设置配置：

cp .env.example .env
# Edit .env with your preferred settings if needed

运行服务器：

python -m src.main

测试安装：

   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": "",
      "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: 
  data: 
  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) {
      // 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，请执行以下操作：

首选 Cursor Settings > MCP.
点击 + Add new Global MCP Server.
或者，将以下配置添加到全局 .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：

引导到 Windsurf - Settings > Advanced Settings 或使用命令面板 Open Windsurf Settings Page.
向下滚动到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

脚本将：

测试所有API集成（开放库、维基百科、词典、arXiv）
验证教育工作流程：

- 基础教育（K-2） - 高中STEM（9-12） - 大学研究 - 教育者资源

衡量绩效指标：

- 每个API的响应时间 - 缓存命中率/未命中率 - 限速有效性 - 教育过滤处理时间

生成包含测试结果和性能统计信息的详细JSON报告

测试用例

开放图书馆:

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

维基百科:

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

词典API:

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

arXiv:

- 使用教育过滤搜索“机器学习”论文 - 获取最近的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参考指南

🤝 贡献

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

开发指南

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

📄 许可证

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

🆘 支持

对于问题、议题或贡献：

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

🙏 致谢

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

______________________________________________________________________

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

OpenEdu MCP Server

快速接入

详细介绍