@cavelang/cli 0.29.1 → 0.31.0

package/dist/internal/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACpI,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAClC,OAAO,EACL,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EACnE,iBAAiB,EAAE,WAAW,EAAE,KAAK,EACtC,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,eAAe,EAC/D,eAAe,EAAE,gBAAgB,EAAE,UAAU,EAAE,QAAQ,EACxD,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAClC,OAAO,EACL,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EACnE,iBAAiB,EAAE,WAAW,EAAE,KAAK,EACtC,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/internal/mcp/index.js

@@ -6,7 +6,7 @@
  * { "command": "cave", "args": ["mcp", "--db", "knowledge.db"] }
  * ```
  *
- * Tools: cave_add, cave_query, cave_fuse, cave_search, cave_about,
+ * Tools: cave_help, cave_add, cave_query, cave_fuse, cave_search, cave_about,
  * cave_neighbors, cave_reconstruct, cave_derive, cave_export, cave_lint —
  * plus one generated `act_<name>` tool per action declared in the store
  * (spec §25.5), the governed write vocabulary. `cave_fuse` and
@@ -17,7 +17,7 @@
  * `--tools <list>` narrow the served surface — the minimum viable agent
  * permission boundary.
  */
-export { agentSource, createServer, serve, instructions, instructionsFor, protocolVersion, serverInfo, specCard } from "./server.js";
+export { agentSource, createServer, serve, instructions, instructionsFor, protocolVersion, protocolVersions, serverInfo, specCard } from "./server.js";
 export { runMcp } from "./main.js";
 export { actionTools, actToolName, actToolPrefix, allowsActions, permissions, scopedActionTools, scopedTools, tools } from "./tools.js";
 //# sourceMappingURL=index.js.map

package/dist/internal/mcp/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEpI,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAClC,OAAO,EACL,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EACnE,iBAAiB,EAAE,WAAW,EAAE,KAAK,EACtC,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,eAAe,EAC/D,eAAe,EAAE,gBAAgB,EAAE,UAAU,EAAE,QAAQ,EACxD,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAClC,OAAO,EACL,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EACnE,iBAAiB,EAAE,WAAW,EAAE,KAAK,EACtC,MAAM,YAAY,CAAA"}

package/dist/internal/mcp/server.d.ts

@@ -1,24 +1,20 @@
 /**
- * MCP server over stdio — newline-delimited JSON-RPC 2.0.
+ * CAVE's tool surface on the official MCP TypeScript SDK v2.
  *
- * Implements the slice of the Model Context Protocol a tools-only server
- * needs: `initialize` / `notifications/initialized`, `ping`, `tools/list`
- * and `tools/call`. The dispatcher is a pure function from message to
- * optional response, so it is testable without a process or a socket;
- * `serve` wires it to stdin/stdout.
- *
- * Hand-rolled rather than pulling in an SDK: the protocol surface here is
- * ~150 lines, the repo is otherwise dependency-free beyond
- * `@prelude/parser`, and `@prelude/jsonrpc` targets WebSocket-style
- * transports with numeric-only ids (MCP ids may be strings).
+ * `createToolSurface` keeps domain behavior transport-free and testable;
+ * `createServer` binds it to the SDK's low-level Server; `serve` delegates
+ * stdio framing, lifecycle, protocol-era detection, and legacy fallback to
+ * `serveStdio`.
  */
+import { Server } from '@modelcontextprotocol/server';
 import type { Store } from '@cavelang/store';
 import { type Scope, type Tool } from './tools.ts';
 export type ServerOptions = Scope & {
     /**
      * Actor provenance stamp for appends (spec §9.5), without the `src:`
-     * prefix. Default: `agent/<client-name>` from the initialize handshake,
-     * plain `agent` before or without one. `false` disables stamping.
+     * prefix. Default: `agent/<client-name>` from the initialize handshake or
+     * modern request envelope, plain `agent` without one. `false` disables
+     * stamping.
      */
     readonly source?: string | false;
     /** Out-of-band hook command templates for action tools (spec §25.4). */
@@ -32,8 +28,10 @@ export type ServerOptions = Scope & {
  * plain `agent` when no usable name is known (spec §9.5).
  */
 export declare const agentSource: (clientName: undefined | string) => string;
-/** The single MCP protocol revision this server implements. */
-export declare const protocolVersion = "2025-06-18";
+/** Legacy initialize-era revisions supported by the official MCP SDK. */
+export declare const protocolVersions: string[];
+/** The preferred MCP protocol revision offered during version negotiation. */
+export declare const protocolVersion = "2025-11-25";
 export declare const serverInfo: {
     readonly name: "cave";
     readonly version: string;
@@ -60,33 +58,35 @@ export declare const instructionsFor: (served: readonly Tool[], options?: {
  * how to write CAVE without reading the full specification.
  */
 export declare const instructions: string;
-type Id = null | string | number;
-type Response = {
-    jsonrpc: '2.0';
-    id: null | Id;
-    result?: unknown;
-    error?: {
-        code: number;
-        message: string;
+export type ListedTool = {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Tool['inputSchema'];
+    readonly annotations?: {
+        readonly readOnlyHint: true;
     };
 };
-type Reply = Response | Response[];
+export type ToolCallResult = {
+    content: [{
+        type: 'text';
+        text: string;
+    }];
+    readonly isError?: true;
+};
 /**
- * @returns pure MCP dispatcher over an open store: message in, response
- * out (`undefined` for notifications). The client name captured from
- * `initialize` becomes the default `agent/<name>` provenance stamp on
- * appends (spec §9.5). Serves the scoped tool surface — tools outside the
- * scope are absent from `tools/list` and unknown to `tools/call`; throws
- * when the scope names an unknown tool or serves none.
+ * Pure CAVE tool surface beneath the MCP SDK. Action declarations are read on
+ * every list/call, so actions added mid-session appear without reconnecting.
  */
-export declare const createServer: (store: Store, options?: ServerOptions) => {
-    handle: (message: unknown) => undefined | Reply;
+export declare const createToolSurface: (store: Store, options?: ServerOptions) => {
+    list: () => ListedTool[];
+    call: (name: string, args: Record<string, unknown>, clientName?: string) => ToolCallResult;
 };
 /**
- * Serves MCP over newline-delimited JSON-RPC on the given streams until
- * the input closes. Protocol traffic only on `output` — logs belong on
- * stderr.
+ * Builds an official SDK server over CAVE's scoped, dynamic tool surface.
+ * Protocol negotiation, validation, lifecycle, ping, and error envelopes are
+ * owned by `@modelcontextprotocol/server`.
  */
+export declare const createServer: (store: Store, options?: ServerOptions) => Server;
+/** Serves both the 2026 MCP era and legacy initialize-era clients on stdio. */
 export declare const serve: (store: Store, input: NodeJS.ReadableStream, output: NodeJS.WritableStream, options?: ServerOptions) => Promise<void>;
-export {};
 //# sourceMappingURL=server.d.ts.map

package/dist/internal/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAuE,KAAK,KAAK,EAAE,KAAK,IAAI,EAAE,MAAM,YAAY,CAAA;AAEvH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG;IAClC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAChC,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,YAAY,SAAS,GAAG,MAAM,KAAG,MAO5D,CAAA;AAED,+DAA+D;AAC/D,eAAO,MAAM,eAAe,eAAe,CAAA;AAE3C,eAAO,MAAM,UAAU;;;CAGb,CAAA;AAEV;;;GAGG;AACH,eAAO,MAAM,QAAQ,i5BAgB4C,CAAA;AAEjE;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,SAAS,IAAI,EAAE,EAAE,UAAS;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,KAAG,MAiC9F,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAA4C,CAAA;AAErE,KAAK,EAAE,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAA;AAShC,KAAK,QAAQ,GAAG;IACd,OAAO,EAAE,KAAK,CAAA;IACd,EAAE,EAAE,IAAI,GAAG,EAAE,CAAA;IACb,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAC1C,CAAA;AAWD,KAAK,KAAK,GAAG,QAAQ,GAAG,QAAQ,EAAE,CAAA;AAElC;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,KAAK,EAAE,UAAS,aAAkB;sBAyF3C,OAAO,KAAG,SAAS,GAAG,KAAK;CAUrD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAChB,OAAO,KAAK,EACZ,OAAO,MAAM,CAAC,cAAc,EAC5B,QAAQ,MAAM,CAAC,cAAc,EAC7B,UAAS,aAAkB,KAC1B,OAAO,CAAC,IAAI,CA8Bd,CAAA"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAEc,MAAM,EAC1B,MAAM,8BAA8B,CAAA;AAGrC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAuE,KAAK,KAAK,EAAE,KAAK,IAAI,EAAE,MAAM,YAAY,CAAA;AAEvH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAChC,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,YAAY,SAAS,GAAG,MAAM,KAAG,MAO5D,CAAA;AAED,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,UAAmC,CAAA;AAEhE,8EAA8E;AAC9E,eAAO,MAAM,eAAe,eAA0B,CAAA;AAEtD,eAAO,MAAM,UAAU;;;CAGb,CAAA;AAEV;;;GAGG;AACH,eAAO,MAAM,QAAQ,i5BAgB4C,CAAA;AAEjE;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,SAAS,IAAI,EAAE,EAAE,UAAS;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,KAAG,MAkC9F,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAA4C,CAAA;AAErE,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC,CAAA;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAA;KAAE,CAAA;CACvD,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAA;CACxB,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,KAAK,EAAE,UAAS,aAAkB;gBAMxD,UAAU,EAAE;iBAQrB,MAAM,QACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,eAChB,MAAM,KAClB,cAAc;CAmBlB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,KAAK,EAAE,UAAS,aAAkB,KAAG,MAqBxE,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,KAAK,GAChB,OAAO,KAAK,EACZ,OAAO,MAAM,CAAC,cAAc,EAC5B,QAAQ,MAAM,CAAC,cAAc,EAC7B,UAAS,aAAkB,KAC1B,OAAO,CAAC,IAAI,CAgCd,CAAA"}

package/dist/internal/mcp/server.js

@@ -1,18 +1,13 @@
 /**
- * MCP server over stdio — newline-delimited JSON-RPC 2.0.
+ * CAVE's tool surface on the official MCP TypeScript SDK v2.
  *
- * Implements the slice of the Model Context Protocol a tools-only server
- * needs: `initialize` / `notifications/initialized`, `ping`, `tools/list`
- * and `tools/call`. The dispatcher is a pure function from message to
- * optional response, so it is testable without a process or a socket;
- * `serve` wires it to stdin/stdout.
- *
- * Hand-rolled rather than pulling in an SDK: the protocol surface here is
- * ~150 lines, the repo is otherwise dependency-free beyond
- * `@prelude/parser`, and `@prelude/jsonrpc` targets WebSocket-style
- * transports with numeric-only ids (MCP ids may be strings).
+ * `createToolSurface` keeps domain behavior transport-free and testable;
+ * `createServer` binds it to the SDK's low-level Server; `serve` delegates
+ * stdio framing, lifecycle, protocol-era detection, and legacy fallback to
+ * `serveStdio`.
  */
-import { createInterface } from 'node:readline';
+import { CLIENT_INFO_META_KEY, LATEST_PROTOCOL_VERSION, ProtocolError, ProtocolErrorCode, Server, SUPPORTED_PROTOCOL_VERSIONS } from '@modelcontextprotocol/server';
+import { serveStdio, StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { Version } from '@cavelang/core';
 import { actToolPrefix, allowsActions, scopedActionTools, scopedTools, tools } from "./tools.js";
 /**
@@ -28,8 +23,10 @@ export const agentSource = (clientName) => {
         .replace(/[^a-z0-9._/-]/g, '');
     return name === '' ? 'agent' : `agent/${name}`;
 };
-/** The single MCP protocol revision this server implements. */
-export const protocolVersion = '2025-06-18';
+/** Legacy initialize-era revisions supported by the official MCP SDK. */
+export const protocolVersions = [...SUPPORTED_PROTOCOL_VERSIONS];
+/** The preferred MCP protocol revision offered during version negotiation. */
+export const protocolVersion = LATEST_PROTOCOL_VERSION;
 export const serverInfo = {
     name: 'cave',
     version: Version.current()
@@ -67,6 +64,7 @@ export const instructionsFor = (served, options = {}) => {
     const has = (name) => served.some(tool => tool.name === name);
     const explore = ['cave_about', 'cave_neighbors'].filter(has);
     const clauses = [
+        ...has('cave_help') ? ['consult cave_help for version-matched usage guidance when needed'] : [],
         ...has('cave_add') ?
             [`extract knowledge with one claim per line via cave_add${has('cave_lint') ? ' (validate with cave_lint first)' : ''}`] :
             has('cave_lint') ? ['validate CAVE text with cave_lint'] : [],
@@ -103,149 +101,100 @@ export const instructionsFor = (served, options = {}) => {
  * how to write CAVE without reading the full specification.
  */
 export const instructions = instructionsFor(tools, { actions: true });
-const result = (id, value) => ({ jsonrpc: '2.0', id, result: value });
-const failure = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
-const isId = (value) => value === null || typeof value === 'string' || typeof value === 'number';
 /**
- * @returns pure MCP dispatcher over an open store: message in, response
- * out (`undefined` for notifications). The client name captured from
- * `initialize` becomes the default `agent/<name>` provenance stamp on
- * appends (spec §9.5). Serves the scoped tool surface — tools outside the
- * scope are absent from `tools/list` and unknown to `tools/call`; throws
- * when the scope names an unknown tool or serves none.
+ * Pure CAVE tool surface beneath the MCP SDK. Action declarations are read on
+ * every list/call, so actions added mid-session appear without reconnecting.
  */
-export const createServer = (store, options = {}) => {
+export const createToolSurface = (store, options = {}) => {
     const served = scopedTools(options);
     const servedByName = new Map(served.map(tool => [tool.name, tool]));
-    // Action tools are generated from the store's current declarations per
-    // request (spec §25.5) — an action declared mid-session appears in the
-    // next tools/list without reconnecting.
     const actionsPossible = allowsActions(options);
     const actServed = () => actionsPossible ? scopedActionTools(store, options) : [];
-    const servedInstructions = instructionsFor(served, { actions: actionsPossible });
-    let clientName;
-    const source = () => options.source === false ? undefined : options.source ?? agentSource(clientName);
-    const dispatch = (message) => {
-        if (typeof message !== 'object' || message === null || Array.isArray(message)) {
-            return failure(null, -32600, 'Invalid request');
+    const list = () => [...served, ...actServed()].map(tool => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        ...(tool.permission === 'record' || tool.permission === 'action' ?
+            {} : { annotations: { readOnlyHint: true } })
+    }));
+    const call = (name, args, clientName) => {
+        const tool = servedByName.get(name) ??
+            (name.startsWith(actToolPrefix) ? actServed().find(candidate => candidate.name === name) : undefined);
+        if (tool === undefined) {
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown tool: ${name}`);
         }
