USDA Nutrition Mcp Server

🥗 USDA 营养 MCP 启用型服务

面向 USDA FoodData Central 的专业 Model Context Protocol（MCP）启用型服务
将 60 万多种食物转化为智能营养工具，供 Claude Desktop 和其他 MCP 客户端使用

🌟 本项目展示的内容

本项目展示了专业的 MCP 实现技能：

✅ 双重架构 - 同时提供 MCP 协议服务和 HTTP API
✅ 生产环境桥接器 - 智能 mcp_bridge.py，支持托管、本地和自定义服务
✅ 三种部署选项 - 托管服务、本地开发、自定义服务
✅ 类型安全模型 - 采用 Pydantic 模式并进行适当验证
✅ Docker + Cloud Run - 完整的部署流程

🚀 Claude Desktop 快速入门

选项 1：最简安装（推荐）

只需下载桥接文件，无需克隆整个仓库：

# Download the bridge
wget https://raw.githubusercontent.com/zen-apps/mcp-nutrition-tools/main/src/mcp_bridge.py

# Install dependencies
pip install mcp httpx

然后将以下内容添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "usda-nutrition": {
      "command": "python3",
      "args": ["/path/to/downloaded/mcp_bridge.py"]
    }
  }
}

使用虚拟环境的 Mac 用户

# Navigate to your project
cd /Users/yourusername/your-project-folder

# Create new venv in the project folder
python3 -m venv venv

# Activate it
source venv/bin/activate

# Install dependencies
pip install mcp httpx

# Test it works
python src/mcp_bridge.py --server-url https://usda-nutrition-mcp-356272800218.us-central1.run.app

选项 2：完整仓库（用于开发）

{
  "mcpServers": {
    "usda-nutrition": {
      "command": "python3",
      "args": ["/path/to/mcp-nutrition-tools/src/mcp_bridge.py"],
      "cwd": "/path/to/mcp-nutrition-tools"
    }
  }
}

选项 2：本地开发

{
  "mcpServers": {
    "usda-nutrition": {
      "command": "python3",
      "args": [
        "/path/to/mcp-nutrition-tools/src/mcp_bridge.py",
        "--server-url",
        "http://localhost:8080"
      ],
      "cwd": "/path/to/mcp-nutrition-tools"
    }
  }
}

选项 3：自定义服务

{
  "mcpServers": {
    "usda-nutrition": {
      "command": "python3", 
      "args": [
        "/path/to/mcp-nutrition-tools/src/mcp_bridge.py",
        "--server-url",
        "https://your-server.com"
      ],
      "cwd": "/path/to/mcp-nutrition-tools"
    }
  }
}

详细配置示例请参阅 examples/configs/claude_desktop_config_examples.json。

🔧 适用于非 Claude Desktop 用户

直接使用 HTTP API

在线 API：https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app
文档：https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app/docs

# Search foods
curl -X POST "https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app/tools/search_foods" \
  -H "Content-Type: application/json" \
  -d '{"query": "chicken breast", "page_size": 5}'

# Get nutrition details  
curl -X POST "https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app/tools/get_food_nutrition" \
  -H "Content-Type: application/json" \
  -d '{"fdc_id": 171688}'

Python、JavaScript、LangChain 和 OpenAI 的完整集成示例，请参阅 API_USAGE.md。

🛠 可用的 MCP 工具

完成配置后，Claude Desktop 即可使用以下营养工具：

• search_foods - 按文本搜索 USDA 数据库
• get_food_nutrition - 获取特定食物的详细营养信息
• compare_foods - 比较多种食物的营养成分

Claude 对话示例

你： “比较鸡胸肉和三文鱼的蛋白质含量。”

Claude： 自动使用 MCP 工具：

1. search_foods("chicken breast") → 找到 FDC ID 171077
2. search_foods("salmon") → 找到 FDC ID 175167
3. compare_foods([171077, 175167]) → 获取比较数据
4. 提供详细分析和建议

🏗 深入了解架构

双服务设计

Claude Desktop ←→ mcp_bridge.py ←→ HTTP API ←→ USDA FoodData Central
     (MCP)              ↑              ↑              ↑
                   Smart Bridge    FastAPI       Rate Limited
                                                   Client

主要实现细节：

• src/mcp_server.py - FastMCP 协议服务
• src/mcp_http_server.py - FastAPI HTTP 服务
• src/mcp_bridge.py - 可自动检测服务类型的智能桥接器
• src/usda_client.py - 带重试逻辑的 API 客户端
• src/models/ - 类型安全的 Pydantic 模式

智能桥接逻辑

桥接器会自动检测服务类型并提供相应的用户反馈：

# Hosted service detection
if "usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app" in args.server_url:
    print("🌐 Using hosted service (1,000 requests/hour shared)")

# Local development  
elif "localhost" in args.server_url:
    print("🏠 Using local server (requires your USDA API key)")

📦 安装与开发

# Clone and setup
git clone https://github.com/zen-apps/mcp-nutrition-tools
cd mcp-nutrition-tools
pip install -r requirements.txt

# Get USDA API key (for local development)
# Visit: https://fdc.nal.usda.gov/api-guide.html
echo "FDC_API_KEY=your_key_here" > .env

# Test MCP server
python -m src.mcp_server

# Test HTTP server  
python -m src.mcp_http_server

# Run tests
python -m pytest tests/ -v

# Code quality
ruff check src/
ruff format src/
mypy src/

🐳 部署选项

本地开发

# Run HTTP server locally
python -m src.mcp_http_server

# Run with Docker
make up

生产环境部署

# Deploy to Google Cloud Run
export FDC_API_KEY="your_usda_key"
./scripts/deploy-gcp.sh

生产环境部署包括：

• 自动启用 SSL/HTTPS
• 健康检查和监控
• 根据需求自动扩缩容
• 结构化日志记录

🔑 配置

环境变量

• FDC_API_KEY - USDA FoodData Central API 密钥（本地运行必需）
• ENVIRONMENT - “development” 或 “production”
• LOG_LEVEL - 日志级别（DEBUG、INFO 等）

速率限制

• 托管服务：每小时 1,000 次请求（共享）
• 本地部署：每小时 1,000 次请求（使用你的密钥）
• 企业版：如需更高限额，请联系

🧪 测试策略

# Quick connectivity test
python test_quick.py

# Full test suite with mocking
python -m pytest tests/ -v

# Test specific MCP tools
python examples/live_demo.py

测试套件包括：

• 使用 httpx-mock 模拟 USDA API
• 异步 MCP 服务测试
• 集成测试示例
• 性能基准测试

🤝 参与贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 运行测试：python -m pytest tests/
4. 运行代码检查：ruff check src/
5. 提交拉取请求

📄 许可证

MIT 许可证 — 详情请参阅 LICENSE 文件。

---

🎯 准备好使用了吗？请参阅 examples/configs/claude_desktop_config_examples.json 了解设置说明！

🔗 在线 API：https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app/docs