当前位置：首页 > news >正文

MCP (Model Context Protocol) 框架介绍文档

news 2025/11/5 11:59:53

最近在学习MCP的功能，记录一些学习笔记。

1. 架构概述

MCP（Model Context Protocol）是一个专为大模型应用设计的协议框架，旨在标准化大模型与外部数据源、工具之间的交互方式。该框架采用客户端-服务器架构，通过JSON-RPC 2.0协议实现高效、可靠的通信。

2. 核心组件

2.1 Host（宿主应用）

角色定位：最终承载大模型和用户界面的应用
核心功能：
- 启动时在内部创建MCP Client实例
- 管理大模型的交互逻辑和用户界面
- 处理Client返回的数据并整合到模型提示中
职责范围：
- 业务逻辑处理
- 用户交互管理
- 模型调用协调

2.2 Client（客户端）

角色定位：MCP协议的客户端实现
核心功能：
- 接受上层业务或大模型交互产生的请求
- 将请求打包成符合JSON-RPC 2.0规范的消息
- 通过底层传输通道与Server进行通信
- 接收来自Server的Notification消息
数据处理：
- 将Server返回的数据交回给Host
- 数据可用于拼接到模型的Prompt中
- 支持数据的二次处理和分析

2.3 Server（服务器）

角色定位：提供上下文内容和工具执行能力的进程或服务
核心功能：
- 启动时注册一系列接口能力
- 监听来自Client的JSON-RPC消息
- 执行具体的工具操作和数据查询
- 管理资源列表和工具定义
服务能力：
- 数据源接入（数据库、API、文件系统等）
- 工具执行（计算、转换、分析等）
- 资源管理（权限控制、连接池等）

3. 底层协议层

3.1 BaseSession（基础会话）

核心职责：提供所有JSON-RPC消息的读写、帧解析、请求-响应关联、通知分发的通用逻辑

架构设计：

承担对所有JSON-RPC消息的统一管理和生命周期控制
封装通用逻辑：发送请求、等待响应、发出单向通知，接收并分发对端消息等

泛型参数设计：

Generic[SendRequestT,      # Request 请求类型SendNotificationT, # Notification 类型  SendResultT,       # 发出的Response(Result)类型ReceiveRequestT,   # 接收的Request类型ReceiveNotificationT, # 接收的Notification类型ReceiveResultT     # 接收的Response(Result)类型
]

核心函数实现：

3.1.1 send_request（发送请求）

处理流程：

分配请求ID：request_id自增取新ID
创建响应流：为ID注册一个缓冲大小为1的内存流
构造JSONRPCRequest：将pydantic模型request序列化成JSONRPC格式，附带ID
写入_write_stream：发往对端
等待响应：在对应的响应流上阻塞读取，设置超时
错误处理：
- 若拿到JSONPRCError就抛McpError
- 若超时就抛带Http 408码的McpError
- 否则，把result部分反序列化为ReceiveResultT返回
清理：无论成功或失败，都要把流和注册记录删除并关闭

3.1.2 send_response（发送响应）

处理逻辑：

如果是正常结果的SendResultT，构造JSONRPCResponse(含ID+result字段)
如果是错误ErrorData，构造JSONRPCError，同样写入_write_stream

3.1.3 send_notification（发送通知）

特点：只需要单向推送，不需要回复的事件等静悄悄发给对端而不阻塞
实现：构造JSONRPCNotification

3.1.4 receive_loop（消息接收循环）

持续处理流程：

不断从底层流里读入任何一方发来的JSON-RPC消息
按类型分流到请求处理、通知处理或回应分发的正确管道里
消息类型分流：
- JSONRPCRequest → 请求处理
- JSONRPCNotification → 通知处理
- JSONRPCResponse/JSONRPCError → 回应分发

重写钩子：子类可以通过重写特定钩子方法来自定义处理逻辑

3.2 ClientSession（客户端会话）

初始化配置：

通过构造函数将下游的读写流、超时设置以及各类回调注入会话实例
回调包括：取样、列出根目录、日志和通用消息处理

握手流程：

调用initialize()时，客户端首先向服务端发送一个initialize请求
收到initializeResult后，再发出一条InitializedNotification通知
完成握手过程，建立正式通信

3.3 ServerSession（服务器会话）

握手逻辑设计：

协议的握手逻辑内嵌在received_request和receive_notification的两个钩子里
首次InitializeRequest处理：
- 服务器将请求参数保存到self._client_params
- 利用responder.respond(...)返回包含服务端能力集、版本号和说明文字的InitializeResult
InitializedNotification处理：
- 当接收到InitializedNotification时，状态机才真正进入Initialized阶段
- 任何在未完成初始化前到来的其他请求或通知都会被触发RuntimeError
- 确保交互顺序的正确性