bring-photo-mcp

Bring Photo MCP v1

English | Deutsch

商品写真をBring!の買い物リストの項目に変換します。

AIエージェントにパッケージ、ラベル、商品写真を見せて、**「これを買い物リストに追加して」**と言うだけです。Bring Photo MCPを使うと、エージェントが商品を特定し、Bring!カタログと照合して、適切なカテゴリとアイコンを選び、写真を添付して、確認済みの商品をBring!リストに追加できます。

また、項目の検索、追加、チェック、移動、コピー、削除といった一般的なリスト操作にも対応しています。ただし、このツールの特長は写真を起点としたワークフローです。入力の手間が減り、商品名の曖昧さを抑えられるうえ、元の商品画像をリストに直接表示できます。

Bring Photo MCPは、ローカルで動作し、特定のエージェントに依存しない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はプロジェクトをビルドし、src/index.tsをstdioサーバーとして起動します。起動時に設定を検証し、その後でのみBringに認証します。このリポジトリには、意図的にHermesやクライアントのランタイム設定を含めていません。

配布可能な成果物

このパッケージは、filesの許可リストで範囲を明示して公開npmでの配布に備えており、stdioバイナリエントリーポイントとしてbring-photo-mcpを含んでいます。公開向けのシンプルなスキルのガイダンスは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-）
• 複数リストのE2E専用の任意設定BRING_TEST_SECOND_LIST

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を指定する場合は、名前を指定した2つのTESTリストだけを設定する必要があります。空でないBRING_TEST_ITEM_PREFIXも必要です。

ハーネスは一時ディレクトリに2つの合成PNGファイルを作成し、追加と読み戻しに加え、写真の置換と削除を検証します。また、finally内ですべての接頭辞付き項目を削除し、その後、項目が存在しないことを確認します。コピー、移動、複数リストの操作は、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 のマルチパート形式を使用し、写真には imageData フィールドを持つネイティブの FormData を使用します。明示的な transferImage ゲートウェイ機能は、Bring 認証なしで元画像のバイトデータをダウンロードし、転送先にのみアップロードします。
• src/bring-service.ts：ビジネスルール、リストの許可リスト、分類と重複のルール、読み戻し検証、移動時のコピー後削除、およびリストごとの結果を扱います。
• src/mcp-server.ts：Zod で検証する 15 個の 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 は、完全に同一の ID の場合にのみ変更します。複数リストへの呼び出しでは、対象リストごとに 1 件の結果を必ず返し、一部で失敗した場合は 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 を活用したコーディングおよびドキュメント作成ツールを使用して開発されました。自動テスト、分離されたライブ E2E チェック、リリース成果物は、公開前に独立して検証されました。Thomas Schnuecker は引き続きプロジェクトのメンテナーを務め、リリースに責任を負います。

セキュリティ境界とロールバック

認証情報、実際のリスト UUID、商品写真を Git、フィクスチャ、ログに含めてはいけません。このリポジトリはログインやライブ操作を実行しません。明示的に承認された切り替えが行われるまで、既存の bring-safe ソリューションをロールバック手段として変更せずに維持します。

TEST E2E と 8 枚の写真の回帰テストは、自動では意図的に実行されません。これらのテストには、承認済みの専用 TEST リスト、一時的なプレフィックス付きアイテム、および提供されたテスト画像が必要です。実行後は、生成された TEST アイテムと写真をすべて読み戻しによって削除し、存在しないことを確認してください。