JinDaGe - open-food-facts-mcp MCP Details

article

README

🚀 开放食品事实MCP服务器

这是一个全面的模型上下文协议（MCP）服务器，它能让AI助手访问开放食品事实数据库。用户可以通过该服务器查询详细的食品产品信息、营养数据和环境评分，从而做出明智的食品选择。

🚀 快速开始

🐳 Docker部署（推荐）

# 克隆并运行
git clone https://github.com/conner/open-food-facts-mcp
cd open-food-facts-mcp
docker-compose up --build

💻 本地开发

# 安装依赖
npm install

# 配置环境
cp .env.example .env

# 构建并启动
npm run build
npm start

# 开发模式
npm run dev

✨ 主要特性

产品查询：通过条形码获取详细信息，包括营养成分、配料和评分。
智能搜索：通过类别、品牌、营养等级等高级过滤功能查找产品。
营养分析：解读营养评分、NOVA加工类别和生态评分。
产品比较：在不同标准下对多个产品进行并排比较。
饮食建议：根据饮食偏好和限制提供产品建议。
速率限制：内置速率限制，遵守开放食品事实API的约束。
支持Docker：可使用Docker和Docker Compose进行生产部署。

📦 安装指南

通过环境变量配置服务器：

# API配置
OPEN_FOOD_FACTS_BASE_URL=https://world.openfoodfacts.net
OPEN_FOOD_FACTS_USER_AGENT=YourApp/1.0 (contact@example.com)

# 速率限制（每分钟请求数）
RATE_LIMIT_PRODUCTS=100
RATE_LIMIT_SEARCH=10
RATE_LIMIT_FACETS=2

💻 使用示例

可用工具

`get_product`

通过条形码检索全面的产品信息。

{
  "barcode": "3017620422003"
}

返回值：产品名称、品牌、营养评分、配料、营养成分和元数据。

`search_products`

使用高级过滤功能搜索产品。

{
  "search": "organic chocolate",
  "categories": "snacks",
  "nutrition_grades": "a,b,c",
  "page_size": 10
}

过滤器：类别、品牌、国家、营养等级、NOVA类别、排序选项。

`analyze_product`

获取详细的营养分析和评分解读。

{
  "barcode": "3017620422003"
}

返回值：评分解释、带有健康评估的营养明细和加工等级详情。

`compare_products`

在不同方面比较多个产品。

{
  "barcodes": ["3017620422003", "8712566073219"],
  "focus": "nutrition"
}

关注选项：nutrition（营养）、environmental（环境）、processing（加工）、ingredients（配料）。

`get_product_suggestions`

获取个性化的产品推荐。

{
  "category": "beverages",
  "dietary_preferences": ["vegan", "organic"],
  "min_nutriscore": "b",
  "max_results": 5
}

饮食选项：素食、纯素食、无麸质、有机、低脂、低糖、高蛋白。

MCP集成

添加到您的MCP客户端配置中：

{
  "mcpServers": {
    "open-food-facts": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "open-food-facts-mcp"]
    }
  }
}

或者用于本地开发：

{
  "mcpServers": {
    "open-food-facts": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/open-food-facts-mcp"
    }
  }
}

📚 详细文档

数据与评分

营养评分（Nutri-Score）

A - E等级：表示整体营养质量。
绿色（A/B）：更健康的选择。
红色（D/E）：不太健康的选择。

NOVA类别

第1类：未加工或最低限度加工的食品。
第2类：加工烹饪原料。
第3类：加工食品。
第4类：超加工食品。

生态评分（Eco-Score）

A - E等级：表示环境影响。
考虑包装、运输和生产方法。

🔧 技术细节

开发

测试

# 运行所有测试
npm test

# 监听模式
npm run test:watch

# 覆盖率报告
npm run test:coverage

# 验证代码质量
npm run validate

代码质量

# 类型检查
npm run typecheck

# 代码检查
npm run lint
npm run lint:fix

项目结构

src/
├── client.ts       # 带有速率限制的HTTP客户端
├── handlers.ts     # MCP工具实现
├── index.ts        # MCP服务器入口点
├── tools.ts        # 工具定义
└── types.ts        # TypeScript类型和模式

tests/
├── client.test.ts      # 客户端单元测试
├── handlers.test.ts    # 处理程序单元测试
├── server.test.ts      # 集成测试
├── validation.test.ts  # 模式验证测试
├── rate-limiting.test.ts # 速率限制测试
├── e2e.test.ts        # 端到端测试
├── fixtures/          # 测试数据
└── utils/            # 测试实用工具

性能

速率限制：自动执行API限制。
高效缓存：智能去重请求。
批量操作：优化多产品比较。
错误恢复：优雅处理API故障。

API限制

服务器遵守开放食品事实API的速率限制：

产品查询：每分钟100个请求。
搜索查询：每分钟10个请求。
方面查询：每分钟2个请求。速率限制会自动执行，并提供适当的错误消息。

数据源

所有数据均来自开放食品事实，这是世界上最大的开放食品数据库：

来自150多个国家的900,000多种产品。
由全球贡献者维护的协作数据。
开放数据库许可证：确保免费获取食品信息。
全球社区的实时更新。

示例

基本产品信息

**能多益巧克力榛子酱（Nutella）**
品牌：费列罗（Ferrero）
净含量：400克
类别：甜味酱、巧克力酱

评分：
营养评分（Nutri-Score）：E | NOVA类别：4 | 生态评分（Eco-Score）：D

配料：
糖、棕榈油、榛子（13%）、脱脂奶粉...

营养成分（每100克）：
能量：539千卡 | 脂肪：30.9克 | 碳水化合物：57.5克 | 糖：56.3克

营养分析

能多益巧克力榛子酱（Nutella）营养分析

评分：
• 营养评分（Nutri-Score）E：营养质量非常差
• NOVA类别4：超加工食品
• 生态评分（Eco-Score）D：环境影响高

营养明细：
• 能量：539千卡（高）
• 脂肪：30.9克（高）
• 糖：56.3克（高）
• 盐：0.107克（低）

🤝 贡献指南

分叉仓库。
创建功能分支（git checkout -b feature/amazing-feature）。
编写测试并进行更改。
运行质量检查（npm run validate）。
提交更改（git commit -m 'Add amazing feature'）。
推送到分支（git push origin feature/amazing-feature）。
打开拉取请求。

📄 许可证

本项目采用MIT许可证 - 有关详细信息，请参阅LICENSE文件。

🙏 致谢

开放食品事实：提供全面的食品数据库。
模型上下文协议：提供MCP规范。
维护食品数据质量的全球贡献者社区。

需要帮助？ 请打开一个问题或查看示例以获取详细的使用模式。

open-food-facts-mcp