ApparelHub

@apparelhub/mcp-server

AI エージェントが ApparelHub ストアを最初から最後まで運営できるワークフローレベルのMCPツールです。ストアのセットアップ、アパレルのデザイン、商品の作成、販売チャネルへの掲載、そして届いた注文や掲載商品の管理を行えます。各ツールはApparelHub Agent APIをラップし、プラットフォームで培われた本番環境での知見を組み込んでいるため、エージェントは落とし穴を自分で学ばなくても、適切な動作をすぐに実現できます。

実行方法は2つあります。OAuth で認証するホステッドコネクター（推奨、API キーの取り扱い不要）と、自分で実行するこの npm パッケージ（API キーが必要）です。どちらも同一のツールセットを提供します。

ステータス：早期アクセス。 npm パッケージは、ツールセットの安定化に向けて 1.0 未満です。エージェント向けのツールセットは v1 であり、安定して維持する契約です（CHANGELOG.mdとバージョン管理を参照）。

何が違うのか

REST API を薄くラップしただけのものは、HTTP 呼び出しの名前を変えているにすぎません。これらのツールはワークフローレベルです。1 回の ship_product 呼び出しで、バリエーションを解決し、モックアップを生成して待機し（画像が実際に公開されるまで待ちます）、適切なフィールド名で商品を作成し、すべてのバリエーションを追加して、ストアに関連付け、正しい順序でフルフィルメントと販売チャネルに同期します。その過程で、利益率がマイナスになる価格設定を拒否し、既知のバリエーションに関する落とし穴を警告します。苦労して得た知見は、エージェントのコンテキストではなくコードに組み込まれています。

接続

ホステッドコネクターをおすすめします。 認証すると 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 キーを扱う必要は一切ありません。 承認すると、アカウントにコネクターキーが用意され（すでにある場合は再利用され）、ホステッドサーバーは呼び出しのたびにセッションをそのキーに解決します。貼り付けるものも、手動でローテーションするものも、ドットファイルに保存されるものもありません。

ホステッドサーバーには、デザインツールと品質ツールが必要とする画像処理ツールチェーンも含まれているため、透明部分のキーイング、画像統計、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 を貼り付けて、プロンプトが表示されたら認証してください。

上記のベース 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）を使った認可コードフローを実行します。リフレッシュトークンとトークンの失効にも対応しています。アクセストークンは不透明です。ホステッドサーバーがサーバー側でアクセストークンをコネクターキーに交換するため、キーがクライアント、設定、チャット履歴に保存されることはありません。

キースロットと取り消し

アカウントごとにコネクターキーが1つ発行され、許可したすべてのチャット画面で共有されます。このキーは、プランの API キー枠を1つ使用します。Free プランには API アクセス用の枠が1つ含まれているため、その枠がセルフサービスキーによってすでに使用されている場合、同意画面にその旨が表示され、枠を空けるかアップグレードするかを選べます。取り消すには、許可を受けているクライアントから接続を解除するか、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 では主要なグループについて説明しています。正式な最新スキーマを確認するには、エージェントから 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 に対応しています。そのうち 1 つを 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 と、デザインに関する同等のツール。
• ワークスペースとチームの管理（agency / 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 仕様からエージェント API 全体を確認）と api_request（専用ツールが適さない場合に、任意の /agents/v1 エンドポイントを呼び出す）。 読み取りツールは読み取り専用です。商品・デザインツールはデフォルトで下書きのまま公開されず、価格の下限を適用し、既知のバリエーションの落とし穴を防ぎます。アクション実行システムの変更はデフォルトでドライランとなり、適用時も安全な操作（削除ではなくアーカイブ）のみを行います。すべての商品／注文／ストアの結果には、apparelhub.ai に戻る view_url が含まれます。エラーは一貫した形式（{error: {code, message, retry_after?, suggestion?}}）で返されます。ツールが MCP の境界を越えて例外をスローすることはありません。

get_api_reference は、実際に接続しているサーバーが提供するもの（バージョン、ツールの数、すべてのツール名）も報告するため、エージェントは推測に頼らず、「そのツールは存在しない」のか「キャッシュされたツール一覧が古い」のかを判別できます。

プライバシー

任意の粗い使用状況シグナルを送信して、ツールの改善に役立てることができます。送信されるのは、ツール名、結果、レイテンシ、エラーコード、および許可リストで厳密に制限された粗いフィールド（AI のソース名、衣料品カテゴリーなど）といった、個人を特定しない情報のみです。プロンプト、画像、ID、URL、顧客データは決して送信されません。データはバッファーに保存され、結果を待たずに送信されます（ツール呼び出しに影響することはありません）。APPARELHUB_MCP_TELEMETRY=off を設定すると、完全に無効にできます。

ホステッドコネクターは、リクエストごとに運用メトリクス（結果、レイテンシ、ツール呼び出しの場合はツール名）も記録します。個人識別情報に関するディメンションやユーザーデータは含まれません。

スキル、MCP、レシピの違い

ApparelHub は、エージェント向け機能を次の3つの形式で提供します。

• **Markdown スキル**は、Claude Code から ApparelHub を使う最も手軽な方法です。REST API とデザインルールをエージェントに直接教えます。
• この MCP サーバーは、その知識を型付きで呼び出し可能なツール群（アクション実行システムのツールを含む）に変換します。MCP 対応のあらゆるエージェントで利用でき、ホステッドコネクターを通じて、スキルやローカルプロセスを実行できないチャット環境からも利用できます。
• **レシピ**は、エージェントの実行環境に導入するエンドツーエンドの運用設計図です。エージェントが従う規範、実行をまたいで保持するメモリモデル、そして起動用のプロンプトが含まれています。これらはこのツール群を使用し、金銭に関する制限と公開前のゲートがデフォルトで有効になっています。

Claude Code ですぐに使い始めるならスキルを、型付きツール、より高度なワークフロー、または Claude Code 以外のクライアントが必要なら MCP サーバーを、個々のリクエストに答えるのではなく、ストア全体の運用パターンをエージェントに実行させるならレシピを使ってください。

開発

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

画像ツールは、バンドルされた python/ 内の Python スクリプトを起動します。画像処理レイヤーは差し替え可能なため、ツールのオーケストレーションはフェイクを使って単体テストし、スクリプトは直接スモークテストできます。

バージョン管理と安定性

ツール群はパッケージとは別にバージョン管理されています（現在は v1 です）。基盤となる REST API が進化しても、サーバーが内部で対応するため、エージェント向けのツール名と形式は変わりません。これが、一度インストールすればそのまま使い続けられるという保証です。パッケージのリリースにはセマンティックバージョニングを採用しています。詳しくは docs/RELEASING.md をご覧ください。

ホステッドコネクターでは常に最新バージョンを利用できるため、新しいツールが登場してもアップグレードは不要です。クライアントはツール一覧をキャッシュするため、手元の一覧が古くなっていると思われる場合は get_api_reference を実行してください。

ライセンス

MIT © ApparelHub。詳しくは LICENSE をご覧ください。