OpenEdu MCP

面向从 K-12 到大学水平的教育资料检索 MCP 服务器。结合 Open Library、Wikipedia、Dictionary API、arXiv 4 个公开 API，以 22 个工具提供图书推荐、维基文档摘要、词汇分析、学术论文检索等功能。

本仓库是 Cicatriiz/openedu-mcp 为 Goover MCP Hub 部署而分叉·修改的版本。原版仅支持 stdio transport，本仓库新增了 streamable HTTP transport 支持，并修复了导致服务完全无法启动的致命 bug。

基本信息

Related MCP server: MCP Learning Server

介绍

English

OpenEdu MCP provides curated educational resources for K-12 through college-level learning by combining four public APIs: Open Library, Wikipedia, Dictionary API, and arXiv. It offers 22 tools covering educational book search and recommendations by grade level, Wikipedia article search with grade-appropriate summaries and featured articles, dictionary lookups with vocabulary complexity analysis and pronunciation guides, and academic paper search with research trend analysis by subject and academic level. Every tool tags results with grade-level appropriateness (K-2 through College) and curriculum alignment (e.g., Common Core). Responses are cached locally to reduce redundant API calls. No API keys or authentication are required for any of the underlying data sources.

中文

OpenEdu MCP 是结合 Open Library、Wikipedia、Dictionary API、arXiv 等 4 个公开 API，为从 K-12 到大学水平提供教育资料的 MCP。共 22 个工具，支持按年级搜索·推荐教育图书、按年级水平匹配的维基百科文档搜索·摘要·今日推荐文档、包含词汇难度分析与发音指南的词典查询、按主题·学业水平检索学术论文及研究趋势分析。所有结果均附带年级适配度（K-2~College）与课程衔接信息（Common Core 等）标签。响应会存入本地缓存以减少重复调用，无需任何 API 密钥或认证即可使用。

提供的工具（22 个）

不提供 prompt/resource，是纯 tool 型 MCP。

相对原版的变更内容

Bug 修复

1. import 时崩溃 — 导致服务器完全无法启动的致命缺陷

原版 src/main.py 末尾残留了未完成的 SSE 实验代码。

@mcp.tool(route="/events", methods=["GET"])  # Assuming a route decorator might exist or be added to FastMCP
async def stream_events(request: Request) -> StreamingResponse:

@mcp.tool() 不支持 route/methods 参数，会立即抛出 TypeError 导致崩溃，因此即使在 stdio 模式下服务器也无法启动。已删除 sse_event_generator 和 stream_events 函数整体（约 34 行）。

2. mcp 包未列入直接依赖

requirements.txt/pyproject.toml 中仅声明了 fastmcp>=0.1.0，但实际代码导入的是与之不同的 mcp.server.fastmcp。此前只是靠 fastmcp 包的传递依赖偶然运行，一旦 fastmcp 依赖发生变化就可能崩溃，结构非常脆弱。已将 mcp>=1.9.0,<2.0.0 添加为直接依赖。

3. 缺少 HTTP transport 配置

# 변경 전
mcp = FastMCP("openedu-mcp-server")

# 변경 후
mcp = FastMCP(
    "openedu-mcp-server",
    host=os.getenv("OPENEDU_MCP_HOST", "0.0.0.0"),
    port=int(os.getenv("OPENEDU_MCP_PORT", "8000")),
    stateless_http=True,
)

同时补充了缺失的 import os。

参考 — 无需修改代码、通过部署解决的问题

src/config.py 的 load_config() 以进程 cwd 为基准的相对路径查找 config/default.yaml，因此通过将 Dockerfile 的 WORKDIR 对齐到仓库根目录解决（无需修改代码）。

新增 HTTP 桥接

完全不改动现有 main()（stdio 路径），在 src/main.py 中新增了 main_http() 函数。

def main_http():
    """HTTP entry point for the OpenEdu MCP Server (streamable-http transport).

    Added for Goover MCP Hub deployment; the original stdio path via main()
    is untouched.
    """
    try:
        asyncio.run(initialize_services())

        import atexit
        atexit.register(lambda: asyncio.run(cleanup_services()))

        logger.info("Starting OpenEdu MCP Server (HTTP)...")

        mcp.run(transport="streamable-http")

    except KeyboardInterrupt:
        logger.info("Server shutdown requested")
    except Exception as e:
        logger.error(f"Server startup failed:{e}")
        sys.exit(1)
    finally:
        logger.info("OpenEdu MCP Server stopped")

新文件 src/http_entrypoint.py：

"""
HTTP entrypoint for OpenEdu MCP Server (Goover MCP Hub deployment).

Runs the server over streamable-http transport by invoking main_http()
from main.py. The original stdio entrypoint (main.py's main(), run via
`python src/main.py`) is left completely untouched.

Must be run with the repository root as the working directory, since
config.py resolves "config/default.yaml" relative to the process cwd.
"""
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent))

import main

if __name__ == "__main__":
    main.main_http()

pyproject.toml 中新增的条目：

dependencies = [..., "mcp>=1.9.0,<2.0.0", ...]

[project.scripts]
openedu-mcp-server = "src.main:main"
openedu-mcp-server-http = "src.main:main_http"

trailing-slash 测试结果：裸 /mcp 返回 200，/mcp/ 返回 307，确认无需额外 ASGI 包装器即可正常工作。

运行方法

stdio（原版方式，原样保留）

python src/main.py

streamable HTTP（新增，用于 Goover MCP Hub 部署）

python src/http_entrypoint.py

Docker

Dockerfile

FROM python:3.11-slim-bookworm

WORKDIR /app

COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

ENV OPENEDU_MCP_HOST=0.0.0.0
ENV OPENEDU_MCP_PORT=8000
ENV OPENEDU_MCP_CACHE_PATH=/data/cache.db

EXPOSE 8000

CMD ["python", "src/http_entrypoint.py"]

本地构建与冒烟测试

docker build --no-cache --platform linux/amd64 -t openedu-mcp:latest .
docker run -d --name openedu-mcp-test -p 8069:8000 openedu-mcp:latest

已验证项目：

• initialize — 无会话 ID，无状态正常运行

• tools/list — 正常返回 22 个工具

• tools/call（get_word_definition, "photosynthesis"）— 成功实际调用 dictionaryapi.dev，正常返回定义、发音及教育元数据

本分叉特有的要点

• 原版仓库仅针对 stdio 模式验证过，未完成的 HTTP/SSE 代码在 import 时导致整个服务器崩溃，且一直处于无人修复的状态。这并非简单的配置缺失，而是根本无法运行级别的缺陷。

• mcp 包并非直接依赖，而仅作为 fastmcp 包的传递依赖存在，打包结构脆弱。已将其声明为直接依赖，以应对未来的 breaking change。

• config 加载器依赖相对路径，因此未修改代码，而是通过 Dockerfile WORKDIR 绕道解决。

• 缓存服务与用量统计服务共享同一个 SQLite 文件。

• 4 个外部 API（Open Library、Wikipedia、Dictionary API、arXiv）均无需认证/API 密钥，不存在凭据管理问题。

许可证

遵循原始仓库（Cicatriiz/openedu-mcp）的许可证。在再分发或商业使用前，请务必查看原版 LICENSE 文件。