@adrkit/mcp 0.2.0 → 0.3.0

package/README.md

@@ -1,22 +1,152 @@
 # `@adrkit/mcp`
 
-A **local, read-only** [Model Context Protocol](https://modelcontextprotocol.io)
-server that exposes adrkit decision retrieval over stdio. It lets an agent harness
-ask "has this been decided?", "what governs these files?", and "what replaced this?"
-against one Git-backed ADR corpus — deterministically, offline, with no model,
-network, or write access.
+**Deterministic, offline, read-only decision memory for coding agents — including
+the decisions you already rejected.**
 
-> 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.
+A local [Model Context Protocol](https://modelcontextprotocol.io) server that lets
+an agent harness query one Git-backed ADR (Architecture Decision Record) corpus
+over stdio: *"has this been decided?"*, *"what governs these files?"*, and *"what
+replaced this?"* It surfaces **superseded and rejected** decisions specifically so
+agents stop re-proposing paths the team already ruled out.
 
-## Install and run
+> **No model calls. No network calls. No writes.** The server reads Markdown files
+> from your repo and returns structured JSON. It never calls an LLM, never opens a
+> socket, and never mutates your corpus. Every tool is annotated
+> `readOnlyHint: true`, `openWorldHint: false`.
+
+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. 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
+
+adrkit is **early**. Phases 0–6 are *landed / reference-verified* against
+[ADR-0014](https://github.com/mbeacom/adrkit/blob/main/docs/adr/0014-stage-phase-landing-evidence-across-a-three-rung-validation-ladder.md)
+rungs 1–2 (unit/contract/conformance plus maintainer-owned isolated
+reference-repository validation). It has **no external adopters or production users
+yet**, and rung-3 external/community validation is openly tracked as not-yet-met.
+The 4-tool surface is locked by a
+[surface test](https://github.com/mbeacom/adrkit/blob/main/packages/mcp/test/surface.test.ts).
+
+## Quick start
+
+The published binary is **`adrkit-mcp`**. Run it with `npx` (no install):
 
 ```sh
-bunx @adrkit/mcp                       # run the adrkit-mcp bin
-adrkit-mcp --cwd /path/to/repo --dir docs/adr
+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:
+`~/Library/Application Support/Claude/claude_desktop_config.json`). Claude launches
+servers from an arbitrary working directory, so set `ADRKIT_MCP_CWD` to your repo's
+absolute path:
+
+```json
+{
+  "mcpServers": {
+    "adrkit": {
+      "command": "npx",
+      "args": ["-y", "@adrkit/mcp"],
+      "env": {
+        "ADRKIT_MCP_CWD": "/absolute/path/to/your/repo",
+        "ADRKIT_MCP_DIR": "docs/adr"
+      }
+    }
+  }
+}
 ```
 
+### VS Code
+
+Create `.vscode/mcp.json` in your workspace (VS Code uses the `servers` key and
+substitutes `${workspaceFolder}`):
+
+```json
+{
+  "servers": {
+    "adrkit": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@adrkit/mcp", "--cwd", "${workspaceFolder}", "--dir", "docs/adr"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Create `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "adrkit": {
+      "command": "npx",
+      "args": ["-y", "@adrkit/mcp"],
+      "env": {
+        "ADRKIT_MCP_CWD": "/absolute/path/to/your/repo",
+        "ADRKIT_MCP_DIR": "docs/adr"
+      }
+    }
+  }
+}
+```
+
+### GitHub Copilot CLI
+
+Add to `~/.copilot/mcp-config.json` (user-level) or `./.copilot/mcp-config.json`
+(per-repo). Copilot CLI runs servers from the trusted repo directory, so the default
+`cwd` usually resolves correctly:
+
+```json
+{
+  "mcpServers": {
+    "adrkit": {
+      "type": "local",
+      "command": "npx",
+      "args": ["-y", "@adrkit/mcp", "--dir", "docs/adr"],
+      "tools": ["*"]
+    }
+  }
+}
+```
+
+You can also add it interactively with `/mcp add` inside a `copilot` session.
+
+### Configuration reference
+
 | Option | Env | Default | Meaning |
 |---|---|---|---|
 | `--cwd <path>` | `ADRKIT_MCP_CWD` | `process.cwd()` | Repository root; must canonicalize to a directory containing a readable `.git` entry (a normal clone or a linked-worktree `.git` file). |
@@ -27,6 +157,148 @@ configuration exits non-zero with a diagnostic on **stderr** (`2` for an
 unparseable flag, `1` for an invalid root/directory) and never starts a transport.
 **stdout is reserved for JSON-RPC protocol frames only.**
 
+## The four tools
+
+Exactly four tools, all read-only. Each shares fixed annotations
+(`readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`,
+`openWorldHint: false`), returns a deterministic human-readable summary line in
+`content[0].text`, and carries a `findings` page with the corpus's own
+parse/validation findings. Every substantive response also includes a
+`corpusHealth` sibling: `{ fingerprint, recordCount, excludedCount }`.
+
+Shapes below are the real input/output contracts (see
+[`packages/mcp/src/tools`](https://github.com/mbeacom/adrkit/tree/main/packages/mcp/src/tools)).
+Each tool's structured output is `{ corpusHealth?, result }`; the objects shown
+under "output" are the members of that discriminated `result` union (keyed on
+`outcome`). `findings` and every growing array are cursor-paginated (see
+[Pagination](#pagination-and-cursor-restart)); `findings` and repeated pagination
+fields are elided here for brevity.
+
+### `search_decisions`
+
+Normalized literal substring search over id, title, tags, and body (the graveyard of
+superseded/rejected records is included by default). Filters are ANDed:
+`status`/`scope` match any-of; `tags` matches all-of.
+
+```jsonc
+// input
+{
+  "query": "postgres",          // required, 1–256 code units, non-empty after trim
+  "status": ["accepted"],        // optional, ≤6, any-of
+  "tags": ["database"],          // optional, ≤32 tags × ≤64 chars, all-of
+  "scope": ["backend"]           // optional, ≤3, any-of
+}
+// output → single "results" branch (empty results use the same branch)
+{
+  "outcome": "results",
+  "items": [
+    {
+      "id": "0007",
+      "title": "Adopt Postgres",
+      "status": "accepted",
+      "sourcePath": "docs/adr/0007-adopt-postgres.md",
+      "matchedFields": ["title", "body"]   // subset of id | title | tag | body
+    }
+  ],
+  "cursor": null
+}
+```
+
+### `get_decision`
+
+The complete typed frontmatter + body for one ref.
+
+```jsonc
+// input
+{ "ref": "0007" }               // AdrRef, 1–128 chars (local id, or a "log:id" federated ref)
+// output → discriminated on "outcome"
+// found (the full record is nested under "decision"):
+{
+  "outcome": "found",
+  "decision": {
+    "requestedRef": "0007",
+    "id": "0007",
+    "title": "Adopt Postgres",
+    "status": "accepted",
+    "sourcePath": "docs/adr/0007-adopt-postgres.md",
+    "frontmatter": { /* typed YAML: status, tags, affects, relations, ... */ },
+    "body": "## Context\n..."
+  }
+}
+// other outcomes:
+// { "outcome": "not-found", "requestedRef": "9999" }
+// { "outcome": "ambiguous-local-id", "requestedRef": "0007", "candidates": [ /* DecisionSummary[] */ ] }
+// { "outcome": "federated-log-unavailable", "requestedRef": "core:12", "log": "core", "id": "12" }
+```
+
+A `log:id` federated ref is recognized but **never resolved or substituted** — this
+server reads exactly one local corpus.
+
+### `get_decision_context`
+
+Governing / active-proposal / historical decisions for repo-relative `files[]`, via
+each record's own `affects` matchers. **Paths are compared against patterns only —
+never opened.**
+
+```jsonc
+// input
+{
+  "files": ["src/db/pool.ts", "src/db/schema.sql"]
+  // 1–256 entries; each POSIX, 1–1024 chars; no leading "/", no "..", no drive, no "\"
+}
+// output → single "matches" branch (all three arrays; empty is the same branch)
+{
+  "outcome": "matches",
+  "governing": [
+    {
+      "id": "0007",
+      "title": "Adopt Postgres",
+      "status": "accepted",
+      "sourcePath": "docs/adr/0007-adopt-postgres.md",
+      "firedMatchers": [ { "type": "path", "pattern": "src/db/**" } ],
+      "relations": { "supersedes": [], "supersededBy": null, "relatesTo": [], "conflictsWith": [] }
+    }
+  ],
+  "activeProposals": [],
+  "history": []
+}
+```
+
+### `list_superseded`
+
+Every superseded record with its **direct** local replacement state — the tool that
+keeps agents from re-proposing rejected paths.
+
+```jsonc
+// input (pagination only)
+{}
+// output → single "entries" branch
+{
+  "outcome": "entries",
+  "items": [
+    {
+      "id": "0003",
+      "title": "Use MySQL",
+      "status": "superseded",
+      "sourcePath": "docs/adr/0003-use-mysql.md",
+      "supersededBy": {            // one of four states:
+        "resolved": true,
+        "target": { "id": "0007", "title": "Adopt Postgres", "status": "accepted", "sourcePath": "docs/adr/0007-adopt-postgres.md" }
+      }
+      // unresolved states:
+      //   { "resolved": false, "targetRef": "0099", "reason": "dangling" }
+      //   { "resolved": false, "targetRef": "0007", "reason": "ambiguous", "candidateCount": 2 }
+      //   { "resolved": false, "targetRef": "core:1", "reason": "federated-unavailable", "log": "core", "id": "1" }
+    }
+  ],
+  "cursor": null
+}
+```
+
+Relation refs (`supersedes`, `supersededBy`, `relatesTo`, `conflictsWith`) are
+surfaced verbatim and never expanded — follow them with a second `get_decision`
+call. Supersession is reported one hop deep; there is no transitive traversal.
+
 ## Library surface
 
 The package root exports only a sealed lifecycle factory. There is no way to reach
@@ -36,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();
 ```
@@ -44,23 +316,11 @@ await server.close();
 `createAdrkitMcpServer(options?)` performs no filesystem access at construction and
 returns a frozen, null-prototype handle with exactly `start()` and `close()`.
 
-## The four tools
-
-All four share fixed annotations (`readOnlyHint: true`, `destructiveHint: false`,
-`idempotentHint: true`, `openWorldHint: false`), a `corpusHealth`
-(`fingerprint`/`recordCount`/`excludedCount`) sibling on every substantive
-response, and a `findings` page carrying the corpus's own parse/validation findings.
-
-| Tool | Answers | Notable outcomes |
-|---|---|---|
-| `search_decisions` | Normalized literal substring search over id, title, tags, and body (graveyard included by default). Filters: `status`/`scope` (any-of), `tags` (all-of), ANDed. | `results` (empty is the same branch) |
-| `get_decision` | The complete typed frontmatter + body for one ref. | `found`, `not-found`, `ambiguous-local-id` (duplicate ids), `federated-log-unavailable` (a `log:id` ref is recognized, never resolved or substituted) |
-| `get_decision_context` | Governing / active-proposal / historical decisions for repo-relative `files[]`, via the corpus's own `affects` matchers. Paths are compared against patterns only — never opened. | `matches` (all three arrays; empty is the same branch) |
-| `list_superseded` | Every superseded record with its **direct** local replacement state. | `entries` with `resolved` / `dangling` / `ambiguous` (`candidateCount` only) / `federated-unavailable` targets |
-
-Relation refs (`supersedes`, `supersededBy`, `relatesTo`, `conflictsWith`) are
-surfaced verbatim and never expanded — follow them with a second `get_decision`
-call.
+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
 
@@ -80,7 +340,8 @@ an unchanged corpus; otherwise the response is a non-error `invalid-cursor` outc
 (`corpus-changed`, `query-mismatch`, `wrong-channel`, `offset-out-of-range`,
 `cursor-not-applicable`, `version-unsupported`, or `decode-failed`) and you should
 restart the walk from no cursor. The primary-result and `findings` channels page
-independently.
+independently. A `corpus-unavailable` outcome is returned when the ADR directory
+cannot be read.
 
 ## Boundaries (out of scope by design)
 
@@ -94,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,22 +1,20 @@
 #!/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
-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) {
@@ -107,9 +105,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 {
@@ -207,29 +209,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;
@@ -501,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({
@@ -513,7 +492,7 @@ function searchDecisionsOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function getDecisionOutputSchema() {
   const fullDecision = z.object({
@@ -525,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() }),
@@ -547,7 +526,7 @@ function getDecisionOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function getDecisionContextOutputSchema() {
   const contextEntry = z.object({
@@ -558,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({
@@ -572,7 +551,7 @@ function getDecisionContextOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function listSupersededOutputSchema() {
   const supersededBy = z.union([
@@ -599,7 +578,7 @@ function listSupersededOutputSchema() {
     sourcePath: z.string(),
     supersededBy
   });
-  return {
+  return z.object({
     corpusHealth: corpusHealthSchema().optional(),
     result: z.discriminatedUnion("outcome", [
       z.object({
@@ -611,7 +590,7 @@ function listSupersededOutputSchema() {
       invalidCursorSchema(),
       corpusUnavailableSchema()
     ])
-  };
+  });
 }
 function structuredResult(result, text, corpusHealth) {
   const structuredContent = corpusHealth === undefined ? { result } : { corpusHealth, result };
@@ -845,13 +824,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) };
@@ -1018,21 +993,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;
@@ -1043,7 +1027,6 @@ function createAdrkitMcpServer(options) {
     if (startPromise)
       return startPromise;
     startPromise = (async () => {
-      let nextServer;
       try {
         const roots = await resolveCanonicalRoots({ cwd, dir });
         const config = {
@@ -1052,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;
       }
@@ -1078,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();
     })();
@@ -1113,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 {
@@ -1139,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/corpus/ordering.d.ts

@@ -1,17 +1,8 @@
 /**
- * @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 declare function compareCodeUnits(a: string, b: string): number;
-export interface OrderedSummary {
-    readonly id: string;
-    readonly sourcePath: string;
-}
-/** Canonical `(id, sourcePath)` ascending order; sourcePath is the unique tiebreak. */
-export declare function compareByIdThenPath(a: OrderedSummary, b: OrderedSummary): number;
-/** Canonical finding order using `sortFindings`' field tuple with the code-unit comparator. */
-export declare function compareFindings(a: Finding, b: Finding): number;
-export declare function sortFindingsCanonical(findings: readonly Finding[]): Finding[];
-export declare function sortByIdThenPath<T extends OrderedSummary>(items: readonly T[]): T[];
+export { compareByIdThenPath, compareCodeUnits, compareFindings, sortByIdThenPath, sortFindingsCanonical, type OrderedSummary, } from '@adrkit/core';