-        const { jsonrpc, id, method, params } = message;
-        const hasId = Object.hasOwn(message, 'id');
-        if (jsonrpc !== '2.0' || typeof method !== 'string' || (hasId && !isId(id))) {
-            return failure(isId(id) ? id : null, -32600, 'Invalid request');
+        try {
+            const stamp = options.source === false ? undefined : options.source ?? agentSource(clientName);
+            const text = tool.run(store, args, {
+                ...stamp === undefined ? {} : { source: stamp },
+                ...options.hooks === undefined ? {} : { hooks: options.hooks }
+            });
+            return { content: [{ type: 'text', text }] };
         }
-        if (!hasId) {
-            // Notifications (notifications/initialized, notifications/cancelled, …)
-            // require no response.
-            return undefined;
+        catch (error) {
+            const text = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text }], isError: true };
         }
-        const requestId = id;
-        switch (method) {
-            case 'initialize': {
-                const requested = params?.protocolVersion;
-                if (requested !== protocolVersion) {
-                    return failure(requestId, -32602, `Unsupported protocol version: ${String(requested)}; supported: ${protocolVersion}`);
-                }
-                const name = params?.clientInfo?.name;
-                if (typeof name === 'string') {
-                    clientName = name;
-                }
-                return result(requestId, {
-                    protocolVersion,
-                    capabilities: { tools: {} },
-                    serverInfo,
-                    instructions: servedInstructions
-                });
-            }
-            case 'ping':
-                return result(requestId, {});
-            case 'tools/list':
-                return result(requestId, {
-                    tools: [...served, ...actServed()].map(tool => ({
-                        name: tool.name,
-                        description: tool.description,
-                        inputSchema: tool.inputSchema,
-                        ...(tool.permission === 'record' || tool.permission === 'action' ?
-                            {} : { annotations: { readOnlyHint: true } })
-                    }))
-                });
-            case 'tools/call': {
-                const call = (params ?? {});
-                const tool = typeof call.name === 'string' ?
-                    servedByName.get(call.name) ??
-                        (call.name.startsWith(actToolPrefix) ? actServed().find(candidate => candidate.name === call.name) : undefined) :
-                    undefined;
-                if (tool === undefined) {
-                    return failure(requestId, -32602, `Unknown tool: ${String(call.name)}`);
-                }
-                const args = typeof call.arguments === 'object' && call.arguments !== null ?
-                    call.arguments :
-                    {};
-                try {
-                    const stamp = source();
-                    const text = tool.run(store, args, {
-                        ...stamp === undefined ? {} : { source: stamp },
-                        ...options.hooks === undefined ? {} : { hooks: options.hooks }
-                    });
-                    return result(requestId, { content: [{ type: 'text', text }] });
-                }
-                catch (error) {
-                    const text = error instanceof Error ? error.message : String(error);
-                    return result(requestId, { content: [{ type: 'text', text }], isError: true });
-                }
-            }
-            default:
-                return failure(requestId, -32601, `Method not found: ${method}`);
-        }
-    };
-    const handle = (message) => {
-        if (!Array.isArray(message))
-            return dispatch(message);
-        if (message.length === 0)
-            return failure(null, -32600, 'Invalid request');
-        const responses = message.flatMap(item => {
-            const response = dispatch(item);
-            return response === undefined ? [] : [response];
-        });
-        return responses.length === 0 ? undefined : responses;
     };
