USDA Nutrition MCP Server

Acesse informações nutricionais de mais de 600.000 alimentos do banco de dados USDA FoodData Central.

GitHub
5
Experimente este MCPPatrocinado

Documentação

🥗 Servidor USDA Nutrition MCP Habilitado

Servidor profissional habilitado para Model Context Protocol (MCP) para USDA FoodData Central
Transforma mais de 600 mil alimentos em ferramentas inteligentes de nutrição para Claude Desktop e outros clientes MCP

License: MIT Python 3.11+ MCP Compatible Hosted Service

🌟 O Que Isto Demonstra

Este projeto apresenta habilidades profissionais de implementação MCP:

✅ Arquitetura Dupla - Servidor de protocolo MCP E API HTTP
✅ Ponte de Produção - mcp_bridge.py inteligente com suporte a servidores hospedados/locais/personalizados
✅ Três Opções de Implantação - Serviço hospedado, desenvolvimento local, servidor personalizado
✅ Modelos Type-Safe - Esquemas Pydantic com validação adequada
✅ Docker + Cloud Run - Pipeline completo de implantação

🚀 Início Rápido para Claude Desktop

Opção 1: Instalação Mínima (Recomendado)

Baixe apenas o arquivo de ponte - não é necessário clonar o repositório inteiro:

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

# Install dependencies
pip install mcp httpx

Em seguida, adicione à sua configuração do Claude Desktop:

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

Usuários de Mac com Ambiente Virtual

# 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

Opção 2: Repositório Completo (Para Desenvolvimento)

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

Opção 2: Desenvolvimento Local

{
  "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"
    }
  }
}

Opção 3: Servidor Personalizado

{
  "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"
    }
  }
}

Consulte examples/configs/claude_desktop_config_examples.json para exemplos detalhados de configuração.

🔧 Para Usuários que Não Usam Claude Desktop

API HTTP Direta

API ao Vivo: https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app
Documentação: 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}'

Consulte API_USAGE.md para exemplos completos de integração com Python, JavaScript, LangChain e OpenAI.

🛠 Ferramentas MCP Disponíveis

Uma vez configurado, o Claude Desktop recebe estas ferramentas de nutrição:

  • search_foods - Pesquisar banco de dados USDA por texto
  • get_food_nutrition - Obter nutrição detalhada para alimentos específicos
  • compare_foods - Comparar nutrição entre múltiplos alimentos

Exemplo de Interação com Claude

Você: "Compare o teor de proteína do peito de frango com o salmão"

Claude: Usa ferramentas MCP automaticamente:

  1. search_foods("chicken breast") → Encontra FDC ID 171077
  2. search_foods("salmon") → Encontra FDC ID 175167
  3. compare_foods([171077, 175167]) → Obtém dados de comparação
  4. Fornece análise detalhada com recomendações

🏗 Análise Profunda da Arquitetura

Design de Servidor Duplo

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

Detalhes Chave de Implementação:

  • src/mcp_server.py - Servidor de protocolo FastMCP
  • src/mcp_http_server.py - Servidor HTTP FastAPI
  • src/mcp_bridge.py - Ponte inteligente com detecção automática de servidor
  • src/usda_client.py - Cliente de API com lógica de repetição
  • src/models/ - Esquemas Pydantic type-safe

Lógica da Ponte Inteligente

A ponte detecta automaticamente o tipo de servidor e fornece feedback apropriado ao usuário:

# 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)")

📦 Instalação e Desenvolvimento

# 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/

🐳 Opções de Implantação

Desenvolvimento Local

# Run HTTP server locally
python -m src.mcp_http_server

# Run with Docker
make up

Implantação em Produção

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

A implantação em produção inclui:

  • SSL/HTTPS automático
  • Verificações de saúde e monitoramento
  • Escalonamento automático baseado na demanda
  • Registro estruturado

🔑 Configuração

Variáveis de Ambiente

  • FDC_API_KEY - Chave de API USDA FoodData Central (necessária para local)
  • ENVIRONMENT - "development" ou "production"
  • LOG_LEVEL - Nível de registro (DEBUG, INFO, etc.)

Limites de Taxa

  • Serviço Hospedado: 1.000 solicitações/hora (compartilhado)
  • Implantação Local: 1.000 solicitações/hora (sua chave)
  • Empresarial: Contate para limites maiores

🧪 Estratégia de Testes

# 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

A suíte de testes inclui:

  • Simulação da API USDA com httpx-mock
  • Testes assíncronos do servidor MCP
  • Exemplos de testes de integração
  • Benchmarking de desempenho

🤝 Contribuindo

  1. Faça um fork do repositório
  2. Crie uma branch de funcionalidade: git checkout -b feature/amazing-feature
  3. Execute os testes: python -m pytest tests/
  4. Execute o linting: ruff check src/
  5. Envie um pull request

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🎯 Pronto para usar? Consulte examples/configs/claude_desktop_config_examples.json para instruções de configuração!

🔗 API ao Vivo: https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app/docs