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 - 為教育工作者提供智能教育資源發現和課程規劃工具。