clanka 0.10.1 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/README.md +75 -0
  2. package/dist/Acp.d.ts +1 -1
  3. package/dist/Acp.d.ts.map +1 -1
  4. package/dist/Acp.js +112 -7
  5. package/dist/Acp.js.map +1 -1
  6. package/dist/Acp.test.js +178 -0
  7. package/dist/Acp.test.js.map +1 -1
  8. package/dist/Agent.d.ts.map +1 -1
  9. package/dist/Agent.js +26 -8
  10. package/dist/Agent.js.map +1 -1
  11. package/dist/AgentExecutor.js +15 -1
  12. package/dist/AgentExecutor.js.map +1 -1
  13. package/dist/AgentExecutor.test.js +24 -4
  14. package/dist/AgentExecutor.test.js.map +1 -1
  15. package/dist/AgentSkills.test.js +0 -1
  16. package/dist/AgentSkills.test.js.map +1 -1
  17. package/dist/AgentSubagents.test.js +16 -6
  18. package/dist/AgentSubagents.test.js.map +1 -1
  19. package/dist/AgentTools.d.ts +7 -0
  20. package/dist/AgentTools.d.ts.map +1 -1
  21. package/dist/AgentTools.js +7 -0
  22. package/dist/AgentTools.js.map +1 -1
  23. package/dist/McpConfig.d.ts +36 -0
  24. package/dist/McpConfig.d.ts.map +1 -0
  25. package/dist/McpConfig.js +182 -0
  26. package/dist/McpConfig.js.map +1 -0
  27. package/dist/McpConfig.test.d.ts +2 -0
  28. package/dist/McpConfig.test.d.ts.map +1 -0
  29. package/dist/McpConfig.test.js +163 -0
  30. package/dist/McpConfig.test.js.map +1 -0
  31. package/dist/McpServers.d.ts +176 -0
  32. package/dist/McpServers.d.ts.map +1 -0
  33. package/dist/McpServers.js +707 -0
  34. package/dist/McpServers.js.map +1 -0
  35. package/dist/McpServers.test.d.ts +2 -0
  36. package/dist/McpServers.test.d.ts.map +1 -0
  37. package/dist/McpServers.test.js +717 -0
  38. package/dist/McpServers.test.js.map +1 -0
  39. package/dist/TypeBuilder.d.ts +9 -0
  40. package/dist/TypeBuilder.d.ts.map +1 -1
  41. package/dist/TypeBuilder.js +24 -11
  42. package/dist/TypeBuilder.js.map +1 -1
  43. package/dist/TypeBuilder.test.js +33 -0
  44. package/dist/TypeBuilder.test.js.map +1 -1
  45. package/dist/bin/{Effect-2jPlJ8eu.mjs → Effect-DuThyCJ1.mjs} +155 -74
  46. package/dist/bin/Effect-DuThyCJ1.mjs.map +1 -0
  47. package/dist/bin/McpClient-CIiPyMDJ.mjs +36 -0
  48. package/dist/bin/McpClient-CIiPyMDJ.mjs.map +1 -0
  49. package/dist/bin/{OutputFormatter-BFAv48k9.mjs → OutputFormatter-BvIjvUmT.mjs} +3 -3
  50. package/dist/bin/{OutputFormatter-BFAv48k9.mjs.map → OutputFormatter-BvIjvUmT.mjs.map} +1 -1
  51. package/dist/bin/{Schema-D-7VuCiC.mjs → Schema-DcXUXpRg.mjs} +1069 -124
  52. package/dist/bin/Schema-DcXUXpRg.mjs.map +1 -0
  53. package/dist/bin/{SemanticSearch-Cb8aqvGv.mjs → SemanticSearch-CdGA4CIC.mjs} +27 -21
  54. package/dist/bin/SemanticSearch-CdGA4CIC.mjs.map +1 -0
  55. package/dist/bin/{Stream-DEu2tfCV.mjs → Stream-I9SRMlLj.mjs} +60 -45
  56. package/dist/bin/Stream-I9SRMlLj.mjs.map +1 -0
  57. package/dist/bin/cli.mjs +27217 -10325
  58. package/dist/bin/cli.mjs.map +1 -1
  59. package/dist/bin/{index.min-CI3qqohw.mjs → index.min-Bkz7vIWv.mjs} +7 -7
  60. package/dist/bin/index.min-Bkz7vIWv.mjs.map +1 -0
  61. package/dist/bin/rolldown-runtime-zY4HT0JA.mjs +30 -0
  62. package/dist/bin/{turndown.cjs-DK29wZw3.mjs → turndown.cjs-LntFxFyd.mjs} +2 -2
  63. package/dist/bin/{turndown.cjs-DK29wZw3.mjs.map → turndown.cjs-LntFxFyd.mjs.map} +1 -1
  64. package/dist/cli.js +46 -7
  65. package/dist/cli.js.map +1 -1
  66. package/dist/fixtures/McpFakeServer.d.ts +47 -0
  67. package/dist/fixtures/McpFakeServer.d.ts.map +1 -0
  68. package/dist/fixtures/McpFakeServer.js +112 -0
  69. package/dist/fixtures/McpFakeServer.js.map +1 -0
  70. package/dist/fixtures/McpStdioServer.d.ts +2 -0
  71. package/dist/fixtures/McpStdioServer.d.ts.map +1 -0
  72. package/dist/fixtures/McpStdioServer.js +53 -0
  73. package/dist/fixtures/McpStdioServer.js.map +1 -0
  74. package/dist/index.d.ts +4 -0
  75. package/dist/index.d.ts.map +1 -1
  76. package/dist/index.js +4 -0
  77. package/dist/index.js.map +1 -1
  78. package/package.json +14 -14
  79. package/src/Acp.test.ts +242 -0
  80. package/src/Acp.ts +141 -5
  81. package/src/Agent.ts +38 -10
  82. package/src/AgentExecutor.test.ts +31 -5
  83. package/src/AgentExecutor.ts +14 -1
  84. package/src/AgentSkills.test.ts +0 -1
  85. package/src/AgentSubagents.test.ts +20 -6
  86. package/src/AgentTools.ts +8 -0
  87. package/src/McpConfig.test.ts +238 -0
  88. package/src/McpConfig.ts +255 -0
  89. package/src/McpServers.test.ts +1050 -0
  90. package/src/McpServers.ts +1072 -0
  91. package/src/TypeBuilder.test.ts +70 -0
  92. package/src/TypeBuilder.ts +41 -14
  93. package/src/cli.ts +92 -8
  94. package/src/fixtures/McpFakeServer.ts +162 -0
  95. package/src/fixtures/McpStdioServer.ts +60 -0
  96. package/src/index.ts +5 -0
  97. package/dist/bin/Effect-2jPlJ8eu.mjs.map +0 -1
  98. package/dist/bin/McpClient-1W508adc.mjs +0 -14179
  99. package/dist/bin/McpClient-1W508adc.mjs.map +0 -1
  100. package/dist/bin/Schema-D-7VuCiC.mjs.map +0 -1
  101. package/dist/bin/SemanticSearch-Cb8aqvGv.mjs.map +0 -1
  102. package/dist/bin/Stream-DEu2tfCV.mjs.map +0 -1
  103. package/dist/bin/index.min-CI3qqohw.mjs.map +0 -1
