# Stateless MCP Incident Lab — Raw TypeScript

Independent raw HTTP/JSON-RPC implementation of the Stateless MCP Incident Lab for Node.js 24. It implements MCP wire shapes directly and intentionally does not depend on the official MCP SDK.

## Capabilities

- Stateless per-request protocol-version and capability negotiation
- Streamable HTTP JSON responses and SSE diagnostic progress
- Tool, resource, resource-template, and prompt catalogs
- Synthetic incident lifecycle and signed multi-round remediation approval
- Public/private response caching with stale-on-refresh-error behavior
- CLI workflows, structured telemetry, health readiness, and security bounds

All remediation effects are simulated.

## Quick start

```bash
npm ci
npm run build
npm start
```

The server binds to `127.0.0.1:3101` by default and exposes `POST /raw/mcp` plus `GET /raw/healthz`. Override the bind with `HOST` and `PORT`. Production replicas must share an `MCP_REQUEST_STATE_SECRET` of at least 32 bytes and set `DYNAMODB_TABLE` (plus optional `DYNAMODB_ENDPOINT` for DynamoDB Local); development uses process-local ephemeral key and effect storage. In another shell:

```bash
node dist/src/main.js --version
node dist/src/main.js discover http://127.0.0.1:3101/raw/mcp
```

## CLI

The `incident-mcp` binary supports these command families:

```text
incident-mcp discover <url>
incident-mcp tools list|inspect|call <url> [...]
incident-mcp resources list|templates|read <url> [...]
incident-mcp prompts list|get <url> [...]
incident-mcp demo <url> --approve|--decline|--cancel
```

Tool and prompt arguments are supplied as one JSON object, either positionally or after a `--json`
marker. Global diagnostic options include `--wire` with sensitive-value redaction and `--no-cache`.
`tools inspect` exits 3 when the named tool is absent from the catalog.

## Docker

Build and run the minimal runtime image:

```bash
docker build --target runtime -t incident-mcp-raw .
docker run --rm -p 127.0.0.1:3101:3101 \
  -e HOST=0.0.0.0 \
  -e MCP_REQUEST_STATE_SECRET="$(openssl rand -hex 32)" \
  -e EFFECT_STORE=memory \
  incident-mcp-raw
# Or inspect the image version without starting the service:
docker run --rm incident-mcp-raw --version
```

The test stage requires the external behavioral repository as a named build context:

```bash
docker build --target test \
  --build-context conformance=../stateless-mcp-incident-lab-conformance \
  --build-context sdk=../stateless-mcp-incident-lab-typescript-sdk/src \
  -t incident-mcp-raw-test .
```

## Runtime behavior

The public HTTP/CLI path uses the same application modules exercised by conformance. Incident lifecycle records and conditional remediation claims share the configured DynamoDB table in production; development uses in-memory stores. The CLI applies MCP cache hints in-process, supports explicit bypass, and serves stale entries only after refresh failure with a warning. Diagnostic SSE work is paced and request-scoped, stops on disconnect or deadline, and returns the actual diagnostic result. Live JSON requests enforce a five-second deadline and emit structured, trace-correlated telemetry with bearer-bearing resource names redacted.

## Development and verification

```bash
npm run format
npm run lint
npm run typecheck
npm run test:architecture -- --self-test
npm run test:independence
npm run test:source-hygiene
npm run test:coverage
npm run test:mutation
npm run build
npm run test:conformance
npm audit --audit-level=high
```

The behavioral suite is resolved from `CONFORMANCE_PATH`, defaulting to the sibling `../stateless-mcp-incident-lab-conformance/conformance` directory.

Coverage is enforced at 95% lines/functions, 90% statements, and 80% branches overall, with a separate 100% statement/branch/function/line gate for the protocol codec and validator. The remaining overall lines are defensive malformed-internal-input paths and the direct-process bootstrap. Mutation testing covers the complete raw protocol core (`codec`, headers, request state, schema guards, validation, and version negotiation) with an enforced score of at least 90%.