SFCC MCP Server

SFCC MCP サーバー

Salesforce Commerce Cloud（SFCC）API と連携するための Model Context Protocol（MCP）サーバーです。

特長

• endpoints.json の設定に基づく動的なエンドポイント登録
• パスパラメーターとクエリパラメーターの自動処理
• GET リクエストと POST リクエストの両方に対応
• クライアント認証情報フローを使用した OCAPI 認証
• 商品検索を含む、SFCC Data API エンドポイントに対応
• リモートモード：OAuth 認証を使用する HTTP ベースのサーバー
• セッションごとの設定：セッションごとに異なる SFCC 認証情報と API エンドポイントを使用できます
• マルチテナント対応：複数のクライアントが異なる SFCC インスタンスに同時に接続できます
• 自動デプロイ：Google App Engine へのデプロイに対応する GitHub Actions 連携
• バージョン管理：バージョン管理とデプロイのワークフローを自動化

インストール

# Install dependencies
npm install

# Build the server
npm run build

設定

プロジェクトのルートディレクトリに .env ファイルを作成し、次の変数を設定します。

# SFCC API Configuration
SFCC_API_BASE=https://your-instance.api.commercecloud.salesforce.com/

# Admin API Credentials (Client credentials flow)
SFCC_ADMIN_CLIENT_ID=your_admin_client_id
SFCC_ADMIN_CLIENT_SECRET=your_admin_client_secret

OCAPI の設定

SFCC Data API を使用するには、適切な権限を設定した API クライアントを SFCC で構成する必要があります。

API クライアント

1. SFCC Account Manager で、API Client に移動します
2. 新しい API クライアントを作成するか、既存のものを編集します
3. OAuth の設定を行います：
   • OAuth Client ID： （クライアント ID）
   • OAuth Client Secret： （クライアントシークレット）
   • Default scopes：エンドポイントに必要なスコープを含めます
   • Token Endpoint Auth Method：client_secret_post
4. API クライアントのロールを設定します：
   • 必要なデータにアクセスできる適切なロールを割り当てます

Business Manager

1. SFCC Business Manager で、Administration > Site Development > Open Commerce API Settings に移動します
2. 設定例については ocapi-bm-config.json を参照してください

VSCode の MCP 設定

1. コマンドパレット（Ctrl/Cmd + Shift + P）を開きます
2. 「MCP」と入力し、MCP: Add Server... を選択します
3. Command (stdio) Manual Install を選択します
4. コマンドとして node <full-path-to-your>/build/index.js を入力します（送信する前にパスのプレースホルダーを置き換えてください）
5. MCP サーバーの名前を入力します（例：「sfcc」）
6. User または Workspace のどちらに設定するかを選択します

これにより、ユーザーの settings.json またはワークスペースの .vscode/mcp.json に新しいサーバー定義が作成されます

{
    "servers": {
        "sfcc": {
            "type": "stdio",
            "command": "node",
            "args": [
                "<full-path-to-your>/build/index.js"
            ]
        }
    }
}

これで、MCP: List Servers コマンドからサーバーの状態を確認したり、起動、再起動、停止したりできます。GitHub Copilot Chat で Agent モードに切り替えると、ツールを使用できます。

使用方法

サーバーを起動します：

node build/index.js

エンドポイントの設定

エンドポイントは src/endpoints.json で設定します。各エンドポイントは次の構造になっています。

{
    "path": "/your/endpoint/{param}",
    "description": "Description of what this endpoint does",
    "method": "GET",  // Optional: HTTP method (GET, POST, PUT, DELETE). Defaults to GET
    "params": [
        {
            "name": "param",
            "description": "Description of the parameter",
            "type": "string",
            "required": true
        }
    ]
}

• path：API エンドポイントのパス。パスパラメーターは中括弧で指定します
• description：エンドポイントの機能の説明
• method：使用する HTTP メソッド（GET、POST、PUT、DELETE）。指定されていない場合は GET がデフォルトです
• params：パラメーター定義の配列
  • name：パラメーター名
  • description：パラメーターの説明
  • type：パラメーターの型（string、number、boolean）
  • required：パラメーターが必須かどうか

パスに含まれるパラメーター（例：{param}）は、パスの置換に使用されます。それ以外のパラメーターは、自動的にクエリパラメーターとして追加されます。

POST リクエストとリクエストボディ

POST エンドポイントでは、ツールの呼び出し時に requestBody パラメーターを使用して JSON リクエストボディを指定できます。例：

{
  "site_id": "SiteGenesis",
  "requestBody": {
    "query": {
      "text_query": {
        "search_phrase": "shirt"
      }
    },
    "sort": "price-asc",
    "count": 10
  }
}

デフォルトのリクエストボディ

エンドポイントでは、リクエストボディが指定されなかった場合に使用する defaultBody プロパティを定義できます。これにより、正確なボディ構造を知らなくても API を簡単に使用できます。たとえば、product_search エンドポイントと campaign_search エンドポイントには、特定のクエリが指定されていない場合にすべての項目に一致するデフォルトのボディが設定されています。

パスパラメーターとクエリパラメーター

エンドポイントによって、パラメーターの使い方は異なります。

1. パスパラメーター：/sites/{site_id}/campaign_search のように、波括弧を使ってエンドポイントのパスに含めるパラメーターです。
2. クエリパラメーター：クエリ文字列として URL に追加するその他のパラメーターです。

