Openedu MCP

🚀 OpenEdu MCP Server

OpenEdu MCP Serverは、教育者に教育リソースを提供し、カリキュラムの計画をサポートするために設計された包括的なモデルコンテキストプロトコル（MCP）サーバーです。このサーバーは複数の教育APIと統合されており、書籍、記事、定義、研究論文などにアクセスでき、教育的なフィルタリングと学年レベルの適切性を考慮した検索が可能です。

✨ 主な機能

完全なAPI統合セット

• 📚 Open Library統合：教育用書籍の検索、推薦、メタデータ提供
• 🌐 Wikipedia統合：学年レベルでフィルタリングされた教育記事の分析
• 📖 辞書統合：語彙分析と言語学習のサポート
• 🔬 arXiv統合：教育的な関連性をスコアリングした学術論文の検索

教育的インテリジェンス

• 学年レベルフィルタリング：幼稚園～2年生、3～5年生、6～8年生、9～12年生、大学レベルのコンテンツ
• 科目分類：数学、科学、英語、社会、芸術、体育、技術
• カリキュラムアライメント：共通コア、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
# 必要に応じて.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

🛠️ MCPツールリファレンス

教育用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
)

📖 辞書ツール（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サーバーとやり取りする方法を詳述します。

Stdioツール (handle_stdio_input)

サーバーには、直接的なコマンドラインまたはパイプ入力用に設計されたツールが含まれています。

• ツール名：handle_stdio_input
• 説明：1行のテキスト入力を処理し、変換されたバージョンを返します。これは、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": "<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フィールドはerrorオブジェクトに置き換えられ、codeとmessageが含まれます。

Server-Sent Events (SSE)エンドポイント

サーバーは、リアルタイム通知用のSSEエンドポイントを提供します。これは、サーバーが開始したイベントで常に最新の状態を維持する必要があるクライアントに役立ちます。

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

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

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

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

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

• 既知のイベント：

  • connected：クライアントがSSEストリームに正常に接続したときに1回送信されます。
    • 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) {
      // 特定のイベントタイプが一致しない場合の汎用メッセージハンドラー
      console.log("Generic message:", event.data);
      try {
          const parsedData = JSON.parse(event.data);
          console.log("Parsed generic data:", parsedData);
      } catch (e) {
          // データが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 {
          // ストリーミング中にエラーが発生しました、データが利用可能な場合があります
          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サーバーをさまざまな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" // このプロジェクトのルートの実際のパスに置き換える
    }
  }
}

詳細については、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" // このプロジェクトのルートの実際のパスに置き換える
    }
  }
}

Cline

ClineのMCPサーバー設定を介してcline_mcp_settings.jsonに以下のJSONを手動で追加します（cwdがこのプロジェクトのルートディレクトリを指していることを確認してください）。

{
  "mcpServers": {
    "openedu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "/path/to/your/openedu-mcp" // このプロジェクトのルートの実際のパスに置き換える
    }
  }
}

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" // このプロジェクトのルートの実際のパスに置き換える
    }
  }
}

Claude

claude_desktop_config.jsonファイルに以下を追加します（cwdがこのプロジェクトのルートディレクトリを指していることを確認してください）。

{
  "mcpServers": {
    "openedu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "/path/to/your/openedu-mcp" // このプロジェクトのルートの実際のパスに置き換える
    }
  }
}

利用可能な場合は、Claude Desktopのドキュメントを参照してください。

📋 教育的な使用例

初等教育（幼稚園～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  # 1分あたりのリクエスト数
  wikipedia:
    rate_limit: 200  # 1分あたりのリクエスト数
  dictionary:
    rate_limit: 450  # 1時間あたりのリクエスト数
  arxiv:
    rate_limit: 3    # 1秒あたりのリクエスト数

環境変数

環境変数を使用して設定を上書きします。

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)
│   ├── レート制限サービス
│   └── 使用状況追跡サービス
├── ツール層
│   ├── Open Libraryツール
│   ├── Wikipediaツール
│   ├── 辞書ツール
│   └── arXivツール
├── API層
│   ├── Open Library API
│   ├── Wikipedia API
│   ├── 辞書API
│   └── arXiv API
└── データ層
    ├── 教育モデル
    ├── キャッシュデータベース
    └── 使用状況分析

