Cloud ALM MCP

Esqueleto de Node.js y TypeScript para un servidor de Model Context Protocol de SAP Cloud ALM.

Este repositorio es actualmente mock-first. Puede instalarse, compilarse, probarse e iniciarse sin credenciales de SAP Cloud ALM, configuración de BTP Destination Service ni configuración de OAuth.

Arquitectura objetivo

• Runtime: Node.js en SAP BTP Cloud Foundry.

• Transporte MCP de producción: MCP Streamable HTTP mediante el SDK oficial de MCP TypeScript.

• STR-158 usa Streamable HTTP sin estado para el POC al no configurar un generador de ID de sesión MCP.

• Transporte local de respaldo: stdio, destinado únicamente al desarrollo local.

• Futura vía de acceso a Cloud ALM: SAP BTP Destination Service.

• Futuro modelo de autenticación: OAuth2 Client Credentials a través de un destino configurado.

La conectividad real con SAP Cloud ALM se excluye intencionalmente de STR-158.

Los requisitos de sesión y estado deben revisarse antes del uso en agentes de producción si los flujos de herramientas posteriores requieren estado de sesión MCP persistente. STR-158 no introduce intencionalmente un almacén de sesiones.

Related MCP server: Cubi MCP Playground

Desarrollo local

npm install
npm run build
npm test
npm start

Por defecto, npm start ejecuta el modo mock a través de HTTP y expone:

• Endpoint MCP: POST /mcp

• Endpoint de salud: GET /health

El endpoint MCP remoto es sin estado y solo POST. GET, DELETE y otros métodos no admitidos en /mcp devuelven 405 Method Not Allowed con Allow: POST; el SSE de GET y la terminación de sesión MCP no se implementan intencionalmente. Los cuerpos de solicitud JSON están limitados a 64kb.

Ejemplo:

curl http://localhost:3000/health

Usa .env.example como lista de marcadores de posición admitidos. No agregues secretos reales de Cloud ALM a archivos locales que se confirmen en git.

Despliegue del POC en SAP BTP Cloud Foundry

manifest.yml define una única aplicación de Cloud Foundry cloud-alm-mcp que usa nodejs_buildpack, command: npm start y una comprobación de salud HTTP en /health. El primer despliegue está bloqueado intencionalmente al modo mock seguro:

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

No se requieren credenciales de Cloud ALM, ajustes de OAuth, enlace XSUAA/IAS, enlace de Destination Service ni valores de destino reales para STR-162.

El staging de Cloud Foundry ejecuta npm install; el ciclo de vida postinstall del paquete ejecuta npm run build para que dist/src/index.js exista antes de npm start. TypeScript y los paquetes de tipos necesarios para la compilación son dependencias regulares, de modo que la instalación de producción estándar del buildpack de Node.js pueda compilar la aplicación sin incluir herramientas solo locales como vitest y tsx.

La aplicación sigue usando el PORT proporcionado por la plataforma; no fijes un puerto de producción. package.json solicita Node.js 22.x para un comportamiento determinista de staging/runtime en el primer despliegue. SAP BTP Cloud Foundry admite actualmente Node.js 22 a través de nodejs_buildpack; los operadores deben verificar igualmente la fundación objetivo exacta con cf buildpacks antes del despliegue.

package-lock.json sigue siendo el bloqueo de dependencias npm autoritativo. No se establece el campo packageManager porque Cloud Foundry usa npm para un package.json/package-lock.json raíz, y forzar una versión de npm solo es necesario si el npm predeterminado de la fundación objetivo resulta incompatible.

Validación local:

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

Valores de BTP necesarios del operador:

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

Flujo de validación manual de 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

Después del despliegue, valida que /health devuelva status: ok, que POST /mcp funcione en modo mock, que GET /mcp devuelva 405 Method Not Allowed con Allow: POST, y que los registros contengan IDs de solicitud, método, ruta, estado y duración sin cuerpos de solicitud, encabezados de autorización, tokens ni secretos.

Configuración

Variables de entorno principales:

• 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

Los valores predeterminados locales son intencionalmente seguros: runtime mock, transporte HTTP, lectura habilitada, escritura deshabilitada y llamadas externas deshabilitadas.

El modo destination existe solo como marcador de posición en este esqueleto. Falla de forma cerrada hasta que la búsqueda de BTP Destination Service y el flujo de tokens OAuth se implementen en tareas posteriores.

Cliente de tareas mock

El modo mock usa datos deterministas de tareas y comentarios en memoria para el desarrollo local y las pruebas. Solo admite los campos actuales del contrato mock: id, title, status, priority de la tarea, y id, taskId, author, text, createdAt del comentario.

El cliente mock devuelve tareas conocidas, rechaza IDs de tarea desconocidos, agrega un comentario a la vez con IDs deterministas y actualiza solo los campos de tareas mock explícitamente permitidos. No se afirma que estos campos sean campos oficiales de payload de SAP CALM_TKM. Los endpoints reales de Cloud ALM, esquemas de payload, ámbitos, nombres de paginación y semántica de actualización siguen sin verificarse y se difieren al trabajo de integración real.

Límite de seguridad

El Policy Guard se aplica mediante código antes de las llamadas al cliente de Cloud ALM. Valida:

• solo nombres de operación permitidos,

• separación de capacidades de lectura/escritura,

• rechazo de operaciones de eliminación,

• rechazo de operaciones masivas,

• rechazo de operaciones desconocidas,

• ninguna selección de destino o cliente proporcionada por el agente,

• comportamiento de fallo cerrado para configuración ambigua.

Esto no es deliberadamente una aplicación solo mediante prompts. El aislamiento del cliente y el registro de auditoría duradero se dejan como trabajo de arquitectura futuro, con los límites de módulos ya presentes.

Los eventos de auditoría ya reservan campos opcionales para trazabilidad futura: actor, contexto de cliente, tipo/ID de recurso e ID de correlación. El esqueleto no inventa valores reales de actor o cliente y no registra payloads de solicitud, tokens, encabezados de autorización, IDs de cliente, secretos de cliente ni cuerpos de respuesta sensibles.