src/tools/controls.ts

Functions

Imports

It imports src/controls-base.ts, src/controls.ts, src/limits.ts, src/ops-types/portal.ts, src/tools/docs.ts. Imported by src/server.ts.

Source

1import { McpServer } from "@modelcontextprotocol/server";
2import { z } from "zod";
3import { CONTROLS, performControl, previewControl, TOKEN_TTL_SECONDS } from "../controls";
4import { PORTAL_ACTIONS } from "../controls-base";
5import { bounded, MAX_TITLE } from "../limits";
6import type { PortalAction } from "../ops-types/portal";
7import { fail, ok, type ToolCtx } from "./docs";
8
9const MAX_PARAM = 1024;
10const MAX_KEY = 64;
11const MAX_TOKEN = 4096;
12const ACCESS_PREFIX = "access:";
13
14export function defineControlOperations(server: McpServer, ctx: ToolCtx): void {
15  const { env } = ctx;
16
17  // The admin controls the Portal's buttons run, reachable from chat as one tool (a ruled
18  // exception to the tool surface rule, 2026-10-03). One registry (src/controls.ts) is behind both surfaces, so a control
19  // is implemented once and a test holds the two lists equal. Admin only in whole
20  // (TOOL_GRANTS.capsid_admin_run_controls): the registrar refuses every other caller before this handler
21  // runs. The confirmation is the Portal's: preview returns the plan and a signed token for
22  // five minutes that binds the action, its params and this administrator, and perform
23  // takes only the token and spends it, so no confirmation is used twice.
24  ctx.ops.define(
25    "controls",
26    {
27      description: `The administrator's controls, the same ones Capsid Portal's buttons run: ${PORTAL_ACTIONS.join(", ")}. Admin only. Two steps, never one. action "list" returns each control, the params it takes and whether it needs a reason. action "preview" (control, params) reads the current state, WRITES NOTHING, and returns what will change, the audit rows it will write and a token good for ${TOKEN_TTL_SECONDS / 60} minutes. action "perform" (token) runs exactly what that preview described, once: the token binds the action, its params and you, and is spent when used, so a second perform of it is refused and you preview again. Performing from here writes a control-<action> audit row naming you and the surface; the Portal writes portal-<action>. Merging a pull request and minting a credential are deliberately not controls: a merge can start a deploy and stays with capsid_close_pr action merge behind can_merge, and a mint stays with capsid_admin_manage_agents. REFUSES: a caller that is not the administrator signed in through Access; an unknown control; a param the control does not take; a switch with no reason; a token that is malformed, expired, issued to someone else or already used.`,
28      inputSchema: {
29        action: z.enum(["list", "preview", "perform"]).describe("list | preview | perform."),
30        control: z
31          .enum(PORTAL_ACTIONS as unknown as [PortalAction, ...PortalAction[]])
32          .optional()
33          .describe("For preview: the control to preview."),
34        params: z
35          .record(bounded(MAX_KEY), bounded(MAX_PARAM))
36          .optional()
37          .describe(`For preview: the control's params, each a string (list says which). A reason is at most ${MAX_TITLE} characters.`),
38        token: bounded(MAX_TOKEN).optional().describe("For perform: the token the preview returned. Nothing else is read."),
39      },
40    },
41    async (args) => {
42      const now = new Date();
43      // The token binds an email, and a chat caller has one only when it is the administrator
44      // signed in through Access (agent:access:<email>). An operator key or a minted agent
45      // has none and cannot hold a control, whatever its grant.
46      if (!ctx.actor.startsWith(ACCESS_PREFIX) || ctx.actor.length === ACCESS_PREFIX.length) {
47        return fail(`controls needs the administrator signed in through Access; ${ctx.actor} is not.`);
48      }
49      const email = ctx.actor.slice(ACCESS_PREFIX.length);
50      try {
51        if (args.action === "list") {
52          return ok({
53            controls: CONTROLS.map((c) => ({ control: c.name, params: c.fields, reason_required: c.reasonRequired })),
54            next: 'Call action "preview" with a control and its params, read the plan, then call action "perform" with the token.',
55          });
56        }
57        if (args.action === "preview") {
58          if (!args.control) return fail('preview needs a control. Call action "list" for the names.');
59          const previewed = await previewControl(env, email, args.control, args.params ?? {}, now, "chat");
60          return previewed.ok ? ok(previewed.preview) : fail(previewed.refusal);
61        }
62        if (!args.token) return fail("perform needs the token a preview returned.");
63        const did = await performControl(env, email, args.token, null, now, "chat");
64        return did.ok ? ok({ action: did.action, summary: did.result.summary, warning: did.result.warning }) : fail(did.refusal);
65      } catch (err) {
66        return fail(err instanceof Error ? err.message : String(err));
67      }
68    }
69  );
70}