Model Context Protocol

--8<-- "versioning-snippets.md:beta"

Model Context Protocol (MCP) 是一种标准化协议，允许 AI 代理通过统一接口与外部工具和服务进行交互。

MCP 将工具和提示公开为 AI 代理可以调用的 API 端点。每个工具都有一个特定的名称和一个输入架构，该架构使用 JSON Schema 格式描述其输入和输出。

Koog 框架提供了与 MCP 服务器的集成，使您能够将 MCP 工具合并到您的 Koog 代理中。

要了解有关该协议的更多信息，请参阅 Model Context Protocol 文档。

MCP 服务器

MCP 服务器实现了 Model Context Protocol，并为 AI 代理与工具和服务进行交互提供了一种标准化的方式。

您可以在 MCP Marketplace 或 MCP DockerHub 中找到开箱即用的 MCP 服务器。

MCP 服务器支持以下传输协议与代理通信：

• 标准输入/输出 (stdio) 传输协议：用于与作为独立进程运行的 MCP 服务器进行通信。例如，Docker 容器或 CLI 工具。
• 服务器发送事件 (SSE) 传输协议（可选）：用于通过 HTTP 与 MCP 服务器进行通信。

与 Koog 集成

Koog 框架使用 MCP SDK 与 MCP 集成，并在 agent-mcp 模块中提供了额外的 API 扩展。

此集成允许 Koog 代理执行以下操作：

• 通过各种传输机制（stdio、SSE）连接到 MCP 服务器。
• 从 MCP 服务器检索可用工具。
• 将 MCP 工具转换为 Koog 工具接口。
• 在工具注册表中注册转换后的工具。
• 使用 LLM 提供的实参调用 MCP 工具。

核心组件

以下是 Koog 中 MCP 集成的主要组件：

组件	描述
McpTool	作为 Koog 工具接口与 MCP SDK 之间的桥梁。
McpToolDescriptorParser	将 MCP 工具定义解析为 Koog 工具描述符格式。
McpToolRegistryProvider	创建工具注册表，通过各种传输机制（stdio、SSE）连接到 MCP 服务器。

快速入门

1. 设置 MCP 连接

要在 Koog 中使用 MCP，您需要设置一个连接：

1. 启动一个 MCP 服务器（作为进程、Docker 容器或 Web 服务）。
2. 创建一个传输机制以与服务器通信。

MCP 服务器支持 stdio 和 SSE 传输机制与代理通信，因此您可以使用其中之一进行连接。

通过 stdio 连接

当 MCP 服务器作为独立进程运行时使用此协议。以下是使用 stdio 传输设置 MCP 连接的示例：

// 启动一个 MCP 服务器（例如，作为一个进程）
val process = ProcessBuilder("path/to/mcp/server").start()

// 创建 stdio 传输 
val transport = McpToolRegistryProvider.defaultStdioTransport(process)

通过 SSE 连接

当 MCP 服务器作为 Web 服务运行时使用此协议。以下是使用 SSE 传输设置 MCP 连接的示例：

// 创建 SSE 传输
val transport = McpToolRegistryProvider.defaultSseTransport("http://localhost:8931")

2. 创建工具注册表

建立 MCP 连接后，您可以通过以下方式之一使用来自 MCP 服务器的工具创建工具注册表：

• 使用提供的传输机制进行通信。例如：

// 使用来自 MCP 服务器的工具创建工具注册表
val toolRegistry = McpToolRegistryProvider.fromTransport(
    transport = transport,
    serverInfo = McpServerInfo(url = "http://localhost:8931", command = "path/to/mcp/server"),
    name = "my-client",
    version = "1.0.0"
)

• 使用连接到 MCP 服务器的 MCP 客户端。例如：

// 从现有的 MCP 客户端创建工具注册表
val toolRegistry = McpToolRegistryProvider.fromClient(
    mcpClient = existingMcpClient,
    serverInfo = McpServerInfo(url = "http://localhost:8931")
)

3. 与您的代理集成

要在 Koog 代理中使用 MCP 工具，您需要在代理中注册该工具注册表：

// 创建包含工具的代理
val agent = AIAgent(
    promptExecutor = executor,
    strategy = strategy,
    llmModel = OpenAIModels.Chat.GPT4o,
    toolRegistry = toolRegistry
)

// 运行代理以执行使用 MCP 工具的任务
val result = agent.run("Use the MCP tool to perform a task")

使用示例

Google Maps MCP 集成

此示例演示如何使用 MCP 连接到 Google Maps 服务器以获取地理数据：

// 启动包含 Google Maps MCP 服务器的 Docker 容器
val process = ProcessBuilder(
    "docker", "run", "-i",
    "-e", "GOOGLE_MAPS_API_KEY=$googleMapsApiKey",
    "mcp/google-maps"
).start()

// 使用来自 MCP 服务器的工具创建 ToolRegistry
val toolRegistry = McpToolRegistryProvider.fromProcess(process = process)

// 创建并运行代理
val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(openAIApiToken),
    llmModel = OpenAIModels.Chat.GPT4o,
    toolRegistry = toolRegistry,
)
agent.run("Get elevation of the Jetbrains Office in Munich, Germany?")

Playwright MCP 集成

此示例演示如何使用 MCP 连接到 Playwright 服务器进行 Web 自动化：

// 启动 Playwright MCP 服务器
val process = ProcessBuilder(
    "npx", "@playwright/mcp@latest", "--port", "8931"
).start()

// 使用来自 MCP 服务器的工具创建 ToolRegistry
val toolRegistry = McpToolRegistryProvider.fromSseUrl("http://localhost:8931")

// 创建并运行代理
val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(openAIApiToken),
    llmModel = OpenAIModels.Chat.GPT4o,
    toolRegistry = toolRegistry,
)
agent.run("Open a browser, navigate to jetbrains.com, accept all cookies, click AI in toolbar")