src/server.ts

Functions

Imports

It imports src/admin-client-audit.ts, src/agents.ts, src/cache-hints.ts, src/env.ts, src/prompts.ts, src/resources.ts, src/scope.ts, src/time.ts, src/tools/admin.ts, src/tools/agents.ts, src/tools/claims.ts, src/tools/cloudflare.ts, src/tools/controls.ts, src/tools/docs.ts, src/tools/jobs.ts, src/tools/lint.ts, src/tools/operations.ts, src/tools/ops.ts, src/tools/repo.ts, src/tools/status.ts, src/tools/surface.ts. Imported by src/index.ts, src/routes.ts, src/tools/docs-write.ts.

Source

1import { McpServer } from "@modelcontextprotocol/server";
2import type { Env } from "./env";
3import { legacyAgent, type Agent } from "./agents";
4import { checkScope, guardRegistrations } from "./scope";
5import type { AdminWriteObserver } from "./admin-client-audit";
6import { registerDocumentResources } from "./resources";
7import { registerPrompts } from "./prompts";
8import { CACHE_HINTS } from "./cache-hints";
9import { defineDocOperations, type ToolCtx, type ToolGrant } from "./tools/docs";
10import { defineLintOperations } from "./tools/lint";
11import { defineRepoOperations } from "./tools/repo";
12import { defineStatusOperations } from "./tools/status";
13import { defineJobOperations } from "./tools/jobs";
14import { defineAgentOperations } from "./tools/agents";
15import { defineClaimsOperations } from "./tools/claims";
16import { defineOpsSnapshotOperations } from "./tools/ops";
17import { defineCloudflareOperations } from "./tools/cloudflare";
18import { defineControlOperations } from "./tools/controls";
19import { defineAdminOperations } from "./tools/admin";
20import { Operations } from "./tools/operations";
21import { registerCapsidAdminTools, registerCapsidTools } from "./tools/surface";
22import { HOUR_MS } from "./time";
23
24export type { ToolGrant };
25
26const SERVER_INFO = { name: "capsid", version: "1.0.0" };
27const ADMIN_SERVER_INFO = { name: "capsid-admin", version: "1.0.0" };
28
29// Warn, never refuse, when overwriting a document touched in the last hour without if_match.
30const CONCURRENT_EDIT_WINDOW_MS = HOUR_MS;
31
32export function concurrentEditWarning(updatedAt: string | null | undefined, now: number): string | null {
33  if (!updatedAt) return null;
34  // D1 stores datetime('now') in UTC with no zone, which Date.parse reads as local.
35  // That would silence the warning on a machine behind UTC and fire it constantly on
36  // one ahead.
37  const parsed = Date.parse(`${updatedAt.replace(" ", "T")}Z`);
38  if (Number.isNaN(parsed)) return null;
39  const age = now - parsed;
40  if (age < 0 || age > CONCURRENT_EDIT_WINDOW_MS) return null;
41  return (
42    `possible concurrent edit: this document was last written at ${updatedAt} UTC, within the last hour, and no if_match was passed. ` +
43    `The write went through and the prior body was snapshotted to document_versions, so nothing is lost, but if another session is working on this document your write may have just replaced its changes. ` +
44    `Pass if_match (the sha256 this response returns) on the next write to make that a refusal instead of a warning.`
45  );
46}
47
48// The caller is an agent (src/agents.ts). A bare grant plus an actor string means an
49// unrestricted caller at that grant: the OPERATOR_KEY_HASH fallback, expressed once so
50// there is no second code path where scopes do not apply.
51const MAX_TOOL_INPUT_ELEMENTS = 10_000;
52
53export function buildServer(env: Env, caller: Agent | ToolGrant, actor = "", observeAdminWrite?: AdminWriteObserver): McpServer {
54  return build(env, caller, actor, observeAdminWrite, "capsid");
55}
56
57// Capsid Admin: the eight
58// administrator tools, on their own route for the administrator alone
59// (src/mcp-handler.ts). Every tool on it is admin only in TOOL_GRANTS too, so the route
60// and the registrar refuse a non-admin twice.
61export function buildAdminServer(env: Env, caller: Agent | ToolGrant, actor = "", observeAdminWrite?: AdminWriteObserver): McpServer {
62  return build(env, caller, actor, observeAdminWrite, "admin");
63}
64
65function build(env: Env, caller: Agent | ToolGrant, actor: string, observeAdminWrite: AdminWriteObserver | undefined, surface: "capsid" | "admin"): McpServer {
66  const agent = typeof caller === "string" ? legacyAgent(caller, actor) : caller;
67  // maxToolInputElements caps how many array elements and object members one tools/call may
68  // carry, which the SDK leaves unlimited (GHSA-46jr-4wx8-v453; Grok audit 2026-10-21, CA-2).
69  // A document body is one string, so one element; 10,000 leaves room for any list a tool takes.
70  const server = new McpServer(surface === "admin" ? ADMIN_SERVER_INFO : SERVER_INFO, { cacheHints: CACHE_HINTS, maxToolInputElements: MAX_TOOL_INPUT_ELEMENTS });
71  const db = env.DB;
72
73  // Provenance: the actor from a document's latest audit_log entry, surfaced by read
74  // and brief so a session can tell who wrote what it treats as context: a document
75  // another client wrote is untrusted input. A separate read rather than a joined
76  // subquery, so the document read stays a named-column projection. Null when the
77  // document has no audit history.
78  const lastActor = async (ns: string, path: string): Promise<string | null> => {
79    const row = await db
80      .prepare("SELECT actor FROM audit_log WHERE namespace = ?1 AND path = ?2 ORDER BY id DESC LIMIT 1")
81      .bind(ns, path)
82      .first<{ actor: string | null }>();
83    return row?.actor ?? null;
84  };
85
86  const ctx: ToolCtx = {
87    env,
88    db,
89    actor: agent.actor,
90    agent,
91    // The handler half of the one enforcement point, for checks that need the action,
92    // mode or path.
93    scope: (need) => checkScope(agent, need),
94    lastActor,
95    ops: new Operations(),
96  };
97
98  // Every operation, on both servers: an operation is not served until a tool on this
99  // server dispatches to it (src/tools/surface.ts).
100  defineDocOperations(server, ctx);
101  defineLintOperations(server, ctx);
102  defineRepoOperations(server, ctx);
103  defineStatusOperations(server, ctx);
104  defineJobOperations(server, ctx);
105  defineAgentOperations(server, ctx);
106  defineClaimsOperations(server, ctx);
107  defineOpsSnapshotOperations(server, ctx);
108  defineCloudflareOperations(server, ctx);
109  defineControlOperations(server, ctx);
110  defineAdminOperations(server, ctx);
111
112  // Before any registration, so every tool registered below is wrapped.
113  guardRegistrations(server, agent, observeAdminWrite, env.APP_KV);
114
115  if (surface === "admin") {
116    registerCapsidAdminTools(server, ctx.ops);
117    return server;
118  }
119  registerCapsidTools(server, ctx.ops);
120
121  // Resources and prompts are raw request handlers, not tool registrations, so they
122  // check scope themselves (src/resources.ts).
123  registerDocumentResources(server, agent, db);
124  registerPrompts(server, agent, db);
125
126  return server;
127}