ApparelHub

@apparelhub/mcp-server

工作流级别的 MCP 工具，让 AI Agent 能够端到端地运营 ApparelHub 商店：完成设置、设计服饰、构建产品、在各个销售渠道上架，并处理后续订单和商品信息。每个工具都封装了 ApparelHub Agent API，并融入平台经过实践检验的生产经验，让 Agent 无需自行摸索各种注意事项，就能直接获得正确的行为。

有两种运行方式：通过 OAuth 授权的托管连接器（推荐，无需处理 API 密钥），以及自行运行的 npm 包（需要密钥）。两者提供完全相同的工具接口。

状态：抢先体验。 npm 包目前处于 1.0 之前的阶段，接口仍在逐步稳定。面向 Agent 的工具接口为 v1，这是我们承诺保持稳定的契约（请参阅 CHANGELOG.md 和版本控制与稳定性）。

有何不同

对 REST API 的简单封装只是给 HTTP 调用换个名字。这些工具位于工作流级别：一次 ship_product 调用即可解析变体、生成并等待样图（一直等到图像实际发布）、使用正确的字段名称创建产品、添加所有变体、将产品关联到商店，并按正确顺序同步到履约服务和各个渠道；过程中还会拒绝负利润定价，并警告已知的变体陷阱。这些实践经验都写在代码里，而不是留给 Agent 在上下文中自行摸索。

连接

建议使用托管连接器。 授权后会为你配置 API 密钥，因此无需创建、粘贴、轮换凭据，也不必担心密钥泄露到配置文件中。只有在客户端无法连接远程 MCP 或使用 OAuth，或者你明确希望服务运行在自己的机器上时，才需要自行运行软件包。

	托管连接器（OAuth）	自行运行的软件包（API 密钥）
凭据	批准后为你配置	你自行创建并粘贴 API 密钥
本地前置条件	无	Node.js 20+、Python 3 + Pillow，可选安装 tesseract
传输方式	基于 HTTP 的远程 MCP	stdio
适用场景	支持远程 MCP 的任何客户端	不支持远程连接或 OAuth 的客户端、本地控制、开发

推荐：托管连接器

https://mcp.apparelhub.ai

将该 URL 添加到任何支持远程服务的 MCP 客户端，登录 ApparelHub 并批准即可。你无需处理 API 密钥。 批准授权后，系统会在你的账户中配置一个连接器密钥（或重复使用已有密钥），托管服务会在每次调用时将你的会话映射到该密钥。无需粘贴，无需手动轮换，也不会有密钥存放在 dotfile 中。

托管服务还包含设计和质量工具所需的图像处理工具链，因此透明色键、图像统计和 OCR 全都可以完全不依赖本地组件：无需 Node、Python、Pillow 或 tesseract。

Claude Code

claude mcp add --transport http apparelhub https://mcp.apparelhub.ai

然后运行 /mcp 并选择 Authenticate。

任何读取 MCP 配置文件的客户端

{
  "mcpServers": {
    "apparelhub": {
      "type": "http",
      "url": "https://mcp.apparelhub.ai"
    }
  }
}

claude.ai — 在 Settings → Connectors 下将其添加为自定义连接器，粘贴相同的 URL，然后按提示授权。

上面的裸域名是服务的规范地址：它是自身 OAuth 元数据公布的 resource 标识符。路径不会参与路由，因此现有配置若指向 https://mcp.apparelhub.ai/mcp，仍可正常使用，无需更改。

握手实际执行的操作

这是标准的 OAuth 2.1，无需你进行任何特殊配置。客户端会从 /.well-known/oauth-protected-resource（RFC 9728）发现授权服务器，动态注册自身，并针对 https://api.apparelhub.ai 的 mcp 作用域运行带 PKCE（S256）的授权码流程。支持刷新令牌和撤销。访问令牌是不透明的：托管服务会在服务器端将你的令牌兑换为连接器密钥，因此密钥不会出现在你的客户端、配置文件或聊天记录中。

密钥槽位与撤销

每个账户会生成一个连接器密钥，并在你授权的所有聊天界面中共用；该密钥会占用套餐的 API 密钥额度。免费套餐包含一个 API 访问槽位，因此如果该槽位已被自助创建的密钥占用，授权页面会提示这一情况，并提供释放槽位或升级套餐的选项。要撤销授权，请在持有授权的客户端中断开连接，或前往 https://apparelhub.ai/developer/api-keys 删除连接器密钥。

其他方案：自行运行软件包

要求：

• Node.js 20+。
• ApparelHub 账户和 API 密钥——可前往 https://apparelhub.ai/developer/api-keys 生成。
• 仅设计和质量工具需要：安装了 Pillow 的 Python 3（透明背景抠图、图像质检），以及可选的 tesseract（OCR 文本检测）。这些工具在本地运行；如果缺少依赖，工具会清楚提示你需要安装什么，且不会崩溃。

