src/tools/ops.ts

Functions

Imports

It imports src/limits.ts, src/ops-snapshot.ts, src/tools/docs.ts. Imported by src/server.ts.

Source

1import { McpServer } from "@modelcontextprotocol/server";
2import { z } from "zod";
3import { OPS_SNAPSHOT_KEY, readSnapshot, RING_SLOTS, ringReading } from "../ops-snapshot";
4import { bounded, nsName } from "../limits";
5import { fail, ok, type ToolCtx } from "./docs";
6
7// An ISO time, as the other tools bound a timestamp argument.
8const MAX_AT = 40;
9
10export function defineOpsSnapshotOperations(server: McpServer, ctx: ToolCtx): void {
11  const { env } = ctx;
12
13  // The watcher's last pass, the value the Portal's Watch Floor reads (ops:snapshot in
14  // APP_KV, src/ops-snapshot.ts). Ruled 2026-09-29, "Capsid MCP roadmap, build or don't
15  // build". Admin only in whole: the snapshot spans every
16  // namespace's sites, CI and Cloudflare state. TOOL_GRANTS.capsid_admin_read_ops in src/scope.ts
17  // states it and the registrar refuses anyone else before this handler runs. It reads
18  // one KV value and writes nothing.
19  ctx.ops.define(
20    "ops_snapshot",
21    {
22      description: `The watcher's last pass as the Watch Floor reads it (${OPS_SNAPSHOT_KEY}): every check's state and findings, /health, the backup mirror, each roster repo's latest CI run, the site map, and every site's probe, Cloudflare state and 7-day uptime ring. Admin only. It reads and never writes. With no arguments it returns the whole snapshot. site (a namespace) returns that site's entry with the pass time. site with slot (0 to ${RING_SLOTS - 1}, 0 the newest half hour) or at (an ISO time) returns that site's ring value for one half-hour slot, with the window it covers: up, down, no-pass (no pass reached it) or outside-ring (older than the history held). REFUSES: no snapshot written yet or one that does not parse, a site the snapshot does not hold, slot or at without site, slot with at, and a slot or time outside the ring.`,
23      inputSchema: {
24        site: nsName.optional().describe("A site's namespace, as the snapshot's sites list names it."),
25        slot: z
26          .number()
27          .int()
28          .min(0)
29          .max(RING_SLOTS - 1)
30          .optional()
31          .describe(`With site: a ring slot counted back from the newest (0), up to ${RING_SLOTS - 1}.`),
32        at: bounded(MAX_AT).optional().describe("With site: the ISO time whose half-hour slot to read."),
33      },
34    },
35    async ({ site, slot, at }) => {
36      try {
37        if ((slot !== undefined || at !== undefined) && site === undefined) {
38          return fail("ops_snapshot: slot and at read one site's ring, so they need site.");
39        }
40        if (slot !== undefined && at !== undefined) {
41          return fail("ops_snapshot: pass slot or at, not both.");
42        }
43        const snapshot = await readSnapshot(env);
44        if (!snapshot) {
45          // readSnapshot treats a value that does not parse, or a version other than 1,
46          // as absent, and logs which. Both mean there is nothing current to read.
47          return fail(
48            `ops_snapshot: there is no readable snapshot at ${OPS_SNAPSHOT_KEY}. The watcher has not written one yet, or the stored value did not parse as version 1. The watcher's next pass writes it; the Portal's Refresh runs one now.`
49          );
50        }
51        if (site === undefined) return ok(snapshot);
52
53        const entry = snapshot.sites.find((s) => s.namespace === site);
54        if (!entry) {
55          const held = snapshot.sites.map((s) => s.namespace);
56          return fail(`ops_snapshot: the snapshot of ${snapshot.pass_at} holds no site '${site}'. It holds: ${held.join(", ") || "no sites"}.`);
57        }
58        if (slot === undefined && at === undefined) return ok({ pass_at: snapshot.pass_at, site: entry });
59
60        const reading = ringReading(entry, slot !== undefined ? { slot } : { at: new Date(at as string) });
61        if (typeof reading === "string") return fail(`ops_snapshot: ${reading}`);
62        return ok({ pass_at: snapshot.pass_at, ...reading });
63      } catch (err) {
64        return fail(err instanceof Error ? err.message : String(err));
65      }
66    }
67  );
68}