Cloud ALM MCP

用于 SAP Cloud ALM Model Context Protocol 服务器的 Node.js 和 TypeScript 骨架。

该仓库目前以 mock 优先。它可以在没有 SAP Cloud ALM 凭据、BTP Destination Service 配置或 OAuth 设置的情况下安装、构建、测试和启动。

目标架构

• 运行时：SAP BTP Cloud Foundry 上的 Node.js。

• 生产 MCP 传输：通过官方 MCP TypeScript SDK 的 MCP Streamable HTTP。

• STR-158 通过不设置 MCP 会话 ID 生成器，为 POC 使用无状态 Streamable HTTP。

• 本地回退传输：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 运行 mock 模式并暴露：

• MCP 端点：POST /mcp

• 健康端点：GET /health

远程 MCP 端点是无状态且仅支持 POST。/mcp 上的 GET、DELETE 和其他不支持的方法返回 405 Method Not Allowed 并带有 Allow: POST；GET SSE 和 MCP 会话终止有意未实现。JSON 请求体限制为 64kb。

示例：

curl http://localhost:3000/health

使用 .env.example 作为受支持占位符的列表。不要将真实的 Cloud ALM 密钥添加到提交到 git 的本地文件中。

SAP BTP Cloud Foundry POC 部署

manifest.yml 定义了一个使用 nodejs_buildpack、command: npm start 和 /health 上的 HTTP 健康检查的单一 cloud-alm-mcp Cloud Foundry 应用程序。首次部署有意锁定在安全的 mock 模式：

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 依赖锁。未设置 packageManager 字段，因为 Cloud Foundry 对根 package.json/package-lock.json 使用 npm，并且仅当目标基础的默认 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 在 mock 模式下工作，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

本地默认值有意保持安全：mock 运行时、HTTP 传输、读取启用、写入禁用和外部调用禁用。

Destination 模式在此骨架中仅作为占位符存在。在后续任务中实现 BTP Destination Service 查找和 OAuth 令牌流程之前，它保持失败关闭。

Mock 任务客户端

Mock 模式为本地开发和测试使用确定性的内存任务和评论数据。它仅支持当前的 mock 契约字段：任务 id、title、status、priority，以及评论 id、taskId、author、text、createdAt。

Mock 客户端返回已知任务，拒绝未知任务 ID，一次追加一条具有确定性 ID 的评论，并且仅更新明确列入白名单的 mock 任务字段。这些字段不被声称是官方的 SAP CALM_TKM 负载字段。真实的 Cloud ALM 端点、负载模式、范围、分页名称和更新语义仍未验证，并推迟到真实的集成工作中。

安全边界

Policy Guard 在 Cloud ALM 客户端调用之前通过代码强制执行。它验证：

• 仅允许的操作名称，

• 读/写能力分离，

• 删除操作拒绝，

• 批量操作拒绝，

• 未知操作拒绝，

• 不允许代理提供的目标或客户选择，

• 对模糊配置的失败关闭行为。

这有意不是仅提示词执行。客户隔离和持久审计日志留作未来的架构工作，模块边界已经存在。

审计事件已经为未来的可追溯性保留了可选字段：操作者、客户上下文、资源类型/ID 和关联 ID。骨架不会虚构真实的操作者或客户值，也不会记录请求负载、令牌、授权头、客户端 ID、客户端密钥或敏感响应体。