toyMCP To-Do List Server

toyMCP To-Do List サーバー

これは、特に HTTP 上の JSON-RPC 2.0 を使用し、Model Context Protocol（MCP）の概念に基づいて To-Do リストの CRUD API を実装する、シンプルなサンプルサーバーです。

永続化には、Node.js、Express、PostgreSQL（Docker 経由）を使用します。

コンポーネント

このプロジェクトは、主に次の 2 つのコンポーネントで構成されています。

1. MCP サーバー：To-Do アイテムを管理する JSON-RPC ベースの API サーバー
2. エージェントフレームワーク：AI モデルを使用して MCP サーバーを自然言語で操作するインターフェース

セットアップ

1. 前提条件：

   • Node.js（LTS バージョンを推奨）
   • npm（通常は Node.js に付属しています）
   • Docker と Docker Compose

2. リポジトリをクローンします（該当する場合）：

   # git clone ...
   # cd toyMCP
   

3. 依存関係をインストールします：

   npm install
   

4. PostgreSQL データベースを起動します： Docker Desktop（または Docker デーモン）が実行中であることを確認してください。

   docker compose up -d db
   

   これにより、toymcp_db という名前の PostgreSQL コンテナがバックグラウンドで起動し、データ用の永続ボリュームが作成されます。

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

   npm start
   

   サーバーは必要に応じてデータベーススキーマを初期化し、http://localhost:3000（または PORT 環境変数で指定したポート）でリクエストの待ち受けを開始します。 JSON-RPC エンドポイントは http://localhost:3000/rpc です。 Swagger API ドキュメント UI は http://localhost:3000/api-docs で利用できます。

サーバーをクリーンな状態で起動する

サーバーを完全に新しいデータベースで起動したい場合（たとえば、手動のエンドツーエンドテストを実行する前や、状態をリセットする場合）は、clean_start.sh スクリプトを使用できます。

1. 実行中のサーバーを停止します（実行中の場合）。サーバーを起動したターミナルで Ctrl+C を押してください。
2. スクリプトに実行権限があることを確認します：

   chmod +x clean_start.sh
   

3. スクリプトを実行します：

   ./clean_start.sh
   

   このスクリプトは、データベースコンテナを停止して削除し（docker compose down）、再起動して（docker compose up -d db）、Node.js サーバーを起動します（npm start）。

テストの実行

PostgreSQL コンテナが実行中であることを確認してください（docker compose up -d db）。

テストは tests/unit_tests と tests/integration_tests に分かれています。次のコマンドを実行すると、すべてのテストが実行されます。

npm test

カバレッジレポートの生成

npm run coverage

このコマンドを実行すると、ターミナルに概要が出力され、ユニットテストと統合テストの両方のカバレッジを反映した詳細な HTML レポートが coverage/lcov-report/ ディレクトリに生成されます。

エンドツーエンドテストスクリプトの実行

このプロジェクトには、稼働中のサーバーに対して curl を使用し、データベースの事前クリーンアップや概要レポートの出力を含む一連のテストを実行するオーケストレータースクリプト（run_full_test.sh）が含まれています。手動でエンドツーエンドチェックを行う場合は、この方法を推奨します。

前提条件： curl、jq

chmod +x run_full_test.sh test_server.sh # Ensure scripts are executable
./run_full_test.sh

API ドキュメント

インタラクティブな API ドキュメントは、ローカル（サーバー実行中）と GitHub Pages で公開されているページの両方から、Swagger UI を通じて利用できます。

• ローカルの Swagger UI： http://localhost:3000/api-docs
• GitHub Pages の Swagger UI： https://izaqyos.github.io/toyMCP/swagger-ui/

ドキュメントは、swagger-jsdoc を使用して src/swagger_definitions.js の JSDoc コメントから自動生成されます。

API の使用方法

認証

ほとんどの API エンドポイントでは、JSON Web Token（JWT）による認証が必要です。

1. ログイン： まず、ユーザー名とパスワードを JSON ボディに含めて、/auth/login に POST リクエストを送信します。

   curl -X POST -H "Content-Type: application/json" \
        -d '{"username": "testuser", "password": "password123"}' \
        http://localhost:3000/auth/login
   

   成功時のレスポンス：

   {
       "message": "Login successful",
       "user": { "id": 1, "username": "testuser" },
       "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
   }
   

2. トークンの使用： 受け取った token の値をコピーします。保護されたエンドポイント（/rpc など）への以降のリクエストでは、Authorization ヘッダーにベアラートークンとして含めます。

   TOKEN="YOUR_JWT_TOKEN_HERE" # Replace with the actual token
   curl -X POST -H "Content-Type: application/json" \
        -H "Authorization: Bearer $TOKEN" \
        -d '{"jsonrpc": "2.0", "method": "mcp.discover", "id": 1}' \
        http://localhost:3000/rpc
   

JSON-RPC エンドポイント（/rpc）

Content-Type: application/json と Authorization: Bearer <token> ヘッダーを指定し、JSON-RPC 2.0 ペイロードを本文に含めて、http://localhost:3000/rpc に POST リクエストを送信します。

