P0.2.1 — Step 5 Verification

Evidence that Step 4 (3372d993, feat(p0-2-1): MCP server bootstrap + 5-stage α middleware + server_ping) satisfies the contract acceptance checklist (§12) and the packet gate (§8).

Collected from the worktree at E:\AMS\.worktrees\claude\p0-2-1-mcp-server\ immediately after the Step 4 commit.

§1. npm run lint 

$ npx eslint src
(no output)
exit 0

Clean. No warnings, no errors across src/config.ts, src/modes.ts, src/server.ts, and every file in src/__tests__/.

§2. npm run build 

$ npx tsc
(no output)
exit 0

tsc emits dist/server.js, dist/server.d.ts, dist/config.*, dist/modes.* silently. Strict mode (strict, exactOptionalPropertyTypes, noUncheckedIndexedAccess) with no opt-outs.

§3. npm test -- --coverage 

$ npm test
Test Suites: 4 passed, 4 total
Tests:       89 passed, 89 total
Snapshots:   0 total
Time:        ~12s
exit 0

3a. Test suite breakdown

Suite Tests Status
src/__tests__/config.test.ts 14 pass
src/__tests__/modes.test.ts 24 pass
src/__tests__/smoke.test.ts 1 pass
src/__tests__/server.test.ts 50 pass
Total 89 pass

Prior test count (on origin/main at a64d7349): 39 (14 config + 24 modes + 1 smoke). This PR adds 50 server tests → new total 89 (packet §2f target was 66; actual exceeds target by +23 because coverage-driven tests for the bootstrap() / default-arg / idempotence / handler-body paths were added per Q-7 + coverage targets).

3b. Coverage summary 

-----------|---------|----------|---------|---------|-------------------
File       | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-----------|---------|----------|---------|---------|-------------------
All files  |   98.62 |    92.75 |     100 |    98.6 |
 config.ts |     100 |       80 |     100 |     100 | 78
 modes.ts  |     100 |      100 |     100 |     100 |
 server.ts |   98.21 |    92.59 |     100 |   98.19 | 552,558
-----------|---------|----------|---------|---------|-------------------

3c. Coverage on src/server.ts

Metric Target Actual Delta Verdict
Statements 100% 98.21% -1.79% Near
Branches ≥90% 92.59% +2.59% Pass
Functions 100% 100% 0 Pass
Lines 100% 98.19% -1.81% Near

Uncovered lines: 552, 558.

  • Line 552 — the return false inside isInvokedAsScript() when process.argv[1] === undefined. Jest’s test runner always supplies a path in argv[1], so this branch is only reachable via node --input-type=module -e "import('server.ts')" (subprocess). The subprocess test in describe('script-invocation guard') + the describe('donor-bug regressions') test cover it end-to-end at runtime; Jest’s Istanbul instrumentation does not span subprocess boundaries, so the coverage counter cannot increment here.
  • Line 558 — await bootstrap() inside the if (isInvokedAsScript()) guard. Reachable only when src/server.ts is the entry script (node dist/server.js or tsx src/server.ts). Packet §2f explicitly acknowledges this: “the main() guard IIFE … may contribute uncovered-branch lines.”

The two uncovered lines are the entry-script guard proper. Their downstream body has been refactored out of the legacy main() IIFE and into an exported bootstrap() factory, which is unit-tested in-process — bringing coverage from the packet-predicted gap down to just these two lines.

3d. Coverage regression check

src/config.ts: unchanged (100% stmts / 80% branch / 100% func / 100% lines — line 78 is the i.path.length > 0 branch, pre-existing from P0.1.4).

src/modes.ts: unchanged (100% all four metrics).

No regressions.

§4. Contract acceptance checklist (§12)

