MCP-SDK源码架构

Client架构

graph LR
    subgraph "的应用程序 (例如 Cursor)"
        A[App Code]
    end

    subgraph "MCP SDK 核心"
        McpClientBuilder["McpClient.builder() / McpClient工厂"]
        McpClientInterface["McpClient (桥梁接口)"]
        SyncClient["McpSyncClient (同步通行)"]
        AsyncClient["McpAsyncClient (异步通行)"]
        
        TransportInterface["ClientTransport (交通工具规范/接口)"]
        HttpSseTransport["HttpClientSseClientTransport (远洋货轮)"]
        StdioTransport["StdioClientTransport (本地卡车)"]
        OtherTransport["未来可能的其他Transport..."]
        
        Schema["McpSchema (交流语言规范)"]
    end

    subgraph "MCP 服务 (城市B)"
        RemoteService["远程MCP服务 (通过网络)"]
        LocalService["本地MCP服务 (通过命令行)"]
        RemoteService_OR_LocalService["远程或本地服务"]
    end

    A --> McpClientBuilder
    McpClientBuilder --> McpClientInterface
    
    McpClientInterface -- 选择 --> SyncClient
    McpClientInterface -- 选择 --> AsyncClient
    
    SyncClient -- 使用 --> TransportInterface
    AsyncClient -- 使用 --> TransportInterface
    
    TransportInterface --|继承|--> HttpSseTransport
    TransportInterface --|继承|--> StdioTransport
    TransportInterface --|继承|--> OtherTransport
    
    HttpSseTransport -- 消息格式遵循 --> Schema
    StdioTransport -- 消息格式遵循 --> Schema
    OtherTransport -- 消息格式遵循 --> Schema

    HttpSseTransport -- 连接 --> RemoteService
    StdioTransport -- 连接 --> LocalService
    OtherTransport -- 连接 --> RemoteService_OR_LocalService

    classDef sdkCore fill:#e6f2ff,stroke:#a6c9ff,color:#333;
    classDef app fill:#ffe6e6,stroke:#ffa6a6,color:#333;
    classDef mcpService fill:#e6ffe6,stroke:#a6ffa6,color:#333;

    class McpClientBuilder,McpClientInterface,SyncClient,AsyncClient,TransportInterface,HttpSseTransport,StdioTransport,OtherTransport,Schema sdkCore;
    class A app;
    class RemoteService,LocalService,RemoteService_OR_LocalService mcpService;

1. MCP-SDK的核心使命：搭建沟通桥梁

想象应用程序（例如Cursor）是“城市A”，而MCP服务（远程或本地）是“城市B”。MCP-SDK的核心任务就是在这两座城市之间搭建一座桥梁，让它们能够顺畅地交流信息。

这座桥梁，我们称之为 McpClient，它是和SDK交互的主要入口。

2. 桥梁的两种通行方式：同步与异步

在这座桥梁上，可以选择两种不同的沟通方式：

• 同步（McpSyncClient） 就像打电话一样，提出问题后一直等对方回答，拿到回复后才继续后续操作。
• 异步（McpAsyncClient） 就像发邮件，发送完问题邮件后，自己忙别的事情，服务端处理完后再通过某种方式（比如邮件回复）通知结果。

这两种方式都由McpClient提供，满足不同场景下的调用需求。

3. 桥梁的建造材料与交通工具：传输层 ClientTransport

桥梁虽然有了设计图，但具体怎样传递消息，则依赖于“交通工具”，这就是传输层的职责。

• ClientTransport 是所有传输工具必须遵守的标准接口，定义了如何发送请求、接收响应的规范。
• SDK内置了几种常见的交通工具实现：
  • HttpClientSseClientTransport：远洋货轮，采用HTTP + SSE长连接技术，适合远程网络通信。
  • StdioClientTransport：本地卡车，通过命令行的标准输入输出流与本地MCP服务交互。
• 未来可以按需开发新的交通工具（例如无人机快递），只要实现ClientTransport接口，就能无缝插入现有桥梁系统。

