@genkit-ai/mcp 1.33.0 → 1.35.0

package/src/client/host.ts

@@ -20,13 +20,14 @@ import {
   type DynamicResourceAction,
   type ExecutablePrompt,
   type Genkit,
+  type MultipartToolAction,
   type PromptGenerateOptions,
   type ToolAction,
 } from 'genkit';
 import { logger } from 'genkit/logging';
 import { GenkitMcpClient, McpServerConfig } from './client.js';
 
-export interface McpHostOptions {
+export interface McpHostOptions<M extends boolean = false> {
   /**
    * An optional client name for this MCP host. This name is advertised to MCP Servers
    * as the connecting client name. Defaults to 'genkit-mcp'.
@@ -52,13 +53,19 @@ export interface McpHostOptions {
    */
   rawToolResponses?: boolean;
 
+  /** If true, tools will be registered as multipart tool.v2 actions. */
+  multipart?: M;
+
   /**
    * When provided, each connected MCP server will be sent the roots specified here. Overridden by any specific roots sent in the `mcpServers` config for a given server.
    */
   roots?: Root[];
 }
 
-export type McpHostOptionsWithCache = Omit<McpHostOptions, 'name'> & {
+export type McpHostOptionsWithCache<M extends boolean = false> = Omit<
+  McpHostOptions<M>,
+  'name'
+> & {
   /**
    * A client name for this MCP host. This name is advertised to MCP Servers
    * as the connecting client name.
@@ -92,9 +99,9 @@ interface ClientState {
  * It allows for dynamic registration of tools from all connected and enabled MCP servers
  * into a Genkit instance.
  */
-export class GenkitMcpHost {
+export class GenkitMcpHost<Multipart extends boolean = false> {
   name: string;
-  private _clients: Record<string, GenkitMcpClient> = {};
+  private _clients: Record<string, GenkitMcpClient<Multipart>> = {};
   private _clientStates: Record<string, ClientState> = {};
   private _readyListeners: {
     resolve: () => void;
@@ -104,10 +111,12 @@ export class GenkitMcpHost {
   private _dynamicActionProvider: DynamicActionProviderAction | undefined;
   private roots: Root[] | undefined;
   rawToolResponses?: boolean;
+  multipart?: Multipart;
 
-  constructor(options: McpHostOptions) {
+  constructor(options: McpHostOptions<Multipart>) {
     this.name = options.name || 'genkit-mcp';
     this.rawToolResponses = options.rawToolResponses;
+    this.multipart = options.multipart;
     this.roots = options.roots;
 
     if (options.mcpServers) {
@@ -165,11 +174,12 @@ export class GenkitMcpHost {
       `[MCP Host] Connecting to MCP server '${serverName}' in host '${this.name}'.`
     );
     try {
-      const client = new GenkitMcpClient({
+      const client = new GenkitMcpClient<Multipart>({
         name: this.name,
         serverName: serverName,
         mcpServer: { ...config, roots: config.roots || this.roots },
         rawToolResponses: this.rawToolResponses,
+        multipart: this.multipart,
       });
       this._clients[serverName] = client;
     } catch (e) {
@@ -353,9 +363,13 @@ export class GenkitMcpHost {
    * @returns A Promise that resolves to an array of `ToolAction` from all
    * active MCP clients.
    */
-  async getActiveTools(ai: Genkit): Promise<ToolAction[]> {
+  async getActiveTools(
+    ai: Genkit
+  ): Promise<(Multipart extends true ? MultipartToolAction : ToolAction)[]> {
     await this.ready();
-    let allTools: ToolAction[] = [];
+    let allTools: (Multipart extends true
+      ? MultipartToolAction
+      : ToolAction)[] = [];
 
     for (const serverName in this._clients) {
       const client = this._clients[serverName];
@@ -510,7 +524,7 @@ export class GenkitMcpHost {
   /**
    * Returns an array of all active clients.
    */
-  get activeClients(): GenkitMcpClient[] {
+  get activeClients(): GenkitMcpClient<Multipart>[] {
     return Object.values(this._clients).filter((c) => c.isEnabled());
   }
 

package/src/index.ts

@@ -70,8 +70,10 @@ export interface McpServerOptions {
  * @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 createMcpHost(options: McpHostOptions) {
-  return new GenkitMcpHost(options);
+export function createMcpHost<M extends boolean = false>(
+  options: McpHostOptions<M>
+) {
+  return new GenkitMcpHost<M>(options);
 }
 
 /**
@@ -97,8 +99,11 @@ export function createMcpHost(options: McpHostOptions) {
  * @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);
+export function defineMcpHost<M extends boolean = false>(
+  ai: Genkit,
+  options: McpHostOptionsWithCache<M>
+) {
+  const mcpHost = new GenkitMcpHost<M>(options);
   const dap = ai.defineDynamicActionProvider(
     {
       name: options.name,
@@ -135,8 +140,10 @@ export function defineMcpHost(ai: Genkit, options: McpHostOptionsWithCache) {
  *                to the MCP server and its behavior.
  * @returns A new instance of GenkitMcpClient.
  */
-export function createMcpClient(options: McpClientOptions) {
-  return new GenkitMcpClient(options);
+export function createMcpClient<M extends boolean = false>(
+  options: McpClientOptions<M>
+) {
+  return new GenkitMcpClient<M>(options);
 }
 
 /**
@@ -165,11 +172,11 @@ export function createMcpClient(options: McpClientOptions) {
  *                to the MCP server and its behavior.
  * @returns A new instance of GenkitMcpClient.
  */
-export function defineMcpClient(
+export function defineMcpClient<M extends boolean = false>(
   ai: Genkit,
-  options: McpClientOptionsWithCache
+  options: McpClientOptionsWithCache<M>
 ) {
-  const mcpClient = new GenkitMcpClient(options);
+  const mcpClient = new GenkitMcpClient<M>(options);
   const dap = ai.defineDynamicActionProvider(
     {
       name: options.name,

package/src/util/tools.ts

@@ -19,7 +19,15 @@ import type {
   CallToolResult,
   Tool,
 } from '@modelcontextprotocol/sdk/types.js' with { 'resolution-mode': 'import' };
-import { JSONSchema7, z, type Genkit, type ToolAction } from 'genkit';
+import {
+  JSONSchema7,
+  tool as genkitTool,
+  z,
+  type Genkit,
+  type MultipartToolAction,
+  type Part,
+  type ToolAction,
+} from 'genkit';
 import { logger } from 'genkit/logging';
 
 const toText = (c: CallToolResult['content']) =>
@@ -27,6 +35,9 @@ const toText = (c: CallToolResult['content']) =>
 
 function processResult(result: CallToolResult) {
   if (result.isError) return { error: toText(result.content) };
+  if (result.structuredContent !== undefined) {
+    return result.structuredContent;
+  }
   if (result.content.every((c) => c.type === 'text' && !!c.text)) {
     const text = toText(result.content);
     if (text.trim().startsWith('{') || text.trim().startsWith('[')) {
@@ -42,6 +53,81 @@ function processResult(result: CallToolResult) {
   return result;
 }
 
+function processMultipartResult(result: CallToolResult) {
+  if (result.isError) {
+    return {
+      output: { error: toText(result.content) },
+      metadata: result._meta,
+    };
+  }
+
+  const content: Part[] = [];
+  let textOutput = '';
+
+  for (const c of result.content) {
+    if (c.type === 'text') {
+      if (c.text) {
+        textOutput += c.text;
+      }
+    } else if (c.type === 'image' || c.type === 'audio') {
+      if (c.data) {
+        content.push({
+          media: {
+            url: `data:${c.mimeType};base64,${c.data}`,
+            contentType: c.mimeType,
+          },
+        });
+      }
+    } else if (c.type === 'resource_link') {
+      if (c.uri) {
+        content.push({
+          resource: {
+            uri: c.uri,
+          },
+        });
+      }
+    } else if (c.type === 'resource') {
+      if (c.resource) {
+        if ('text' in c.resource && c.resource.text) {
+          textOutput +=
+            (textOutput ? '\n\n' : '') +
+            `Resource (${c.resource.uri}):\n${c.resource.text}`;
+        } else if ('blob' in c.resource && c.resource.blob) {
+          content.push({
+            media: {
+              url: `data:${c.resource.mimeType};base64,${c.resource.blob}`,
+              contentType: c.resource.mimeType,
+            },
+          });
+        }
+      }
+    }
+  }
+
+  let output: unknown = result.structuredContent;
+
+  if (output === undefined && textOutput) {
+    if (
+      textOutput.trim().startsWith('{') ||
+      textOutput.trim().startsWith('[')
+    ) {
+      try {
+        output = JSON.parse(textOutput);
+      } catch (e) {
+        output = textOutput;
+      }
+    } else {
+      output = textOutput;
+    }
+  }
+
+  return {
+    ...(output !== undefined ? { output } : {}),
+    ...(content.length > 0 ? { content } : {}),
+    metadata: result._meta,
+  };
+}
+
 /**
  * Registers a single MCP tool as a Genkit tool.
  * It defines a new Genkit tool action that, when called, will
@@ -57,32 +143,69 @@ function registerTool(
   ai: Genkit,
   client: Client,
   tool: Tool,
-  params: { serverName: string; name: string; rawToolResponses?: boolean }
+  params: {
+    serverName: string;
+    name: string;
+    rawToolResponses?: boolean;
+    multipart?: boolean;
+  }
 ) {
   logger.debug(
-    `[MCP] Registering tool '${params.name}/${tool.name}'' from server '${params.serverName}'`
-  );
-  ai.defineTool(
-    {
-      name: `${params.serverName}/${tool.name}`,
-      description: tool.description || '',
-      inputJsonSchema: tool.inputSchema as JSONSchema7,
-      outputSchema: z.any(),
-      metadata: { mcp: { _meta: tool._meta || {} } },
-    },
-    async (args) => {
-      logger.debug(
-        `[MCP] Calling MCP tool '${params.serverName}/${tool.name}' with arguments`,
-        JSON.stringify(args)
-      );
-      const result = await client.callTool({
-        name: tool.name,
-        arguments: args,
-      });
-      if (params.rawToolResponses) return result;
-      return processResult(result as CallToolResult);
-    }
+    `[MCP] Registering tool '${params.name}/${tool.name}' from server '${params.serverName}'`
   );
+  if (params.multipart && params.rawToolResponses) {
+    logger.warn(
+      `[MCP] Tool '${params.serverName}/${tool.name}' is configured with both multipart and rawToolResponses. Genkit will return the raw MCP CallToolResult in the output field, and media parts will not be natively parsed.`
+    );
+  }
+  if (params.multipart) {
+    ai.defineTool(
+      {
+        name: `${params.serverName}/${tool.name}`,
+        description: tool.description || '',
+        inputJsonSchema: tool.inputSchema as JSONSchema7,
+        outputSchema: z.any(),
+        metadata: { mcp: { _meta: tool._meta || {} } },
+        multipart: true as const,
+      },
+      async (args, { context }) => {
+        logger.debug(
+          `[MCP] Calling MCP tool '${params.serverName}/${tool.name}' with arguments`,
+          JSON.stringify(args)
+        );
+        const result = await client.callTool({
+          name: tool.name,
+          arguments: args,
+          _meta: context?.mcp?._meta,
+        });
+        if (params.rawToolResponses) return { output: result };
+        return processMultipartResult(result as CallToolResult);
+      }
+    );
+  } else {
+    ai.defineTool(
+      {
+        name: `${params.serverName}/${tool.name}`,
+        description: tool.description || '',
+        inputJsonSchema: tool.inputSchema as JSONSchema7,
+        outputSchema: z.any(),
+        metadata: { mcp: { _meta: tool._meta || {} } },
+      },
+      async (args, { context }) => {
+        logger.debug(
+          `[MCP] Calling MCP tool '${params.serverName}/${tool.name}' with arguments`,
+          JSON.stringify(args)
+        );
+        const result = await client.callTool({
+          name: tool.name,
+          arguments: args,
+          _meta: context?.mcp?._meta,
+        });
+        if (params.rawToolResponses) return result;
+        return processResult(result as CallToolResult);
+      }
+    );
+  }
 }
 
 /**
@@ -96,13 +219,48 @@ function registerTool(
  * @param params Configuration parameters including namespacing and raw response flag.
  * @returns A Genkit `ToolAction` representing the MCP tool.
  */
-function createDynamicTool(
+function createDynamicTool<Multipart extends boolean = false>(
   ai: Genkit,
   client: Client,
   tool: Tool,
-  params: { serverName: string; name: string; rawToolResponses?: boolean }
-): ToolAction {
-  return ai.dynamicTool(
+  params: {
+    serverName: string;
+    name: string;
+    rawToolResponses?: boolean;
+    multipart?: Multipart;
+  }
+): Multipart extends true ? MultipartToolAction : ToolAction {
+  if (params.multipart && params.rawToolResponses) {
+    logger.warn(
+      `[MCP] Tool '${params.serverName}/${tool.name}' is configured with both multipart and rawToolResponses. Genkit will return the raw MCP CallToolResult in the output field, and media parts will not be natively parsed.`
+    );
+  }
+  if (params.multipart) {
+    return genkitTool(
+      {
+        name: `${params.serverName}/${tool.name}`,
+        description: tool.description || '',
+        inputJsonSchema: tool.inputSchema as JSONSchema7,
+        outputSchema: z.any(),
+        metadata: { mcp: { _meta: tool._meta || {} } },
+        multipart: true as const,
+      },
+      async (args, { context }) => {
+        logger.debug(
+          `[MCP] calling tool '${params.serverName}/${tool.name}' in host '${params.name}'`
+        );
+        const result = await client.callTool({
+          name: tool.name,
+          arguments: args,
+          _meta: context?.mcp?._meta,
+        });
+        if (params.rawToolResponses) return { output: result };
+        return processMultipartResult(result as CallToolResult);
+      }
+    ) as unknown as Multipart extends true ? MultipartToolAction : ToolAction;
+  }
+
+  return genkitTool(
     {
       name: `${params.serverName}/${tool.name}`,
       description: tool.description || '',
@@ -119,10 +277,10 @@ function createDynamicTool(
         arguments: args,
         _meta: context?.mcp?._meta,
       });
-      if (params.rawToolResponses) return result;
+      if (params.rawToolResponses) return result as CallToolResult;
       return processResult(result as CallToolResult);
     }
-  );
+  ) as unknown as Multipart extends true ? MultipartToolAction : ToolAction;
 }
 
 /**
@@ -131,7 +289,12 @@ function createDynamicTool(
 export async function registerAllTools(
   ai: Genkit,
   client: Client,
-  params: { name: string; serverName: string; rawToolResponses?: boolean }
+  params: {
+    name: string;
+    serverName: string;
+    rawToolResponses?: boolean;
+    multipart?: boolean;
+  }
 ): Promise<void> {
   let cursor: string | undefined;
   while (true) {
@@ -145,13 +308,19 @@ export async function registerAllTools(
 /**
  * Lookup all tools available in the server and fetches as a Genkit dynamic tool.
  */
-export async function fetchDynamicTools(
+export async function fetchDynamicTools<Multipart extends boolean = false>(
   ai: Genkit,
   client: Client,
-  params: { name: string; serverName: string; rawToolResponses?: boolean }
-): Promise<ToolAction[]> {
+  params: {
+    name: string;
+    serverName: string;
+    rawToolResponses?: boolean;
+    multipart?: Multipart;
+  }
+): Promise<(Multipart extends true ? MultipartToolAction : ToolAction)[]> {
   let cursor: string | undefined;
-  let allTools: ToolAction[] = [];
+  let allTools: (Multipart extends true ? MultipartToolAction : ToolAction)[] =
+    [];
   while (true) {
     const { nextCursor, tools } = await client.listTools({ cursor });
     allTools.push(

package/tests/host_test.ts

@@ -251,12 +251,162 @@ describe('createMcpHost', () => {
         ],
       };
 
-      const tool = (await clientHost.getActiveTools(ai))[0];
+      const tool: ToolAction = (await clientHost.getActiveTools(ai))[0];
       const response = await tool({
         foo: 'bar',
       });
       assert.deepStrictEqual(response, 'yep {"foo":"bar"}');
     });
+
+    it('should call the multipart tool', async () => {
+      const multipartHost = createMcpHost({
+        name: 'test-multipart-host',
+        multipart: true,
+        mcpServers: {
+          'test-server': {
+            transport: fakeTransport,
+          },
+        },
+      });
+      await multipartHost.ready();
+
+      fakeTransport.callToolResult = {
+        content: [
+          {
+            type: 'text',
+            text: 'yep {"foo":"bar"}',
+          },
+          {
+            type: 'image',
+            data: 'base64data',
+            mimeType: 'image/png',
+          },
+          {
+            type: 'resource',
+            resource: {
+              uri: 'file:///foo.txt',
+              text: 'hello resource',
+            },
+          },
+          {
+            type: 'resource',
+            resource: {
+              uri: 'file:///blob.bin',
+              blob: 'base64blob',
+              mimeType: 'application/octet-stream',
+            },
+          },
+        ],
+        _meta: {
+          someData: true,
+        },
+      };
+
+      const tools = await multipartHost.getActiveTools(ai);
+      const tool = tools[0];
+      const response = await tool(
+        { foo: 'bar' },
+        { context: { mcp: { _meta: { soMeta: true } } } }
+      );
+
+      assert.deepStrictEqual(response, {
+        output:
+          'yep {"foo":"bar"}\n\nResource (file:///foo.txt):\nhello resource{"soMeta":true}',
+        content: [
+          {
+            media: {
+              url: 'data:image/png;base64,base64data',
+              contentType: 'image/png',
+            },
+          },
+          {
+            media: {
+              url: 'data:application/octet-stream;base64,base64blob',
+              contentType: 'application/octet-stream',
+            },
+          },
+        ],
+        metadata: {
+          someData: true,
+        },
+      });
+    });
+
+    it('should call the multipart tool and handle errors', async () => {
+      const multipartHost = createMcpHost({
+        name: 'test-multipart-host',
+        multipart: true,
+        mcpServers: {
+          'test-server': {
+            transport: fakeTransport,
+          },
+        },
+      });
+      await multipartHost.ready();
+
+      fakeTransport.callToolResult = {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: 'Simulated tool failure',
+          },
+        ],
+        _meta: {
+          errorCode: 500,
+        },
+      };
+
+      const tools = await multipartHost.getActiveTools(ai);
+      const tool = tools[0];
+      const response = await tool({ foo: 'bar' });
+
+      assert.deepStrictEqual(response, {
+        output: { error: 'Simulated tool failure' },
+        metadata: {
+          errorCode: 500,
+        },
+      });
+    });
+
+    it('should return raw tool response when rawToolResponses is true alongside multipart', async () => {
+      const multipartHost = createMcpHost({
+        name: 'test-multipart-host',
+        multipart: true,
+        rawToolResponses: true,
+        mcpServers: {
+          'test-server': {
+            transport: fakeTransport,
+          },
+        },
+      });
+      await multipartHost.ready();
+
+      fakeTransport.callToolResult = {
+        content: [
+          {
+            type: 'text',
+            text: 'yep {"foo":"bar"}',
+          },
+        ],
+      };
+
+      const tools = await multipartHost.getActiveTools(ai);
+      const tool = tools[0];
+      const response = await tool({ foo: 'bar' });
+
+      // Genkit output schema for multipart expects `{ output: ... }` when returning raw responses
+      assert.deepStrictEqual(response, {
+        output: {
+          content: [
+            {
+              type: 'text',
+              text: 'yep {"foo":"bar"}',
+            },
+          ],
+        },
+      });
+    });
   });
 
   describe('prompts', () => {