ctxr-cli 0.30.0 → 0.31.0

package/dist/core/mcp/tools/find.js

@@ -0,0 +1,136 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { joinBaseUrl, noteRoute } from '../../browse/page-url.js';
+import { catalogSectionsFor, sectionForNote } from '../../catalog/model.js';
+import { isUnderAnyPrefix } from '../../fs/prefix.js';
+import { listCaptures, listNotes } from '../../notes/list.js';
+import { readCatalogGlosses } from '../../records.js';
+import { ToolRefusal } from '../jsonrpc.js';
+/**
+ * remote-access spec, *`find` stands in for a client's own content
+ * matching*; context-retrieval's bounded exception. Literal,
+ * case-insensitive substring matching over the notes the store's
+ * enumeration admits, in path order, with no score. Captures — inbox files
+ * on the default branch and on pending `capture/` branches — come back in
+ * `unfiled`, never among the notes (context-ingest's exception, design.md
+ * D6). With no text, the catalog as a map to pick selectors from.
+ */
+export const MAX_LINES_PER_HIT = 3;
+export const MAX_LINE_CHARS = 240;
+export const DEFAULT_MAX_MATCHES = 25;
+export const DEFAULT_MAX_MAP_NOTES = 500;
+export const MAX_RESULTS = 1000;
+const MAX_TEXT_CHARS = 200;
+/**
+ * Plain on purpose: type, description and required only. Some clients (Gemini) accept a narrow subset of JSON
+ * Schema and drop a tool whose schema uses more; every limit is enforced by `parseFindArgs` instead.
+ */
+export const FIND_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        text: { type: 'string', description: 'Literal text to look for, case-insensitive. Omit it to get the map of the store instead.' },
+        under: { type: 'string', description: 'Only look under this folder of the store, e.g. "projects/".' },
+        max: { type: 'integer', description: `How many notes to return (default ${DEFAULT_MAX_MATCHES} when matching, ${DEFAULT_MAX_MAP_NOTES} for the map).` },
+    },
+};
+export function parseFindArgs(args) {
+    const out = {};
+    if (args.text !== undefined && args.text !== null) {
+        if (typeof args.text !== 'string')
+            throw new ToolRefusal('mcp.invalid_arguments', '"text" must be a string.');
+        if (args.text.length > MAX_TEXT_CHARS)
+            throw new ToolRefusal('mcp.invalid_arguments', `"text" is at most ${MAX_TEXT_CHARS} characters.`);
+        if (args.text.trim().length > 0)
+            out.text = args.text.trim();
+    }
+    if (args.under !== undefined && args.under !== null) {
+        if (typeof args.under !== 'string')
+            throw new ToolRefusal('mcp.invalid_arguments', '"under" must be a string.');
+        const under = args.under.trim().replace(/^\.?\/+/, '');
+        if (under.length > 0)
+            out.under = under;
+    }
+    if (args.max !== undefined && args.max !== null) {
+        if (typeof args.max !== 'number' || !Number.isInteger(args.max) || args.max < 1 || args.max > MAX_RESULTS) {
+            throw new ToolRefusal('mcp.invalid_arguments', `"max" must be a whole number from 1 to ${MAX_RESULTS}.`);
+        }
+        out.max = args.max;
+    }
+    return out;
+}
+function matchLines(text, needle) {
+    const lines = [];
+    let count = 0;
+    const all = text.split(/\r?\n/);
+    for (let i = 0; i < all.length; i += 1) {
+        const line = all[i];
+        if (!line.toLowerCase().includes(needle))
+            continue;
+        count += 1;
+        if (lines.length < MAX_LINES_PER_HIT) {
+            lines.push({ line: i + 1, text: line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS - 1)}…` : line });
+        }
+    }
+    return { lines, count };
+}
+const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+/** `baseUrl` is `serve.base_url` from the configuration `serve` loaded: links point at the browsing surface it answers. */
+export async function find(snapshot, args, baseUrl) {
+    const store = snapshot.store;
+    const linkFor = (notePath) => joinBaseUrl(baseUrl, noteRoute(notePath));
+    const glosses = await readCatalogGlosses(store);
+    const scope = (p) => args.under === undefined || isUnderAnyPrefix(p, [args.under]);
+    const notes = (await listNotes(store.root, store.config)).filter((n) => scope(n.path)).sort(byPath);
+    if (args.text === undefined) {
+        const max = args.max ?? DEFAULT_MAX_MAP_NOTES;
+        const sections = catalogSectionsFor(store.config);
+        const grouped = new Map(sections.map((s) => [s.id, []]));
+        let listed = 0;
+        for (const note of notes) {
+            if (listed >= max)
+                break;
+            grouped.get(sectionForNote(sections, note.path).id).push({ path: note.path, gloss: glosses.get(note.path) ?? '', url: linkFor(note.path) });
+            listed += 1;
+        }
+        return {
+            mode: 'map',
+            sections: [...grouped.entries()].filter(([, entries]) => entries.length > 0).map(([id, entries]) => ({ id, notes: entries })),
+            notes_omitted: notes.length - listed,
+        };
+    }
+    const needle = args.text.toLowerCase();
+    const max = args.max ?? DEFAULT_MAX_MATCHES;
+    // Raw file text, frontmatter included, so line numbers are the file's own — what grep would report.
+    const noteHits = [];
+    for (const note of notes) {
+        const { lines, count } = matchLines(await readFile(path.join(store.root, note.path), 'utf8'), needle);
+        if (count > 0)
+            noteHits.push({ path: note.path, gloss: glosses.get(note.path) ?? '', lines, matching_lines: count, url: linkFor(note.path) });
+    }
+    const inbox = store.config.ingest.inbox_path;
+    const unfiled = [];
+    for (const capture of (await listCaptures(store.root, store.config)).sort(byPath)) {
+        if (!isUnderAnyPrefix(capture.path, [inbox]) || !scope(capture.path))
+            continue;
+        const { lines, count } = matchLines(await readFile(path.join(store.root, capture.path), 'utf8'), needle);
+        if (count > 0)
+            unfiled.push({ path: capture.path, lines, matching_lines: count, pending_merge: false, branch: null });
+    }
+    const pending = [...snapshot.pending].sort((a, b) => byPath(a, b) || (a.branch < b.branch ? -1 : 1));
+    for (const capture of pending) {
+        if (!scope(capture.path))
+            continue;
+        const { lines, count } = matchLines(capture.text, needle);
+        if (count > 0)
+            unfiled.push({ path: capture.path, lines, matching_lines: count, pending_merge: true, branch: capture.branch });
+    }
+    return {
+        mode: 'match',
+        text: args.text,
+        notes: noteHits.slice(0, max),
+        notes_omitted: Math.max(0, noteHits.length - max),
+        unfiled: unfiled.slice(0, max),
+        unfiled_omitted: Math.max(0, unfiled.length - max),
+    };
+}
+//# sourceMappingURL=find.js.map

package/dist/core/mcp/tools/find.js.map

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

package/dist/core/mcp/tools/gather.d.ts

@@ -0,0 +1,88 @@
+import { type GatherOutcome, type GatherResult } from '../../retrieval/pass.js';
+import type { Snapshot } from '../sync.js';
+/**
+ * remote-access spec, *`gather` returns the retrieval pass with the bodies a
+ * client cannot read itself* (design.md D8). The pass runs unchanged against
+ * the view's notes and the view's own graph, and still returns no body; this
+ * attaches them afterwards, to a prefix of the pass's order, within a byte
+ * budget — so the cap never reorders anything, exactly as the pass's own cap.
+ */
+export declare const DEFAULT_GATHER_MAX_BYTES = 60000;
+export interface GatherArgs {
+    seeds?: string[];
+    sections?: string[];
+    under?: string[];
+    entities?: string[];
+    hops?: number;
+    direction?: 'in' | 'out' | 'both';
+    type?: string;
+    max_notes?: number;
+}
+export interface GatheredNote extends GatherResult {
+    /** The note's text, frontmatter included; null once the byte budget is spent. */
+    body: string | null;
+    /** Set on the first note only, when it alone exceeded the budget and was cut to it. */
+    body_clipped?: true;
+}
+export interface GatherToolResult extends Omit<GatherOutcome, 'notes'> {
+    notes: GatheredNote[];
+    bodies: {
+        max_bytes: number;
+        returned: number;
+        omitted: number;
+    };
+}
+/** Plain on purpose (see FIND_INPUT_SCHEMA): `parseGatherArgs` enforces every limit. */
+export declare const GATHER_INPUT_SCHEMA: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly seeds: {
+            readonly type: 'array';
+            readonly items: {
+                readonly type: 'string';
+            };
+            readonly description: 'Note paths to start from, usually from find.';
+        };
+        readonly sections: {
+            readonly type: 'array';
+            readonly items: {
+                readonly type: 'string';
+            };
+            readonly description: 'Catalog section ids whose notes to start from (find with no text lists them).';
+        };
+        readonly under: {
+            readonly type: 'array';
+            readonly items: {
+                readonly type: 'string';
+            };
+            readonly description: 'Folders whose notes to start from, e.g. "projects/".';
+        };
+        readonly entities: {
+            readonly type: 'array';
+            readonly items: {
+                readonly type: 'string';
+            };
+            readonly description: 'Note paths whose backlinks to start from: every note linking to them.';
+        };
+        readonly hops: {
+            readonly type: 'integer';
+            readonly description: 'How many links to follow out from the starting notes (default 1; 0 returns only them).';
+        };
+        readonly direction: {
+            readonly type: 'string';
+            readonly enum: readonly ['in', 'out', 'both'];
+            readonly description: 'Follow links pointing out, in, or both (default both).';
+        };
+        readonly type: {
+            readonly type: 'string';
+            readonly description: 'Follow only links of this relation type.';
+        };
+        readonly max_notes: {
+            readonly type: 'integer';
+            readonly description: 'Cap on how many notes to return; the omitted count is reported.';
+        };
+    };
+};
+export declare function parseGatherArgs(args: Record<string, unknown>): GatherArgs;
+export declare function gatherWithBodies(snapshot: Snapshot, args: GatherArgs, maxBytes?: number): Promise<GatherToolResult>;
+//# sourceMappingURL=gather.d.ts.map

package/dist/core/mcp/tools/gather.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gather.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/tools/gather.ts"],"names":[],"mappings":"AAKA,OAAO,EAAqB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEnG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;GAMG;AAEH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,iFAAiF;IACjF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,uFAAuF;IACvF,YAAY,CAAC,EAAE,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC;IACpE,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAClE;AAED,wFAAwF;AACxF,eAAO,MAAM,mBAAmB;aAC9B,IAAI,EAAE,QAAQ;aACd,UAAU;iBACR,KAAK;qBAAI,IAAI,EAAE,OAAO;qBAAE,KAAK;yBAAI,IAAI,EAAE,QAAQ;;qBAAI,WAAW,EAAE,8CAA8C;;iBAC9G,QAAQ;qBAAI,IAAI,EAAE,OAAO;qBAAE,KAAK;yBAAI,IAAI,EAAE,QAAQ;;qBAAI,WAAW,EAAE,+EAA+E;;iBAClJ,KAAK;qBAAI,IAAI,EAAE,OAAO;qBAAE,KAAK;yBAAI,IAAI,EAAE,QAAQ;;qBAAI,WAAW,EAAE,sDAAsD;;iBACtH,QAAQ;qBAAI,IAAI,EAAE,OAAO;qBAAE,KAAK;yBAAI,IAAI,EAAE,QAAQ;;qBAAI,WAAW,EAAE,uEAAuE;;iBAC1I,IAAI;qBAAI,IAAI,EAAE,SAAS;qBAAE,WAAW,EAAE,wFAAwF;;iBAC9H,SAAS;qBAAI,IAAI,EAAE,QAAQ;qBAAE,IAAI,YAAG,IAAI,EAAE,KAAK,EAAE,MAAM;qBAAG,WAAW,EAAE,wDAAwD;;iBAC/H,IAAI;qBAAI,IAAI,EAAE,QAAQ;qBAAE,WAAW,EAAE,0CAA0C;;iBAC/E,SAAS;qBAAI,IAAI,EAAE,SAAS;qBAAE,WAAW,EAAE,iEAAiE;;;CAEtG,CAAC;AAqBX,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAuBzE;AAED,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,SAA2B,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiD3I"}

package/dist/core/mcp/tools/gather.js

@@ -0,0 +1,123 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isUnderAnyPrefix } from '../../fs/prefix.js';
+import { readAdmittedGraph } from '../../graph/persist.js';
+import { listNotes } from '../../notes/list.js';
+import { gather as runPass } from '../../retrieval/pass.js';
+import { ToolRefusal } from '../jsonrpc.js';
+/**
+ * remote-access spec, *`gather` returns the retrieval pass with the bodies a
+ * client cannot read itself* (design.md D8). The pass runs unchanged against
+ * the view's notes and the view's own graph, and still returns no body; this
+ * attaches them afterwards, to a prefix of the pass's order, within a byte
+ * budget — so the cap never reorders anything, exactly as the pass's own cap.
+ */
+export const DEFAULT_GATHER_MAX_BYTES = 60_000;
+/** Plain on purpose (see FIND_INPUT_SCHEMA): `parseGatherArgs` enforces every limit. */
+export const GATHER_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        seeds: { type: 'array', items: { type: 'string' }, description: 'Note paths to start from, usually from find.' },
+        sections: { type: 'array', items: { type: 'string' }, description: 'Catalog section ids whose notes to start from (find with no text lists them).' },
+        under: { type: 'array', items: { type: 'string' }, description: 'Folders whose notes to start from, e.g. "projects/".' },
+        entities: { type: 'array', items: { type: 'string' }, description: 'Note paths whose backlinks to start from: every note linking to them.' },
+        hops: { type: 'integer', description: 'How many links to follow out from the starting notes (default 1; 0 returns only them).' },
+        direction: { type: 'string', enum: ['in', 'out', 'both'], description: 'Follow links pointing out, in, or both (default both).' },
+        type: { type: 'string', description: 'Follow only links of this relation type.' },
+        max_notes: { type: 'integer', description: 'Cap on how many notes to return; the omitted count is reported.' },
+    },
+};
+function stringList(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    const list = typeof value === 'string' ? [value] : value;
+    if (!Array.isArray(list) || !list.every((v) => typeof v === 'string' && v.trim().length > 0)) {
+        throw new ToolRefusal('mcp.invalid_arguments', `"${key}" must be a list of non-empty strings.`);
+    }
+    return list.map((v) => v.trim().replace(/^\.?\/+/, ''));
+}
+function wholeNumber(args, key, min, max) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max) {
+        throw new ToolRefusal('mcp.invalid_arguments', `"${key}" must be a whole number from ${min} to ${max}.`);
+    }
+    return value;
+}
+export function parseGatherArgs(args) {
+    const out = {
+        seeds: stringList(args, 'seeds'),
+        sections: stringList(args, 'sections'),
+        under: stringList(args, 'under'),
+        entities: stringList(args, 'entities'),
+        hops: wholeNumber(args, 'hops', 0, 5),
+        max_notes: wholeNumber(args, 'max_notes', 1, 500),
+    };
+    if (args.direction !== undefined && args.direction !== null) {
+        if (args.direction !== 'in' && args.direction !== 'out' && args.direction !== 'both') {
+            throw new ToolRefusal('mcp.invalid_arguments', '"direction" is one of in, out, both.');
+        }
+        out.direction = args.direction;
+    }
+    if (args.type !== undefined && args.type !== null) {
+        if (typeof args.type !== 'string')
+            throw new ToolRefusal('mcp.invalid_arguments', '"type" must be a string.');
+        out.type = args.type;
+    }
+    if ([out.seeds, out.sections, out.under, out.entities].every((l) => l === undefined || l.length === 0)) {
+        throw new ToolRefusal('mcp.invalid_arguments', 'Name at least one starting point: seeds, sections, under or entities. Use find first to get note paths.');
+    }
+    return out;
+}
+export async function gatherWithBodies(snapshot, args, maxBytes = DEFAULT_GATHER_MAX_BYTES) {
+    const store = snapshot.store;
+    const captureRoot = store.config.ingest.capture_root;
+    for (const seed of args.seeds ?? []) {
+        if (isUnderAnyPrefix(seed, [captureRoot])) {
+            throw new ToolRefusal('mcp.capture_not_filed', `"${seed}" is a capture that has not been filed into a note yet, so it cannot start a gather; read it with Read instead.`, { path: seed });
+        }
+    }
+    const notes = await listNotes(store.root, store.config);
+    const graph = await readAdmittedGraph(store);
+    const pass = await runPass(store, notes, graph, {
+        seeds: args.seeds,
+        sections: args.sections,
+        under: args.under,
+        entities: args.entities,
+        hops: args.hops,
+        direction: args.direction,
+        type: args.type,
+        maxNotes: args.max_notes,
+    });
+    let spent = 0;
+    let open = true;
+    let returned = 0;
+    const withBodies = [];
+    for (const [index, note] of pass.notes.entries()) {
+        if (!open) {
+            withBodies.push({ ...note, body: null });
+            continue;
+        }
+        const text = await readFile(path.join(store.root, note.path), 'utf8');
+        const bytes = Buffer.byteLength(text, 'utf8');
+        if (spent + bytes <= maxBytes) {
+            spent += bytes;
+            returned += 1;
+            withBodies.push({ ...note, body: text });
+        }
+        else if (index === 0) {
+            // A call never comes back with no text at all: the first note is cut to the budget and says so.
+            withBodies.push({ ...note, body: Buffer.from(text, 'utf8').subarray(0, maxBytes).toString('utf8'), body_clipped: true });
+            returned += 1;
+            open = false;
+        }
+        else {
+            withBodies.push({ ...note, body: null });
+            open = false;
+        }
+    }
+    return { ...pass, notes: withBodies, bodies: { max_bytes: maxBytes, returned, omitted: pass.notes.length - returned } };
+}
+//# sourceMappingURL=gather.js.map

package/dist/core/mcp/tools/gather.js.map

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

package/dist/core/mcp/tools/index.d.ts

@@ -0,0 +1,21 @@
+import type { ToolDefinition } from '../jsonrpc.js';
+import type { Principal } from '../oauth.js';
+import type { Mutex, WriteDeps } from '../sessions.js';
+import type { McpView, SyncDeps } from '../sync.js';
+/**
+ * The remote surface's tool set and the prose that describes it
+ * (templates/mcp/, shipped-prose-lives-in-templates). Built per request from
+ * the server's current state. Reads go through `view.read`, so each sees one
+ * commit and names it; writes go through the one mutex (design.md D9, D13).
+ */
+export declare function serverInstructions(storeName: string): string;
+export interface ToolContext {
+    view: McpView;
+    syncDeps: SyncDeps;
+    write: WriteDeps;
+    mutex: Mutex;
+    /** `serve.base_url` from the loaded configuration. */
+    baseUrl: string | undefined;
+}
+export declare function buildTools(ctx: ToolContext): ToolDefinition<Principal>[];
+//# sourceMappingURL=index.d.ts.map

package/dist/core/mcp/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAoBpD;;;;;GAKG;AAEH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAWD,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,cAAc,CAAC,SAAS,CAAC,EAAE,CAuGxE"}

package/dist/core/mcp/tools/index.js

@@ -0,0 +1,129 @@
+import { packagedTemplate } from '../../templates.js';
+import { asToolRefusal, capture, CAPTURE_INPUT_SCHEMA, parseCaptureArgs } from './capture.js';
+import { EDIT_INPUT_SCHEMA, editTool, parseEditArgs, parseWriteArgs, WRITE_INPUT_SCHEMA, writeTool } from './edit.js';
+import { GLOB_INPUT_SCHEMA, globTool, GREP_INPUT_SCHEMA, grepTool, parseGlobArgs, parseGrepArgs, parseReadArgs, READ_INPUT_SCHEMA, readTool, renderGlob, renderGrep, renderRead, } from './files.js';
+import { find, FIND_INPUT_SCHEMA, parseFindArgs } from './find.js';
+import { GATHER_INPUT_SCHEMA, gatherWithBodies, parseGatherArgs } from './gather.js';
+/**
+ * The remote surface's tool set and the prose that describes it
+ * (templates/mcp/, shipped-prose-lives-in-templates). Built per request from
+ * the server's current state. Reads go through `view.read`, so each sees one
+ * commit and names it; writes go through the one mutex (design.md D9, D13).
+ */
+export function serverInstructions(storeName) {
+    return packagedTemplate('mcp', 'server-instructions').replaceAll('__STORE_NAME__', storeName);
+}
+/** Writes surface a WriteRefusal as a refusal the client model can read. */
+async function writing(ctx, fn) {
+    try {
+        return await ctx.mutex.run(fn);
+    }
+    catch (err) {
+        throw asToolRefusal(err);
+    }
+}
+export function buildTools(ctx) {
+    const read = (fn) => ctx.view.read(ctx.syncDeps, fn);
+    return [
+        {
+            name: 'find',
+            title: 'Find in the store',
+            description: packagedTemplate('mcp', 'find'),
+            inputSchema: FIND_INPUT_SCHEMA,
+            scope: 'read',
+            readOnly: true,
+            run: (args) => {
+                const parsed = parseFindArgs(args);
+                return read((snapshot) => find(snapshot, parsed, ctx.baseUrl));
+            },
+        },
+        {
+            name: 'gather',
+            title: 'Gather related notes',
+            description: packagedTemplate('mcp', 'gather'),
+            inputSchema: GATHER_INPUT_SCHEMA,
+            scope: 'read',
+            readOnly: true,
+            run: (args) => {
+                const parsed = parseGatherArgs(args);
+                return read((snapshot) => gatherWithBodies(snapshot, parsed));
+            },
+        },
+        {
+            name: 'Read',
+            title: 'Read a file',
+            description: packagedTemplate('mcp', 'Read'),
+            inputSchema: READ_INPUT_SCHEMA,
+            scope: 'read',
+            readOnly: true,
+            render: renderRead,
+            run: (args, principal) => {
+                const parsed = parseReadArgs(args);
+                return read((snapshot) => readTool(snapshot, ctx.write, principal.email, parsed));
+            },
+        },
+        {
+            name: 'Grep',
+            title: 'Search file contents',
+            description: packagedTemplate('mcp', 'Grep'),
+            inputSchema: GREP_INPUT_SCHEMA,
+            scope: 'read',
+            readOnly: true,
+            render: renderGrep,
+            run: (args) => {
+                const parsed = parseGrepArgs(args);
+                return read((snapshot) => grepTool(snapshot, parsed));
+            },
+        },
+        {
+            name: 'Glob',
+            title: 'Find files by name',
+            description: packagedTemplate('mcp', 'Glob'),
+            inputSchema: GLOB_INPUT_SCHEMA,
+            scope: 'read',
+            readOnly: true,
+            render: renderGlob,
+            run: (args) => {
+                const parsed = parseGlobArgs(args);
+                return read((snapshot) => globTool(snapshot, parsed));
+            },
+        },
+        {
+            name: 'capture',
+            title: 'Capture into the store',
+            description: packagedTemplate('mcp', 'capture'),
+            inputSchema: CAPTURE_INPUT_SCHEMA,
+            scope: 'capture',
+            readOnly: false,
+            run: (args, principal) => {
+                const parsed = parseCaptureArgs(args);
+                return writing(ctx, () => capture({ view: ctx.view, syncDeps: ctx.syncDeps, write: ctx.write }, principal.email, parsed));
+            },
+        },
+        {
+            name: 'Edit',
+            title: 'Edit a note',
+            description: packagedTemplate('mcp', 'Edit'),
+            inputSchema: EDIT_INPUT_SCHEMA,
+            scope: 'edit',
+            readOnly: false,
+            run: (args, principal) => {
+                const parsed = parseEditArgs(args);
+                return writing(ctx, () => editTool({ view: ctx.view, syncDeps: ctx.syncDeps, write: ctx.write }, principal.email, parsed));
+            },
+        },
+        {
+            name: 'Write',
+            title: 'Create a note',
+            description: packagedTemplate('mcp', 'Write'),
+            inputSchema: WRITE_INPUT_SCHEMA,
+            scope: 'edit',
+            readOnly: false,
+            run: (args, principal) => {
+                const parsed = parseWriteArgs(args);
+                return writing(ctx, () => writeTool({ view: ctx.view, syncDeps: ctx.syncDeps, write: ctx.write }, principal.email, parsed));
+            },
+        },
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/core/mcp/tools/index.js.map

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

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** Kept in sync with package.json's "version" field. */
-export declare const CLI_VERSION = "0.30.0";
+export declare const CLI_VERSION = "0.31.0";
 /**
  * The npm package this executable is published as. Bound here, beside the
  * version, because the release check resolves the latest published release by

package/dist/version.js

@@ -1,5 +1,5 @@
 /** Kept in sync with package.json's "version" field. */
-export const CLI_VERSION = '0.30.0';
+export const CLI_VERSION = '0.31.0';
 /**
  * The npm package this executable is published as. Bound here, beside the
  * version, because the release check resolves the latest published release by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctxr-cli",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Context store for AI coding agents — markdown and git, catalog and graph retrieval, no vector database.",
   "type": "module",
   "license": "MIT",

package/templates/mcp/Edit.md

@@ -0,0 +1,7 @@
+Makes an exact string replacement in a note, like a local Edit tool.
+
+- Read the note first, and copy `old_string` exactly as it appears, including indentation and line breaks. Do not include the line-number prefix that `Read` shows.
+- The edit fails if `old_string` is not unique in the note. Give more surrounding text to make it unique, or set `replace_all` to change every occurrence.
+- Only notes can be edited: never configuration, the entry document, captures or tool-owned files.
+
+Edits do not change the store directly. Each one is saved to your draft, a pull request that collects all of your edits and lands only once someone approves it on the store's approval page. Tell the person that, and give them the approval link the result returns. If someone asked for changes on your draft, more edits go into the same draft.

package/templates/mcp/Glob.md

@@ -0,0 +1,5 @@
+Finds files in the store by name pattern, like a local Glob tool.
+
+- Supports glob patterns like `**/*.md` or `projects/**/*.md`.
+- Returns matching file paths relative to the store root, in path order.
+- Use `path` to search one folder only.

package/templates/mcp/Grep.md

@@ -0,0 +1,10 @@
+A search tool over the store's files, built on ripgrep, with the same parameters as a local Grep tool.
+
+- Supports full regular-expression syntax (e.g. `kestrel.*launch`, `^## Decisions`).
+- Filter files with `glob` (e.g. `projects/**/*.md`) or `type` (e.g. `md`).
+- `output_mode`: `content` shows matching lines (with `-n` line numbers, `-A`/`-B`/`-C` context); `files_with_matches` shows only file paths (the default); `count` shows match counts.
+- `multiline: true` lets a pattern span lines.
+- Results are in path order. Use `head_limit` and `offset` to page through many results.
+- Matching captures still awaiting approval are listed after the results. They are not in the store yet.
+
+For a plain question about what the store knows, `find` (with glosses and links) is usually the better start. Use Grep for an exact pattern.

package/templates/mcp/Read.md

@@ -0,0 +1,7 @@
+Reads a file from the store. Works like a local Read tool: `file_path` is relative to the store root (a leading `/` means the store root), and the result is numbered like `cat -n`, starting at 1.
+
+- By default it reads up to 2000 lines from the start; use `offset` and `limit` for longer files.
+- It reads notes, the entry document (`AGENTS.md`), and captures under the inbox. A capture is raw material not yet filed into a note: never present it as what the store says.
+- If you have a pending draft that changed this note (from `Edit` or `Write`), you get your draft's version, marked as such. Other people still see the version in the store until your draft is approved.
+- Configuration, derived files and tool-owned folders cannot be read.
+- A note's result names its page on the store's site. When you cite the note to the person, include that link.

package/templates/mcp/Write.md

@@ -0,0 +1,7 @@
+Creates a new note, like a local Write tool, except that it never overwrites. Use `Edit` to change a note that already exists.
+
+- `file_path` is relative to the store root and must end in `.md`, e.g. `projects/kestrel-launch.md`. Put it where similar notes live: use `Glob` or `find` to see the store's folders first.
+- Follow the store's conventions for notes (frontmatter, headings, links). `Read` `AGENTS.md` if you have not.
+- Captures of outside material go through `capture`, not `Write`.
+
+Like edits, a new note goes into your draft and lands only once someone approves it. Tell the person, and give them the approval link the result returns.

package/templates/mcp/capture.md

@@ -0,0 +1,9 @@
+Save one item of outside material — a meeting transcript or notes, an email, a document, a web page — into the store's inbox, where it waits to be reviewed and filed into notes. It never changes an existing note.
+
+Rules:
+- Pass the material in its own words. Copy it through; do not condense, reorder, correct or summarise it. If the source supplies its own summary, keep it in a separate section marked as the source's summary, beside the record rather than instead of it.
+- One item per call. Two meetings are two captures.
+- `source_type` names where the material came from, lowercased (for example `email`, `meeting`, `web`, `document`). Use the same word the store already uses for that source.
+- `source_id` is the source system's own identifier for the item when you have one (a message id, a meeting id, a URL). Leave it out when there is none.
+
+The store refuses material it already holds, and tells you where; tell the person rather than retrying.