@cavelang/cli 0.27.14 → 0.29.1

package/dist/internal/mcp/main.js

@@ -0,0 +1,156 @@
+/**
+ * `cave mcp` entry — opens the knowledge database and serves MCP on stdio
+ * until the client disconnects. Everything written to stdout is protocol;
+ * the startup banner goes to stderr.
+ */
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { Registry } from '@cavelang/canonical';
+import { defaultDbPath, open } from '@cavelang/store';
+import { serve, serverInfo } from "./server.js";
+import { scopedTools } from "./tools.js";
+export const usage = `cave mcp — serve a CAVE knowledge database as an MCP server on stdio
+
+Usage:
+  cave mcp [--db <path>] [--no-prelude] [--read-only]
+           [--permissions <list>] [--tools <list>]
+           [--src <context>] [--no-src] [--hooks <file>]
+
+Options:
+  --db <path>      database file (default: $CAVE_DB, or cave.db)
+  --no-prelude     open the store without the standard verb registry
+  --read-only      serve only tools that never write (drops cave_add,
+                   cave_derive and the generated act_<name> action tools)
+  --permissions    serve only operation classes from read,evaluate,record,
+                   action (comma-separated); evaluation is ephemeral,
+                   recording is durable, and action may execute effects
+  --tools <list>   serve only these tools (comma-separated); --read-only
+                   still drops writing tools from the list; act_<name>
+                   entries scope whichever actions exist at call time
+  --src <context>  provenance stamp for appends, without the src: prefix
+                   (default: agent/<client-name> from the MCP handshake)
+  --no-src         do not stamp actor provenance on appends
+  --hooks <file>   JSON file of out-of-band hook command templates for
+                   action tools, name → shell template (spec §25.4);
+                   default: $CAVE_HOOKS
+
+Appended claims that carry no @src: context are stamped with the
+connected client's source context (spec §9.5). Actions declared in the
+store are served as generated act_<name> tools (spec §25.5) — the
+governed write vocabulary — recomputed per tools/list. Tools outside the
+served scope are absent from tools/list and unknown to tools/call. Runs
+until the client disconnects; stdout is protocol, diagnostics go to
+stderr.
+
+Examples:
+  cave mcp --db k.db
+  cave mcp --db k.db --read-only
+  cave mcp --db k.db --permissions read,evaluate
+  cave mcp --db k.db --permissions action --tools act_mark-deployed
+  cave mcp --db k.db --tools cave_query,cave_about,cave_search
+  cave mcp --db k.db --tools cave_query,act_mark-deployed
+  cave mcp --db k.db --hooks hooks.json
+  cave mcp --db k.db --src pipeline/nightly
+  claude mcp add cave -- cave mcp --db k.db`;
+/**
+ * Loads a hooks configuration file (spec §25.4): a JSON object mapping
+ * hook names to shell command templates. Throws on anything else — a
+ * misconfigured side-effect surface must not come up at all.
+ */
+export const readHooks = (path) => {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed) ||
+        Object.values(parsed).some(value => typeof value !== 'string')) {
+        throw new Error(`${path}: hooks must be a JSON object of name → shell template strings`);
+    }
+    return parsed;
+};
+/** Validates the single accepted `--src` spelling: a non-empty context token without `src:`. */
+export const sourceFromOption = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (!/^[A-Za-z0-9._/:-]+$/.test(value)) {
+        throw new Error('--src must be a context token (letters, digits, . _ / : -)');
+    }
+    if (value.startsWith('src:')) {
+        throw new Error('--src must not include the src: prefix');
+    }
+    return value;
+};
+/** Runs the server; resolves with the process exit code. */
+export const runMcp = async (argv, context = {}) => {
+    const stdin = context.stdin ?? process.stdin;
+    const stdout = context.stdout ?? process.stdout;
+    const stderr = context.stderr ?? process.stderr;
+    const { values } = parseArgs({
+        args: [...argv],
+        options: {
+            db: { type: 'string' },
+            'no-prelude': { type: 'boolean' },
+            'read-only': { type: 'boolean' },
+            permissions: { type: 'string' },
+            tools: { type: 'string' },
+            src: { type: 'string' },
+            'no-src': { type: 'boolean' },
+            hooks: { type: 'string' },
+            help: { type: 'boolean', short: 'h' }
+        },
+        allowPositionals: false
+    });
+    if (values.help === true) {
+        stdout.write(`${usage}\n`);
+        return 0;
+    }
+    let sourceOverride;
+    try {
+        sourceOverride = sourceFromOption(values.src);
+    }
+    catch (error) {
+        stderr.write(`cave mcp: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
+    const scope = {
+        ...values['read-only'] === true ? { readOnly: true } : {},
+        ...values.permissions === undefined ? {} : {
+            permissions: values.permissions.split(',').map(name => name.trim()).filter(name => name !== '')
+        },
+        ...values.tools === undefined ? {} : {
+            tools: values.tools.split(',').map(name => name.trim()).filter(name => name !== '')
+        }
+    };
+    let hooks;
+    try {
+        // Validate the scope and hook configuration before touching the
+        // database or the protocol — a misconfigured permission boundary or
+        // side-effect surface must not come up at all.
+        scopedTools(scope);
+        const hooksPath = values.hooks ?? process.env['CAVE_HOOKS'];
+        hooks = hooksPath === undefined ? undefined : readHooks(hooksPath);
+    }
+    catch (error) {
+        stderr.write(`cave mcp: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
+    const db = values.db ?? defaultDbPath();
+    const store = open(db, values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    const scopeNote = [
+        ...values['read-only'] === true ? ['read-only'] : [],
+        ...scope.permissions === undefined ? [] : [`permissions ${scope.permissions.join(',')}`],
+        ...scope.tools === undefined ? [] : [`tools ${scopedTools(scope).map(tool => tool.name).join(',')}`]
+    ];
+    stderr.write(`${serverInfo.name} mcp server ${serverInfo.version} — db ${db}` +
+        `${scopeNote.length > 0 ? ` (${scopeNote.join('; ')})` : ''}\n`);
+    try {
+        await serve(store, stdin, stdout, {
+            ...scope,
+            ...values['no-src'] === true ? { source: false } : sourceOverride === undefined ? {} : { source: sourceOverride },
+            ...hooks === undefined ? {} : { hooks },
+            ...context.signal === undefined ? {} : { signal: context.signal }
+        });
+    }
+    finally {
+        store.close();
+    }
+    return 0;
+};
+//# sourceMappingURL=main.js.map

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

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

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

@@ -0,0 +1,92 @@
+/**
+ * MCP server over stdio — newline-delimited JSON-RPC 2.0.
+ *
+ * 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).
+ */
+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.
+     */
+    readonly source?: string | false;
+    /** Out-of-band hook command templates for action tools (spec §25.4). */
+    readonly hooks?: Readonly<Record<string, string>>;
+    /** Stop accepting protocol input and resolve after the current message. */
+    readonly signal?: AbortSignal;
+};
+/**
+ * @returns `agent/<name>` source context from an MCP client name —
+ * lowercased, whitespace to `-`, restricted to context-safe characters;
+ * 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";
+export declare const serverInfo: {
+    readonly name: "cave";
+    readonly version: string;
+};
+/**
+ * The spec §22 compact card — tool-agnostic CAVE writing knowledge,
+ * shared with `@cavelang/cli/ingest` prompts.
+ */
+export declare const specCard = "CAVE (Compressed Atomic Verb Expressions) persists knowledge as atomic claims:\n\n  subject VERB [NOT] object                [@context...] [#tag[:value]...] [@ N%] [!] [; comment]\n  subject HAS attribute: value [+/- delta] [@context...] [#tag[:value]...] [@ N%] [!] [; comment]\n\nExamples:\n  auth/middleware USES jwt @ 90%\n  OpenAI HAS revenue: ~20B USD/yr +/- 2B USD/yr @2026-Q1\n  server IS NOT compromised @ 90%\n  memory-leak CAUSE app/crash @ 70% #topic:stability\n\nVerbs are UPPERCASE (IS, HAS, CAUSE, FIX, NEEDS, USES, YIELDS, ENABLES, BLOCKS,\nCONTAINS, PRECEDES, EXTENDS, ALIAS, LIKE, EXISTS, VS, BECOMES, EXCEEDS,\nIS-BELOW, IS-AT-LEAST, IS-AT-MOST, EQUALS, DIFFERS-FROM).\nEntities are kebab-case with / for scope (auth/middleware). @ctx = context\n(no space), @ 90% = confidence (space). Storage is append-only: update belief\nby adding the same claim with new confidence; retract with @ 0%.";
+/**
+ * Server instructions for a served tool surface — the card plus tool
+ * guidance mentioning only tools actually served, so a connected model is
+ * never pointed at a tool the scope hides. A surface with no writing tool
+ * says so outright. `actions` marks a scope that (also) serves generated
+ * action tools (spec §25.5) — a write surface even when no static tool
+ * writes.
+ */
+export declare const instructionsFor: (served: readonly Tool[], options?: {
+    actions?: boolean;
+}) => string;
+/**
+ * Server instructions for the full default surface — every static tool
+ * plus generated action tools (spec §25.5) — so a connected model knows
+ * 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;
+    };
+};
+type Reply = Response | Response[];
+/**
+ * @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.
+ */
+export declare const createServer: (store: Store, options?: ServerOptions) => {
+    handle: (message: unknown) => undefined | Reply;
+};
+/**
+ * Serves MCP over newline-delimited JSON-RPC on the given streams until
+ * the input closes. Protocol traffic only on `output` — logs belong on
+ * stderr.
+ */
+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

@@ -0,0 +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"}

package/dist/internal/mcp/server.js

@@ -0,0 +1,251 @@
+/**
+ * MCP server over stdio — newline-delimited JSON-RPC 2.0.
+ *
+ * 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).
+ */
+import { createInterface } from 'node:readline';
+import { Version } from '@cavelang/core';
+import { actToolPrefix, allowsActions, scopedActionTools, scopedTools, tools } from "./tools.js";
+/**
+ * @returns `agent/<name>` source context from an MCP client name —
+ * lowercased, whitespace to `-`, restricted to context-safe characters;
+ * plain `agent` when no usable name is known (spec §9.5).
+ */
+export const agentSource = (clientName) => {
+    const name = (clientName ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9._/-]/g, '');
+    return name === '' ? 'agent' : `agent/${name}`;
+};
+/** The single MCP protocol revision this server implements. */
+export const protocolVersion = '2025-06-18';
+export const serverInfo = {
+    name: 'cave',
+    version: Version.current()
+};
+/**
+ * The spec §22 compact card — tool-agnostic CAVE writing knowledge,
+ * shared with `@cavelang/cli/ingest` prompts.
+ */
+export const specCard = `CAVE (Compressed Atomic Verb Expressions) persists knowledge as atomic claims:
+
+  subject VERB [NOT] object                [@context...] [#tag[:value]...] [@ N%] [!] [; comment]
+  subject HAS attribute: value [+/- delta] [@context...] [#tag[:value]...] [@ N%] [!] [; comment]
+
+Examples:
+  auth/middleware USES jwt @ 90%
+  OpenAI HAS revenue: ~20B USD/yr +/- 2B USD/yr @2026-Q1
+  server IS NOT compromised @ 90%
+  memory-leak CAUSE app/crash @ 70% #topic:stability
+
+Verbs are UPPERCASE (IS, HAS, CAUSE, FIX, NEEDS, USES, YIELDS, ENABLES, BLOCKS,
+CONTAINS, PRECEDES, EXTENDS, ALIAS, LIKE, EXISTS, VS, BECOMES, EXCEEDS,
+IS-BELOW, IS-AT-LEAST, IS-AT-MOST, EQUALS, DIFFERS-FROM).
+Entities are kebab-case with / for scope (auth/middleware). @ctx = context
+(no space), @ 90% = confidence (space). Storage is append-only: update belief
+by adding the same claim with new confidence; retract with @ 0%.`;
+/**
+ * Server instructions for a served tool surface — the card plus tool
+ * guidance mentioning only tools actually served, so a connected model is
+ * never pointed at a tool the scope hides. A surface with no writing tool
+ * says so outright. `actions` marks a scope that (also) serves generated
+ * action tools (spec §25.5) — a write surface even when no static tool
+ * writes.
+ */
+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_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'] : [],
+        ...has('cave_query') ? ['ask questions with cave_query patterns (?x USES jwt)'] : [],
+        ...has('cave_fuse') ? ['delegate combining numeric estimates to cave_fuse (Bayesian fusion) instead of averaging in tokens'] : [],
+        ...explore.length > 0 ? [`explore with ${explore.join(' / ')}`] : [],
+        ...has('cave_reconstruct') ? ['use cave_reconstruct to pull everything related to a symptom or task before reasoning about it'] : [],
+        ...has('cave_derive') ? ['fire the stored rules with cave_derive so derived knowledge materializes with lineage'] : []
+    ];
+    const last = clauses.length - 1;
+    const guidance = [
+        ...clauses.length === 0 ? [] : [clauses
+                .map((clause, index) => index === 0 ? `${clause[0].toUpperCase()}${clause.slice(1)}` : index === last ? `and ${clause}` : clause)
+                .join(',\n') + '.'],
+        ...has('cave_add') ? [
+            'Claims you add without a @src: context are stamped with your agent source\n' +
+                'context; to update or retract a claim that carries a different @src:,\n' +
+                'restate it with that exact context.'
+        ] : [],
+        ...options.actions === true ? [
+            'Actions declared in the knowledge database are served as act_<name>\n' +
+                'tools (spec §25) — a governed write vocabulary: parameters validated,\n' +
+                'preconditions checked against current belief, effects appended\n' +
+                `atomically with provenance. Prefer them over ${has('cave_add') ? 'cave_add' : 'freeform appends'} when one fits.`
+        ] : [],
+        ...(served.some(tool => tool.permission === 'record' || tool.permission === 'action') || options.actions === true ?
+            [] : ['This server is read-only: no tool writes to the knowledge database.'])
+    ].join('\n');
+    return guidance === '' ? specCard : `${specCard}\n\n${guidance}`;
+};
+/**
+ * Server instructions for the full default surface — every static tool
+ * plus generated action tools (spec §25.5) — so a connected model knows
+ * 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.
+ */
+export const createServer = (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 { 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');
+        }
+        if (!hasId) {
+            // Notifications (notifications/initialized, notifications/cancelled, …)
+            // require no response.
+            return undefined;
+        }
+        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 };
+};
+/**
+ * Serves MCP over newline-delimited JSON-RPC on the given streams until
+ * the input closes. Protocol traffic only on `output` — logs belong on
+ * stderr.
+ */
+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() === '') {
+                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);
+            resolve();
+        });
+        if (options.signal?.aborted === true) {
+            lines.close();
+        }
+    });
+};
+//# sourceMappingURL=server.js.map

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

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

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

