src/prompts.ts

Functions

Imports

It imports src/agents.ts, src/resources.ts, src/scope.ts. Imported by src/server.ts.

Source

1import { McpServer, ProtocolError, ProtocolErrorCode } from "@modelcontextprotocol/server";
2import type { Agent } from "./agents";
3import { checkScope } from "./scope";
4import { namespaceFilter, resourceRefusal } from "./resources";
5
6export function registerPrompts(server: McpServer, agent: Agent, db: D1Database): void {
7  // Prompts: reusable templates stored as type 'prompt' documents whose bodies use
8  // {{variable}} placeholders. Handled at the protocol level, since McpServer only
9  // lists prompts registered at build time, so the D1 query runs lazily on
10  // prompts/list and prompts/get.
11  //
12  // A prompt is named "<namespace>/<path without .md>", the way every other tool
13  // addresses a document. A bare path is not a document key: two namespaces can both
14  // hold prompts/brief.md.
15  const PLACEHOLDER = /\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g;
16  const promptVariables = (body: string) => [...new Set([...body.matchAll(PLACEHOLDER)].map((m) => m[1]))];
17  // A title reaches the client's model as a description, which it trusts like a tool
18  // description, and any write-grant session can write it, so it passes a character
19  // allowlist (no backticks, braces or control characters) and a length cap.
20  const PROMPT_TITLE_DISALLOWED = /[^A-Za-z0-9 ,.;:()'"!?_/-]+/g;
21  const promptSafeTitle = (title: string | null): string | undefined => {
22    if (!title) return undefined;
23    const safe = title.replace(PROMPT_TITLE_DISALLOWED, " ").replace(/\s+/g, " ").trim().slice(0, 200);
24    return safe || undefined;
25  };
26  server.server.registerCapabilities({ prompts: { listChanged: false } });
27  server.server.setRequestHandler("prompts/list", async () => {
28    // The whole scope check, as prompts/get makes it (Grok audit 2026-10-21, CA-5).
29    const listRefusal = checkScope(agent, { tool: "capsid_read_doc", action: "read", grant: "read" });
30    if (listRefusal) throw new ProtocolError(ProtocolErrorCode.InvalidParams, listRefusal);
31    const { results } = await db
32      .prepare("SELECT namespace, path, title, body FROM documents WHERE type = 'prompt' ORDER BY namespace, path")
33      .all<{ namespace: string; path: string; title: string | null; body: string | null }>();
34    return {
35      prompts: namespaceFilter(agent, results).map((row) => ({
36        name: `${row.namespace}/${row.path.replace(/\.md$/, "")}`,
37        description: promptSafeTitle(row.title),
38        arguments: promptVariables(row.body ?? "").map((name) => ({ name, required: true })),
39      })),
40    };
41  });
42  server.server.setRequestHandler("prompts/get", async (request) => {
43    const { name } = request.params;
44    const args = request.params.arguments ?? {};
45    // Split on the FIRST slash only: the namespace never contains one and the
46    // path frequently does.
47    const slash = name.indexOf("/");
48    if (slash <= 0 || slash === name.length - 1) {
49      throw new ProtocolError(
50        ProtocolErrorCode.InvalidParams,
51        `prompt name must be "<namespace>/<path>", got "${name}". Call prompts/list for the available names.`
52      );
53    }
54    const promptNs = name.slice(0, slash);
55    const promptPath = name.slice(slash + 1);
56    const refusal = resourceRefusal(agent, promptNs);
57    if (refusal) throw new ProtocolError(ProtocolErrorCode.InvalidParams, refusal);
58    const row = await db
59      .prepare(
60        "SELECT title, body FROM documents WHERE type = 'prompt' AND namespace = ?1 AND (path = ?2 OR path = ?2 || '.md')"
61      )
62      .bind(promptNs, promptPath)
63      .first<{ title: string | null; body: string | null }>();
64    if (!row) throw new ProtocolError(ProtocolErrorCode.InvalidParams, `prompt not found: ${name}`);
65    const missing = new Set<string>();
66    const text = (row.body ?? "").replace(PLACEHOLDER, (placeholder, variable: string) => {
67      const value = args[variable];
68      if (value === undefined) {
69        missing.add(variable);
70        return placeholder;
71      }
72      return String(value);
73    });
74    if (missing.size > 0) {
75      throw new ProtocolError(ProtocolErrorCode.InvalidParams, `missing arguments for prompt ${name}: ${[...missing].join(", ")}`);
76    }
77    return {
78      description: promptSafeTitle(row.title),
79      // The body is data, not the user's own words. Any write-grant session can write
80      // it, and returning it as plain user text would hand whoever last wrote the row
81      // a message the client's model reads as its human speaking. An embedded
82      // resource is the protocol's shape for content from a store.
83      messages: [
84        {
85          role: "user" as const,
86          content: {
87            type: "resource" as const,
88            resource: { uri: `capsid://${promptNs}/${promptPath}`, mimeType: "text/markdown", text },
89          },
90        },
91      ],
92    };
93  });
94}