-    return { handle };
+    return { list, call };
 };
 /**
- * Serves MCP over newline-delimited JSON-RPC on the given streams until
- * the input closes. Protocol traffic only on `output` — logs belong on
- * stderr.
+ * Builds an official SDK server over CAVE's scoped, dynamic tool surface.
+ * Protocol negotiation, validation, lifecycle, ping, and error envelopes are
+ * owned by `@modelcontextprotocol/server`.
  */
+export const createServer = (store, options = {}) => {
+    const served = scopedTools(options);
+    const actionsPossible = allowsActions(options);
+    const surface = createToolSurface(store, options);
+    const server = new Server(serverInfo, {
+        capabilities: { tools: {} },
+        instructions: instructionsFor(served, { actions: actionsPossible })
+    });
+    const clientName = (context) => {
+        const envelope = context.mcpReq.envelope;
+        const modern = envelope?.[CLIENT_INFO_META_KEY];
+        return typeof modern?.name === 'string' ? modern.name : server.getClientVersion()?.name;
+    };
+    server.setRequestHandler('tools/list', async () => ({ tools: surface.list() }));
+    server.setRequestHandler('tools/call', async (request, context) => server.projectCallToolResult(surface.call(request.params.name, request.params.arguments ?? {}, clientName(context)), undefined));
+    return server;
+};
+/** Serves both the 2026 MCP era and legacy initialize-era clients on stdio. */
 export const serve = (store, input, output, options = {}) => {
-    const server = createServer(store, options);
-    return new Promise(resolve => {
-        const lines = createInterface({ input });
-        const abort = () => lines.close();
-        options.signal?.addEventListener('abort', abort, { once: true });
-        lines.on('line', line => {
-            if (line.trim() === '') {
+    const transport = new StdioServerTransport(input, output);
+    const handle = serveStdio(() => createServer(store, options), { transport });
+    return new Promise((resolve, reject) => {
+        let finished = false;
+        const cleanup = () => {
+            input.removeListener('end', close);
+            input.removeListener('close', close);
+            input.removeListener('error', fail);
+            options.signal?.removeEventListener('abort', close);
+        };
+        const done = () => {
+            if (finished)
                 return;
-            }
-            let message;
-            try {
-                message = JSON.parse(line);
-            }
-            catch {
-                output.write(`${JSON.stringify(failure(null, -32700, 'Parse error'))}\n`);
-                return;
-            }
-            const response = server.handle(message);
-            if (response !== undefined) {
-                output.write(`${JSON.stringify(response)}\n`);
-            }
-        });
-        lines.on('close', () => {
-            options.signal?.removeEventListener('abort', abort);
+            finished = true;
+            cleanup();
             resolve();
-        });
-        if (options.signal?.aborted === true) {
-            lines.close();
-        }
+        };
+        const fail = (error) => {
+            if (finished)
+                return;
+            finished = true;
+            cleanup();
+            reject(error);
+        };
+        const close = () => {
+            void handle.close().then(done, fail);
+        };
+        input.once('end', close);
+        input.once('close', close);
+        input.once('error', fail);
+        options.signal?.addEventListener('abort', close, { once: true });
+        if (options.signal?.aborted === true)
+            close();
     });
 };
 //# sourceMappingURL=server.js.map

package/dist/internal/mcp/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"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"}

package/dist/internal/mcp/tools.d.ts

@@ -4,6 +4,7 @@
  *
  * | Tool | Purpose |
  * |---|---|
+ * | `cave_help` | version-matched usage guidance for agents |
  * | `cave_add` | append CAVE text (extraction output) to the store |
  * | `cave_query` | run a CAVE-Q pattern (spec §12) |
  * | `cave_fuse` | Bayesian fusion of numeric estimates (§10.1) — named computation |
@@ -23,6 +24,7 @@
  * the minimum viable agent permission boundary.
  */
 import type { Store } from '@cavelang/store';
+import type { Tool as McpTool } from '@modelcontextprotocol/server';
 /** Per-connection state the server threads into tool calls. */
 export type ToolContext = {
     /**
@@ -40,7 +42,9 @@ export type Tool = {
     readonly description: string;
     /** Evaluation is ephemeral, recording is durable, and action may cause effects. */
     readonly permission: Permission;
-    readonly inputSchema: object;
+    readonly inputSchema: McpTool['inputSchema'] & {
+        readonly properties: NonNullable<McpTool['inputSchema']['properties']>;
+    };
     readonly run: (store: Store, args: Record<string, unknown>, context: ToolContext) => string;
 };
 /**

package/dist/internal/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAO5C,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAClD,CAAA;AAED,eAAO,MAAM,WAAW,mDAAoD,CAAA;AAC5E,MAAM,MAAM,UAAU,GAAG,OAAO,WAAW,CAAC,MAAM,CAAC,CAAA;AAEnD,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,CAAA;CAC5F,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IAC5C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC,CAAA;AA6GD,eAAO,MAAM,KAAK,EAAE,SAAS,IAAI,EA6UhC,CAAA;AAED,eAAO,MAAM,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CACE,CAAA;AAE/C,+DAA+D;AAC/D,eAAO,MAAM,aAAa,SAAS,CAAA;AAEnC;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,KAAG,MACmB,CAAA;AAkDhE;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,KAAG,IAAI,EAY9C,CAAA;AAiBD,eAAO,MAAM,aAAa,GAAI,QAAO,KAAU,KAAG,OAEuC,CAAA;AAEzF,eAAO,MAAM,iBAAiB,GAAI,OAAO,KAAK,EAAE,QAAO,KAAU,KAAG,IAAI,EAGlE,CAAA;AAEN;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,QAAO,KAAU,KAAG,SAAS,IAAI,EAkB5D,CAAA"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAM5C,OAAO,KAAK,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,8BAA8B,CAAA;AAGnE,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAClD,CAAA;AAED,eAAO,MAAM,WAAW,mDAAoD,CAAA;AAC5E,MAAM,MAAM,UAAU,GAAG,OAAO,WAAW,CAAC,MAAM,CAAC,CAAA;AAEnD,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG;QAC7C,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,YAAY,CAAC,CAAC,CAAA;KACvE,CAAA;IACD,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,CAAA;CAC5F,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IAC5C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC,CAAA;AA6GD,eAAO,MAAM,KAAK,EAAE,SAAS,IAAI,EAoWhC,CAAA;AAED,eAAO,MAAM,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CACE,CAAA;AAE/C,+DAA+D;AAC/D,eAAO,MAAM,aAAa,SAAS,CAAA;AAEnC;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,KAAG,MACmB,CAAA;AAkDhE;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,KAAG,IAAI,EAY9C,CAAA;AAiBD,eAAO,MAAM,aAAa,GAAI,QAAO,KAAU,KAAG,OAEuC,CAAA;AAEzF,eAAO,MAAM,iBAAiB,GAAI,OAAO,KAAK,EAAE,QAAO,KAAU,KAAG,IAAI,EAGlE,CAAA;AAEN;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,QAAO,KAAU,KAAG,SAAS,IAAI,EAkB5D,CAAA"}

package/dist/internal/mcp/tools.js

@@ -4,6 +4,7 @@
  *
  * | Tool | Purpose |
  * |---|---|
+ * | `cave_help` | version-matched usage guidance for agents |
  * | `cave_add` | append CAVE text (extraction output) to the store |
  * | `cave_query` | run a CAVE-Q pattern (spec §12) |
  * | `cave_fuse` | Bayesian fusion of numeric estimates (§10.1) — named computation |
@@ -31,6 +32,7 @@ import { estimateOf, fuse } from '@cavelang/fusion';
 import { derive } from '@cavelang/cli/rules';
 import { reconstruct, heuristicPolicy, sqliteStore } from '@cavelang/cli/loop';
 import { act, listActions } from '@cavelang/cli/act';
+import { guideFor, guideTopics } from "./guide.js";
 export const permissions = ['read', 'evaluate', 'record', 'action'];
 const text = (value, name) => {
     if (typeof value !== 'string' || value === '') {
@@ -131,6 +133,29 @@ const selectFuseClaims = (store, args) => {
     return result.claims.map(entry => entry.claim);
 };
 export const tools = [
+    {
+        name: 'cave_help',
+        description: 'Version-matched CAVE usage guidance for agents. Call before the first CAVE task ' +
+            'or when choosing how to write, find, revise, or safely handle knowledge. This reads no user data.',
+        permission: 'read',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                topic: {
+                    type: 'string',
+                    enum: [...guideTopics],
+                    description: 'guide topic (default: overview)'
+                }
+            }
+        },
+        run: (_store, args) => {
+            const topic = args['topic'] ?? 'overview';
+            if (typeof topic !== 'string' || !guideTopics.includes(topic)) {
+                throw new Error(`topic must be one of ${guideTopics.join(', ')}`);
+            }
+            return guideFor(topic);
+        }
+    },
     {
         name: 'cave_add',
         description: 'Append CAVE claims to the knowledge database. Input is CAVE text ' +
@@ -429,7 +454,7 @@ export const tools = [
             type: 'object',
             properties: {
                 current: { type: 'boolean' },
-                maxSensitivity: { type: 'string', enum: Sensitivity.levels }
+                maxSensitivity: { type: 'string', enum: [...Sensitivity.levels] }
             }
         },
         run: (store, args) => {