# @mcp-abap-adt/calm-server

[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://stand-with-ukraine.pp.ua)

MCP server for **SAP Cloud ALM**, built on
[`@mcp-abap-adt/calm-client`](https://github.com/fr0ster/mcp-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.

## 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

```bash
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)

```bash
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:

```bash
cp .env.example .env
```

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

```env
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)**:

```env
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

```bash
# 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`:

| Flow | Use case | Browser? | Refresh token? |
|---|---|---|---|
| `client_credentials` (default) | technical service-binding (`sb-*` client) | no | no |
| `authorization_code` | end-user dev workflow, full user scope | once | yes |

### 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`](https://www.npmjs.com/package/@mcp-abap-adt/auth-broker)
CLI to convert a BTP service key into a token-bearing `.env`:

```bash
# 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):

```json
{
  "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.

```ts
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:

```ts
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)

| Service | Tools |
|---|---|
| **Features** (11) | `list`, `get`, `get_by_display_id`, `create`, `update`, `delete`, `create_external_reference`, `delete_external_reference`, `list_external_references`, `list_statuses`, `list_priorities` |
| **Tasks** (10) | `list`, `get`, `create`, `update`, `delete`, `list_comments`, `create_comment`, `list_references`, `list_deliverables`, `list_workstreams` |
| **TestCases** (9) | `list`, `get`, `create`, `update`, `delete`, `create_activity`, `create_action`, `list_activities`, `list_actions` |
| **Documents** (7) | `list`, `get`, `create`, `update`, `delete`, `list_statuses`, `list_types` |
| **Projects** (7) | `list`, `get`, `create`, `list_programs`, `get_program`, `list_team_members`, `list_timeboxes` |
| **Hierarchy** (5) | `list`, `get_with_children`, `create_node`, `update_node`, `delete_node` |
| **Analytics** (2, read-only) | `query` (17 endpoints), `list_providers` (static catalog) |
| **Logs** (2, domain-specific REST) | `get` (provider + serviceId + time window), `post` (inbound log records) |
| **ProcessMonitoring** (1, read-only) | `list_processes` |

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

```bash
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

```bash
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`:

| Gate | Env trigger | What it unlocks |
|---|---|---|
| `describeSandbox` | `CALM_MODE=sandbox` + `CALM_API_KEY` | The `api.sap.com` sandbox |
| `describeOAuth2` | `CALM_MODE=oauth2` + `CALM_BASE_URL` + 3× UAA env | Live tenant (incl. endpoints absent from the sandbox catalog, e.g. Business Processes) |
| `describeWhenLive` | either of the above | Read-side tests that work in either mode |
| `describeWithProject` | live backend + `CALM_PROJECT_ID` | Project-scoped chains (features list→get, tasks list→get→comments, …) |
| `describeMutating` | live + `CALM_PROJECT_ID` + `CALM_ALLOW_MUTATIONS=1` | Write tests (every mutation finalises via `try/finally { delete }`) |

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](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.