Sfcc Dev MCP

🚀 SFCC Development MCP Server

このMCPサーバーは、Salesforce B2C Commerce Cloudの開発機能に包括的にアクセスできるようにするツールです。AIエージェントがSFCCの開発タスク（ログ分析、デバッグ、モニタリング、SFCCドキュメントの照会など）を支援できるようになります。

🚀 クイックスタート

Claude Desktopやその他のMCPクライアントでこのMCPサーバーを使用するには、MCP設定ファイルに以下を追加します。

ドキュメントのみモード（SFCCの資格情報は不要）

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp"]
    }
  }
}

フルモード（ログ分析やシステムオブジェクトツールを使用するためのSFCCの資格情報が必要）

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/your/dw.json"]
    }
  }
}

フルモードの場合

SFCCの資格情報を含むdw.jsonファイルを作成します。

{
  "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
  "username": "your-username",
  "password": "your-password",
  "client-id": "your-client-id",
  "client-secret": "your-client-secret"
}

モード別利用可能なツール

すぐに始める: このサーバーは資格情報なしでも動作します。npx sfcc-dev-mcpを使用して、すべてのドキュメントとベストプラクティスツールにアクセスできます！

✨ 主な機能

SFCCベストプラクティスガイド

• 利用可能なガイドの取得: カートリッジ作成、ISMLテンプレート、OCAPIフック、SCAPIフック、SFRAコントローラー、カスタムSCAPIエンドポイントなど、すべての利用可能なSFCCベストプラクティスガイドをリストします。
• 完全なガイドの取得: 特定のSFCC開発領域の構造化された内容を持つ包括的なベストプラクティスガイドを取得します。新しいISMLテンプレートガイドには、セキュリティ、パフォーマンス、保守性のガイドラインが含まれています。
• ベストプラクティスの検索: すべてのベストプラクティスガイドを対象に、特定の用語、概念、またはパターンを検索します。ISML固有のトピック（エンコーディング、XSS防止、テンプレートアーキテクチャなど）も検索できます。
• フックリファレンスの取得: OCAPIおよびSCAPIフックの詳細なフックリファレンステーブルにアクセスします。

SFCCドキュメント照会

• クラス情報の取得: 任意のSFCCクラスの詳細情報（プロパティ、メソッド、説明など）を取得します。
• クラスの検索: 名前でSFCCクラスを検索します。部分一致もサポートします。
• クラスメソッドの取得: 特定のSFCCクラスのすべてのメソッドをリストします。
• クラスプロパティの取得: 特定のSFCCクラスのすべてのプロパティをリストします。型と修飾子も表示されます。
• メソッドの検索: すべてのSFCCクラスを対象に、特定のメソッドを検索します。
• すべてのクラスのリスト: 利用可能なすべてのSFCCクラスの完全なリストを取得します。
• 生のドキュメントの取得: 任意のクラスの完全なMarkdownドキュメントにアクセスします。

SFRAドキュメントアクセス

• 利用可能なSFRAドキュメントのリスト: すべての利用可能なSFRA（ストアフロントリファレンスアーキテクチャ）ドキュメント（サーバー、リクエスト、レスポンス、クエリ文字列、レンダリングモジュールなど）をリストします。
• SFRAドキュメントの取得: 特定のSFRAクラスまたはモジュールの完全なドキュメントを取得します。プロパティ、メソッド、使用例の詳細情報が含まれています。
• SFRAドキュメントの検索: すべてのSFRAドキュメントを対象に、特定の用語、概念、または機能（ルーティング、ミドルウェア、リクエスト処理、レスポンス管理など）を検索します。
• SFRAクラスメソッドの取得: 特定のSFRAクラス（サーバー、リクエスト、レスポンス、クエリ文字列）のすべてのメソッドを取得します。詳細なシグネチャ、パラメーター、説明が含まれています。
• SFRAクラスプロパティの取得: 特定のSFRAクラスのすべてのプロパティを取得します。型と説明が含まれており、リクエスト/レスポンスオブジェクトやコントローラー内のSFRAクラスのプロパティを理解するのに役立ちます。

