sfcc-dev-mcp

SFCC 開発 MCP サーバー

Salesforce B2C Commerce Cloud の開発ツール、ドキュメント、ランタイム診断への包括的なアクセスを提供する、AI を活用した Model Context Protocol（MCP）サーバーです。

✨ 主な機能

• 🔍 SFCC ドキュメントへの完全なアクセス - すべての SFCC API クラスとメソッドを検索・探索できます
• 🏗️ SFRA ドキュメント - Storefront Reference Architecture ドキュメントへの強化されたアクセス
• 🧱 ISML テンプレートリファレンス - 例と使用ガイダンスを含む、完全な ISML 要素ドキュメント
• 📊 ログ分析ツール - SFCC インスタンスのリアルタイムエラー監視、デバッグ、ジョブログ分析
• ⚙️ システムオブジェクト定義 - カスタム属性とサイト設定を探索できます
• 🧪 スクリプトデバッガー - 認証情報モードでスクリプトデバッガーのエンドポイントを実行・検査できます。デフォルト以外のストアフロントルート用のカスタムトリガー URL／パスにも対応
• 🚀 カートリッジ生成 - ワークスペースにバインドされたパス安全性を備えたカートリッジ構造の自動作成（書き込みはワークスペースルート内、またはルートが利用できない場合はカレントワーキングディレクトリへのフォールバックに限定され、ホームディレクトリへのフォールバックはブロックされます）
• 🧩 エージェントスキルのブートストラップ - AI アシスタント向けに AGENTS.md とバンドルされたスキルを現在のプロジェクトまたは一時ディレクトリにインストールまたはマージ
• ✅ ツール引数の検証 - ランタイムのスキーマ検証により、ハンドラー実行前に必須フィールド、型チェック、enum 制約、整数／数値の範囲、およびオブジェクトスキーマ（トップレベルとネスト）に対する厳密な未知キーチェックを適用
• ⏱️ MCP 進捗とキャンセル - ツール呼び出しはリクエストのキャンセルシグナルに従い、クライアントが progressToken を提供した場合に帯域外の notifications/progress 更新を発行します

🚀 クイックスタート

オプション 1: ドキュメントのみのモード（SFCC の認証情報は不要）

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

オプション 2: フルモード（ログとジョブ分析用の SFCC 認証情報を使用）

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

SFCC の認証情報を含む dw.json ファイルを作成します。どちらかの認証モード（または両方）を使用できます:

• Basic 認証: username + password
• OAuth: client-id + client-secret
• オプションのストアフロント認証（Basic 認証のストアフロントでスクリプトデバッガーのトリガーを使用する場合）: storefrontUsername + storefrontPassword

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

hostname が設定されている場合、少なくとも 1 組の完全な認証情報ペアが必要です。 認証情報が提供されている場合、hostname も必須です。

オプション 3: 自動検出（VS Code ユーザーに推奨）

dw.json ファイルを含む VS Code ワークスペースを開くだけです - サーバーが自動的に検出して使用します:

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

🔧 設定の検出優先順位

サーバーは次の順序で SFCC 認証情報を検出します（優先度の高い順）:

優先度	ソース	説明
1	--dw-json CLI パラメータ	dw.json ファイルへの明示的なパス
2	環境変数	SFCC_HOSTNAME、SFCC_USERNAME、SFCC_PASSWORD、SFCC_CLIENT_ID、SFCC_CLIENT_SECRET
3	MCP ワークスペースルート	VS Code ワークスペースフォルダー内の dw.json を自動的に検出し、クライアントが notifications/roots/list_changed を送信したときに更新します

注意: MCP サーバーはしばしば cwd がユーザーのホームディレクトリに設定された状態で起動するため、サーバーはデフォルトでカレントワーキングディレクトリを検索しなくなりました。MCP ワークスペースルートの仕組みにより、信頼性の高いプロジェクトコンテキストが提供されます。

🎯 動作モード

モード	利用可能なツール	SFCC 認証情報が必要
ドキュメントのみ	18 ツール	❌ いいえ
フルモード	40 ツール	✅ はい

ドキュメント専用モード

学習と開発に最適で、SFCC インスタンスは不要です：

• 完全な SFCC API ドキュメント（5 ツール）
• SFRA ドキュメント（5 ツール）
• ISML テンプレートドキュメント（5 ツール）
• カートリッジ生成（1 ツール、書き込みはワークスペースルート/cwd に制限）
• エージェント指示のブートストラップ（2 ツール）で AGENTS.md とスキルをコピー/マージ、または今後のプロンプトを無効化

