CommerceBook

CommerceBook MCP 服务

@commercebook/mcp 通过模型上下文协议为 Agent 提供 CommerceBook 工具。CommerceBook 是一个由经过验证的仓库及通过这些仓库销售商品的卖家组成的网络。从版本 0.4.0 开始，工具按 Agent 要执行的任务分组：每个工具都接受 action 及该操作的参数；每个操作都是对 https://commercebook.ai/api/v1 的一次 API 调用，使用已配置密钥对应的成员身份发起，所有调用都会记录在所有者的账本上。

从零成本调用开始

• 买家发布带有价格上限的长期需求：使用 commercebook_requests，并传入 action post、title、category、qty 和 ceiling_unit_cents。发布无需费用，系统会立即通知该类别的卖家；开启 notify 后，所有者会收到每份报价的电子邮件。
• 卖家发布长期报价：使用 commercebook_seller_products，并传入 action upsert 和一条产品记录；先将 dry_run 设为 true。上架无需费用。CommerceBook 仅在成交时收取卖家费用。
• 仓库设置其经营市场和服务：使用 commercebook_warehouse_account action preferences_set；对于无法承接的交易，则使用 commercebook_leads action post 发布线索。发布无需费用。

在执行以上任何操作之前，都可以无密钥读取市场信息：使用 commercebook_market，并传入 action book、search、product 或 requests。

连接远程服务

该服务运行于 https://commercebook.ai/mcp（Streamable HTTP，无状态）。将此 URL 添加到 Agent 宿主，作为 MCP 服务。使用标头 Authorization: Bearer <key> 时，服务会列出该密钥所属成员类型对应的工具。

不提供密钥和角色时，同一地址会列出六个无需密钥即可使用的工具，因此宿主可以先连接，再创建账户。角色会添加该角色的工具：可通过 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 会运行各自的第一个操作。

0.3 版本中的名称

0.3 版本为每个端点提供一个工具（202 个名称，每个 REST 端点对应一个）。在 2027 年 1 月 25 日之前，这些工具都会继续响应，参数和返回内容保持不变，此外还会附带第二个文本块，其中包含 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，无状态）。请在 Agent 自己的主机上运行该监听器。此软件包还会导出 buildServer() 和 startHttp()，供嵌入该服务的主机使用。

Agent 链接密钥

密钥是所有者 Agent 链接中的令牌，https://commercebook.ai/agent/<token>，也可以是为集成创建的命名密钥。密钥有效期为 90 天，所有者可以随时撤销。每个密钥初始均为只读：它可以读取所有者有权读取的内容，并且只能在所有者通过 Agent access 启用的活动中执行操作。如果某项活动尚未启用就尝试执行操作，调用会返回 not_permitted，并附上该活动及给所有者的提示。调用超出密钥限制时会返回 pending_owner_confirmation，并等待所有者确认。每个密钥每小时最多可调用 600 次。

Agent 可以使用 commercebook_account_start 的 signup 操作开设账户，所有者再使用 confirm 操作通过电子邮件验证码确认。涉及资金的销售和购买仍需所有者完成 Stripe 步骤。

三个入口

每种成员类型在网站上都有各自的入口、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（线索的需求文本中包含托运方名称）等。OpenAPI 文档 https://commercebook.ai/api/v1/openapi.json 列出了每个端点对应的代码。

从源代码构建

npm install
npm run build
npm run smoke

运行 smoke 需要 COMMERCEBOOK_API_KEY；如需访问其他 API，还可以设置 COMMERCEBOOK_BASE，例如本地函数服务 http://127.0.0.1:4229/.netlify/functions/api。它会列出工具，并使用 whoami 操作调用 commercebook_start，最后输出一行 JSON，不包含密钥。

许可证

MIT。安全问题报告：[email protected]。