Add ContextRouter

.changeset/cold-bears-behave.md

@@ -0,0 +1,5 @@
+---
+"agents": patch
+---
+
+Add unstable_getMcpPrompt to provide LLM consumable MCP integration context

.changeset/sharp-bears-appear.md

@@ -0,0 +1,5 @@
+---
+"agents": patch
+---
+
+Add ContextRouter to allow users to provide an LLM with a list of filtered tools and resources

packages/agents/package.json

@@ -68,6 +68,11 @@
       "types": "./dist/mcp/do-oauth-client-provider.d.ts",
       "require": "./dist/mcp/do-oauth-client-provider.js",
       "import": "./dist/mcp/do-oauth-client-provider.js"
+    },
+    "./mcp/context-router": {
+      "types": "./dist/mcp/context-router.d.ts",
+      "require": "./dist/mcp/context-router.js",
+      "import": "./dist/mcp/context-router.js"
     }
   },
   "keywords": [],

packages/agents/scripts/build.ts

@@ -9,6 +9,7 @@ async function main() {
       "src/mcp/index.ts",
       "src/mcp/client.ts",
       "src/mcp/do-oauth-client-provider.ts",
+      "src/mcp/context-router.ts",
     ],
     splitting: true,
     sourcemap: true,

packages/agents/src/mcp/client-connection.ts

@@ -2,7 +2,6 @@ import { SSEEdgeClientTransport } from "./sse-edge";
 
 import {
   ToolListChangedNotificationSchema,
-  type ClientCapabilities,
   type Resource,
   type Tool,
   type Prompt,
@@ -14,7 +13,7 @@ import {
   type ServerCapabilities,
   type ResourceTemplate,
   type ListResourceTemplatesResult,
-  type Notification,
+  type Implementation,
 } from "@modelcontextprotocol/sdk/types.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { SSEClientTransportOptions } from "@modelcontextprotocol/sdk/client/sse.js";
@@ -34,6 +33,7 @@ export class MCPClientConnection {
   resources: Resource[] = [];
   resourceTemplates: ResourceTemplate[] = [];
   serverCapabilities: ServerCapabilities | undefined;
+  serverInfo: Implementation | undefined;
 
   constructor(
     public url: URL,
@@ -84,20 +84,28 @@ export class MCPClientConnection {
       throw new Error("The MCP Server failed to return server capabilities");
     }
 
-    const [instructions, tools, resources, prompts, resourceTemplates] =
-      await Promise.all([
-        this.client.getInstructions(),
-        this.registerTools(),
-        this.registerResources(),
-        this.registerPrompts(),
-        this.registerResourceTemplates(),
-      ]);
+    const [
+      instructions,
+      serverInfo,
+      tools,
+      resources,
+      prompts,
+      resourceTemplates,
+    ] = await Promise.all([
+      this.client.getInstructions(),
+      this.client.getServerVersion(),
+      this.registerTools(),
+      this.registerResources(),
+      this.registerPrompts(),
+      this.registerResourceTemplates(),
+    ]);
 
     this.instructions = instructions;
     this.tools = tools;
     this.resources = resources;
     this.prompts = prompts;
     this.resourceTemplates = resourceTemplates;
+    this.serverInfo = serverInfo;
 
     this.connectionState = "ready";
   }

packages/agents/src/mcp/client.ts

@@ -17,6 +17,7 @@ import type { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.j
 import type { AgentsOAuthProvider } from "./do-oauth-client-provider";
 import { jsonSchema, type ToolSet } from "ai";
 import { nanoid } from "nanoid";
+import { BaseContextRouter, type ContextRouter } from "./context-router";
 
 /**
  * Utility class that aggregates multiple MCP clients into one
@@ -32,8 +33,11 @@ export class MCPClientManager {
    */
   constructor(
     private _name: string,
-    private _version: string
-  ) {}
+    private _version: string,
+    public unstable_contextRouter: ContextRouter = new BaseContextRouter()
+  ) {
+    this.unstable_contextRouter.clientManager = this;
+  }
 
   /**
    * Connect to and register an MCP server
@@ -176,42 +180,6 @@ export class MCPClientManager {
     return { serverId };
   }
 
-  /**
-   * @returns namespaced list of tools
-   */
-  listTools(): NamespacedData["tools"] {
-    return getNamespacedData(this.mcpConnections, "tools");
-  }
-
-  /**
-   * @returns a set of tools that you can use with the AI SDK
-   */
-  unstable_getAITools(): ToolSet {
-    return Object.fromEntries(
-      getNamespacedData(this.mcpConnections, "tools").map((tool) => {
-        return [
-          `${tool.serverId}_${tool.name}`,
-          {
-            parameters: jsonSchema(tool.inputSchema),
-            description: tool.description,
-            execute: async (args) => {
-              const result = await this.callTool({
-                name: tool.name,
-                arguments: args,
-                serverId: tool.serverId,
-              });
-              if (result.isError) {
-                // @ts-expect-error TODO we should fix this
-                throw new Error(result.content[0].text);
-              }
-              return result;
-            },
-          },
-        ];
-      })
-    );
-  }
-
   /**
    * Closes all connections to MCP servers
    */
@@ -235,17 +203,31 @@ export class MCPClientManager {
   }
 
   /**
-   * @returns namespaced list of prompts
+   * @returns namespaced list of tools
    */
-  listPrompts(): NamespacedData["prompts"] {
-    return getNamespacedData(this.mcpConnections, "prompts");
+  listTools(): NamespacedData["tools"] {
+    return this.unstable_contextRouter.listTools();
+  }
+
+  /**
+   * @returns a set of tools that you can use with the AI SDK
+   */
+  unstable_getAITools(): ToolSet {
+    return this.unstable_contextRouter.getAITools();
   }
 
   /**
    * @returns namespaced list of tools
    */
   listResources(): NamespacedData["resources"] {
-    return getNamespacedData(this.mcpConnections, "resources");
+    return this.unstable_contextRouter.listResources();
+  }
+
+  /**
+   * @returns namespaced list of prompts
+   */
+  listPrompts(): NamespacedData["prompts"] {
+    return getNamespacedData(this.mcpConnections, "prompts");
   }
 
   /**
@@ -301,9 +283,18 @@ export class MCPClientManager {
       options
     );
   }
+
+  /**
+   * Utility function to fetch MCP information which you can add to an LLM's system prompt.
+   *
+   * @param includeResources Whether to include resources in the prompt. This may be useful if you include a tool to fetch resources OR if the servers you connect to interact with resources.
+   */
+  unstable_systemPrompt(): string {
+    return this.unstable_contextRouter.systemPrompt();
+  }
 }
 
-type NamespacedData = {
+export type NamespacedData = {
   tools: (Tool & { serverId: string })[];
   prompts: (Prompt & { serverId: string })[];
   resources: (Resource & { serverId: string })[];