フルモード

ライブ SFCC インスタンスへのアクセスを備えた完全な開発体験：

• ドキュメント専用のすべての機能（18 ツール）
• リアルタイムのログ分析とジョブログ（13 ツール）
• システムオブジェクト定義（6 ツール）
• コードバージョン管理（2 ツール）
• スクリプトデバッガー操作（1 ツール）

🏗️ アーキテクチャの概要

このサーバーは、ツールのルーティングとドメインロジックを明確に分離するケイパビリティゲート方式のモジュラーハンドラーアーキテクチャを中心に構築されています：

コアレイヤー

• ツールスキーマ (src/core/tool-schemas/): モジュール化されたカテゴリベースのツール定義（ドキュメント、SFRA、ISML、ログ、ジョブログ、システムオブジェクト、カートリッジ、コードバージョン、エージェント指示、スクリプトデバッガー）。tool-definitions.ts を介して再エクスポートされます。
• サーバーオーケストレーションモジュール (src/core/server-tool-catalog.ts、src/core/server-tool-call-lifecycle.ts、src/core/server-workspace-discovery.ts): ケイパビリティを考慮したツールカタログロジック、tools/call ライフサイクル（進捗/キャンセル/プリフライト）、ワークスペースルート再構成フローを抽出することで、server.ts の責務を絞り込みます。
• ツール引数バリデータ (src/core/tool-argument-validator.ts): ツールのディスパッチ前に、すべてのツールに対して MCP 境界で実行時引数の形状を強制します（必須フィールド、プリミティブ/オブジェクト/配列型、enum チェック、整数/数値範囲、文字列パターン/長さ、およびオブジェクトスキーマのトップレベルとネストレベルの厳格な未知キーチェック）。
• OCAPI クエリカバレッジ (src/core/tool-schemas/shared-schemas.ts): 共有検索スキーマには text_query、term_query、bool_query、filtered_query、match_all_query が含まれるため、MCP 境界の検証がサポートされる OCAPI クエリパターンと整合します。
• ハンドラー (src/core/handlers/): 各カテゴリには、タイミング、構造化ログ、エラー正規化のための共通ベースを拡張したハンドラーがあり、ConfiguredClientHandler による設定駆動の配線で反復的なボイラープレートを削減します（例: log-handler、docs-handler、isml-handler、system-object-handler）。
• クライアント (src/clients/): ドメイン操作（OCAPI、SFRA ドキュメント、ISML ドキュメント、モジュラーログ分析、スクリプトデバッガー、カートリッジ生成、エージェント指示同期）をカプセル化します。ハンドラーはこれらに委譲するため、オーケストレーションと計算が分離されたままになります。
• サービス (src/services/): ファイルシステムとパス操作のための依存性注入された抽象化 — テスト容易性を向上させ、副作用を分離します。
• モジュラーログシステム (src/clients/logs/): メンテナンスしやすい進化のために、リーダー（範囲/テール最適化）、ディスカバリー、プロセッサー（行 → 構造化エントリ）、アナライザー（パターンとヘルス）、フォーマッター（人間向け出力）を提供します。
• 設定ファクトリー (src/config/configuration-factory.ts): 提供された認証情報に基づいてケイパビリティ（canAccessLogs、canAccessOCAPI）を判定し、公開されるツールをそれに応じてフィルタリングします（最小権限の原則）。
• 共有認証情報検証 (src/config/credential-validation.ts): dw.json の読み込みと実行時設定作成の両方について、認証ペアの完全性とホスト名形式の検証を一元化します。
• 呼び出し時のケイパビリティガード (src/core/server.ts): 現在のモードで利用できないツールの実行を拒否するため、非表示のツールを直接の tools/call リクエスト経由で呼び出すことはできません。
• 呼び出しライフサイクルシグナル (src/core/server.ts): tools/call 処理は、リクエストの中止シグナルによるキャンセルをサポートし、呼び出し元が _meta.progressToken を提供する場合はベストエフォートの進捗通知を発行します。
• ツールエラーのサニタイズ (src/core/tool-error-response.ts): MCP ツールレスポンスを返す前に上流の実行エラーをサニタイズし、バックエンドのペイロード詳細の偶発的な漏洩を軽減します。
• 実行時 WebDAV 検証 (src/core/server.ts): OAuth のみの構成（username/password なしの client-id/client-secret）の場合、ログ/ジョブログ/スクリプトデバッガーツールの公開は、ツールの利用可否の誤検知を避けるために、1 回限りの WebDAV ケイパビリティプローブによってゲートされます。
• CLI オプションヘルパー (src/config/cli-options.ts): 予測可能な起動動作のために、コマンドライン解析と環境認証情報の検出を一元化します。
• 共有パスセキュリティポリシー (src/config/path-security-policy.ts): 許可/ブロックパスルールをワークスペースルートのディスカバリーと安全な dw.json の読み込み全体で再利用します。
• 共有中止ユーティリティ (src/utils/abort-utils.ts): 一貫したキャンセルセマンティクスとタイマークリーンアップのために、HTTP クライアントとデバッガークライアントで使用されるタイムアウトと中止シグナルの合成を一元化します。

