agents 0.0.0-de168a2 → 0.0.0-df41827

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 (42) hide show
  1. package/dist/ai-chat-agent.d.ts +46 -4
  2. package/dist/ai-chat-agent.js +138 -68
  3. package/dist/ai-chat-agent.js.map +1 -1
  4. package/dist/ai-react.d.ts +17 -4
  5. package/dist/ai-react.js +49 -42
  6. package/dist/ai-react.js.map +1 -1
  7. package/dist/ai-types.d.ts +5 -0
  8. package/dist/chunk-767EASBA.js +106 -0
  9. package/dist/chunk-767EASBA.js.map +1 -0
  10. package/dist/chunk-E3LCYPCB.js +469 -0
  11. package/dist/chunk-E3LCYPCB.js.map +1 -0
  12. package/dist/chunk-NKZZ66QY.js +116 -0
  13. package/dist/chunk-NKZZ66QY.js.map +1 -0
  14. package/dist/{chunk-XG52S6YY.js → chunk-ZRRXJUAA.js} +357 -160
  15. package/dist/chunk-ZRRXJUAA.js.map +1 -0
  16. package/dist/client.d.ts +15 -1
  17. package/dist/client.js +6 -126
  18. package/dist/client.js.map +1 -1
  19. package/dist/index.d.ts +123 -14
  20. package/dist/index.js +8 -6
  21. package/dist/mcp/client.d.ts +34 -14
  22. package/dist/mcp/client.js +3 -402
  23. package/dist/mcp/client.js.map +1 -1
  24. package/dist/mcp/do-oauth-client-provider.d.ts +3 -3
  25. package/dist/mcp/do-oauth-client-provider.js +3 -103
  26. package/dist/mcp/do-oauth-client-provider.js.map +1 -1
  27. package/dist/mcp/index.d.ts +44 -5
  28. package/dist/mcp/index.js +593 -159
  29. package/dist/mcp/index.js.map +1 -1
  30. package/dist/react.d.ts +85 -5
  31. package/dist/react.js +20 -8
  32. package/dist/react.js.map +1 -1
  33. package/dist/schedule.d.ts +2 -2
  34. package/dist/schedule.js +4 -6
  35. package/dist/schedule.js.map +1 -1
  36. package/dist/serializable.d.ts +32 -0
  37. package/dist/serializable.js +1 -0
  38. package/package.json +71 -56
  39. package/src/index.ts +429 -86
  40. package/dist/chunk-HMLY7DHA.js +0 -16
  41. package/dist/chunk-XG52S6YY.js.map +0 -1
  42. /package/dist/{chunk-HMLY7DHA.js.map → serializable.js.map} +0 -0
package/src/index.ts CHANGED
@@ -1,19 +1,30 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+ import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
3
+ import type { SSEClientTransportOptions } from "@modelcontextprotocol/sdk/client/sse.js";
4
+
5
+ import type {
6
+ Prompt,
7
+ Resource,
8
+ ServerCapabilities,
9
+ Tool,
10
+ } from "@modelcontextprotocol/sdk/types.js";
11
+ import { parseCronExpression } from "cron-schedule";
12
+ import { nanoid } from "nanoid";
1
13
  import {
2
- Server,
3
- routePartykitRequest,
4
- type PartyServerOptions,
5
- getServerByName,
6
14
  type Connection,
7
15
  type ConnectionContext,
16
+ getServerByName,
17
+ type PartyServerOptions,
18
+ routePartykitRequest,
19
+ Server,
8
20
  type WSMessage,
9
21
  } from "partyserver";
22
+ import { camelCaseToKebabCase } from "./client";
23
+ import { MCPClientManager } from "./mcp/client";
24
+ // import type { MCPClientConnection } from "./mcp/client-connection";
25
+ import { DurableObjectOAuthClientProvider } from "./mcp/do-oauth-client-provider";
10
26
 
11
- import { parseCronExpression } from "cron-schedule";
12
- import { nanoid } from "nanoid";
13
-
14
- import { AsyncLocalStorage } from "node:async_hooks";
15
-
16
- export type { Connection, WSMessage, ConnectionContext } from "partyserver";
27
+ export type { Connection, ConnectionContext, WSMessage } from "partyserver";
17
28
 
