技术文档摘要

Open Food Facts MCP 服务器

这是为 Open Food Facts 项目实现的一个 Model Context Protocol (MCP) 服务器。它使用官方的 Model Context Protocol 规范，向 AI 驱动的开发工具提供有关食品产品的上下文信息。

概述

什么是 Model Context Protocol？

Model Context Protocol (MCP) 是一种标准化的方式，用于 AI 驱动的开发工具与代码仓库和其他数据源进行通信。它通过提供结构化的访问方式，使 AI 工具能够更好地理解代码库：

• 文件内容和项目结构
• 代码关系和架构洞察
• 领域特定的知识和文档
• 代码探索的交互式工具

对 Open Food Facts 的好处

此 MCP 服务器实现了以下功能：

1. 增强的 AI 辅助：LLMs 可以提供更准确的食品产品信息
2. 提高开发者生产力：自动辅助常见的 Open Food Facts 开发任务
3. 知识共享：贡献者对代码库有更好的理解
4. 用户支持：改善营养和产品相关问题的回答

服务器模式

MCP 服务器支持两种操作模式：

标准模式

默认模式，专注于为普通用户提供食品产品信息：

• 仅限于食品产品工具的访问
• 资源有限，专注于产品信息
• 简化界面，适用于非开发者用户
• 优化用于营养分析和食品产品问题

开发者模式

增强模式，带有额外的工具供 Open Food Facts 贡献者使用：

• 所有标准食品产品工具
• GitHub 仓库分析工具
• 代码库导航和分析工具
• 开发特定资源和提示
• 技术文档和指南

可用工具

食品产品工具（两种模式都可用）

• searchProducts：按名称、品牌、类别或其他关键词搜索 Open Food Facts 数据库中的产品
• getProductByBarcode：通过条形码（EAN、UPC 等）获取产品的详细信息
• analyzeProduct：使用 AI 分析 Open Food Facts 数据库中的产品
• compareProducts：使用 AI 比较 Open Food Facts 数据库中的两个产品
• suggestRecipes：使用来自 Open Food Facts 数据库的产品生成 AI 驱动的食谱建议

GitHub 仓库工具（仅开发者模式）

• analyzeGitHubIssue：使用 AI 分析 Open Food Facts 仓库中的特定 GitHub 问题
• analyzeGitHubIssuesByLabel：分析具有特定标签的多个 GitHub 问题
• createGitHubIssueRoadmap：基于 Open Food Facts 仓库中的开放 GitHub 问题生成优先级路线图

开发者工具（仅开发者模式）

• analyzeRepository：分析 Open Food Facts 仓库的结构和组织
• explainCode：获取 Open Food Facts 代码库中代码段的详细解释
• matchIssues：查找与特定问题相关的议题和拉取请求
• generatePR：为代码更改生成拉取请求模板
• generateTests：为函数或模块创建测试用例
• gitHelper：在 Open Food Facts 开发过程中获得 git 命令的帮助

快速开始

先决条件

• Node.js (v16.x 或更高版本)
• npm 或 yarn
• 访问 Open Food Facts API（无需身份验证）

安装

1. 克隆仓库或导航到 MCP 服务器目录：

cd mcp-server

2. 安装依赖项：

npm install

3. 构建服务器：

npm run build

4. 启动服务器：

标准模式（默认）：

npm start
# 或
node dist/cli.js

开发者模式：

npm start -- --developer
# 或
node dist/cli.js --developer

VS Code 集成

在 VS Code 中设置 MCP

1. 安装 VS Code 的 "Model Context Protocol" 扩展

2. 创建或更新 .vscode/mcp.json，添加适当的配置：

对于标准用户：

{
    "servers": {
        "openfoodfacts-standard": {
            "command": "node",
            "args": [
                "${workspaceFolder}/mcp-server/dist/cli.js"
            ],
            "env": {
                "TRANSPORT": "stdio"
            },
            "description": "仅包含食品产品工具的标准模式"
        }
    },
    "defaultServer": "openfoodfacts-standard"
}

对于开发者：

{
    "servers": {
        "openfoodfacts-developer": {
            "command": "node",
            "args": [
                "${workspaceFolder}/mcp-server/dist/cli.js",
                "--developer"
            ],
            "env": {
                "TRANSPORT": "stdio"
            },
            "description": "包含所有工具的开发者模式，包括 GitHub 和代码分析"
        }
    },
    "defaultServer": "openfoodfacts-developer"
}

3. 使用 VS Code 中的 "MCP: 连接到服务器" 命令，并选择您偏好的服务器模式

示例工具提示