4. MCP通信的语言规范：McpSchema

两座城市交流，必须使用同一种语言和信件格式，这就是McpSchema的作用。

它定义了：

• 请求消息格式（如 CallToolRequest 调用工具请求）
• 响应消息格式（如 CallToolResult 工具调用结果）
• 工具定义（如 Tool）等

这保证了客户端和服务端之间能够准确理解彼此传递的信息。

5. 从应用程序到MCP服务的全流程解读

1. **应用程序（App Code）**调用McpClient.builder()或使用工厂方法创建客户端桥梁。
2. 选择同步桥梁（McpSyncClient）或异步桥梁（McpAsyncClient）。
3. 选择桥梁上的交通工具（ClientTransport的实现）：
   • 远程网络通信用远洋货轮（HttpClientSseClientTransport）
   • 本地命令行通信用本地卡车（StdioClientTransport）
4. 客户端通过桥梁和交通工具，按统一语言规范（McpSchema）发送请求，连接远程或本地MCP服务。
5. MCP服务端（城市B）接收请求，执行业务逻辑，返回结果。
6. 应用程序拿到结果，继续业务流程。

6. 设计亮点与扩展优势

• 主线不变，灵活扩展：无论是同步还是异步，无论是远程服务还是本地命令行，整个通信流程和调用方式保持一致，用户体验统一。
• 接口插槽设计：ClientTransport接口让传输工具成为可插拔模块，方便未来新增和替换。
• 规范保障兼容性：McpSchema定义消息格式，确保客户端和服务端无缝对接。
• 面向未来：支持未来更多传输方式、新型通信技术的接入，无需改动核心逻辑。

---

Server架构

graph LR
    subgraph "MCP客户端应用 (例如 Cursor)"
        ClientApp[MCP Client App]
    end

    subgraph "MCP SDK Server核心"
        McpServerBuilder["McpServer.sync()/async() (服务器工厂)"]
        McpServerInterface["McpServer (服务器核心接口)"]
        SyncServer["SyncServer (同步服务器)"]
        AsyncServer["AsyncServer (异步服务器)"]
        
        TransportProviderInterface["McpServerTransportProvider (传输供应商接口)"]
        StdioServerProvider["StdioServerTransportProvider (本地进程供应商)"]
        HttpServletSseProvider["HttpServletSseServerTransportProvider (传统Web供应商)"]
        WebFluxSseProvider["WebFluxSseServerTransportProvider (响应式Web供应商)"]
        WebMvcSseProvider["WebMvcSseServerTransportProvider (Spring MVC供应商)"]
        
        SessionFactory["McpServerSession.Factory (会话工厂)"]
        ServerSession["McpServerSession (服务器会话)"]
        ServerTransport["McpServerTransport (服务器传输通道)"]
        
        RequestHandlers["RequestHandler (请求处理器集)"]
        NotificationHandlers["NotificationHandler (通知处理器集)"]
        
        Schema["McpSchema (协议规范)"]
    end

    subgraph "你的MCP服务应用程序"
        ServiceApp["Service Application Code"]
        ToolImplementations["Tool实现 (如数据库查询、文件操作等)"]
        ResourceProviders["Resource提供者 (如文档、代码等)"]
        PromptTemplates["Prompt模板"]
    end

    ClientApp -- 连接请求 --> TransportProviderInterface

    McpServerBuilder --> McpServerInterface
    
    McpServerInterface -- 选择 --> SyncServer
    McpServerInterface -- 选择 --> AsyncServer
    
    SyncServer -- 使用 --> TransportProviderInterface
    AsyncServer -- 使用 --> TransportProviderInterface
    
    TransportProviderInterface --|继承|--> StdioServerProvider
    TransportProviderInterface --|继承|--> HttpServletSseProvider
    TransportProviderInterface --|继承|--> WebFluxSseProvider
    TransportProviderInterface --|继承|--> WebMvcSseProvider
    
    TransportProviderInterface -- 创建 --> SessionFactory
    SessionFactory -- 创建 --> ServerSession
    ServerSession -- 使用 --> ServerTransport
    
    ServerSession -- 路由请求 --> RequestHandlers
    ServerSession -- 路由通知 --> NotificationHandlers
    
    RequestHandlers -- 调用 --> ServiceApp
    NotificationHandlers -- 调用 --> ServiceApp
    
    ServiceApp -- 实现 --> ToolImplementations
    ServiceApp -- 提供 --> ResourceProviders
    ServiceApp -- 管理 --> PromptTemplates
    
    StdioServerProvider -- 消息格式遵循 --> Schema
    HttpServletSseProvider -- 消息格式遵循 --> Schema
    WebFluxSseProvider -- 消息格式遵循 --> Schema
    WebMvcSseProvider -- 消息格式遵循 --> Schema

    StdioServerProvider -- 监听标准输入输出 --> ClientApp
    HttpServletSseProvider -- 监听HTTP SSE --> ClientApp
    WebFluxSseProvider -- 监听WebFlux SSE --> ClientApp
    WebMvcSseProvider -- 监听WebMVC SSE --> ClientApp

    classDef sdkCore fill:#e6f2ff,stroke:#a6c9ff,color:#333;
    classDef clientApp fill:#ffe6e6,stroke:#ffa6a6,color:#333;
    classDef serviceApp fill:#e6ffe6,stroke:#a6ffa6,color:#333;

    class McpServerBuilder,McpServerInterface,SyncServer,AsyncServer,TransportProviderInterface,StdioServerProvider,HttpServletSseProvider,WebFluxSseProvider,WebMvcSseProvider,SessionFactory,ServerSession,ServerTransport,RequestHandlers,NotificationHandlers,Schema sdkCore;
    class ClientApp clientApp;
    class ServiceApp,ToolImplementations,ResourceProviders,PromptTemplates serviceApp;

