FatSecret MCP Server

这是一个提供对FatSecret营养数据库API访问的Model Context Protocol (MCP)服务器，并支持完整的三腿OAuth认证。

功能

• 完整的OAuth 1.0a实现：完整的三腿OAuth流程用于用户认证
• 食品数据库访问：搜索并检索详细的营养信息
• 食谱数据库：搜索食谱并获取详细的烹饪说明
• 用户数据管理：访问用户的饮食日记并添加食物条目
• 安全凭证存储：加密存储API凭证和令牌

开始使用

预备条件

• Node.js（v14或更高版本）
• npm 或 yarn
• 一个FatSecret开发者账户

安装

# 克隆仓库
git clone https://github.com/your-username/fatsecret-mcp.git
cd fatsecret-m- cp

# 安装依赖
npm install

# 构建TypeScript
npm run build

设置

1. 获取FatSecret API凭证

1. 访问FatSecret平台
2. 创建一个开发者账户并注册您的应用程序
3. 记下您的客户端ID和客户端密钥

2. 配置MCP服务器

需要在您的MCP客户端（如Claude Desktop）中配置服务器。在您的MCP配置中添加以下内容：

{
  "mcpServers": {
    "fatsecret": {
      "command": "node",
      "args": ["path/to/fatsecret-mcp-server/dist/index.js"]
    }
  }
}

3. 认证过程

方案1：使用OAuth控制台工具（推荐）

最简单的认证方式是使用包含的OAuth控制台工具：

# 确保您已经构建了项目
npm run build

# 运行OAuth控制台工具
node dist/cli.js

这个交互式工具会：

1. 请求您的客户端ID和客户端密钥
2. 将它们安全地保存在~/.fatsecret-mcp-config.json
3. 引导您完成OAuth流程：
   • 打开浏览器到FatSecret授权页面
   • 提示您在授权后粘贴验证代码
   • 保存访问令牌以供将来使用

方案2：通过MCP工具进行手动认证

如果您希望通过MCP界面（例如，在Claude中）进行认证：

1. 设置您的API凭证：

   使用工具：set_credentials
   参数：
   - clientId: "your_client_id_here"
   - clientSecret: "your_client_secret_here"
   

2. 启动OAuth流程：

   使用工具：start_oauth_flow
   参数：
   - callbackUrl: "oob"（用于带外认证）
   

3. 访问提供的授权URL：

   • 登录您的FatSecret账户（或创建一个）
   • 单击“允许”以授权应用
   • 复制授权页面上显示的验证代码

4. 完成OAuth流程：

   使用工具：complete_oauth_flow
   参数：
   - requestToken: [来自步骤2响应]
   - requestTokenSecret: [来自步骤2响应]
   - verifier: [从授权页面复制的代码]
   

方案3：使用环境变量

您也可以通过环境变量提供凭证：

# 在项目根目录创建一个.env文件
CLIENT_ID=your_client_id_here
CLIENT_SECRET=your_client_secret_here

# 服务器将在启动时自动加载这些

注意：您仍然需要完成OAuth流程以执行特定于用户的操作。

使用

1. 设置API凭证

首先，设置您的FatSecret API凭证：

使用set_credentials工具与您的客户端ID和客户端密钥

2. 认证用户（三腿OAuth）

对于特定于用户的操作，您需要完成OAuth流程：

1. 使用start_oauth_flow工具（带有回调URL或“oob”用于带外）
2. 访问提供的授权URL
3. 授权应用并获取验证代码
4. 使用complete_oauth_flow工具与请求令牌、秘密和验证器

3. 使用API

一旦认证成功，您可以使用所有可用工具：

食品搜索和信息

• search_foods：在数据库中搜索食品
• get_food：获取特定食品的详细营养信息

食谱搜索和信息

• search_recipes：在数据库中搜索食谱
• get_recipe：获取特定食谱的详细信息，包括成分和说明

用户数据（需要认证）

• get_user_profile：获取已认证用户的个人资料
• get_user_food_entries：获取特定日期的食物日记条目
• add_food_entry：向用户的日记添加食物条目

实用工具

• check_auth_status：检查当前认证状态

可用工具

认证工具

set_credentials

设置您的FatSecret API凭证。

参数：

• clientId（字符串，必需）：您的FatSecret客户端ID
• clientSecret（字符串，必需）：您的FatSecret客户端密钥

start_oauth_flow

开始三腿OAuth流程。

参数：

• callbackUrl（字符串，可选）：OAuth回调URL（默认：“oob”）

complete_oauth_flow

完成OAuth流程并授权。

参数：

• requestToken（字符串，必需）：来自start_oauth_flow的请求令牌
• requestTokenSecret（字符串，必需）：来自start_oauth_flow的请求令牌秘密
• verifier（字符串，必需）：来自授权页面的OAuth验证器

check_auth_status

检查当前认证状态。

食品数据库工具

search_foods

在FatSecret数据库中搜索食品。

参数：

