MCP USDA Server

MCP USDA サーバー

USDA Foreign Agricultural Service（FAS）の Production, Supply and Distribution（PSD）データベースから農業データを取得し、整形するためのモジュール式 MCP（Model Control Protocol）サーバーテンプレートです。

🌾 概要

このプロジェクトは、大規模言語モデル（LLM）に農業データのツールを提供する Model Control Protocol（MCP）サーバーを作成するためのテンプレートです。USDA FAS API からデータを取得して処理し、LLM が利用しやすい形式で提示する方法を示します。

このサーバーでは、次のことを簡単に行えるモジュール式アーキテクチャを採用しています。

• 新しいデータソースやツールの追加
• LLM が利用しやすい形式への複雑なデータの整形
• ハルシネーション防止のためのガードレールの作成
• 複数のサーバーからツールを集約する MCP クライアントへの接続

📐 アーキテクチャ

このプロジェクトでは、MCP（Model Control Protocol）方式を用いたクライアント・サーバーアーキテクチャを実装しています。

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│             │     │             │     │             │
│    LLM      │◄───►│  MCP Client │◄───►│ MCP Servers │
│             │     │             │     │             │
└─────────────┘     └─────────────┘     └─────────────┘

コアコンポーネント：

1. MCP クライアント：

   • 複数の MCP サーバーからツールを集約します
   • LLM がすべてのツールにアクセスするための統一インターフェースを提供します
   • ツール名に基づいて、ツール呼び出しを適切なサーバーにルーティングします

2. MCP USDA サーバー：

   • USDA の農業データに特化したツールを実装します
   • API 呼び出し、データ処理、整形を行います
   • LLM が利用しやすい形式でデータを返します

3. 通信プロトコル：

   • 標準化されたクライアント・サーバー間通信に JSON-RPC 2.0 を使用します
   • ツール一覧、ツールのメタデータ、ツール実行リクエストに対応しています

🧰 利用可能なツール

このサーバーでは、5 つの USDA データツールを実装しています。

1. usda-psd-regions：USDA FAS PSD データベースから地域データを取得します
2. usda-psd-countries：地域との関連付けを含む国データを取得します
3. usda-psd-commodities：農産物の定義を取得します
4. usda-psd-units-of-measure：農産物の数量に用いる単位を取得します
5. usda-psd-commodity-attributes：農産物の属性（生産、供給、流通）を取得します

各ツールは、USDA API からデータを取得し、ユーザーのクエリに基づいて絞り込み、LLM が利用しやすい Markdown 形式に整形するよう設計されています。

📁 プロジェクト構成

このプロジェクトでは、モジュール式アーキテクチャを採用しています。

MCP_USDA_Server/
├── src/
│   ├── tools/           # Core implementation of each tool
│   ├── handlers/        # Request handlers for each tool
│   ├── formatters/      # Format tool results for LLM consumption
│   ├── routers/         # Route requests to the appropriate handler
│   ├── utils/           # Utility functions
│   └── server.js        # Main server entry point
├── Architecture.md      # Detailed architecture documentation
└── package.json         # Dependencies and scripts

主要ファイル：

• src/server.js：HTTP サーバーを起動し、リクエストプロセッサを初期化するメインエントリーポイント
• src/tools/registry.js：メタデータを含む、利用可能なすべてのツールの中央レジストリ
• src/routers/toolRouter.js：ツール関連のリクエストを適切なハンドラーにルーティングします
• src/tools/psd.js*：各エンドポイントの USDA PSD データ取得を実装します
• src/formatters/psd*Formatter.js：API の結果を LLM が利用しやすい Markdown 形式に整形します
• src/handlers/psd*Handler.js：各ツールへの受信リクエストを処理します

🔄 JSON-RPC 通信

このサーバーは、JSON-RPC 2.0 を使用して MCP クライアントと通信します。

例：

1. ツール一覧リクエスト：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

2. ツール実行リクエスト：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/execute",
  "params": {
    "name": "usda-psd-regions",
    "args": {
      "query": "asia"
    }
  }
}

⚙️ LLM との統合

このサーバーは LLM に依存しない設計です。つまり、次のいずれかに対応するあらゆる LLM で動作します。

• 関数／ツール呼び出し：ネイティブの関数呼び出し機能を備えた LLM（例：OpenAI の GPT-4、Anthropic の Claude 3、Google の Gemini）
• 指示への対応：利用可能なツールについての構造化された指示に従える LLM

次の機能を備えた LLM で最適に動作します。

1. 関数／ツール呼び出し機能
2. 構造化データを解析および生成する能力
3. 農業データに関する文脈理解

🚀 はじめに

前提条件：

• Node.js（v14+）
• npm または yarn

インストール：

1. このリポジトリをクローンします。

git clone https://github.com/yourusername/MCP_USDA_Server.git
cd MCP_USDA_Server

2. 依存関係をインストールします。

npm install

3. サーバーを起動します。

npm start

デフォルトでは、サーバーはポート 3100 で起動します（.env で設定できます）。

MCP クライアントとの接続：

このサーバーは、複数のサーバーからツールを集約する MCP クライアントと連携するよう設計されています。実装の詳細については、関連リポジトリの MCP_WebAgent_Client を参照してください。

🔧 サーバーの拡張

新しいツールの追加：

1. src/tools/ に新しいツールの実装を作成します
2. src/formatters/ にフォーマッターを作成します
3. src/handlers/ にハンドラーを作成します
4. src/tools/registry.js にツールを登録します
5. src/routers/toolRouter.js のルーターを更新します

実装例については、既存のツールを参照してください。

📝 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については LICENSE ファイルを参照してください。

🙏 謝辞

• PSD API を提供してくださった USDA Foreign Agricultural Service
• モジュール型アーキテクチャの発想や例を提供してくださったオープンソースコミュニティ

---

LLM にドメイン固有のデータを公開する MCP サーバーを構築するためのテンプレートとして作成されました。