@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 306 lines 11.7 KB
Raw
1 import { McpServer, Tool, Toolkit } from "effect/ai";
2 import * as Effect from "effect/Effect";
3 import type * as Headers from "effect/http/Headers";
4 import { HttpServerRequest } from "effect/http/HttpServerRequest";
5 import * as Layer from "effect/Layer";
6 import * as Option from "effect/Option";
7 import type * as Rpc from "effect/rpc/Rpc";
8 import type * as RpcGroup from "effect/rpc/RpcGroup";
9 import type * as RpcMiddleware from "effect/rpc/RpcMiddleware";
10 import * as Schema from "effect/Schema";
11 import * as SchemaAST from "effect/SchemaAST";
12 import type * as Scope from "effect/Scope";
13 import type { Servable } from "./Api.ts";
14 import { DefinitionError, DuplicateTool, ToolNameTooLong } from "./DefinitionError.ts";
15 import { type Operation, operationsOf, outsideClient } from "./ReadRpcs.ts";
16
17 /** What {@link toToolkit} reads from an Api class: what it serves, its RPCs, and its in-process client. */
18 export interface Toolable {
19 readonly apiName: string;
20 readonly serves: ReadonlyArray<Servable>;
21 readonly group: RpcGroup.RpcGroup<Rpc.Any>;
22 readonly clientInProcess: Effect.Effect<unknown, never, any>;
23 }
24
25 /**
26 * The services an Api's tools need: the hosted Domain and its middleware
27 * Layers. Not the client half of any middleware: the agent's calls carry
28 * their own headers.
29 */
30 export type Services<A extends Toolable> = Exclude<
31 Effect.Services<A["clientInProcess"]>,
32 Scope.Scope | RpcMiddleware.ForClient<any>
33 >;
34
35 /** One schema for several failures, without repeats or `Never`. */
36 const failures = (schemas: ReadonlyArray<Schema.Top>): Schema.Top => {
37 const members = new Set<Schema.Top>();
38 const add = (schema: Schema.Top): void => {
39 const union = schema as Schema.Top & { readonly members?: ReadonlyArray<Schema.Top> };
40 if (SchemaAST.isUnion(schema.ast) && union.members) union.members.forEach(add);
41 else if (!SchemaAST.isNever(schema.ast)) members.add(schema);
42 };
43 schemas.forEach(add);
44 const list = [...members];
45 return list.length === 0 ? Schema.Never : list.length === 1 ? list[0]! : Schema.Union(list);
46 };
47
48 export interface ToolkitOptions<R = never> {
49 /**
50 * The headers each call carries to the Api's middleware (a session cookie,
51 * a bearer token), read in the context of the call. By default, the
52 * headers of the current `HttpServerRequest`, if there is one: an MCP
53 * server over HTTP passes on what its client sent. Without one, a call
54 * carries no headers.
55 */
56 readonly headers?: Effect.Effect<Headers.Input, never, R>;
57 }
58
59 /** An Api's tools, and the Layer that answers them. */
60 export interface ApiToolkit<R> {
61 /** One tool per call of the Api that returns once (see {@link toToolkit}). */
62 readonly toolkit: Toolkit.Toolkit<Record<string, Tool.Any>>;
63 /** The handlers of {@link toolkit}: each calls the Api in process. */
64 readonly layer: Layer.Layer<Tool.HandlersFor<Record<string, Tool.Any>>, never, R>;
65 }
66
67 /** Characters every MCP client and model provider accepts in a tool name. */
68 const unsafe = /[^A-Za-z0-9_-]/g;
69 /** The longest tool name model providers accept. */
70 const MAX_NAME = 64;
71
72 /**
73 * The tool's name: `<api>_<name>_<operation>`, with any other character
74 * than a letter, digit, `_` or `-` replaced by `_`.
75 */
76 export const toolName = (op: {
77 readonly api: string;
78 readonly name: string;
79 readonly operation: string;
80 }): string => `${op.api}_${op.name}_${op.operation}`.replace(unsafe, "_");
81
82 /**
83 * What the model reads about the tool: a command's Schema `description`
84 * annotation, or a sentence built from the call.
85 */
86 const toolDescription = (op: Operation): string =>
87 (op.served.kind === "Command" ? SchemaAST.resolveDescription(op.served.ast) : undefined) ??
88 (op.operation === "send"
89 ? `Send the ${op.name} command.`
90 : op.operation === "peek"
91 ? `Get the latest entry of the ${op.name} stream for a key.`
92 : op.operation === "list"
93 ? `List a page of the ${op.name} entries of a key.`
94 : op.operation === "snapshot"
95 ? `Get the current ${op.name} of a key, with the cursor it is valid at.`
96 : `Get the current ${op.name} of a key.`);
97
98 /**
99 * A call that returns once. A stream (`watch`, `events`) is not one tool
100 * result: it stays on the Api's own clients.
101 */
102 const isToolCall = (op: Operation): boolean => !op.stream;
103
104 /** Whether values of the schema are JSON objects, as an MCP tool's output must be. */
105 const isObject = (schema: Schema.Top): boolean => {
106 const document = Schema.toJsonSchemaDocument(schema);
107 const ref = document.schema.$ref;
108 const root =
109 typeof ref === "string"
110 ? (document.definitions[ref.slice(ref.lastIndexOf("/") + 1)] ?? document.schema)
111 : document.schema;
112 return root.type === "object";
113 };
114
115 /** The tool for one call, and how to call it with the in-process client. */
116 const toolOf = (api: string) => (op: Operation) => {
117 const { rpc } = op;
118 const success = rpc.successSchema;
119 // MCP clients reject a tool whose output is not an object (`State | null`),
120 // so such a value is returned as `{ value }`.
121 const wrapped = !isObject(success);
122 const write = op.operation === "send";
123 const tool = Tool.make(toolName({ api, name: op.name, operation: op.operation }), {
124 description: toolDescription(op),
125 // JSON codecs, as the Api's HTTP server uses: the tool decodes the
126 // call's JSON once, and the in-process call does not decode it again.
127 parameters: Schema.toCodecJson(rpc.payloadSchema),
128 success: Schema.toCodecJson(wrapped ? Schema.Struct({ value: success }) : success),
129 failure: Schema.toCodecJson(
130 failures([rpc.errorSchema, ...[...rpc.middlewares].map((middleware) => middleware.error)]),
131 ),
132 // A rejection is a result the model can act on, not a failed generation.
133 failureMode: "return",
134 })
135 .annotate(Tool.Readonly, !write)
136 .annotate(Tool.Destructive, write)
137 .annotate(Tool.Idempotent, !write);
138 return { tool, op, wrapped };
139 };
140
141 type Client = Record<string, unknown>;
142
143 /**
144 * Send one call through the Api's client: a command takes its target, input
145 * and command id; a read its key and options.
146 */
147 const invoke = (client: Client, op: Operation, payload: unknown, headers?: Headers.Input) => {
148 if (op.operation === "send") {
149 const send = client[op.name] as (
150 target: unknown,
151 input: unknown,
152 options: object,
153 ) => Effect.Effect<unknown, unknown>;
154 const { target, input, commandId } = payload as {
155 readonly target: unknown;
156 readonly input: unknown;
157 readonly commandId?: string;
158 };
159 return send(target, input, { headers, ...(commandId === undefined ? {} : { commandId }) });
160 }
161 const { key, ...options } = payload as { readonly key: unknown };
162 const read = (
163 client[op.name] as Record<string, (k: unknown, o: object) => Effect.Effect<unknown, unknown>>
164 )[op.operation]!;
165 return read(key, { ...options, headers });
166 };
167
168 const requestHeaders: Effect.Effect<Headers.Input | undefined> = Effect.map(
169 Effect.serviceOption(HttpServerRequest),
170 Option.match({ onNone: () => undefined, onSome: (request) => request.headers }),
171 );
172
173 /**
174 * An Effect AI `Toolkit` with one tool per call of the Api that returns once:
175 * each command's `send` (a write), and each `get`, `peek`, `list` and
176 * `snapshot` (reads).
177 * `watch` and `events` are streams, not one tool result, so they stay on the
178 * Api's own clients.
179 *
180 * A tool is named `<api>_<name>_<operation>` (`BankApi_DepositMoney_send`),
181 * with every character other than a letter, digit, `_` or `-` replaced by
182 * `_`. Its parameters, success and failure are the call's own schemas, as the
183 * Api's RPC server decodes them. A read is marked
184 * read-only and a command destructive. A success that is not a JSON object
185 * (a view's `state | null`) comes back as `{ value }`, since MCP requires an
186 * object.
187 *
188 * Each handler calls the Api in process, through the same RPC server as
189 * `clientInProcess`: the call's middleware runs against the headers from
190 * `options.headers`, and a rejection or a middleware error comes back as the
191 * tool's typed failure, for the model to act on. Any other error is a
192 * defect, and never reaches the model. Two calls that make the same tool
193 * name, or a name longer than 64 characters, fail the Layer with a
194 * `DefinitionError`.
195 *
196 * **Example:** Tools for an in-app agent
197 * ```typescript
198 * import * as DomainAi from "@alchemy.run/domain/Ai";
199 * import { LanguageModel } from "effect/ai";
200 *
201 * const { toolkit, layer } = DomainAi.toToolkit(CustomerApi, {
202 * // The signed-in customer's session, for the Api's session middleware.
203 * headers: Effect.map(CurrentSession, (s) => ({ authorization: `Bearer ${s.token}` })),
204 * });
205 *
206 * const answer = LanguageModel.generateText({
207 * prompt: "Move 20 dollars to savings",
208 * toolkit,
209 * }).pipe(Effect.provide(layer));
210 * ```
211 */
212 export const toToolkit = <A extends Toolable, R = never>(
213 api: A,
214 options: ToolkitOptions<R> = {},
215 ): ApiToolkit<Services<A> | R> => {
216 // A tool name a model provider would refuse fails the Layer, like the model's own definition problems.
217 const problems: Array<DefinitionError> = [];
218 const names = new Set<string>();
219 const tools = operationsOf(api.serves)
220 .filter(isToolCall)
221 .map(toolOf(api.apiName))
222 .filter(({ tool }) => {
223 if (tool.name.length > MAX_NAME) {
224 problems.push(
225 new DefinitionError({
226 reason: new ToolNameTooLong({ tool: tool.name, max: MAX_NAME }),
227 }),
228 );
229 } else if (names.has(tool.name)) {
230 problems.push(
231 new DefinitionError({
232 reason: new DuplicateTool({ api: api.apiName, tool: tool.name }),
233 }),
234 );
235 } else {
236 names.add(tool.name);
237 return true;
238 }
239 return false;
240 });
241 const toolkit = Toolkit.make(...tools.map(({ tool }) => tool)) as unknown as Toolkit.Toolkit<
242 Record<string, Tool.Any>
243 >;
244 const headers = (options.headers ?? requestHeaders) as Effect.Effect<
245 Headers.Input | undefined,
246 never,
247 R
248 >;
249 const layer = toolkit.toLayer(
250 Effect.gen(function* () {
251 if (problems.length > 0) return yield* Effect.die(problems[0]);
252 // Without the client half of any middleware (see `outsideClient`).
253 const client = (yield* outsideClient(api)) as Client;
254 return Object.fromEntries(
255 tools.map(({ tool, op, wrapped }) => [
256 tool.name,
257 (payload: unknown) =>
258 headers.pipe(
259 Effect.flatMap((headers) => invoke(client, op, payload, headers)),
260 Effect.map((value) => (wrapped ? { value } : value)),
261 ),
262 ]),
263 );
264 }) as Effect.Effect<Record<string, never>, never, Services<A> | R | Scope.Scope>,
265 );
266 return { toolkit, layer } as ApiToolkit<Services<A> | R>;
267 };
268
269 /**
270 * Serve an Api's tools ({@link toToolkit}) from Effect's `McpServer`. Provide
271 * an `McpServer` transport, such as `McpServer.layerHttp`. Over HTTP, each
272 * call carries the headers of the MCP request to the Api's middleware, so
273 * the Api authenticates an MCP client as it does any other.
274 *
275 * **Example:** An MCP server for an Api
276 * ```typescript
277 * import * as DomainAi from "@alchemy.run/domain/Ai";
278 * import { McpProtocol, McpServer } from "effect/ai";
279 * import * as HttpRouter from "effect/http/HttpRouter";
280 *
281 * const Mcp = DomainAi.toMcp(CustomerApi).pipe(
282 * Layer.provide(
283 * McpServer.layerHttp({
284 * name: "bank",
285 * version: "1.0.0",
286 * path: "/mcp",
287 * protocols: [McpProtocol.v2025_11_25],
288 * }),
289 * ),
290 * Layer.provide(BankLive),
291 * );
292 *
293 * const { handler } = HttpRouter.toWebHandler(Mcp);
294 * ```
295 */
296 export const toMcp = <A extends Toolable, R = never>(
297 api: A,
298 options: ToolkitOptions<R> = {},
299 ): Layer.Layer<never, never, Services<A> | R> => {
300 const { toolkit, layer } = toToolkit(api, options);
301 return McpServer.toolkit(toolkit).pipe(Layer.provide(layer)) as Layer.Layer<
302 never,
303 never,
304 Services<A> | R
305 >;
306 };