Cloud ALM MCP

Каркас на Node.js и TypeScript для сервера Model Context Protocol для SAP Cloud ALM.

Этот репозиторий в настоящее время ориентирован на mock-режим. Он может устанавливаться, собираться, тестироваться и запускаться без учетных данных SAP Cloud ALM, конфигурации BTP Destination Service или настройки OAuth.

Целевая архитектура

• Среда выполнения: Node.js на SAP BTP Cloud Foundry.

• Продакшн-транспорт MCP: MCP Streamable HTTP через официальный MCP TypeScript SDK.

• STR-158 использует stateless Streamable HTTP для POC, не задавая генератор ID сессии MCP.

• Локальный запасной транспорт: stdio, предназначен только для локальной разработки.

• Будущий путь доступа к Cloud ALM: SAP BTP Destination Service.

• Будущая модель аутентификации: OAuth2 Client Credentials через настроенный destination.

Реальное подключение к 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 запускает mock-режим через HTTP и предоставляет:

• конечную точку MCP: POST /mcp

• конечную точку health: GET /health

Удаленная конечная точка MCP является stateless и поддерживает только POST. GET, DELETE и другие неподдерживаемые методы на /mcp возвращают 405 Method Not Allowed с Allow: POST; GET SSE и завершение сессии MCP намеренно не реализованы. Тела JSON-запросов ограничены 64kb.

Пример:

curl http://localhost:3000/health

Используйте .env.example как список поддерживаемых плейсхолдеров. Не добавляйте реальные секреты Cloud ALM в локальные файлы, фиксируемые в git.

Развертывание POC на SAP BTP Cloud Foundry

manifest.yml определяет одно приложение Cloud Foundry cloud-alm-mcp с использованием nodejs_buildpack, command: npm start и HTTP health check на /health. Первое развертывание намеренно ограничено безопасным 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 или реальные значения destination.

Staging в Cloud Foundry выполняет npm install; жизненный цикл пакета postinstall запускает npm run build, чтобы dist/src/index.js существовал до npm start. TypeScript и пакеты типов, необходимые для компиляции, являются обычными зависимостями, чтобы стандартная продакшн-установка Node.js buildpack могла собрать приложение без локальных инструментов, таких как vitest и tsx.

Приложение продолжает использовать предоставляемый платформой PORT; не задавайте продакшн-порт жестко. package.json запрашивает Node.js 22.x для детерминированного поведения staging/runtime при первом развертывании. SAP BTP Cloud Foundry в настоящее время поддерживает Node.js 22 через nodejs_buildpack; операторы должны все же проверить точную целевую платформу с помощью cf buildpacks перед развертыванием.

package-lock.json остается авторитетной блокировкой зависимостей npm. Поле packageManager не задано, потому что Cloud Foundry использует npm для корневого package.json/package-lock.json, и принудительное указание версии 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 возвращает 405 Method Not Allowed с Allow: POST, а логи содержат 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 существует только как плейсхолдер в этом каркасе. Он завершается с ошибкой (fail closed), пока поиск BTP Destination Service и поток OAuth-токенов не будут реализованы в последующих задачах.

Mock Task Client

Mock-режим использует детерминированные данные задач и комментариев в памяти для локальной разработки и тестов. Он поддерживает только текущие поля mock-контракта: id, title, status, priority задачи и id, taskId, author, text, createdAt комментария.

Mock-клиент возвращает известные задачи, отклоняет неизвестные ID задач, добавляет по одному комментарию за раз с детерминированными ID и обновляет только явно разрешенные поля mock-задач. Эти поля не заявляются как официальные поля полезной нагрузки SAP CALM_TKM. Реальные конечные точки Cloud ALM, схемы полезных нагрузок, области, имена пагинации и семантика обновления остаются непроверенными и откладываются до реальной интеграционной работы.

Граница безопасности

Policy Guard применяется на уровне кода перед вызовами клиента Cloud ALM. Он проверяет:

• только разрешенные имена операций,

• разделение возможностей чтения/записи,

• отклонение операций удаления,

• отклонение массовых операций,

• отклонение неизвестных операций,

• отсутствие выбора destination или клиента, предоставленного агентом,

• поведение fail-closed при неоднозначной конфигурации.

Это намеренно не только ограничение на уровне промптов. Изоляция клиентов и долговечное аудиторское логирование оставлены как будущая архитектурная работа, при этом модульные границы уже присутствуют.

События аудита уже резервируют необязательные поля для будущей трассируемости: субъект, контекст клиента, тип/ID ресурса и корреляционный ID. Каркас не выдумывает реальные значения субъекта или клиента и не логирует полезные нагрузки запросов, токены, заголовки авторизации, ID клиентов, секреты клиентов или чувствительные тела ответов.