18
29
  /**
19
30
  * RPC request message from client
@@ -97,7 +108,6 @@ export type CallableMetadata = {
97
108
  streaming?: boolean;
98
109
  };
99
110
 
100
- // biome-ignore lint/complexity/noBannedTypes: <explanation>
101
111
  const callableMetadata = new Map<Function, CallableMetadata>();
102
112
 
103
113
  /**
@@ -107,6 +117,7 @@ const callableMetadata = new Map<Function, CallableMetadata>();
107
117
  export function unstable_callable(metadata: CallableMetadata = {}) {
108
118
  return function callableDecorator<This, Args extends unknown[], Return>(
109
119
  target: (this: This, ...args: Args) => Return,
120
+ // biome-ignore lint/correctness/noUnusedFunctionParameters: later
110
121
  context: ClassMethodDecoratorContext
111
122
  ) {
112
123
  if (!callableMetadata.has(target)) {
@@ -158,24 +169,95 @@ function getNextCronTime(cron: string) {
158
169
  return interval.getNextDate();
159
170
  }
160
171
 
172
+ /**
173
+ * MCP Server state update message from server -> Client
174
+ */
175
+ export type MCPServerMessage = {
176
+ type: "cf_agent_mcp_servers";
177
+ mcp: MCPServersState;
178
+ };
179
+
180
+ export type MCPServersState = {
181
+ servers: {
182
+ [id: string]: MCPServer;
183
+ };
184
+ tools: Tool[];
185
+ prompts: Prompt[];
186
+ resources: Resource[];
187
+ };
188
+
189
+ export type MCPServer = {
190
+ name: string;
191
+ server_url: string;
192
+ auth_url: string | null;
193
+ // This state is specifically about the temporary process of getting a token (if needed).
194
+ // Scope outside of that can't be relied upon because when the DO sleeps, there's no way
195
+ // to communicate a change to a non-ready state.
196
+ state: "authenticating" | "connecting" | "ready" | "discovering" | "failed";
197
+ instructions: string | null;
198
+ capabilities: ServerCapabilities | null;
199
+ };
200
+
201
+ /**
202
+ * MCP Server data stored in DO SQL for resuming MCP Server connections
203
+ */
204
+ type MCPServerRow = {
205
+ id: string;
206
+ name: string;
207
+ server_url: string;
208
+ client_id: string | null;
209
+ auth_url: string | null;
210
+ callback_url: string;
211
+ server_options: string;
212
+ };
213
+
161
214
  const STATE_ROW_ID = "cf_state_row_id";
162
215
  const STATE_WAS_CHANGED = "cf_state_was_changed";
163
216
 
164
217
  const DEFAULT_STATE = {} as unknown;
165
218
 
