AI导哈

模型上下文协议通信

MCP客户端通过JSON-RPC 2.0协议与服务器通信，支持stdio、TCP套接字和文件邮箱适配器，用于工具发现和调用。

  • by ahmedrowaihi
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 ahmedrowaihi/mcp-client

使用说明

MCP客户端-服务器通信（模型上下文协议）

此存储库演示 模型上下文协议（MCP）客户端如何与MCP服务器通信 使用简单的通用协议： JSON-RPC 2.0 通过标准输入/输出（stdio）、TCP套接字或邮箱（基于文件）适配器。

项目目的

  • 展示一般沟通流程 在MCP客户端和服务器之间。
  • 通过stdio、TCP套接字和邮箱（基于文件）适配器演示JSON-RPC 用于工具发现和调用。
  • 作为参考实施 用于以任何语言构建自定义MCP客户端或服务器。

工作原理（通用协议）

  • 这 客户端 使用多种传输机制（stdio、TCP套接字或邮箱）之一启动或连接到MCP服务器。
  • 所有通信都使用 JSON-RPC 2.0 协议，每条消息都是一行JSON。
  • 客户端和服务器交换初始化、工具发现和工具调用的请求和响应。

大趋势

  1. 流程启动和连接
    • 客户端将服务器作为子进程（stdio）启动，通过TCP套接字连接，或通过邮箱文件通信。
  2. JSON-RPC消息交换
    • 所有通信都是通过JSON-RPC 2.0消息进行的，每行一条。
  3. 初始化
    • 客户端发送 initialize 请求。
    • 服务器以功能进行响应。
    • 客户端发送 initialized 通知。
  4. 工具发现和调用
    • 客户要求提供可用工具列表(tools/list).
    • 服务器使用工具元数据进行响应。
    • 客户端调用工具(tools/call)与争论。
    • 服务器执行该工具并返回结果。
  5. 结果处理和循环
    • 客户端接收结果，并可根据需要重复工具调用。
  6. 关机
    • 客户端可以终止服务器进程（或发送关闭消息，如果支持的话）。

通信顺序图（标准）

sequenceDiagram
  participant Client
  participant Server

  Client->>Server: (spawn as child process, connect stdio)
  Client->>Server: initialize (JSON-RPC)
  Server-->>Client: initialize response
  Client->>Server: notifications/initialized
  loop Tool usage
    Client->>Server: tools/list
    Server-->>Client: tools list
    Client->>Server: tools/call (with args)
    Server-->>Client: tool result
  end
  Client->>Server: (process exit or shutdown)

邮箱（基于文件）流（带适配器）

邮箱实验现在使用 适配器 它通过stdio将邮箱请求桥接到标准服务器。适配器读取请求文件，将其转发到标准服务器，并写回响应文件。

sequenceDiagram
  participant MailboxClient as Mailbox Client
  participant MailboxAdapter as Mailbox Server Adapter
  participant StdServer as Standard MCP Server

  MailboxClient->>MailboxAdapter: Write request file (mailbox-requests/request-<id>.json)
  MailboxAdapter->>StdServer: Send JSON-RPC request via stdio
  StdServer-->>MailboxAdapter: JSON-RPC response via stdio
  MailboxAdapter->>MailboxClient: Write response file (mailbox-responses/response-<id>.json)
  Note over MailboxClient,MailboxAdapter: Files are created and deleted per request/response

套接字（TCP）流（带适配器）

套接字模式使用TCP服务器适配器，该适配器通过stdio将套接字请求桥接到标准服务器。套接字客户端连接到此适配器，并通过TCP使用JSON-RPC进行通信。

sequenceDiagram
  participant SocketClient as Socket Client
  participant SocketAdapter as Socket Server Adapter
  participant StdServer as Standard MCP Server

  SocketClient->>SocketAdapter: Connect via TCP socket
  SocketClient->>SocketAdapter: Send JSON-RPC request (tools/list, tools/call)
  SocketAdapter->>StdServer: Forward JSON-RPC request via stdio
  StdServer-->>SocketAdapter: JSON-RPC response via stdio
  SocketAdapter->>SocketClient: Forward JSON-RPC response via TCP

JSON-RPC消息示例

请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "greet",
    "arguments": { "name": "Alice" }
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "Hello, Alice!" }]
  }
}

项目结构

  • src/mcp/standard/ --标准（基于stdio）MCP客户端和交互式运行器
  • src/mcp/socket/ --Socket（基于TCP）MCP客户端、交互式运行器和服务器适配器（桥接到标准服务器）
  • src/mcp/mailbox/ --邮箱（基于文件）MCP客户端、交互式运行器和 适配器 （连接到标准服务器）
  • src/server/ --MCP服务器实现示例

统一客户端界面

所有MCP客户端(MCPClient, SocketMCPClient, MailboxMCPClient)实现一个通用 IMCPClient 接口，为连接、列出工具、调用工具和关闭连接提供一致的API。这使得在代码中的不同传输机制之间进行交换变得容易。

试试看

标准（基于stdio）模式

bun install
bun run standard

Socket（基于TCP）实验

  • 启动套接字服务器适配器：

    bun run socket:server

  • 在另一个终端中，启动套接字客户端：

    bun run socket:client

    或者直接运行交互式套接字客户端：

    bun run src/mcp/socket/interactive-socket.ts

邮箱（基于文件）实验

此回购还包括 基于邮箱的实验流程 其中客户端和服务器通过在邮箱目录中写入/读取文件进行通信。邮箱服务器现在是一个适配器，通过stdio将请求桥接到标准服务器。

  • 启动邮箱服务器适配器：

    bun run mailbox:server

  • 在另一个终端中，启动邮箱客户端：

    bun run mailbox:client

此仓库是使用JSON-RPC通过stdio、TCP套接字或邮箱文件构建和理解MCP客户端-服务器通信的参考，并包括用于桥接协议的适配器。

相关 MCP