@adrkit/mcp 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -9,6 +9,22 @@
 export interface AdrkitMcpServerOptions {
     readonly cwd: string;
     readonly dir: string;
+    /**
+     * Called for out-of-band transport failures: a transport that fails to start,
+     * and every background error the connection reports afterwards (an stdin or
+     * stdout stream error, such as the EPIPE from a client that has gone away).
+     *
+     * This is not optional plumbing. `serveStdio` reports these **only** through
+     * its `onerror` callback — it consumes the rejected `start()` promise
+     * deliberately — so without a callback a broken transport tears the connection
+     * down while the process still exits 0. That is a dead server reporting
+     * success, the fail-quiet shape ADR-0016 rejects, so the default writes a
+     * diagnostic to stderr rather than staying silent. `main-module.ts` supplies a
+     * reporter that also fails the exit status.
+     *
+     * Never writes to stdout: that is reserved for protocol frames.
+     */
+    readonly onError: (error: Error) => void;
 }
 export interface AdrkitMcpServerHandle {
     start(): Promise<void>;
@@ -16,8 +32,14 @@ export interface AdrkitMcpServerHandle {
 }
 /**
  * The public stdio lifecycle factory. Performs NO filesystem access at construction;
- * `start()` validates the configured root, builds the closure-private server, creates
- * exactly one `StdioServerTransport`, and connects it. The concrete server, its
+ * `start()` validates the configured root, then hands a closure-private server factory
+ * to the SDK's connection-pinned `serveStdio` entry. The concrete server, its
  * registrations, and its transport remain unreachable to the caller.
+ *
+ * `serveStdio` — not a hand-wired `StdioServerTransport` — is what makes this server
+ * speak protocol revision 2026-07-28. The opening exchange selects the connection's
+ * era and pins one factory instance to it; `legacy: 'serve'` (the default) keeps
+ * 2025-era clients working unchanged. The four tools are registered once and served
+ * identically to both eras.
  */
 export declare function createAdrkitMcpServer(options?: Partial<AdrkitMcpServerOptions>): Readonly<AdrkitMcpServerHandle>;

package/dist/index.js

@@ -1,20 +1,18 @@
 // src/index.ts
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { resolve as resolve2 } from "node:path";
 
 // src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 
 // src/corpus/ordering.ts
-function compareCodeUnits(a, b) {
-  return a < b ? -1 : a > b ? 1 : 0;
-}
-function compareFindings(a, b) {
-  return compareCodeUnits(a.rule, b.rule) || compareCodeUnits(a.id ?? "", b.id ?? "") || compareCodeUnits(a.pattern ?? "", b.pattern ?? "") || compareCodeUnits(a.path ?? "", b.path ?? "") || compareCodeUnits(a.field ?? "", b.field ?? "") || compareCodeUnits(a.message, b.message);
-}
-function sortFindingsCanonical(findings) {
-  return [...findings].sort(compareFindings);
-}
+import {
+  compareByIdThenPath,
+  compareCodeUnits,
+  compareFindings,
+  sortByIdThenPath,
+  sortFindingsCanonical
+} from "@adrkit/core";
 
 // src/search/normalize.ts
 function normalize(value) {
@@ -105,9 +103,13 @@ import { AdrFrontmatter, AdrRef, Status, Scope } from "@adrkit/core";
 
 // src/corpus/projection.ts
 import { access, constants as FS, lstat, realpath, stat } from "node:fs/promises";
-import { createHash as createHash2 } from "node:crypto";
 import { isAbsolute, relative, resolve, sep } from "node:path";
-import { discoverAdrFiles, lintCorpus, normalizeDisplayPath } from "@adrkit/core";
+import {
+  discoverAdrFiles,
+  fingerprintOf,
+  lintCorpus,
+  normalizeDisplayPath
+} from "@adrkit/core";
 var MAX_SOURCE_BYTES = 64 * 1024;
 
 class CorpusUnavailableError extends Error {
@@ -205,29 +207,6 @@ async function verifyRoots(options) {
     fail("root-not-found");
   return roots;
 }
-function canonicalStringify(value) {
-  if (value === null || value === undefined)
-    return "null";
-  if (typeof value === "number" || typeof value === "boolean" || typeof value === "string") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value))
-    return `[${value.map(canonicalStringify).join(",")}]`;
-  if (typeof value === "object") {
-    const record = value;
-    const keys = Object.keys(record).filter((key) => record[key] !== undefined).sort(compareCodeUnits);
-    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalStringify(record[key])}`).join(",")}}`;
-  }
-  return "null";
-}
-function fingerprintOf(records, corpusFindings, recordCount, excludedCount) {
-  const projection = {
-    records: records.map((record) => ({ sourcePath: record.path, frontmatter: record.frontmatter, body: record.body })),
-    corpusFindings,
-    corpusHealth: { recordCount, excludedCount }
-  };
-  return createHash2("sha256").update(canonicalStringify(projection), "utf8").digest("hex");
-}
 async function loadCorpusProjection(options) {
   const roots = await verifyRoots(options);
   let candidates;
@@ -499,7 +478,7 @@ function searchDecisionsOutputSchema() {
     sourcePath: z.string(),
     matchedFields: z.array(z.enum(["id", "title", "tag", "body"]))
   });
