Stateless MCP Incident Lab — TypeScript SDK

Official @modelcontextprotocol/sdk implementation of the Stateless MCP Incident Lab.

Requirements

• Node.js 24+

• The external conformance repository checked out as ../stateless-mcp-incident-lab-conformance (or set CONFORMANCE_PATH)

Related MCP server: MCP Hello World

Development

npm ci
npm run format
npm run lint
npm run typecheck
npm test
npm run test:coverage
npm run test:conformance
npm run test:mutation

The external suite holds 197 golden contracts; the SDK lane selects and runs 159 of them. Conformance fixtures remain in the external repository and are never copied into this implementation.

Runtime

npm run build
npm start

The server listens on port 3102 by default (PORT overrides it). Validated requests cross an official @modelcontextprotocol/sdk Server/Client pair over InMemoryTransport before application dispatch:

• MCP: POST /sdk/mcp

• Health: GET /sdk/healthz

The same executable is the network client; the command group comes first, with no client prefix:

node dist/src/main.js discover http://localhost:3102/sdk/mcp
node dist/src/main.js tools list http://localhost:3102/sdk/mcp
node dist/src/main.js tools call http://localhost:3102/sdk/mcp get_incident '{"incident_id":"..."}'

Configuration

• PORT (default 3102) and HOST (default 127.0.0.1; the image sets 0.0.0.0).

• MCP_REQUEST_STATE_SECRET — at least 32 bytes. Required when NODE_ENV=production: without it /sdk/healthz reports 503 and signing requestState fails. Outside production a per-process random key is used, so signed state does not survive a restart or span replicas.

• EFFECT_STORE — memory for explicit local, per-replica state, or dynamodb for durable shared state.

• DYNAMODB_TABLE — required with EFFECT_STORE=dynamodb. The single-table adapter uses conditional lifecycle writes and an atomic effect-claim/incident-mitigation transaction.

Container

docker build -t incident-lab-sdk .
docker run --rm -p 3102:3102 \
  -e EFFECT_STORE=memory \
  -e MCP_REQUEST_STATE_SECRET=0123456789abcdef0123456789abcdef \
  incident-lab-sdk
curl http://localhost:3102/sdk/healthz

The Docker test target accepts the conformance repository as a named build context, as demonstrated by CI.

Quality gates

CI enforces formatting, lint, type checking, unit tests, coverage thresholds (90% statements/functions/lines, 80% branches), the complete SDK conformance lane, production dependency audit, build, mutation score ≥80%, the charter invariants (197 external contracts, zero vendored fixtures, the architecture contract directories, and no suppression pragmas in src/), the container test target, and a build-and-probe of the production image against /sdk/healthz and a live server/discover.

The mutation gate covers the core lifecycle, MRTR, cache, protocol validation, official SDK dispatch, and DynamoDB conditional-write boundaries listed in stryker.config.mjs; its ≥80% score therefore includes the production integration paths added during peer review. The implementation stub scan stays a local step because it is supplied by the separate cdd-skills tooling repository, which CI does not check out.