OpenEdu MCP Server

OpenEdu MCP サーバー

教育者向けに教育リソースを提供し、カリキュラム計画を支援するために設計された、包括的なモデルコンテキストプロトコル（MCP）サーバーです。このサーバーは複数の教育関連 API と連携し、インテリジェントな教育的フィルタリングと学年レベルに応じた適切性の評価を通じて、書籍、記事、定義、研究論文を利用できるようにします。

🎓 特長

API 連携スイートの完全な実装

• 📚 Open Library 連携：教育書の検索、おすすめ、メタデータ
• 🌐 Wikipedia 連携：学年レベルによるフィルタリングを備えた教育記事の分析
• 📖 Dictionary 連携：語彙分析と言語学習のサポート
• 🔬 arXiv 連携：教育的関連性スコアによる学術論文の検索

教育インテリジェンス

• 学年レベルによるフィルタリング：K-2、3-5、6-8、9-12、大学レベルのコンテンツ
• 教科の分類：数学、科学、英語（ELA）、社会科、芸術、体育、テクノロジー
• カリキュラムとの整合：Common Core、NGSS、州基準に対応
• 教育メタデータ：複雑さのスコア、読解レベル、教育的価値の評価

パフォーマンスと信頼性

• インテリジェントなキャッシュ：TTL に対応した SQLite ベースのキャッシュ
• レート制限：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
# Edit .env with your preferred settings if needed

4. サーバーを実行します：

python -m src.main

5. インストールをテストします：

   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 ツールのリファレンス

Education MCP サーバーは、4 つの API 連携にわたって 21 以上の MCP ツールを提供します：

📚 Open Library ツール（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
)

🌐 Wikipedia ツール（5 ツール）

search_educational_articles

教育的なフィルタリングと分析を用いて、Wikipedia の記事を検索します。

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

教育的な分析を含む Wikipedia の注目記事を取得します。

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
)

📖 Dictionary ツール（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()

🔌 接続エンドポイント

このセクションでは、標準入出力による直接的な操作、ツール実行用の HTTP、リアルタイム更新用の Server-Sent Events など、さまざまなインターフェースを通じて OpenEdu MCP Server を利用する方法を説明します。

Stdio ツール（handle_stdio_input）

サーバーには、コマンドラインまたはパイプ経由の入力を直接受け付けるツールが含まれています。

• ツール名：handle_stdio_input
• 説明：1 行のテキスト入力を処理し、変換した結果を返します。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": "<tool_name>",
      "params": {"param1": "value1", ...},
      "id": "your_request_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 フィールドは code と message を含む error オブジェクトに置き換えられます。

Server-Sent Events（SSE）エンドポイント

サーバーは、リアルタイム通知用の SSE エンドポイントを提供します。サーバーから開始されるイベントの最新情報を常に受け取る必要があるクライアントに便利です。

• エンドポイント：GET /events

• 説明：サーバーからクライアントにイベントをストリーミングします。

• イベント形式：各イベントはテキストのブロックとして送信されます：

  event: <event_type>
  data: <json_payload_of_the_event_data>
  id: <optional_event_id>
  
  

  （注：イベントは空行で区切られます。）

• 既知のイベント：

  • connected：クライアントが SSE ストリームへの接続に成功した際に、一度だけ送信されます。
    • data：{"message": "Successfully connected to SSE stream"}
  • ping：接続を維持し、サーバーの状態を示すハートビートとして定期的に送信されます。
    • data：{"heartbeat": <loop_count>, "message": "ping"}（loop_count は増加します）
  • error：SSE 生成ストリーム内でエラーが発生した場合に送信されます。
    • data：{"error": "<error_message>"}

• 例：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 Server は、さまざまな AI 支援コーディングツールや IDE プラグインと連携できます。これにより、これらのツールは開発環境内でサーバーの教育機能を直接利用できます。通常、エディターが OpenEdu MCP サーバーの起動方法と通信方法を認識できるように設定します。このプロジェクトのルートから python -m src.main を実行してサーバーを起動します。

以下に、よく使われるツールの設定例を示します。ローカル環境に応じて、パス（例：cwd の値や、特定の Python 環境を使用している場合のパス）を調整する必要がある場合があります。

Cursor

このサーバーを Cursor IDE に追加するには：

1. Cursor Settings > MCP に移動します。
2. + Add new Global MCP Server をクリックします。
3. または、次の設定をグローバル .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

Windsurf（旧 Cascade）で MCP をセットアップするには：

1. Windsurf - Settings > Advanced Settings に移動するか、コマンドパレットから Open Windsurf Settings Page を実行します。
2. Cascade セクションまでスクロールし、mcp_config.json に OpenEdu 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
    }
  }
}

Cline

Cline の MCP Server 設定から、次の JSON を cline_mcp_settings.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
    }
  }
}

