MCP USDA Server

A modular MCP (Model Control Protocol) server template for fetching and formatting agricultural data from the USDA Foreign Agricultural Service (FAS) Production, Supply and Distribution (PSD) database.

🌾 Overview

This project serves as a template for creating Model Control Protocol (MCP) servers that expose agricultural data tools to Large Language Models (LLMs). It demonstrates how to fetch data from the USDA FAS API, process it, and present it in a format that's optimized for LLM consumption.

The server implements a modular architecture that makes it easy to:
- Add new data sources and tools
- Format complex data for LLM consumption
- Create anti-hallucination guardrails
- Connect to an MCP client that aggregates tools from multiple servers

📐 Architecture

This project implements a client-server architecture using the MCP (Model Control Protocol) approach:

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

Core Components:

1. MCP Client:
- Aggregates tools from multiple MCP servers
- Provides a unified interface for the LLM to access all tools
- Routes tool calls to the appropriate server based on the tool name

2. MCP USDA Server:
- Implements specialized tools for USDA agricultural data
- Handles the API calls, data processing, and formatting
- Returns data in a format optimized for LLM consumption

3. Communication Protocol:
- Uses JSON-RPC 2.0 for standardized client-server communication
- Supports tool listing, tool metadata, and tool execution requests

🧰 Available Tools

This server implements five USDA data tools:

1. usda-psd-regions: Get region data from the USDA FAS PSD database
2. usda-psd-countries: Get country data with region associations
3. usda-psd-commodities: Get agricultural commodity definitions
4. usda-psd-units-of-measure: Get units of measure for agricultural quantities
5. usda-psd-commodity-attributes: Get commodity attributes (production, supply, distribution)

Each tool is designed to fetch data from the USDA API, filter it based on user queries, and format it into markdown that's optimized for LLM consumption.

📁 Project Structure

The project follows a modular architecture:

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

Key Files:

- src/server.js: Main entry point that starts the HTTP server and initializes the request processor
- src/tools/registry.js: Central registry of all available tools with metadata
- src/routers/toolRouter.js: Routes tool-related requests to the appropriate handler
- src/tools/psd.js: Implementation of USDA PSD data fetching for different endpoints
- src/formatters/psdFormatter.js: Formats API results into markdown for LLM consumption
- src/handlers/psd*Handler.js: Handles incoming requests for each tool

🔄 JSON-RPC Communication

The server communicates with the MCP client using JSON-RPC 2.0:

Examples:

1. Tool Listing Request:

{

  "jsonrpc": "2.0",

  "id": 1,

  "method": "tools/list",

  "params": {}

}

2. Tool Execution Request:

{

  "jsonrpc": "2.0",

  "id": 2,

  "method": "tools/execute",

  "params": {

    "name": "usda-psd-regions",

    "args": {

      "query": "asia"

    }

  }

}

⚙️ LLM Integration

This server is designed to be LLM-agnostic, meaning it can work with any LLM that supports either:

- Function/Tool Calling: For LLMs that have native function calling capabilities (e.g., OpenAI's GPT-4, Anthropic's Claude 3, Google's Gemini)
- Instruction Following: For LLMs that can follow structured instructions about available tools

The system works best with LLMs that have:
1. Function/tool calling capabilities
2. Ability to parse and generate structured data
3. Contextual understanding of agricultural data

🚀 Getting Started

Prerequisites:

Installation:

1. Clone this repository:

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

cd MCP_USDA_Server

2. Install dependencies:

npm install

3. Start the server:

npm start

The server will start on port 3100 by default (configurable in .env).

Connecting with MCP Client:

The server is designed to work with an MCP client that aggregates tools from multiple servers. See the companion MCP_WebAgent_Client repository for implementation details.

🔧 Extending the Server

Adding a New Tool:

1. Create a new tool implementation in src/tools/
2. Create a formatter in src/formatters/
3. Create a handler in src/handlers/
4. Register the tool in src/tools/registry.js
5. Update the router in src/routers/toolRouter.js

See the existing tools for implementation examples.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgements

- USDA Foreign Agricultural Service for providing the PSD API
- The open-source community for inspiration and examples of modular architecture

---

Created as a template for building MCP servers that expose domain-specific data to LLMs.