SFCCシステムオブジェクト定義

• すべてのシステムオブジェクトの取得: すべてのシステムオブジェクト定義の完全なリストを取得します。メタデータ（属性数など）も含まれています。
• システムオブジェクト定義の取得: 特定のシステムオブジェクト（製品、顧客、注文など）の詳細情報を取得します。すべての属性が含まれています。
• システムオブジェクト属性定義の検索: 複雑なクエリを使用して、特定のシステムオブジェクトタイプ内の特定の属性定義を検索します。ID、表示名、説明のテキスト検索、必須、検索可能、システムなどのプロパティによるフィルタリング、ソートをサポートしています。カスタム属性や特定の特性を持つ属性を見つけるのに役立ちます。オブジェクトのすべての属性を取得するには、match_all_queryを使用します。
• サイト設定の検索: 指定された設定グループとインスタンス内のサイト設定を検索します。カスタムサイト設定を見つける、設定構成を理解する、またはサイト固有の設定を操作する際に重要です。テキスト検索、フィルタリング、ソートを含む複雑なクエリをサポートしています。
• システムオブジェクト属性グループの検索: 特定のシステムオブジェクトタイプの属性グループを検索します。サイト設定検索APIに必要なサイト設定グループを見つけるのに重要です（オブジェクトタイプとしてSitePreferencesを使用）。グループプロパティのテキスト検索、フィルタリング、ソートを含む複雑なクエリをサポートしています。
• カスタムオブジェクト属性定義の検索: 複雑なクエリを使用して、特定のカスタムオブジェクトタイプ内の特定の属性定義を検索します。システムオブジェクトではなく、カスタムオブジェクト（ユーザー定義のデータ構造）に使用します。ID、表示名、説明のテキスト検索、必須、検索可能、システムなどのプロパティによるフィルタリング、ソートをサポートしています。カスタムオブジェクト定義内のカスタム属性や特定の特性を持つ属性を見つけるのに役立ちます。

注: システムオブジェクト定義ツールにはOAuth資格情報（clientIdとclientSecret）が必要で、標準のSFCCオブジェクトに追加されたカスタム属性やサイト設定を見つけるのに役立ちます。

ログ分析とモニタリング

• 最新のエラーの取得: SFCCログから最新のエラーメッセージを取得します。
• 最新の警告の取得: 最近の警告メッセージを取得します。
• 最新の情報の取得: 最近の情報レベルのログエントリーにアクセスします。
• ログの要約: エラー数や主要な問題を含むログアクティビティの概要を取得します。
• ログの検索: ログファイル全体で特定のパターンを検索します。
• ログファイルのリスト: 利用可能なログファイルとそのメタデータを表示します。

📦 インストール

1. このリポジトリをクローンします。
2. 依存関係をインストールします。

   npm install
   

3. TypeScriptコードをビルドします。

   npm run build
   

💻 使用例

基本的な使用法

Claude Desktopやその他のMCPクライアントでこのMCPサーバーを使用するには、MCP設定ファイルに以下を追加します。

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp"]
    }
  }
}

高度な使用法

フルモードで使用する場合は、dw.jsonファイルを指定します。

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/your/dw.json"]
    }
  }
}

📚 ドキュメント

作業ディレクトリのオーバーライド

サーバーは、現在の作業ディレクトリ（cwd）を使用してドキュメントファイルを検索します。デフォルトでは、サーバーが起動されたディレクトリ内のdocs/フォルダを期待しています。別の場所のドキュメントを使用する必要がある場合は、いくつかのオプションがあります。

オプション1: 正しいディレクトリからサーバーを起動する

cd /path/to/sfcc-dev-mcp
npx sfcc-dev-mcp

オプション2: --cwdフラグを使用する（MCPクライアントがサポートしている場合）

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp"],
      "cwd": "/path/to/sfcc-dev-mcp"
    }
  }
}

オプション3: シンボリックリンクを作成する

