NutriRef 是一个按次付费的 USDA 营养数据 API，专为 AI 智能体设计，采用 x402 微支付协议，使用 Base 主网上的 USDC 结算。其目标是在无需注册、无需 API 密钥、无需人工授权流程的前提下，让智能体能够直接获取结构化的 FoodData Central 营养数据。
主要能力
- 提供四个端点：食物搜索（search）、食物详情（detail）、食物对比（compare）和食谱（recipe）。
- 所有营养数值均以每 100 克为单位；缺失的营养素返回 null，而不是 0。
- compare 返回每种营养素的胜出者（例如蛋白质最高、钠最低等）。
- recipe 按克数缩放并汇总营养数据。
- search 和 detail 会直接缓存 USDA 响应；compare 和 recipe 基于缓存的详情数据组合，缓存预热后无需额外调用 USDA。缓存是重要的成本杠杆：预热请求可在 50 毫秒内返回，且不会访问 USDA。
使用方式
- 通过 MCP 使用：NutriRef 提供 MCP 服务器，将四个端点暴露为原生工具。可从 PyPI 安装，然后在 MCP 客户端配置（如 Claude Desktop 的 claude_desktop_config.json、Claude Code 的 MCP 设置等）中添加。若不想安装，可使用 uvx nutriref-mcp 按需运行；若从克隆仓库工作，可执行 pip install -e ".[mcp]" 并将 command 设为 python，args 设为 ["-m", "mcp_server"]。钱包需要 Base 主网上的 USDC，gas 由 facilitator 代付，因此只需稳定币余额。配置后智能体即拥有 nutrition_search、nutrition_detail、nutrition_compare、nutrition_recipe 四个工具，并按次自动支付。
- 通过任意 HTTP 客户端使用：未付费请求会返回 402 Payment Required 及 x402 支付说明。任何支持 x402 的客户端会签署无 gas 的 USDC 授权（EIP-3009）并自动重试。
- 响应示例：GET /v1/nutrition/detail/173944。
- 自托管：NutriRef 是开源的，nutriref.xyz 上的实例只是众多可能部署之一。主网需要 Coinbase CDP 账户以及公共 x402 facilitator（https://api.cdp.coinbase.com）；测试网可免费使用社区 facilitator（https://x402.org/facilitator）。
适用场景
- 为 Claude 或其他 MCP 智能体添加营养数据查询能力。
- 构建需要按次付费、无需管理 API 密钥的营养数据应用。
- 示例：examples/meal-planner/ 是一个完整的约 150 行智能体，将四个 NutriRef 端点作为工具提供给 Claude，并要求它规划一天满足卡路里/蛋白质目标的膳食。该示例包含工具 schema 和支付循环，适合在将 NutriRef 接入自有智能体时参考，详见 examples/meal-planner/README.md。
限制与说明
- 每次请求费用约为 0.001–0.005 USDC，具体价格以实际为准。
- 需要 Base 主网 USDC 余额；gas 由 facilitator 代付。
- 数据来源为 USDA FoodData Central。
- 实时实例位于 https://nutriref.xyz，规范见 /openapi.json，Swagger 见 /docs，Bazaar 发现见 /.well-known/x402。
- 致谢：USDA FoodData Central 提供数据，x402 提供支付协议，fastapi-x402 提供服务器中间件（启动时应用了一个小的 EIP-712 补丁以支持 Base 主网 USDC）。