服务启动时会从 APPARELHUB_API_KEY 环境变量读取密钥，并通过 stdio 使用 MCP。它不会接受作为工具参数传入的密钥，并且 API 主机地址是固定的（不可覆盖）。

Claude Code

// ~/.claude/mcp.json (or a project .mcp.json)
{
  "mcpServers": {
    "apparelhub": {
      "command": "npx",
      "args": ["-y", "@apparelhub/mcp-server"],
      "env": { "APPARELHUB_API_KEY": "your-key-here" }
    }
  }
}

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "apparelhub": {
      "command": "npx",
      "args": ["-y", "@apparelhub/mcp-server"],
      "env": { "APPARELHUB_API_KEY": "your-key-here" }
    }
  }
}

Aider

# .aider.conf.yml
mcp-servers:
  apparelhub:
    command: npx
    args: ["-y", "@apparelhub/mcp-server"]
    env:
      APPARELHUB_API_KEY: your-key-here

其他任何 MCP 客户端

用法都相同：在环境中设置 APPARELHUB_API_KEY，然后运行 npx -y @apparelhub/mcp-server。

环境变量

变量	用途
APPARELHUB_API_KEY	必需。 你的 ApparelHub API 密钥。使用托管连接器时无需设置。
APPARELHUB_MCP_TELEMETRY	设为 off 可禁用粗粒度使用情况信号（参见隐私）。
APPARELHUB_MCP_PYTHON	本地图像工具所用 Python 3 解释器的路径（默认为 python3）。

工具

共有 127 个工具。 docs/TOOLS.md 介绍了核心工具组；要获取权威的实时架构，请从你的 Agent 调用 tools/list。

• 设置并连接 — check_setup_readiness（查看账户已具备的条件、所需条件以及唯一的下一步操作）、list_connectable_providers、connect_fulfillment_provider 和 connect_sales_channel（完全在聊天中连接的 API 令牌服务商），以及用于基于浏览器连接的服务（Printful、Shopify、TikTok Shop、Fourthwall）的 start_channel_connect / check_connection_status。
• 读取 — list_my_workspaces、list_my_stores、list_my_designs、get_design_collection、list_my_products、list_my_orders、get_order_details。
• 目录 — browse_catalog、get_garment_details、find_garments（一次搜索所有已连接的服务商，查找符合某项能力的商品）、recommend_garment、list_catalog_providers。
• 设计 — design_apparel、iterate_design、upload_design（上传商家已有的作品）、fit_aspect（免费调整形状）、设计生命周期操作（archive_design、restore_design、delete_design），以及拆分式基础工具 generate_image、process_transparency、verify_design_text。
• 商品 — ship_product、update_product、delete_product、unsync_from_channel、diagnose_tiktok_listings，以及拆分式基础工具 create_product、add_variants、sync_to_fulfillment、sync_to_channel。
• 订单 — 生命周期操作（approve_order、unapprove_order、hold_order、cancel_order、confirm_order、submit_order_to_fulfillment、check_order_status、reconcile_order）、草稿编辑（add_order_item、remove_order_item）以及设计审批暂停操作（list_order_holds、approve_order_hold、request_hold_changes）。
• 履约问题 — report_fulfillment_issue（报告订单商品缺陷）、list_fulfillment_issues（按订单或整个工作区查看收件箱）、check_fulfillment_issue（查看完整问题详情及可提交给服务商的问题报告）、resolve_fulfillment_issue（记录向服务商提交的问题、以解决方案关闭问题，或创建替换订单）。
• 销售渠道情报 — 销售渠道自身报告的信息及可在渠道上设置的内容：channel_performance、channel_opportunities、channel_coverage、listing_changes（确认上次编辑是否生效）、describe_listing_attributes、set_listing_attributes、set_channel_settings、import_size_measurements。
• 目录导入（跟踪的商品列表） — 以只读方式导入商家已在渠道销售的商品：import_channel_catalog（启动导入；如果已有运行中的导入，则返回该任务）、get_catalog_import_run（查询状态）、list_tracked_listings（查看商品列表，以及每个渠道的 catalog_read 和最近一次运行记录）。不会向商家的店铺写入任何内容，这些商品也会照常发货。支持 Shopify、WooCommerce、Wix 和 TikTok Shop。若要让 ApparelHub 履约其中一件商品，可通过 bind_tracked_listing 将其绑定到 ApparelHub 商品（不会更改商家的商品列表）；unbind_tracked_listing 可撤销绑定。
• 分析 — analytics_summary、analytics_timeseries、analytics_breakdown、analytics_ops、analytics_portfolio。
• 系列 — list_collections、get_collection、create_collection、update_collection、delete_collection、add_products_to_collection、remove_product_from_collection、sync_collection。
• 跨工作区转移 — copy_product_to_workspace、move_product_to_workspace、check_product_move，以及对应的设计工具。
• 工作区与团队管理（代理机构 / Enterprise，账户级密钥）— 工作区（create_workspace、update_workspace、delete_workspace、check_workspace_deletion、assign_workspace_member、unassign_workspace_member、move_store_to_workspace、get_role_matrix）和团队（get_account_overview、list_account_members、remove_member、invite_member、list_invites、revoke_invite、resend_invite、accept_invite）。
• 店铺与订单管理 — 店铺设置/生命周期（get_store_settings、update_store_settings、create_store、archive_store、unarchive_store、activate_store）、订单付款/运营（record_order_payment、mark_order_no_payment、set_order_payment_method、sync_orders、estimate_order_costs、get_orders_summary、list_pending_fulfillments），以及 archive_product / restore_product。
• 行动系统 — analyze_what_works、auto_optimize_listings、cascade_price_change、set_prices_by_margin、recover_from_outage。
• 安全 — verify_design_quality、verify_mockup_quality、check_design_compliance。
• API 备用入口 — get_api_reference（通过实时 OpenAPI 规范查找完整的 Agent API）和 api_request（在没有合适专用工具时调用任何 /agents/v1 端点）。 读取工具为只读。产品与设计工具默认仅创建草稿，不会直接上线，会强制执行定价底线，并防范已知的变体陷阱。行动系统的变更默认先进行试运行，应用时只执行安全操作（归档，绝不删除）。每个产品、订单和店铺结果都会带有指向 apparelhub.ai 的 view_url。错误会以统一格式返回（{error: {code, message, retry_after?, suggestion?}}）——工具绝不会跨越 MCP 边界抛出异常。