# 希望の場所にdocsフォルダへのシンボリックリンクを作成する
ln -s /path/to/sfcc-dev-mcp/docs /your/desired/location/docs
cd /your/desired/location
npx sfcc-dev-mcp

期待されるディレクトリ構造

サーバーは、作業ディレクトリに対して以下の構造を期待しています。

./docs/
├── best-practices/
│   ├── cartridge_creation.md
│   ├── ocapi_hooks.md
│   ├── scapi_hooks.md
│   └── ...
├── sfra/
│   ├── server.md
│   ├── request.md
│   ├── response.md
│   ├── querystring.md
│   └── render.md
├── dw_catalog/
├── dw_order/
└── ... (その他のSFCCクラスドキュメントフォルダ)

dw.jsonの使用（推奨）

サーバーは、Commerce Cloud開発ツールで使用される標準のSFCC dw.json構成形式をサポートしています。プロジェクトルートにdw.jsonファイルを作成します。

{
  "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
  "username": "your-username",
  "password": "your-password",
  "client-id": "your-client-id",
  "client-secret": "your-client-secret",
  "code-version": "version1"
}

必須フィールド

• hostname: あなたのSFCCインスタンスのホスト名
• username: あなたのSFCCユーザー名
• password: あなたのSFCCパスワード

オプションフィールド

• client-id: OAuthクライアントID（APIアクセス用）
• client-secret: OAuthクライアントシークレット（APIアクセス用）
• code-version: 使用するコードバージョン

環境変数の使用

あるいは、環境変数を使用してサーバーを構成することもできます。

export SFCC_HOSTNAME="your-instance.sandbox.us01.dx.commercecloud.salesforce.com"
export SFCC_USERNAME="your-username"
export SFCC_PASSWORD="your-password"
export SFCC_CLIENT_ID="your-client-id"
export SFCC_CLIENT_SECRET="your-client-secret"
export SFCC_SITE_ID="RefArch"

データAPIの構成

システムオブジェクト定義ツールのためのビジネスマネージャーの設定

システムオブジェクト定義ツール（get_system_object_definitions, get_system_object_definition, search_system_object_attribute_definitions, search_site_preferences, search_system_object_attribute_groups, search_custom_object_attribute_definitions）を使用するには、ビジネスマネージャーでデータAPIアクセスを構成する必要があります。

ステップ1: アカウントマネージャーでAPIクライアントを作成する

1. アカウントマネージャー（ビジネスマネージャーではない）にログインします。
2. APIクライアントセクションに移動します。
3. APIクライアントの追加をクリックします。
4. APIクライアントを構成します。
   • 名前: SFCC Dev MCP Server（または任意の説明的な名前）
   • パスワード: 安全なパスワードを生成します。
   • スコープ: SFCCスコープを選択します。
   • ロール: 組織に適したロールを割り当てます。

ステップ2: ビジネスマネージャーでデータAPIアクセスを構成する

1. インスタンスのビジネスマネージャーにログインします。
2. 管理 > サイト開発 > オープンコマースAPI設定に移動します。
3. データAPIタブをクリックします。
4. 以下の設定を構成します。

クライアント構成:

{
  "_v": "23.2",
  "clients": [
    {
      "client_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "resources": [
        {
          "resource_id": "/system_object_definitions",
          "methods": [
            "get"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/system_object_definitions/*",
          "methods": [
            "get"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/system_object_definition_search",
          "methods": [
            "post"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/system_object_definitions/*/attribute_definition_search",
          "methods": [
            "post"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/system_object_definitions/*/attribute_group_search",
          "methods": [
            "post"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/custom_object_definitions/*/attribute_definition_search",
          "methods": [
            "post"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/site_preferences/preference_groups/*/*/preference_search",
          "methods": [
            "post"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        }
      ]
    }
  ]
}

必須設定:

• クライアントID: あなたのAPIクライアントID（例: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa）
• リソースID: /system_object_definitions/*（すべてのシステムオブジェクト定義エンドポイントへのアクセスを許可）
• リソースID: /site_preferences/preference_groups/*/*/preference_search（サイト設定検索へのアクセスを許可）
• メソッド: getとpost（システムオブジェクトと設定の取得と検索に必要）
• 読み取り属性: (**)（すべての属性の読み取りを許可）
• 書き込み属性: (**)（一部の操作に必要な場合があります）

ステップ3: 構成の更新

クライアント資格情報をdw.jsonに追加します。

{
  "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
  "username": "your-username",
  "password": "your-password",
  "client-id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "client-secret": "your-api-client-password",
  "code-version": "version1"
}

データAPIアクセスのトラブルシューティング

一般的な問題:

• 403 Forbidden: APIクライアントが正しいスコープとロールを持っていることを確認してください。
• 401 Unauthorized: クライアント資格情報が正しいことを確認してください。
• リソースが見つからない: リソースIDパターンが/system_object_definitions/*と/site_preferences/preference_groups/*/*/preference_searchに一致することを確認してください。

構成のテスト: MCPツールを使用してデータAPIアクセスをテストすることができます。

{
  "tool": "get_system_object_definitions",
  "parameters": {
    "count": 5,
    "select": "(**)"
  }
}

サイト設定ワークフローのテスト:

{
  "tool": "search_system_object_attribute_groups",
  "parameters": {
    "objectType": "SitePreferences",
    "searchRequest": {
      "query": {
        "match_all_query": {}
      },
      "select": "(**)"
    }
  }
}

起動パラメータとコマンドラインオプション

サーバーは、その動作をカスタマイズするためのいくつかのコマンドラインパラメータをサポートしています。

--dw-json <path>

dw.json構成ファイルのカスタムパスを指定します。

# カスタムdw.jsonパスでnpmを使用する
npm start -- --dw-json /path/to/your/dw.json

# 相対パスでnpmを使用する
npm start -- --dw-json ./config/dw.json

# 直接nodeを使用する
node dist/main.js --dw-json /path/to/your/dw.json

--debug <true|false>

デバッグログ出力を制御して、サーバーログの詳細度をカスタマイズします。

# デバッグログを有効にする（詳細なデバッグメッセージ、メソッドのエントリ/エグジット、タイミング情報を表示）
npm start -- --debug true
npm start -- --debug  # trueの省略形

# デバッグログを無効にする（必須情報、警告、エラーのみを表示）
npm start -- --debug false

# 他のオプションと組み合わせる
npm start -- --dw-json ./config/dw.json --debug false

デバッグログには以下が含まれます:

• メソッドのエントリとエグジットログ
• 操作の詳細なタイミング情報
• デバッグ用の完全なレスポンスプレビュー
• トラブルシューティングのための追加のコンテキスト

本番環境での使用: 本番環境では--debug falseを使用して、ログのノイズを減らし、パフォーマンスを向上させます。

構成の読み込み優先順位

サーバーは、以下の優先順位で構成を読み込みます。

1. コマンドラインの--dw-json引数（最も高い優先順位）
   • dw.jsonファイルのカスタムパスを指定できます。
   • 異なる環境やプロジェクト構成に役立ちます。
2. 現在のディレクトリ内の./dw.jsonファイル
   • 作業ディレクトリに存在する場合、自動的に検出されます。
   • 標準のSFCC開発ワークフローです。
3. 環境変数（最も低い優先順位）
   • dw.jsonが見つからない場合、環境変数にフォールバックします。
   • 以下の「環境変数の使用」セクションを参照してください。

サーバーの起動

# 基本的な起動（./dw.jsonまたは環境変数を使用）
npm start

# カスタムdw.jsonファイルで起動
npm start -- --dw-json /path/to/custom/dw.json

# または直接nodeを使用
node dist/main.js

# またはカスタム構成で起動
node dist/main.js --dw-json ./config/production.json

npxでの使用

ローカルにインストールせずに、npxを使用してサーバーを直接実行することもできます。

# npxで実行（./dw.jsonまたは環境変数を使用）
npx sfcc-dev-mcp

# npxとカスタムdw.jsonファイルで実行
npx sfcc-dev-mcp --dw-json /path/to/custom/dw.json

# npxと相対パスで実行
npx sfcc-dev-mcp --dw-json ./config/dw.json

注: npxを使用する場合は、dw.jsonファイルが現在の作業ディレクトリにあることを確認するか、--dw-jsonパラメータを使用して完全なパスを指定してください。

MCPクライアントの構成

このサーバーをMCPクライアントの構成に追加します。例えば、Claude Desktopの設定では以下のようになります。

ローカルインストールを使用する場合

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "node",
      "args": ["/path/to/sfcc-dev-mcp/dist/main.js"]
    }
  }
}