📊 パフォーマンス

キャッシュ戦略

• キャッシュヒット率：繰り返しのクエリで70%以上
• レスポンス時間：キャッシュされたリクエストで500ms未満、キャッシュされていないリクエストで2000ms未満
• キャッシュサイズ：自動クリーンアップ付きで構成可能
• TTL管理：コンテンツタイプに基づくインテリジェントな有効期限管理

レート制限

• Open Library：1分あたり100リクエスト
• Wikipedia：1分あたり200リクエスト
• 辞書：1時間あたり450リクエスト
• arXiv：1秒あたり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検証テスト

本番環境での使用準備ができていることを確認するために、包括的な実世界の検証テストを実装しています。これらのテストは、モックではなくライブサービスに対して機能を検証します。

機能

• すべての20以上のMCPツールをそれぞれのライブAPIに対してテストする
• さまざまな学年レベルの教育的なワークフローを検証する
• パフォーマンスメトリクス（レスポンス時間、キャッシュ率、エラー率）を測定する
• 無効な入力とエッジケースでエラーハンドリングをテストする
• 実際のAPIレスポンスでキャッシュ動作を検証する

検証テストの実行

python run_validation_tests.py

このスクリプトは以下のことを行います：

1. すべてのAPI統合（Open Library、Wikipedia、辞書、arXiv）をテストする
2. 教育的なワークフローを検証する：
   • 初等教育（幼稚園～2年生）
   • 高校のSTEM（9～12年生）
   • 大学の研究
   • 教育者用のリソース
3. パフォーマンスメトリクスを測定する：
   • 各APIのレスポンス時間
   • キャッシュのヒット/ミス率
   • レート制限の有効性
   • 教育的なフィルタリングの処理時間
4. テスト結果とパフォーマンス統計を含む詳細なJSONレポートを生成する

テストケース

1. Open Library：
   • 学年レベルでフィルタリングされた「Harry Potter」を検索する
   • ISBNで書籍の詳細を取得する（例：9780439064866）
   • 既知の書籍の可用性を確認する
   • 教育的なメタデータのエンリッチメントを検証する
2. Wikipedia：
   • 学術レベルでフィルタリングされた「Quantum Mechanics」を検索する
   • 「Albert Einstein」の記事要約を取得する
   • 当日の注目記事を取得する
   • コンテンツ分析と複雑度スコアリングを検証する
3. 辞書API：
   • 教育的なコンテキスト付きの「photosynthesis」の定義を取得する
   • 「quinoa」の発音ガイドをテストする
   • STEM用語の語彙分析を検証する
   • 学年に適した定義をテストする
4. arXiv：
   • 教育的なフィルタリングで「machine learning」の論文を検索する
   • 最近のAI研究論文を取得する
   • 学術レベルの評価を検証する
   • 研究トレンド分析をテストする

📚 ドキュメント

• 教育的な機能ガイド：完全な教育機能
• APIリファレンス：詳細なMCPツールのドキュメント
• パフォーマンスベンチマーク：実世界のテスト結果とメトリクス
• デプロイメントガイド：本番環境のデプロイメント手順
• パフォーマンスガイド：最適化とモニタリング

🔧 開発状況

✅ 完了 - すべての機能が実装されました

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

• [x] プロジェクト構造と設定
• [x] コアサービス（キャッシュ、レート制限、使用状況追跡）
• [x] 基本モデルと検証
• [x] FastMCPサーバーのセットアップ
• [x] 教育的なフィルタリングフレームワーク

API統合 ✅

• [x] Open Library API統合（4つのツール）
• [x] Wikipedia 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フレームワークを使用して構築されています。
• Open Library、Wikipedia、辞書API、およびarXivと統合されています。
• 教育的な使用例とカリキュラム計画のために設計されています。
• アクセス可能な教育技術の必要性に触発されています。

---

OpenEdu MCP Server - 教育者にインテリジェントな教育リソースの発見とカリキュラム計画ツールを提供します。