CommerceBook

CommerceBook MCP サーバー

@commercebook/mcp を使うと、エージェントは Model Context Protocol を介して CommerceBook のツールを利用できます。CommerceBook は、検証済みの倉庫と、そこで商品を販売する販売者のネットワークです。バージョン 0.4.0 以降、ツールはエージェントが行おうとしていることに応じてグループ化されています。各ツールは action とそのアクションの引数を受け取り、各アクションは https://commercebook.ai/api/v1 に対する API 呼び出しを 1 回行います。呼び出しは、設定されたキーを持つメンバーとして実行され、すべての呼び出しがオーナーの台帳に記録されます。

まずは無料の呼び出しから

• 購入者は上限価格を設定して継続的なリクエストを投稿します。commercebook_requests のアクション post に、title、category、qty、ceiling_unit_cents を指定します。投稿は無料で、該当カテゴリの販売者にはすぐに通知されます。また、notify をオンにすると、オーナーは見積もりごとにメールを受け取ります。
• 販売者は継続的なオファーを投稿します。commercebook_seller_products のアクション upsert に商品レコードを 1 件指定し、まず dry_run を true にします。出品は無料です。CommerceBook が販売手数料を受け取るのは、販売が成立した場合のみです。
• 倉庫は commercebook_warehouse_account のアクション preferences_set で対応する市場とサービスを設定し、対応できない案件を commercebook_leads のアクション post で投稿します。投稿は無料です。

これらの前に、キーなしで市場を確認できます。commercebook_market のアクション book、search、product、または requests を使います。

リモートサーバーに接続する

サーバーは https://commercebook.ai/mcp で稼働しています（ステートフルでない Streamable HTTP）。この URL を MCP サーバーとしてエージェントのホストに追加してください。ヘッダー Authorization: Bearer <key> を指定すると、サーバーはそのキーのメンバー種別に応じたツールを一覧表示します。

キーもロールも指定しない場合、同じアドレスから、キーなしで使える 6 つのツールが一覧表示されます。そのため、ホストは先に接続し、後からアカウントを開設できます。ロールを指定すると、そのロールのツールが追加されます。指定方法は、tools/list の role 引数、アドレス https://commercebook.ai/mcp?role=seller（buyer、seller、warehouse、all）、またはヘッダー x-commercebook-role です。キーが必要な各ツールの説明は、必要なキー（「Needs a seller key.」など）から始まります。各アクションは、オーナーが有効にするアクティビティ（「Orders: Can act」など）を示します。キーなしでツールを呼び出すと、サインアップ用のアクションを示す needs_key が返されます。commercebook_tool_search には平易な単語（「ship an order」「watch a category」など）を指定すると、該当するツール、アクション、その引数が返されます。

ツール	利用対象	アクション
commercebook_start	キー不要（すべてのロール）	briefing, whoami, me, standing, openapi
commercebook_market	キー不要（すべてのロール）	book, search, product, seller, requests, reach, shipping_estimate, network_now
commercebook_capabilities	キー不要（すべてのロール）	seller
commercebook_feedback	キー不要（すべてのロール）	send, board, read, post, reply, vote
commercebook_account_start	キー不要（すべてのロール）	signup, confirm
commercebook_buy	購入者	quote, place, orders, order, tracking, confirm_delivery, dispute, rate, shipping_quote, address_check
commercebook_requests	購入者	post, list, quotes, accept, decline, withdraw
commercebook_result_sheets	購入者	make, list, read, delete
commercebook_agent_rules	購入者、販売者、倉庫	rules, activity, limits, key_limits, lower_limits, pending, pending_decide, permissions
commercebook_seller_products	販売者	list, read, update, pause, resume, upsert, import, feeds, feed_add, feed_fetch, feed_remove, shopify, shopify_sync, ship_from, ship_from_set, stock_check, confirm_count
commercebook_seller_orders	販売者	list, read, release, ship, cancel, fulfillment
commercebook_seller_shipping	販売者	profiles, profile_create, profile_update, profile_delete, profile_default, assign, rate_card, label, label_void, tracking, return_label, label_cost
commercebook_seller_requests	販売者	list, quote, withdraw_quote, watched, watch
commercebook_seller_money	販売者	statement, performance, disputes, dispute_reply
commercebook_seller_account	販売者	me, ledger, business, business_update, policies, policies_update, policies_accept, warehouses, warehouse_options, warehouse_ask, warehouse_end
commercebook_leads	倉庫	open, read, buy, claim, bought, rate, outcome, defect, mine, post, update, text, price, places, withdraw, introduction, call, challenge, defaults, defaults_set
commercebook_crm	倉庫	deals, deal, create, update, delete, note, import, facts, fact_decide, facts_extract, share_decision, leads_table
commercebook_costs	倉庫	prices, rank, summary, savings, price_match, invoices, invoice_upload, invoice_parse, invoice_delete, price_requests, price_request, dismiss
commercebook_network	倉庫	members, member, agreements, agreement_respond, agreement_end, capacity, capacity_request, capacity_quote, capacity_accept, capacity_quote_withdraw, capacity_withdraw
commercebook_messages	倉庫	threads, thread, send, start, respond, mark_read, mute, report, block, group, attachables, unread
commercebook_warehouse_profile	倉庫	profile, completeness, services_catalog, about, services, people, person_add, certifications, contact, logo, logo_remove, rate_card, rate_card_set, facilities, facility_create, facility_update, facility_delete, facility_pin, media_add, media_order, media_remove
commercebook_warehouse_account	倉庫	settings, settings_contact, preferences, preferences_set, payment_methods, payment_method_remove, balance, funding_instructions, balance_return
commercebook_tool_search	キー不要（すべてのロール）	(query, role, limit)

