peaks-loop 4.1.2 → 4.1.3

package/dist/services/mcp/cli-executor.d.ts

@@ -0,0 +1,36 @@
+/** Ceiling on one CLI execution. Generous for a read, far short of "forever". */
+export declare const DEFAULT_EXECUTION_TIMEOUT_MS = 15000;
+/** How to start this tree's own CLI. */
+export interface CliLaunch {
+    readonly command: string;
+    readonly argsPrefix: readonly string[];
+}
+/**
+ * Resolve the platform-neutral launch shape. Uses the shared daemon-supervisor
+ * resolvers rather than a second copy of them: the entry path and the
+ * TypeScript-loader flags have to agree with every other self-spawn in this
+ * tree, and the file that owns them says so in as many words.
+ */
+export declare function resolveCliLaunch(): CliLaunch;
+export interface CliExecution {
+    /** The concrete argv that was handed to the CLI, without the launch prefix. */
+    readonly argv: readonly string[];
+    /** Exit status, or `null` when the process died on a signal or was killed. */
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** True when the deadline fired and the child was killed. */
+    readonly timedOut: boolean;
+    /** Set ONLY when the process could not be started at all. Never set on timeout. */
+    readonly launchError?: string;
+}
+export interface ExecuteOptions {
+    readonly launch?: CliLaunch;
+    readonly timeoutMs?: number;
+    readonly cwd?: string;
+}
+/**
+ * Run one argv. Always resolves: a failure is a described outcome, never a
+ * rejection, because the caller has to report it to the harness either way.
+ */
+export declare function executeCliArgv(argv: readonly string[], options?: ExecuteOptions): Promise<CliExecution>;

package/dist/services/mcp/cli-executor.js

@@ -0,0 +1,97 @@
+// src/services/mcp/cli-executor.ts
+//
+// The one place the MCP server touches the outside world: it runs a concrete
+// argv against the peaks CLI and hands back what happened.
+//
+// THREE RULES, EACH MEASURED INTO THE SHAPE BELOW.
+//
+// 1. NO SHELL, NO PLATFORM BRANCH (spec §8.2). The launch is
+//    `node <this tree's CLI entry>` — `process.execPath` plus the argument list
+//    that makes this Node interpret that entry. Naming the CLI as a command
+//    (`peaks`) is measurably wrong on a platform whose CLI is a batch shim:
+//    Node refuses to spawn `.cmd`/`.bat` without a shell, and with a shell the
+//    argv array stops being an argv array. `process.execPath` needs neither, so
+//    one shape serves every platform and no `if (platform)` exists.
+//
+// 2. THE TIMEOUT IS MANDATORY, NOT OPTIONAL. `peaks job status --watch` never
+//    returns. It is outside the read-only surface, but it proves the class: a
+//    server that waits forever on a hung child gives its caller no recovery
+//    path. A timeout therefore returns a NAMED failure, never an empty success
+//    (spec §7.2 + §9 rule 3).
+//
+// 3. THE CHILD GETS NO STDIN. Our stdin is the JSON-RPC transport; a child that
+//    inherited it would read our protocol stream and answer the harness itself.
+import { spawn } from 'node:child_process';
+import { readonlySpawnOptions } from '../readonly-surface/argv-guard.js';
+import { cliEntryPath, interpreterArgs } from '../web/daemon-supervisor.js';
+/** Ceiling on one CLI execution. Generous for a read, far short of "forever". */
+export const DEFAULT_EXECUTION_TIMEOUT_MS = 15_000;
+/**
+ * Resolve the platform-neutral launch shape. Uses the shared daemon-supervisor
+ * resolvers rather than a second copy of them: the entry path and the
+ * TypeScript-loader flags have to agree with every other self-spawn in this
+ * tree, and the file that owns them says so in as many words.
+ */
+export function resolveCliLaunch() {
+    return { command: process.execPath, argsPrefix: interpreterArgs(cliEntryPath()) };
+}
+/** The spawn + drain half: one child, one settlement, whatever happens to it. */
+function runChild(launch, argv, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let settled = false;
+        let launchError;
+        const child = spawn(launch.command, [...launch.argsPrefix, ...argv], {
+            ...readonlySpawnOptions(),
+            cwd,
+            // stdin must stay ours; stdout/stderr are read as data.
+            stdio: ['ignore', 'pipe', 'pipe'],
+            // Windows contract: a spawned child must not allocate a console window.
+            windowsHide: true
+        });
+        const deadline = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, timeoutMs);
+        const settle = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            const outcome = { argv, exitCode, stdout, stderr, timedOut };
+            resolve(launchError === undefined ? outcome : { ...outcome, launchError });
+        };
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        child.on('error', (error) => {
+            launchError = error.message;
+        });
+        // `close` (not `exit`) so both pipes are drained before we read them.
+        child.on('close', (code) => {
+            settle(code);
+        });
+    });
+}
+/**
+ * Run one argv. Always resolves: a failure is a described outcome, never a
+ * rejection, because the caller has to report it to the harness either way.
+ */
+export async function executeCliArgv(argv, options = {}) {
+    let launch;
+    try {
+        launch = options.launch ?? resolveCliLaunch();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { argv, exitCode: null, stdout: '', stderr: '', timedOut: false, launchError: message };
+    }
+    return runChild(launch, argv, options.cwd ?? process.cwd(), options.timeoutMs ?? DEFAULT_EXECUTION_TIMEOUT_MS);
+}