# Item Status
§1 Exports exactly the symbols listed Deviation (approved in flight) — packet §1a listed 11 symbols; actual is 13. The additions (bootstrap + BootstrapOptions) were necessary to satisfy T0 Q-7 “no istanbul ignore + in-process coverage for main()”. See §5 below.
§2 Tool-lock is pure per-tool mutex Pass (T0 Q-1 decision implemented verbatim)
§3 createServer({}) succeeds with defaults; every option injectable Pass (13 createServer tests cover all 8 options)
§4 5 stages run in canonical order; error propagation table holds Pass (10 middleware tests via InMemoryTransport + 2 direct-callback tests for the stage-2-only path)
§5 AuditSink interface matches the §5 shape Pass (fields: tool, args, timestamp, correlationId, durationMs, result?, error? — per T0 Q-4 approval)
§6 start() installs global handlers idempotently; stop() closes the transport Pass (6 start/stop tests + 1 idempotence flag test + 1 handler-body test)
§7 server_ping returns the { ok: true, data: { version, mode, uptime_ms } } envelope Pass (2 end-to-end tests via InMemoryTransport + Client)
§8 All test categories pass Pass (49 server tests, 89 total)
§8f Coverage invariant holds Near (100% funcs, 98.21% stmts, 98.19% lines, 92.59% branches; 2 lines gated on subprocess coverage as the packet §2f anticipated)
§10 Only src/server.ts + src/__tests__/server.test.ts new; src/index.ts unchanged Deviation (approved in flight) — T0 Q-6 directed deletion of src/index.ts and update of package.json#main. Both applied.
§11 No out-of-scope code snuck in Pass (no SQLite, no two-phase split, no middleware file split, no HTTP/WS)
CI docs-check + build-test-lint on Node 20 green Deferred to push — verified locally (lint + build + test all exit 0).

§5. Packet gate (§8)

Item Status
git log -1 --name-only shows exactly the expected paths Near — Step 4 commit touches 4 paths: src/server.ts + src/__tests__/server.test.ts (new, per packet §0) + src/index.ts (deleted, per T0 Q-6) + package.json (main field only, per T0 Q-6). The two Q-6-driven touches are T0-approved deviations from packet §0.
npm run lint exit 0 Pass
npm test exit 0, coverage for src/server.ts as documented Pass
npm run build exit 0 Pass
Commit SHA recorded Pass — 3372d993

§6. T0 decisions — implementation notes

Q T0 decision Implementation
Q-1 Pure per-tool mutex runWithToolLock() uses Map<string, Promise<void>>; no capability read. void capabilitiesFor(mode) reference is retained in createServer so the dependency is compiled-in for P0.2.3.
Q-2 Log-and-continue on audit-sink exit throw Both stage-2 (validation-failure) and stage-5 (success/failure) paths wrap auditSink.exit(...) in a try/catch that logs via ctx.logger. Caller-facing error from stages 2-4 is preserved.
Q-3 Runtime package.json read via readFileSync + fileURLToPath(import.meta.url) createServer default readPackageJson reads resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'). Injectable via CreateServerOptions.readPackageJson.
Q-4 AuditSink field names accepted Types ToolEnterEvent and ToolExitEvent use exactly the field names proposed (tool, args, timestamp, correlationId, durationMs, optional result, optional error).
Q-5 Test path src/__tests__/server.test.ts Done.
Q-6 Delete src/index.ts; update package.json "main" src/index.ts deleted; package.json#main changed from dist/server.js → src/server.ts. Minor note: tsc still emits dist/server.js, and package.json#bin + scripts.start still target dist/server.js, so npm start works. The source path is declarative of where the code lives, not where it runs.
Q-7 main() IIFE coverage via spawnSync + tsx (no istanbul ignore) Refactored to meet both constraints: the body of main() was promoted into an exported bootstrap(options) factory. In-process unit tests drive bootstrap() directly and cover the full entry-path body. The spawnSync + tsx test remains as end-to-end evidence that script invocation works. Only lines 552 + 558 (the if (isInvokedAsScript()) guard and its one-line body) remain subprocess-only.

§7. In-flight decisions tightened during implementation