以下是您可以使用任何 AI 助手触发特定 MCP 工具的示例提示。这些展示了自然地表述请求以访问每个工具功能的方法。

标准模式工具示例

searchProducts

• "在 Open Food Facts 数据库中搜索巧克力麦片"
• "找到含有杏仁奶的产品"
• "在 Open Food Facts 中查找有机酸奶产品"

getProductByBarcode

• "获取条形码为 3017620422003 的产品信息"
• "条形码为 EAN 5000159407236 的产品里有什么？"
• "显示条形码 8076809513326 的营养数据"

analyzeProduct

• "你能从营养角度分析 Nutella 吗？"
• "分析 Cheerios 麦片并告诉我它是否健康"
• "给我分析一下奥利奥饼干的成分"

compareProducts

• "比较 Nutella 和 Nocciolata"
• "哪一种更健康：可口可乐还是百事可乐？"
• "从营养角度比较杏仁奶和豆浆"

suggestRecipes

• "我可以用希腊酸奶做什么？"
• "提出一些使用鹰嘴豆的食谱"
• "给我一些关于藜麦的食谱创意"

开发者模式工具示例

analyzeGitHubIssue

• "分析 openfoodfacts-server 仓库中的 GitHub 问题 #1234"
• "问题 #876 在 openfoodfacts-server 中的状态是什么？"
• "给我总结一下 GitHub 问题 #2468"

analyzeGitHubIssuesByLabel

• "分析 openfoodfacts-server 仓库中标记为 'bug' 的问题"
• "标记为 'enhancement' 的问题有哪些共同主题？"
• "总结所有标记为 'documentation' 的问题"

createGitHubIssueRoadmap

• "为 openfoodfacts-server 仓库创建一个路线图"
• "生成一个短期路线图，用于移动应用改进"
• "应该优先考虑哪些产品搜索功能？"

analyzeRepository

• "分析 Open Food Facts 仓库的结构"
• "给我一个代码库架构的概述"
• "Open Food Facts 代码库的整体设计是什么样的？"

explainCode

• "解释产品搜索功能的工作原理"
• "Open Food Facts 中的分类系统是如何工作的？"
• "解释处理产品图片的代码"

matchIssues

• "查找与产品图片处理相关的 GitHub 问题"
• "是否有任何关于条形码扫描问题的问题？"
• "匹配与产品搜索功能相关的问题"

generatePR

• "为修复产品搜索端点生成一个 PR 模板"
• "我需要一个拉取请求来添加一个新的字段到产品模式中"
• "创建一个改进错误处理的 PR"

generateTests

• "为产品搜索功能生成测试"
• "为条形码验证函数创建单元测试"
• "我需要用户认证流程的测试用例"

gitHelper

• "如何在 Open Food Facts 中为一个特性创建新分支？"
• "为这个项目贡献的正确 git 工作流是什么？"
• "为了更新我的 fork，我应该使用哪些 git 命令？"

LLM 连接方法

您可以将各种 AI 助手连接到您的 Open Food Facts MCP 服务器：

VS Code 扩展与 GitHub Copilot

1. 安装 VS Code 的 MCP 扩展
2. 如上所示配置 .vscode/mcp.json
3. 通过 VS Code MCP 扩展 UI 连接

Claude Desktop

1. 使用 HTTP/SSE 传输模式启动您的 MCP 服务器：

PORT=28375 npm start
# 对于开发者模式：
PORT=28375 npm start -- --developer

2. 在 Claude Desktop 中，连接到 http://localhost:28375/sse 的 MCP 服务器

其他 AI 工具（如 Cursor AI、WindsurfAI 等）

1. 按照您喜欢的模式启动您的 MCP 服务器
2. 配置 AI 工具以连接到您的本地 MCP 服务器
3. 使用上面的示例提示访问特定工具

资源和提示

MCP 服务器根据活动模式提供不同的资源和提示集：

标准模式资源

• 产品信息
• 数据库模式
• API 文档
• 食品类别分类法

开发者模式附加资源

• 项目结构导航
• 代码模式和约定
• 文件组织指南
• 开发模板

提示

服务器提供了预配置的提示以完成常见任务：

标准模式：

• 分析食品产品
• 比较产品
• 检查添加剂

开发者模式（附加）：

• 调试 Perl 代码
• 解释代码库结构
• 实现功能
• 优化 MongoDB 查询
• 创建单元测试
• 审查拉取请求
• 以及许多其他开发导向的提示

有效使用 MCP 工具

为了最大限度地发挥 MCP 工具的效果：

产品信息（标准模式）

1. 查找产品：

   • 使用 searchProducts 按名称、品牌或类别查找产品
   • 使用 getProductByBarcode 当您有一个具体的产品条形码时

