Genkit MCP

参见 Genkit MCP 文档。

此插件提供了 Genkit 和 模型上下文协议 (MCP) 之间的集成。MCP 是一个开放标准，允许开发者构建提供工具、资源和提示给客户端的“服务器”。Genkit MCP 允许 Genkit 开发者：

• 使用 createMcpHost 或 createMcpClient 作为客户端来消费 MCP 工具、提示和资源。
• 使用 createMcpServer 提供 Genkit 工具和提示作为 MCP 服务器。

安装

要开始，请安装 Genkit 和 MCP 插件：

npm i genkit @genkit-ai/mcp

MCP 主机

要连接到一个或多个 MCP 服务器，您需要使用 createMcpHost 函数。该函数返回一个 GenkitMcpHost 实例，用于管理与配置的 MCP 服务器的连接。

import { googleAI } from '@genkit-ai/google-genai';
import { createMcpHost } from '@genkit-ai/mcp';
import { genkit } from 'genkit';

const mcpHost = createMcpHost({
  name: 'myMcpClients', // 主机插件本身的名称
  mcpServers: {
    // 每个键（例如 'fs', 'git'）成为服务器工具的命名空间。
    fs: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', process.cwd()],
    },
    memory: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-memory'],
    },
  },
});

const ai = genkit({
  plugins: [googleAI()],
});

(async () => {
  // 向您选择的模型提供 MCP 工具。
  const { text } = await ai.generate({
    model: googleAI.model('gemini-2.0-flash'),
    prompt: `分析 ${process.cwd()} 中的所有文件.`,
    tools: await mcpHost.getActiveTools(ai),
    resources: await mcpHost.getActiveResources(ai),
  });

  console.log(text);

  await mcpHost.close();
})();

createMcpHost 函数初始化一个 GenkitMcpHost 实例，该实例处理与定义的 MCP 服务器的生命周期和通信。

createMcpHost() 选项

• name: (可选，字符串) 主机插件本身的名称。默认值为 'genkitx-mcp'。
• version: (可选，字符串) MCP 主机插件的版本。默认值为 "1.0.0"。
• rawToolResponses: (可选，布尔值) 当设置为 true 时，工具响应将以原始 MCP 格式返回；否则，它们将被处理以适应 Genkit。默认值为 false。
• mcpServers: (必需，对象) 每个键是 MCP 服务器的客户端侧名称（命名空间），值是该服务器的配置。

每个服务器配置对象可以包括：

• disabled: (可选，布尔值) 如果设置为 true，则不会尝试建立此服务器连接。默认值为 false。
• 以下之一的服务器连接配置：
  • 使用 stdio MCP 运输启动本地服务器进程的参数。
    • command: (必需，字符串) 启动 MCP 服务器的 shell 命令路径（例如，npx，python）。
    • args: (可选，字符串数组) 要传递给命令的字符串参数数组。
    • env: (可选，字符串键值对对象) 环境变量。
  • url: (字符串) 使用 Streamable HTTP MCP 运输连接的远程服务器的 URL。
  • transport: 用于连接到服务器的现有 MCP 运输对象。

MCP 客户端（单个服务器）

在只需要连接到单个 MCP 服务器或希望单独管理客户端实例的情况下，您可以使用 createMcpClient。

import { googleAI } from '@genkit-ai/google-genai';
import { createMcpClient } from '@genkit-ai/mcp';
import { genkit } from 'genkit';

const myFsClient = createMcpClient({
  name: 'myFileSystemClient', // 此客户端实例的唯一名称
  mcpServer: {
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', process.cwd()],
  },
  // rawToolResponses: true, // 可选：获取原始 MCP 响应
});

// 在您的 Genkit 配置中：
const ai = genkit({
  plugins: [googleAI()],
});

(async () => {
  await myFsClient.ready();

  // 从此特定客户端检索工具
  const fsTools = await myFsClient.getActiveTools(ai);

  const { text } = await ai.generate({
    model: googleAI.model('gemini-2.0-flash'), // 替换为您自己的模型
    prompt: '列出 ' + process.cwd() + ' 中的文件',
    tools: fsTools,
  });
  console.log(text);

  await myFsClient.disable();
})();

createMcpClient() 选项

createMcpClient 函数接受一个 McpClientOptions 对象：