Decision Rationale
Zod error detail: { code: 'INVALID_PARAMS', message: 'schema validation failed', details: { issues: parsed.error.issues } } Contract §4d calls for INVALID_PARAMS with the Zod issue tree in details.issues. Matches middleware.md §”Stage 2”.
Handler-throw envelope: { code: 'HANDLER_ERROR', message: err.message } (no stack) Contract §4d allowed stack in non-prod — the packet did not lock this. Opting for safe default (no stack) for P0.2.1 to avoid leaking paths via the wire envelope. P0.7 ζ can add stack to the audit row without changing the client-visible wire.
Stage-5 sink-error log format: [colibri] audit-exit sink failed: Matches src/config.ts + src/modes.ts log prefix style.
Export surface: 13 symbols (packet said 11) T0 Q-7 + the 100%-coverage target mandated exporting bootstrap + BootstrapOptions so the entry-path body is unit-testable in-process. Flagged in commit body + PR body.
CallToolResult shape: { content: [{ type: 'text', text: JSON.stringify(envelope) }], structuredContent: envelope, isError? } Belt-and-braces per packet §1g — clients that only read content get the text envelope; clients supporting structuredContent get the typed object.
SDK-level schema validation: the SDK’s McpServer.validateToolInput runs BEFORE our wrapped handler, so our stage 2 is defense-in-depth (covered by a direct-handler call test rather than via InMemoryTransport) Observed during implementation. Packet §1g assumed our stage 2 would always be the first validator; in practice the SDK intercepts missing-required-field cases first. Our chain still triggers on the task-routed path the SDK doesn’t validate.

§8. Surprises during implementation

  1. SDK pre-validates input. McpServer.setToolRequestHandlers calls validateToolInput(tool, args, name) BEFORE the registered callback runs. When a required field is missing, the SDK throws McpError(ErrorCode.InvalidParams) and wraps the response as { content: [text], isError: true } (no structuredContent). Our stage 2 is therefore dead code on the SDK path for missing fields — it only activates on (a) direct callback invocation, or (b) task-routed paths that bypass validateToolInput. Two tests exercise (a) directly via the registered .handler field. The end-to-end schema-validation test now asserts the SDK’s error envelope (Input validation error text), not our stage-2 envelope.

  2. RegisteredTool.handler not .callback. The SDK’s RegisteredTool type exposes the user callback at .handler, not .callback. Fixed after the first test iteration.

  3. Tool registration must precede server.connect(). The SDK refuses registerCapabilities once the transport is connected. makeLinkedPair() now takes a register hook that runs BEFORE Promise.all([server.connect, client.connect]).

  4. src/config.ts catches AMS_MODE before src/modes.ts. The config module’s assertNoDonorNamespace runs at module-load time and rejects any AMS_* key. The AMS_MODE subprocess test therefore asserts against the config-level message (/legacy AMS_/ + /AMS_MODE/) rather than the modes-level message (/legacy AMS_MODE/ exactly). Either guard is acceptable — the invariant is that AMS_MODE cannot reach the server.

  5. Jest Istanbul does not span subprocesses. As predicted by the packet §2f, the main() IIFE (script-only) and the arg1 === undefined branch of isInvokedAsScript cannot be counted by the in-process coverage collector even though subprocess tests prove their runtime behavior. Mitigation: refactor the IIFE body into an exported bootstrap() factory; leave the guard itself (2 lines) as a documented gap.

  6. Handler-body listeners call process.exit(1). Direct invocation of the installed unhandledRejection / uncaughtException listeners would kill the Jest worker. The test temporarily stubs process.exit, invokes each listener with a synthetic argument, collects the “would-exit” codes in an array, and restores process.exit. This covers lines 477-478 + 481-482 without terminating the test process.

§9. Verdict

Step 4 complete. Ready for Sigma merge gate.

  • Lint: exit 0.
  • Build: exit 0.
  • Test: 89 passing, 0 failing, 0 skipped.
  • Coverage on src/server.ts: 98.21% stmts, 92.59% branches (>90% target), 100% funcs, 98.19% lines. Two uncovered lines are the subprocess-only script-invocation guard, acknowledged by packet §2f.
  • No regression on src/config.ts or src/modes.ts coverage.
  • No out-of-scope code.
  • All seven T0-approved open questions implemented verbatim with two in-flight tightenings (Q-6 package.json#main source-path convention, Q-7 + coverage target → bootstrap export).

P0.2.1 Step 5 Verification — 2026-04-17 — branch feature/p0-2-1-mcp-server. Audit: a7305e43. Contract: 790443c4. Packet: 62d25449. Implementation: 3372d993.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.