MCP(模型上下文协议) 最小 Kotlin 客户端服务器示例

一个简单的天气工具，演示了使用模型上下文协议 (MCP) 的服务器-客户端交互。 仅用于演示目的。

用户：“东京的天气怎么样？” 响应：“东京的天气晴朗。”

这是 mcp-minimal-client-weather-server-sample 的 Kotlin 版本

客户端: src/main/kotlin/Client.kt 服务器: server.main.kts

图 1：初始化和工具发现

sequenceDiagram
    autonumber

    participant User as 用户
    participant ClientApp as ClientApp (主机)<br>在本地电脑上
    participant LLM as LLM (例如，Claude)<br>远程服务
    participant MCPClient as MCPClient (内部组件)<br>在本地电脑上的 ClientApp 中
    participant MCPServer as MCPServer (例如，工具服务器)<br>在本地电脑上

    Note over 用户, MCPServer: 用户启动 ClientApp，发起与 MCPServer 的连接

    ClientApp->>+MCPClient: 指示准备连接到特定的 MCPServer
    Note right of ClientApp: 主机管理每个服务器的 MCPClient 实例

    MCPClient->>+MCPServer: 1. 初始化 (请求)<br>[protocol_version, client_capabilities]
    Note over MCPClient, MCPServer: 启动连接建立和能力交换 (JSON-RPC)
    MCPServer-->>-MCPClient: 2. 初始化 (响应)<br>[selected_protocol_version, server_capabilities (tools, resources, etc.)]
    Note over MCPClient, MCPServer: 服务器通知其可用能力

    MCPClient->>MCPServer: 3. notifications/initialized (初始化完成通知)
    Note over MCPClient, MCPServer: 握手完成，可以进行正常通信

    MCPClient-->>-ClientApp: 初始化成功 & 服务器能力已通知 (通过成功的初始化等待隐式地)
    Note right of ClientApp: 主机 (ClientApp) 现在知道服务器已准备就绪

    ClientApp->>MCPClient: 4. 指示获取服务器提供的工具列表 (session.list_tools())
    MCPClient->>+MCPServer: 5. tools/list (请求)
    Note over MCPClient, MCPServer: 请求服务器上定义的工具列表
    MCPServer-->>-MCPClient: 6. tools/list (响应)<br>[{"name": "get_weather", "description": "...", "inputSchema": {...}}]
    Note over MCPClient, MCPServer: 示例：返回 'get_weather' 工具的定义

    MCPClient-->>ClientApp: 7. 通知工具列表 (包含 'get_weather' 等) 通过 tools_response 对象
    Note right of ClientApp: 主机存储/处理检索到的工具信息 (format_tools_for_llm)

    ClientApp->>LLM: 8. 将可用工具信息发送到 LLM<br>(例如，通过使用格式化的 tools_prompt 的系统提示)
    Note over ClientApp, LLM: 主机通知 LLM 'get_weather' 可用<br>LLM 现在可以根据此信息决定使用该工具

图 2：工具执行流程

sequenceDiagram
    autonumber

    participant User as 用户
    participant ClientApp as ClientApp (主机)<br>在本地电脑上
    participant LLM as LLM (例如，Claude)<br>远程服务
    participant MCPClient as MCPClient (内部组件)<br>在本地电脑上的 ClientApp 中
    participant MCPServer as MCPServer (例如，工具服务器)<br>在本地电脑上

    User->>ClientApp: 1. "东京的天气怎么样？"
    Note right of User: 用户提出一个可能需要工具的问题

    ClientApp->>LLM: 2. 转发用户的问题以及上下文<br>[系统提示 (包含工具信息) + 用户问题]
    Note over ClientApp, LLM: 主机将问题和格式化的工具信息 ('get_weather') 发送到 LLM

    LLM->>ClientApp: 3. LLM 响应，请求使用工具<br>响应: `{"tool_name": "get_weather", "arguments": {"location": "Tokyo"}}`
    Note over ClientApp, LLM: 基于提供的工具信息，LLM 决定使用天气工具<br>并生成带有参数的所需 JSON 结构

    ClientApp->>User: (可选) 4. 确认工具执行<br>"在工具服务器上执行 'get_weather' 吗？"
    User->>ClientApp: (可选) 5. "是"
    Note over ClientApp, User: 为了安全/透明，主机可能会寻求用户许可 (未在示例代码中实现)

    ClientApp->>+MCPClient: 6. 指示执行 'get_weather' 工具 (session.call_tool())<br>参数: {"location": "Tokyo"}
    Note right of ClientApp: 主机通过 MCPClient 指示 MCP 服务器

    MCPClient->>+MCPServer: 7. tools/call (请求)<br>[name: "get_weather", arguments: {"location": "Tokyo"}]
    Note over MCPClient, MCPServer: 使用指定的工具名称和参数调用服务器函数 (JSON-RPC)

    MCPServer->>MCPServer: 内部处理 (执行 get_weather 函数)
    Note over MCPServer: 记录执行，返回结果 (例如，"晴朗")
    MCPServer-->>-MCPClient: 8. tools/call (响应)<br>[result: {content: [{type: "text", text: "晴朗"}]}]
    Note over MCPClient, MCPServer: 服务器以结构化格式返回处理结果 (天气信息)

    MCPClient-->>-ClientApp: 9. 通知工具执行结果<br>结果对象包含: "晴朗" (从 tool_result_obj.content[0].text 中提取)

    ClientApp->>LLM: 10. 将工具执行结果发送回 LLM<br>新用户消息: "工具 'get_weather' 返回: '晴朗'。 根据此信息回答原始问题。"
    Note over ClientApp, LLM: 主机将从服务器获得的信息反馈给 LLM

    LLM->>ClientApp: 11. 生成最终响应 (作为文本)<br>"东京的天气晴朗。"

    ClientApp->>User: 12. 显示 LLM 生成的最终响应
    Note right of ClientApp: 向用户呈现最终答案