@@ -0,0 +1,707 @@
1
+ /**
2
+ * MCP servers whose tools scripts call as `mcp.<server>.<tool>(…)`.
3
+ *
4
+ * The servers connect when the layer is built and stay connected until its
5
+ * scope closes. Their tools become loop-side handlers of the Agent, and their
6
+ * type declarations are only returned by the `searchTools` function.
7
+ *
8
+ * @since 1.0.0
9
+ */
10
+ import * as NodePath from "node:path";
11
+ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
12
+ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
13
+ import { StreamableHTTPClientTransport, StreamableHTTPError, } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
14
+ import { ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
15
+ import * as Context from "effect/Context";
16
+ import * as Data from "effect/Data";
17
+ import * as Duration from "effect/Duration";
18
+ import * as Effect from "effect/Effect";
19
+ import * as Base64 from "effect/encoding/Base64";
20
+ import * as Exit from "effect/Exit";
21
+ import * as Fiber from "effect/Fiber";
22
+ import * as JsonSchema from "effect/JsonSchema";
23
+ import * as Layer from "effect/Layer";
24
+ import * as Option from "effect/Option";
25
+ import * as Record from "effect/Record";
26
+ import * as Redacted from "effect/Redacted";
27
+ import * as Result from "effect/Result";
28
+ import * as Schema from "effect/Schema";
29
+ import * as SchemaRepresentation from "effect/SchemaRepresentation";
30
+ import * as Stream from "effect/Stream";
31
+ import { defaultMcpCallTimeout } from "./AgentTools.js";
32
+ import * as Image from "./Image.js";
33
+ import * as TypeBuilder from "./TypeBuilder.js";
34
+ // =============================================================================
35
+ // Config
36
+ // =============================================================================
37
+ const Timeout = Schema.Duration;
38
+ /**
39
+ * A server started as a child process and spoken to over stdio.
40
+ *
41
+ * @since 1.0.0
42
+ * @category Config
43
+ */
44
+ export const StdioServerConfig = Schema.Struct({
45
+ type: Schema.Literal("stdio"),
46
+ command: Schema.String,
47
+ args: Schema.optionalKey(Schema.Array(Schema.String)),
48
+ env: Schema.optionalKey(Schema.Record(Schema.String, Schema.RedactedFromValue(Schema.String))),
49
+ /**
50
+ * Resolved against the process cwd. Defaults to the process cwd.
51
+ */
52
+ cwd: Schema.optionalKey(Schema.String),
53
+ connectTimeout: Schema.optionalKey(Timeout),
54
+ callTimeout: Schema.optionalKey(Timeout),
55
+ });
56
+ /**
57
+ * A server reached over streamable HTTP.
58
+ *
59
+ * @since 1.0.0
60
+ * @category Config
61
+ */
62
+ export const HttpServerConfig = Schema.Struct({
63
+ type: Schema.Literal("http"),
64
+ url: Schema.String,
65
+ headers: Schema.optionalKey(Schema.Record(Schema.String, Schema.RedactedFromValue(Schema.String))),
66
+ connectTimeout: Schema.optionalKey(Timeout),
67
+ callTimeout: Schema.optionalKey(Timeout),
68
+ });
69
+ /**
70
+ * @since 1.0.0
71
+ * @category Config
72
+ */
73
+ export const McpServerConfig = Schema.Union([
74
+ StdioServerConfig,
75
+ HttpServerConfig,
76
+ ]);
77
+ const defaultConnectTimeout = Duration.seconds(30);
78
+ // =============================================================================
79
+ // Status
80
+ // =============================================================================
81
+ /**
82
+ * @since 1.0.0
83
+ * @category Status
84
+ */
85
+ export class Connected extends Data.TaggedClass("Connected") {
86
+ }
87
+ /**
88
+ * @since 1.0.0
89
+ * @category Status
90
+ */
91
+ export class Failed extends Data.TaggedClass("Failed") {
92
+ }
93
+ // =============================================================================
94
+ // Service
95
+ // =============================================================================
96
+ /**
97
+ * @since 1.0.0
98
+ * @category Services
99
+ */
100
+ export class McpServers extends Context.Service()("clanka/McpServers") {
101
+ }
102
+ /**
103
+ * Connects every server when built and closes them with its scope. A server
104
+ * that cannot connect is `Failed`; building the layer never fails.
105
+ *
106
+ * @since 1.0.0
107
+ * @category Layers
108
+ */
109
+ export const layer = (config) => fromEntries(Object.entries(config).map(([name, entry]) => toEntry(name, entry)));
110
+ /**
111
+ * Like `layer`, with transports built by the caller.
112
+ *
113
+ * @since 1.0.0
114
+ * @category Layers
115
+ */
116
+ export const layerTransports = (servers) => fromEntries(Object.entries(servers).map(([name, server]) => ({
117
+ name,
118
+ open: () => ({ transport: server.transport(), stderr: undefined }),
119
+ connectTimeout: server.connectTimeout,
120
+ callTimeout: server.callTimeout,
121
+ })));
122
+ const fromEntries = (entries) => Layer.effect(McpServers, make(entries));
123
+ // =============================================================================
124
+ // Naming
125
+ // =============================================================================
126
+ const reservedWords = new Set([
127
+ "arguments",
128
+ "await",
129
+ "break",
130
+ "case",
131
+ "catch",
132
+ "class",
133
+ "const",
134
+ "continue",
135
+ "debugger",
136
+ "default",
137
+ "delete",
138
+ "do",
139
+ "else",
140
+ "enum",
141
+ "eval",
142
+ "export",
143
+ "extends",
144
+ "false",
145
+ "finally",
146
+ "for",
147
+ "function",
148
+ "if",
149
+ "implements",
150
+ "import",
151
+ "in",
152
+ "instanceof",
153
+ "interface",
154
+ "let",
155
+ "new",
156
+ "null",
157
+ "package",
158
+ "private",
159
+ "protected",
160
+ "public",
161
+ "return",
162
+ "static",
163
+ "super",
164
+ "switch",
165
+ "this",
166
+ "throw",
167
+ "true",
168
+ "try",
169
+ "typeof",
170
+ "var",
171
+ "void",
172
+ "while",
173
+ "with",
174
+ "yield",
175
+ ]);
176
+ /**
177
+ * The JavaScript identifier a server or tool name is offered under.
178
+ *
179
+ * @since 1.0.0
180
+ * @category Naming
181
+ */
182
+ export const identifier = (name) => {
183
+ let id = name.replace(/[^A-Za-z0-9_$]/g, "_");
184
+ if (id === "" || /^[0-9]/.test(id))
185
+ id = `_${id}`;
186
+ return reservedWords.has(id) ? `${id}_` : id;
187
+ };
188
+ const toEntry = (name, entry) => {
189
+ switch (entry.type) {
190
+ case "unavailable":
191
+ return { name, error: entry.error };
192
+ case "stdio":
193
+ return {
194
+ name,
195
+ open: () => {
196
+ const transport = new StdioClientTransport({
197
+ command: entry.command,
198
+ args: [...(entry.args ?? [])],
199
+ env: { ...processEnv(), ...unwrapRecord(entry.env) },
200
+ cwd: NodePath.resolve(process.cwd(), entry.cwd ?? "."),
201
+ stderr: "pipe",
202
+ });
203
+ return {
204
+ transport: transport,
205
+ stderr: transport.stderr ?? undefined,
206
+ };
207
+ },
208
+ connectTimeout: entry.connectTimeout,
209
+ callTimeout: entry.callTimeout,
210
+ };
211
+ case "http":
212
+ return {
213
+ name,
214
+ open: () => ({
215
+ transport: new HttpTransport(new URL(entry.url), unwrapRecord(entry.headers)),
216
+ stderr: undefined,
217
+ }),
218
+ connectTimeout: entry.connectTimeout,
219
+ callTimeout: entry.callTimeout,
220
+ };
221
+ }
222
+ };
223
+ /**
224
+ * The SDK transport with its retries stopped by `close`. The SDK reads
225
+ * `maxRetries` when it schedules a retry, and a resumption GET that fails
226
+ * after `close` would otherwise schedule another one.
227
+ */
228
+ class HttpTransport extends StreamableHTTPClientTransport {
229
+ reconnection;
230
+ constructor(url, headers) {
231
+ // The SDK defaults.
232
+ const reconnection = {
233
+ initialReconnectionDelay: 1000,
234
+ maxReconnectionDelay: 30000,
235
+ reconnectionDelayGrowFactor: 1.5,
236
+ maxRetries: 2,
237
+ };
238
+ super(url, { requestInit: { headers }, reconnectionOptions: reconnection });
239
+ this.reconnection = reconnection;
240
+ }
241
+ close() {
242
+ this.reconnection.maxRetries = 0;
243
+ return super.close();
244
+ }
245
+ }
246
+ const processEnv = () => {
247
+ const env = {};
248
+ for (const [key, value] of Object.entries(process.env)) {
249
+ if (value !== undefined)
250
+ env[key] = value;
251
+ }
252
+ return env;
253
+ };
254
+ const unwrapRecord = (record) => Record.map(record ?? {}, Redacted.value);
255
+ const currentStatus = (server) => {
256
+ if (server._tag === "Failed")
257
+ return new Failed({ error: server.error });
258
+ return server.dropped === undefined
259
+ ? server.status
260
+ : new Failed({ error: `disconnected: ${server.dropped}` });
261
+ };
262
+ /** The first line of a failure, for the system prompt. */
263
+ const shortReason = (error) => error.split("\n")[0];
264
+ // The rolling stderr buffer kept until a stdio server is connected.
265
+ const stderrLines = 20;
266
+ const stderrChars = 2000;
267
+ const make = Effect.fnUntraced(function* (entries) {
268
+ const runFork = Effect.runForkWith(yield* Effect.context());
269
+ // Identifiers are claimed in config order, whether or not the server
270
+ // connects.
271
+ const owners = new Map();
272
+ const planned = entries.map((entry) => {
273
+ const id = identifier(entry.name);
274
+ const owner = owners.get(id);
275
+ if (owner !== undefined) {
276
+ return {
277
+ id,
278
+ entry: {
279
+ name: entry.name,
280
+ error: `identifier "${id}" is already used by server "${owner}"`,
281
+ },
282
+ };
283
+ }
284
+ owners.set(id, entry.name);
285
+ return { id, entry };
286
+ });
287
+ const servers = yield* Effect.forEach(planned, ({ id, entry }) => connect(entry, id, runFork), { concurrency: "unbounded" });
288
+ const connected = servers.filter((server) => server._tag === "Connected");
289
+ const searchTools = makeSearchTools(connected);
290
+ return McpServers.of({
291
+ status: Effect.sync(() => Object.fromEntries(servers.map((server) => [server.name, currentStatus(server)]))),
292
+ prompt: renderPrompt(servers),
293
+ dts: connected.length > 0 ? searchToolsDts : "",
294
+ handlers: (onImage) => {
295
+ const handlers = {};
296
+ if (connected.length === 0)
297
+ return handlers;
298
+ let images = 0;
299
+ const nextImage = () => ++images;
300
+ for (const server of connected) {
301
+ for (const tool of server.tools) {
302
+ handlers[`${server.id}.${tool.id}`] = callTool(server, tool, onImage, nextImage);
303
+ }
304
+ }
305
+ handlers["searchTools"] = searchTools;
306
+ return handlers;
307
+ },
308
+ });
309
+ });
310
+ const connect = Effect.fnUntraced(function* (entry, id, runFork) {
311
+ const fail = (error) => Effect.logWarning("MCP server failed").pipe(Effect.annotateLogs({ server: entry.name, error }), Effect.as({ _tag: "Failed", name: entry.name, id, error }));
312
+ if ("error" in entry)
313
+ return yield* fail(entry.error);
314
+ const opened = yield* Effect.result(Effect.try({ try: entry.open, catch: errorMessage }));
315
+ if (Result.isFailure(opened))
316
+ return yield* fail(opened.failure);
317
+ const { transport, stderr } = opened.success;
318
+ // stderr goes to the debug log. Until the server is connected, its tail is
319
+ // also kept for the failure message.
320
+ let buffer = [];
321
+ const stderrReader = yield* Effect.forkScoped(stderr === undefined
322
+ ? Effect.void
323
+ : Stream.fromAsyncIterable(stderr, errorMessage).pipe(Stream.decodeText, Stream.splitLines, Stream.runForEach((line) => {
324
+ if (buffer !== undefined) {
325
+ buffer.push(line);
326
+ while (buffer.length > stderrLines ||
327
+ (buffer.length > 1 && buffer.join("\n").length > stderrChars)) {
328
+ buffer.shift();
329
+ }
330
+ }
331
+ return Effect.logDebug(line).pipe(Effect.annotateLogs({ server: entry.name }));
332
+ }), Effect.ignore));
333
+ const client = new Client({ name: "clanka", version: "1.0.0" });
334
+ // Failed initialization starts close without awaiting it. Retain that
335
+ // promise so failure cleanup and scope finalization await the same shutdown.
336
+ const close = client.close.bind(client);
337
+ let closing;
338
+ client.close = () => (closing ??= close());
339
+ const logError = (error) => runFork(Effect.logDebug("MCP client error", error.message).pipe(Effect.annotateLogs({ server: entry.name })));
340
+ // The SDK client only has callback properties.
341
+ // oxlint-disable-next-line unicorn/prefer-add-event-listener
342
+ client.onerror = logError;
343
+ yield* Effect.addFinalizer(() => Effect.promise(() => client.close().catch(() => undefined)));
344
+ const connectTimeout = Duration.fromInputUnsafe(entry.connectTimeout ?? defaultConnectTimeout);
345
+ const timeout = Duration.toMillis(connectTimeout);
346
+ const listed = yield* Effect.tryPromise({
347
+ try: async (signal) => {
348
+ await client.connect(transport, { signal, timeout });
349
+ const tools = [];
350
+ let cursor = undefined;
351
+ do {
352
+ // Each page needs the cursor of the one before.
353
+ // oxlint-disable-next-line no-await-in-loop
354
+ const page = await client.listTools(cursor === undefined ? undefined : { cursor }, { signal, timeout });
355
+ tools.push(...page.tools);
356
+ cursor = page.nextCursor;
357
+ } while (cursor !== undefined);
358
+ client.cacheToolMetadata(tools);
359
+ return tools;
360
+ },
361
+ catch: errorMessage,
362
+ }).pipe(Effect.timeoutOrElse({
363
+ duration: connectTimeout,
364
+ orElse: () => Effect.fail(`connection timed out after ${timeout}ms`),
365
+ }), Effect.result);
366
+ if (Result.isFailure(listed)) {
367
+ // Closing ends the process; give its last stderr lines a moment to arrive.
368
+ yield* Effect.promise(() => client.close().catch(() => undefined));
369
+ yield* Fiber.join(stderrReader).pipe(Effect.timeoutOption("500 millis"));
370
+ const details = buffer.join("\n");
371
+ buffer = undefined;
372
+ return yield* fail(details === "" ? listed.failure : `${listed.failure}\n${details}`);
373
+ }
374
+ buffer = undefined;
375
+ const seen = new Set();
376
+ const tools = [];
377
+ for (const tool of listed.success) {
378
+ const toolId = identifier(tool.name);
379
+ if (seen.has(toolId)) {
380
+ yield* Effect.logWarning("MCP tool skipped").pipe(Effect.annotateLogs({
381
+ server: entry.name,
382
+ tool: tool.name,
383
+ reason: `identifier "${toolId}" is already used`,
384
+ }));
385
+ continue;
386
+ }
387
+ seen.add(toolId);
388
+ tools.push(yield* makeTool(entry.name, toolId, tool));
389
+ }
390
+ const server = {
391
+ _tag: "Connected",
392
+ name: entry.name,
393
+ id,
394
+ callTimeout: Duration.fromInputUnsafe(entry.callTimeout ?? defaultMcpCallTimeout),
395
+ client,
396
+ status: new Connected({
397
+ tools: listed.success.map((tool) => tool.name),
398
+ instructions: Option.fromNullishOr(client.getInstructions()),
399
+ }),
400
+ tools,
401
+ dropped: undefined,
402
+ };
403
+ // oxlint-disable-next-line unicorn/prefer-add-event-listener
404
+ client.onclose = () => {
405
+ server.dropped ??= "connection closed";
406
+ };
407
+ // oxlint-disable-next-line unicorn/prefer-add-event-listener
408
+ client.onerror = (error) => {
409
+ // A 404 on a request carrying the session ID means the server ended the
410
+ // session. The SDK only reports it, and nothing starts a new session.
411
+ if (error instanceof StreamableHTTPError &&
412
+ error.code === 404 &&
413
+ transport instanceof StreamableHTTPClientTransport &&
414
+ transport.sessionId !== undefined) {
415
+ server.dropped ??= error.message;
416
+ void client.close().catch(() => undefined);
417
+ }
418
+ logError(error);
419
+ };
420
+ return server;
421
+ });
422
+ // =============================================================================
423
+ // Tool declarations
424
+ // =============================================================================
425
+ const importSchema = (schema) => {
426
+ const json = schema;
427
+ const document = typeof json["$schema"] === "string" && json["$schema"].includes("draft-07")
428
+ ? JsonSchema.fromSchemaDraft07(json)
429
+ : JsonSchema.fromSchemaDraft2020_12(json);
430
+ return SchemaRepresentation.fromJsonSchemaDocument(document, {
431
+ patterns: "ignore",
432
+ });
433
+ };
434
+ const indentRest = (text, indent) => text.split("\n").join(`\n${indent}`);
435
+ const makeTool = Effect.fnUntraced(function* (serverName, id, tool) {
436
+ // A schema the importer rejects leaves the tool unvalidated, typed as a
437
+ // record with the raw schema in its doc comment.
438
+ const input = yield* Effect.try({
439
+ try: () => {
440
+ const schema = importSchema(tool.inputSchema);
441
+ const decodeParams = Schema.decodeUnknownEffect(schema);
442
+ return {
443
+ parameters: TypeBuilder.render(schema),
444
+ decode: Option.some((params) => decodeParams(params, { onExcessProperty: "error" }).pipe(Effect.mapError((error) => error.message))),
445
+ fallback: undefined,
446
+ };
447
+ },
448
+ catch: errorMessage,
449
+ }).pipe(Effect.catch((error) => Effect.logWarning("MCP tool schema not imported").pipe(Effect.annotateLogs({ server: serverName, tool: tool.name, error }), Effect.as({
450
+ parameters: "Record<string, unknown>",
451
+ decode: Option.none(),
452
+ fallback: `Input JSON Schema:\n${JSON.stringify(tool.inputSchema, null, 2)}`,
453
+ }))));
454
+ const { parameters, decode, fallback } = input;
455
+ const outputSchema = tool.outputSchema;
456
+ const result = outputSchema === undefined
457
+ ? "string"
458
+ : yield* Effect.try(() => TypeBuilder.render(importSchema(outputSchema), {
459
+ omitUnknownIndexSignatures: true,
460
+ })).pipe(Effect.orElseSucceed(() => "unknown"));
461
+ const docs = [tool.description, fallback].filter((text) => text !== undefined && text !== "");
462
+ const signature = ` function ${id}(options: ${indentRest(parameters, " ")}): Promise<${indentRest(result, " ")}>`;
463
+ const parameterNames = Object.keys(tool.inputSchema.properties ?? {});
464
+ return {
465
+ id,
466
+ name: tool.name,
467
+ description: tool.description,
468
+ decode,
469
+ structured: tool.outputSchema !== undefined,
470
+ dts: docs.length === 0
471
+ ? signature
472
+ : `${TypeBuilder.renderJsDoc(docs.join("\n\n"), " ")}\n${signature}`,
473
+ search: {
474
+ names: [tool.name.toLowerCase(), id.toLowerCase()],
475
+ nameTokens: new Set([...tokens(tool.name), ...tokens(id)]),
476
+ parameterTokens: new Set(parameterNames.flatMap(tokens)),
477
+ description: (tool.description ?? "").toLowerCase(),
478
+ },
479
+ };
480
+ });
481
+ // =============================================================================
482
+ // Discovery
483
+ // =============================================================================
484
+ const searchToolsDts = `/**
485
+ * List every tool on a server:
486
+ *
487
+ * console.log(await searchTools({ server: "github" }))
488
+ *
489
+ * Search all servers by keyword, for at most 10 tools:
490
+ *
491
+ * console.log(await searchTools({ query: "create issue" }))
492
+ *
493
+ * Both return the tools' type declarations. Print them before calling a tool.
494
+ * A \`query\` with a \`server\` searches only that server.
495
+ */
496
+ declare function searchTools(options: {
497
+ readonly query?: string;
498
+ readonly server?: string;
499
+ }): Promise<string>`;
500
+ const SearchParams = Schema.Struct({
501
+ query: Schema.optionalKey(Schema.String),
502
+ server: Schema.optionalKey(Schema.String),
503
+ });
504
+ // The most tools a query returns. Listing a server returns all of them.
505
+ const maxResults = 10;
506
+ const tokens = (text) => text
507
+ .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
508
+ .toLowerCase()
509
+ .split(/[^a-z0-9]+/)
510
+ .filter((token) => token !== "");
511
+ const score = (tool, query) => {
512
+ let total = tool.search.names.includes(query.text) ? 1000 : 0;
513
+ for (const token of query.tokens) {
514
+ if (tool.search.nameTokens.has(token))
515
+ total += 10;
516
+ else if (tool.search.names.some((name) => name.includes(token)))
517
+ total += 5;
518
+ if (tool.search.parameterTokens.has(token))
519
+ total += 3;
520
+ if (tool.search.description.includes(token))
521
+ total += 2;
522
+ }
523
+ return total;
524
+ };
525
+ const makeSearchTools = (servers) => {
526
+ const decode = Schema.decodeUnknownEffect(SearchParams);
527
+ const serverList = servers.map((server) => server.id).join(", ");
528
+ const counts = servers
529
+ .map((server) => `${server.id} (${server.status.tools.length} tools)`)
530
+ .join(", ");
531
+ return Effect.fnUntraced(function* (params) {
532
+ const options = yield* decode(params ?? {}).pipe(Effect.mapError((error) => `searchTools: ${error.message}`));
533
+ const query = options.query?.trim() ?? "";
534
+ let candidates = servers;
535
+ if (options.server !== undefined) {
536
+ const server = servers.find((server) => server.id === options.server || server.name === options.server);
537
+ if (server === undefined) {
538
+ return yield* Effect.fail(`searchTools: unknown MCP server "${options.server}". Servers: ${serverList}`);
539
+ }
540
+ if (query === "")
541
+ return renderTools([[server, server.tools]]);
542
+ candidates = [server];
543
+ }
544
+ else if (query === "") {
545
+ return yield* Effect.fail(`searchTools: pass a query or a server. Servers: ${serverList}`);
546
+ }
547
+ const terms = { text: query.toLowerCase(), tokens: tokens(query) };
548
+ const ranked = candidates
549
+ .flatMap((server) => server.tools.map((tool) => ({
550
+ server,
551
+ tool,
552
+ score: score(tool, terms),
553
+ })))
554
+ .filter((match) => match.score > 0)
555
+ .toSorted((a, b) => b.score - a.score)
556
+ .slice(0, maxResults);
557
+ if (ranked.length === 0) {
558
+ return `No MCP tools match "${query}". Servers: ${counts}.`;
559
+ }
560
+ const groups = new Map();
561
+ for (const { server, tool } of ranked) {
562
+ const group = groups.get(server);
563
+ if (group === undefined)
564
+ groups.set(server, [tool]);
565
+ else
566
+ group.push(tool);
567
+ }
568
+ return renderTools([...groups]);
569
+ });
570
+ };
571
+ const renderTools = (groups) => groups
572
+ .map(([server, tools]) => `declare namespace mcp.${server.id} {\n${tools.map((tool) => tool.dts).join("\n\n")}\n}`)
573
+ .join("\n\n");
574
+ // =============================================================================
575
+ // Calls
576
+ // =============================================================================
577
+ const callTool = (server, tool, onImage, nextImage) => {
578
+ const name = `${server.id}.${tool.id}`;
579
+ const prefix = `mcp.${name}:`;
580
+ const timeout = Duration.toMillis(server.callTimeout);
581
+ const timedOut = `${prefix} timed out after ${timeout}ms`;
582
+ return Effect.fnUntraced(function* (params) {
583
+ if (server.dropped !== undefined) {
584
+ return yield* Effect.fail(`${prefix} MCP server "${server.name}" is not connected: ${server.dropped}`);
585
+ }
586
+ const args = params ?? {};
587
+ if (Option.isSome(tool.decode)) {
588
+ yield* tool.decode
589
+ .value(args)
590
+ .pipe(Effect.mapError((message) => `${prefix} ${message}`));
591
+ }
592
+ const result = (yield* Effect.tryPromise({
593
+ try: (signal) => server.client.callTool({ name: tool.name, arguments: args }, undefined, { signal, timeout }),
594
+ catch: (error) => error instanceof McpError && error.code === ErrorCode.RequestTimeout
595
+ ? timedOut
596
+ : `${prefix} ${errorMessage(error)}`,
597
+ }).pipe(Effect.timeoutOrElse({
598
+ duration: server.callTimeout,
599
+ orElse: () => Effect.fail(timedOut),
600
+ })));
601
+ if (result.isError !== true && tool.structured) {
602
+ return result.structuredContent;
603
+ }
604
+ const text = yield* renderContent(result.content ?? [], {
605
+ name,
606
+ onImage,
607
+ nextImage,
608
+ });
609
+ if (result.isError === true) {
610
+ return yield* Effect.fail(`${prefix} ${text === "" ? "tool returned an error with no message" : text}`);
611
+ }
612
+ return text;
613
+ });
614
+ };
615
+ const extensions = {
616
+ "image/png": "png",
617
+ "image/jpeg": "jpg",
618
+ "image/gif": "gif",
619
+ "image/webp": "webp",
620
+ };
621
+ const renderContent = Effect.fnUntraced(function* (content, options) {
622
+ const parts = [];
623
+ for (const block of content) {
624
+ switch (block.type) {
625
+ case "text":
626
+ parts.push(block.text);
627
+ break;
628
+ case "image": {
629
+ if (!Image.isImageMediaType(block.mimeType)) {
630
+ parts.push(`[Image omitted (${block.mimeType}): unsupported type]`);
631
+ break;
632
+ }
633
+ const decoded = Base64.decode(block.data);
634
+ if (Result.isFailure(decoded)) {
635
+ parts.push(`[Image omitted (${block.mimeType}): invalid base64 data]`);
636
+ break;
637
+ }
638
+ const bytes = decoded.success;
639
+ const prepared = yield* Effect.exit(Image.prepare({
640
+ data: bytes,
641
+ mediaType: Option.getOrElse(Image.mediaTypeFromBytes(bytes), () => block.mimeType),
642
+ }));
643
+ if (Exit.isFailure(prepared)) {
644
+ const error = Option.match(Exit.findErrorOption(prepared), {
645
+ onNone: () => "the image could not be read",
646
+ onSome: (error) => error.message,
647
+ });
648
+ parts.push(`[Image omitted (${block.mimeType}): ${error}]`);
649
+ break;
650
+ }
651
+ const fileName = `${options.name}-${options.nextImage()}.${extensions[prepared.value.mediaType]}`;
652
+ yield* options.onImage({
653
+ fileName,
654
+ mediaType: prepared.value.mediaType,
655
+ data: prepared.value.data,
656
+ });
657
+ parts.push(`[Image attached: ${fileName}]`);
658
+ break;
659
+ }
660
+ case "audio":
661
+ parts.push(`[Audio omitted (${block.mimeType})]`);
662
+ break;
663
+ case "resource":
664
+ parts.push("text" in block.resource && typeof block.resource.text === "string"
665
+ ? `[Resource ${block.resource.uri}]\n${block.resource.text}`
666
+ : `[Binary resource omitted: ${block.resource.uri} (${block.resource.mimeType ?? "unknown type"})]`);
667
+ break;
668
+ case "resource_link":
669
+ parts.push(`[Resource link: ${block.name} ${block.uri}]`);
670
+ break;
671
+ }
672
+ }
673
+ return parts.join("\n");
674
+ });
675
+ // =============================================================================
676
+ // System prompt
677
+ // =============================================================================
678
+ const maxInstructions = 2000;
679
+ const renderPrompt = (servers) => {
680
+ if (servers.length === 0)
681
+ return "";
682
+ const anyConnected = servers.some((server) => server._tag === "Connected");
683
+ const lines = servers.map((server) => {
684
+ if (server._tag === "Failed") {
685
+ return `- ${server.name}: failed to connect: ${shortReason(server.error)}`;
686
+ }
687
+ const header = `- ${server.id} (${server.status.tools.length} tools). List them with \`searchTools({ server: ${JSON.stringify(server.id)} })\`.`;
688
+ return Option.match(server.status.instructions, {
689
+ onNone: () => header,
690
+ onSome: (instructions) => {
691
+ const text = instructions.length > maxInstructions
692
+ ? `${instructions.slice(0, maxInstructions)}\n[instructions truncated]`
693
+ : instructions;
694
+ return `${header} Its instructions:\n\n${text.trim()}\n`;
695
+ },
696
+ });
697
+ });
698
+ return `# MCP servers
699
+ ${anyConnected
700
+ ? `
701
+ MCP tools are called as \`mcp.<server>.<tool>(options)\`. Their types are not listed above: list a server's tools with \`searchTools({ server })\`, or search across all servers by keyword with \`searchTools({ query })\`, and print the declarations before calling a tool. Images in their results are attached to the next message.
702
+ `
703
+ : ""}
704
+ ${lines.join("\n")}`;
705
+ };
706
+ const errorMessage = (error) => error instanceof Error ? error.message : String(error);
707
+ //# sourceMappingURL=McpServers.js.map