@mcp-abap-adt/calm-server

MCP server for SAP Cloud ALM, built on @mcp-abap-adt/calm-client. Ships 54 MCP tools covering all 9 Cloud ALM services — full CRUD where the service supports it, plus a wide read surface — with rich JSON Schema descriptions that let an LLM plan multi-step workflows.

This package is dual-purpose:

• Runnable stdio server — npx @mcp-abap-adt/calm-server. Plug directly into Claude Desktop, Claude Code, or any MCP-compatible host.

• Reusable library of tool primitives — import individual tools (FEATURES_GROUP, TASKS_GROUP, …) and embed them in a larger composed MCP server without reimplementing anything.

Status

0.2.0 — 54 tools, 232 tests (224 unit + integration, 7 env-gated skips, 1 todo), full build green. Integration suite runs live against the SAP sandbox (api.sap.com) or any OAuth2 Cloud ALM tenant with a single .env switch; gates skip cleanly when no backend is wired.

Related MCP server: odata-mcp-proxy

Installation

Requires Node.js 22, 24 or 26 — the versions @mcp-abap-adt/auth-providers, which obtains the server's tokens, supports.

As a standalone MCP server

npm install -g @mcp-abap-adt/calm-server
# or per-project:
npm install @mcp-abap-adt/calm-server

As a library (compose into your own MCP server)

npm install @mcp-abap-adt/calm-server
# peers:
npm install @mcp-abap-adt/calm-client @mcp-abap-adt/interfaces-calm @mcp-abap-adt/interfaces-auth @mcp-abap-adt/interfaces-utils @modelcontextprotocol/sdk

The peers are the packages whose types this package's API names, so your code and this package must share one copy: CalmClient (calm-client), ICalmConnection (interfaces-calm), ITokenRefresher (interfaces-auth) and ILogger (interfaces-utils). The auth pipeline the standalone server runs — auth-broker, auth-providers, auth-stores and interfaces-auth-sap — is a regular dependency: nothing you import from this package exposes it.

Standalone: running the server

1. Configure credentials

Copy the template and fill in:

cp .env.example .env

OAuth2 mode (real tenant) — paste values from an XSUAA service key:

CALM_MODE=oauth2
CALM_BASE_URL=https://<tenant>.<region>.alm.cloud.sap
CALM_UAA_URL=https://<tenant>.authentication.<region>.hana.ondemand.com
CALM_UAA_CLIENT_ID=sb-…!b…|calm!b…
CALM_UAA_CLIENT_SECRET=…

Sandbox mode (SAP API Business Hub):

CALM_MODE=sandbox
CALM_API_KEY=<your-key-from-api.sap.com>
# CALM_BASE_URL defaults to https://sandbox.api.sap.com/SAPCALM

2. Launch

# Global install:
calm-mcp
# Or via npx without install:
npx @mcp-abap-adt/calm-server
# Or from a clone:
npm run build && node dist/bin/stdio.js

The server speaks MCP over stdio. Misconfiguration is reported to stderr with a non-zero exit code.

Authentication setup

calm-mcp supports two OAuth2 flows for live tenants, selectable via CALM_AUTH_FLOW:

Option A — quick CC setup (technical user)

Plain .env with inline CALM_UAA_URL / CALM_UAA_CLIENT_ID / CALM_UAA_CLIENT_SECRET works as before — no extra steps. The broker uses an in-memory session shim for these inline creds.

Option B — broker-backed setup (CC or AC)

Use the bundled mcp-auth CLI to convert a BTP service key into a token-bearing .env:

# CC (no browser)
npx mcp-auth --service-key ./sk.json --output ./DEFAULT.env \
             --type xsuaa --credential

# AC (browser pops once; refresh_token persists)
npx mcp-auth --service-key ./sk.json --output ./DEFAULT.env \
             --type xsuaa --browser auto

The server itself never logs in interactively: it speaks over stdio and has no one to show a login page to. With authorization_code it uses the refresh token in ./DEFAULT.env; when there is none, or the identity provider refuses it, the call fails with LoginRequiredError (code: 'LOGIN_REQUIRED'), whose message is the mcp-auth command to run. Run it and restart the server.

Then in your .env:

CALM_MODE=oauth2
CALM_BASE_URL=https://<tenant>.<region>.alm.cloud.sap
CALM_AUTH_FLOW=authorization_code   # or client_credentials
CALM_DESTINATION=DEFAULT

The server's runtime auth pipeline is @mcp-abap-adt/auth-broker. The broker writes each new token (and refresh token) back to ./DEFAULT.env; it does not write CALM_BASE_URL there. The URL the broker needs for a session comes from CALM_BASE_URL at read time, so a session file without XSUAA_MCP_URL — which is what mcp-auth writes for a Cloud ALM key — works as it is.

