SparkyFitness MCP服务器
一个无状态的基于Go-的MCP（模型上下文协议）服务器，充当人工智能代理（如Claude Chat）和SparkyFitness后端之间的API桥梁。该服务器提供创建和搜索具有完整营养数据的食品的工具。
特性
- 智能搜索：在数据库中查找现有食物以避免重复
- 食物创造：创建包含完整营养数据的新食品条目
- 变体管理：为同一食物添加多种份量（例如100克、150克、1杯）
- 双重运输支持:
- 标准：用于本地Claude Desktop集成 - HTTP/SSE：用于远程部署和claude.ai web集成
- 无状态设计：纯API转换层，无本地存储
与AI代理无缝协作： 当与Claude Chat或其他具有视觉能力的人工智能代理一起使用时，用户可以上传营养标签照片，并在调用MCP工具之前让人工智能自动提取数据。
快速开始
使用克劳德桌面（本地）
- 下载或构建二进制文件 （参见 发布)
- 添加到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。
- 重新启动克劳德桌面
- 开始使用它：上传一张营养标签照片，让克劳德将其添加到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/
配置
所需的环境变量
| 变量 | 描述 |
|---|---|
SPARKYFITNESS_API_URL | SparkyFitness的基本URL 服务器组件 （后端），而不是前端。例子： http://localhost:8000 或 https://sparkyfitness-server.example.com |
SPARKYFITNESS_API_KEY | 用于身份验证的API密钥 |
可选环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
MCP_TRANSPORT | stdio | 运输方式： stdio 或 http |
MCP_HTTP_HOST | 0.0.0.0 | 要绑定的主机（仅限HTTP模式） |
MCP_HTTP_PORT | 8080 | 要侦听的端口（仅限HTTP模式） |
MCP_HTTP_BASIC_AUTH_USER | - | HTTP基本身份验证的用户名（可选） |
MCP_HTTP_BASIC_AUTH_PASSWORD | - | HTTP基本身份验证密码（可选） |
可用工具
此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聊天）
- 上传营养标签照片至Claude Chat
- Claude Chat利用其视觉功能从照片中提取营养成分
- 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.
许可证
看 许可证 了解详情。
支持
对于问题、疑问或功能请求，请在 .