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のサポートを追加し、起動自体が不可能だった致命的バグを修正しました。

基本情報

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 키나 인증 없이 사용 가능합니다.

日本語

OpenEdu MCPは、Open Library、Wikipedia、Dictionary API、arXivの4つの公開APIを組み合わせ、K-12から大学レベルまでの教育資料を提供するMCPです。全22ツールで、学年別の教育書籍検索・推薦、学年レベルに合わせたウィキペディア文書の検索・要約・今日の注目記事、語彙難易度分析と発音ガイドを含む辞書検索、テーマ・学術レベル別の学術論文検索と研究動向分析をサポートします。すべての結果に学年適合度(K-2~College)とカリキュラム連携情報(Common Coreなど)がタグとして付与されます。応答はローカルキャッシュに保存され重複呼び出しを削減し、別途のAPIキーや認証なしで利用可能です。

提供ツール (22個)

プロンプト/リソースは提供しない純粋なtoolベースのMCPです。

オリジナルからの変更点

バグ修正

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()がconfig/default.yamlをプロセスcwd基準の相対パスで探索する構造のため、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テスト結果: bare /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なし、stateless正常動作

• 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ファイルを必ず確認してください。