食品营养数据管理服务器

SparkyFitness MCP服务器

一个无状态的基于Go-的MCP（模型上下文协议）服务器，充当人工智能代理（如Claude Chat）和SparkyFitness后端之间的API桥梁。该服务器提供创建和搜索具有完整营养数据的食品的工具。

特性

• 智能搜索：在数据库中查找现有食物以避免重复
• 食物创造：创建包含完整营养数据的新食品条目
• 变体管理：为同一食物添加多种份量（例如100克、150克、1杯）
• 双重运输支持:
  • 标准：用于本地Claude Desktop集成
  • HTTP/SSE：用于远程部署和claude.ai web集成
• 无状态设计：纯API转换层，无本地存储

与AI代理无缝协作： 当与Claude Chat或其他具有视觉能力的人工智能代理一起使用时，用户可以上传营养标签照片，并在调用MCP工具之前让人工智能自动提取数据。

快速开始

使用克劳德桌面（本地）

1. 下载或构建二进制文件 （参见 发布)

2. 添加到Claude桌面配置:

   在macOS上： ~/Library/Application Support/Claude/claude_desktop_config.json

   复制

   {
     "mcpServers": {
       "sparkyfitness": {
         "command": "/path/to/sparkyfitness-mcp",
         "env": {
           "SPARKYFITNESS_API_URL": "http://localhost:8000",
           "SPARKYFITNESS_API_KEY": "your-api-key"
         }
       }
     }
   }
   

   注： 替换 http://localhost:8000 使用SparkyFitness服务器组件（后端）的实际URL。

3. 重新启动克劳德桌面

4. 开始使用它：上传一张营养标签照片，让克劳德将其添加到SparkyFitness！

使用Docker

docker run -p 8080:8080 \
  -e SPARKYFITNESS_API_URL=http://localhost:8000 \
  -e SPARKYFITNESS_API_KEY=your-api-key \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_PORT=8080 \
  sparkyfitness-mcp

注： 替换 http://localhost:8000 使用SparkyFitness服务器组件（后端）的实际URL。

然后使用MCP端点从claude.ai网络连接： http://localhost:8080/mcp/

配置

所需的环境变量

可选环境变量

可用工具

此MCP服务器提供了Claude可以使用的三个工具：

🔍 search_foods

在SparkyFitness营养数据库中搜索现有的食物。 总是先打电话 在制作任何食物之前，要防止重复。

它的作用：

• 按食品名称搜索，并可选择按品牌过滤
• 返回匹配的食物及其默认变体的完整营养数据
• 提供 food_id 在现有食品中添加变体所需的值

搜索模式：

• broad_match=true （默认）：查找相似食物的模糊不区分大小写的搜索
• broad_match=false：精确匹配，获得精确结果

例子：

User: "Find nutrition info for chicken breast"
Claude: [Calls search_foods]
Result: List of matching foods with nutrition facts

🆕 create_food_variant

创建 全新的 第一份不同份量的食物入口。仅在没有匹配的食物或用户明确希望单独输入时使用。

何时使用：

• search_foods 未找到匹配项（不存在重复项），或
• 尽管有重复项，用户仍明确选择创建单独的食物条目

它的作用：

• 在数据库中创建新的食品实体
• 添加第一个服务尺寸变量作为默认值
• 返回两者 food_id 和 variant_id

重要提示： 不用于在现有食品中添加变体-使用 add_food_variant 为了这个。

例子：

User: [Uploads photo of nutrition label for "Organic Quinoa"]
Claude: [Searches first, finds no matches]
Claude: [Creates new food entry with nutrition data]
Result: New food created successfully

➕ add_food_variant

添加新的份量变体 现有的 食物。使用此功能为通过以下方式找到的食物添加替代份量 search_foods.

何时使用：

• search_foods 找到了匹配的食物，而且
• 用户希望为现有食物添加新的份量（而不是创建单独的条目）

它的作用：

• 在现有食品条目中添加另一个份量选项
• 需要 food_id 从搜索结果
• 示例：食物有100克变体，在同一食物中添加150克变体

例子：

User: "I have nutrition data for Enoki Mushroom 150g serving"
Claude: [Searches and finds existing Enoki Mushroom with 100g variant]
Claude: "Found existing Enoki Mushroom with 100g variant. Add 150g variant?"
User: "Yes"
Claude: [Calls add_food_variant with food_id and nutrition data]
Result: Enoki Mushroom now has TWO variants (100g and 150g)

用法示例

添加新食物（与Claude聊天）

1. 上传营养标签照片至Claude Chat
2. Claude Chat利用其视觉功能从照片中提取营养成分
3. Claude Chat称MCP工具为：
   • 使用以下命令搜索重复项 search_foods
   • 使用以下命令创建食物条目 create_food_variant 如果没有找到重复项
   • 确认食物ID成功

寻找食物

User: "What's the nutrition info for quinoa?"
Claude: [Searches and shows available options with nutrition details]

管理变量

User: "Add a 1 cup serving size for Brown Rice"
Claude: [Searches, finds existing food, asks to confirm, adds variant]

安全

HTTP基本认证

在HTTP模式下运行时，您可以选择启用基本身份验证：

export MCP_HTTP_BASIC_AUTH_USER=admin
export MCP_HTTP_BASIC_AUTH_PASSWORD=your-secret-password

备注：必须设置用户名和密码才能启用身份验证。如果缺少其中之一，则禁用身份验证。

健康检查

在HTTP模式下运行时，服务器提供健康检查端点：

curl http://localhost:8080/health

贡献

有关开发设置、从源代码构建和贡献指南，请参阅 贡献.md.

许可证

看 许可证 了解详情。

支持

对于问题、疑问或功能请求，请在 GitHub.