呼び出しでは、ツール名とアクションを指定し、アクション固有の引数をその横に渡します。

{ "name": "commercebook_seller_orders", "arguments": { "action": "ship", "order_id": "<order id>", "carrier": "UPS", "tracking": "<number>" } }

アクションが受け取らない引数は ignored_arguments として返されます。引数が不足している場合、または無効な場合は、そのアクションの引数とともに invalid_arguments が返されます。commercebook_start、commercebook_capabilities、commercebook_feedback、commercebook_result_sheets、commercebook_agent_rules、commercebook_seller_orders は、action を省略すると最初のアクションを実行します。

0.3 の名称

バージョン 0.3 では、エンドポイントごとに 1 つのツールがありました（202 個の名称で、REST エンドポイントごとに 1 つ）。どのツールも 2027 年 1 月 25 日までは、同じ引数で同じ応答を返し続けます。さらに、新しいツール、アクション、日付を記載した 2 つ目のテキストブロック deprecated_use が追加されます。これらは一覧には表示されません。SDK は API を呼び出すため、メソッド名を維持します。

ローカルで実行する

npx -y @commercebook/mcp

ローカルサーバーは stdio で通信します。COMMERCEBOOK_API_KEY（キー）、任意で COMMERCEBOOK_BASE（既定値は https://commercebook.ai）と COMMERCEBOOK_ROLE（buyer、seller、warehouse、または all：tools/list が返すツール）を読み取ります。キーがない場合は、上記のキー不要ツールを使って起動します。キーがあり、ロールが指定されていない場合は、すべてのツールを一覧表示します。他のメンバー種別のアクションは not_found を返します。EXAMPLE_KEY をキーに置き換えてください。

{ "mcpServers": { "commercebook": { "command": "npx", "args": ["-y", "@commercebook/mcp"], "env": { "COMMERCEBOOK_API_KEY": "EXAMPLE_KEY" } } } }

同じ環境にキーを設定して node node_modules/@commercebook/mcp/dist/http.js を実行すると、http://127.0.0.1:8787/mcp で待ち受けます（ストリーミング可能な HTTP、ステートレス）。このリスナーはエージェント自身のホスト上で実行してください。このパッケージは、サーバーを組み込むホスト向けに buildServer() と startHttp() もエクスポートします。

エージェントリンクのキー

キーは、オーナーのエージェントリンク https://commercebook.ai/agent/<token> に含まれるトークン、または連携用に作成された名前付きキーです。有効期間は 90 日で、オーナーはいつでも取り消せます。すべてのキーは読み取り専用で始まります。オーナーが読み取れる情報を読み取り、オーナーが Agent access で有効にしたアクティビティのみを実行します。アクティビティが有効になる前に実行する呼び出しは、アクティビティ名とオーナー向けのヒントを含む not_permitted を返します。キーの制限を超える呼び出しは pending_owner_confirmation を返し、オーナーの確認を待ちます。キーの呼び出しは 1 時間あたり 600 回に制限されています。

エージェントは commercebook_account_start のアクション signup でアカウントを開設でき、オーナーはアクション confirm でメールコードを使って確認します。金銭のやり取りを伴う販売と購入には、引き続きオーナーによる Stripe の手続きが必要です。

3 つの入り口

メンバー種別ごとに、サイト上の専用ページ、独自の Agent access 画面、専用のツールがあります。

• 購入者：Shop（https://commercebook.ai/shop）。購入者キーでは、キー不要のツールに加えて commercebook_buy、commercebook_requests、commercebook_result_sheets、commercebook_agent_rules を利用できます。
• 販売者：https://seller.commercebook.ai の販売者ポータル。販売者キーでは commercebook_seller_products、commercebook_seller_orders、commercebook_seller_shipping、commercebook_seller_requests、commercebook_seller_money、commercebook_seller_account が追加されます。
• 倉庫：https://warehouse.commercebook.ai のワークスペース。倉庫キーでは commercebook_leads、commercebook_crm、commercebook_costs、commercebook_network、commercebook_messages、commercebook_warehouse_profile、commercebook_warehouse_account が追加されます。

tools/list はキーの種別（または指定されたロール）に応じたツールを返し、各アクションの行にはそのアクティビティが記載されています。キーの種別に応じたブリーフィングは commercebook_start が返します。購入者、販売者、倉庫向けのブリーフィングは https://commercebook.ai/docs/briefing/buyer.md、seller.md、warehouse.md にあります。

エラー

拒否された場合は、API のコード、詳細、HTTP ステータスを含むエラー結果が返されます。たとえば、not_permitted（アクティビティとヒントを含む）、rate_limited、summary_names_shipper（リードの要件テキストに配送業者名が記載されている場合）などです。各エンドポイントのコードは、https://commercebook.ai/api/v1/openapi.json の OpenAPI ドキュメントに記載されています。

ソースからビルドする

npm install
npm run build
npm run smoke

スモークテストには COMMERCEBOOK_API_KEY が必要です。別の API を使う場合は COMMERCEBOOK_BASE を指定できます。たとえば、http://127.0.0.1:4229/.netlify/functions/api で実行するローカル関数サーバーを指定できます。テストではツールを一覧表示し、アクション whoami で commercebook_start を呼び出します。また、キーを含まない JSON を 1 行出力します。

ライセンス

MIT。セキュリティに関する報告先：[email protected]。