SAP Commerce MCP Server

SAP Commerce MCP Server

この Model Context Protocol（MCP）サーバーは、SAP Commerce Cloud の OCC API と連携し、Claude を通じて商品データを自然言語で操作できるようにします。

機能

• 商品検索：自然言語のクエリを使用して商品を検索します
• 高度な検索：カテゴリ、価格帯などで商品を絞り込みます
• 商品詳細：特定の商品の詳細情報を取得します
• 在庫状況：商品の在庫数と入手可能状況を確認します
• カテゴリ：カテゴリ別に商品を閲覧、検索します
• プロモーション：実施中のプロモーション情報を取得します
• レビュー：商品レビューと評価にアクセスします
• 商品提案：パーソナライズされた商品レコメンデーションを取得します
• カート管理：ショッピングカートのすべての操作をサポートします
• ヘルスモニタリング：サービスの健全性をリアルタイムで追跡します
• パフォーマンス分析：過去のパフォーマンスを分析し、インサイトを取得します

利用可能なツール

1. search-products：ページネーションに対応した基本的な商品検索

   • パラメーター：
     • query：検索クエリ文字列
     • currentPage：（任意）ページ番号
     • pageSize：（任意）ページあたりの結果数

2. search-products-advanced：フィルターを使用した高度な商品検索

   • パラメーター：
     • query：（任意）検索クエリ文字列
     • categoryCode：（任意）カテゴリコードのフィルター
     • minPrice：（任意）最低価格のフィルター
     • maxPrice：（任意）最高価格のフィルター
     • sort：（任意）並べ替え順
     • currentPage：（任意）ページ番号
     • pageSize：（任意）ページあたりの結果数

3. get-product-details：商品の詳細情報を取得します

   • パラメーター：
     • productCode：商品コード／SKU

4. check-product-availability：商品の在庫数を確認します

   • パラメーター：
     • productCode：商品コード／SKU
     • location：（任意）倉庫／店舗のロケーションコード

5. get-categories：商品カテゴリを閲覧します

   • パラメーター：
     • categoryId：（任意）特定のカテゴリ ID

6. get-products-by-category：カテゴリ内の商品を取得します

   • パラメーター：
     • categoryId：カテゴリ ID
     • currentPage：（任意）ページ番号
     • pageSize：（任意）ページあたりの結果数
     • sort：（任意）並べ替え順

7. get-promotions：プロモーション情報を取得します

   • パラメーター：
     • promotionId：（任意）特定のプロモーション ID

8. get-product-reviews：商品レビューを取得します

   • パラメーター：
     • productCode：商品コード／SKU

9. get-product-suggestions：商品レコメンデーションを取得します

   • パラメーター：
     • productCode：参照商品のコード／SKU
     • maxResults：（任意）提案の最大数

10. create-cart：新しいショッピングカートを作成します

    • パラメーター：なし

11. get-cart：カートの詳細を取得します

    • パラメーター：
      • cartId：取得するカート ID

12. add-to-cart：商品をカートに追加します

    • パラメーター：
      • cartId：カート ID
      • productCode：商品コード／SKU
      • quantity：（任意）追加する数量（デフォルト：1）

13. update-cart-entry：カート内の商品の数量を更新します

    • パラメーター：
      • cartId：カート ID
      • entryNumber：カート内のエントリー番号
      • quantity：新しい数量

14. remove-from-cart：商品をカートから削除します

    • パラメーター：
      • cartId：カート ID
      • entryNumber：削除するエントリー番号

15. get-order-status：注文状況を確認します

    • パラメーター：
      • orderId：注文 ID

16. get-order-history：注文履歴を表示します

    • パラメーター：
      • userId：ユーザー ID

17. check-service-health：現在のサービスの健全性ステータスを取得します

    • パラメーター：なし

18. analyze-performance：過去のパフォーマンスに関するインサイトを取得します

    • パラメーター：なし

設定

サーバーは環境変数を使用して設定できます。

# SAP Commerce Cloud Configuration
SAP_COMMERCE_URL=https://your-commerce-url/occ/v2
SAP_COMMERCE_SITE=your-site-name
SAP_COMMERCE_TIMEOUT=10000
SAP_COMMERCE_VALIDATE_SSL=false

# OAuth2 Authentication (optional)
SAP_COMMERCE_CLIENT_ID=your-client-id
SAP_COMMERCE_CLIENT_SECRET=your-client-secret

# Logging Configuration
LOG_LEVEL=info # debug, info, warn, or error

セットアップ