2. 分析和比较：

   • 使用 analyzeProduct 获取营养见解和健康分析
   • 使用 compareProducts 直接比较两个产品
   • 使用 suggestRecipes 根据成分获取烹饪创意

开发任务（开发者模式）

1. 理解代码库：

   • 使用 analyzeRepository 把握整体结构
   • 使用 explainCode 获取详细的代码解释

2. 问题管理：

   • 使用 analyzeGitHubIssue 理解特定问题
   • 使用 analyzeGitHubIssuesByLabel 识别问题之间的模式
   • 使用 matchIssues 查找与问题相关的议题

3. 贡献代码：

   • 使用 generatePR 创建 PR 模板
   • 使用 generateTests 添加测试覆盖
   • 使用 gitHelper 获取 git 工作流指导

示例用户工作流程

标准模式工作流程示例

1. 营养分析：

   用户："Nutella 是否健康？"
   MCP 流程：
   1. 使用 searchProducts 查找 Nutella
   2. 使用找到的条形码调用 getProductByBarcode
   3. 使用 analyzeProduct 进行营养评估
   

2. 产品比较：

   用户："Nutella 和 Nocciolata 哪个更健康？"
   MCP 流程：
    1. 使用 searchProducts 查找每个产品
   2. 使用找到的条形码比较产品
   3. 结构化的营养值比较
   

3. 食谱创意：

   用户："我可以用希腊酸奶做什么？"
   MCP 流程：
   1. 使用 searchProducts 查找希腊酸奶
   2. 使用该产品建议食谱
   

开发者模式工作流程示例

1. 理解代码库：

   用户："产品模式是如何组织的？"
   MCP 流程：
   1. 使用 explainCode 关注模式
   2. 使用 analyzeRepository 查找相关组件
   

2. 解决问题：

   用户："帮我调试这个与产品验证相关的 Perl 错误"
   MCP 流程：
   1. 使用 matchIssues 查找类似的问题
   2. 使用 explainCode 理解验证逻辑
   

3. 贡献：

   用户："我想在产品模式中添加一个新的字段"
   MCP 流程：
   1. 使用 explainCode 检查模式结构
   2. 使用 generatePR 创建 PR 模板
   3. 为新字段生成测试
   

实现细节

服务器架构

MCP 服务器的结构如下：

• src/cli.ts：命令行接口，解析开发者模式标志
• src/server.ts：核心服务器实现，具有模式特定配置
• src/tools/：包含所有工具实现
  • src/tools/index.ts：中央注册表，根据模式有条件地注册工具
  • src/tools/product-search.ts：产品搜索和条形码查找工具
  • src/tools/ai-analysis-tool.ts：AI 驱动的产品分析工具
  • src/tools/github-issues-tool.ts：GitHub 问题分析工具（开发者模式）
• src/resources/：资源处理器和注册表，带模式过滤
• src/prompts/：提示定义和处理器，带模式过滤
• src/sampling/：与 AI 模型交互的服务
• src/transport/：传输层实现（stdio, HTTP/SSE）

命令行参数

服务器支持以下命令行参数：

• --developer：启用带有额外工具和资源的开发者模式
• --transport=<类型>：设置传输类型（stdio, http）
• --port=<数字>：设置 HTTP 端口（HTTP/SSE 传输）
• --help：显示帮助信息

调试和故障排除

常见问题

1. 连接问题：

   • 检查服务器是否以正确的传输模式运行
   • 使用 HTTP/SSE 传输时检查端口可用性
   • 确保 VS Code 扩展已正确配置

2. 标准模式中缺少工具：

   • 开发者工具需要 --developer 标志
   • 检查是否以标准模式启动了服务器

3. GitHub API 速率限制：

   • 服务器使用未经身份验证的 GitHub API 调用，这有速率限制
   • 考虑使用身份验证连接到 GitHub 以获得更高的限制

日志

服务器输出日志以帮助诊断问题：

• 标准日志输出显示连接信息和错误
• 启动时显示服务器模式和启用的功能
• 工具调用和错误详情被记录

贡献

欢迎贡献！这里有一些可以改进 MCP 服务器的方法：

1. 为 Open Food Facts 特定功能添加更多专用工具
2. 通过提供更多详细信息来增强现有工具
3. 改进错误处理和验证
4. 添加对更多数据源的支持

开发工作流程

1. 在 src/ 目录中进行更改
2. 使用 npm run build 构建
3. 测试两种模式：标准模式和开发者模式
4. 提交 PR 并清晰地记录您的更改

许可证

本项目在 GNU Affero General Public License 下发布，与 Open Food Facts 项目的许可证相同。