利用可能なメソッド：

• todo.list：すべての To-Do アイテムを一覧表示します。
• todo.add：新しい To-Do アイテムを追加します（params: { "text": "..." }）。
• todo.remove：To-Do アイテムを削除します（params: { "id": ... }）。
• mcp.discover：サービスと利用可能なメソッドについて説明します。

ツールの例： curl（/auth/login で取得した有効な $TOKEN があることを前提とします）

• サービスを検出する（mcp.discover）

  curl -X POST -H "Content-Type: application/json" \
       -H "Authorization: Bearer $TOKEN" \
       -d '{"jsonrpc": "2.0", "method": "mcp.discover", "id": 1}' \
       http://localhost:3000/rpc
  

  成功レスポンス（例）：

  {
      "jsonrpc": "2.0",
      "result": {
          "mcp_version": "1.0.0",
          "name": "ToyMCP Todo Service",
          "description": "A simple To-Do list manager implementing MCP concepts.",
          "methods": [
              {"name": "todo.list", ...},
              {"name": "todo.add", ...},
              {"name": "todo.remove", ...},
              {"name": "mcp.discover", ...}
          ]
      },
      "id": 1
  }
  

• アイテムを追加する（todo.add）

  curl -X POST -H "Content-Type: application/json" \
       -H "Authorization: Bearer $TOKEN" \
       -d '{"jsonrpc": "2.0", "method": "todo.add", "params": {"text": "Buy groceries"}, "id": 1}' \
       http://localhost:3000/rpc
  

  成功レスポンス：

  {
      "jsonrpc": "2.0",
      "result": {
          "id": 1,
          "text": "Buy groceries",
          "created_at": "2025-04-07T16:15:00.123Z"
      },
      "id": 1
  }
  

• アイテムを一覧表示する（todo.list）

  curl -X POST -H "Content-Type: application/json" \
       -H "Authorization: Bearer $TOKEN" \
       -d '{"jsonrpc": "2.0", "method": "todo.list", "id": 2}' \
       http://localhost:3000/rpc
  

  成功レスポンス（例）：

  {
      "jsonrpc": "2.0",
      "result": [
          {
              "id": 1,
              "text": "Buy groceries",
              "created_at": "2025-04-07T16:15:00.123Z"
          }
          // ... other items
      ],
      "id": 2
  }
  

• アイテムを削除する（todo.remove） （ID 1 のアイテムが存在することを前提とします）

  curl -X POST -H "Content-Type: application/json" \
       -H "Authorization: Bearer $TOKEN" \
       -d '{"jsonrpc": "2.0", "method": "todo.remove", "params": {"id": 1}, "id": 3}' \
       http://localhost:3000/rpc
  

  成功レスポンス：

  {
      "jsonrpc": "2.0",
      "result": {
          "id": 1,
          "text": "Buy groceries",
          "created_at": "2025-04-07T16:15:00.123Z"
      },
      "id": 3
  }
  

• エラーレスポンスの例（アイテムが見つからない場合）

  curl -X POST -H "Content-Type: application/json" \
       -H "Authorization: Bearer $TOKEN" \
       -d '{"jsonrpc": "2.0", "method": "todo.remove", "params": {"id": 999}, "id": 4}' \
       http://localhost:3000/rpc
  

  レスポンス：

  {
      "jsonrpc": "2.0",
      "error": {
          "code": 1001,
          "message": "Todo item with ID 999 not found"
      },
      "id": 4
  }
  

エージェントフレームワーク

このリポジトリには、MCP サーバーに自然言語インターフェースを提供する、AI 搭載のエージェントフレームワークが含まれています。エージェントは、ローカルの Ollama モデルまたは OpenAI のクラウドベースのモデルを使用してユーザーの指示を解釈し、To-Do リストに対して適切な操作を実行します。

アーキテクチャ

┌───────────────┐    ┌────────────────┐    ┌───────────────┐
│ LLM Provider  │◄───┤ Agent Framework├───►│  toyMCP API   │
│ (Ollama/Cloud)│    │                │    │  (Todo Server)│
└───────────────┘    └────────────────┘    └───────────────┘

セットアップと使用方法

エージェントフレームワークは agent-framework/ ディレクトリにあります。使用するには、次の手順に従ってください。

1. 環境をセットアップします。

   cd agent-framework
   npm install
   cp .env-example .env    # Configure settings as needed
   npm run build
   

2. 自然言語を使って ToDo リストを管理します。

   # Add a task
   node index.js "Add milk to my shopping list"
   
   # List all tasks
   node index.js "What's on my todo list?"
   
   # Remove a task
   node index.js "Remove the shopping task"
   
   # Debug mode
   node index.js --debug "Add a reminder to call mom"
   

エージェントフレームワークの詳細なドキュメントについては、以下を参照してください。

• agent-framework/README.md：セットアップと使用方法
• agent-framework/ARCHITECTURE.md：技術設計とインタラクションの流れ
• agent-framework/CHANGELOG.md：開発履歴と変更内容