@@ -0,0 +1,91 @@
+/**
+ * The CAVE engine surface exposed as MCP tools, all operating on one open
+ * `@cavelang/store` database:
+ *
+ * | Tool | Purpose |
+ * |---|---|
+ * | `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 |
+ * | `cave_search` | full-text search over claims and comments |
+ * | `cave_about` | current claims about an entity, both directions |
+ * | `cave_neighbors` | named forward + inverse edges of an entity (§13.3) |
+ * | `cave_reconstruct` | cave-loop active reconstruction from seed cues (§18) |
+ * | `cave_derive` | fire the stored rules (§24) — named computation |
+ * | `cave_export` | canonical CAVE text of the store |
+ * | `cave_lint` | parse text and report diagnostics without storing |
+ *
+ * Results are text — canonical CAVE lines wherever claims are returned,
+ * because that is the notation the client model is instructed with.
+ *
+ * Every tool declares its permission class; `scopedTools` narrows the
+ * served surface to a `Scope` (`--read-only`, `--permissions`, `--tools`) —
+ * the minimum viable agent permission boundary.
+ */
+import type { Store } from '@cavelang/store';
+/** Per-connection state the server threads into tool calls. */
+export type ToolContext = {
+    /**
+     * Actor provenance stamp for appends (spec §9.5), without the `src:`
+     * prefix — e.g. `agent/claude-code`. `undefined` disables stamping.
+     */
+    readonly source?: string;
+    /** Out-of-band hook command templates for action tools (spec §25.4). */
+    readonly hooks?: Readonly<Record<string, string>>;
+};
+export declare const permissions: readonly ["read", "evaluate", "record", "action"];
+export type Permission = typeof permissions[number];
+export type Tool = {
+    readonly name: string;
+    readonly description: string;
+    /** Evaluation is ephemeral, recording is durable, and action may cause effects. */
+    readonly permission: Permission;
+    readonly inputSchema: object;
+    readonly run: (store: Store, args: Record<string, unknown>, context: ToolContext) => string;
+};
+/**
+ * Serving scope — which tools the server exposes (the minimum viable
+ * agent permission boundary). Tools outside the scope are absent from
+ * `tools/list` and indistinguishable from nonexistent in `tools/call`.
+ */
+export type Scope = {
+    /** Serve only tools that never write to the store (drops `cave_add`). */
+    readonly readOnly?: boolean;
+    /** Serve only these operation classes; `readOnly` removes record/action. */
+    readonly permissions?: readonly Permission[];
+    /**
+     * Serve only these tools, by name. `readOnly` narrows further: a
+     * writing tool listed here is still not served.
+     */
+    readonly tools?: readonly string[];
+};
+export declare const tools: readonly Tool[];
+export declare const byName: ReadonlyMap<string, Tool>;
+/** Tool-name prefix of generated action tools (spec §25.5). */
+export declare const actToolPrefix = "act_";
+/**
+ * MCP tool name of an action: `act_` plus the action name with
+ * characters outside the MCP tool alphabet mapped to `_`
+ * (`team/promote` → `act_team_promote`).
+ */
+export declare const actToolName: (action: string) => string;
+/**
+ * @returns the generated action tools of the store's current positive
+ * declarations (spec §25.5), computed per call so an action declared
+ * mid-session appears without reconnecting. Actions whose stored body
+ * does not parse are skipped, as are name collisions after MCP-alphabet
+ * mapping (first declaration wins).
+ */
+export declare const actionTools: (store: Store) => Tool[];
+export declare const allowsActions: (scope?: Scope) => boolean;
+export declare const scopedActionTools: (store: Store, scope?: Scope) => Tool[];
+/**
+ * @returns the static tool surface actually served under a scope: `tools`
+ * (when given) narrowed by permission and by `readOnly`. Throws on
+ * names that exist nowhere and on a scope that serves nothing — a
+ * misconfigured permission boundary must fail loudly, not serve quietly.
+ * `act_`-prefixed names pass through: they scope generated action tools
+ * (spec §25.5), resolved against the store at call time.
+ */
+export declare const scopedTools: (scope?: Scope) => readonly Tool[];
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +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"}