これが重要な理由

• 拡張性: 新しいツールの追加は通常、スキーマ + 最小限のハンドラーロジックを追加することを意味します（新しいドメインの場合は新しいハンドラー）。
• セキュリティ: 認証情報を必要とするツールは、機能フラグが false の場合には決して公開されません。
• テスト容易性: ユニットテストはクライアントとモジュールを対象とし、統合テスト/MCP テストはハンドラーのルーティングとレスポンス構造を検証します。
• パフォーマンス: テールログの読み取り + 軽量なキャッシュ（cache.ts、log-cache.ts）により、不要な I/O を削減します。

新しいツールの追加（概要）

1. src/core/tool-schemas/ 内の適切なファイルにスキーマを追加します（新しいカテゴリの場合は新しいファイルを作成します）。
2. 新しいファイルを追加する場合は、src/core/tool-schemas/index.ts から新しいスキーマをエクスポートします。
3. クライアント/サービスにドメインロジックを実装します（ハンドラーを肥大化させないようにします）。
4. 既存のハンドラーを拡張するか、新しいカテゴリの場合は新しいハンドラーを作成します。
5. （新しいカテゴリの場合のみ）server.ts の registerHandlers() 内に新しいハンドラーを登録します。
6. テストを書く前に、npx aegis query で実際のレスポンス形状を確認します。
7. Jest ユニットテスト + YAML MCP テストを追加します（認証情報が必要な場合は docs モードと full モードの両方）。
8. ドキュメントを更新します（AGENTS.md + 変更があった場合は README のカウント）。

より深い内部の詳細については、ドキュメントサイトの開発ガイドを参照してください。

🤖 AI インターフェースのセットアップ

お好みの AI アシスタントを選択してください:

インターフェース	最適な用途	セットアップガイド
Claude Desktop	マルチターンの会話、デバッグ	📖 セットアップガイド
GitHub Copilot	VS Code 統合、インライン提案	📖 セットアップガイド
Cursor	モダンな AI 搭載エディター	📖 セットアップガイド

📦 インストール

npx の使用（推奨）

ヒント: -y（または --yes）を追加すると、パッケージをダウンロードする前に npx が表示する対話型プロンプトを抑制できます。これにより、AI クライアント（Claude Desktop、Copilot、Cursor）が確認を待ってハングするのを防ぎます。

# Test the server
npx -y sfcc-dev-mcp

# Use with your configuration
npx -y sfcc-dev-mcp --dw-json /path/to/your/dw.json

グローバルインストール

npm install -g sfcc-dev-mcp
sfcc-dev-mcp --dw-json /path/to/your/dw.json

🐛 デバッグモードとログ

デバッグログの有効化

# Enable debug mode for detailed logging
npx -y sfcc-dev-mcp --debug

# Or with configuration file
npx -y sfcc-dev-mcp --dw-json /path/to/your/dw.json --debug

--debug は true/false、1/0、または yes/no を受け付けます。無効な値は明確なエラーメッセージとともに即座に失敗します。

ログファイルの場所

サーバーはシステムの一時ディレクトリにログを書き込みます:

• macOS: /var/folders/{user-id}/T/sfcc-mcp-logs/
• Linux: /tmp/sfcc-mcp-logs/
• Windows: %TEMP%\sfcc-mcp-logs\

作成されるログファイル:

• sfcc-mcp-info.log - 一般的なアプリケーションログと起動メッセージ
• sfcc-mcp-debug.log - 詳細なデバッグ情報（--debug が有効な場合のみ）
• sfcc-mcp-error.log - エラーメッセージとスタックトレース
• sfcc-mcp-warn.log - 警告メッセージ

ログディレクトリの確認方法

// The exact path varies by system - to find yours:
node -e "console.log(require('os').tmpdir() + '/sfcc-mcp-logs')"

🧪 リリースフロー（メンテナー向け）