• searchExpression（字符串，必需）：搜索词
• pageNumber（数字，可选）：页码（默认：0）
• maxResults（数字，可选）：每页最大结果数（默认：20）

get_food

获取特定食品的详细信息。

参数：

• foodId（字符串，必需）：FatSecret食品ID

食谱数据库工具

search_recipes

在FatSecret数据库中搜索食谱。

参数：

• searchExpression（字符串，必需）：搜索词
• pageNumber（数字，可选）：页码（默认：0）
• maxResults（数字，可选）：每页最大结果数（默认：20）

get_recipe

获取特定食谱的详细信息。

参数：

• recipeId（字符串，必需）：FatSecret食谱ID

用户数据工具（需要认证）

get_user_profile

获取已认证用户的个人资料信息。

get_user_food_entries

获取用户特定日期的食物日记条目。

参数：

• date（字符串，可选）：YYYY-MM-DD格式的日期（默认：今天）

add_food_entry

向用户的日记添加食物条目。

参数：

• foodId（字符串，必需）：FatSecret食品ID
• servingId（字符串，必需）：食品的服务ID
• quantity（数字，必需）：服务的数量
• mealType（字符串，必需）：餐类型（早餐、午餐、晚餐、小吃）
• date（字符串，可选）：YYYY-MM-DD格式的日期（默认：今天）

示例工作流

1. 设置凭证：

   工具：set_credentials
   - clientId: "your_client_id"
   - clientSecret: "your_client_secret"
   

2. 搜索食品：

   工具：search_foods
   - searchExpression: "鸡胸肉"
   

3. 获取食品详情：

   工具：get_food
   - foodId: "12345"
   

4. 认证用户（如果需要）：

   工具：start_oauth_flow
   - callbackUrl: "oob"
   
   # 跟随授权URL，然后：
   
   工具：complete_oauth_flow
   - requestToken: "from_start_oauth_flow"
   - requestTokenSecret: "from_start_oauth_flow"
   - verifier: "from_authorization_page"
   

5. 添加食物到日记：

   工具：add_food_entry
   - foodId: "12345"
   - servingId: "67890"
   - quantity: 1
   - mealType: "午餐"
   

配置存储

服务器将配置（凭证和令牌）存储在~/.fatsecret-mcp-config.json。此文件包含：

• API凭证（客户端ID和密钥）
• OAuth访问令牌（当认证时）
• 用户ID（当认证时）

安全注意事项

• 凭证本地存储在您的主目录中
• OAuth令牌使用适当的HMAC-SHA1签名安全管理
• 所有API通信使用HTTPS
• 服务器实现了适当的OAuth 1.0a安全措施

API参考

此服务器实现了FatSecret平台API。有关详细的API文档，请访问：

• FatSecret平台API文档
• OAuth 1.0a规范

错误处理

服务器提供了常见问题的详细错误消息：

• 缺失或无效的凭证
• OAuth流程错误
• API速率限制
• 网络连接问题
• 无效的参数

测试

命令行测试

项目包括几个测试实用程序：

1. 交互式测试工具

# 运行交互式测试菜单
node test-interactive.js

这提供了一个菜单驱动的接口来测试所有MCP工具。

2. 日期转换测试

# 测试日期转换逻辑
node test-date-conversion.js

验证日期是否正确转换为FatSecret的“自纪元以来的天数”格式。

3. 直接JSON-RPC测试

# 通过管道发送测试消息
node test-mcp.js | node dist/index.js

在Claude Desktop中测试

1. 在配置MCP服务器后重启Claude Desktop
2. 查找可用工具中的“fatsecret”
3. 使用check_auth_status工具开始以验证连接

故障排除

常见问题

“无效整数值：日期”

• FatSecret API期望日期为自纪元以来的天数（1970-01-01）
• 服务器会自动将YYYY-MM-DD格式的日期转换
• 如果您遇到此错误，请确保您正在使用最新版本

OAuth认证失败

• 验证您的客户端ID和客户端密钥是否正确
• 确保您使用的是正确的URL（OAuth为authentication.fatsecret.com）
• 检查您是否从授权页面复制了整个验证代码

Claude中找不到服务器

• 确保MCP配置中的路径是绝对路径，而不是相对路径
• 验证服务器是否成功构建（npm run build）
• 检查Claude的日志是否有任何错误消息

“需要用户认证”

• 使用CLI工具或MCP工具完成OAuth流程
• 使用check_auth_status工具检查认证状态
• 令牌保存在~/.fatsecret-mcp-config.json

开发

要修改或扩展服务器：

# 安装依赖
npm install

# 构建并运行
npm run build
npm start

# 开发模式，自动重建
npm run dev

项目结构

fatsecret-mcp/
├── src/
│   ├── index.ts        # 主MCP服务器实现
│   └── cli.ts          # OAuth控制台工具
├── dist/               # 编译后的JavaScript文件
├── test-*.js           # 测试实用程序
├── package.json
├── tsconfig.json
└── README.md

许可证

MIT许可证 - 详见LICENSE文件。