パスパラメーターを含むエンドポイント（campaign_search）の例：

{
  "site_id": "SiteGenesis",
  "requestBody": {
    "query": {
      "term_query": {
        "fields": ["enabled"],
        "operator": "is",
        "values": ["true"]
      }
    },
    "count": 20
  }
}

ツール名

ツール名はエンドポイントのパスから自動的に生成されます。

• パスの区切り文字はアンダースコアに置き換えられます。
• パスパラメーターは "by_param" に置き換えられます。
• 必要に応じて、名前は 64 文字に切り詰められます。
• 必要に応じて、数値の接尾辞を付けて一意性が確保されます。

例：/catalogs/{id}/products は catalogs_by_id_products になります。

エンドポイント設定でカスタムツール名を指定することもできます。

{
  "path": "/product_search",
  "toolName": "product_search",
  "description": "Search for products..."
}

カスタムハンドラー

エンドポイント用のカスタムハンドラーは、次の手順で作成できます。

1. エンドポイント定義でカスタム toolName を指定します。
2. デフォルトのハンドラーの代わりに呼び出される、handler_[toolName] という名前の関数を作成します。

カスタムハンドラーを作成するには、handler_[toolName] という命名パターンに従って関数を作成します。この関数は自動的に検出され、デフォルトのハンドラーの代わりに使用されます。

/**
 * Custom handler for product search
 * This function will be called instead of the default handler when 
 * the endpoint with toolName "product_search" is accessed
 */
export async function handler_product_search(endpoint, params) {
  console.log(`Custom handler for ${endpoint.path} called with params:`, params);
  
  // Example of custom processing before making the actual request
  if (params.requestBody && typeof params.requestBody === 'object') {
    // Modify the request if needed
    params.requestBody.custom_field = 'Added by custom handler';
  }
  
  // Call the default handler with your modified params
  const defaultHandler = getDefaultHandler();
  return await defaultHandler(endpoint, params);
}

カスタムハンドラーの作成

index.ts ファイル内でカスタムハンドラーを直接定義できます。

/**
 * Custom handler for an endpoint with toolName "example_endpoint"
 */
async function handler_example_endpoint(endpoint, params) {
  // Your custom implementation
  // ...
}

// Make the custom handler accessible globally
(global as any).handler_example_endpoint = handler_example_endpoint;

カスタムハンドラー関数は、次の 2 つのパラメーターを受け取ります。

• endpoint：エンドポイント設定オブジェクト
• params：エンドポイントに送信されたパラメーター

関数は、クライアントに返すデータを返す必要があります。

ヘルパー関数

このヘルパー関数を使うと、デフォルトのハンドラーにアクセスできます。

// Helper to get the default handler
function getDefaultHandler() {
  if (typeof handleSFCCRequest === 'function') {
    return handleSFCCRequest;
  }
  if (typeof (global as any).handleSFCCRequest === 'function') {
    return (global as any).handleSFCCRequest;
  }
  throw new Error('Default handler not available');
}

カスタムハンドラーのパターン

カスタムハンドラーには、さまざまなパターンを実装できます。

前処理： デフォルトのハンドラーを呼び出す前にパラメーターを変更します。

export async function handler_example(endpoint, params) {
  // Modify params
  params.customField = 'value';
  
  // Call default handler with modified params
  return await getDefaultHandler()(endpoint, params);
}

後処理： デフォルトのハンドラーを呼び出した後に結果を拡張します。

export async function handler_example(endpoint, params) {
  // Get result from default handler
  const result = await getDefaultHandler()(endpoint, params);
  
  // Modify the result
  result.enhancedField = 'value';
  
  return result;
}

完全な上書き： デフォルトのハンドラーを呼び出さずに、カスタムの動作を実装します。

export async function handler_example(endpoint, params) {
  // Custom implementation
  return {
    custom: true,
    data: [...]
  };
}

テスト

SFCC MCP Server には、信頼性を確保し、自動化された CI/CD プロセスを促進するための包括的なテストが含まれています。

テストの実行

# Run all tests
npm test

# Run tests in watch mode for development
npm run test:watch

# Run tests with coverage report
npm run test:coverage

テストカバレッジ

テストスイートでは、次の項目をテストします。

• ツールユーティリティ（tests/tool-utils.test.ts）：ツール名の生成とスキーマの構築
• 設定管理（tests/config-simple.test.ts）：環境設定とセッション管理
• 統合テスト（tests/integration.test.ts）：MCP サーバーのインスタンス化とツールの登録

テストフレームワーク

このプロジェクトでは、テストに TypeScript をサポートする Jest を使用しています。テストは tests/ ディレクトリにあり、*.test.ts という命名規則に従います。

デプロイ

SFCC MCP Server は、Google App Engine への自動デプロイをサポートしています。

クイックスタート

1. Google Cloud をセットアップします。

   npm run setup:gcp
   

2. バージョン管理を使用してデプロイします。

   npm run version:create
   

3. 手動でデプロイします。

   npm run version:deploy
   

ドキュメント

• DEPLOYMENT.md：デプロイのセットアップに関する完全なガイド
• REMOTE.md：リモートサーバーの設定と使用方法

使用可能なコマンド

npm run setup:gcp          # Interactive Google Cloud setup
npm run version:create     # Create version and auto-deploy
npm run version:deploy     # Manual deployment with version input
npm run deploy             # Direct deployment to App Engine

ライセンス

MIT