mcpField
C
commercetools-platform

commercetools-platform

github.com/commercetools開発6103 回インストール6 日前に更新
リポジトリ

commercetools-platform について

commercetools APIをTypeScriptから利用する開発者向けのスキルです。最新ドキュメント検索を必須とし、ローカル資料やスキーマ取得スクリプトを組み合わせて実装を案内します。

主な機能

  1. 01最新ドキュメントの必須検索
  2. 02SDKセットアップ案内
  3. 03商品検索の例
  4. 04GraphQLスキーマの取得
  5. 05OpenAPIスキーマの取得

活用シーン

  1. 01commercetools用TypeScriptクライアントの設定
  2. 02商品検索クエリの作成
  3. 03GraphQLリソーススキーマの確認
  4. 04REST操作とペイロードの検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/commercetools/commercetools-ai-plugins --skill commercetools-platform

インストール後、Claude Code で/commercetools-platformを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
product-search.md
sdk-setup.md
scripts/
docs-search.mjs
graphql-schemata.mjs
openApi-schemata.mjs

詳細

commercetools TypeScript SDK

TypeScript から commercetools API に接続するための基本パターンです。これらのパターンはプロジェクトの種類に依存しません。Next.js のストアフロント、サーバーレス関数、CLI スクリプトのいずれを構築する場合にも適用できます。

ワークフロー

このスキルが呼び出されたら、必ず次の手順に従ってください。

  1. ドキュメント検索（必須、最初に実行） — このスキルをセッションで初めて使用するときは、回答する前にこれを実行する必要があります。このスキルが対象とする製品に絞り込んだ、最新の検証済みドキュメントを収集し、回答の主な根拠とします。このスキルの作業中は、ドキュメント検索にこのスクリプトを使用してください。それ以外の内容は Knowledge MCP で確認できます。スキルのテキストだけでなく、取得したドキュメントで必ず詳細を確認してください。

    node "<this skill's directory>/scripts/docs-search.mjs" \
  --query "<extract key terms from user's question>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>" \
  --commercetools-project-key "<if known>" \
  --commercetools-region "<if known>" \
  --limit 10

    commercetools のプロジェクトキーとリージョン（api.{region}.commercetools.com の形式）は、コンテキストにすでに含まれている場合に限り指定してください。それ以外の場合は、どちらも省略してください。ファイルを検索したり、ユーザーに尋ねたりしないでください。

  2. スキルのリファレンスと組み合わせる — 分析結果を ./references/ 内のローカルリファレンスと照合し、完全なコンテキストを得ます。

  3. 実装ガイダンスを提供する — ドキュメントの内容を、ユーザーが対象としている具体的な統合方式に合わせてまとめます。

オプションのスクリプト

GraphQL スキーマを取得する — commercetools の GraphQL クエリまたはミューテーションに関するコンテキストが必要な場合に実行します。たとえば、クエリを作成する前にリソースのフィールド、型、利用可能な操作を確認したり、生成した GraphQL クエリ／ミューテーションを実際のスキーマに照らして検証したりする場合です。単一の commercetools リソースの部分的な GraphQL SDL を取得します。

node scripts/graphql-schemata.mjs \
  --resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

出力は、そのリソースの GraphQL SDL です。リソース名が認識されない場合、スクリプトは有効なリソース名の一覧を表示します。正しい名前を選び、再実行してください。注： SDL にはスタブ型が含まれる場合があります。これは、参照先のリソースをスタブとして表現したもので、実際の型名はコメントに記載されています。必要な型があれば、その型名を --resource-name として指定してこのスクリプトを再実行し、個別に取得してください。

OpenAPI（REST）スキーマを取得する — commercetools の REST エンドポイント、リクエスト／レスポンスのペイロード、または更新アクションに関するコンテキストが必要な場合に実行します。たとえば、リクエストを作成する前にリソースの REST 操作を確認したり、生成した REST リクエスト／ペイロードを実際の仕様に照らして検証したりする場合です。単一の commercetools リソースの部分的な OpenAPI 仕様を取得します。

node scripts/openApi-schemata.mjs \
  --resource-name "<commercetools resource, e.g. api-Cart-write, api-Customer-read, checkout-Application>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

出力は、そのリソースの OpenAPI 仕様（YAML）です。REST リソース名は、読み取り／書き込みを分けた形式（例：api-Cart-read、api-Cart-write）を使用します。リソース名が認識されない場合、スクリプトは有効なリソース名の一覧を表示します。正しい名前を選び、再実行してください。注： 仕様には参照先の展開スキーマは含まれません。参照先リソースを指定してこのスクリプトを再実行し、そのスキーマを個別に取得してください。

SDK のセットアップ

以下については、sdk-setup.md を参照してください。

  • パッケージのインストール（@commercetools/platform-sdk + @commercetools/ts-client）
  • Client Credentials フローを使用する ClientBuilder シングルトン
  • 必須の環境変数とリージョン別の認証 URL
  • 必須の API クライアントスコープ

商品検索 API

以下については、product-search.md を参照してください。

  • 公式ドキュメントと、旧式の productProjections 検索が非推奨である理由
  • 全文検索 + フィルター + 並べ替え + ファセットの例
  • カテゴリーフィルター、SKU 検索、価格選択、割引の展開、BOPIS チャネルフィルタリング

コメント

Markdown 対応