Cloud ALM MCP

SAP Cloud ALM Model Context Protocol サーバー用の Node.js および TypeScript スケルトンです。

このリポジトリは現在モックファーストです。SAP Cloud ALM の認証情報、BTP Destination Service の設定、OAuth のセットアップなしで、インストール、ビルド、テスト、起動が可能です。

ターゲットアーキテクチャ

• ランタイム: SAP BTP Cloud Foundry 上の Node.js。

• 本番 MCP トランスポート: 公式 MCP TypeScript SDK による MCP Streamable HTTP。

• STR-158 では、MCP セッション ID ジェネレーターを設定せず、ステートレスな Streamable HTTP を POC に使用します。

• ローカルフォールバックトランスポート: stdio。ローカル開発専用を想定。

• 将来の Cloud ALM アクセスパス: SAP BTP Destination Service。

• 将来の認証モデル: 設定済み宛先を通じた OAuth2 Client Credentials。

実際の SAP Cloud ALM 接続は、STR-158 には意図的に含まれていません。

セッションと状態の要件は、後のツールフローで永続的な MCP セッション状態が必要になる場合、本番エージェント使用前に再検討する必要があります。STR-158 は意図的にセッションストアを導入しません。

Related MCP server: Cubi MCP Playground

ローカル開発

npm install
npm run build
npm test
npm start

デフォルトでは、npm start はモックモードで HTTP 上で実行され、以下を公開します:

• MCP エンドポイント: POST /mcp

• ヘルスエンドポイント: GET /health

リモート MCP エンドポイントはステートレスで POST のみです。/mcp に対する GET、DELETE、その他の未サポートのメソッドは、Allow: POST を含む 405 Method Not Allowed を返します。GET SSE と MCP セッション終了は意図的に実装されていません。JSON リクエストボディは 64kb に制限されています。

例:

curl http://localhost:3000/health

サポートされているプレースホルダーのリストとして .env.example を使用してください。git にコミットされたローカルファイルに実際の Cloud ALM シークレットを追加しないでください。

SAP BTP Cloud Foundry POC デプロイメント

manifest.yml は、nodejs_buildpack、command: npm start、および /health 上の HTTP ヘルスチェックを使用する単一の cloud-alm-mcp Cloud Foundry アプリケーションを定義します。最初のデプロイは意図的に安全なモックモードに固定されています:

RUNTIME_MODE=mock
MCP_TRANSPORT=http
EXTERNAL_CALLS_ENABLED=false
READ_CAPABILITY_ENABLED=true
WRITE_CAPABILITY_ENABLED=false

STR-162 には、Cloud ALM の認証情報、OAuth 設定、XSUAA/IAS バインディング、Destination Service バインディング、または実際の宛先値は必要ありません。

Cloud Foundry のステージングでは npm install が実行されます。パッケージの postinstall ライフサイクルは npm run build を実行するため、npm start の前に dist/src/index.js が存在します。TypeScript とコンパイルに必要な型パッケージは通常の依存関係であるため、標準の Node.js ビルドパックの本番インストールで、vitest や tsx などのローカルのみのツールを保持せずにアプリをビルドできます。

アプリはプラットフォーム提供の PORT を使用し続けます。本番ポートをハードコードしないでください。package.json は、最初のデプロイで決定的なステージング/ランタイム動作のために Node.js 22.x を要求します。SAP BTP Cloud Foundry は現在 nodejs_buildpack を通じて Node.js 22 をサポートしています。オペレーターは、デプロイ前に cf buildpacks で正確なターゲット基盤を確認する必要があります。

package-lock.json は、権威ある npm 依存関係ロックのままです。Cloud Foundry はルートの package.json/package-lock.json に npm を使用するため、packageManager フィールドは設定されていません。npm バージョンの強制は、ターゲット基盤のデフォルト npm が非互換であることが証明された場合にのみ必要です。

ローカル検証:

npm install
npm run build
npm test
npm start
curl http://localhost:3000/health

オペレーターから必要な BTP 値:

CF API endpoint
BTP org
BTP space
route/domain decision, if not using the default route

手動 BTP 検証フロー:

cf login -a <api-endpoint>
cf target -o <org> -s <space>
cf buildpacks
cf push
cf app cloud-alm-mcp
cf logs cloud-alm-mcp --recent
curl https://<route>/health

デプロイ後、/health が status: ok を返し、POST /mcp がモックモードで動作し、GET /mcp が Allow: POST を含む 405 Method Not Allowed を返し、ログにリクエスト ID、メソッド、パス、ステータス、所要時間が含まれ、リクエストボディ、認証ヘッダー、トークン、シークレットが含まれないことを検証します。

設定

コア環境変数:

• RUNTIME_MODE=mock|destination

• MCP_TRANSPORT=http|stdio

• PORT=3000

• READ_CAPABILITY_ENABLED=true|false

• WRITE_CAPABILITY_ENABLED=true|false

• ALLOWED_DESTINATIONS=cloud-alm-dev

• EXTERNAL_CALLS_ENABLED=false|true

ローカルデフォルトは意図的に安全です: モックランタイム、HTTP トランスポート、読み取り有効、書き込み無効、外部呼び出し無効。

宛先モードは、このスケルトンではプレースホルダーとしてのみ存在します。BTP Destination Service ルックアップと OAuth トークンフローが後のタスクで実装されるまで、フェイルクローズします。

モックタスククライアント

モックモードは、ローカル開発とテストのために、決定的なインメモリのタスクおよびコメントデータを使用します。現在のモックコントラクトフィールドのみをサポートします: タスク id、title、status、priority、およびコメント id、taskId、author、text、createdAt。

モッククライアントは既知のタスクを返し、未知のタスク ID を拒否し、決定的な ID で一度に 1 つのコメントを追加し、明示的に許可リストに登録されたモックタスクフィールドのみを更新します。これらのフィールドは、公式の SAP CALM_TKM ペイロードフィールドであるとは主張されていません。実際の Cloud ALM エンドポイント、ペイロードスキーマ、スコープ、ページネーション名、更新セマンティクスは未検証のままであり、実際の統合作業に延期されます。

セキュリティ境界

ポリシーガードは、Cloud ALM クライアント呼び出しの前にコードで強制されます。以下を検証します:

• 許可された操作名のみ、

• 読み取り/書き込み機能の分離、

• 削除操作の拒否、

• 一括操作の拒否、

• 未知の操作の拒否、

• エージェント指定の宛先または顧客選択なし、

• あいまいな設定に対するフェイルクローズ動作。

これは意図的にプロンプトのみの強制ではありません。顧客の分離と永続的な監査ログは将来のアーキテクチャ作業として残されており、モジュール境界はすでに存在します。

監査イベントは、将来のトレーサビリティのためにオプションのフィールドをすでに予約しています: アクター、顧客コンテキスト、リソースタイプ/ID、相関 ID。スケルトンは実際のアクターや顧客値を発明せず、リクエストペイロード、トークン、認証ヘッダー、クライアント ID、クライアントシークレット、機密の応答ボディをログに記録しません。