src/tools/operations.ts

Functions

Imports

It imports no other module of this repo. Imported by src/server.ts, src/tools/docs.ts, src/tools/surface.ts.

Source

1import { z, type ZodType } from "zod";
2
3// An input shape as the SDK takes it: field name to zod (classic) schema.
4export type Shape = Record<string, ZodType>;
5
6// The operations behind the served tools (the MCP 4 regroup).
7//
8// Capsid serves 14 tools and Capsid Admin 8, each one whole job with an `action`
9// argument. The work each action does is an operation: a handler with its own input
10// shape, defined once by the module that owns it (src/tools/docs-read.ts and the rest)
11// and dispatched by the composite tool in src/tools/surface.ts. An operation is not a
12// tool: nothing serves its name, scope never sees it, and an agent's tools axis names
13// the composite tool and its action ("capsid_read_doc.versions"), never the operation.
14//
15// The dispatcher validates the arguments against the operation's own shape, which is
16// what the SDK did when each operation was a tool, so a handler still receives
17// arguments its schema has parsed.
18
19export interface OperationConfig {
20  description: string;
21  inputSchema: Shape;
22}
23
24// The SDK's tool result, as the handlers build it (ok and fail in ./docs).
25export interface OperationResult {
26  content: Array<{ type: "text"; text: string }>;
27  isError?: boolean;
28  [key: string]: unknown;
29}
30
31// Handlers keep the argument types their own shape gives them; the dispatcher has parsed
32// them before the call, so the table stores each one taking unknown.
33type OperationHandler = (args: unknown) => OperationResult | Promise<OperationResult>;
34
35interface Operation {
36  config: OperationConfig;
37  handler: OperationHandler;
38}
39
40export class Operations {
41  private readonly table = new Map<string, Operation>();
42
43  define<S extends Shape>(
44    name: string,
45    config: { description: string; inputSchema: S },
46    handler: (args: z.infer<z.ZodObject<S>>) => OperationResult | Promise<OperationResult>
47  ): void {
48    if (this.table.has(name)) throw new Error(`operation '${name}' is defined twice`);
49    this.table.set(name, { config, handler: handler as OperationHandler });
50  }
51
52  has(name: string): boolean {
53    return this.table.has(name);
54  }
55
56  config(name: string): OperationConfig {
57    return this.get(name).config;
58  }
59
60  names(): string[] {
61    return [...this.table.keys()];
62  }
63
64  // Parses `args` against the operation's own shape, then runs it. A parse failure is
65  // the refusal the SDK gave before: the argument and what was wrong with it.
66  async run(name: string, args: Record<string, unknown>, label: string): Promise<OperationResult> {
67    const op = this.get(name);
68    const parsed = z.object(op.config.inputSchema).safeParse(args);
69    if (!parsed.success) {
70      const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "(arguments)"}: ${i.message}`).join("; ");
71      return { content: [{ type: "text", text: `invalid arguments for ${label}: ${issues}` }], isError: true };
72    }
73    return op.handler(parsed.data);
74  }
75
76  private get(name: string): Operation {
77    const op = this.table.get(name);
78    if (!op) throw new Error(`no operation '${name}'`);
79    return op;
80  }
81}