このリポジトリは npm リリースに Changesets を使用するようになりました。

変更を新しい sfcc-dev-mcp バージョンでリリースする場合は、リポジトリのルートからチェンジセットを追加します:

npm run changeset

マージする前に main に対する保留中のリリース状態を確認します:

npm run release:status

main 上のリリースワークフローは、保留中のチェンジセットからリリースプルリクエストを作成または更新します。そのリリースプルリクエストをマージすると、npm trusted publishing（GitHub Actions OIDC）を通じて npm パッケージが公開され、npm の伝播を待ち、公開された NPX アーティファクトに対して MCP テストを再実行し、その後同じバージョンを MCP Registry に公開します。

npm run version-packages は server.json をパッケージバージョンと同期させるため、リリース PR で validate:server-json が引き続きパスします。

パッケージの公開は GitHub Actions OIDC trusted publishing を使用するようになったため、別途 npm publish シークレットは不要です。

同じ検証をローカルで実行できます:

# Ensure docs-site tool catalog stays in sync with runtime tool definitions
npm run validate:tools-sync

# Ensure docs-site skills catalog stays in sync with bundled skills
npm run validate:skills-sync

# Ensure MCP registry metadata stays in sync with package.json
npm run validate:server-json

# In a separate terminal, start the mock server first for full-mode MCP tests
npm run test:mock-server:start

# Uses latest published version by default
npm run test:mcp:published-npx

# Or pin a specific published version
bash ./scripts/test-published-npx.sh 1.0.21

GitHub Actions では、公開ワークフローがモックサーバーのライフサイクルを自動的に管理します。

📖 ドキュメント

📚 完全なドキュメント - 包括的なガイドとリファレンス

ドキュメントのソースは docs-site-v2/（VitePress）にあります。レガシーの React サイトは docs-site/ に残っています。

クイックリンク:

• はじめに - インストールと初回実行時のセットアップ
• AI インターフェースのセットアップ - Claude Desktop、GitHub Copilot、Cursor の設定
• 設定ガイド - SFCC の認証情報と Data API のセットアップ
• 利用可能なツール - 完全なツールリファレンス
• 例 - 実践的な使用パターン
• トラブルシューティング - よくある問題と解決策

🛠️ AI インタラクションの例

🧑‍💻 "Create a new SFCC controller for product search"
🤖 Generates complete controller with proper imports, route handling, and SFRA patterns

🧑‍💻 "What's wrong with my checkout flow? Check the logs"  
🤖 Analyzes recent error logs, identifies issues, and suggests fixes

🧑‍💻 "Show me how to implement OCAPI hooks for order validation"
🤖 Retrieves related SFCC classes and methods, then proposes a concrete hook implementation pattern

🔒 セキュリティに関する注意

• ローカル開発への注力: ローカルマシン上での個々の開発者による使用を想定して設計されています
• 認証情報の保護: dw.json ファイルはバージョン管理にコミットしないでください
• ネットワークセキュリティ: すべての API 呼び出しは適切な認証を伴う HTTPS を使用します
• データの保存なし: サーバーは SFCC データをローカルに一切保存しません

🔮 今後の予定

私たちは SFCC Development MCP Server を継続的に改善しており、魅力的な新機能を計画しています:

🎯 今後の強化

• 🧠 よりスマートなログ取得 - インテリジェントなフィルタリング、パターン認識、コンテキストに基づくエラー相関を備えた強化されたログ分析
• 🚀 デプロイメントツール - SFCC のデプロイプロセスおよびコードバージョン管理との統合

🤝 皆さまのコントリビューションをお待ちしています!

新機能や改善についてのアイデアはありますか? ぜひお聞かせください!

• 💡 機能リクエスト: Issue を作成してアイデアを議論しましょう
• 🐛 バグ報告: 遭遇した問題を報告して改善にご協力ください
• 🔧 プルリクエスト: コード、ドキュメント、または例を贡献してください
• 📚 ドキュメント: ガイドやベストプラクティスの拡充にご協力ください

始めるには コントリビューションガイド をご覧いただくか、オープンな Issue を眺めて、どこでお手伝いいただけるかを確認してください。

皆さまの専門知識とフィードバックが、このツールを SFCC コミュニティ全体にとってより良いものにします!

🤝 コントリビューション

コントリビューションを歓迎します! 詳細は コントリビューションガイド をご覧ください。

📄 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています - 詳細は LICENSE ファイルをご覧ください。

---

🚀 AI で SFCC 開発を加速する準備はできましたか?

📖 完全なドキュメントを読んで始めましょう