Note: buildCalmClient is async since v0.4.0 (was sync in v0.3.x). Library consumers must await it.

3. Wire into Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "calm": {
      "command": "npx",
      "args": ["-y", "@mcp-abap-adt/calm-server"],
      "env": {
        "CALM_MODE": "sandbox",
        "CALM_API_KEY": "<your-sandbox-key>"
      }
    }
  }
}

Restart Claude Desktop; the 54 calm_* tools become available to the model.

Library: composing into another MCP server

Useful when you want to expose Cloud ALM tools alongside ADT tools, Reports tools, or your own domain tools in a single MCP process.

import { CalmClient } from '@mcp-abap-adt/calm-client';
import { SandboxCalmConnection } from '@mcp-abap-adt/calm-server/connection';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import {
  ALL_GROUPS,
  BaseCalmMcpServer,
  CalmToolRegistry,
  FEATURES_GROUP,
  TASKS_GROUP,
} from '@mcp-abap-adt/calm-server';

// Option A — BaseCalmMcpServer with a curated subset
// `OAuth2CalmConnection` takes a `tokenRefresher` (an `ITokenRefresher`
// from `@mcp-abap-adt/interfaces-auth`) instead of an API key.
const calm = new CalmClient(
  new SandboxCalmConnection({ baseUrl, apiKey }),
);
const server = new BaseCalmMcpServer({
  name: 'my-mcp',
  version: '1.0.0',
  calm,
  groups: [FEATURES_GROUP, TASKS_GROUP], // only these land as tools
});

// Option B — embed into your existing McpServer
const existing = new McpServer({ name: 'combined', version: '1.0.0' });
const registry = new CalmToolRegistry([...ALL_GROUPS]);
registry.registerAll(existing, () => ({ calm }));
// Now `existing` serves Cloud ALM tools + whatever else you registered.

Subpath exports:

import { ALL_GROUPS } from '@mcp-abap-adt/calm-server/tools';
import { CalmToolRegistry } from '@mcp-abap-adt/calm-server/registry';
import { createCalmConnection } from '@mcp-abap-adt/calm-server/connection';

Tool surface (54 tools across 9 services)

Every MCP tool:

• Has a full JSON Schema with descriptions — the LLM reads these to plan.

• Wraps arguments into OData $filter / $select / $top / $skip internally — the LLM never sees raw OData syntax.

• Returns compact records by default (limit=20, fields default ≈ 6 columns per entity); callers opt into more via fields, limit, withCount, offset.

• Maps CalmApiError → a typed MCP error the LLM can branch on (NOT_FOUND, NETWORK, ODATA_ERROR with serviceCode, …).

See src/tools/<service>/*.ts for per-tool argument schemas.

Destructive tools (write operations)

Every Cloud ALM service that supports writes is now exposed:

• Features: create, update, delete, plus external-reference create / delete

• Tasks: create, update, delete, create_comment

• TestCases: create, update, delete, plus nested create_activity / create_action

• Documents: create, update, delete

• Hierarchy: create_node, update_node, delete_node

• Projects: create

• Logs: post (inbound OpenTelemetry-style record ingestion)

The shared SAP sandbox at api.sap.com is read-friendly only — mutation integration tests are opt-in (see Live-tenant integration below).

Debug logging

CALM_LOG_LEVEL=debug         # error | warn | info | debug
DEBUG_CALM_CONNECTORS=true   # connection retries, 401 refresh, URLs
DEBUG_CALM_LIBS=true         # resource-client internals
DEBUG_CALM_TESTS=true        # test execution progress

Logging goes to stderr (stdout is reserved for the MCP protocol stream).

Development

git clone git@github.com:fr0ster/mcp-calm-server.git
cd mcp-calm-server
npm install

npm run test           # 224 unit + integration tests
npm run build          # emits dist/, includes executable bin
npm run lint:check     # biome

Live-tenant integration

src/__tests__/integration/ runs against a real backend when env is present, and skips cleanly when it isn't (so npm test without secrets is always green). Five gates, drop them into .env:

A quick smoke script lives at scripts/smoke-sandbox.mjs — spawns the stdio bin, lists tools, calls a handful of read endpoints, and exits 1 on any non-skip failure.

License

GPL-3.0-only — see LICENSE.

This is a server you run, not a library you link, which is why it carries the GPL where the contract and client packages in this family carry the LGPL. Versions up to and including 0.7.0 were released under MIT and stay MIT: a licence change is not retroactive.