Open Food Facts MCP

🚀 開放食品事實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克（低）

🤝 貢獻指南

1. 分叉倉庫。
2. 創建功能分支（git checkout -b feature/amazing-feature）。
3. 編寫測試並進行更改。
4. 運行質量檢查（npm run validate）。
5. 提交更改（git commit -m 'Add amazing feature'）。
6. 推送到分支（git push origin feature/amazing-feature）。
7. 打開拉取請求。

📄 許可證

本項目採用MIT許可證 - 有關詳細信息，請參閱LICENSE文件。

🙏 致謝

• 開放食品事實：提供全面的食品數據庫。
• 模型上下文協議：提供MCP規範。
• 維護食品數據質量的全球貢獻者社區。

需要幫助？ 請打開一個問題或查看示例以獲取詳細的使用模式。