r2mcp 0.2.0

package/dist/tools/classify.d.ts

@@ -0,0 +1,44 @@
+/**
+ * MCP tool handler for `classify()` — wraps the SPEC-043 edge classifier.
+ *
+ * Per the SPEC-044 invariant that the MCP server itself makes no LLM
+ * calls, this handler spawns the standalone classify-edges driver as a
+ * subprocess. The actual provider calls happen in that subprocess.
+ *
+ * The subprocess command is resolved via resolveCliCommand so the tool
+ * works for both dev (tsx + .ts) and prod (node + dist/.js) consumers.
+ */
+import { spawn } from 'node:child_process';
+export interface ClassifyToolInput {
+    /** Filter candidate pairs to memories updated in the last N days. */
+    since_days?: number;
+    /** Per-run cost cap in USD. Default: $1.00 (R2MCP_EDGE_MAX_USD env). */
+    max_cost_usd?: number;
+    /** Estimate-only mode — no edges written, no LLM calls beyond Stage 1 sampling. */
+    dry_run?: boolean;
+    /** Resume a prior run_id; pairs already terminal in that run are not re-classified. */
+    resume_run_id?: string;
+    /** Force a specific provider for this run. */
+    provider?: 'claude-code' | 'anthropic' | 'openrouter';
+}
+export interface ClassifySummary {
+    run_id: string;
+    started_at: string;
+    ended_at: string;
+    candidate_pairs: number;
+    stage1_total: number;
+    stage1_pass: number;
+    stage1_skip: number;
+    stage2_total: number;
+    stage2_classified: number;
+    edges_written: number;
+    total_cost_usd: number;
+    hit_cost_cap: boolean;
+    error?: string;
+}
+export interface ClassifyToolDeps {
+    spawnFn?: typeof spawn;
+    cwd?: string;
+    runTimeoutMs?: number;
+}
+export declare function classify(input: ClassifyToolInput, deps?: ClassifyToolDeps): Promise<ClassifySummary>;

package/dist/tools/classify.js