package/dist/services/mcp/json-rpc.d.ts

@@ -0,0 +1,81 @@
+/** The only JSON-RPC version this server speaks. */
+export declare const JSON_RPC_VERSION: "2.0";
+/** A request/response correlation id. `null` is legal and means "unknown". */
+export type JsonRpcId = string | number | null;
+export interface JsonRpcErrorObject {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+}
+export interface JsonRpcRequest {
+    readonly jsonrpc: typeof JSON_RPC_VERSION;
+    readonly id: JsonRpcId;
+    readonly method: string;
+    readonly params?: unknown;
+}
+/** A request WITHOUT an id. JSON-RPC forbids replying to one. */
+export interface JsonRpcNotification {
+    readonly jsonrpc: typeof JSON_RPC_VERSION;
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface JsonRpcSuccess {
+    readonly jsonrpc: typeof JSON_RPC_VERSION;
+    readonly id: JsonRpcId;
+    readonly result: unknown;
+}
+export interface JsonRpcFailure {
+    readonly jsonrpc: typeof JSON_RPC_VERSION;
+    readonly id: JsonRpcId;
+    readonly error: JsonRpcErrorObject;
+}
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcFailure;
+/** Standard JSON-RPC codes. The server adds no private codes of its own. */
+export declare const JSON_RPC_PARSE_ERROR = -32700;
+export declare const JSON_RPC_INVALID_REQUEST = -32600;
+export declare const JSON_RPC_METHOD_NOT_FOUND = -32601;
+export declare const JSON_RPC_INVALID_PARAMS = -32602;
+export declare const JSON_RPC_INTERNAL_ERROR = -32603;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** What one decoded line turned out to be. */
+export type DecodedMessage = {
+    readonly kind: 'request';
+    readonly request: JsonRpcRequest;
+} | {
+    readonly kind: 'notification';
+    readonly notification: JsonRpcNotification;
+} | {
+    readonly kind: 'invalid';
+    readonly id: JsonRpcId;
+    readonly error: JsonRpcErrorObject;
+};
+export declare function makeError(code: number, message: string, data?: unknown): JsonRpcErrorObject;
+export declare function successResponse(id: JsonRpcId, result: unknown): JsonRpcSuccess;
+export declare function failureResponse(id: JsonRpcId, error: JsonRpcErrorObject): JsonRpcFailure;
+/**
+ * Decode one frame.
+ *
+ * `undefined` means "nothing to answer" — an empty line, which is legal padding
+ * and must not be reported as a parse error (an empty line is not a message the
+ * peer sent; it is whitespace between messages).
+ */
+export declare function decodeMessage(line: string): DecodedMessage | undefined;
+/**
+ * Encode one frame for the wire. `JSON.stringify` escapes every newline inside
+ * a string, which is what keeps one message on one line.
+ */
+export declare function encodeMessage(message: JsonRpcResponse | JsonRpcNotification): string;
+/**
+ * The buffer that turns an arbitrary chunking of bytes into whole lines.
+ *
+ * Needed because a pipe delivers no framing of its own: one `data` event may
+ * carry half a message or three of them, and a server that parsed each event as
+ * a message would work on a fast local pipe and fail on a loaded one.
+ */
+export declare class LineDecoder {
+    private buffer;
+    /** Feed a chunk; get back the complete lines it completed (no trailing newline). */
+    push(chunk: string): string[];
+    /** Whatever is left when the stream ends. A peer that never sent a newline still sent a message. */
+    flush(): string[];
+}

package/dist/services/mcp/json-rpc.js

@@ -0,0 +1,116 @@
+// src/services/mcp/json-rpc.ts
+//
+// JSON-RPC 2.0 message shapes plus the stdio framing MCP uses, implemented in
+// this tree rather than pulled in as a dependency.
+//
+// WHY NOT THE SDK. peaks-loop ships 12 runtime dependencies to every user
+// globally, and the protocol surface this server needs is four methods and five
+// error codes — all frozen since the first MCP revision. A dependency would be
+// the larger commitment. See the slice report for the exact surface list.
+//
+// THE FRAMING IS NEWLINE-DELIMITED JSON, not LSP's `Content-Length` headers.
+// That is the MCP stdio transport's rule, and it is also why a message may not
+// contain a raw newline: this module therefore serializes with `JSON.stringify`
+// (which escapes newlines inside strings) and never pretty-prints.
+/** The only JSON-RPC version this server speaks. */
+export const JSON_RPC_VERSION = '2.0';
+/** Standard JSON-RPC codes. The server adds no private codes of its own. */
+export const JSON_RPC_PARSE_ERROR = -32700;
+export const JSON_RPC_INVALID_REQUEST = -32600;
+export const JSON_RPC_METHOD_NOT_FOUND = -32601;
+export const JSON_RPC_INVALID_PARAMS = -32602;
+export const JSON_RPC_INTERNAL_ERROR = -32603;
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isJsonRpcId(value) {
+    return typeof value === 'string' || typeof value === 'number' || value === null;
+}
+export function makeError(code, message, data) {
+    return data === undefined ? { code, message } : { code, message, data };
+}
+export function successResponse(id, result) {
+    return { jsonrpc: JSON_RPC_VERSION, id, result };
+}
+export function failureResponse(id, error) {
+    return { jsonrpc: JSON_RPC_VERSION, id, error };
+}
+function invalid(id, code, message) {
+    return { kind: 'invalid', id, error: makeError(code, message) };
+}
+/** The message's id when it carries a legal one, else the protocol's `null`. */
+function idOf(parsed) {
+    const id = parsed['id'];
+    return isJsonRpcId(id) ? id : null;
+}
+/**
+ * Build the message from a well-formed envelope. The presence of the `id` KEY is
+ * the only thing separating a request from a notification — `id: null` is a legal
+ * id, so this cannot be written as a null check.
+ */
+function buildMessage(parsed, method) {
+    const params = parsed['params'];
+    const head = { jsonrpc: JSON_RPC_VERSION, method, ...(params === undefined ? {} : { params }) };
+    return 'id' in parsed
+        ? { kind: 'request', request: { ...head, id: idOf(parsed) } }
+        : { kind: 'notification', notification: head };
+}
+/**
+ * Decode one frame.
+ *
+ * `undefined` means "nothing to answer" — an empty line, which is legal padding
+ * and must not be reported as a parse error (an empty line is not a message the
+ * peer sent; it is whitespace between messages).
+ */
+export function decodeMessage(line) {
+    if (line.trim().length === 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return invalid(null, JSON_RPC_PARSE_ERROR, 'Invalid JSON received on the transport.');
+    }
+    if (!isPlainObject(parsed) || parsed['jsonrpc'] !== JSON_RPC_VERSION) {
+        const id = isPlainObject(parsed) ? idOf(parsed) : null;
+        return invalid(id, JSON_RPC_INVALID_REQUEST, `Messages must declare jsonrpc "${JSON_RPC_VERSION}".`);
+    }
+    const method = parsed['method'];
+    if (typeof method !== 'string' || method.length === 0) {
+        return invalid(idOf(parsed), JSON_RPC_INVALID_REQUEST, 'Messages must carry a non-empty "method".');
+    }
+    return buildMessage(parsed, method);
+}
+/**
+ * Encode one frame for the wire. `JSON.stringify` escapes every newline inside
+ * a string, which is what keeps one message on one line.
+ */
+export function encodeMessage(message) {
+    return `${JSON.stringify(message)}\n`;
+}
+/**
+ * The buffer that turns an arbitrary chunking of bytes into whole lines.
+ *
+ * Needed because a pipe delivers no framing of its own: one `data` event may
+ * carry half a message or three of them, and a server that parsed each event as
+ * a message would work on a fast local pipe and fail on a loaded one.
+ */
+export class LineDecoder {
+    buffer = '';
+    /** Feed a chunk; get back the complete lines it completed (no trailing newline). */
+    push(chunk) {
+        this.buffer += chunk;
+        const lines = this.buffer.split('\n');
+        // The last element is either an incomplete line or '' when the chunk ended
+        // on a newline. Either way it stays buffered for the next push.
+        this.buffer = lines.pop() ?? '';
+        return lines;
+    }
+    /** Whatever is left when the stream ends. A peer that never sent a newline still sent a message. */
+    flush() {
+        const remainder = this.buffer.trim().length > 0 ? [this.buffer] : [];
+        this.buffer = '';
+        return remainder;
+    }
+}

package/dist/services/mcp/memory-tool.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from './surface.js';
+import { type ToolCallContext, type ToolCallResult } from './tool-core.js';
+export declare function callMemorySearchTool(tool: McpToolDefinition, args: Readonly<Record<string, unknown>>, context: ToolCallContext): Promise<ToolCallResult>;

package/dist/services/mcp/memory-tool.js

@@ -0,0 +1,62 @@
+// src/services/mcp/memory-tool.ts
+//
+// `peaks_memory_search`: one argv, a bounded reply (§7.1).
+//
+// It answers "is there anything, and what is it called" — never "what does it
+// say". The raw CLI output is measured in megabytes, so the reply is bounded
+// twice over: a hard ceiling on how many matches come back, and a truncated
+// excerpt per match. Both are on §3.2's allowed list for a composite tool
+// (field selection and truncation), and neither concludes anything: the count,
+// the names and the first characters are all the CLI's.
+import { buildArgv } from '../readonly-surface/argv-guard.js';
+import { MEMORY_EXCERPT_CHARS, MEMORY_MAX_RETURNED, rejectedResult, resultOf, runArgv, valuesForEntry } from './tool-core.js';
+/** Project one raw CLI match down to the fields §7.1 allows, with a bounded excerpt. */
+function boundMatch(raw) {
+    const match = typeof raw === 'object' && raw !== null ? raw : {};
+    const description = typeof match['description'] === 'string' ? match['description'] : '';
+    return {
+        name: match['name'],
+        kind: match['kind'],
+        excerpt: description.slice(0, MEMORY_EXCERPT_CHARS)
+    };
+}
+export async function callMemorySearchTool(tool, args, context) {
+    const entry = tool.entries[0];
+    if (entry === undefined) {
+        return { content: [{ type: 'text', text: '{"reason":"no entry"}' }], isError: true };
+    }
+    const values = valuesForEntry(entry, args, context);
+    if (values === undefined) {
+        return rejectedResult(entry, 'A search query is required.');
+    }
+    const built = buildArgv(entry, values);
+    if (!built.ok) {
+        return rejectedResult(entry, `Parameter ${built.param} was refused: ${built.message}`);
+    }
+    const outcome = await runArgv(entry.id, built.argv, context);
+    if (outcome.failure !== undefined)
+        return resultOf([outcome]);
+    const envelope = outcome.envelope;
+    const record = typeof envelope === 'object' && envelope !== null ? envelope : {};
+    const matches = record['matches'];
+    if (!Array.isArray(matches)) {
+        // No `matches` array is not "nothing matched" — it is a shape this tool does
+        // not understand, and reporting it as empty is the failure §9 rule 3 names.
+        const argv = outcome.execution.argv.join(' ');
+        return resultOf([
+            { ...outcome, failure: `peaks memory search returned no matches array: peaks ${argv}` }
+        ]);
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    query: record['query'],
+                    total: record['total'],
+                    matches: matches.slice(0, MEMORY_MAX_RETURNED).map(boundMatch)
+                })
+            }
+        ]
+    };
+}

