@adrkit/mcp 0.2.1 → 0.3.0

package/README.md

@@ -16,8 +16,10 @@ agents stop re-proposing paths the team already ruled out.
 
 Part of [adrkit](https://adrkit.dev). The corpus lives in git as one Markdown file
 per decision with typed YAML frontmatter (`@adrkit/core`); this server only reads
-it. Registry namespace: **`dev.adrkit/mcp`** (this is the Node/npm `@adrkit/mcp`
-package — unrelated to the `adr-kit` Python package on PyPI).
+it. Listed in the [official MCP registry](https://registry.modelcontextprotocol.io)
+as **`dev.adrkit/mcp`** (this is the Node/npm `@adrkit/mcp` package — unrelated to
+the `adr-kit` Python package on PyPI). A registry listing is distribution, not
+adoption; see Maturity below.
 
 ## Maturity
 
@@ -40,6 +42,30 @@ npx -y @adrkit/mcp --cwd /path/to/your/repo --dir docs/adr
 It speaks JSON-RPC over stdio, so you normally point an MCP client at it rather than
 running it by hand. Copy-pasteable client configs follow.
 
+### Protocol revisions
+
+The server speaks **both** MCP protocol eras on the same stdio connection, and the
+client picks. The opening exchange selects the era and pins it for the connection's
+lifetime:
+
+| Client opens with                                     | Server serves                                     |
+| ----------------------------------------------------- | ------------------------------------------------- |
+| `server/discover`, or any request carrying a 2026 `_meta` envelope | **`2026-07-28`** — stateless, no handshake |
+| `initialize` / `notifications/initialized`            | the 2025-era revision it negotiates               |
+
+On `2026-07-28` there is no `initialize` handshake and no session id: every request
+carries its own protocol version and client capabilities in `_meta`, and every result
+is self-describing (`resultType`, plus server identity in `_meta`). `tools/list` and
+`server/discover` are cacheable (SEP-2549) and are served with `ttlMs: 300000,
+cacheScope: "public"` — the four-tool surface is immutable for the life of the process
+and carries no corpus content, so a client may reuse it instead of re-listing. Corpus
+reads are never cacheable: every `tools/call` loads a fresh projection.
+
+Nothing else about the tools changes between eras — same names, same schemas, same
+annotations, same structured results. The server uses none of the features the
+`2026-07-28` revision deprecated (roots, sampling, logging) or removed (sessions,
+`ping`, `resources/subscribe`).
+
 ### Claude Desktop
 
 Edit `claude_desktop_config.json` (macOS:
@@ -282,7 +308,7 @@ the underlying SDK server, its registrations, or its transport:
 import { createAdrkitMcpServer } from '@adrkit/mcp';
 
 const server = createAdrkitMcpServer({ cwd: process.cwd(), dir: 'docs/adr' });
-await server.start();   // validates the root, connects exactly one stdio transport
+await server.start();   // validates the root, then serves one stdio connection
 // ... later:
 await server.close();
 ```
@@ -290,6 +316,12 @@ await server.close();
 `createAdrkitMcpServer(options?)` performs no filesystem access at construction and
 returns a frozen, null-prototype handle with exactly `start()` and `close()`.
 
+Transport failures — a transport that fails to start, or a background stream error
+such as the `EPIPE` from a client that has gone away — are reported through the
+optional `onError` option, which defaults to a stderr diagnostic. The `adrkit-mcp`
+binary additionally exits non-zero. Nothing is written to stdout: that is reserved
+for protocol frames.
+
 ## Limits
 
 `query` 1–256 code units (non-empty after trimming); `ref` 1–128; `files[]` 1–256
@@ -323,6 +355,6 @@ traversal.
 
 Developed and tested with Bun; published artifacts are ESM targeting Node.js `>=22`
 and are verified on Node 22 and 24. Runtime dependencies are exactly `@adrkit/core`,
-`@modelcontextprotocol/sdk`, and `zod`.
+`@modelcontextprotocol/server` (MCP TypeScript SDK v2), and `zod`.
 
 Apache-2.0.

package/dist/bin.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 // 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
 import {
@@ -480,7 +480,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({
@@ -492,7 +492,7 @@ function searchDecisionsOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function getDecisionOutputSchema() {
   const fullDecision = z.object({
@@ -504,7 +504,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() }),
@@ -526,7 +526,7 @@ function getDecisionOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function getDecisionContextOutputSchema() {
   const contextEntry = z.object({
@@ -537,7 +537,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({
@@ -551,7 +551,7 @@ function getDecisionContextOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function listSupersededOutputSchema() {
   const supersededBy = z.union([
@@ -578,7 +578,7 @@ function listSupersededOutputSchema() {
     sourcePath: z.string(),
     supersededBy
   });
-  return {
+  return z.object({
     corpusHealth: corpusHealthSchema().optional(),
     result: z.discriminatedUnion("outcome", [
       z.object({
@@ -590,7 +590,7 @@ function listSupersededOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function structuredResult(result, text, corpusHealth) {
   const structuredContent = corpusHealth === undefined ? { result } : { corpusHealth, result };
@@ -993,21 +993,30 @@ function registerListSuperseded(server, config) {
 }
 
 // src/server.ts
-var SERVER_INFO = { name: "@adrkit/mcp", version: "0.2.1" };
+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;
@@ -1018,7 +1027,6 @@ function createAdrkitMcpServer(options) {
     if (startPromise)
       return startPromise;
     startPromise = (async () => {
-      let nextServer;
       try {
         const roots = await resolveCanonicalRoots({ cwd, dir });
         const config = {
@@ -1027,19 +1035,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;
       }
@@ -1053,8 +1051,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();
     })();
@@ -1088,6 +1086,13 @@ function reportUnhandledRejection(reason, write = writeStderr, fail2 = () => {
 `);
   fail2();
 }
+function reportTransportError(error, write = writeStderr, fail2 = () => {
+  process.exitCode = 1;
+}) {
+  write(`adrkit-mcp: transport error: ${error.message}
+`);
+  fail2();
+}
 async function main(argv, env) {
   let values;
   try {
@@ -1114,7 +1119,7 @@ ${USAGE}`);
     }
     throw error;
   }
-  const handle = createAdrkitMcpServer({ cwd, dir });
+  const handle = createAdrkitMcpServer({ cwd, dir, onError: (error) => reportTransportError(error) });
   const shutdown = () => {
     handle.close().finally(() => process.exit(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,9 +1,9 @@
 // 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
 import {
@@ -478,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({
@@ -490,7 +490,7 @@ function searchDecisionsOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function getDecisionOutputSchema() {
   const fullDecision = z.object({
@@ -502,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() }),
@@ -524,7 +524,7 @@ function getDecisionOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function getDecisionContextOutputSchema() {
   const contextEntry = z.object({
@@ -535,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({
@@ -549,7 +549,7 @@ function getDecisionContextOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function listSupersededOutputSchema() {
   const supersededBy = z.union([
@@ -576,7 +576,7 @@ function listSupersededOutputSchema() {
     sourcePath: z.string(),
     supersededBy
   });
-  return {
+  return z.object({
     corpusHealth: corpusHealthSchema().optional(),
     result: z.discriminatedUnion("outcome", [
       z.object({
@@ -588,7 +588,7 @@ function listSupersededOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function structuredResult(result, text, corpusHealth) {
   const structuredContent = corpusHealth === undefined ? { result } : { corpusHealth, result };
@@ -991,21 +991,30 @@ function registerListSuperseded(server, config) {
 }
 
 // src/server.ts
-var SERVER_INFO = { name: "@adrkit/mcp", version: "0.2.1" };
+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;
@@ -1016,7 +1025,6 @@ function createAdrkitMcpServer(options) {
     if (startPromise)
       return startPromise;
     startPromise = (async () => {
-      let nextServer;
       try {
         const roots = await resolveCanonicalRoots({ cwd, dir });
         const config = {
@@ -1025,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;
       }
@@ -1051,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.2.1";
+    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,7 +1,7 @@
 {
   "name": "@adrkit/mcp",
   "mcpName": "dev.adrkit/mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Local, read-only Model Context Protocol server exposing adrkit decision retrieval over stdio.",
   "type": "module",
   "license": "Apache-2.0",
@@ -45,11 +45,12 @@
     "typecheck": "tsc --noEmit --customConditions bun --project ../../tsconfig.json"
   },
   "dependencies": {
-    "@adrkit/core": "0.2.1",
-    "@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/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));

package/src/server.ts

@@ -7,21 +7,54 @@
  * `package.json#exports` and every public subpath.
  */
 
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, type ServerOptions } from '@modelcontextprotocol/server';
 import { registerSearchDecisions } from './tools/search-decisions.ts';
 import { registerGetDecision } from './tools/get-decision.ts';
 import { registerGetDecisionContext } from './tools/get-decision-context.ts';
 import { registerListSuperseded } from './tools/list-superseded.ts';
 import type { ToolConfig } from './tools/shared.ts';
 
-export const SERVER_INFO = { name: '@adrkit/mcp', version: '0.2.1' } as const;
+export const SERVER_INFO = { name: '@adrkit/mcp', version: '0.3.0' } as const;
 
-/** 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 const MODERN_PROTOCOL_VERSION = '2026-07-28' as const;
+
+/**
+ * SEP-2549 cache hints for the two cacheable results this server can answer.
+ *
+ * Both are immutable for the lifetime of the process and carry no corpus content,
+ * caller identity, or per-request state: `tools/list` is the four ratified tools with
+ * their fixed schemas and annotations, and `server/discover` is the supported
+ * revisions plus the tools capability. They are therefore honestly `public` and safe
+ * to cache, which spares an agent a round trip per re-list. Corpus reads are NOT
+ * cacheable and are unaffected — every `tools/call` still loads a fresh projection.
+ *
+ * Without this the SDK falls back to the conservative `{ ttlMs: 0, cacheScope:
+ * 'private' }`. 2025-era responses never carry these fields either way.
+ */
+const CACHE_HINTS = {
+  'tools/list': { ttlMs: 300_000, cacheScope: 'public' },
+  'server/discover': { ttlMs: 300_000, cacheScope: 'public' },
+} as const satisfies ServerOptions['cacheHints'];
+
+/**
+ * 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 function buildRegisteredServer(config: ToolConfig): McpServer {
-  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;
 }

package/src/tools/get-decision-context.ts

@@ -7,7 +7,7 @@
  * page is partitioned by status.
  */
 
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from '@modelcontextprotocol/server';
 import { decisionBucketFor, resolveAffects, type Adr, type Finding, type FiredMatcher } from '@adrkit/core';
 import { compareCodeUnits, sortFindingsCanonical } from '../corpus/ordering.ts';
 import { paginate, queryShapeHash } from '../pagination/cursor.ts';

package/src/tools/get-decision.ts

@@ -7,7 +7,7 @@
  * 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 { parseAdrRef, type Adr } from '@adrkit/core';
 import { paginate, queryShapeHash, checkInapplicablePrimaryCursor } from '../pagination/cursor.ts';
 import {

package/src/tools/list-superseded.ts

@@ -7,7 +7,7 @@
  * finding templates.
  */
 
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from '@modelcontextprotocol/server';
 import { parseAdrRef, type Adr, type Finding } from '@adrkit/core';
 import { sortFindingsCanonical } from '../corpus/ordering.ts';
 import { paginate, queryShapeHash } from '../pagination/cursor.ts';

package/src/tools/search-decisions.ts

@@ -7,7 +7,7 @@
  * 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 { Adr } from '@adrkit/core';
 import { compareCodeUnits } from '../corpus/ordering.ts';
 import { normalize } from '../search/normalize.ts';

package/src/tools/shared.ts

@@ -7,7 +7,7 @@
 
 import { z } from 'zod';
 import { AdrFrontmatter, AdrRef, Status, Scope, type Finding, type FiredMatcher } from '@adrkit/core';
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult } from '@modelcontextprotocol/server';
 import {
   loadCorpusProjection,
   CorpusUnavailableError,
@@ -265,7 +265,7 @@ export function renderResponseText(spec: TextSpec): string {
  * ------------------------------------------------------------------ */
 
 export type ToolInputSchema = z.ZodType;
-export type ToolOutputSchema = z.ZodRawShape;
+export type ToolOutputSchema = z.ZodType;
 
 const uniqueArray = <T>(schema: z.ZodType<T>, min: number, max: number) =>
   z
@@ -392,7 +392,7 @@ export function searchDecisionsOutputSchema(): ToolOutputSchema {
     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({
@@ -404,7 +404,7 @@ export function searchDecisionsOutputSchema(): ToolOutputSchema {
       invalidCursorSchema(),
       corpusUnavailableSchema(),
     ]),
-  };
+  });
 }
 
 export function getDecisionOutputSchema(): ToolOutputSchema {
@@ -417,7 +417,7 @@ export function getDecisionOutputSchema(): ToolOutputSchema {
     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() }),
@@ -439,7 +439,7 @@ export function getDecisionOutputSchema(): ToolOutputSchema {
       invalidCursorSchema(),
       corpusUnavailableSchema(),
     ]),
-  };
+  });
 }
 
 export function getDecisionContextOutputSchema(): ToolOutputSchema {
@@ -451,7 +451,7 @@ export function getDecisionContextOutputSchema(): ToolOutputSchema {
     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({
@@ -465,7 +465,7 @@ export function getDecisionContextOutputSchema(): ToolOutputSchema {
       invalidCursorSchema(),
       corpusUnavailableSchema(),
     ]),
-  };
+  });
 }
 
 export function listSupersededOutputSchema(): ToolOutputSchema {
@@ -493,7 +493,7 @@ export function listSupersededOutputSchema(): ToolOutputSchema {
     sourcePath: z.string(),
     supersededBy,
   });
-  return {
+  return z.object({
     corpusHealth: corpusHealthSchema().optional(),
     result: z.discriminatedUnion('outcome', [
       z.object({
@@ -505,7 +505,7 @@ export function listSupersededOutputSchema(): ToolOutputSchema {
       invalidCursorSchema(),
       corpusUnavailableSchema(),
     ]),
-  };
+  });
 }
 
 /* ------------------------------------------------------------------ *