1. 依存関係をインストールします。

   npm install
   

2. プロジェクトをビルドします。

   npm run build
   

3. サーバーを起動します。

   npm start
   

Claude 連携のクエリ例

• 「hacendado」に関連するすべての商品を検索してください
• 500 ドル未満の電子機器を検索してください
• コードが「ABC123」の商品の詳細を取得してください
• 商品「XYZ789」の在庫状況を確認してください
• 「electronics」カテゴリのすべての商品を表示してください
• 現在有効なプロモーションを教えてください
• 商品「ABC123」のレビューを表示してください
• 「ABC123」に似た商品を提案してください
• 新しいショッピングカートを作成してください
• 商品「ABC123」を 2 個カートに追加してください
• カート内の項目 1 の数量を 3 に更新してください
• カートから項目 2 を削除してください
• カートの詳細を表示してください
• 注文「ORD123456」のステータスを教えてください
• 注文履歴を表示してください
• サービスの現在のヘルスステータスを確認してください
• 過去 12 時間のパフォーマンスを分析してください
• パフォーマンスに関する分析情報を表示してください
• 本日のキャッシュヒット率を取得してください

開発

このプロジェクトには、デバッグと開発を容易にするため、.vscode/mcp.json による VS Code 連携が含まれています。SAP Commerce インスタンスの詳細に合わせて設定を更新してください。

開発モードでの実行

開発時には、次のコマンドを使用できます。

npm run dev

これにより、TypeScript がウォッチモードで起動し、変更のたびに再コンパイルされます。

パフォーマンス監視

リアルタイムのヘルスチェック

このサーバーには、次のメトリクスを使用したリアルタイムのヘルス監視機能が含まれています。

• API レイテンシ
• エラー率
• キャッシュヒット率
• サービスステータス（正常／低下／異常）

履歴分析

パフォーマンスデータは保存され、次の項目について分析されます。

• 24 時間の履歴傾向
• P95 レイテンシの追跡
• エラー率のパターン
• キャッシュ効率のメトリクス
• 自動パフォーマンス分析情報

ロギング

ログは自動ローテーションとともに logs ディレクトリに保存されます。

• エラーログ：logs/error-YYYY-MM-DD.log
• 統合ログ：logs/combined-YYYY-MM-DD.log
• ヘルスメトリクス：logs/health-YYYY-MM-DD.log

ログは毎日自動的にローテーションされ、30 日間保持されます。

エラー処理

このサーバーには、SAP Commerce API でよく発生する問題に対応する包括的なエラー処理機能が含まれています。

• 無効な商品コード
• ネットワーク接続の問題
• 認証エラー
• API のレート制限
• 無効なカテゴリ ID またはプロモーション ID
• 価格範囲の検証
• 並べ替えパラメーターの検証
• カート操作の失敗

認証

このサーバーは、SAP Commerce への認証済みリクエストに OAuth2 クライアントクレデンシャルフローをサポートしています。認証済みリクエストを有効にするには、環境変数にクライアント ID とシークレットを設定してください。

トークン管理

• トークンの自動更新処理
• トークンの有効期限に対するバッファー時間（5 分）
• 認証失敗時の適切なフォールバック

キャッシュ

このサーバーには、次の機能を備えたインテリジェントなキャッシュが実装されています。

• 商品データの TTL は 5 分
• キャッシュの自動無効化
• キャッシュヒット率の監視
• メモリ管理のための退去ポリシー

カートセッション管理

このサーバーは、次の機能を備えた匿名ユーザー用カートセッションを管理します。

• カートの自動作成
• カート ID の永続的な追跡
• カート項目の管理
• カート合計の計算
• 商品の在庫状況の検証

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

• 開発時には、SAP_COMMERCE_VALIDATE_SSL=false を使用して SSL 証明書の検証を無効にできます
• 本番環境では、適切な SSL 証明書と認証が設定されていることを確認してください
• 機密性の高い認証情報（クライアント ID／シークレット）は環境変数に保存し、コードには記述しないでください
• 本番環境へのデプロイでは、定期的なセキュリティ監査を推奨します
• カート ID は機密情報として扱ってください

パフォーマンス最適化

このサーバーには、次のようなパフォーマンス最適化機能が含まれています。

• 指数バックオフによるリクエストの自動再試行
• 頻繁にアクセスされるデータのレスポンスキャッシュ
• リクエストのバッチ処理とスロットリング
• パフォーマンスの監視とアラート
• 過去のパフォーマンス分析
• 自動パフォーマンス分析情報と推奨事項