Openedu Mcp

笔记 Python

🚀 OpenEdu MCP Server

OpenEdu MCP Server 是一个全面的模型上下文协议（MCP）服务器，旨在为教育工作者提供教育资源并支持课程规划。该服务器与多个教育 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
# 如有需要，使用你偏好的设置编辑 .env 文件

启动服务器

python -m src.main

测试安装

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：

转到 Cursor 设置 > MCP。
点击 + 添加新的全局 MCP 服务器。
或者，将以下配置添加到你的全局 .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：

导航到 Windsurf - 设置 > 高级设置 或使用命令面板打开 Windsurf 设置页面。
向下滚动到 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

该脚本将：

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

测试用例

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

🤝 贡献

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

开发指南

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

📄 许可证

本项目采用 MIT 许可证。

🆘 支持

如有问题、疑问或想要贡献代码，请参考以下方式：

问题反馈：在仓库中创建问题。
文档查阅：查看 docs/ 目录。
讨论交流：使用 GitHub Discussions 进行提问。
邮件联系：联系维护者。

🙏 致谢

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

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

0 条评论
分类：笔记