Cloud ALM MCP

SAP Cloud ALM Model Context Protocol 서버를 위한 Node.js 및 TypeScript 스켈레톤입니다.

이 저장소는 현재 mock 우선(mock-first) 방식입니다. 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에 대해 상태 비저장(stateless) Streamable HTTP를 사용합니다.

• 로컬 대체 전송: stdio, 로컬 개발 전용.

• 향후 Cloud ALM 접근 경로: SAP BTP Destination Service.

• 향후 인증 모델: 구성된 destination을 통한 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는 mock 모드로 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 애플리케이션을 정의합니다. 첫 번째 배포는 의도적으로 안전한 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 값이 필요하지 않습니다.

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가 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 토큰 흐름이 이후 작업에서 구현될 때까지 실패 시 닫힘(fail-closed) 방식으로 동작합니다.

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 클라이언트 호출 전에 코드로 강제됩니다. 다음을 검증합니다:

• 허용된 작업 이름만,

• 읽기/쓰기 기능 분리,

• 삭제 작업 거부,

• 일괄 작업 거부,

• 알 수 없는 작업 거부,

• 에이전트가 제공한 destination 또는 고객 선택 없음,

• 모호한 구성에 대한 실패 시 닫힘 동작.

이는 의도적으로 프롬프트 전용 강제가 아닙니다. 고객 격리 및 영구 감사 로깅은 모듈 경계가 이미 존재하는 상태에서 향후 아키텍처 작업으로 남겨집니다.

감사 이벤트는 이미 향후 추적 가능성을 위한 선택적 필드를 예약합니다: 행위자, 고객 컨텍스트, 리소스 유형/ID 및 상관 ID. 스켈레톤은 실제 행위자 또는 고객 값을 만들지 않으며 요청 페이로드, 토큰, 권한 부여 헤더, 클라이언트 ID, 클라이언트 비밀 또는 민감한 응답 본문을 기록하지 않습니다.