@adrkit/mcp 0.2.0 → 0.3.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.1.0' } 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,8 +7,8 @@
  * page is partitioned by status.
  */
 
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { resolveAffects, type Adr, type Finding, type FiredMatcher } from '@adrkit/core';
+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';
 import {
@@ -37,10 +37,12 @@ interface GetDecisionContextArgs {
 
 type Bucket = 'governing' | 'activeProposals' | 'history';
 
+/**
+ * Delegates to `@adrkit/core`'s `decisionBucketFor` so this tool and the CLI/Action
+ * cannot drift apart on what counts as governing (#39).
+ */
 function bucketFor(status: string): Bucket {
-  if (status === 'accepted') return 'governing';
-  if (status === 'draft' || status === 'proposed') return 'activeProposals';
-  return 'history';
+  return decisionBucketFor(status);
 }
 
 function contextEntry(record: Adr, firedMatchers: readonly FiredMatcher[]): ContextEntry {

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(),
     ]),
-  };
+  });
 }
 
 /* ------------------------------------------------------------------ *