@genkit-ai/mcp 1.20.0 → 1.22.0-rc.0

package/src/client/host.ts

@@ -16,6 +16,7 @@
 
 import { Root } from '@modelcontextprotocol/sdk/types.js';
 import {
+  type DynamicActionProviderAction,
   type DynamicResourceAction,
   type ExecutablePrompt,
   type Genkit,
@@ -57,6 +58,24 @@ export interface McpHostOptions {
   roots?: Root[];
 }
 
+export type McpHostOptionsWithCache = Omit<McpHostOptions, 'name'> & {
+  /**
+   * A client name for this MCP host. This name is advertised to MCP Servers
+   * as the connecting client name.
+   */
+  name: string;
+
+  /**
+   * Cache TTL. The dynamic action provider has a cache for the available actions
+   * The default TTL is 3 seconds.
+   * The cache will automatically be invalidated if any connections change.
+   *   Negative = no caching (expect noisy traces and slower resolution)
+   *   Zero or undefined = use the default 3000 millis (3 seconds)
+   *   Positive: The number of milliseconds to keep the cache.
+   */
+  cacheTTLMillis?: number;
+};
+
 /** Internal representation of client state for logging. */
 interface ClientState {
   error?: {
@@ -82,6 +101,7 @@ export class GenkitMcpHost {
     reject: (err: Error) => void;
   }[] = [];
   private _ready = false;
+  private _dynamicActionProvider: DynamicActionProviderAction | undefined;
   private roots: Root[] | undefined;
   rawToolResponses?: boolean;
 
@@ -97,6 +117,16 @@ export class GenkitMcpHost {
     }
   }
 
+  set dynamicActionProvider(dap: DynamicActionProviderAction) {
+    this._dynamicActionProvider = dap;
+  }
+
+  _invalidateCache(): void {
+    if (this._dynamicActionProvider) {
+      this._dynamicActionProvider.invalidateCache();
+    }
+  }
+
   /**
    * Returns a Promise that resolves when the host has attempted to connect
    * to all configured clients, or rejects if a critical error occurs during
@@ -148,6 +178,7 @@ export class GenkitMcpHost {
         detail: `Details: ${e}`,
       });
     }
+    this._invalidateCache();
   }
 
   /**
@@ -175,6 +206,7 @@ export class GenkitMcpHost {
       });
     }
     delete this._clients[serverName];
+    this._invalidateCache();
   }
 
   /**
@@ -198,6 +230,7 @@ export class GenkitMcpHost {
       `[MCP Host] Disabling MCP server '${serverName}' in host '${this.name}'`
     );
     await client.disable();
+    this._invalidateCache();
   }
 
   /**
@@ -224,6 +257,7 @@ export class GenkitMcpHost {
         detail: `Details: ${e}`,
       });
     }
+    this._invalidateCache();
   }
 
   /**
@@ -251,6 +285,7 @@ export class GenkitMcpHost {
         detail: `Details: ${e}`,
       });
     }
+    this._invalidateCache();
   }
 
   /**
@@ -290,6 +325,8 @@ export class GenkitMcpHost {
           this._readyListeners.pop()?.reject(err);
         }
       });
+
+    this._invalidateCache();
   }
 
   /**
@@ -446,6 +483,7 @@ export class GenkitMcpHost {
     for (const client of Object.values(this._clients)) {
       await client._disconnect();
     }
+    this._invalidateCache();
   }
 
   /** Helper method to track and log client errors. */

package/src/client/index.ts

@@ -18,11 +18,16 @@ import { SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.
 import { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { GenkitMcpClient, McpClientOptions } from './client.js';
-import { GenkitMcpHost, McpHostOptions } from './host.js';
+import {
+  GenkitMcpHost,
+  McpHostOptions,
+  McpHostOptionsWithCache,
+} from './host.js';
 export { GenkitMcpClient, GenkitMcpHost };
 export type {
   McpClientOptions,
   McpHostOptions,
+  McpHostOptionsWithCache,
   SSEClientTransportOptions,
   StdioServerParameters,
   Transport,

package/src/index.ts

@@ -18,16 +18,23 @@ import type { Genkit } from 'genkit';
 import {
   GenkitMcpClient,
   McpClientOptions,
+  McpClientOptionsWithCache,
   McpServerConfig,
   McpStdioServerConfig,
 } from './client/client.js';
-import { GenkitMcpHost, McpHostOptions } from './client/index.js';
+import {
+  GenkitMcpHost,
+  McpHostOptions,
+  McpHostOptionsWithCache,
+} from './client/index.js';
 import { GenkitMcpServer } from './server.js';
 export {
   GenkitMcpClient,
   GenkitMcpHost,
   type McpClientOptions,
+  type McpClientOptionsWithCache,
   type McpHostOptions,
+  type McpHostOptionsWithCache,
   type McpServerConfig,
   type McpStdioServerConfig,
 };
@@ -67,6 +74,47 @@ export function createMcpHost(options: McpHostOptions) {
   return new GenkitMcpHost(options);
 }
 
+/**
+ * Creates an MCP Client Host that connects to one or more MCP servers.
+ * Each server is defined in the `mcpClients` option, where the key is a
+ * client-side name for the server and the value is the server's configuration.
+ *
+ * By default, all servers in the config will be attempted to connect unless
+ * their configuration includes `{disabled: true}`.
+ *
+ * ```ts
+ * const clientHost = defineMcpHost(ai, {
+ *   name: "my-mcp-client-host", // Name for the host itself
+ *   mcpServers: {
+ *     // Each key is a name for this client/server configuration
+ *     // Each value is an McpServerConfig object
+ *     gitToolServer: { command: "uvx", args: ["mcp-server-git"] },
+ *     customApiServer: { url: "http://localhost:1234/mcp" }
+ *   }
+ * });
+ * ```
+ *
+ * @param options Configuration for the MCP Client Host, including the definitions of MCP servers to connect to.
+ * @returns A new instance of GenkitMcpHost.
+ */
+export function defineMcpHost(ai: Genkit, options: McpHostOptionsWithCache) {
+  const mcpHost = new GenkitMcpHost(options);
+  const dap = ai.defineDynamicActionProvider(
+    {
+      name: options.name,
+      cacheConfig: {
+        ttlMillis: options.cacheTTLMillis,
+      },
+    },
+    async () => ({
+      tool: await mcpHost.getActiveTools(ai),
+      resource: await mcpHost.getActiveResources(ai),
+    })
+  );
+  mcpHost.dynamicActionProvider = dap;
+  return mcpHost;
+}
+
 /**
  * Creates an MCP Client that connects to a single MCP server.
  * This is useful when you only need to interact with one MCP server,
@@ -91,6 +139,55 @@ export function createMcpClient(options: McpClientOptions) {
   return new GenkitMcpClient(options);
 }
 
+/**
+ * Defines an MCP Client that connects to a single MCP server.
+ * This is useful when you only need to interact with one MCP server,
+ * or if you want to manage client instances individually.
+ *
+ * ```ts
+ * const client = defineMcpClient(ai, {
+ *   name: "mySingleMcpClient", // A name for this client instance
+ *   command: "npx", // Example: Launching a local server
+ *   args: ["-y", "@modelcontextprotocol/server-everything", "/path/to/allowed/dir"],
+ * });
+ *
+ * // To get tools from this client:
+ * // const tools = await client.getActiveTools(ai);
+ *
+ * // Or in a generate call you can use:
+ * ai.generate({
+    prompt: `<a prompt requiring tools>`,
+    tools: ['mySingleMcpClient:tool/*'],
+  });
+ * ```
+ *
+ * @param options Configuration for the MCP Client, defining how it connects
+ *                to the MCP server and its behavior.
+ * @returns A new instance of GenkitMcpClient.
+ */
+export function defineMcpClient(
+  ai: Genkit,
+  options: McpClientOptionsWithCache
+) {
+  const mcpClient = new GenkitMcpClient(options);
+  const dap = ai.defineDynamicActionProvider(
+    {
+      name: options.name,
+      cacheConfig: {
+        ttlMillis: options.cacheTtlMillis,
+      },
+    },
+    async () => {
+      return {
+        tool: await mcpClient.getActiveTools(ai),
+        resource: await mcpClient.getActiveResources(ai),
+      };
+    }
+  );
+  mcpClient.dynamicActionProvider = dap;
+  return mcpClient;
+}
+
 /**
  * Creates an MCP server based on the supplied Genkit instance. All tools and prompts
  * will be automatically converted to MCP compatibility.

package/src/server.ts

@@ -444,7 +444,7 @@ function toMcpResourceMessage(
       if (!url.startsWith('data:'))
         throw new GenkitError({
           status: 'UNIMPLEMENTED',
-          message: `[MCP Server] MCP prompt messages only support base64 data images.`,
+          message: `[MCP Server] MCP resource messages only support base64 data images.`,
         });
       const mimeType =
         contentType || url.substring(url.indexOf(':')! + 1, url.indexOf(';'));
@@ -455,7 +455,7 @@ function toMcpResourceMessage(
     } else {
       throw new GenkitError({
         status: 'UNIMPLEMENTED',
-        message: `[MCP Server] MCP prompt messages only support media and text parts.`,
+        message: `[MCP Server] MCP resource messages only support media and text parts.`,
       });
     }
   });