166
- export const unstable_context = new AsyncLocalStorage<{
219
+ const agentContext = new AsyncLocalStorage<{
167
220
  agent: Agent<unknown>;
168
221
  connection: Connection | undefined;
169
222
  request: Request | undefined;
170
223
  }>();
171
224
 
225
+ export function getCurrentAgent<
226
+ T extends Agent<unknown, unknown> = Agent<unknown, unknown>,
227
+ >(): {
228
+ agent: T | undefined;
229
+ connection: Connection | undefined;
230
+ request: Request<unknown, CfProperties<unknown>> | undefined;
231
+ } {
232
+ const store = agentContext.getStore() as
233
+ | {
234
+ agent: T;
235
+ connection: Connection | undefined;
236
+ request: Request<unknown, CfProperties<unknown>> | undefined;
237
+ }
238
+ | undefined;
239
+ if (!store) {
240
+ return {
241
+ agent: undefined,
242
+ connection: undefined,
243
+ request: undefined,
244
+ };
245
+ }
246
+ return store;
247
+ }
248
+
172
249
  /**
173
250
  * Base class for creating Agent implementations
174
251
  * @template Env Environment type containing bindings
175
252
  * @template State State type to store within the Agent
176
253
  */
177
254
  export class Agent<Env, State = unknown> extends Server<Env> {
178
- #state = DEFAULT_STATE as State;
255
+ private _state = DEFAULT_STATE as State;
256
+
257
+ private _ParentClass: typeof Agent<Env, State> =
258
+ Object.getPrototypeOf(this).constructor;
259
+
260
+ mcp: MCPClientManager = new MCPClientManager(this._ParentClass.name, "0.0.1");
179
261
 
180
262
  /**
181
263
  * Initial state for the Agent
@@ -187,9 +269,9 @@ export class Agent<Env, State = unknown> extends Server<Env> {
187
269
  * Current state of the Agent
188
270
  */
189
271
  get state(): State {
190
- if (this.#state !== DEFAULT_STATE) {
272
+ if (this._state !== DEFAULT_STATE) {
191
273
  // state was previously set, and populated internal state
192
- return this.#state;
274
+ return this._state;
193
275
  }
194
276
  // looks like this is the first time the state is being accessed
195
277
  // check if the state was set in a previous life
@@ -209,8 +291,8 @@ export class Agent<Env, State = unknown> extends Server<Env> {
209
291
  ) {
210
292
  const state = result[0]?.state as string; // could be null?
211
293
 
212
- this.#state = JSON.parse(state);
213
- return this.#state;
294
+ this._state = JSON.parse(state);
295
+ return this._state;
214
296
  }
215
297
 
216
298
  // ok, this is the first time the state is being accessed
@@ -271,7 +353,7 @@ export class Agent<Env, State = unknown> extends Server<Env> {
271
353
  `;
272
354
 
273
355
  void this.ctx.blockConcurrencyWhile(async () => {
274
- return this.#tryCatch(async () => {
356
+ return this._tryCatch(async () => {
275
357
  // Create alarms table if it doesn't exist
276
358
  this.sql`
277
359
  CREATE TABLE IF NOT EXISTS cf_agents_schedules (
@@ -291,25 +373,65 @@ export class Agent<Env, State = unknown> extends Server<Env> {
291
373
  });
292
374
  });
293
375
 
376
+ this.sql`
377
+ CREATE TABLE IF NOT EXISTS cf_agents_mcp_servers (
378
+ id TEXT PRIMARY KEY NOT NULL,
379
+ name TEXT NOT NULL,
380
+ server_url TEXT NOT NULL,
381
+ callback_url TEXT NOT NULL,
382
+ client_id TEXT,
383
+ auth_url TEXT,
384
+ server_options TEXT
385
+ )
386
+ `;
387
+
388
+ const _onRequest = this.onRequest.bind(this);
389
+ this.onRequest = (request: Request) => {
390
+ return agentContext.run(
391
+ { agent: this, connection: undefined, request },
392
+ async () => {
393
+ if (this.mcp.isCallbackRequest(request)) {
394
+ await this.mcp.handleCallbackRequest(request);
395
+
396
+ // after the MCP connection handshake, we can send updated mcp state
397
+ this.broadcast(
398
+ JSON.stringify({
399
+ mcp: this.getMcpServers(),
400
+ type: "cf_agent_mcp_servers",
401
+ })
402
+ );
403
+
404
+ // We probably should let the user configure this response/redirect, but this is fine for now.
405
+ return new Response("<script>window.close();</script>", {
406
+ headers: { "content-type": "text/html" },
407
+ status: 200,
408
+ });
409
+ }
410
+
411
+ return this._tryCatch(() => _onRequest(request));
412
+ }
413
+ );
414
+ };
415
+
294
416
  const _onMessage = this.onMessage.bind(this);
295
417
  this.onMessage = async (connection: Connection, message: WSMessage) => {
296
- return unstable_context.run(
418
+ return agentContext.run(
297
419
  { agent: this, connection, request: undefined },
298
420
  async () => {
299
421
  if (typeof message !== "string") {
300
- return this.#tryCatch(() => _onMessage(connection, message));
422
+ return this._tryCatch(() => _onMessage(connection, message));
301
423
  }
302
424
 
303
425
  let parsed: unknown;
304
426
  try {
305
427
  parsed = JSON.parse(message);
306
- } catch (e) {
428
+ } catch (_e) {
307
429
  // silently fail and let the onMessage handler handle it
308
- return this.#tryCatch(() => _onMessage(connection, message));
430
+ return this._tryCatch(() => _onMessage(connection, message));
309
431
  }
310
432
 
311
433
  if (isStateUpdateMessage(parsed)) {
312
- this.#setStateInternal(parsed.state as State, connection);
434
+ this._setStateInternal(parsed.state as State, connection);
313
435
  return;
314
436
  }
315
437
 
@@ -323,11 +445,10 @@ export class Agent<Env, State = unknown> extends Server<Env> {
323
445
  throw new Error(`Method ${method} does not exist`);
324
446
  }
325
447
 
326
- if (!this.#isCallable(method)) {
448
+ if (!this._isCallable(method)) {
327
449
  throw new Error(`Method ${method} is not callable`);
328
450
  }
329
451
 
330
- // biome-ignore lint/complexity/noBannedTypes: <explanation>
331
452
  const metadata = callableMetadata.get(methodFn as Function);
332
453
 
333
454
  // For streaming methods, pass a StreamingResponse object
@@ -340,21 +461,21 @@ export class Agent<Env, State = unknown> extends Server<Env> {
340
461
  // For regular methods, execute and send response
341
462
  const result = await methodFn.apply(this, args);
342
463
  const response: RPCResponse = {
343
- type: "rpc",
464
+ done: true,
344
465
  id,
345
- success: true,
346
466
  result,
347
- done: true,
467
+ success: true,
468
+ type: "rpc",
348
469
  };
349
470
  connection.send(JSON.stringify(response));
350
471
  } catch (e) {
351
472
  // Send error response
352
473
  const response: RPCResponse = {
353
- type: "rpc",
354
- id: parsed.id,
355
- success: false,
356
474
  error:
357
475
  e instanceof Error ? e.message : "Unknown error occurred",
476
+ id: parsed.id,
477
+ success: false,
478
+ type: "rpc",
358
479
  };
359
480
  connection.send(JSON.stringify(response));
360
481
  console.error("RPC error:", e);
@@ -362,7 +483,7 @@ export class Agent<Env, State = unknown> extends Server<Env> {
362
483
  return;
363
484
  }
364
485
 
365
- return this.#tryCatch(() => _onMessage(connection, message));
486
+ return this._tryCatch(() => _onMessage(connection, message));
366
487
  }
367
488
  );
368
489
  };
@@ -371,27 +492,79 @@ export class Agent<Env, State = unknown> extends Server<Env> {
371
492
  this.onConnect = (connection: Connection, ctx: ConnectionContext) => {
372
493
  // TODO: This is a hack to ensure the state is sent after the connection is established
373
494
  // must fix this
374
- return unstable_context.run(
495
+ return agentContext.run(
375
496
  { agent: this, connection, request: ctx.request },
376
497
  async () => {
377
498
  setTimeout(() => {
378
499
  if (this.state) {
379
500
  connection.send(
380
501
  JSON.stringify({
381
- type: "cf_agent_state",
382
502
  state: this.state,
503
+ type: "cf_agent_state",
383
504
  })
384
505
  );
385
506
  }
386
- return this.#tryCatch(() => _onConnect(connection, ctx));
507
+
508
+ connection.send(
509
+ JSON.stringify({
510
+ mcp: this.getMcpServers(),
511
+ type: "cf_agent_mcp_servers",
512
+ })
513
+ );
514
+
515
+ return this._tryCatch(() => _onConnect(connection, ctx));
387
516
  }, 20);
388
517
  }
389
518
  );
390
519
  };
520
+
521
+ const _onStart = this.onStart.bind(this);
522
+ this.onStart = async () => {
523
+ return agentContext.run(
524
+ { agent: this, connection: undefined, request: undefined },
525
+ async () => {
526
+ const servers = this.sql<MCPServerRow>`
527
+ SELECT id, name, server_url, client_id, auth_url, callback_url, server_options FROM cf_agents_mcp_servers;
528
+ `;
529
+
530
+ // from DO storage, reconnect to all servers not currently in the oauth flow using our saved auth information
531
+ await Promise.allSettled(
532
+ servers
533
+ .filter((server) => server.auth_url === null)
534
+ .map((server) => {
535
+ return this._connectToMcpServerInternal(
536
+ server.name,
537
+ server.server_url,
538
+ server.callback_url,
539
+ server.server_options
540
+ ? JSON.parse(server.server_options)
541
+ : undefined,
542
+ {
543
+ id: server.id,
544
+ oauthClientId: server.client_id ?? undefined,
545
+ }
546
+ );
547
+ })
548
+ );
549
+
550
+ this.broadcast(
551
+ JSON.stringify({
552
+ mcp: this.getMcpServers(),
553
+ type: "cf_agent_mcp_servers",
554
+ })
555
+ );
556
+
557
+ await this._tryCatch(() => _onStart());
558
+ }
559
+ );
560
+ };
391
561
  }
392
562
 
393
- #setStateInternal(state: State, source: Connection | "server" = "server") {
394
- this.#state = state;
563
+ private _setStateInternal(
564
+ state: State,
565
+ source: Connection | "server" = "server"
566
+ ) {
567
+ this._state = state;
395
568
  this.sql`
396
569
  INSERT OR REPLACE INTO cf_agents_state (id, state)
397
570
  VALUES (${STATE_ROW_ID}, ${JSON.stringify(state)})
@@ -402,14 +575,14 @@ export class Agent<Env, State = unknown> extends Server<Env> {
402
575
  `;
403
576
  this.broadcast(
404
577
  JSON.stringify({
405
- type: "cf_agent_state",
406
578
  state: state,
579
+ type: "cf_agent_state",
407
580
  }),
408
581
  source !== "server" ? [source.id] : []
409
582
  );
410
- return this.#tryCatch(() => {
411
- const { connection, request } = unstable_context.getStore() || {};
412
- return unstable_context.run(
583
+ return this._tryCatch(() => {
584
+ const { connection, request } = agentContext.getStore() || {};
585
+ return agentContext.run(
413
586
  { agent: this, connection, request },
414
587
  async () => {
415
588
  return this.onStateUpdate(state, source);
@@ -423,7 +596,7 @@ export class Agent<Env, State = unknown> extends Server<Env> {
423
596
  * @param state New state to set
424
597
  */
425
598
  setState(state: State) {
426
- this.#setStateInternal(state, "server");
599
+ this._setStateInternal(state, "server");
427
600
  }
428
601
 
429
602
  /**
@@ -431,6 +604,7 @@ export class Agent<Env, State = unknown> extends Server<Env> {
431
604
  * @param state Updated state
432
605
  * @param source Source of the state update ("server" or a client connection)
433
606
  */
607
+ // biome-ignore lint/correctness/noUnusedFunctionParameters: overridden later
434
608
  onStateUpdate(state: State | undefined, source: Connection | "server") {
435
609
  // override this to handle state updates
436
610
  }
@@ -439,8 +613,9 @@ export class Agent<Env, State = unknown> extends Server<Env> {
439
613
  * Called when the Agent receives an email
440
614
  * @param email Email message to process
441
615
  */
616
+ // biome-ignore lint/correctness/noUnusedFunctionParameters: overridden later
442
617
  onEmail(email: ForwardableEmailMessage) {
443
- return unstable_context.run(
618
+ return agentContext.run(
444
619
  { agent: this, connection: undefined, request: undefined },
445
620
  async () => {
446
621
  console.error("onEmail not implemented");
@@ -448,7 +623,7 @@ export class Agent<Env, State = unknown> extends Server<Env> {
448
623
  );
449
624
  }
450
625
 
451
- async #tryCatch<T>(fn: () => T | Promise<T>) {
626
+ private async _tryCatch<T>(fn: () => T | Promise<T>) {
452
627
  try {
453
628
  return await fn();
454
629
  } catch (e) {
@@ -522,11 +697,11 @@ export class Agent<Env, State = unknown> extends Server<Env> {
522
697
  )}, 'scheduled', ${timestamp})
523
698
  `;
524
699
 
525
- await this.#scheduleNextAlarm();
700
+ await this._scheduleNextAlarm();
526
701
 
527
702
  return {
528
- id,
529
703
  callback: callback,
704
+ id,
530
705
  payload: payload as T,
531
706
  time: timestamp,
532
707
  type: "scheduled",
@@ -543,13 +718,13 @@ export class Agent<Env, State = unknown> extends Server<Env> {
543
718
  )}, 'delayed', ${when}, ${timestamp})
544
719
  `;
545
720
 
546
- await this.#scheduleNextAlarm();
721
+ await this._scheduleNextAlarm();
547
722
 
548
723
  return {
549
- id,
550
724
  callback: callback,
551
- payload: payload as T,
552
725
  delayInSeconds: when,
726
+ id,
727
+ payload: payload as T,
553
728
  time: timestamp,
554
729
  type: "delayed",
555
730
  };
@@ -565,13 +740,13 @@ export class Agent<Env, State = unknown> extends Server<Env> {
565
740
  )}, 'cron', ${when}, ${timestamp})
566
741
  `;
567
742
 
568
- await this.#scheduleNextAlarm();
743
+ await this._scheduleNextAlarm();
569
744
 
570
745
  return {
571
- id,
572
746
  callback: callback,
573
- payload: payload as T,
574
747
  cron: when,
748
+ id,
749
+ payload: payload as T,
575
750
  time: timestamp,
576
751
  type: "cron",
577
752
  };
@@ -652,11 +827,11 @@ export class Agent<Env, State = unknown> extends Server<Env> {
652
827
  async cancelSchedule(id: string): Promise<boolean> {
653
828
  this.sql`DELETE FROM cf_agents_schedules WHERE id = ${id}`;
654
829
 
655
- await this.#scheduleNextAlarm();
830
+ await this._scheduleNextAlarm();
656
831
  return true;
657
832
  }
658
833
 
659
- async #scheduleNextAlarm() {
834
+ private async _scheduleNextAlarm() {
660
835
  // Find the next schedule that needs to be executed
661
836
  const result = this.sql`
662
837
  SELECT time FROM cf_agents_schedules
@@ -673,10 +848,14 @@ export class Agent<Env, State = unknown> extends Server<Env> {
673
848
  }
674
849
 
675
850
  /**
676
- * Method called when an alarm fires
677
- * Executes any scheduled tasks that are due
851
+ * Method called when an alarm fires.
852
+ * Executes any scheduled tasks that are due.
853
+ *
854
+ * @remarks
855
+ * To schedule a task, please use the `this.schedule` method instead.
856
+ * See {@link https://developers.cloudflare.com/agents/api-reference/schedule-tasks/}
678
857
  */
679
- async alarm() {
858
+ public readonly alarm = async () => {
680
859
  const now = Math.floor(Date.now() / 1000);
681
860
 
682
861
  // Get all schedules that should be executed now
@@ -690,7 +869,7 @@ export class Agent<Env, State = unknown> extends Server<Env> {
690
869
  console.error(`callback ${row.callback} not found`);
691
870
  continue;
692
871
  }
693
- await unstable_context.run(
872
+ await agentContext.run(
694
873
  { agent: this, connection: undefined, request: undefined },
695
874
  async () => {
696
875
  try {
@@ -722,8 +901,8 @@ export class Agent<Env, State = unknown> extends Server<Env> {
722
901
  }
723
902
 
724
903
  // Schedule the next alarm
725
- await this.#scheduleNextAlarm();
726
- }
904
+ await this._scheduleNextAlarm();
905
+ };
727
906
 
728
907
  /**
729
908
  * Destroy the Agent, removing all state and scheduled tasks
@@ -732,20 +911,184 @@ export class Agent<Env, State = unknown> extends Server<Env> {
732
911
  // drop all tables
733
912
  this.sql`DROP TABLE IF EXISTS cf_agents_state`;
734
913
  this.sql`DROP TABLE IF EXISTS cf_agents_schedules`;
914
+ this.sql`DROP TABLE IF EXISTS cf_agents_mcp_servers`;
735
915
 
736
916
  // delete all alarms
737
917
  await this.ctx.storage.deleteAlarm();
738
918
  await this.ctx.storage.deleteAll();
919
+ this.ctx.abort("destroyed"); // enforce that the agent is evicted
739
920
  }
740
921
 
741
922
  /**
742
923
  * Get all methods marked as callable on this Agent
743
924
  * @returns A map of method names to their metadata
744
925
  */
745
- #isCallable(method: string): boolean {
746
- // biome-ignore lint/complexity/noBannedTypes: <explanation>
926
+ private _isCallable(method: string): boolean {
747
927
  return callableMetadata.has(this[method as keyof this] as Function);
748
928
  }
929
+
930
+ /**
931
+ * Connect to a new MCP Server
932
+ *
933
+ * @param url MCP Server SSE URL
934
+ * @param callbackHost Base host for the agent, used for the redirect URI.
935
+ * @param agentsPrefix agents routing prefix if not using `agents`
936
+ * @param options MCP client and transport (header) options
937
+ * @returns authUrl
938
+ */
939
+ async addMcpServer(
940
+ serverName: string,
941
+ url: string,
942
+ callbackHost: string,
943
+ agentsPrefix = "agents",
944
+ options?: {
945
+ client?: ConstructorParameters<typeof Client>[1];
946
+ transport?: {
947
+ headers: HeadersInit;
948
+ };
949
+ }
950
+ ): Promise<{ id: string; authUrl: string | undefined }> {
951
+ const callbackUrl = `${callbackHost}/${agentsPrefix}/${camelCaseToKebabCase(this._ParentClass.name)}/${this.name}/callback`;
952
+
953
+ const result = await this._connectToMcpServerInternal(
954
+ serverName,
955
+ url,
956
+ callbackUrl,
957
+ options
958
+ );
959
+
960
+ this.broadcast(
961
+ JSON.stringify({
962
+ mcp: this.getMcpServers(),
963
+ type: "cf_agent_mcp_servers",
964
+ })
965
+ );
966
+
967
+ return result;
968
+ }
969
+
970
+ async _connectToMcpServerInternal(
971
+ serverName: string,
972
+ url: string,
973
+ callbackUrl: string,
974
+ // it's important that any options here are serializable because we put them into our sqlite DB for reconnection purposes
975
+ options?: {
976
+ client?: ConstructorParameters<typeof Client>[1];
977
+ /**
978
+ * We don't expose the normal set of transport options because:
979
+ * 1) we can't serialize things like the auth provider or a fetch function into the DB for reconnection purposes
980
+ * 2) We probably want these options to be agnostic to the transport type (SSE vs Streamable)
981
+ *
982
+ * This has the limitation that you can't override fetch, but I think headers should handle nearly all cases needed (i.e. non-standard bearer auth).
983
+ */
984
+ transport?: {
985
+ headers?: HeadersInit;
986
+ };
987
+ },
988
+ reconnect?: {
989
+ id: string;
990
+ oauthClientId?: string;
991
+ }
992
+ ): Promise<{ id: string; authUrl: string | undefined }> {
993
+ const authProvider = new DurableObjectOAuthClientProvider(
994
+ this.ctx.storage,
995
+ this.name,
996
+ callbackUrl
997
+ );
998
+
999
+ if (reconnect) {
1000
+ authProvider.serverId = reconnect.id;
1001
+ if (reconnect.oauthClientId) {
1002
+ authProvider.clientId = reconnect.oauthClientId;
1003
+ }
1004
+ }
1005
+
1006
+ // allows passing through transport headers if necessary
1007
+ // this handles some non-standard bearer auth setups (i.e. MCP server behind CF access instead of OAuth)
1008
+ let headerTransportOpts: SSEClientTransportOptions = {};
1009
+ if (options?.transport?.headers) {
1010
+ headerTransportOpts = {
1011
+ eventSourceInit: {
1012
+ fetch: (url, init) =>
1013
+ fetch(url, {
1014
+ ...init,
1015
+ headers: options?.transport?.headers,
1016
+ }),
1017
+ },
1018
+ requestInit: {
1019
+ headers: options?.transport?.headers,
1020
+ },
1021
+ };
1022
+ }
1023
+
1024
+ const { id, authUrl, clientId } = await this.mcp.connect(url, {
1025
+ client: options?.client,
1026
+ reconnect,
1027
+ transport: {
1028
+ ...headerTransportOpts,
1029
+ authProvider,
1030
+ },
1031
+ });
1032
+
1033
+ this.sql`
1034
+ INSERT OR REPLACE INTO cf_agents_mcp_servers (id, name, server_url, client_id, auth_url, callback_url, server_options)
1035
+ VALUES (
1036
+ ${id},
1037
+ ${serverName},
1038
+ ${url},
1039
+ ${clientId ?? null},
1040
+ ${authUrl ?? null},
1041
+ ${callbackUrl},
1042
+ ${options ? JSON.stringify(options) : null}
1043
+ );
1044
+ `;
1045
+
1046
+ return {
1047
+ authUrl,
1048
+ id,
1049
+ };
1050
+ }
1051
+
1052
+ async removeMcpServer(id: string) {
1053
+ this.mcp.closeConnection(id);
1054
+ this.sql`
1055
+ DELETE FROM cf_agents_mcp_servers WHERE id = ${id};
1056
+ `;
1057
+ this.broadcast(
1058
+ JSON.stringify({
1059
+ mcp: this.getMcpServers(),
1060
+ type: "cf_agent_mcp_servers",
1061
+ })
1062
+ );
1063
+ }
1064
+
1065
+ getMcpServers(): MCPServersState {
1066
+ const mcpState: MCPServersState = {
1067
+ prompts: this.mcp.listPrompts(),
1068
+ resources: this.mcp.listResources(),
1069
+ servers: {},
1070
+ tools: this.mcp.listTools(),
1071
+ };
1072
+
1073
+ const servers = this.sql<MCPServerRow>`
1074
+ SELECT id, name, server_url, client_id, auth_url, callback_url, server_options FROM cf_agents_mcp_servers;
1075
+ `;
1076
+
1077
+ for (const server of servers) {
1078
+ const serverConn = this.mcp.mcpConnections[server.id];
1079
+ mcpState.servers[server.id] = {
1080
+ auth_url: server.auth_url,
1081
+ capabilities: serverConn?.serverCapabilities ?? null,
1082
+ instructions: serverConn?.instructions ?? null,
1083
+ name: server.name,
1084
+ server_url: server.server_url,
1085
+ // mark as "authenticating" because the server isn't automatically connected, so it's pending authenticating
1086
+ state: serverConn?.connectionState ?? "authenticating",
1087
+ };
1088
+ }
1089
+
1090
+ return mcpState;
1091
+ }
749
1092
  }
750
1093
 
751
1094
  /**
@@ -785,9 +1128,9 @@ export async function routeAgentRequest<Env>(
785
1128
  const corsHeaders =
786
1129
  options?.cors === true
787
1130
  ? {
788
- "Access-Control-Allow-Origin": "*",
789
- "Access-Control-Allow-Methods": "GET, POST, HEAD, OPTIONS",
790
1131
  "Access-Control-Allow-Credentials": "true",
1132
+ "Access-Control-Allow-Methods": "GET, POST, HEAD, OPTIONS",
1133
+ "Access-Control-Allow-Origin": "*",
791
1134
  "Access-Control-Max-Age": "86400",
792
1135
  }
793
1136
  : options?.cors;
@@ -835,9 +1178,9 @@ export async function routeAgentRequest<Env>(
835
1178
  * @param options Routing options
836
1179
  */
837
1180
  export async function routeAgentEmail<Env>(
838
- email: ForwardableEmailMessage,
839
- env: Env,
840
- options?: AgentOptions<Env>
1181
+ _email: ForwardableEmailMessage,
1182
+ _env: Env,
1183
+ _options?: AgentOptions<Env>
841
1184
  ): Promise<void> {}
842
1185
 
843
1186
  /**
@@ -849,7 +1192,7 @@ export async function routeAgentEmail<Env>(
849
1192
  * @param options Options for Agent creation
850
1193
  * @returns Promise resolving to an Agent instance stub
851
1194
  */
852
- export function getAgentByName<Env, T extends Agent<Env>>(
1195
+ export async function getAgentByName<Env, T extends Agent<Env>>(
853
1196
  namespace: AgentNamespace<T>,
854
1197
  name: string,
855
1198
  options?: {
@@ -864,13 +1207,13 @@ export function getAgentByName<Env, T extends Agent<Env>>(
864
1207
  * A wrapper for streaming responses in callable methods
865
1208
  */
866
1209
  export class StreamingResponse {
867
- #connection: Connection;
868
- #id: string;
869
- #closed = false;
1210
+ private _connection: Connection;
1211
+ private _id: string;
1212
+ private _closed = false;
870
1213
 
871
1214
  constructor(connection: Connection, id: string) {
872
- this.#connection = connection;
873
- this.#id = id;
1215
+ this._connection = connection;
1216
+ this._id = id;
874
1217
  }
875
1218
 
876
1219
  /**
@@ -878,17 +1221,17 @@ export class StreamingResponse {
878
1221
  * @param chunk The data to send
879
1222
  */
880
1223
  send(chunk: unknown) {
881
- if (this.#closed) {
1224
+ if (this._closed) {
882
1225
  throw new Error("StreamingResponse is already closed");
883
1226
  }
884
1227
  const response: RPCResponse = {
885
- type: "rpc",
886
- id: this.#id,
887
- success: true,
888
- result: chunk,
889
1228
  done: false,
1229
+ id: this._id,
1230
+ result: chunk,
1231
+ success: true,
1232
+ type: "rpc",
890
1233
  };
891
- this.#connection.send(JSON.stringify(response));
1234
+ this._connection.send(JSON.stringify(response));
892
1235
  }
893
1236
 
894
1237
  /**
@@ -896,17 +1239,17 @@ export class StreamingResponse {
896
1239
  * @param finalChunk Optional final chunk of data to send
897
1240
  */
898
1241
  end(finalChunk?: unknown) {
899
- if (this.#closed) {
1242
+ if (this._closed) {
900
1243
  throw new Error("StreamingResponse is already closed");
901
1244
  }
902
- this.#closed = true;
1245
+ this._closed = true;
903
1246
  const response: RPCResponse = {
904
- type: "rpc",
905
- id: this.#id,
906
- success: true,
907
- result: finalChunk,
908
1247
  done: true,
1248
+ id: this._id,
1249
+ result: finalChunk,
1250
+ success: true,
1251
+ type: "rpc",
909
1252
  };
910
- this.#connection.send(JSON.stringify(response));
1253
+ this._connection.send(JSON.stringify(response));
911
1254
  }
912
1255
  }