-  return {
+  return z.object({
     corpusHealth: corpusHealthSchema().optional(),
     result: z.discriminatedUnion("outcome", [
       z.object({
@@ -511,7 +490,7 @@ function searchDecisionsOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function getDecisionOutputSchema() {
   const fullDecision = z.object({
@@ -523,7 +502,7 @@ function getDecisionOutputSchema() {
     frontmatter: AdrFrontmatter,
     body: z.string()
   });
-  return {
+  return z.object({
     corpusHealth: corpusHealthSchema().optional(),
     result: z.discriminatedUnion("outcome", [
       z.object({ outcome: z.literal("found"), decision: fullDecision, findings: findingsPageSchema() }),
@@ -545,7 +524,7 @@ function getDecisionOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function getDecisionContextOutputSchema() {
   const contextEntry = z.object({
@@ -556,7 +535,7 @@ function getDecisionContextOutputSchema() {
     firedMatchers: z.array(z.object({ type: z.string(), pattern: z.string() })),
     relations: relationRefsSchema()
   });
-  return {
+  return z.object({
     corpusHealth: corpusHealthSchema().optional(),
     result: z.discriminatedUnion("outcome", [
       z.object({
@@ -570,7 +549,7 @@ function getDecisionContextOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function listSupersededOutputSchema() {
   const supersededBy = z.union([
@@ -597,7 +576,7 @@ function listSupersededOutputSchema() {
     sourcePath: z.string(),
     supersededBy
   });
-  return {
+  return z.object({
     corpusHealth: corpusHealthSchema().optional(),
     result: z.discriminatedUnion("outcome", [
       z.object({
@@ -609,7 +588,7 @@ function listSupersededOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function structuredResult(result, text, corpusHealth) {
   const structuredContent = corpusHealth === undefined ? { result } : { corpusHealth, result };
@@ -843,13 +822,9 @@ function registerGetDecision(server, config) {
 }
 
 // src/tools/get-decision-context.ts
-import { resolveAffects } from "@adrkit/core";
+import { decisionBucketFor, resolveAffects } from "@adrkit/core";
 function bucketFor(status) {
-  if (status === "accepted")
-    return "governing";
-  if (status === "draft" || status === "proposed")
-    return "activeProposals";
-  return "history";
+  return decisionBucketFor(status);
 }
 function contextEntry(record, firedMatchers) {
   return { ...toSummary(record), firedMatchers, relations: toRelationRefs(record.frontmatter) };
@@ -1016,21 +991,30 @@ function registerListSuperseded(server, config) {
 }
 
 // src/server.ts
-var SERVER_INFO = { name: "@adrkit/mcp", version: "0.1.0" };
+var SERVER_INFO = { name: "@adrkit/mcp", version: "0.3.0" };
+var CACHE_HINTS = {
+  "tools/list": { ttlMs: 300000, cacheScope: "public" },
+  "server/discover": { ttlMs: 300000, cacheScope: "public" }
+};
 function buildRegisteredServer(config) {
-  const server = new McpServer(SERVER_INFO);
-  registerSearchDecisions(server, config);
+  const server = new McpServer(SERVER_INFO, { cacheHints: CACHE_HINTS });
   registerGetDecision(server, config);
   registerGetDecisionContext(server, config);
   registerListSuperseded(server, config);
+  registerSearchDecisions(server, config);
   return server;
 }
 
 // src/index.ts
+function writeTransportDiagnostic(error) {
+  process.stderr.write(`adrkit-mcp: transport error: ${error.message}
+`);
+}
 function createAdrkitMcpServer(options) {
   const cwd = resolve2(options?.cwd ?? process.cwd());
   const dir = options?.dir ?? "docs/adr";
-  let server;
+  const onError = options?.onError ?? writeTransportDiagnostic;
+  let connection;
   let startPromise;
   let closePromise;
   let closed = false;
@@ -1041,7 +1025,6 @@ function createAdrkitMcpServer(options) {
     if (startPromise)
       return startPromise;
     startPromise = (async () => {
-      let nextServer;
       try {
         const roots = await resolveCanonicalRoots({ cwd, dir });
         const config = {
@@ -1050,19 +1033,9 @@ function createAdrkitMcpServer(options) {
           expectedCanonicalCwd: roots.canonicalCwd,
           maxSourceBytes: MAX_SOURCE_BYTES
         };
-        nextServer = buildRegisteredServer(config);
-        server = nextServer;
-        await nextServer.connect(new StdioServerTransport);
+        connection = serveStdio(() => buildRegisteredServer(config), { onerror: onError });
       } catch (error) {
-        server = undefined;
-        if (nextServer) {
-          try {
-            await nextServer.close();
-          } catch (closeError) {
-            startPromise = undefined;
-            throw new AggregateError([error, closeError], "MCP server startup and cleanup failed");
-          }
-        }
+        connection = undefined;
         startPromise = undefined;
         throw error;
       }
@@ -1076,8 +1049,8 @@ function createAdrkitMcpServer(options) {
     closePromise = (async () => {
       if (startPromise)
         await startPromise;
-      const current = server;
-      server = undefined;
+      const current = connection;
+      connection = undefined;
       if (current)
         await current.close();
     })();

package/dist/main-module.d.ts

@@ -8,4 +8,13 @@
  */
 export declare function isMainModule(moduleUrl: string, argvPath: string | undefined): boolean;
 export declare function reportUnhandledRejection(reason: unknown, write?: (text: string) => void, fail?: () => void): void;
+/**
+ * Out-of-band transport failures reach the bin here.
+ *
+ * `serveStdio` reports them only through its `onerror` callback — it consumes
+ * the rejected `start()` promise itself — so this is the only path by which a
+ * broken transport can reach stderr and a non-zero exit status. Without it the
+ * connection tears down while the process still exits 0 (ADR-0016).
+ */
+export declare function reportTransportError(error: Error, write?: (text: string) => void, fail?: () => void): void;
 export declare function main(argv: string[], env: Record<string, string | undefined>): Promise<0 | 1 | 2>;

package/dist/server.d.ts

@@ -6,11 +6,25 @@
  * exposes only the sealed lifecycle handle. This module is absent from
  * `package.json#exports` and every public subpath.
  */
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/server';
 import type { ToolConfig } from './tools/shared.js';
 export declare const SERVER_INFO: {
     readonly name: "@adrkit/mcp";
-    readonly version: "0.1.0";
+    readonly version: "0.3.0";
 };
-/** Package-internal: build the concrete server with exactly the four ratified tools. */
+/**
+ * The MCP protocol revision this server serves through `serveStdio`'s modern era.
+ *
+ * The SDK keeps the revision string internal (`LATEST_PROTOCOL_VERSION` names the
+ * latest *legacy*-era version, `2025-11-25`), so the modern revision is stated here
+ * once and asserted against the wire in `test/bin.test.ts`.
+ */
+export declare const MODERN_PROTOCOL_VERSION: "2026-07-28";
+/**
+ * Package-internal: build the concrete server with exactly the four ratified tools.
+ *
+ * Registration order is lexicographic by tool name so `tools/list` answers in a
+ * deterministic, self-evidently stable order (2026-07-28 minor change 3 — servers
+ * SHOULD do this so clients can cache catalogs and keep upstream prompt caches warm).
+ */
 export declare function buildRegisteredServer(config: ToolConfig): McpServer;

package/dist/tools/get-decision-context.d.ts

@@ -6,6 +6,6 @@
  * reading a caller-supplied path. One canonical flat walk is paginated, then the
  * page is partitioned by status.
  */
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from '@modelcontextprotocol/server';
 import { type ToolConfig } from './shared.js';
 export declare function registerGetDecisionContext(server: McpServer, config: ToolConfig): void;

package/dist/tools/get-decision.d.ts

@@ -6,6 +6,6 @@
  * resolved through the fresh local `byId` bucket into found / not-found /
  * ambiguous-local-id. Relation refs are surfaced verbatim, never expanded.
  */
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from '@modelcontextprotocol/server';
 import { type ToolConfig } from './shared.js';
 export declare function registerGetDecision(server: McpServer, config: ToolConfig): void;

package/dist/tools/list-superseded.d.ts

@@ -6,6 +6,6 @@
  * lineage, never embeds candidate arrays, and mints only the two specified derived
  * finding templates.
  */
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from '@modelcontextprotocol/server';
 import { type ToolConfig } from './shared.js';
 export declare function registerListSuperseded(server: McpServer, config: ToolConfig): void;

package/dist/tools/search-decisions.d.ts

@@ -6,6 +6,6 @@
  * normalizer. Graveyard records are included by default. Returns bounded summaries
  * only — never a body, ranking score, or hidden index.
  */
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from '@modelcontextprotocol/server';
 import { type ToolConfig } from './shared.js';
 export declare function registerSearchDecisions(server: McpServer, config: ToolConfig): void;

package/dist/tools/shared.d.ts

@@ -6,7 +6,7 @@
  */
 import { z } from 'zod';
 import { AdrFrontmatter, Status, Scope, type Finding, type FiredMatcher } from '@adrkit/core';
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult } from '@modelcontextprotocol/server';
 import { type CorpusHealth, type CorpusProjection, type CorpusUnavailableReason } from '../corpus/projection.js';
 import type { InvalidCursorReason, Page } from '../pagination/cursor.js';
 export type { Finding, FiredMatcher } from '@adrkit/core';
@@ -215,7 +215,7 @@ export type TextSpec = {
 export declare function cap512(value: string): string;
 export declare function renderResponseText(spec: TextSpec): string;
 export type ToolInputSchema = z.ZodType;
-export type ToolOutputSchema = z.ZodRawShape;
+export type ToolOutputSchema = z.ZodType;
 export declare function searchDecisionsInputSchema(): ToolInputSchema;
 export declare function getDecisionInputSchema(): ToolInputSchema;
 export declare function getDecisionContextInputSchema(): ToolInputSchema;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@adrkit/mcp",
-  "version": "0.2.0",
+  "mcpName": "dev.adrkit/mcp",
+  "version": "0.3.0",
   "description": "Local, read-only Model Context Protocol server exposing adrkit decision retrieval over stdio.",
   "type": "module",
   "license": "Apache-2.0",
@@ -44,11 +45,12 @@
     "typecheck": "tsc --noEmit --customConditions bun --project ../../tsconfig.json"
   },
   "dependencies": {
-    "@adrkit/core": "0.2.0",
-    "@modelcontextprotocol/sdk": "1.29.0",
-    "zod": "^4"
+    "@adrkit/core": "0.3.0",
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "^4.2.0"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
     "@types/bun": "latest"
   },
   "files": [

package/src/corpus/ordering.ts

@@ -1,41 +1,16 @@
 /**
- * @adrkit/mcp — the one locale-independent comparator and the canonical orderings
- * every channel uses. Never `String.prototype.localeCompare` (research §R6).
+ * @adrkit/mcp — re-export shim.
+ *
+ * The comparator and canonical orderings were promoted to `@adrkit/core`
+ * (`packages/core/src/ordering/index.ts`). This module preserves every existing
+ * `../corpus/ordering` import site while the single implementation now lives in core.
  */
 
-import type { Finding } from '@adrkit/core';
-
-/** The sole code-unit comparator: `a < b ? -1 : a > b ? 1 : 0` over UTF-16 units. */
-export function compareCodeUnits(a: string, b: string): number {
-  return a < b ? -1 : a > b ? 1 : 0;
-}
-
-export interface OrderedSummary {
-  readonly id: string;
-  readonly sourcePath: string;
-}
-
-/** Canonical `(id, sourcePath)` ascending order; sourcePath is the unique tiebreak. */
-export function compareByIdThenPath(a: OrderedSummary, b: OrderedSummary): number {
-  return compareCodeUnits(a.id, b.id) || compareCodeUnits(a.sourcePath, b.sourcePath);
-}
-
-/** Canonical finding order using `sortFindings`' field tuple with the code-unit comparator. */
-export function compareFindings(a: Finding, b: Finding): number {
-  return (
-    compareCodeUnits(a.rule, b.rule) ||
-    compareCodeUnits(a.id ?? '', b.id ?? '') ||
-    compareCodeUnits(a.pattern ?? '', b.pattern ?? '') ||
-    compareCodeUnits(a.path ?? '', b.path ?? '') ||
-    compareCodeUnits(a.field ?? '', b.field ?? '') ||
-    compareCodeUnits(a.message, b.message)
-  );
-}
-
-export function sortFindingsCanonical(findings: readonly Finding[]): Finding[] {
-  return [...findings].sort(compareFindings);
-}
-
-export function sortByIdThenPath<T extends OrderedSummary>(items: readonly T[]): T[] {
-  return [...items].sort(compareByIdThenPath);
-}
+export {
+  compareByIdThenPath,
+  compareCodeUnits,
+  compareFindings,
+  sortByIdThenPath,
+  sortFindingsCanonical,
+  type OrderedSummary,
+} from '@adrkit/core';

package/src/corpus/projection.ts

@@ -8,9 +8,15 @@
  */
 
 import { access, constants as FS, lstat, realpath, stat } from 'node:fs/promises';
-import { createHash } from 'node:crypto';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
-import { discoverAdrFiles, lintCorpus, normalizeDisplayPath, type Adr, type Finding } from '@adrkit/core';
+import {
+  discoverAdrFiles,
+  fingerprintOf,
+  lintCorpus,
+  normalizeDisplayPath,
+  type Adr,
+  type Finding,
+} from '@adrkit/core';
 import { compareCodeUnits, sortFindingsCanonical } from './ordering.ts';
 
 export const MAX_SOURCE_BYTES = 64 * 1024;
@@ -169,31 +175,6 @@ async function verifyRoots(options: LoadCorpusProjectionOptions): Promise<Canoni
   return roots;
 }
 
-function canonicalStringify(value: unknown): string {
-  if (value === null || value === undefined) return 'null';
-  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'string') {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) return `[${value.map(canonicalStringify).join(',')}]`;
-  if (typeof value === 'object') {
-    const record = value as Record<string, unknown>;
-    const keys = Object.keys(record)
-      .filter((key) => record[key] !== undefined)
-      .sort(compareCodeUnits);
-    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalStringify(record[key])}`).join(',')}}`;
-  }
-  return 'null';
-}
-
-function fingerprintOf(records: readonly Adr[], corpusFindings: readonly Finding[], recordCount: number, excludedCount: number): string {
-  const projection = {
-    records: records.map((record) => ({ sourcePath: record.path, frontmatter: record.frontmatter, body: record.body })),
-    corpusFindings,
-    corpusHealth: { recordCount, excludedCount },
-  };
-  return createHash('sha256').update(canonicalStringify(projection), 'utf8').digest('hex');
-}
-
 /** The one entry point every tool handler calls, fresh, at the start of its execution. */
 export async function loadCorpusProjection(options: LoadCorpusProjectionOptions): Promise<CorpusProjection> {
   const roots = await verifyRoots(options);

package/src/index.ts

@@ -7,8 +7,7 @@
  * construction time (data-model.md §8, contracts/tools.md §1).
  */
 
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { serveStdio, type StdioServerHandle } from '@modelcontextprotocol/server/stdio';
 import { resolve } from 'node:path';
 import { buildRegisteredServer } from './server.ts';
 import { resolveCanonicalRoots, MAX_SOURCE_BYTES } from './corpus/projection.ts';
@@ -17,6 +16,22 @@ import type { ToolConfig } from './tools/shared.ts';
 export interface AdrkitMcpServerOptions {
   readonly cwd: string;
   readonly dir: string;
+  /**
+   * Called for out-of-band transport failures: a transport that fails to start,
+   * and every background error the connection reports afterwards (an stdin or
+   * stdout stream error, such as the EPIPE from a client that has gone away).
+   *
+   * This is not optional plumbing. `serveStdio` reports these **only** through
+   * its `onerror` callback — it consumes the rejected `start()` promise
+   * deliberately — so without a callback a broken transport tears the connection
+   * down while the process still exits 0. That is a dead server reporting
+   * success, the fail-quiet shape ADR-0016 rejects, so the default writes a
+   * diagnostic to stderr rather than staying silent. `main-module.ts` supplies a
+   * reporter that also fails the exit status.
+   *
+   * Never writes to stdout: that is reserved for protocol frames.
+   */
+  readonly onError: (error: Error) => void;
 }
 
 export interface AdrkitMcpServerHandle {
@@ -24,19 +39,30 @@ export interface AdrkitMcpServerHandle {
   close(): Promise<void>;
 }
 
+function writeTransportDiagnostic(error: Error): void {
+  process.stderr.write(`adrkit-mcp: transport error: ${error.message}\n`);
+}
+
 /**
  * The public stdio lifecycle factory. Performs NO filesystem access at construction;
- * `start()` validates the configured root, builds the closure-private server, creates
- * exactly one `StdioServerTransport`, and connects it. The concrete server, its
+ * `start()` validates the configured root, then hands a closure-private server factory
+ * to the SDK's connection-pinned `serveStdio` entry. The concrete server, its
  * registrations, and its transport remain unreachable to the caller.
+ *
+ * `serveStdio` — not a hand-wired `StdioServerTransport` — is what makes this server
+ * speak protocol revision 2026-07-28. The opening exchange selects the connection's
+ * era and pins one factory instance to it; `legacy: 'serve'` (the default) keeps
+ * 2025-era clients working unchanged. The four tools are registered once and served
+ * identically to both eras.
  */
 export function createAdrkitMcpServer(
   options?: Partial<AdrkitMcpServerOptions>,
 ): Readonly<AdrkitMcpServerHandle> {
   const cwd = resolve(options?.cwd ?? process.cwd());
   const dir = options?.dir ?? 'docs/adr';
+  const onError = options?.onError ?? writeTransportDiagnostic;
 
-  let server: McpServer | undefined;
+  let connection: StdioServerHandle | undefined;
   let startPromise: Promise<void> | undefined;
   let closePromise: Promise<void> | undefined;
   let closed = false;
@@ -48,7 +74,6 @@ export function createAdrkitMcpServer(
     if (startPromise) return startPromise;
 
     startPromise = (async () => {
-      let nextServer: McpServer | undefined;
       try {
         const roots = await resolveCanonicalRoots({ cwd, dir });
         const config: ToolConfig = {
@@ -57,19 +82,9 @@ export function createAdrkitMcpServer(
           expectedCanonicalCwd: roots.canonicalCwd,
           maxSourceBytes: MAX_SOURCE_BYTES,
         };
-        nextServer = buildRegisteredServer(config);
-        server = nextServer;
-        await nextServer.connect(new StdioServerTransport());
+        connection = serveStdio(() => buildRegisteredServer(config), { onerror: onError });
       } catch (error) {
-        server = undefined;
-        if (nextServer) {
-          try {
-            await nextServer.close();
-          } catch (closeError) {
-            startPromise = undefined;
-            throw new AggregateError([error, closeError], 'MCP server startup and cleanup failed');
-          }
-        }
+        connection = undefined;
         startPromise = undefined;
         throw error;
       }
@@ -82,8 +97,8 @@ export function createAdrkitMcpServer(
     closed = true;
     closePromise = (async () => {
       if (startPromise) await startPromise;
-      const current = server;
-      server = undefined;
+      const current = connection;
+      connection = undefined;
       if (current) await current.close();
     })();
     return closePromise;

package/src/main-module.ts

@@ -37,6 +37,25 @@ export function reportUnhandledRejection(
   fail();
 }
 
+/**
+ * Out-of-band transport failures reach the bin here.
+ *
+ * `serveStdio` reports them only through its `onerror` callback — it consumes
+ * the rejected `start()` promise itself — so this is the only path by which a
+ * broken transport can reach stderr and a non-zero exit status. Without it the
+ * connection tears down while the process still exits 0 (ADR-0016).
+ */
+export function reportTransportError(
+  error: Error,
+  write: (text: string) => void = writeStderr,
+  fail: () => void = () => {
+    process.exitCode = 1;
+  },
+): void {
+  write(`adrkit-mcp: transport error: ${error.message}\n`);
+  fail();
+}
+
 export async function main(
   argv: string[],
   env: Record<string, string | undefined>,
@@ -68,7 +87,7 @@ export async function main(
     throw error;
   }
 
-  const handle = createAdrkitMcpServer({ cwd, dir });
+  const handle = createAdrkitMcpServer({ cwd, dir, onError: (error) => reportTransportError(error) });
 
   const shutdown = (): void => {
     void handle.close().finally(() => process.exit(0));