@@ -0,0 +1,121 @@
+/**
+ * MCP tool handler for `classify()` — wraps the SPEC-043 edge classifier.
+ *
+ * Per the SPEC-044 invariant that the MCP server itself makes no LLM
+ * calls, this handler spawns the standalone classify-edges driver as a
+ * subprocess. The actual provider calls happen in that subprocess.
+ *
+ * The subprocess command is resolved via resolveCliCommand so the tool
+ * works for both dev (tsx + .ts) and prod (node + dist/.js) consumers.
+ */
+import { spawn } from 'node:child_process';
+import { resolveCliCommand } from './spawn-cli.js';
+export async function classify(input, deps = {}) {
+    const { bin, args: cliArgs } = resolveCliCommand('classify-edges');
+    const flags = buildArgs(input);
+    const cwd = deps.cwd ?? process.cwd();
+    const spawnFn = deps.spawnFn ?? spawn;
+    const timeoutMs = deps.runTimeoutMs ?? 30 * 60_000;
+    const stdout = await runSubprocess(spawnFn, cwd, [bin, ...cliArgs, ...flags], timeoutMs);
+    return parseSummary(stdout);
+}
+function buildArgs(input) {
+    const flags = [];
+    if (typeof input.since_days === 'number')
+        flags.push(`--since=${input.since_days}d`);
+    if (typeof input.max_cost_usd === 'number')
+        flags.push(`--max-cost=${input.max_cost_usd}`);
+    if (input.dry_run)
+        flags.push('--dry-run');
+    if (input.resume_run_id)
+        flags.push(`--resume=${input.resume_run_id}`);
+    if (input.provider)
+        flags.push(`--provider=${input.provider}`);
+    return flags;
+}
+function runSubprocess(spawnFn, cwd, args, timeoutMs) {
+    return new Promise((resolveP, rejectP) => {
+        const [bin, ...rest] = args;
+        const child = spawnFn(bin, rest, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            fn();
+        };
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* ignore */
+            }
+            settle(() => rejectP(new Error(`classify-edges timed out after ${timeoutMs}ms`)));
+        }, timeoutMs);
+        child.stdout?.on('data', (d) => {
+            stdout += d.toString();
+        });
+        child.stderr?.on('data', (d) => {
+            stderr += d.toString();
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            settle(() => rejectP(err));
+        });
+        child.on('exit', (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                return settle(() => rejectP(new Error(`classify-edges exited ${code}: ${stderr.slice(-500)}`)));
+            }
+            settle(() => resolveP(stdout));
+        });
+    });
+}
+function parseSummary(stdout) {
+    // The CLI prints the JSON summary as its final stdout output. Walk back
+    // from the last '}' matching braces to find the start. Same pattern as
+    // compile.ts — robust against earlier JSON-shaped output.
+    const trimmed = stdout.trimEnd();
+    const lastBrace = trimmed.lastIndexOf('}');
+    if (lastBrace === -1) {
+        throw new Error(`classify-edges produced no parseable summary; output was:\n${stdout.slice(-500)}`);
+    }
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escapeNext = false;
+    for (let i = lastBrace; i >= 0; i--) {
+        const c = trimmed[i];
+        if (escapeNext) {
+            escapeNext = false;
+            continue;
+        }
+        if (c === '\\' && inString) {
+            escapeNext = true;
+            continue;
+        }
+        if (c === '"' && !escapeNext) {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (c === '}')
+            depth++;
+        else if (c === '{') {
+            depth--;
+            if (depth === 0) {
+                start = i;
+                break;
+            }
+        }
+    }
+    if (start === -1) {
+        throw new Error(`classify-edges produced no parseable summary; output was:\n${stdout.slice(-500)}`);
+    }
+    const json = trimmed.slice(start, lastBrace + 1);
+    return JSON.parse(json);
+}

package/dist/tools/compile.d.ts

@@ -0,0 +1,31 @@
+/**
+ * MCP tool handler for `compile()`.
+ *
+ * Per the SPEC-044 constraint that the MCP server itself makes no LLM calls,
+ * this handler spawns the standalone `compile-wiki` driver as a subprocess
+ * and returns the JSON summary it prints to stdout. The actual provider
+ * calls happen in that subprocess, not in the server process.
+ */
+import { spawn } from 'node:child_process';
+import type { CompileSummary } from '../compiler/types.js';
+export interface CompileToolInput {
+    tier?: 'preferences' | 'project-context' | 'conversations';
+    all?: boolean;
+    topic?: string;
+    dry_run?: boolean;
+    /** Override the cost cap for this invocation. */
+    max_cost_usd?: number;
+    /** Force a specific provider for this run. */
+    provider?: 'claude-code' | 'anthropic' | 'openrouter';
+}
+export interface CompileToolDeps {
+    /** Override the spawn function (tests inject a mock). */
+    spawnFn?: typeof spawn;
+    /** Working directory for the subprocess. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Maximum subprocess runtime. Default 30 minutes. */
+    runTimeoutMs?: number;
+}
+export declare function compile(input: CompileToolInput, deps?: CompileToolDeps): Promise<CompileSummary>;
+/** Resolved path to the compile-wiki CLI script — used in production wiring. */
+export declare function compileCliPath(projectRoot: string): string;

package/dist/tools/compile.js

@@ -0,0 +1,132 @@
+/**
+ * MCP tool handler for `compile()`.
+ *
+ * Per the SPEC-044 constraint that the MCP server itself makes no LLM calls,
+ * this handler spawns the standalone `compile-wiki` driver as a subprocess
+ * and returns the JSON summary it prints to stdout. The actual provider
+ * calls happen in that subprocess, not in the server process.
+ */
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { resolveCliCommand } from './spawn-cli.js';
+export async function compile(input, deps = {}) {
+    validateInput(input);
+    const { bin, args: cliArgs } = resolveCliCommand('compile-wiki');
+    const flags = buildArgs(input);
+    const cwd = deps.cwd ?? process.cwd();
+    const spawnFn = deps.spawnFn ?? spawn;
+    const timeoutMs = deps.runTimeoutMs ?? 30 * 60_000;
+    const stdout = await runSubprocess(spawnFn, cwd, [bin, ...cliArgs, ...flags], timeoutMs);
+    return parseSummary(stdout);
+}
+function validateInput(input) {
+    const modes = [input.tier, input.all, input.topic].filter(Boolean).length;
+    if (modes !== 1) {
+        throw new Error('compile() requires exactly one of: tier, all, topic');
+    }
+}
+function buildArgs(input) {
+    const flags = [];
+    if (input.tier)
+        flags.push(`--tier=${input.tier}`);
+    if (input.all)
+        flags.push('--all');
+    if (input.topic)
+        flags.push(`--topic=${input.topic}`);
+    if (input.dry_run)
+        flags.push('--dry-run');
+    if (typeof input.max_cost_usd === 'number')
+        flags.push(`--max-cost=${input.max_cost_usd}`);
+    if (input.provider)
+        flags.push(`--provider=${input.provider}`);
+    return flags;
+}
+function runSubprocess(spawnFn, cwd, args, timeoutMs) {
+    return new Promise((resolveP, rejectP) => {
+        const [bin, ...rest] = args;
+        const child = spawnFn(bin, rest, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* ignore */
+            }
+        }, timeoutMs);
+        child.stdout?.on('data', (d) => {
+            stdout += d.toString();
+        });
+        child.stderr?.on('data', (d) => {
+            stderr += d.toString();
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            rejectP(err);
+        });
+        child.on('exit', (code) => {
+            clearTimeout(timer);
+            if (timedOut)
+                return rejectP(new Error(`compile-wiki timed out after ${timeoutMs}ms`));
+            if (code !== 0) {
+                return rejectP(new Error(`compile-wiki exited ${code}: ${stderr.slice(-500)}`));
+            }
+            resolveP(stdout);
+        });
+    });
+}
+function parseSummary(stdout) {
+    // The CLI prints the JSON summary as its final stdout output. Walk the
+    // string from the end backwards looking for a trailing `}`, then match
+    // braces to find the start of the JSON block. This is robust against the
+    // subprocess emitting earlier JSON-shaped output (dry-run previews,
+    // intermediate logging) — only the FINAL balanced object is parsed.
+    const trimmed = stdout.trimEnd();
+    const lastBrace = trimmed.lastIndexOf('}');
+    if (lastBrace === -1) {
+        throw new Error(`compile-wiki produced no parseable summary; output was:\n${stdout.slice(-500)}`);
+    }
+    // Walk back, balancing braces (ignoring those inside strings).
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escapeNext = false;
+    for (let i = lastBrace; i >= 0; i--) {
+        const c = trimmed[i];
+        if (escapeNext) {
+            escapeNext = false;
+            continue;
+        }
+        if (c === '\\' && inString) {
+            escapeNext = true;
+            continue;
+        }
+        if (c === '"' && !escapeNext) {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (c === '}')
+            depth++;
+        else if (c === '{') {
+            depth--;
+            if (depth === 0) {
+                start = i;
+                break;
+            }
+        }
+    }
+    if (start === -1) {
+        throw new Error(`compile-wiki produced no parseable summary; output was:\n${stdout.slice(-500)}`);
+    }
+    const json = trimmed.slice(start, lastBrace + 1);
+    return JSON.parse(json);
+}
+/** Resolved path to the compile-wiki CLI script — used in production wiring. */
+export function compileCliPath(projectRoot) {
+    return resolve(projectRoot, 'scripts/compile-wiki.ts');
+}

package/dist/tools/dump-edges-sidecar.d.ts

@@ -0,0 +1,37 @@
+/**
+ * SPEC-045: in-process sidecar JSON exporter for memory_edges + memories.
+ *
+ * Exposed in two ways:
+ *   1. As an MCP tool (handler in this same file — see dumpEdgesSidecarTool).
+ *   2. As a CLI script (scripts/dump-edges-json.ts) — thin wrapper over dumpEdgesJson().
+ *
+ * Both paths run in-process against pgvector — no subprocess, no LLM call.
+ * Output: <out_dir>/edges.json and <out_dir>/memories.json. The caller
+ * supplies out_dir; the MCP server makes no assumption about a fixed path.
+ */
+import pg from 'pg';
+export interface DumpEdgesInput {
+    /** Absolute path to the directory where edges.json + memories.json land. Required. */
+    out_dir: string;
+}
+export interface DumpEdgesOutput {
+    memories_count: number;
+    edges_count: number;
+    out_dir: string;
+}
+/**
+ * Pure function — takes a connected pg.Client and an out dir, writes the
+ * two JSON files, returns counts. Connection lifecycle is the caller's job
+ * so tests can inject a test client.
+ */
+export declare function dumpEdgesJsonWithClient(client: pg.Client, outDir: string): Promise<DumpEdgesOutput>;
+/**
+ * Convenience wrapper that opens its own connection from R2MCP_DATABASE_URL.
+ * Used by the CLI script and the MCP tool handler.
+ */
+export declare function dumpEdgesJson(outDir: string): Promise<DumpEdgesOutput>;
+/**
+ * MCP tool wrapper. The server calls this with the validated input.
+ * Returns the structured output as a JSON-serialized text content block.
+ */
+export declare function dumpEdgesSidecarTool(input: DumpEdgesInput): Promise<DumpEdgesOutput>;

package/dist/tools/dump-edges-sidecar.js

@@ -0,0 +1,80 @@
+/**
+ * SPEC-045: in-process sidecar JSON exporter for memory_edges + memories.
+ *
+ * Exposed in two ways:
+ *   1. As an MCP tool (handler in this same file — see dumpEdgesSidecarTool).
+ *   2. As a CLI script (scripts/dump-edges-json.ts) — thin wrapper over dumpEdgesJson().
+ *
+ * Both paths run in-process against pgvector — no subprocess, no LLM call.
+ * Output: <out_dir>/edges.json and <out_dir>/memories.json. The caller
+ * supplies out_dir; the MCP server makes no assumption about a fixed path.
+ */
+import pg from 'pg';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Pure function — takes a connected pg.Client and an out dir, writes the
+ * two JSON files, returns counts. Connection lifecycle is the caller's job
+ * so tests can inject a test client.
+ */
+export async function dumpEdgesJsonWithClient(client, outDir) {
+    const edges = await client.query(`
+    SELECT id, from_memory_id, to_memory_id, relation, confidence, rationale,
+           classifier_version, valid_from, valid_until, created_at, updated_at
+    FROM memory_edges
+    WHERE valid_until IS NULL
+    ORDER BY created_at DESC
+  `);
+    const memories = await client.query(`
+    SELECT id, content, tier, type, section, topics, people, date, fingerprint,
+           source_file, source_line, created_at, updated_at
+    FROM memories
+    WHERE type != 'archived'
+    ORDER BY created_at DESC
+  `);
+    await mkdir(outDir, { recursive: true });
+    const generatedAt = new Date().toISOString();
+    await writeFile(join(outDir, 'edges.json'), JSON.stringify({
+        generated_at: generatedAt,
+        memory_count: memories.rows.length,
+        edge_count: edges.rows.length,
+        edges: edges.rows,
+    }, null, 2), 'utf-8');
+    await writeFile(join(outDir, 'memories.json'), JSON.stringify({
+        generated_at: generatedAt,
+        memory_count: memories.rows.length,
+        memories: memories.rows,
+    }, null, 2), 'utf-8');
+    return {
+        memories_count: memories.rows.length,
+        edges_count: edges.rows.length,
+        out_dir: outDir,
+    };
+}
+/**
+ * Convenience wrapper that opens its own connection from R2MCP_DATABASE_URL.
+ * Used by the CLI script and the MCP tool handler.
+ */
+export async function dumpEdgesJson(outDir) {
+    const url = process.env.R2MCP_DATABASE_URL;
+    if (!url)
+        throw new Error('R2MCP_DATABASE_URL not set');
+    const client = new pg.Client({ connectionString: url });
+    await client.connect();
+    try {
+        return await dumpEdgesJsonWithClient(client, outDir);
+    }
+    finally {
+        await client.end();
+    }
+}
+/**
+ * MCP tool wrapper. The server calls this with the validated input.
+ * Returns the structured output as a JSON-serialized text content block.
+ */
+export async function dumpEdgesSidecarTool(input) {
+    if (!input.out_dir) {
+        throw new Error('dump_edges_sidecar requires out_dir');
+    }
+    return dumpEdgesJson(input.out_dir);
+}

package/dist/tools/extract-entities.d.ts

@@ -0,0 +1,53 @@
+/**
+ * MCP tool handler for `extract_entities()` — SPEC-046 Task 8.
+ *
+ * Per the SPEC-044/045 invariant that the MCP server itself makes no LLM
+ * calls, this handler spawns the standalone extract-entities driver as a
+ * subprocess. The actual provider calls happen in that subprocess.
+ *
+ * The subprocess command is resolved via resolveCliCommand so the tool
+ * works for both dev (tsx + .ts) and prod (node + dist/.js) consumers.
+ *
+ * Pattern mirrors src/tools/classify.ts intentionally — same dependency
+ * injection seams (spawnFn, cwd, runTimeoutMs), same settled-flag timeout
+ * shape, same JSON parse strategy.
+ */
+import { spawn } from 'node:child_process';
+import type { RunSummary } from '../entities/types.js';
+/**
+ * Build a W3C `traceparent` string from the currently active span.
+ * Returns undefined when there's no active span (OTel SDK not initialized
+ * or this call is outside withToolSpan). Exported for testability.
+ *
+ * Format: `00-<trace_id:32hex>-<span_id:16hex>-<flags:2hex>` (version 00,
+ * sampled flag taken from the span's traceFlags). See
+ * https://www.w3.org/TR/trace-context/#traceparent-header.
+ *
+ * Subprocess receivers should set this on a `propagation.extract()` carrier
+ * keyed by `traceparent` (lowercase) to rebuild the context — see
+ * scripts/extract-entities.ts startup.
+ */
+export declare function currentTraceparent(): string | undefined;
+export interface ExtractEntitiesInput {
+    /** Filter candidate memories to those updated in the last N days. */
+    since_days?: number;
+    /** Per-run cost cap in USD. Default: $1.00 (R2MCP_ENTITY_MAX_USD env). */
+    max_cost_usd?: number;
+    /** Force a specific provider for this run. */
+    provider?: 'claude-code' | 'anthropic' | 'openrouter';
+    /** Resume a prior run_id; memories already terminal in that run are skipped. */
+    resume?: string;
+    /** Backfill mode — process all memories regardless of recency. */
+    full?: boolean;
+    /** Top-N existing entities to include in extraction context. */
+    context_top_n?: number;
+}
+export interface ExtractEntitiesToolDeps {
+    /** Override the spawn function (tests inject a mock). */
+    spawnFn?: typeof spawn;
+    /** Working directory for the subprocess. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Maximum subprocess runtime. Default 30 minutes. */
+    runTimeoutMs?: number;
+}
+export declare function extractEntitiesTool(input: ExtractEntitiesInput, deps?: ExtractEntitiesToolDeps): Promise<RunSummary>;

package/dist/tools/extract-entities.js

@@ -0,0 +1,169 @@
+/**
+ * MCP tool handler for `extract_entities()` — SPEC-046 Task 8.
+ *
+ * Per the SPEC-044/045 invariant that the MCP server itself makes no LLM
+ * calls, this handler spawns the standalone extract-entities driver as a
+ * subprocess. The actual provider calls happen in that subprocess.
+ *
+ * The subprocess command is resolved via resolveCliCommand so the tool
+ * works for both dev (tsx + .ts) and prod (node + dist/.js) consumers.
+ *
+ * Pattern mirrors src/tools/classify.ts intentionally — same dependency
+ * injection seams (spawnFn, cwd, runTimeoutMs), same settled-flag timeout
+ * shape, same JSON parse strategy.
+ */
+import { spawn } from 'node:child_process';
+import { trace } from '@opentelemetry/api';
+import { resolveCliCommand } from './spawn-cli.js';
+/**
+ * Build a W3C `traceparent` string from the currently active span.
+ * Returns undefined when there's no active span (OTel SDK not initialized
+ * or this call is outside withToolSpan). Exported for testability.
+ *
+ * Format: `00-<trace_id:32hex>-<span_id:16hex>-<flags:2hex>` (version 00,
+ * sampled flag taken from the span's traceFlags). See
+ * https://www.w3.org/TR/trace-context/#traceparent-header.
+ *
+ * Subprocess receivers should set this on a `propagation.extract()` carrier
+ * keyed by `traceparent` (lowercase) to rebuild the context — see
+ * scripts/extract-entities.ts startup.
+ */
+export function currentTraceparent() {
+    const span = trace.getActiveSpan();
+    if (!span)
+        return undefined;
+    const ctx = span.spanContext();
+    if (!ctx || !ctx.traceId || !ctx.spanId)
+        return undefined;
+    const flags = (ctx.traceFlags & 0xff).toString(16).padStart(2, '0');
+    return `00-${ctx.traceId}-${ctx.spanId}-${flags}`;
+}
+export async function extractEntitiesTool(input, deps = {}) {
+    validateInput(input);
+    const { bin, args: cliArgs } = resolveCliCommand('extract-entities');
+    const flags = buildArgs(input);
+    const cwd = deps.cwd ?? process.cwd();
+    const spawnFn = deps.spawnFn ?? spawn;
+    const timeoutMs = deps.runTimeoutMs ?? 30 * 60_000;
+    const traceparent = currentTraceparent();
+    const stdout = await runSubprocess(spawnFn, cwd, [bin, ...cliArgs, ...flags], timeoutMs, traceparent);
+    return parseSummary(stdout);
+}
+function validateInput(input) {
+    if (input.full && input.since_days !== undefined) {
+        throw new Error('extract_entities: --full and --since-days are mutually exclusive');
+    }
+}
+function buildArgs(input) {
+    const flags = [];
+    if (typeof input.since_days === 'number')
+        flags.push(`--since-days=${input.since_days}`);
+    if (typeof input.max_cost_usd === 'number')
+        flags.push(`--max-cost=${input.max_cost_usd}`);
+    if (input.provider)
+        flags.push(`--provider=${input.provider}`);
+    if (input.resume)
+        flags.push(`--resume=${input.resume}`);
+    if (input.full)
+        flags.push('--full');
+    if (typeof input.context_top_n === 'number')
+        flags.push(`--context-top-n=${input.context_top_n}`);
+    return flags;
+}
+function runSubprocess(spawnFn, cwd, args, timeoutMs, traceparent) {
+    return new Promise((resolveP, rejectP) => {
+        const [bin, ...rest] = args;
+        // claw-2jbo finding 6: propagate the parent OTel span context to the
+        // child via the standard W3C `traceparent` env var. The script entry
+        // point reads OTEL_TRACEPARENT at startup (see scripts/extract-entities.ts)
+        // and uses `propagation.extract()` to make the child's spans children of
+        // the parent. When traceparent is undefined (no active span / SDK off),
+        // we simply inherit process.env unchanged.
+        const childEnv = traceparent ? { ...process.env, OTEL_TRACEPARENT: traceparent } : process.env;
+        const child = spawnFn(bin, rest, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: childEnv,
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            fn();
+        };
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* ignore */
+            }
+            settle(() => rejectP(new Error(`extract-entities timed out after ${timeoutMs}ms`)));
+        }, timeoutMs);
+        child.stdout?.on('data', (d) => {
+            stdout += d.toString();
+        });
+        child.stderr?.on('data', (d) => {
+            stderr += d.toString();
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            settle(() => rejectP(err));
+        });
+        child.on('exit', (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                return settle(() => rejectP(new Error(`extract-entities exited ${code}: ${stderr.slice(-500)}`)));
+            }
+            settle(() => resolveP(stdout));
+        });
+    });
+}
+function parseSummary(stdout) {
+    // The CLI prints the JSON summary as its final stdout output. Walk back
+    // from the last '}' matching braces to find the start. Same pattern as
+    // classify.ts / compile.ts — robust against earlier JSON-shaped output.
+    const trimmed = stdout.trimEnd();
+    const lastBrace = trimmed.lastIndexOf('}');
+    if (lastBrace === -1) {
+        throw new Error(`extract-entities produced no parseable summary; output was:\n${stdout.slice(-500)}`);
+    }
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escapeNext = false;
+    for (let i = lastBrace; i >= 0; i--) {
+        const c = trimmed[i];
+        if (escapeNext) {
+            escapeNext = false;
+            continue;
+        }
+        if (c === '\\' && inString) {
+            escapeNext = true;
+            continue;
+        }
+        if (c === '"' && !escapeNext) {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (c === '}')
+            depth++;
+        else if (c === '{') {
+            depth--;
+            if (depth === 0) {
+                start = i;
+                break;
+            }
+        }
+    }
+    if (start === -1) {
+        throw new Error(`extract-entities produced no parseable summary; output was:\n${stdout.slice(-500)}`);
+    }
+    const json = trimmed.slice(start, lastBrace + 1);
+    return JSON.parse(json);
+}

package/dist/tools/lint.d.ts

@@ -0,0 +1,10 @@
+/**
+ * MCP tool handler for `lint()`.
+ *
+ * Lint is SQL-only — no LLM calls (C.R5) — so unlike `compile()` it runs
+ * directly in the MCP server process against the existing pgvector pool.
+ * No subprocess delegation needed.
+ */
+import type { LintInput, LintResult } from '../lint/types.js';
+export type { LintInput, LintResult } from '../lint/types.js';
+export declare function lint(input: LintInput): Promise<LintResult>;