模型上下文协议

模型上下文协议（MCP）是一种标准化协议，允许AI代理通过一致的接口与外部工具和服务进行交互。

MCP将工具和提示作为API端点暴露给AI代理调用。每个工具具有特定的名称，并使用JSON架构格式描述其输入和输出的输入模式。

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

要了解更多关于该协议的信息，请参阅模型上下文协议文档。

MCP服务器

MCP服务器实现了模型上下文协议，为AI代理与工具和服务的交互提供了标准化方式。

您可以在MCP市场或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 | 创建 MCP 工具注册表，通过多种传输机制（stdio、SSE）连接到 MCP 服务器。 |

快速开始

1. 设置 MCP 连接

要在 Koog 中使用 MCP，您需要建立连接：

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

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

使用 stdio 连接

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

// Start an MCP server (for example, as a process)
val process = ProcessBuilder("path/to/mcp/server").start()

// Create the stdio transport 
val transport = McpToolRegistryProvider.defaultStdioTransport(process)

使用 SSE 连接

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

// Create the SSE transport
val transport = McpToolRegistryProvider.defaultSseTransport("http://localhost:8931")

2. 创建工具注册表

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

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

// Create a tool registry with tools from the MCP server
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 客户端。例如：

// Create a tool registry from an existing MCP client
val toolRegistry = McpToolRegistryProvider.fromClient(
    mcpClient = existingMcpClient,
    serverInfo = McpServerInfo(url = "http://localhost:8931")
)

3. 与您的代理集成

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

// Create an agent with the tools
val agent = AIAgent(
    promptExecutor = executor,
    strategy = strategy,
    llmModel = OpenAIModels.Chat.GPT4o,
    toolRegistry = toolRegistry
)

// Run the agent with a task that uses an MCP tool
val result = agent.run("Use the MCP tool to perform a task")

使用示例

Google 地图 MCP 集成

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

// Start the Docker container with the Google Maps MCP server
val process = ProcessBuilder(
    "docker", "run", "-i",
    "-e", "GOOGLE_MAPS_API_KEY=$googleMapsApiKey",
    "mcp/google-maps"
).start()

// Create the ToolRegistry with tools from the MCP server
val toolRegistry = McpToolRegistryProvider.fromProcess(process = process)

// Create and run the agent
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 服务器以进行网页自动化：

// Start the Playwright MCP server
val process = ProcessBuilder(
    "npx", "@playwright/mcp@latest", "--port", "8931"
).start()

// Create the ToolRegistry with tools from the MCP server
val toolRegistry = McpToolRegistryProvider.fromSseUrl("http://localhost:8931")

// Create and run the agent
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")