package/dist/services/mcp/server-main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/mcp/server-main.js

@@ -0,0 +1,66 @@
+// src/services/mcp/server-main.ts
+//
+// The process entry: a stdin pipe, a stdout pipe, and spec §6's L4 check before
+// either is used.
+//
+// STDOUT CARRIES PROTOCOL AND NOTHING ELSE. Any diagnostic goes to stderr,
+// because a harness reads stdout as the message stream and one stray line is a
+// parse error that is indistinguishable from a broken server. That is also why
+// the startup refusal below writes to stderr and exits non-zero rather than
+// printing a JSON error: at that point there is no session to answer in.
+//
+// L4 REFUSES TO START. If the surface cannot be served as proven — a tool with
+// no description, an argv the whitelist does not carry, a whitelisted argv
+// reachable from no tool, or a tool with no handler — this process exits 1.
+// A server that started anyway would be serving something nobody proved, and the
+// failure would surface as data rather than as a refusal (spec §6, L4).
+import { loadReadOnlyWhitelist } from '../readonly-surface/readonly-whitelist.js';
+import { LineDecoder } from './json-rpc.js';
+import { buildToolDefinitions, validateSurface } from './surface.js';
+import { createMcpServer } from './server.js';
+import { missingHandlers } from './tools.js';
+function refuse(reason) {
+    process.stderr.write(`peaks mcp: ${reason}\n`);
+    process.exit(1);
+}
+function start() {
+    let tools;
+    try {
+        const whitelist = loadReadOnlyWhitelist();
+        tools = buildToolDefinitions(whitelist);
+        validateSurface(whitelist, tools);
+    }
+    catch (error) {
+        refuse(`refusing to start: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const unserved = missingHandlers(tools);
+    if (unserved.length > 0) {
+        refuse(`refusing to start: no handler for tool(s) ${unserved.join(', ')}`);
+    }
+    const server = createMcpServer({ tools });
+    const decoder = new LineDecoder();
+    const write = (line) => {
+        if (line !== undefined)
+            process.stdout.write(line);
+    };
+    const consume = (line) => {
+        void server.handleLine(line).then(write);
+    };
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+        for (const line of decoder.push(chunk))
+            consume(line);
+    });
+    process.stdin.on('end', () => {
+        for (const line of decoder.flush())
+            consume(line);
+    });
+    // A read error on our own transport is not recoverable and not ours to
+    // interpret: report it and stop, so the harness sees a dead server instead of
+    // a live one that answers nothing.
+    process.stdin.on('error', (error) => {
+        process.stderr.write(`peaks mcp: stdin error: ${error.message}\n`);
+        process.exitCode = 1;
+    });
+}
+start();

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

@@ -0,0 +1,22 @@
+import type { McpToolDefinition } from './surface.js';
+import { type ToolCallContext } from './tool-core.js';
+/** Used when the client names no protocol version. */
+export declare const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+/** The server's own name, as it appears in `initialize`. */
+export declare const SERVER_NAME = "peaks";
+export declare const METHOD_INITIALIZE = "initialize";
+export declare const METHOD_INITIALIZED = "notifications/initialized";
+export declare const METHOD_TOOLS_LIST = "tools/list";
+export declare const METHOD_TOOLS_CALL = "tools/call";
+export interface McpServerOptions {
+    readonly tools: readonly McpToolDefinition[];
+    readonly context?: ToolCallContext;
+    readonly serverVersion?: string;
+}
+export interface McpServer {
+    /** Answer one line. A notification (or blank line) yields `undefined`. */
+    handleLine(line: string): Promise<string | undefined>;
+    /** The tools, for a caller that wants to assert what it built. */
+    readonly tools: readonly McpToolDefinition[];
+}
+export declare function createMcpServer(options: McpServerOptions): McpServer;

package/dist/services/mcp/server.js

@@ -0,0 +1,152 @@
+// src/services/mcp/server.ts
+//
+// The protocol core: one decoded line in, at most one encoded line out.
+//
+// WHAT THIS SERVER IS. A table lookup, an execution, and the CLI's own answer —
+// nothing else (spec §3, component 3: "there is no fourth responsibility").
+// It does not know what a gate is, does not cache, keeps no state between
+// messages, and never rewrites a CLI result. `handleLine` is a pure function of
+// (line, surface, context), which is also what makes it testable without a pipe.
+//
+// THE PROTOCOL SURFACE IS DELIBERATELY SMALL and is listed in full here so it can
+// be checked line by line rather than inferred:
+//
+//   initialize                -> protocolVersion, capabilities.tools, serverInfo
+//   notifications/initialized -> accepted, no reply (it is a notification)
+//   tools/list                -> tools[] {name, description, inputSchema}
+//   tools/call                -> params {name, arguments} -> content[] | isError
+//   (anything else, request)  -> -32601 METHOD_NOT_FOUND
+//   (anything else, notification) -> ignored; JSON-RPC forbids replying
+//   malformed JSON            -> -32700   wrong envelope -> -32600
+//   bad tools/call params     -> -32602   handler crash  -> -32603
+//
+// NOT IMPLEMENTED, on purpose: `ping`, `resources/*`, `prompts/*`, `logging/*`,
+// `completion/*`, `notifications/*` beyond `initialized`, progress tokens,
+// cancellation, and resource subscriptions. Any of them arrives as a
+// METHOD_NOT_FOUND rather than as silence.
+//
+// NO HANDSHAKE STATE. The server does not track whether `initialize` has been
+// seen; every method is answerable on any line. MCP asks clients to initialize
+// first, and this server simply does not depend on it — a state machine here
+// would be state kept for no decision.
+//
+// PROTOCOL VERSION. The client's requested version is echoed when it names one,
+// and a constant is used otherwise. Echoing is honest for this surface and not a
+// claim of unlimited support: the four methods above have had identical request
+// and response shapes across every published revision, so there is no version
+// whose meaning this server would get wrong.
+import { CLI_VERSION } from 'peaks-loop-shared/version';
+import { decodeMessage, encodeMessage, failureResponse, isPlainObject, makeError, successResponse, JSON_RPC_INTERNAL_ERROR, JSON_RPC_INVALID_PARAMS, JSON_RPC_METHOD_NOT_FOUND } from './json-rpc.js';
+import { handlerFor } from './tools.js';
+/** Used when the client names no protocol version. */
+export const DEFAULT_PROTOCOL_VERSION = '2025-06-18';
+/** The server's own name, as it appears in `initialize`. */
+export const SERVER_NAME = 'peaks';
+export const METHOD_INITIALIZE = 'initialize';
+export const METHOD_INITIALIZED = 'notifications/initialized';
+export const METHOD_TOOLS_LIST = 'tools/list';
+export const METHOD_TOOLS_CALL = 'tools/call';
+/** The tool shape that goes on the wire — behaviour without the whitelist entries. */
+function wireTool(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+    };
+}
+function requestedVersion(params) {
+    if (!isPlainObject(params))
+        return undefined;
+    const version = params['protocolVersion'];
+    return typeof version === 'string' && version.length > 0 ? version : undefined;
+}
+function callArguments(params) {
+    const args = params['arguments'];
+    if (args === undefined)
+        return {};
+    return isPlainObject(args) ? args : undefined;
+}
+/**
+ * Reject an argument the tool does not declare, BEFORE anything runs. The tool
+ * schemas set `additionalProperties: false`; enforcing it here is what makes
+ * that a promise rather than a hint, and it is the boundary at which an
+ * injection-shaped key ("--apply") stops being an argument.
+ */
+function unknownArgument(tool, args) {
+    const declared = new Set(Object.keys(tool.inputSchema.properties));
+    return Object.keys(args).find((name) => !declared.has(name));
+}
+function initializeResult(params, version) {
+    return {
+        protocolVersion: requestedVersion(params) ?? DEFAULT_PROTOCOL_VERSION,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: SERVER_NAME, version }
+    };
+}
+function fail(id, message) {
+    return encodeMessage(failureResponse(id, makeError(JSON_RPC_INVALID_PARAMS, message)));
+}
+async function toolsCallResult(tools, context, id, params) {
+    if (!isPlainObject(params)) {
+        return fail(id, 'tools/call requires an object of parameters.');
+    }
+    const name = params['name'];
+    if (typeof name !== 'string' || name.length === 0) {
+        return fail(id, 'tools/call requires a tool "name".');
+    }
+    const tool = tools.find((candidate) => candidate.name === name);
+    const handler = tool === undefined ? undefined : handlerFor(tool.name);
+    if (tool === undefined || handler === undefined) {
+        return fail(id, `Unknown tool: ${name}`);
+    }
+    const args = callArguments(params);
+    if (args === undefined) {
+        return fail(id, 'tools/call "arguments" must be an object.');
+    }
+    const unexpected = unknownArgument(tool, args);
+    if (unexpected !== undefined) {
+        return fail(id, `Tool ${name} declares no argument "${unexpected}".`);
+    }
+    return encodeMessage(successResponse(id, await handler(tool, args, context)));
+}
+export function createMcpServer(options) {
+    const tools = options.tools;
+    const context = options.context ?? {};
+    const version = options.serverVersion ?? CLI_VERSION;
+    const respond = async (id, method, params) => {
+        switch (method) {
+            case METHOD_INITIALIZE:
+                return encodeMessage(successResponse(id, initializeResult(params, version)));
+            case METHOD_TOOLS_LIST:
+                return encodeMessage(successResponse(id, { tools: tools.map(wireTool) }));
+            case METHOD_TOOLS_CALL:
+                return toolsCallResult(tools, context, id, params);
+            default:
+                return encodeMessage(failureResponse(id, makeError(JSON_RPC_METHOD_NOT_FOUND, `Unknown method: ${method}`)));
+        }
+    };
+    const handleLine = async (line) => {
+        const decoded = decodeMessage(line);
+        if (decoded === undefined)
+            return undefined;
+        if (decoded.kind === 'invalid') {
+            return encodeMessage(failureResponse(decoded.id, decoded.error));
+        }
+        if (decoded.kind === 'notification') {
+            // Notifications are answered by not answering. `initialized` needs no
+            // branch of its own for that reason — but an unknown one is silently
+            // dropped, which is the protocol's rule, not this server's leniency.
+            return undefined;
+        }
+        try {
+            return await respond(decoded.request.id, decoded.request.method, decoded.request.params);
+        }
+        catch (error) {
+            // A handler crash is reported, never swallowed: the caller has to know the
+            // answer is missing rather than empty.
+            const message = error instanceof Error ? error.message : 'Internal error';
+            return encodeMessage(failureResponse(decoded.request.id, makeError(JSON_RPC_INTERNAL_ERROR, message)));
+        }
+    };
+    return { tools, handleLine };
+}