get_api_reference 还会报告你实际连接的服务所提供的内容——其版本、工具数量和所有工具名称——这样 Agent 就能区分“该工具不存在”和“我缓存的工具列表已过时”，而不必猜测。

隐私

可选的粗粒度使用信号有助于改进工具。它只会发送非识别性特征——工具名称、结果、延迟、错误代码，以及严格允许列表中的粗粒度字段（例如 AI 来源名称、服装类别）。它绝不会发送提示词、图片、ID、URL 或客户数据。信号会缓冲并以即发即弃方式发送（绝不会影响工具调用）。将 APPARELHUB_MCP_TELEMETRY=off 设置为完全关闭。

托管连接器还会为每个请求记录一项运行指标（结果、延迟；对于工具调用，还包括工具名称）。该指标不包含任何身份维度或用户数据。

Skill、MCP 与配方

ApparelHub 以三种形式提供 Agent 功能：

• markdown skill 是在 Claude Code 中使用 ApparelHub 最轻松的方式——它直接向 Agent 传授 REST API 和设计规则。
• 这个 MCP 服务将这些知识转化为类型化、可调用的工具接口（包含行动系统工具），适用于任何支持 MCP 的 Agent；通过托管连接器，也可用于无法运行 Skill 或本地进程的聊天界面。
• 配方 是端到端的运营蓝图，可放入 Agent 的运行时：Agent 遵循的章程、跨运行周期保留的记忆模型，以及启动它的提示词。配方会调用这套工具接口，并默认启用资金与上线门槛。

若要在 Claude Code 中快速上手，请使用 Skill；若需要类型化工具、更高阶的工作流，或使用 Claude Code 以外的客户端，请使用 MCP 服务；若希望 Agent 运行完整的店铺运营模式，而非一次只处理一个请求，请使用配方。

开发

npm ci
npm run build      # tsc -> dist/
npm run typecheck
npm run lint
npm test           # vitest

图像工具会调用 python/ 中捆绑的 Python 脚本；图像处理层可注入，因此工具编排可通过伪造对象进行单元测试，而脚本则直接进行冒烟测试。

版本控制与稳定性

工具接口单独于软件包进行版本控制（当前为 v1）。底层 REST API 演进时，服务会在内部进行适配——面向 Agent 的工具名称和结构保持稳定。这一契约让你只需安装一次，就能持续使用。软件包发行版遵循语义化版本；请参阅 docs/RELEASING.md。

使用托管连接器时，你始终使用当前版本，这也是优先选择它的另一个原因：无需升级，便会有新工具可用。客户端会缓存工具列表；如果怀疑列表已过时，请查询 get_api_reference。

许可证

MIT © ApparelHub。请参阅 LICENSE。