convez.ai
PluginIntegração & APIsIntermediário
Younghef

NutriRef API

Younghef/nutriref-api

Dados nutricionais USDA sob demanda via micropagamentos em blockchain

Ver no GitHub
InicialPluginScore · de 0 a 100

API de dados nutricionais USDA com micropagamentos em USDC via protocolo x402. Agentes de IA consultam informações de nutrição de alimentos sem autenticação prévia, pagando $0.001–$0.005 por requisição. Inclui server MCP nativo para integração com Claude.

Instalação

$npx convez-ai Younghef/nutriref-api

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.2.3
Issues abertas
0
Contribuidores
1

Casos de uso

  • Assistentes de IA consultarem informações nutricionais de alimentos em tempo real
  • Comparar perfis nutricionais entre alimentos diferentes
  • Calcular macronutrientes de receitas escaladas por porção
  • Integrar dados nutricionais em aplicações de health tech sem autenticação prévia

Veredito

Solução inovadora que alia dados USDA confiáveis com economia de micropagamentos em blockchain. Ideal para agentes autônomos, mas requer wallet financiada em USDC—curva de entrada técnica não-trivial para quem desconhece Web3.

README

A tradução para o português deste README ainda está na fila.

NutriRef

NutriRef MCP server

Pay-per-call USDA nutrition data for AI agents. Structured FoodData Central via the x402 micropayment protocol — agents pay $0.001–$0.005 in USDC per request, no signup, no API keys, no human auth flows.

Live at https://nutriref.xyz. Spec at /openapi.json · Swagger at /docs · Bazaar discovery at /.well-known/x402.

Endpoints

MethodPathPriceCache
GET/v1/nutrition/search?q=&limit=$0.00124h
GET/v1/nutrition/detail/{fdc_id}$0.0027d
POST/v1/nutrition/compare$0.003derived
POST/v1/nutrition/recipe$0.005derived

All values per 100g. Missing nutrients are null, not 0. compare returns per-nutrient winners (highest protein, lowest sodium, etc.). recipe scales by grams and sums.

Use it from Claude (or any MCP agent)

NutriRef ships an MCP server that exposes the four endpoints as native tools. Install it from PyPI:

pip install nutriref-mcp

Then add this to your MCP client config (Claude Desktop's claude_desktop_config.json, Claude Code's MCP settings, etc.):

{
  "mcpServers": {
    "nutriref": {
      "command": "nutriref-mcp",
      "env": {
        "PAYER_PRIVATE_KEY": "0x...your-funded-wallet-key...",
        "NUTRIREF_BASE_URL": "https://nutriref.xyz"
      }
    }
  }
}

Prefer not to install? Use uvx nutriref-mcp as the command to run it on demand. To work from a clone instead, pip install -e ".[mcp]" and set command to python with args: ["-m", "mcp_server"].

The wallet needs USDC on Base mainnet — gas is sponsored by the facilitator, so you only need stablecoin balance. The agent now has nutrition_search, nutrition_detail, nutrition_compare, nutrition_recipe and auto-pays per call.

Use it from any HTTP client

Unpaid requests get 402 Payment Required with x402 payment instructions. Any x402-aware client signs a gasless USDC authorization (EIP-3009) and retries automatically:

import asyncio
from eth_account import Account
from x402.client import x402Client
from x402.http.clients.httpx import wrapHttpxWithPayment
from x402.mechanisms.evm.exact import register_exact_evm_client

account = Account.from_key("0x...funded-wallet-key...")
client = x402Client(); register_exact_evm_client(client, account)

async def main():
    async with wrapHttpxWithPayment(client, base_url="https://nutriref.xyz") as http:
        r = await http.get("/v1/nutrition/detail/2012128")
        print(r.json())

asyncio.run(main())

Response example

GET /v1/nutrition/detail/173944:

{
  "fdc_id": 173944,
  "description": "Banana, raw",
  "data_type": "Foundation",
  "serving_size": 100, "serving_size_unit": "g",
  "calories": 89.0,  "protein": 1.1,    "fat": 0.3,
  "carbs": 22.8,     "fiber": 2.6,      "sugar": 12.2,
  "sodium": 1.0,     "cholesterol": null, "saturated_fat": 0.1,
  "vitamin_c": 8.7,  "calcium": 5.0,    "iron": 0.3,  "potassium": 358.0
}

Self-hosting

NutriRef is open source; the live instance at nutriref.xyz is one deployment among many possible. To run your own:

cp .env.example .env
# fill in USDA_API_KEY (free at https://fdc.nal.usda.gov/api-key-signup.html)
# and X402_RECEIVER_ADDRESS (an EVM address that should receive payments)
docker compose up --build
curl http://localhost:8000/health

Configuration

VarRequiredDefaultPurpose
USDA_API_KEYyes—Free key from fdc.nal.usda.gov
USDA_BASE_URLnohttps://api.nal.usda.gov/fdc/v1
REDIS_URLnoredis://redis:6379/0Response cache
X402_NETWORKnobase-sepoliabase for mainnet
X402_RECEIVER_ADDRESSyes—EVM address that receives USDC
X402_FACILITATOR_URLnohttps://x402.org/facilitatorhttps://api.cdp.coinbase.com for mainnet
CDP_API_KEY_IDmainnet only—Coinbase Developer Platform key ID
CDP_API_KEY_SECRETmainnet only—Coinbase Developer Platform key secret
LOG_LEVELnoINFO

For mainnet you need a Coinbase CDP account and the public x402 facilitator at https://api.cdp.coinbase.com. Testnet works for free with the community facilitator at https://x402.org/facilitator.

Architecture

agent → x402 middleware → route handler → cache (Redis) → USDA FDC API

search and detail cache USDA responses directly. compare and recipe compose from the cached detail data — no extra USDA calls when warm. The cache is a meaningful cost lever: warm requests return in <50ms and never hit USDA.

Tests

pip install -e ".[dev]"
pytest

Example: Claude agent that uses NutriRef

examples/meal-planner/ is a complete, ~150-line agent that gives Claude the four NutriRef endpoints as tools and asks it to plan a day of meals hitting a calorie/protein goal. Worth reading if you're wiring NutriRef into your own agent — the tool schemas and the payment loop are all there. See examples/meal-planner/README.md.

Repo layout

app/                # FastAPI service
  main.py             # app factory + x402 init
  routes/             # search, detail, compare, recipe
  landing.py          # / (public landing page)
  discovery.py        # /.well-known/x402, /llms.txt, /.well-known/ai-plugin.json, /logo.svg
  usda.py             # async USDA client
  cache.py            # Redis wrapper
  normalize.py        # USDA → flat 13-nutrient schema
mcp_server/         # MCP server wrapper for agent use
examples/           # worked agent examples (meal planner)
scripts/            # CDP wallet bootstrap + payer-side test
tests/              # pytest + respx + fakeredis

Acknowledgments

Ver o original no GitHub

Bom para

Relacionados