src/tools/docs-read.ts

Functions

Imports

It imports src/conventions-read.ts, src/doc-index.ts, src/doc-reads.ts, src/limits.ts, src/portfolio-docs.ts, src/scope.ts, src/tools/docs.ts, src/tools/surface.ts. Imported by src/tools/docs.ts.

Source

1import { McpServer } from "@modelcontextprotocol/server";
2import { z } from "zod";
3import { bounded, BRIEF_BUDGET, HISTORY_ROWS, MAX_DOC_STATUS, MAX_DOC_TYPE, MAX_GLOB, MAX_QUERY, MAX_ROWS, nsName, SEARCH_ROWS, docPath } from "../limits";
4import { ok, fail, type ToolCtx } from "./docs";
5import { surfaceOf } from "./surface";
6import { isConventionsDoc, recordConventionsRead } from "../conventions-read";
7import { describePortfolioDocs, isPortfolioPath, PORTFOLIO_DOCS, portfolioDocuments } from "../portfolio-docs";
8import { portfolioOnly } from "../scope";
9import { documentEdges, readDocument, searchDocuments } from "../doc-reads";
10import { hybridSearch } from "../doc-index";
11
12// The document tools that only read: list, read, brief, history, backlinks, find
13// and search. defineDocOperations in ./docs registers them in the published order.
14
15// Ask for one extra row so "exactly limit" is distinguishable from "there are more".
16function boundedRows<T>(rows: T[], limit: number, advice: string) {
17  const truncated = rows.length > limit;
18  const kept = truncated ? rows.slice(0, limit) : rows;
19  return {
20    count: kept.length,
21    limit,
22    truncated,
23    ...(truncated ? { note: `Returned the first ${limit} rows; there are more. ${advice}` } : {}),
24    documents: kept,
25  };
26}
27
28export function defineListOperation(server: McpServer, ctx: ToolCtx): void {
29  const { db, agent } = ctx;
30
31  ctx.ops.define(
32    "list",
33    {
34      description: `List documents with optional namespace, type, and status filters. Returns metadata rows without bodies under \`documents\`: id, namespace, path, title, type, status, tags and timestamps. Bounded to ${MAX_ROWS} rows; when there are more it sets truncated:true with a note.`,
35      inputSchema: {
36        namespace: nsName.optional(),
37        type: bounded(MAX_DOC_TYPE).optional(),
38        status: bounded(MAX_DOC_STATUS).optional(),
39      },
40    },
41    async ({ namespace, type, status }) => {
42      // A caller outside capsid sees the portfolio documents there and nothing else
43      // (src/portfolio-docs.ts). The set is small, so it is read whole and filtered here.
44      if (portfolioOnly(agent, namespace)) {
45        const rows = (await portfolioDocuments(db)).filter((r) => (type == null || r.type === type) && (status == null || r.status === status));
46        return ok(boundedRows(rows, MAX_ROWS, "Narrow with type or status."));
47      }
48      const { results } = await db
49        .prepare(
50          // frontmatter and publish_at are not selected: nothing in this server reads
51          // or writes them. They stay in the table, because dropping a column means a
52          // migration, a rebuild of the FTS triggers and a change to the backup table
53          // guard, to reclaim nothing.
54          `SELECT id, namespace, path, title, type, status, tags, created_at, updated_at
55           FROM documents
56           WHERE (?1 IS NULL OR namespace = ?1) AND (?2 IS NULL OR type = ?2) AND (?3 IS NULL OR status = ?3)
57           ORDER BY namespace, path
58           LIMIT ?4`
59        )
60        .bind(namespace ?? null, type ?? null, status ?? null, MAX_ROWS + 1)
61        .all();
62      return ok(
63        boundedRows(
64          results,
65          MAX_ROWS,
66          namespace
67            ? "Narrow with type or status, or use capsid_find_docs action glob with a path glob."
68            : "Narrow with namespace (the usual case), type or status, or use capsid_find_docs action glob with a path glob."
69        )
70      );
71    }
72  );
73}
74
75export function defineReadOperation(server: McpServer, ctx: ToolCtx): void {
76  const { db, actor, lastActor } = ctx;
77
78  ctx.ops.define(
79    "read",
80    {
81      description:
82        "Read a full document by namespace and path. The response carries last_actor, the actor of the most recent audit_log entry for this document, or null when there is none.",
83      inputSchema: { namespace: nsName, path: docPath },
84    },
85    async ({ namespace, path }) => {
86      const row = await readDocument(db, namespace, path);
87      if (!row) return fail(`not found: ${namespace}/${path}`);
88      // Read first: the row recorded below is not addressed to this document, so it
89      // cannot change last_actor, but the order keeps that from depending on it.
90      const lastWriter = await lastActor(namespace, path);
91      if (isConventionsDoc(namespace, path)) await recordConventionsRead(db, actor, "read", namespace);
92      return ok({ ...row, last_actor: lastWriter });
93    }
94  );
95}
96
97export function defineBriefOperation(server: McpServer, ctx: ToolCtx): void {
98  const { db, actor } = ctx;
99
100  // One-call session start: assembles the read ritual so a session cannot skip a
101  // piece of it. Pure assembly, no reasoning. Size-bounded so it stays loadable;
102  // when trimmed it says so.
103  ctx.ops.define(
104    "brief",
105    {
106      description:
107        `One-call session start for a namespace. Returns capsid/conventions.md, the namespace core.md, \`portfolio_documents\` (the capsid paths every driver reads first and may read: conventions, decisions and its volumes, rulings, core), its open task docs (non-archived and not status closed), the 3 most recent episodics, and the typed edges on core.md, each with updated_at so staleness shows. Read-only. Size-bounded near ${Math.round(BRIEF_BUDGET / 1000)}KB; if trimmed, the \`trimmed\` field lists what was dropped to metadata. When conventions and core.md alone exceed the budget nothing is trimmed and \`floor_exceeds_budget\` carries their sizes.`,
108      inputSchema: { namespace: nsName },
109    },
110    async ({ namespace }) => {
111      const doc = (ns: string, path: string) =>
112        db
113          .prepare("SELECT namespace, path, title, type, body, updated_at FROM documents WHERE namespace = ?1 AND path = ?2")
114          .bind(ns, path)
115          .first<{ namespace: string; path: string; title: string | null; type: string | null; body: string | null; updated_at: string }>();
116      const [conventions, core, portfolio] = await Promise.all([
117        doc("capsid", "conventions.md"),
118        doc(namespace, "core.md"),
119        portfolioDocuments(db),
120      ]);
121      // Not filtered on status (beyond 'closed' below): status records editorial
122      // state and does not mark a task done, so filtering on 'published' would hide
123      // most open task docs. archive/ is the only other exclusion.
124      //
125      // The four remaining reads run together: none depends on another's result.
126      const [openTasksResult, recentEpisodicsResult, coreOutResult, coreInResult] = await Promise.all([
127        db
128          .prepare(
129            // The closure predicate below is the only status filter in this query.
130            // It excludes exactly one value, set deliberately to mean finished.
131            // status is NOT NULL, so the comparison cannot swallow a row via NULL.
132            //
133            // test/doc-meta.test.ts asserts this predicate appears exactly once in
134            // this file, so the lint loop can never grow one. Only the archive/
135            // prefix takes a document out of memory.
136            "SELECT namespace, path, title, type, body, updated_at FROM documents WHERE namespace = ?1 AND type = 'task' AND status != 'closed' AND path NOT LIKE 'archive/%' ORDER BY updated_at DESC"
137          )
138          .bind(namespace)
139          .all<{ namespace: string; path: string; title: string | null; type: string | null; body: string | null; updated_at: string }>(),
140        db
141          .prepare(
142            "SELECT namespace, path, title, type, body, updated_at FROM documents WHERE namespace = ?1 AND type = 'episodic' AND path NOT LIKE 'archive/%' ORDER BY created_at DESC LIMIT 3"
143          )
144          .bind(namespace)
145          .all<{ namespace: string; path: string; title: string | null; type: string | null; body: string | null; updated_at: string }>(),
146        db
147          .prepare("SELECT type, to_ns, to_path FROM document_links WHERE from_ns = ?1 AND from_path = 'core.md' ORDER BY type, to_ns, to_path")
148          .bind(namespace)
149          .all(),
150        db
151          .prepare("SELECT type, from_ns, from_path FROM document_links WHERE to_ns = ?1 AND to_path = 'core.md' ORDER BY type, from_ns, from_path")
152          .bind(namespace)
153          .all(),
154      ]);
155      if (conventions) await recordConventionsRead(db, actor, "brief", namespace);
156      const openTasks = openTasksResult.results;
157      const recentEpisodics = recentEpisodicsResult.results;
158      const coreOut = coreOutResult.results;
159      const coreIn = coreInResult.results;
160
161      // Provenance on every document in the packet: a poisoned task or core.md is
162      // instructions at turn 0, and last_actor is how a session tells the operator's
163      // own writing from another client's. Attached after the reads so each documents
164      // SELECT stays a plain projection.
165      //
166      // One query for all of them. The pairs travel as one JSON parameter because D1
167      // caps a statement at 100 bound parameters and the open-task list has no cap.
168      // The correlated subquery is the lastActor query per pair, so it uses
169      // audit_log_doc.
170      type Keyed = { namespace: string; path: string };
171      type Actored<T> = T & { last_actor: string | null };
172      const present = [conventions, core, ...openTasks, ...recentEpisodics].filter((r): r is NonNullable<typeof r> => r !== null);
173      const actors = new Map<string, string | null>();
174      if (present.length) {
175        // A plain SELECT rather than a CTE, and no comment inside prepare(), so
176        // test-integration/query-plans.test.ts, which walks SELECT statements written
177        // directly as prepare()'s argument, checks this plan too.
178        const { results } = await db
179          .prepare(
180            `SELECT json_extract(w.value, '$[0]') AS ns, json_extract(w.value, '$[1]') AS path,
181               (SELECT actor FROM audit_log
182                WHERE namespace = json_extract(w.value, '$[0]') AND path = json_extract(w.value, '$[1]')
183                ORDER BY id DESC LIMIT 1) AS actor
184             FROM json_each(?1) AS w`
185          )
186          .bind(JSON.stringify(present.map((r) => [r.namespace, r.path])))
187          .all<{ ns: string; path: string; actor: string | null }>();
188        for (const row of results) actors.set(JSON.stringify([row.ns, row.path]), row.actor ?? null);
189      }
190      const withActor = <T extends Keyed>(row: T | null): Actored<T> | null =>
191        row ? { ...row, last_actor: actors.get(JSON.stringify([row.namespace, row.path])) ?? null } : null;
192      const withActors = <T extends Keyed>(rows: T[]): Actored<T>[] => rows.map((r) => withActor(r) as Actored<T>);
193      const conventionsA = withActor(conventions);
194      const coreA = withActor(core);
195      const openTasksA = withActors(openTasks);
196      const recentEpisodicsA = withActors(recentEpisodics);
197
198      // Stay under budget by trimming the largest, most re-readable sections to
199      // metadata first (episodics, then task bodies), and report what was cut.
200      //
201      // Only a cut that happened is reported. Nothing is cut when the two documents
202      // that are never trimmed exceed the budget by themselves, since trimming the
203      // rest cannot bring the packet under it; that is reported as
204      // floor_exceeds_budget with the sizes.
205      type Row = { namespace: string; path: string; title: string | null; body: string | null; updated_at: string; last_actor?: string | null };
206      const bodyChars = (rows: Row[]) => rows.reduce((sum, r) => sum + (r.body?.length ?? 0), 0);
207      const toStub = (rows: Row[]) =>
208        rows.map((r) => ({ namespace: r.namespace, path: r.path, title: r.title, updated_at: r.updated_at, last_actor: r.last_actor ?? null, body: `(trimmed for size: read it with capsid_read_doc, ${r.namespace}/${r.path})` }));
209      const sizes = {
210        conventions: conventionsA?.body?.length ?? 0,
211        core: coreA?.body?.length ?? 0,
212      };
213      const floorChars = sizes.conventions + sizes.core;
214      const floorOver = floorChars > BRIEF_BUDGET;
215      const trimmed: string[] = [];
216      let total = floorChars + bodyChars(openTasksA as Row[]) + bodyChars(recentEpisodicsA as Row[]);
217      let episodicsOut: unknown[] = recentEpisodicsA;
218      let tasksOut: unknown[] = openTasksA;
219      if (!floorOver && total > BRIEF_BUDGET && bodyChars(recentEpisodicsA as Row[]) > 0) {
220        total -= bodyChars(recentEpisodicsA as Row[]);
221        episodicsOut = toStub(recentEpisodicsA as Row[]);
222        trimmed.push(`${recentEpisodicsA.length} episodic bodies`);
223      }
224      if (!floorOver && total > BRIEF_BUDGET && bodyChars(openTasksA as Row[]) > 0) {
225        total -= bodyChars(openTasksA as Row[]);
226        tasksOut = toStub(openTasksA as Row[]);
227        trimmed.push(`${openTasksA.length} task bodies`);
228      }
229
230      return ok({
231        namespace,
232        conventions: conventionsA,
233        core: coreA,
234        open_tasks: tasksOut,
235        recent_episodics: episodicsOut,
236        core_links: { outgoing: coreOut, incoming: coreIn },
237        // The portfolio rules, by path, for every namespace: a session reads these first.
238        // Every namespace driver may read them in capsid and nothing else there.
239        portfolio_documents: {
240          namespace: PORTFOLIO_DOCS.namespace,
241          read_first: portfolio.map((r) => r.path),
242          allowlist: describePortfolioDocs(),
243          note: `Read each with capsid_read_doc(namespace: "${PORTFOLIO_DOCS.namespace}", path). Any namespace driver may read these, and nothing else in ${PORTFOLIO_DOCS.namespace}.`,
244        },
245        approx_chars: total,
246        ...(coreA ? {} : { warning: `no core.md for namespace ${namespace}` }),
247        ...(trimmed.length ? { trimmed } : {}),
248        ...(floorOver ? { floor_exceeds_budget: { ...sizes, floor: floorChars, budget: BRIEF_BUDGET } } : {}),
249      });
250    }
251  );
252}
253
254export function defineHistoryOperation(server: McpServer, ctx: ToolCtx): void {
255  const { db } = ctx;
256
257  ctx.ops.define(
258    "history",
259    {
260      description:
261        "List the retained versions of a document (newest first) from document_versions, or fetch one body by passing version_id. Every overwrite and delete writes a snapshot, so a deleted document's history is readable. Retention is 90 days. Read-only. A version records title and body only; changes to type, status or tags are in the audit log.",
262      inputSchema: { namespace: nsName, path: docPath, version_id: z.number().int().positive().optional() },
263    },
264    async ({ namespace, path, version_id }) => {
265      if (version_id !== undefined) {
266        const row = await db
267          .prepare(
268            "SELECT id, document_id, namespace, path, title, body, snapshot_at FROM document_versions WHERE id = ?1 AND namespace = ?2 AND path = ?3"
269          )
270          .bind(version_id, namespace, path)
271          .first<{ id: number; body: string | null }>();
272        // namespace and path are part of the lookup on purpose: an id alone would let
273        // a caller walk every snapshot in the store by incrementing a number.
274        if (!row) return fail(`no version ${version_id} for ${namespace}/${path}`);
275        return ok({ ...row, bytes: new TextEncoder().encode(row.body ?? "").length });
276      }
277      const { results } = await db
278        .prepare(
279          // Bounded: retention is 90 days, so HISTORY_ROWS covers more than a
280          // snapshot a day.
281          `SELECT id, snapshot_at, title, LENGTH(body) AS bytes
282           FROM document_versions
283           WHERE namespace = ?1 AND path = ?2
284           ORDER BY snapshot_at DESC, id DESC
285           LIMIT ?3`
286        )
287        .bind(namespace, path, HISTORY_ROWS)
288        .all();
289      const live = await db
290        .prepare("SELECT title, updated_at, LENGTH(body) AS bytes FROM documents WHERE namespace = ?1 AND path = ?2")
291        .bind(namespace, path)
292        .first();
293      return ok({
294        namespace,
295        path,
296        live: live ?? null,
297        versions: results,
298        ...(live ? {} : { note: "no live document at this path: these are the snapshots of a deleted or moved document" }),
299      });
300    }
301  );
302}
303
304export function defineBacklinksOperation(server: McpServer, ctx: ToolCtx): void {
305  const { db } = ctx;
306
307  ctx.ops.define(
308    "backlinks",
309    {
310      description:
311        "Return the typed edges touching a document: outgoing (declared on this doc) and incoming (other docs pointing here). Edges are set by capsid_write_doc's links param. Endpoints may be Capsid documents or repo files addressed as namespace/path. Read-only.",
312      inputSchema: { namespace: nsName, path: docPath },
313    },
314    async ({ namespace, path }) => {
315      const { outgoing, incoming } = await documentEdges(db, namespace, path);
316      // An incoming edge names a document in another namespace, so it is kept only when
317      // the caller may read that document, asked through checkScope (Grok audit 2026-10, A2).
318      const readable = incoming.filter((e) => ctx.scope({ ...surfaceOf("backlinks"), grant: "read", namespace: e.from_ns, path: e.from_path }) === null);
319      return ok({ namespace, path, outgoing, incoming: readable });
320    }
321  );
322}
323
324export function defineFindOperation(server: McpServer, ctx: ToolCtx): void {
325  const { db, agent } = ctx;
326
327  ctx.ops.define(
328    "find",
329    {
330      description: `Find documents whose path matches a glob pattern (SQLite GLOB, e.g. 'notes/*.md'). Optional namespace filter. Returns matches under \`documents\`, bounded to ${MAX_ROWS} rows; when there are more it sets truncated:true with a note.`,
331      inputSchema: { namespace: nsName.optional(), glob: bounded(MAX_GLOB) },
332    },
333    async ({ namespace, glob }) => {
334      const { results } = await db
335        .prepare(
336          `SELECT namespace, path, title, type, status, updated_at
337           FROM documents
338           WHERE path GLOB ?1 AND (?2 IS NULL OR namespace = ?2)
339           ORDER BY namespace, path
340           LIMIT ?3`
341        )
342        .bind(glob, namespace ?? null, MAX_ROWS + 1)
343        .all<{ path: string }>();
344      // A caller outside capsid keeps only the portfolio documents (src/portfolio-docs.ts).
345      const kept = portfolioOnly(agent, namespace) ? results.filter((r) => isPortfolioPath(r.path)) : results;
346      return ok(boundedRows(kept, MAX_ROWS, "Tighten the glob, or add a namespace filter."));
347    }
348  );
349}
350
351export function defineSearchOperation(server: McpServer, ctx: ToolCtx): void {
352  const { db, agent } = ctx;
353
354  ctx.ops.define(
355    "search",
356    {
357      description: `Full text search across all documents (FTS5, ranked by bm25). Optional namespace and type filters. This is the cross-project search. Returns the top ${SEARCH_ROWS} matches under \`documents\`; when more matched it sets truncated:true. mode defaults to "hybrid", which matches by meaning as well as by keyword, for a question phrased in other words than the document uses; mode "keyword" is the plain FTS5 search; each row says how it matched (\`match\`: keyword, meaning or both), closed and superseded documents are left out unless include_retired is true, and current canon ranks first. When the meaning index cannot answer, it falls back to the keyword search and says why under \`fallback\`.`,
358      inputSchema: {
359        query: bounded(MAX_QUERY),
360        namespace: nsName.optional(),
361        type: bounded(MAX_DOC_TYPE).optional(),
362        mode: z.enum(["keyword", "hybrid"]).optional(),
363        include_retired: z.boolean().optional(),
364      },
365    },
366    async ({ query, namespace, type, mode, include_retired }) => {
367      // A caller outside capsid searches the portfolio documents there and nothing else
368      // (src/portfolio-docs.ts): the query is narrowed to the paths that exist, so the
369      // page is not spent on rows that would be dropped, and every row is checked again
370      // below, so the narrowing is never what keeps another document out.
371      const restricted = portfolioOnly(agent, namespace);
372      const allowed = restricted ? JSON.stringify((await portfolioDocuments(db)).map((r) => r.path)) : null;
373      const bound = (rows: Array<{ path: string }>) =>
374        boundedRows(
375          restricted ? rows.filter((r) => isPortfolioPath(r.path)) : rows,
376          SEARCH_ROWS,
377          "Add a namespace or type filter, or make the query more specific."
378        );
379      const filter = { namespace: namespace ?? null, type: type ?? null, allowed };
380      let fallback: string | undefined;
381      if (mode !== "keyword") {
382        const hybrid = await hybridSearch(ctx.env, query, { ...filter, includeRetired: include_retired === true });
383        if (typeof hybrid !== "string") return ok({ mode: "hybrid", ...bound(hybrid) });
384        fallback = hybrid;
385      }
386      try {
387        const rows = bound(await searchDocuments(db, query, filter));
388        return ok(fallback === undefined ? rows : { mode: "keyword", fallback, ...rows });
389      } catch (err) {
390        return fail(`search failed (check FTS5 query syntax): ${err instanceof Error ? err.message : String(err)}`);
391      }
392    }
393  );
394}