MCP USDA Server

MCP USDA 服务

一个模块化的 MCP（Model Control Protocol）服务器模板，用于从 USDA Foreign Agricultural Service（FAS）的 Production, Supply and Distribution（PSD）数据库获取并整理农业数据。

🌾 概述

本项目是一个模板，用于创建可向大语言模型（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 实现标准化的客户端-服务端通信
   • 支持工具列表、工具元数据和工具执行请求

🧰 可用工具

此服务实现了五种 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 文件。

🙏 致谢

• 感谢 USDA Foreign Agricultural Service 提供 PSD API
• 感谢开源社区带来的灵感和模块化架构示例

---

此模板用于构建 MCP 服务，以便向大模型提供特定领域的数据。