src/tools/docs.ts

Functions

Imports

It imports src/agents.ts, src/env.ts, src/scope.ts, src/tools/docs-lifecycle.ts, src/tools/docs-read.ts, src/tools/docs-write.ts, src/tools/namespaces.ts, src/tools/operations.ts. Imported by src/namespace-delete.ts, src/server.ts, src/tools/admin.ts, src/tools/agents.ts, src/tools/claims.ts, src/tools/cloudflare.ts, src/tools/controls.ts, src/tools/docs-lifecycle.ts, src/tools/docs-read.ts, src/tools/docs-write.ts, src/tools/jobs.ts, src/tools/lint.ts, src/tools/namespaces.ts, src/tools/ops.ts, src/tools/repo-guards.ts, src/tools/repo.ts, src/tools/status.ts.

Source

1import { McpServer } from "@modelcontextprotocol/server";
2import type { Env } from "../env";
3import type { Agent } from "../agents";
4import { type ScopeNeed } from "../scope";
5import type { Operations } from "./operations";
6import { defineListOperation, defineReadOperation, defineBriefOperation, defineHistoryOperation, defineBacklinksOperation, defineFindOperation, defineSearchOperation } from "./docs-read";
7import { defineWriteOperation } from "./docs-write";
8import { defineDeleteOperation, defineMoveOperation, defineRestoreOperation } from "./docs-lifecycle";
9import { defineNamespaceOperations } from "./namespaces";
10
11export function ok(data: unknown) {
12  return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
13}
14
15export function fail(message: string) {
16  return { content: [{ type: "text" as const, text: message }], isError: true };
17}
18
19// PATH_MUTATION_HELPER_START
20// The only site that mutates documents.path or deletes a documents row.
21// document_links stores (ns, path) strings, no FK. newPath null means delete.
22// Statement order is positional: rename [0] documents [1] from_path [2] to_path;
23// delete [0] document_links [1] documents.
24export function pathMutation(
25  db: D1Database,
26  namespace: string,
27  path: string,
28  newPath: string | null
29): D1PreparedStatement[] {
30  if (newPath === null) {
31    return [
32      db
33        .prepare(
34          "DELETE FROM document_links WHERE (from_ns = ?1 AND from_path = ?2) OR (to_ns = ?1 AND to_path = ?2)"
35        )
36        .bind(namespace, path),
37      db.prepare("DELETE FROM documents WHERE namespace = ?1 AND path = ?2").bind(namespace, path),
38    ];
39  }
40  return [
41    db
42      .prepare("UPDATE documents SET path = ?3, updated_at = datetime('now') WHERE namespace = ?1 AND path = ?2")
43      .bind(namespace, path, newPath),
44    db
45      .prepare("UPDATE document_links SET from_path = ?3 WHERE from_ns = ?1 AND from_path = ?2")
46      .bind(namespace, path, newPath),
47    db
48      .prepare("UPDATE document_links SET to_path = ?3 WHERE to_ns = ?1 AND to_path = ?2")
49      .bind(namespace, path, newPath),
50  ];
51}
52
53// Edges touching a document, read before a mutation so the caller can record
54// them. document_versions snapshots only title and body, so for a delete this
55// is the only place the edges survive.
56export function edgesTouching(db: D1Database, namespace: string, path: string): D1PreparedStatement {
57  return db
58    .prepare(
59      "SELECT from_ns, from_path, type, to_ns, to_path FROM document_links WHERE (from_ns = ?1 AND from_path = ?2) OR (to_ns = ?1 AND to_path = ?2)"
60    )
61    .bind(namespace, path);
62}
63// PATH_MUTATION_HELPER_END
64
65type ConfirmVerdict = "accepted" | "declined" | "unsupported";
66
67// Asks the connected client to confirm a destructive action via MCP elicitation.
68// Stateless Streamable HTTP clients usually cannot answer server-initiated requests,
69// so "unsupported" is the common case and callers fall back to requiring an explicit
70// confirm:true argument.
71async function confirmDestructive(server: McpServer, message: string): Promise<ConfirmVerdict> {
72  if (!server.server.getClientCapabilities()?.elicitation) return "unsupported";
73  try {
74    const result = await server.server.elicitInput(
75      {
76        message,
77        requestedSchema: {
78          type: "object",
79          properties: {
80            confirm: { type: "boolean", title: "Confirm", description: "Set to true to proceed" },
81          },
82          required: ["confirm"],
83        },
84      },
85      { timeout: 90_000 }
86    );
87    return result.action === "accept" && result.content?.confirm === true ? "accepted" : "declined";
88  } catch {
89    return "unsupported";
90  }
91}
92
93// The confirmation step for every destructive tool. The messages stay per tool
94// because they are the instruction the caller acts on.
95//
96// It reports whether it actually elicited. An elicited answer can arrive 90 seconds
97// after the body it approved was read, so that consent goes stale like an if_match,
98// and write and restore arm the commit-time body guard on it.
99type ConfirmResult = { ok: true; elicited: boolean } | { ok: false; message: string };
100
101export async function requireConfirmation(
102  server: McpServer,
103  confirm: boolean | undefined,
104  messages: { prompt: string; declined: string; unsupported: string }
105): Promise<ConfirmResult> {
106  if (confirm === true) return { ok: true, elicited: false };
107  const verdict = await confirmDestructive(server, messages.prompt);
108  if (verdict === "accepted") return { ok: true, elicited: true };
109  return { ok: false, message: verdict === "declined" ? messages.declined : messages.unsupported };
110}
111
112// The grant, not a boolean. A boolean misread at every call site:
113// `buildServer(env, true, ...)` looks like "this is the operator server" when it
114// means "this grant may write", and a read-only ro: key is also an operator.
115// src/auth.ts resolves a key to exactly this union.
116export type ToolGrant = "write" | "read";
117
118export interface ToolCtx {
119  env: Env;
120  db: D1Database;
121  // The principal recorded on every audit_log row: "github:<login>" for an OAuth
122  // session, "opkey:<fingerprint>" for an operator key, "agent:<name>" for a minted
123  // agent (src/agents.ts). The fingerprint is a 12-char prefix of the key's sha256,
124  // because OPERATOR_KEY_HASH is the verifier and a full hash in audit_log would copy
125  // it into the database. Older rows keep a literal 'operator' value.
126  actor: string;
127  // The caller, resolved once per request (src/agents.ts). `actor` is a projection of
128  // it; the scope checks read this.
129  agent: Agent;
130  // checkScope bound to this caller (src/scope.ts): a refusal naming the missing
131  // scope, or null. The registrar has already checked the tool, grant, namespace and
132  // repo; this is for what only the handler knows: an action tool's action, and the
133  // flags a repo mutation needs.
134  scope: (need: ScopeNeed) => string | null;
135  // Where each module defines its operations (./operations). The composite tools in
136  // ./surface dispatch to them.
137  ops: Operations;
138  lastActor: (ns: string, path: string) => Promise<string | null>;
139}
140
141// Registered in this order, which is the order tools/list publishes.
142export function defineDocOperations(server: McpServer, ctx: ToolCtx): void {
143  defineListOperation(server, ctx);
144  defineReadOperation(server, ctx);
145  defineBriefOperation(server, ctx);
146  defineWriteOperation(server, ctx);
147  defineHistoryOperation(server, ctx);
148  defineRestoreOperation(server, ctx);
149  defineBacklinksOperation(server, ctx);
150  defineDeleteOperation(server, ctx);
151  defineMoveOperation(server, ctx);
152  defineFindOperation(server, ctx);
153  defineSearchOperation(server, ctx);
154  defineNamespaceOperations(server, ctx);
155}