bring-photo-mcp

Bring Photo MCP v1

English | 德语

将商品照片转化为 Bring! 购物清单条目。

向 AI Agent 展示包装、标签或商品照片，然后说：“把这个添加到我的购物清单。” Bring Photo MCP 让 Agent 识别商品、与 Bring! 商品目录匹配、选择正确的类别和图标、附上照片，并将经验证的结果添加到 Bring! 清单。

它还提供常见的清单操作——搜索、添加、勾选、移动、复制和移除条目——但重点在于以照片为先的工作流：减少输入，避免商品名称含糊不清，并将原始商品图片直接显示在清单上。

Bring Photo MCP 是一个本地、与 Agent 无关的 TypeScript MCP 服务。可执行的 stdio 入口点仅在通过本地环境变量验证后才会启动；本仓库不包含 Hermes 或客户端运行时配置。

安装

要求：Node.js 20+ 和 npm。

npm install
npm run typecheck
npm run lint
npm test
npm run build

本项目使用官方 MCP TypeScript SDK（@modelcontextprotocol/sdk）。npm start 会构建项目，并以 stdio 服务的形式启动 src/index.ts。启动时会先验证配置，之后才使用 Bring 进行身份验证；本仓库有意不包含 Hermes 或客户端运行时配置。

可分发制品

该软件包已为发布到公开 npm 做好准备，并通过显式的 files 允许列表限制包含的文件，同时提供 bring-photo-mcp stdio 二进制入口点。面向公众的精简技能指南见 SKILL.md；经过测试的客户端模板见 docs/MCP-CLIENT-CONFIGURATION.md。无需切换运行时即可完成迁移和回滚，相关说明见 docs/MIGRATION-ROLLBACK.md。

配置

切勿提交含有真实值的 .env 文件。配置模型要求：

• BRING_ENV=test|prod
• BRING_EMAIL、BRING_PASSWORD
• BRING_DEFAULT_LIST
• BRING_ALLOWED_LISTS（以逗号分隔）
• BRING_LOCALE（默认值为 de-DE）
• BRING_TEST_ITEM_PREFIX（默认值为 MCP-TEST-）
• 可选的 BRING_TEST_SECOND_LIST，仅供多清单 E2E 使用

src/config.ts 会验证这些值。在 PROD 环境中，服务仅接受允许列表中的清单；生产运行时还必须指向固定的发布标签。TEST 仅使用专用的允许列表清单和带临时前缀的测试条目。

选择启用的线上 E2E 测试

npm run test:e2e 不会包含在 npm test 中，本项目也未在此处运行该命令。只有在环境配置完整时才会启动，并且拒绝任何非 BRING_ENV=test 的配置。BRING_ALLOWED_LISTS 必须恰好包含 BRING_DEFAULT_LIST；设置 BRING_TEST_SECOND_LIST 时，必须恰好包含两个已配置的 TEST 清单。必须设置非空的 BRING_TEST_ITEM_PREFIX。

测试工具会在临时目录中创建两个合成 PNG 文件，验证添加和回读，以及照片替换和移除；最后会移除所有带自身前缀的条目，并检查其是否已全部删除。复制、移动和多清单操作仅在显式设置 BRING_TEST_SECOND_LIST 时运行；未设置时，测试工具会如实报告跳过这些操作。

架构

• src/bring-adapter.ts：确定性的 Bring 网关接口和 HTTP 协议适配器。旧版物品请求体仅使用 URLSearchParams 生成；通过 bringlists/{listUuid}/details 读取详情；从 https://web.getbring.com/locale/catalog.{locale}.json 加载目录；详情元数据使用 ISO-8859-1 多部分格式；照片使用原生 FormData，字段为 imageData。显式的 transferImage 网关功能会在不使用 Bring 身份验证的情况下下载源图像字节，并仅将其上传到目标列表。
• src/bring-service.ts：业务规则、列表允许名单、分类和重复项规则、回读验证、移动时先复制后删除，以及每个列表的结果。
• src/mcp-server.ts：15 个经 Zod 验证的 MCP 工具；不包含传输层。
• src/redaction.ts：从错误文本中隐去密码／令牌字段、类似 UUID 的 ID 和本地路径。

只有在重新读取物品和详情后，写入操作才算成功。详情必须包含 UUID、userIconItemId 和 userSectionId；照片还必须包含 imageUrl。除非 itemId 完全匹配，否则不会使用损坏或孤立的详情。

工具

读取：bring_list_lists、bring_list_items、bring_search_catalog、bring_list_categories、bring_suggest_classification、bring_get_item。

写入：bring_add_item、bring_attach_photo、bring_replace_photo、bring_remove_photo、bring_copy_item、bring_move_item、bring_check_item、bring_uncheck_item、bring_remove_item。

bring_add_item 始终要求提供 icon_item_id 和 category_id；两者都必须与已加载的目录匹配。duplicate_policy 的默认值为 fail；update_exact 只会更改身份完全相同的物品。多列表调用始终为每个目标列表返回一个结果，部分失败时使用 status: "partial"。

错误代码

CONFIGURATION、LIST_NOT_ALLOWED、LIST_NOT_FOUND、ITEM_NOT_FOUND、INVALID_CLASSIFICATION、DUPLICATE_AMBIGUOUS、VERIFICATION_FAILED、UPSTREAM_FAILURE、IMAGE_INVALID、CLASSIFICATION_UNCERTAIN。

错误文本不包含凭据、UUID 或图像路径。

开发与验证

本项目在人工指导和审查下，借助 AI 辅助编码和文档工具开发。发布前，已独立验证自动化测试、隔离的实时端到端检查和发布构件。Thomas Schnuecker 仍是项目维护者，并负责发布。

安全边界与回滚

凭据、真实列表 UUID 和产品照片不得放入 Git、测试固件或日志中。本代码库不会触发登录或实时操作。现有的 bring-safe 解决方案保持不变，作为回滚方案，直到明确批准切换为止。

TEST E2E 和八张照片回归测试不会自动运行：它们需要经批准的专用 TEST 列表、带临时前缀的物品，以及提供的测试图像。之后，通过回读移除所有生成的 TEST 物品和照片，并验证它们确已不存在。