• name: (必需，字符串) 此客户端实例的唯一名称。此名称将用作其工具和提示的命名空间。
• version: (可选，字符串) 此客户端实例的版本。默认值为 "1.0.0"。
• 此外，它支持所有来自 McpServerConfig 的选项（例如，disabled，rawToolResponses 和运输配置），如 createMcpHost 选项部分所述。

使用 MCP 动作（工具、提示）

GenkitMcpHost（通过 getActiveTools()）和 GenkitMcpClient（通过 getActiveTools()）从其连接并启用的 MCP 服务器发现可用工具。这些工具是标准的 Genkit ToolAction 实例，并且可以提供给 Genkit 模型。

MCP 提示可以通过 McpHost.getPrompt(serverName, promptName) 或 mcpClient.getPrompt(promptName) 获取。这些返回一个 ExecutablePrompt。

所有 MCP 动作（工具、提示、资源）都是命名空间化的。

• 对于 createMcpHost，命名空间是您在 mcpServers 配置中为此服务器提供的键（例如，localFs/read_file）。
• 对于 createMcpClient，命名空间是您在其选项中提供的 name（例如，myFileSystemClient/list_resources）。

工具响应

MCP 工具返回一个 content 数组，而不是像大多数 Genkit 工具那样的结构化响应。Genkit MCP 插件试图解析并转换返回的内容：

1. 如果内容是文本并且是有效的 JSON，则将其解析并返回为 JSON 对象。
2. 如果内容是文本但不是有效的 JSON，则返回原始文本。
3. 如果内容包含单一非文本部分（例如，一张图片），则直接返回该部分。
4. 如果内容包含多个或混合部分（例如，文本和图片），则返回完整的 content 响应数组。

MCP 服务器

您还可以使用 createMcpServer 函数将 Genkit 实例中的所有工具和提示暴露为 MCP 服务器。

import { googleAI } from '@genkit-ai/google-genai';
import { createMcpServer } from '@genkit-ai/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { genkit, z } from 'genkit/beta';

const ai = genkit({
  plugins: [googleAI()],
});

ai.defineTool(
  {
    name: 'add',
    description: '将两个数字相加',
    inputSchema: z.object({ a: z.number(), b: z.number() }),
    outputSchema: z.number(),
  },
  async ({ a, b }) => {
    return a + b;
  }
);

ai.definePrompt(
  {
    name: 'happy',
    description: '大家一起来',
    input: {
      schema: z.object({
        action: z.string().default('拍手').optional(),
      }),
    },
  },
  `如果你们开心并且知道，{{action}}。`
);

ai.defineResource(
  {
    name: '我的资源',
    uri: 'my://resource',
  },
  async () => {
    return {
      content: [
        {
          text: '我的资源',
        },
      ],
    };
  }
);

ai.defineResource(
  {
    name: '文件',
    template: 'file://{path}',
  },
  async ({ uri }) => {
    return {
      content: [
        {
          text: `文件内容为 ${uri}`,
        },
      ],
    };
  }
);

// 使用 createMcpServer
const server = createMcpServer(ai, {
  name: 'example_server',
  version: '0.0.1',
});
// 设置（异步）然后默认使用 stdio 运输启动
server.setup().then(async () => {
  await server.start();
  const transport = new StdioServerTransport();
  await server!.server?.connect(transport);
});

createMcpServer 函数返回一个 GenkitMcpServer 实例。此实例上的 start() 方法将启动一个 MCP 服务器（默认使用 stdio 运输），该服务器公开所有注册的 Genkit 工具和提示。要使用不同的 MCP 运输启动服务器，您可以将运输实例传递给 start() 方法（例如，server.start(customMcpTransport)）。

createMcpServer() 选项

• name: (必需，字符串) 您想要给服务器的名称，以便 MCP 检查。
• version: (可选，字符串) 您的服务器向客户端宣传的版本。默认值为 "1.0.0"。

已知限制

• MCP 提示只能接受字符串参数，因此模式输入必须是只有字符串属性值的对象。
• MCP 提示仅支持 user 和 model 消息。不支持 system 消息。
• MCP 提示仅在一个消息内支持一种“类型”，因此不能在同一消息中混合媒体和文本。

测试您的 MCP 服务器

您可以使用官方检查器测试您的 MCP 服务器。例如，如果您的服务器代码编译成 dist/index.js，您可以运行：

npx @modelcontextprotocol/inspector dist/index.js

一旦启动检查器，您可以列出提示和动作，并手动测试它们。