SAP Commerce MCP Server

このプロジェクトは、ASM従業員のワークフロー（顧客検索、なりすまし、カートのバインドまたは管理、OCCベースのコマースアクションの実行）に焦点を当てたSAP Commerce Cloud用のMCPサーバーを提供します。

このリポジトリは現在ローカルファーストとして扱われています。デフォルトのターゲットは https://localhost:9002 であり、SAP_BASE_URL で実際のホストを制御します。リモートテナントも引き続き使用可能ですが、ドキュメント、テスト、および検証フローは、ローカルのSAP Commerceランタイムを真実のソースとすることを前提としています。

このサーバーの現在の機能

• ASMファーストの顧客アクション: 顧客の検索、顧客へのなりすまし、および顧客に代わっての操作

• セッション対応のカート管理: 手動でのカート操作なしで、カートの作成、確認、更新、削除、クリアが可能

• チェックアウトフロー: 配送先住所、配送モード、ゲストメールアドレス、注文確定

• 製品および検索ツール: 製品検索、詳細取得、在庫確認、ベースサイト/ストア/カタログ/カテゴリの閲覧

• 2つのツールレイヤー: エージェントフレンドリーな高レベルツールと、低レベルのOCC/ASMラッパー

• セッション指向: get_session_status により、エージェントは現在のカート/ユーザー/ベースサイトのコンテキストを把握可能

• FastMCPトランスポート: ローカルまたはリモートのMCPクライアント向けのstdioおよびSSEトランスポート

リクエストの流れ

1. アーキテクチャの概要

ソース: docs/diagrams/architecture.mmd

2. リクエストのスイムレーン例

これは「エージェントが顧客になりすまし、その顧客に代わって買い物を続ける」という典型的なパスです。

ソース: docs/diagrams/example-request.mmd

MCPツール

高レベルツール

これらはASM従業員ワークフローの主要なインターフェースです。

検索と製品

• search_products — キーワードによる製品検索

• get_product — 製品詳細の取得

• get_session_status — 現在のセッション状態の確認

顧客 / ASM

• search_customer — 顧客の迅速な検索

• impersonate_customer — 顧客になりすまして操作を開始

• end_impersonation — 匿名モードに戻る

カートとチェックアウト

• add_to_cart — 製品の追加

• get_cart — 現在のカートの読み取り

• update_cart_entry — エントリ数量の変更

• remove_from_cart — エントリの削除

• clear_cart — カートを空にする

• set_delivery_address — 配送先住所の登録

• set_delivery_mode — 配送方法の選択

• get_delivery_modes — 配送オプションの一覧表示

• set_guest_email — ゲストチェックアウト用メールアドレスの設定

• place_order — 注文の確定

低レベルツール

これらは、正確な制御のために、より限定的なOCC / ASMプリミティブを公開します。

• basesites.list — 利用可能なベースサイトの一覧表示

• catalogs.list — サイトのカタログ一覧表示

• catalogs.get — カタログの取得

• catalogVersions.get — カタログバージョンの取得

• categories.products — カテゴリ別の製品閲覧

• stores.list — サイトのストア一覧表示

• stores.get — ベースストアの取得

• products.get — OCC製品の取得

• products.stock — 在庫データの確認

• products.stockCount — 在庫場所のカウント

• asm.customer360 — 顧客360フラグメントの取得

• asm.customers.create — 顧客の作成

• asm.customers.search — ASM顧客検索の実行

• asm.customers.suggest — 顧客候補の取得

• carts.list — カートの一覧表示

• carts.create — カートの作成または復元

• carts.get — カートの取得

• carts.delete — カートの削除

• cartEntries.list — カートエントリの一覧表示

• cartEntries.add — エントリの追加

• cartEntries.get — エントリの取得

• cartEntries.update — エントリペイロードの置換

• cartEntries.patch — エントリの部分更新

• cartEntries.delete — エントリの削除

設定

1. 依存関係のインストール:

   uv sync

2. 環境テンプレートのコピー:

   cp .env.example .env

3. ローカルのSAP Commerceインスタンスに対して、以下を設定します:

   SAP_BASE_URL=https://localhost:9002

4. SAPのデプロイメントが異なる場合は、これらのパスフラグメントを維持または調整してください:

   • OCC_API_PATH=/occ/v2

   • OAUTH_PATH=/authorizationserver/oauth/token

   • ASM_PATH=/assistedservicewebservices

5. ローカルテナントまたは検証対象のリモートテナントのOAuth認証情報を設定します。 標準のローカルサンプルデータセットアップでは、以下のデフォルト値が想定されています:

   OAUTH_CLIENT_ID=mobile_android
   OAUTH_CLIENT_SECRET=secret
   OAUTH_USERNAME=asmagent
   OAUTH_PASSWORD=nimda
   OAUTH_SCOPE=basic

実行

• Stdio:

  python -m app.server

• SSE:

  fastmcp serve app/server.py --sse :8080

テスト

• 完全な検証スイート:

  uv run ruff check app tests
  uv run mypy app
  uv run pytest -q

• スモークチェック:

  uv run pytest tests/integration/test_smoke.py -q

• ライブ検索フロー:

  uv run pytest tests/integration/test_integration_live.py -s

注 ライブテストは、現在の契約を実際のSAP Commerceランタイムに対して検証することを目的としています。SAP_BASE_URL=https://localhost:9002 の場合、ローカルのOCC/ASMインスタンスが主要な検証ターゲットとなります。OAuthまたはASMデータの設定が誤っている場合は、範囲を広げる前にローカルで診断してください。

ローカルSAPの注意点 一部のSAP 2211ローカルスタックには messagecentercsocc が含まれており、その遅延実行される Oauth2UserFilter が、/users/{customerId} の代理コンテキストを認証済みエージェントで上書きしてしまうことがあります。asmagent のカート呼び出しで EmployeeModel -> CustomerModel キャストエラーが発生する場合は、現在のOCCユーザーがOAuthプリンシパルと異なる場合に、既に一致している顧客を保持するようにそのフィルターにパッチを当ててください。

品質ゲート

• Ruff: リンティングおよびインポートの衛生管理

• Mypy: app/ 全体に対する実用的な静的型チェック

• Pytest + coverage.xml: CIで使用されるのと同じローカルエビデンスをSonarQubeが利用可能

ローカルのSonarQube分析は以下で公開できます:

uv run pytest -q
sonar-scanner

sonar-project.properties はチェックインされているため、ローカルスキャンとCIスキャンで同じプロジェクトキー/ソースレイアウトが使用されます。

ドキュメント

• Workflows — 実用的なツール呼び出しシーケンス

• Architecture Mermaid — システム図のソース

• Request Mermaid — スイムレーン図のソース

• MCPマニフェストおよびツール登録: app/server.py

• 貢献ガイド: AGENTS.md

今後の改善点

• プロジェクトで将来的にマルチプロセスや水平スケーリングされたセッション永続性が必要になった場合にのみ、オプションの外部バッキングストアを追加する

サポートされているOCC / ASMカバレッジ

現在のサーバーは、ベースサイト、カタログ、ストア、製品、カート、カートエントリ、チェックアウトの住所/配送操作、注文確定、およびASM顧客検索/顧客360/カートバインドスタイルの操作など、上記のフローに必要なエンドポイントをカバーしています。