Roo Code

Roo Code の設定で Edit MCP Settings をクリックするか、VS Code のコマンドパレットから Roo Code: Open MCP Config コマンドを実行して、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
    }
  }
}

Claude

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/ ディレクトリ内の 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  # 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 管理：コンテンツの種類に基づくインテリジェントな有効期限管理

レート制限

• Open Library：100リクエスト/分
• Wikipedia：200リクエスト/分
• Dictionary：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 検証テスト

本番環境での準備状況を確かめるため、包括的な実環境検証テストを実装しています。これらのテストでは、モックではなく稼働中のサービスに対する機能を検証します。

特長

• 20以上のすべての MCP ツールを、それぞれに対応する稼働中の API に対してテストします
• 学年別の教育ワークフローを検証します
• パフォーマンス指標（応答時間、キャッシュ率、エラー率）を測定します
• 無効な入力や境界ケースを使ってエラー処理をテストします
• 実際の API 応答を使ってキャッシュの動作を検証します

検証テストの実行

python run_validation_tests.py

スクリプトは次の処理を行います。

1. すべての API 統合（Open Library、Wikipedia、Dictionary、arXiv）をテストします
2. 教育ワークフローを検証します。
   • 小学校教育（K-2）
   • 高校 STEM（9-12）
   • 大学での研究
   • 教育者向けリソース
3. パフォーマンス指標を測定します。
   • 各 API の応答時間
   • キャッシュのヒット率とミス率
   • レート制限の有効性
   • 教育向けフィルタリングの処理時間
4. テスト結果とパフォーマンス統計を含む、詳細な JSON レポートを生成します

テストケース

1. Open Library：

   • 学年レベルで絞り込みながら「Harry Potter」を検索します
   • ISBN（例：9780439064866）で書籍の詳細を取得します
   • 既知の書籍の入手可能状況を確認します
   • 教育メタデータの拡充を検証します

2. Wikipedia：

   • 学術レベルで絞り込みながら「Quantum Mechanics」を検索します
   • 「Albert Einstein」の記事の概要を取得します
   • 本日の注目記事を取得します
   • コンテンツ分析と難易度スコアリングを検証します

3. Dictionary API：

   • 教育的な文脈で「photosynthesis」の定義を取得します
   • 「quinoa」の発音ガイドをテストします
   • STEM 用語の語彙分析を検証します
   • 学年レベルに適した定義をテストします

4. arXiv：

   • 教育的な条件で絞り込みながら「machine learning」に関する論文を検索します
   • 最近の AI 研究論文を取得します
   • 学術レベルの評価を検証します
   • 研究トレンド分析をテストします

📚 ドキュメント

• 教育機能ガイド：教育機能の全容
• API リファレンス：MCP ツールの詳細なドキュメント
• パフォーマンスベンチマーク：実環境でのテスト結果と指標
• デプロイガイド：本番環境へのデプロイ手順
• パフォーマンスガイド：最適化と監視

🔧 開発状況

✅ 完了 — すべての機能を実装済み

コアインフラストラクチャ ✅

• プロジェクト構成と設定
• コアサービス（キャッシュ、レート制限、使用状況の追跡）
• 基本モデルと検証
• FastMCP サーバーのセットアップ
• 教育的な条件による絞り込みのフレームワーク

API 統合 ✅

• Open Library API の統合（4 つのツール）
• Wikipedia API の統合（5 つのツール）
• Dictionary API の統合（5 つのツール）
• arXiv API の統合（5 つのツール）
• 教育コンテンツの絞り込み
• API をまたいだ教育ワークフロー

テストとドキュメント ✅

• 包括的なユニットテスト
• 統合テストスイート
• パフォーマンスベンチマーク
• すべての機能を含むデモスクリプト
• 完全なドキュメント
• 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 のスタイルガイドラインに従います
• すべての関数に型ヒントを追加します
• すべての公開メソッドに docstring を記述します
• 新機能のテストを作成します
• 必要に応じてドキュメントを更新します

📄 ライセンス

このプロジェクトは MIT ライセンスのもとで公開されています。

🆘 サポート

質問、問題、コントリビューションについては、以下をご利用ください。

• 問題：リポジトリで Issue を作成してください
• ドキュメント：docs/ ディレクトリを確認してください
• ディスカッション：質問には GitHub Discussions をご利用ください
• メール：メンテナーにお問い合わせください

🙏 謝辞

• FastMCP フレームワークを使用して構築
• Open Library、Wikipedia、Dictionary API、arXiv と連携
• 教育用途とカリキュラム計画向けに設計
• 誰もが利用できる教育テクノロジーの必要性に着想を得て開発

---

OpenEdu MCP Server — 教育関係者がインテリジェントな教育リソースの検索とカリキュラム計画ツールを利用できるよう支援します。