npxを使用する場合（推奨）

MCPクライアントをnpxを使用するように構成することができます。これにより、パッケージのインストールと更新が自動的に処理されます。

{
  "mcpServers": {
    "sfcc-dev": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "sfcc-dev-mcp",
        "--dw-json",
        "/path/to/your/dw.json"
      ]
    }
  }
}

例の構成:

{
  "mcpServers": {
    "sfcc-dev": {
      "type": "stdio", 
      "command": "npx",
      "args": [
        "sfcc-dev-mcp",
        "--dw-json",
        "/Users/username/Documents/Projects/my-sfcc-project/dw.json"
      ]
    }
  }
}

自動構成検出を使用する場合（作業ディレクトリ内の./dw.jsonを使用）:

{
  "mcpServers": {
    "sfcc-dev": {
      "type": "stdio",
      "command": "npx",
      "args": ["sfcc-dev-mcp"],
      "cwd": "/path/to/your/sfcc/project"
    }
  }
}

MCP構成でnpxを使用するメリット:

• 存在しない場合、自動的に最新バージョンをインストールします。
• プロジェクトを手動でクローンまたはビルドする必要がありません。
• 新しいバージョンがリリースされたときに自動的に更新されます。
• 異なる環境で一貫した動作を提供します。
• チームメンバーと構成を簡単に共有できます。

利用可能なツール

SFCCドキュメントツール

1. get_sfcc_class_info - SFCCクラスの包括的な情報を取得します。

   {
     "className": "Catalog"
   }
   

2. search_sfcc_classes - 名前でクラスを検索します。

   {
     "query": "product"
   }
   

3. get_sfcc_class_methods - クラスのすべてのメソッドを取得します。

   {
     "className": "dw.catalog.Product"
   }
   

4. get_sfcc_class_properties - クラスのすべてのプロパティを取得します。

   {
     "className": "dw.catalog.Catalog"
   }
   

5. search_sfcc_methods - すべてのクラスを対象にメソッドを検索します。

   {
     "methodName": "getPrice"
   }
   

6. list_sfcc_classes - 利用可能なすべてのSFCCクラスをリストします。
7. get_sfcc_class_documentation - 生のドキュメントを取得します。

   {
     "className": "dw.catalog.Product"
   }
   

SFCCベストプラクティスツール

1. get_available_best_practice_guides - すべての利用可能なベストプラクティスガイドをリストします。

   {}
   

2. get_best_practice_guide - 完全なベストプラクティスガイドを取得します。

   {
     "guideName": "sfra_controllers"
   }
   

3. search_best_practices - すべてのベストプラクティスガイドを対象に検索します。

   {
     "query": "validation"
   }
   

4. get_hook_reference - OCAPI/SCAPIのフックリファレンステーブルを取得します。

   {
     "guideName": "ocapi_hooks"
   }
   

SFCC SFRAドキュメントツール

1. get_available_sfra_documents - すべての利用可能なSFRAドキュメントをリストします。

   {}
   

2. get_sfra_document - 完全なSFRAクラスまたはモジュールのドキュメントを取得します。

   {
     "documentName": "server"
   }
   

3. search_sfra_documentation - すべてのSFRAドキュメントを対象に検索します。

   {
     "query": "middleware"
   }
   

4. get_sfra_class_methods - SFRAクラスのすべてのメソッドを取得します。

   {
     "className": "server"
   }
   

5. **`get_sfra_class，