src/resources.ts

Functions

Imports

It imports src/agents.ts, src/encoding.ts, src/limits.ts, src/scope.ts. Imported by src/prompts.ts, src/server.ts.

Source

1import { McpServer, ProtocolError, ProtocolErrorCode, ResourceTemplate } from "@modelcontextprotocol/server";
2import type { Agent } from "./agents";
3import { checkScope } from "./scope";
4import { b64urlDecode, b64urlEncode } from "./encoding";
5import { MAX_ROWS } from "./limits";
6
7// Scopes for resources and prompts. guardRegistrations wraps registerTool only, and
8// a raw request handler is not a registration, so these handlers check scope here.
9// Without it, an agent bearer on /ops/mcp could read every document by URI and list
10// every prompt while capsid_read_doc refused it.
11// They are checked as capsid_read_doc action read, so an agent narrowed away from it loses
12// both and the two surfaces cannot disagree.
13export function resourceRefusal(agent: Agent, namespace: string): string | null {
14  return checkScope(agent, { tool: "capsid_read_doc", action: "read", grant: "read", namespace });
15}
16
17// A listing filters rather than refusing, which would leak that there is more.
18export function namespaceFilter<T extends { namespace: string }>(agent: Agent, rows: T[]): T[] {
19  const visibleNamespaces = agent.scopes.namespaces;
20  return visibleNamespaces === "*" ? rows : rows.filter((row) => visibleNamespaces.includes(row.namespace));
21}
22
23// Stated once, used by the read registration and the list handler below. It spreads
24// onto every listed resource, so keep it to fields true of every document.
25const RESOURCE_METADATA = { title: "Capsid documents", mimeType: "text/markdown" };
26
27export function registerDocumentResources(server: McpServer, agent: Agent, db: D1Database): void {
28  const visibleNamespaces = agent.scopes.namespaces;
29
30  // Resources: every document is addressable context at capsid://<namespace>/<path>.
31  // Read-only, same visibility as capsid_read_doc.
32  server.registerResource(
33    "document",
34    new ResourceTemplate("capsid://{namespace}/{+path}", {
35      // Listing is served by the raw handler below: McpServer discards _meta and
36      // nextCursor from a list callback, so a callback cannot say it was truncated,
37      // and capping it here would make document 501 unreachable with nothing in the
38      // response admitting it.
39      list: undefined,
40    }),
41    RESOURCE_METADATA,
42    async (uri, variables) => {
43      const namespace = String(variables.namespace);
44      const path = String(variables.path);
45      const refusal = resourceRefusal(agent, namespace);
46      if (refusal) throw new ProtocolError(ProtocolErrorCode.InvalidParams, refusal);
47      const row = await db
48        .prepare("SELECT body FROM documents WHERE namespace = ?1 AND path = ?2")
49        .bind(namespace, path)
50        .first<{ body: string | null }>();
51      if (!row) throw new ProtocolError(ProtocolErrorCode.InvalidParams, `not found: ${uri.href}`);
52      return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: row.body ?? "" }] };
53    }
54  );
55
56  // resources/list, served directly because the request carries the cursor and the
57  // McpServer wrapper does not pass it through.
58  //
59  // Keyset pagination compared as a tuple: a concatenated key would skip rows ('-'
60  // sorts below '/').
61  //
62  // This overrides McpServer's handler, which is safe only while every resource is
63  // served by the one template above. test/bounded-reads.test.ts pins that.
64  server.server.setRequestHandler("resources/list", async (request) => {
65    // The grant, before the query.
66    // Every result is filtered to the caller's namespaces, so its cache hint is private
67    // (src/cache-hints.ts).
68    // The whole scope check, as resources/read makes it, so a caller narrowed away from
69    // capsid_read_doc (or a bench run key) lists nothing either (Grok audit 2026-10-21, CA-5).
70    const listRefusal = checkScope(agent, { tool: "capsid_read_doc", action: "read", grant: "read" });
71    if (listRefusal) throw new ProtocolError(ProtocolErrorCode.InvalidParams, listRefusal);
72    if (visibleNamespaces !== "*" && visibleNamespaces.length === 0) return { resources: [] };
73    const cursor = request.params?.cursor;
74    let afterNs = "";
75    let afterPath = "";
76    if (typeof cursor === "string" && cursor.length > 0) {
77      try {
78        const parsed = JSON.parse(b64urlDecode(cursor)) as { n?: unknown; p?: unknown };
79        afterNs = typeof parsed.n === "string" ? parsed.n : "";
80        afterPath = typeof parsed.p === "string" ? parsed.p : "";
81      } catch {
82        throw new ProtocolError(ProtocolErrorCode.InvalidParams, "invalid resources/list cursor; omit it to start from the beginning");
83      }
84    }
85    // Filtered in the query, so the LIMIT bounds what this caller can see rather than
86    // what the store holds. A filter after the LIMIT gives a caller scoped to a
87    // namespace that sorts late a page of rows it may not see, an empty page after
88    // filtering and no cursor, so its own documents are unreachable. The keyset
89    // cursor names the last row returned, which keeps the walk correct.
90    //
91    // One bound parameter rather than a spliced clause, so the statement text is fixed
92    // and test-integration/query-plans.test.ts can plan it. Null is the unscoped caller.
93    const visible = visibleNamespaces === "*" ? null : JSON.stringify(visibleNamespaces);
94    const { results } = await db
95      .prepare(
96        `SELECT namespace, path, title FROM documents
97         WHERE ((?1 = '' AND ?2 = '') OR (namespace > ?1 OR (namespace = ?1 AND path > ?2)))
98           AND (?4 IS NULL OR namespace IN (SELECT value FROM json_each(?4)))
99         ORDER BY namespace, path
100         LIMIT ?3`
101      )
102      .bind(afterNs, afterPath, MAX_ROWS + 1, visible)
103      .all<{ namespace: string; path: string; title: string | null }>();
104    // A no-op second pass that still holds if an edit loses the predicate.
105    const scoped = namespaceFilter(agent, results);
106    const more = scoped.length > MAX_ROWS;
107    const kept = more ? scoped.slice(0, MAX_ROWS) : scoped;
108    const last = kept[kept.length - 1];
109    return {
110      resources: kept.map((row) => ({
111        // Template metadata first, so a document's own title wins.
112        ...RESOURCE_METADATA,
113        uri: `capsid://${row.namespace}/${row.path}`,
114        name: `${row.namespace}/${row.path}`,
115        title: row.title ?? undefined,
116        mimeType: "text/markdown",
117      })),
118      ...(more && last ? { nextCursor: b64urlEncode(JSON.stringify({ n: last.namespace, p: last.path })) } : {}),
119    };
120  });
121}