架构说明

1. 客户端连接层

• MCP客户端应用：如Cursor等IDE，作为MCP客户端连接到您的服务

2. MCP SDK Server核心层

• 服务器工厂：McpServer.sync()/async() 用于创建同步或异步服务器

• 服务器核心：管理整个服务器生命周期和配置

• 传输供应商：

• StdioServerTransportProvider：处理通过命令行启动的本地服务

• HttpServletSseServerTransportProvider：处理传统Servlet容器的HTTP SSE连接

• WebFluxSseServerTransportProvider：处理Spring WebFlux的响应式SSE连接

• WebMvcSseServerTransportProvider：处理Spring WebMVC的SSE连接

• 会话管理：每个客户端连接对应一个独立会话

• 请求路由：将不同类型的请求分发到对应的处理器

3. 您的服务应用层

• 服务应用代码：您实现的具体MCP服务逻辑

• 工具实现：数据库查询、文件操作、API调用等具体功能

• 资源提供者：文档、代码片段等可供客户端访问的资源

• Prompt模板：预定义的提示模板供客户端使用

与Client架构的对比

维度	Client架构	Server架构
角色	消费MCP服务	提供MCP服务
连接方向	主动连接服务器	被动接受客户端连接
传输实现	ClientTransport	ServerTransportProvider + ServerTransport
会话管理	McpClient管理单一连接	McpServerSession管理多个客户端连接
业务逻辑	调用远程工具和资源	实现工具和资源的具体逻辑

这个架构设计体现了MCP协议的双向通信特性，Server端不仅可以被动响应客户端请求，还能主动向所有连接的客户端发送通知。

结语

通过这座桥梁和交通工具的比喻，MCP-SDK的源码架构设计变得通俗易懂：它是一个灵活、扩展性强的通信桥梁，支持多种通行方式和交通工具，保障了AI模型与业务工具的顺畅互联。

掌握这套设计思想，就能更快理解源码结构，快速开发出适合自身业务的MCP客户端，助力智能系统高效对接。