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,1072 @@
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 type { Readable } from "node:stream"
12
+ import { Client } from "@modelcontextprotocol/sdk/client/index.js"
13
+ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
14
+ import {
15
+ StreamableHTTPClientTransport,
16
+ StreamableHTTPError,
17
+ } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
18
+ import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js"
19
+ import {
20
+ type CallToolResult,
21
+ ErrorCode,
22
+ McpError,
23
+ type Tool as McpTool,
24
+ } from "@modelcontextprotocol/sdk/types.js"
25
+ import * as Context from "effect/Context"
26
+ import * as Data from "effect/Data"
27
+ import * as Duration from "effect/Duration"
28
+ import * as Effect from "effect/Effect"
29
+ import * as Base64 from "effect/encoding/Base64"
30
+ import * as Exit from "effect/Exit"
31
+ import * as Fiber from "effect/Fiber"
32
+ import * as JsonSchema from "effect/JsonSchema"
33
+ import * as Layer from "effect/Layer"
34
+ import * as Option from "effect/Option"
35
+ import * as Record from "effect/Record"
36
+ import * as Redacted from "effect/Redacted"
37
+ import * as Result from "effect/Result"
38
+ import * as Schema from "effect/Schema"
39
+ import * as SchemaRepresentation from "effect/SchemaRepresentation"
40
+ import * as Stream from "effect/Stream"
41
+ import type { LoopToolHandlers } from "./AgentExecutor.ts"
42
+ import { defaultMcpCallTimeout, type ImageAttachment } from "./AgentTools.ts"
43
+ import * as Image from "./Image.ts"
44
+ import * as TypeBuilder from "./TypeBuilder.ts"
45
+
46
+ // =============================================================================
47
+ // Config
48
+ // =============================================================================
49
+
50
+ const Timeout = Schema.Duration
51
+
52
+ /**
53
+ * A server started as a child process and spoken to over stdio.
54
+ *
55
+ * @since 1.0.0
56
+ * @category Config
57
+ */
58
+ export const StdioServerConfig = Schema.Struct({
59
+ type: Schema.Literal("stdio"),
60
+ command: Schema.String,
61
+ args: Schema.optionalKey(Schema.Array(Schema.String)),
62
+ env: Schema.optionalKey(
63
+ Schema.Record(Schema.String, Schema.RedactedFromValue(Schema.String)),
64
+ ),
65
+ /**
66
+ * Resolved against the process cwd. Defaults to the process cwd.
67
+ */
68
+ cwd: Schema.optionalKey(Schema.String),
69
+ connectTimeout: Schema.optionalKey(Timeout),
70
+ callTimeout: Schema.optionalKey(Timeout),
71
+ })
72
+
73
+ /**
74
+ * A server reached over streamable HTTP.
75
+ *
76
+ * @since 1.0.0
77
+ * @category Config
78
+ */
79
+ export const HttpServerConfig = Schema.Struct({
80
+ type: Schema.Literal("http"),
81
+ url: Schema.String,
82
+ headers: Schema.optionalKey(
83
+ Schema.Record(Schema.String, Schema.RedactedFromValue(Schema.String)),
84
+ ),
85
+ connectTimeout: Schema.optionalKey(Timeout),
86
+ callTimeout: Schema.optionalKey(Timeout),
87
+ })
88
+
89
+ /**
90
+ * @since 1.0.0
91
+ * @category Config
92
+ */
93
+ export const McpServerConfig = Schema.Union([
94
+ StdioServerConfig,
95
+ HttpServerConfig,
96
+ ])
97
+
98
+ /**
99
+ * @since 1.0.0
100
+ * @category Config
101
+ */
102
+ export type McpServerConfig = typeof McpServerConfig.Type
103
+
104
+ /**
105
+ * A server that cannot be started, such as one whose configuration refers to
106
+ * a missing environment variable. It is reported as `Failed` with `error`.
107
+ *
108
+ * @since 1.0.0
109
+ * @category Config
110
+ */
111
+ export interface UnavailableServer {
112
+ readonly type: "unavailable"
113
+ readonly error: string
114
+ }
115
+
116
+ /**
117
+ * @since 1.0.0
118
+ * @category Config
119
+ */
120
+ export type ServerEntry = McpServerConfig | UnavailableServer
121
+
122
+ /**
123
+ * A server reached through a transport the caller builds. `transport` is
124
+ * called once, when the layer is built.
125
+ *
126
+ * @since 1.0.0
127
+ * @category Config
128
+ */
129
+ export interface TransportServer {
130
+ readonly transport: () => Transport
131
+ readonly connectTimeout?: Duration.Input | undefined
132
+ readonly callTimeout?: Duration.Input | undefined
133
+ }
134
+
135
+ const defaultConnectTimeout = Duration.seconds(30)
136
+
137
+ // =============================================================================
138
+ // Status
139
+ // =============================================================================
140
+
141
+ /**
142
+ * @since 1.0.0
143
+ * @category Status
144
+ */
145
+ export class Connected extends Data.TaggedClass("Connected")<{
146
+ /**
147
+ * The names of every tool the server listed.
148
+ */
149
+ readonly tools: ReadonlyArray<string>
150
+ readonly instructions: Option.Option<string>
151
+ }> {}
152
+
153
+ /**
154
+ * @since 1.0.0
155
+ * @category Status
156
+ */
157
+ export class Failed extends Data.TaggedClass("Failed")<{
158
+ readonly error: string
159
+ }> {}
160
+
161
+ /**
162
+ * @since 1.0.0
163
+ * @category Status
164
+ */
165
+ export type ServerStatus = Connected | Failed
166
+
167
+ // =============================================================================
168
+ // Service
169
+ // =============================================================================
170
+
171
+ /**
172
+ * @since 1.0.0
173
+ * @category Services
174
+ */
175
+ export class McpServers extends Context.Service<
176
+ McpServers,
177
+ {
178
+ /**
179
+ * Each server by its configured name.
180
+ */
181
+ readonly status: Effect.Effect<Readonly<Record<string, ServerStatus>>>
182
+ /**
183
+ * The system prompt section listing the servers, or `""` when none is
184
+ * configured.
185
+ */
186
+ readonly prompt: string
187
+ /**
188
+ * The declaration of `searchTools`, or `""` when no server is connected.
189
+ */
190
+ readonly dts: string
191
+ /**
192
+ * The loop-side handlers: one per tool, keyed `"<server>.<tool>"`, and
193
+ * `searchTools`. Images in results go to `onImage`.
194
+ */
195
+ readonly handlers: (
196
+ onImage: (image: ImageAttachment) => Effect.Effect<void>,
197
+ ) => LoopToolHandlers
198
+ }
199
+ >()("clanka/McpServers") {}
200
+
201
+ /**
202
+ * Connects every server when built and closes them with its scope. A server
203
+ * that cannot connect is `Failed`; building the layer never fails.
204
+ *
205
+ * @since 1.0.0
206
+ * @category Layers
207
+ */
208
+ export const layer = (
209
+ config: Readonly<Record<string, ServerEntry>>,
210
+ ): Layer.Layer<McpServers> =>
211
+ fromEntries(
212
+ Object.entries(config).map(([name, entry]) => toEntry(name, entry)),
213
+ )
214
+
215
+ /**
216
+ * Like `layer`, with transports built by the caller.
217
+ *
218
+ * @since 1.0.0
219
+ * @category Layers
220
+ */
221
+ export const layerTransports = (
222
+ servers: Readonly<Record<string, TransportServer>>,
223
+ ): Layer.Layer<McpServers> =>
224
+ fromEntries(
225
+ Object.entries(servers).map(([name, server]) => ({
226
+ name,
227
+ open: () => ({ transport: server.transport(), stderr: undefined }),
228
+ connectTimeout: server.connectTimeout,
229
+ callTimeout: server.callTimeout,
230
+ })),
231
+ )
232
+
233
+ const fromEntries = (entries: ReadonlyArray<Entry>): Layer.Layer<McpServers> =>
234
+ Layer.effect(McpServers, make(entries))
235
+
236
+ // =============================================================================
237
+ // Naming
238
+ // =============================================================================
239
+
240
+ const reservedWords = new Set([
241
+ "arguments",
242
+ "await",
243
+ "break",
244
+ "case",
245
+ "catch",
246
+ "class",
247
+ "const",
248
+ "continue",
249
+ "debugger",
250
+ "default",
251
+ "delete",
252
+ "do",
253
+ "else",
254
+ "enum",
255
+ "eval",
256
+ "export",
257
+ "extends",
258
+ "false",
259
+ "finally",
260
+ "for",
261
+ "function",
262
+ "if",
263
+ "implements",
264
+ "import",
265
+ "in",
266
+ "instanceof",
267
+ "interface",
268
+ "let",
269
+ "new",
270
+ "null",
271
+ "package",
272
+ "private",
273
+ "protected",
274
+ "public",
275
+ "return",
276
+ "static",
277
+ "super",
278
+ "switch",
279
+ "this",
280
+ "throw",
281
+ "true",
282
+ "try",
283
+ "typeof",
284
+ "var",
285
+ "void",
286
+ "while",
287
+ "with",
288
+ "yield",
289
+ ])
290
+
291
+ /**
292
+ * The JavaScript identifier a server or tool name is offered under.
293
+ *
294
+ * @since 1.0.0
295
+ * @category Naming
296
+ */
297
+ export const identifier = (name: string): string => {
298
+ let id = name.replace(/[^A-Za-z0-9_$]/g, "_")
299
+ if (id === "" || /^[0-9]/.test(id)) id = `_${id}`
300
+ return reservedWords.has(id) ? `${id}_` : id
301
+ }
302
+
303
+ // =============================================================================
304
+ // Connecting
305
+ // =============================================================================
306
+
307
+ interface Opened {
308
+ readonly transport: Transport
309
+ readonly stderr: Readable | undefined
310
+ }
311
+
312
+ type Entry =
313
+ | {
314
+ readonly name: string
315
+ readonly open: () => Opened
316
+ readonly connectTimeout?: Duration.Input | undefined
317
+ readonly callTimeout?: Duration.Input | undefined
318
+ }
319
+ | { readonly name: string; readonly error: string }
320
+
321
+ const toEntry = (name: string, entry: ServerEntry): Entry => {
322
+ switch (entry.type) {
323
+ case "unavailable":
324
+ return { name, error: entry.error }
325
+ case "stdio":
326
+ return {
327
+ name,
328
+ open: () => {
329
+ const transport = new StdioClientTransport({
330
+ command: entry.command,
331
+ args: [...(entry.args ?? [])],
332
+ env: { ...processEnv(), ...unwrapRecord(entry.env) },
333
+ cwd: NodePath.resolve(process.cwd(), entry.cwd ?? "."),
334
+ stderr: "pipe",
335
+ })
336
+ return {
337
+ transport: transport as Transport,
338
+ stderr: (transport.stderr as Readable | null) ?? undefined,
339
+ }
340
+ },
341
+ connectTimeout: entry.connectTimeout,
342
+ callTimeout: entry.callTimeout,
343
+ }
344
+ case "http":
345
+ return {
346
+ name,
347
+ open: () => ({
348
+ transport: new HttpTransport(
349
+ new URL(entry.url),
350
+ unwrapRecord(entry.headers),
351
+ ) as Transport,
352
+ stderr: undefined,
353
+ }),
354
+ connectTimeout: entry.connectTimeout,
355
+ callTimeout: entry.callTimeout,
356
+ }
357
+ }
358
+ }
359
+
360
+ /**
361
+ * The SDK transport with its retries stopped by `close`. The SDK reads
362
+ * `maxRetries` when it schedules a retry, and a resumption GET that fails
363
+ * after `close` would otherwise schedule another one.
364
+ */
365
+ class HttpTransport extends StreamableHTTPClientTransport {
366
+ readonly reconnection: { maxRetries: number }
367
+
368
+ constructor(url: URL, headers: Record<string, string>) {
369
+ // The SDK defaults.
370
+ const reconnection = {
371
+ initialReconnectionDelay: 1000,
372
+ maxReconnectionDelay: 30000,
373
+ reconnectionDelayGrowFactor: 1.5,
374
+ maxRetries: 2,
375
+ }
376
+ super(url, { requestInit: { headers }, reconnectionOptions: reconnection })
377
+ this.reconnection = reconnection
378
+ }
379
+
380
+ override close(): Promise<void> {
381
+ this.reconnection.maxRetries = 0
382
+ return super.close()
383
+ }
384
+ }
385
+
386
+ const processEnv = (): Record<string, string> => {
387
+ const env: Record<string, string> = {}
388
+ for (const [key, value] of Object.entries(process.env)) {
389
+ if (value !== undefined) env[key] = value
390
+ }
391
+ return env
392
+ }
393
+
394
+ const unwrapRecord = (
395
+ record: Readonly<Record<string, Redacted.Redacted<string>>> | undefined,
396
+ ): Record<string, string> => Record.map(record ?? {}, Redacted.value)
397
+
398
+ interface ToolEntry {
399
+ readonly id: string
400
+ /** The name the server knows the tool by. */
401
+ readonly name: string
402
+ readonly description: string | undefined
403
+ readonly decode: Option.Option<
404
+ (params: unknown) => Effect.Effect<unknown, string>
405
+ >
406
+ /** Whether the result is `structuredContent`. */
407
+ readonly structured: boolean
408
+ readonly dts: string
409
+ readonly search: {
410
+ readonly names: ReadonlyArray<string>
411
+ readonly nameTokens: ReadonlySet<string>
412
+ readonly parameterTokens: ReadonlySet<string>
413
+ readonly description: string
414
+ }
415
+ }
416
+
417
+ interface ConnectedServer {
418
+ readonly _tag: "Connected"
419
+ readonly name: string
420
+ readonly id: string
421
+ readonly callTimeout: Duration.Duration
422
+ readonly client: Client
423
+ readonly status: Connected
424
+ readonly tools: ReadonlyArray<ToolEntry>
425
+ /** Why the connection dropped, once it has. Nothing reconnects. */
426
+ dropped: string | undefined
427
+ }
428
+
429
+ interface FailedServer {
430
+ readonly _tag: "Failed"
431
+ readonly name: string
432
+ readonly id: string
433
+ /** The reason, followed by the stderr tail when there is one. */
434
+ readonly error: string
435
+ }
436
+
437
+ type ServerState = ConnectedServer | FailedServer
438
+
439
+ const currentStatus = (server: ServerState): ServerStatus => {
440
+ if (server._tag === "Failed") return new Failed({ error: server.error })
441
+ return server.dropped === undefined
442
+ ? server.status
443
+ : new Failed({ error: `disconnected: ${server.dropped}` })
444
+ }
445
+
446
+ /** The first line of a failure, for the system prompt. */
447
+ const shortReason = (error: string): string => error.split("\n")[0]!
448
+
449
+ // The rolling stderr buffer kept until a stdio server is connected.
450
+ const stderrLines = 20
451
+ const stderrChars = 2000
452
+
453
+ const make = Effect.fnUntraced(function* (entries: ReadonlyArray<Entry>) {
454
+ const runFork = Effect.runForkWith(yield* Effect.context<never>())
455
+
456
+ // Identifiers are claimed in config order, whether or not the server
457
+ // connects.
458
+ const owners = new Map<string, string>()
459
+ const planned = entries.map((entry) => {
460
+ const id = identifier(entry.name)
461
+ const owner = owners.get(id)
462
+ if (owner !== undefined) {
463
+ return {
464
+ id,
465
+ entry: {
466
+ name: entry.name,
467
+ error: `identifier "${id}" is already used by server "${owner}"`,
468
+ },
469
+ }
470
+ }
471
+ owners.set(id, entry.name)
472
+ return { id, entry }
473
+ })
474
+
475
+ const servers = yield* Effect.forEach(
476
+ planned,
477
+ ({ id, entry }) => connect(entry, id, runFork),
478
+ { concurrency: "unbounded" },
479
+ )
480
+
481
+ const connected = servers.filter(
482
+ (server): server is ConnectedServer => server._tag === "Connected",
483
+ )
484
+ const searchTools = makeSearchTools(connected)
485
+
486
+ return McpServers.of({
487
+ status: Effect.sync(() =>
488
+ Object.fromEntries(
489
+ servers.map((server) => [server.name, currentStatus(server)]),
490
+ ),
491
+ ),
492
+ prompt: renderPrompt(servers),
493
+ dts: connected.length > 0 ? searchToolsDts : "",
494
+ handlers: (onImage) => {
495
+ const handlers: Record<
496
+ string,
497
+ (params: unknown) => Effect.Effect<unknown, string>
498
+ > = {}
499
+ if (connected.length === 0) return handlers
500
+ let images = 0
501
+ const nextImage = () => ++images
502
+ for (const server of connected) {
503
+ for (const tool of server.tools) {
504
+ handlers[`${server.id}.${tool.id}`] = callTool(
505
+ server,
506
+ tool,
507
+ onImage,
508
+ nextImage,
509
+ )
510
+ }
511
+ }
512
+ handlers["searchTools"] = searchTools
513
+ return handlers
514
+ },
515
+ })
516
+ })
517
+
518
+ const connect = Effect.fnUntraced(function* (
519
+ entry: Entry,
520
+ id: string,
521
+ runFork: <A, E>(effect: Effect.Effect<A, E>) => unknown,
522
+ ) {
523
+ const fail = (error: string) =>
524
+ Effect.logWarning("MCP server failed").pipe(
525
+ Effect.annotateLogs({ server: entry.name, error }),
526
+ Effect.as<ServerState>({ _tag: "Failed", name: entry.name, id, error }),
527
+ )
528
+
529
+ if ("error" in entry) return yield* fail(entry.error)
530
+
531
+ const opened = yield* Effect.result(
532
+ Effect.try({ try: entry.open, catch: errorMessage }),
533
+ )
534
+ if (Result.isFailure(opened)) return yield* fail(opened.failure)
535
+ const { transport, stderr } = opened.success
536
+
537
+ // stderr goes to the debug log. Until the server is connected, its tail is
538
+ // also kept for the failure message.
539
+ let buffer: Array<string> | undefined = []
540
+ const stderrReader = yield* Effect.forkScoped(
541
+ stderr === undefined
542
+ ? Effect.void
543
+ : Stream.fromAsyncIterable(
544
+ stderr as AsyncIterable<Uint8Array>,
545
+ errorMessage,
546
+ ).pipe(
547
+ Stream.decodeText,
548
+ Stream.splitLines,
549
+ Stream.runForEach((line) => {
550
+ if (buffer !== undefined) {
551
+ buffer.push(line)
552
+ while (
553
+ buffer.length > stderrLines ||
554
+ (buffer.length > 1 && buffer.join("\n").length > stderrChars)
555
+ ) {
556
+ buffer.shift()
557
+ }
558
+ }
559
+ return Effect.logDebug(line).pipe(
560
+ Effect.annotateLogs({ server: entry.name }),
561
+ )
562
+ }),
563
+ Effect.ignore,
564
+ ),
565
+ )
566
+
567
+ const client = new Client({ name: "clanka", version: "1.0.0" })
568
+ // Failed initialization starts close without awaiting it. Retain that
569
+ // promise so failure cleanup and scope finalization await the same shutdown.
570
+ const close = client.close.bind(client)
571
+ let closing: Promise<void> | undefined
572
+ client.close = () => (closing ??= close())
573
+ const logError = (error: Error) =>
574
+ runFork(
575
+ Effect.logDebug("MCP client error", error.message).pipe(
576
+ Effect.annotateLogs({ server: entry.name }),
577
+ ),
578
+ )
579
+ // The SDK client only has callback properties.
580
+ // oxlint-disable-next-line unicorn/prefer-add-event-listener
581
+ client.onerror = logError
582
+ yield* Effect.addFinalizer(() =>
583
+ Effect.promise(() => client.close().catch(() => undefined)),
584
+ )
585
+
586
+ const connectTimeout = Duration.fromInputUnsafe(
587
+ entry.connectTimeout ?? defaultConnectTimeout,
588
+ )
589
+ const timeout = Duration.toMillis(connectTimeout)
590
+ const listed = yield* Effect.tryPromise({
591
+ try: async (signal) => {
592
+ await client.connect(transport, { signal, timeout })
593
+ const tools: Array<McpTool> = []
594
+ let cursor: string | undefined = undefined
595
+ do {
596
+ // Each page needs the cursor of the one before.
597
+ // oxlint-disable-next-line no-await-in-loop
598
+ const page = await client.listTools(
599
+ cursor === undefined ? undefined : { cursor },
600
+ { signal, timeout },
601
+ )
602
+ tools.push(...page.tools)
603
+ cursor = page.nextCursor
604
+ } while (cursor !== undefined)
605
+ // Every `listTools` call replaces the output validators with those of
606
+ // its own page.
607
+ ;(
608
+ client as unknown as {
609
+ cacheToolMetadata: (tools: ReadonlyArray<McpTool>) => void
610
+ }
611
+ ).cacheToolMetadata(tools)
612
+ return tools
613
+ },
614
+ catch: errorMessage,
615
+ }).pipe(
616
+ Effect.timeoutOrElse({
617
+ duration: connectTimeout,
618
+ orElse: () => Effect.fail(`connection timed out after ${timeout}ms`),
619
+ }),
620
+ Effect.result,
621
+ )
622
+
623
+ if (Result.isFailure(listed)) {
624
+ // Closing ends the process; give its last stderr lines a moment to arrive.
625
+ yield* Effect.promise(() => client.close().catch(() => undefined))
626
+ yield* Fiber.join(stderrReader).pipe(Effect.timeoutOption("500 millis"))
627
+ const details = buffer.join("\n")
628
+ buffer = undefined
629
+ return yield* fail(
630
+ details === "" ? listed.failure : `${listed.failure}\n${details}`,
631
+ )
632
+ }
633
+ buffer = undefined
634
+
635
+ const seen = new Set<string>()
636
+ const tools: Array<ToolEntry> = []
637
+ for (const tool of listed.success) {
638
+ const toolId = identifier(tool.name)
639
+ if (seen.has(toolId)) {
640
+ yield* Effect.logWarning("MCP tool skipped").pipe(
641
+ Effect.annotateLogs({
642
+ server: entry.name,
643
+ tool: tool.name,
644
+ reason: `identifier "${toolId}" is already used`,
645
+ }),
646
+ )
647
+ continue
648
+ }
649
+ seen.add(toolId)
650
+ tools.push(yield* makeTool(entry.name, toolId, tool))
651
+ }
652
+
653
+ const server: ConnectedServer = {
654
+ _tag: "Connected",
655
+ name: entry.name,
656
+ id,
657
+ callTimeout: Duration.fromInputUnsafe(
658
+ entry.callTimeout ?? defaultMcpCallTimeout,
659
+ ),
660
+ client,
661
+ status: new Connected({
662
+ tools: listed.success.map((tool) => tool.name),
663
+ instructions: Option.fromNullishOr(client.getInstructions()),
664
+ }),
665
+ tools,
666
+ dropped: undefined,
667
+ }
668
+ // oxlint-disable-next-line unicorn/prefer-add-event-listener
669
+ client.onclose = () => {
670
+ server.dropped ??= "connection closed"
671
+ }
672
+ // oxlint-disable-next-line unicorn/prefer-add-event-listener
673
+ client.onerror = (error) => {
674
+ // A 404 on a request carrying the session ID means the server ended the
675
+ // session. The SDK only reports it, and nothing starts a new session.
676
+ if (
677
+ error instanceof StreamableHTTPError &&
678
+ error.code === 404 &&
679
+ transport instanceof StreamableHTTPClientTransport &&
680
+ transport.sessionId !== undefined
681
+ ) {
682
+ server.dropped ??= error.message
683
+ void client.close().catch(() => undefined)
684
+ }
685
+ logError(error)
686
+ }
687
+ return server
688
+ })
689
+
690
+ // =============================================================================
691
+ // Tool declarations
692
+ // =============================================================================
693
+
694
+ const importSchema = (schema: object): Schema.Top => {
695
+ const json = schema as JsonSchema.JsonSchema
696
+ const document =
697
+ typeof json["$schema"] === "string" && json["$schema"].includes("draft-07")
698
+ ? JsonSchema.fromSchemaDraft07(json)
699
+ : JsonSchema.fromSchemaDraft2020_12(json)
700
+ return SchemaRepresentation.fromJsonSchemaDocument(document, {
701
+ patterns: "ignore",
702
+ })
703
+ }
704
+
705
+ const indentRest = (text: string, indent: string): string =>
706
+ text.split("\n").join(`\n${indent}`)
707
+
708
+ const makeTool = Effect.fnUntraced(function* (
709
+ serverName: string,
710
+ id: string,
711
+ tool: McpTool,
712
+ ) {
713
+ // A schema the importer rejects leaves the tool unvalidated, typed as a
714
+ // record with the raw schema in its doc comment.
715
+ const input = yield* Effect.try({
716
+ try: () => {
717
+ const schema = importSchema(tool.inputSchema) as Schema.Codec<unknown>
718
+ const decodeParams = Schema.decodeUnknownEffect(schema)
719
+ return {
720
+ parameters: TypeBuilder.render(schema),
721
+ decode: Option.some((params: unknown) =>
722
+ decodeParams(params, { onExcessProperty: "error" }).pipe(
723
+ Effect.mapError((error) => error.message),
724
+ ),
725
+ ),
726
+ fallback: undefined,
727
+ }
728
+ },
729
+ catch: errorMessage,
730
+ }).pipe(
731
+ Effect.catch((error) =>
732
+ Effect.logWarning("MCP tool schema not imported").pipe(
733
+ Effect.annotateLogs({ server: serverName, tool: tool.name, error }),
734
+ Effect.as({
735
+ parameters: "Record<string, unknown>",
736
+ decode: Option.none(),
737
+ fallback: `Input JSON Schema:\n${JSON.stringify(tool.inputSchema, null, 2)}`,
738
+ }),
739
+ ),
740
+ ),
741
+ )
742
+ const { parameters, decode, fallback } = input
743
+
744
+ const outputSchema = tool.outputSchema
745
+ const result =
746
+ outputSchema === undefined
747
+ ? "string"
748
+ : yield* Effect.try(() =>
749
+ TypeBuilder.render(importSchema(outputSchema), {
750
+ omitUnknownIndexSignatures: true,
751
+ }),
752
+ ).pipe(Effect.orElseSucceed(() => "unknown"))
753
+
754
+ const docs = [tool.description, fallback].filter(
755
+ (text): text is string => text !== undefined && text !== "",
756
+ )
757
+ const signature = ` function ${id}(options: ${indentRest(parameters, " ")}): Promise<${indentRest(result, " ")}>`
758
+ const parameterNames = Object.keys(tool.inputSchema.properties ?? {})
759
+
760
+ return {
761
+ id,
762
+ name: tool.name,
763
+ description: tool.description,
764
+ decode,
765
+ structured: tool.outputSchema !== undefined,
766
+ dts:
767
+ docs.length === 0
768
+ ? signature
769
+ : `${TypeBuilder.renderJsDoc(docs.join("\n\n"), " ")}\n${signature}`,
770
+ search: {
771
+ names: [tool.name.toLowerCase(), id.toLowerCase()],
772
+ nameTokens: new Set([...tokens(tool.name), ...tokens(id)]),
773
+ parameterTokens: new Set(parameterNames.flatMap(tokens)),
774
+ description: (tool.description ?? "").toLowerCase(),
775
+ },
776
+ } satisfies ToolEntry
777
+ })
778
+
779
+ // =============================================================================
780
+ // Discovery
781
+ // =============================================================================
782
+
783
+ const searchToolsDts = `/**
784
+ * List every tool on a server:
785
+ *
786
+ * console.log(await searchTools({ server: "github" }))
787
+ *
788
+ * Search all servers by keyword, for at most 10 tools:
789
+ *
790
+ * console.log(await searchTools({ query: "create issue" }))
791
+ *
792
+ * Both return the tools' type declarations. Print them before calling a tool.
793
+ * A \`query\` with a \`server\` searches only that server.
794
+ */
795
+ declare function searchTools(options: {
796
+ readonly query?: string;
797
+ readonly server?: string;
798
+ }): Promise<string>`
799
+
800
+ const SearchParams = Schema.Struct({
801
+ query: Schema.optionalKey(Schema.String),
802
+ server: Schema.optionalKey(Schema.String),
803
+ })
804
+
805
+ // The most tools a query returns. Listing a server returns all of them.
806
+ const maxResults = 10
807
+
808
+ const tokens = (text: string): Array<string> =>
809
+ text
810
+ .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
811
+ .toLowerCase()
812
+ .split(/[^a-z0-9]+/)
813
+ .filter((token) => token !== "")
814
+
815
+ const score = (
816
+ tool: ToolEntry,
817
+ query: { readonly text: string; readonly tokens: ReadonlyArray<string> },
818
+ ): number => {
819
+ let total = tool.search.names.includes(query.text) ? 1000 : 0
820
+ for (const token of query.tokens) {
821
+ if (tool.search.nameTokens.has(token)) total += 10
822
+ else if (tool.search.names.some((name) => name.includes(token))) total += 5
823
+ if (tool.search.parameterTokens.has(token)) total += 3
824
+ if (tool.search.description.includes(token)) total += 2
825
+ }
826
+ return total
827
+ }
828
+
829
+ const makeSearchTools = (servers: ReadonlyArray<ConnectedServer>) => {
830
+ const decode = Schema.decodeUnknownEffect(SearchParams)
831
+ const serverList = servers.map((server) => server.id).join(", ")
832
+ const counts = servers
833
+ .map((server) => `${server.id} (${server.status.tools.length} tools)`)
834
+ .join(", ")
835
+
836
+ return Effect.fnUntraced(function* (
837
+ params: unknown,
838
+ ): Effect.fn.Return<string, string> {
839
+ const options = yield* decode(params ?? {}).pipe(
840
+ Effect.mapError((error) => `searchTools: ${error.message}`),
841
+ )
842
+ const query = options.query?.trim() ?? ""
843
+ let candidates = servers
844
+ if (options.server !== undefined) {
845
+ const server = servers.find(
846
+ (server) =>
847
+ server.id === options.server || server.name === options.server,
848
+ )
849
+ if (server === undefined) {
850
+ return yield* Effect.fail(
851
+ `searchTools: unknown MCP server "${options.server}". Servers: ${serverList}`,
852
+ )
853
+ }
854
+ if (query === "") return renderTools([[server, server.tools]])
855
+ candidates = [server]
856
+ } else if (query === "") {
857
+ return yield* Effect.fail(
858
+ `searchTools: pass a query or a server. Servers: ${serverList}`,
859
+ )
860
+ }
861
+
862
+ const terms = { text: query.toLowerCase(), tokens: tokens(query) }
863
+ const ranked = candidates
864
+ .flatMap((server) =>
865
+ server.tools.map((tool) => ({
866
+ server,
867
+ tool,
868
+ score: score(tool, terms),
869
+ })),
870
+ )
871
+ .filter((match) => match.score > 0)
872
+ .toSorted((a, b) => b.score - a.score)
873
+ .slice(0, maxResults)
874
+ if (ranked.length === 0) {
875
+ return `No MCP tools match "${query}". Servers: ${counts}.`
876
+ }
877
+ const groups = new Map<ConnectedServer, Array<ToolEntry>>()
878
+ for (const { server, tool } of ranked) {
879
+ const group = groups.get(server)
880
+ if (group === undefined) groups.set(server, [tool])
881
+ else group.push(tool)
882
+ }
883
+ return renderTools([...groups])
884
+ })
885
+ }
886
+
887
+ const renderTools = (
888
+ groups: ReadonlyArray<readonly [ConnectedServer, ReadonlyArray<ToolEntry>]>,
889
+ ): string =>
890
+ groups
891
+ .map(
892
+ ([server, tools]) =>
893
+ `declare namespace mcp.${server.id} {\n${tools.map((tool) => tool.dts).join("\n\n")}\n}`,
894
+ )
895
+ .join("\n\n")
896
+
897
+ // =============================================================================
898
+ // Calls
899
+ // =============================================================================
900
+
901
+ const callTool = (
902
+ server: ConnectedServer,
903
+ tool: ToolEntry,
904
+ onImage: (image: ImageAttachment) => Effect.Effect<void>,
905
+ nextImage: () => number,
906
+ ) => {
907
+ const name = `${server.id}.${tool.id}`
908
+ const prefix = `mcp.${name}:`
909
+ const timeout = Duration.toMillis(server.callTimeout)
910
+ const timedOut = `${prefix} timed out after ${timeout}ms`
911
+ return Effect.fnUntraced(function* (
912
+ params: unknown,
913
+ ): Effect.fn.Return<unknown, string> {
914
+ if (server.dropped !== undefined) {
915
+ return yield* Effect.fail(
916
+ `${prefix} MCP server "${server.name}" is not connected: ${server.dropped}`,
917
+ )
918
+ }
919
+ const args = params ?? {}
920
+ if (Option.isSome(tool.decode)) {
921
+ yield* tool.decode
922
+ .value(args)
923
+ .pipe(Effect.mapError((message) => `${prefix} ${message}`))
924
+ }
925
+ const result = (yield* Effect.tryPromise({
926
+ try: (signal) =>
927
+ server.client.callTool(
928
+ { name: tool.name, arguments: args as Record<string, unknown> },
929
+ undefined,
930
+ { signal, timeout },
931
+ ),
932
+ catch: (error) =>
933
+ error instanceof McpError && error.code === ErrorCode.RequestTimeout
934
+ ? timedOut
935
+ : `${prefix} ${errorMessage(error)}`,
936
+ }).pipe(
937
+ Effect.timeoutOrElse({
938
+ duration: server.callTimeout,
939
+ orElse: () => Effect.fail(timedOut),
940
+ }),
941
+ )) as CallToolResult
942
+ if (result.isError !== true && tool.structured) {
943
+ return result.structuredContent
944
+ }
945
+ const text = yield* renderContent(result.content ?? [], {
946
+ name,
947
+ onImage,
948
+ nextImage,
949
+ })
950
+ if (result.isError === true) {
951
+ return yield* Effect.fail(
952
+ `${prefix} ${text === "" ? "tool returned an error with no message" : text}`,
953
+ )
954
+ }
955
+ return text
956
+ })
957
+ }
958
+
959
+ const extensions: Record<Image.ImageMediaType, string> = {
960
+ "image/png": "png",
961
+ "image/jpeg": "jpg",
962
+ "image/gif": "gif",
963
+ "image/webp": "webp",
964
+ }
965
+
966
+ const renderContent = Effect.fnUntraced(function* (
967
+ content: CallToolResult["content"],
968
+ options: {
969
+ readonly name: string
970
+ readonly onImage: (image: ImageAttachment) => Effect.Effect<void>
971
+ readonly nextImage: () => number
972
+ },
973
+ ) {
974
+ const parts: Array<string> = []
975
+ for (const block of content) {
976
+ switch (block.type) {
977
+ case "text":
978
+ parts.push(block.text)
979
+ break
980
+ case "image": {
981
+ if (!Image.isImageMediaType(block.mimeType)) {
982
+ parts.push(`[Image omitted (${block.mimeType}): unsupported type]`)
983
+ break
984
+ }
985
+ const decoded = Base64.decode(block.data)
986
+ if (Result.isFailure(decoded)) {
987
+ parts.push(`[Image omitted (${block.mimeType}): invalid base64 data]`)
988
+ break
989
+ }
990
+ const bytes = decoded.success
991
+ const prepared = yield* Effect.exit(
992
+ Image.prepare({
993
+ data: bytes,
994
+ mediaType: Option.getOrElse(
995
+ Image.mediaTypeFromBytes(bytes),
996
+ () => block.mimeType as Image.ImageMediaType,
997
+ ),
998
+ }),
999
+ )
1000
+ if (Exit.isFailure(prepared)) {
1001
+ const error = Option.match(Exit.findErrorOption(prepared), {
1002
+ onNone: () => "the image could not be read",
1003
+ onSome: (error) => error.message,
1004
+ })
1005
+ parts.push(`[Image omitted (${block.mimeType}): ${error}]`)
1006
+ break
1007
+ }
1008
+ const fileName = `${options.name}-${options.nextImage()}.${extensions[prepared.value.mediaType]}`
1009
+ yield* options.onImage({
1010
+ fileName,
1011
+ mediaType: prepared.value.mediaType,
1012
+ data: prepared.value.data,
1013
+ })
1014
+ parts.push(`[Image attached: ${fileName}]`)
1015
+ break
1016
+ }
1017
+ case "audio":
1018
+ parts.push(`[Audio omitted (${block.mimeType})]`)
1019
+ break
1020
+ case "resource":
1021
+ parts.push(
1022
+ "text" in block.resource && typeof block.resource.text === "string"
1023
+ ? `[Resource ${block.resource.uri}]\n${block.resource.text}`
1024
+ : `[Binary resource omitted: ${block.resource.uri} (${block.resource.mimeType ?? "unknown type"})]`,
1025
+ )
1026
+ break
1027
+ case "resource_link":
1028
+ parts.push(`[Resource link: ${block.name} ${block.uri}]`)
1029
+ break
1030
+ }
1031
+ }
1032
+ return parts.join("\n")
1033
+ })
1034
+
1035
+ // =============================================================================
1036
+ // System prompt
1037
+ // =============================================================================
1038
+
1039
+ const maxInstructions = 2000
1040
+
1041
+ const renderPrompt = (servers: ReadonlyArray<ServerState>): string => {
1042
+ if (servers.length === 0) return ""
1043
+ const anyConnected = servers.some((server) => server._tag === "Connected")
1044
+ const lines = servers.map((server) => {
1045
+ if (server._tag === "Failed") {
1046
+ return `- ${server.name}: failed to connect: ${shortReason(server.error)}`
1047
+ }
1048
+ const header = `- ${server.id} (${server.status.tools.length} tools). List them with \`searchTools({ server: ${JSON.stringify(server.id)} })\`.`
1049
+ return Option.match(server.status.instructions, {
1050
+ onNone: () => header,
1051
+ onSome: (instructions) => {
1052
+ const text =
1053
+ instructions.length > maxInstructions
1054
+ ? `${instructions.slice(0, maxInstructions)}\n[instructions truncated]`
1055
+ : instructions
1056
+ return `${header} Its instructions:\n\n${text.trim()}\n`
1057
+ },
1058
+ })
1059
+ })
1060
+ return `# MCP servers
1061
+ ${
1062
+ anyConnected
1063
+ ? `
1064
+ 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.
1065
+ `
1066
+ : ""
1067
+ }
1068
+ ${lines.join("\n")}`
1069
+ }
1070
+
1071
+ const errorMessage = (error: unknown): string =>
1072
+ error instanceof Error ? error.message : String(error)