src/tools/agents.ts

Functions

Imports

It imports src/agents-admin.ts, src/agents-archive.ts, src/agents-schema.ts, src/limits.ts, src/tools/docs.ts. Imported by src/server.ts.

Source

1import { McpServer } from "@modelcontextprotocol/server";
2import { z } from "zod";
3import { AGENT_KINDS, SCOPE_FLAGS, AGENT_GRANTS } from "../agents-schema";
4import { listAgents, mintAgent, revokeAgent, updateAgentScopes } from "../agents-admin";
5import { listArchivedAgents } from "../agents-archive";
6import { bounded, MAX_DOC_TYPE, nsName } from "../limits";
7import { fail, ok, type ToolCtx } from "./docs";
8
9const AGENT_ACTIONS = ["mint", "list", "revoke", "update_scopes"] as const;
10
11export function defineAgentOperations(server: McpServer, ctx: ToolCtx): void {
12  const { db, actor } = ctx;
13
14  // The credential control plane's one tool, a ruled exception to the tool surface
15  // rule (CLAUDE.md). Minting by hand would leave the scope rows
16  // with no audit trail and no validation. Its actions share one tool because they
17  // are one subsystem with one row shape.
18  ctx.ops.define(
19    "agents",
20    {
21      description:
22        `Scoped credentials: one row per caller, with its own key, scopes and audit identity (agent:<name>). Admin only, every action: a minted agent cannot mint, revoke or re-scope. The admin is an OAuth session on /mcp or a write-grant OPERATOR_KEY_HASH entry on /ops/mcp. action "mint" creates an agent and returns its key once; only its sha256 is stored, so a lost key is replaced by revoking and minting again. It takes name (unique, revoked names included), kind (${AGENT_KINDS.join(" | ")}), namespaces (a list, or the single entry "*"), and optionally repos, tools, grants and flags. A new agent defaults to read on its namespaces with no flags. The flags are ${SCOPE_FLAGS.join(", ")}. action "list" returns every agent in the live table, revoked ones not yet archived included, with its scopes, last_seen and a 12-hex fingerprint of its key digest; never the stored verifier. With archived: true it returns the archive instead: revoked agents moved out of the live table by the watcher pass 7 days after revocation, or an old one-job runner key once its job ended, each with its reason, archived_at and the audit-row and job counts taken at the move. An archived name is never reused. action "revoke" sets revoked_at, keeps the row, and the key stops resolving immediately. action "update_scopes" replaces only the axes named: a call naming one flag leaves the others. Mint, revoke and update_scopes are audit-logged, never with the key.`,
23      inputSchema: {
24        action: z.enum(AGENT_ACTIONS).describe("mint | list | revoke | update_scopes."),
25        name: bounded(64).optional().describe("For mint, revoke and update_scopes: the agent's name."),
26        archived: z.boolean().optional().describe("For list: true returns the archived agents instead of the live table."),
27        kind: bounded(MAX_DOC_TYPE).optional().describe(`For mint: ${AGENT_KINDS.join(" | ")}. Grants nothing by itself.`),
28        namespaces: z
29          .array(nsName)
30          .optional()
31          .describe('For mint (required) and update_scopes: the namespaces this agent may reach, or the single entry "*" for every one.'),
32        repos: z
33          .array(bounded(128))
34          .optional()
35          .describe(
36            'The repos this agent may reach, as "owner/name" entries, or the single entry "*". Omitted, the mint derives it from the namespaces\' repo mapping, and refuses when a namespace maps no repo. A namespace scope of "*" derives "*".'
37          ),
38        tools: z.array(bounded(64)).optional().describe('Tool names this agent may call, or the single entry "*". Defaults to every tool its grant allows. An entry "tool.action" (for example "capsid_open_pr.comment") narrows that tool to the actions named.'),
39        grants: z.array(z.enum(AGENT_GRANTS)).optional().describe(`read, or read and write. A new agent gets read.`),
40        flags: z
41          .object(Object.fromEntries(SCOPE_FLAGS.map((flag) => [flag, z.boolean().optional()])))
42          .optional()
43          .describe(`${SCOPE_FLAGS.join(", ")}. An absent flag is left unchanged. Each defaults to false at mint.`),
44      },
45    },
46    async (args) => {
47      try {
48        // Admin only, every action. TOOL_GRANTS.capsid_admin_manage_agents in src/scope.ts states it and the
49        // registrar refuses a minted agent before this handler runs.
50        const scopeArgs = { namespaces: args.namespaces, repos: args.repos, tools: args.tools, grants: args.grants, flags: args.flags };
51        switch (args.action) {
52          case "mint": {
53            if (!args.name || !args.kind) return fail("mint needs a name and a kind.");
54            return ok(await mintAgent(db, actor, { ...scopeArgs, name: args.name, kind: args.kind }));
55          }
56          case "list":
57            if (args.archived === true) return ok({ ok: true, action: "list", archived: await listArchivedAgents(db) });
58            return ok(await listAgents(db));
59          case "revoke": {
60            if (!args.name) return fail("revoke needs the agent's name.");
61            return ok(await revokeAgent(db, actor, args.name));
62          }
63          case "update_scopes": {
64            if (!args.name) return fail("update_scopes needs the agent's name.");
65            return ok(await updateAgentScopes(db, actor, args.name, scopeArgs));
66          }
67        }
68        return fail(`unknown agents action '${String(args.action as unknown as string)}'.`);
69      } catch (err) {
70        return fail(err instanceof Error ? err.message : String(err));
71      }
72    }
73  );
74}