1. 项目概述从“小鸿AI WS63”到MCP Server的桥梁最近在折腾一个挺有意思的项目核心是把一个叫“小鸿AI WS63”的本地AI工具通过WebSocket协议接入到一个标准的MCPModel Context Protocol Server里。听起来有点绕简单来说就是让这个本地AI模型能像ChatGPT插件一样被外部的AI应用比如Claude Desktop、Cursor等安全、标准化地调用。整个过程的核心就是设计并实现一套稳定、高效的WebSocket通信协议。这可不是简单的“开个WebSocket连上就行”里面涉及到握手认证、消息格式定义、错误处理、状态同步等一系列细节任何一个环节没处理好都可能让整个通信链路变得脆弱不堪。我自己在实现过程中踩了不少坑也总结出一些能让连接更稳定、开发更顺畅的经验。如果你也在做类似AI工具集成或者需要设计一个健壮的WebSocket服务这篇从实战中摸爬滚打出来的协议详解应该能给你省下不少调试时间。2. 协议整体架构与设计思路拆解2.1 为什么是WebSocket而非HTTP在决定通信协议时我们首先排除了传统的HTTP轮询。对于AI工具调用这种可能涉及长时间运行、需要服务端主动推送状态如生成进度、流式输出的场景HTTP轮询不仅实时性差还会带来巨大的无效请求开销。虽然HTTP/2的Server-Send Event (SSE) 是一个选项但它本质上是单向的服务端到客户端。WebSocket协议则完美契合了我们的需求。它在单个TCP连接上提供全双工通信连接建立后客户端和服务端可以随时相互发送数据帧开销极小。这对于“小鸿AI WS63”这类模型非常重要因为一次推理过程服务端可能需要持续地向客户端发送token流而客户端也可能需要中途发送“停止生成”的指令。这种低延迟、双向、持续的消息交换能力是WebSocket的天然优势。2.2 MCP Server的角色与约束MCP Server在这里扮演了一个“协议转换器”或“适配器”的角色。它的核心职责是协议标准化对外暴露标准的MCP协议接口通常基于JSON-RPC over WebSocket让任何兼容MCP的客户端都能以统一的方式发现和调用工具。会话与状态管理管理客户端连接、会话状态并处理客户端的并发请求。适配“小鸿AI WS63”将MCP协议格式的请求如tools/call翻译成“小鸿AI WS63”能理解的内部指令通过我们设计的私有WebSocket协议发送过去同时将WS63返回的结果或流重新包装成MCP协议格式的消息返回给客户端。这意味着我们设计的WebSocket协议需要有两层一层是MCP Client到MCP Server之间的标准MCP协议另一层是MCP Server到“小鸿AI WS63”后端服务之间的私有协议。本文重点详解后者即MCP Server与WS63后端之间的私有WebSocket通信协议。2.3 核心设计目标我们的私有协议设计围绕以下几个核心目标展开简单高效消息结构尽可能扁平减少不必要的嵌套和序列化/反序列化开销。状态明确每个请求都有唯一的标识响应和错误必须能准确关联到原请求。支持流式响应必须能够处理模型逐词生成Token Streaming的输出模式。健壮性包含心跳机制保活定义清晰的错误码和重连逻辑。可扩展性消息类型易于增加以支持未来可能新增的指令如模型切换、参数动态调整等。3. 通信协议消息格式详解协议采用JSON作为消息载体因为它人类可读、易于调试且几乎所有编程语言都有成熟的库支持。每条消息都是一个独立的JSON对象。3.1 基础消息结构所有消息都遵循一个基础结构包含type和data两个顶级字段部分消息会包含id。{ id: req_123456, // 可选请求标识符用于匹配请求与响应 type: message_type_string, // 必需消息类型 data: {} // 必需消息主体内容其结构根据type不同而变化 }3.2 关键消息类型解析我们定义了以下几种核心消息类型涵盖了从连接到调用的完整生命周期。3.2.1 连接初始化与认证 (auth)在WebSocket连接建立后MCP Server必须首先发送认证消息。这是防止未授权访问的第一道关卡。客户端MCP Server - 服务端WS63发送{ id: auth_001, type: auth, data: { api_key: your_pre_shared_secret_key_here, // 预共享密钥 protocol_version: 1.0, client_info: { name: mcp-server-adapter, version: 0.1.0 } } }注意api_key不应硬编码在代码中最好通过环境变量或配置文件注入。在生产环境中可以考虑使用更复杂的机制如JWT但预共享密钥对于内网或可信环境下的简单对接已经足够。服务端WS63响应成功:{ id: auth_001, type: auth_response, data: { status: success, message: Authentication successful, model_info: { name: XiaoHong-WS63, capabilities: [text_completion, streaming] } } }失败:{ id: auth_001, type: error, data: { code: 4001, message: Invalid API key, original_type: auth } }认证失败后服务端应立即关闭WebSocket连接。3.2.2 工具调用 (tool_call)这是最核心的消息类型对应MCP协议中的tools/call请求。客户端MCP Server - 服务端WS63发送{ id: call_789012, type: tool_call, data: { tool_name: generate_text, // 工具名称对应WS63的某个功能 arguments: { prompt: 请用Python写一个快速排序函数并添加详细注释。, max_tokens: 1024, temperature: 0.7, stream: true // 明确要求流式输出 } } }参数设计心得arguments的设计应尽量与WS63后端的原生API参数对齐这样可以减少MCP Server内部的转换逻辑。stream参数至关重要它决定了服务端是返回一个完整的响应还是返回一系列tool_stream消息。3.2.3 流式响应 (tool_stream)当tool_call请求中stream为true时服务端会返回此类型消息。一条完整的响应可能由多条tool_stream消息组成。服务端WS63 - 客户端MCP Server发送{ id: call_789012, // 与请求ID一致 type: tool_stream, data: { content: def, // 流式输出的一个片段 index: 0 // 可选片段序号用于客户端按顺序组装 } }{ id: call_789012, type: tool_stream, data: { content: quick_sort, index: 1 } }// ... 更多 stream 消息处理流式数据的技巧客户端需要维护一个缓冲区按index顺序如果提供或接收顺序拼接content。同时要及时将每个片段转发给最终的MCP客户端如Claude以实现打字机效果。要特别注意网络抖动可能导致的消息乱序虽然WebSocket能保证顺序但客户端处理逻辑也要健壮。3.2.4 调用结束 (tool_result)流式或非流式调用结束后服务端都会发送此消息标志本次调用的终结。服务端WS63 - 客户端MCP Server发送{ id: call_789012, type: tool_result, data: { status: completed, // 或 failed, cancelled final_content: def quick_sort(arr):\n \\\快速排序主函数...\\\\n # 详细代码..., // 非流式时这里是完整结果流式时这里是所有片段的拼接可选方便调试 usage: { prompt_tokens: 25, completion_tokens: 120, total_tokens: 145 } } }即使对于流式调用发送一个包含完整内容和统计信息的tool_result也是一个好习惯这为客户端提供了最终确认和可能的数据校验点。3.2.5 心跳保活 (ping/pong)为了检测连接健康状态我们实现了简单的心跳机制。客户端定期如每30秒发送ping服务端需立即回复pong。客户端 - 服务端{ type: ping, data: { timestamp: 1715000000000 } }服务端 - 客户端{ type: pong, data: { timestamp: 1715000000000 // 原样返回接收的时间戳 } }实操心得心跳超时时间是关键。客户端如果在规定时间如45秒内未收到pong响应应判定连接已死执行重连逻辑。同时很多WebSocket库如Python的websocketsJavaScript的ws有内置的ping/pong机制但使用应用层的心跳可以更好地与你的业务逻辑结合例如在pong中附带服务端当前负载状态。3.2.6 错误处理 (error)任何阶段都可能产生错误。错误消息必须包含足够的信息用于诊断。服务端 - 客户端 或 客户端 - 服务端{ id: call_789012, // 如果错误与特定请求相关则包含该ID type: error, data: { code: 5001, message: Model inference timeout, original_type: tool_call, // 错误源于哪个类型的消息 details: { // 可选的详细错误信息 timeout_seconds: 30 } } }我们定义了一套错误码区间4xxx: 客户端错误如无效参数、认证失败5xxx: 服务端错误如模型加载失败、内部超时6xxx: 连接与协议错误4. 协议实现与核心环节剖析4.1 连接生命周期管理一个健壮的连接管理状态机至关重要。下图描绘了核心状态流转[初始] - [连接建立] - [发送auth] - [认证成功] - [就绪] - [处理请求/心跳] - [断开或错误] - [重连决策] \- [认证失败] - [连接关闭] \- [心跳超时] - [连接关闭] -/实现要点连接建立后立即认证不要在连接建立和发送认证消息之间做其他事情。就绪状态只有收到成功的auth_response后才将连接标记为“就绪”允许发送tool_call请求。请求队列在“非就绪”状态接收到的业务请求应暂存到队列中待就绪后依次发送。同时要为每个请求设置超时。优雅重连连接断开后重连逻辑应包含指数退避策略例如第一次等待1秒第二次2秒第三次4秒...直到最大间隔。重连后需要重新认证。4.2 消息序列化与传输我们选择JSON但需要注意编码确保双方都使用UTF-8编码。大小限制对于非常大的提示prompt或生成结果考虑是否需要对消息进行分片。虽然WebSocket帧本身可以很大理论上是9位无符号整数但过大的单条JSON消息会影响解析性能和内存占用。一个实用的做法是如果arguments或final_content超过一个阈值如1MB则记录警告日志。压缩对于文本数据在WebSocket层面开启permessage-deflate扩展可以显著减少带宽使用尤其是在流式传输大量小消息时。4.3 流式处理的具体实现流式处理是协议中最复杂的部分。以下是MCP Server端处理流式响应的伪代码逻辑async def handle_tool_call(request_id, tool_name, arguments): # 1. 发送请求给WS63后端 await websocket.send(json.dumps({ id: request_id, type: tool_call, data: {tool_name: tool_name, arguments: arguments} })) # 2. 准备流式响应给MCP客户端 buffer [] async for message in websocket: msg json.loads(message) if msg.get(id) ! request_id: continue # 忽略其他请求的消息 if msg[type] tool_stream: chunk msg[data][content] buffer.append(chunk) # 立即将chunk转发给MCP客户端如通过Server-Sent Events await forward_chunk_to_mcp_client(request_id, chunk) elif msg[type] tool_result: final_result msg[data] # 可以选择用buffer里的内容也可以用final_result里的final_content full_content .join(buffer) # 发送最终结果给MCP客户端 await send_final_result_to_mcp_client(request_id, full_content, final_result[usage]) break # 处理结束 elif msg[type] error: # 处理错误 handle_error(request_id, msg[data]) break关键点要确保forward_chunk_to_mcp_client是非阻塞的并且能处理下游客户端断开连接的情况。5. 常见问题、排查技巧与优化实录在实际开发和运维中会遇到各种各样的问题。下面这个表格整理了一些典型问题及其排查思路问题现象可能原因排查步骤与解决方案连接立即断开1. WS63服务未启动或端口错误。2. 防火墙/网络策略阻止。3. WebSocket路径或协议头错误。1. 检查WS63进程状态和日志。2. 使用telnet或nc测试TCP连通性。3. 用浏览器WebSocket测试工具如Chrome插件“Simple WebSocket Client”连接查看握手阶段返回的HTTP状态码。认证持续失败1.api_key不匹配或格式错误。2. 认证消息格式不符合服务端预期。1. 双重检查环境变量和配置文件的键值。2. 抓取首次通信的WebSocket帧对比发送的auth消息JSON与服务端代码逻辑是否一致。确保字段名、嵌套结构完全匹配。收不到流式响应1.tool_call请求中未设置stream: true。2. 服务端流式生成逻辑有bug。3. 客户端消息处理循环被阻塞。1. 检查发送的请求JSON。2. 查看WS63服务端日志确认是否进入了流式生成分支。3. 在客户端添加调试日志打印收到的每一条原始消息确认是否收到了tool_stream但未正确处理。流式响应中断/不完整1. 网络波动导致连接意外断开。2. 服务端模型推理超时或崩溃。3. 客户端缓冲区处理不当消息丢失。1. 检查心跳日志确认连接是否稳定。2. 查看服务端错误日志和资源监控CPU/内存。3. 在客户端实现消息序号(index)校验和乱序重排逻辑。对于关键任务可以考虑在客户端实现一个简单的确认机制如每收到10个chunk回复一个ack。客户端内存持续增长1. 未及时清理已完结请求的上下文和缓冲区。2. 消息队列堆积。1. 在收到tool_result或error后立即清理该request_id对应的所有缓存数据。2. 实现请求速率限制避免向服务端发送超过其处理能力的请求。延迟过高1. 网络延迟。2. 服务端模型推理慢。3. 客户端序列化/反序列化开销大。1. 测量网络RTT。2. 对服务端推理进行性能剖析。3. 对于极端性能场景可以考虑换用更高效的序列化格式如MessagePack或Protobuf但这会增加复杂性。JSON在大多数情况下已经足够好。几个独家避坑技巧为WebSocket连接添加“标签”在创建连接时生成一个简短的唯一ID如conn_7a3b并附加到所有日志中。当同时管理多个连接时这个标签能让你在浩如烟海的日志中快速定位问题连接的所有活动。实现“静默超时”检测除了主动心跳还可以监测业务消息的活跃度。如果连接在长达数分钟内没有任何消息往来包括心跳即使TCP连接没断也可能意味着应用层“卡死”了应主动断开重连。错误消息的“可追溯性”在服务端生成错误时除了错误码尽量在details里包含一个内部追踪ID如trace_id: svr-abc123。这样当客户端报告错误时你可以用这个ID快速在服务端日志里找到完整的错误上下文和堆栈跟踪。压力测试与边界值测试一定要模拟以下场景突然断开网络、发送畸形的JSON消息、发送超长prompt、快速连续发送大量请求。观察你的客户端和服务端是优雅降级还是直接崩溃。6. 进阶考量与扩展方向当基础协议稳定运行后可以考虑以下增强方向会话支持扩展协议允许一个连接内关联多个独立的“会话”。每个tool_call可以指定一个session_id服务端可以维护会话级别的上下文如对话历史。这对于实现多轮对话AI应用非常有用。能力协商在auth_response中服务端可以更详细地声明其能力例如支持的模型列表、每个模型的最大token限制、是否支持图像输入等。客户端可以根据这些信息动态调整界面和请求参数。二进制数据传输如果未来需要支持图像、音频等输入输出可以在协议中定义一种方式将二进制数据如图片base64或字节嵌入到JSON消息中或者通过WebSocket的二进制帧单独传输并在JSON消息中引用。监控与度量在消息中预留非干扰性的metadata字段用于传递诊断信息如客户端SDK版本、请求发起时间戳等。这有助于后期的性能分析和问题诊断。设计并实现这样一套通信协议就像在双方之间铺设一条既标准又坚固的数据管道。它一开始可能只是为了满足“连通”的基本需求但随着业务复杂度的提升协议本身的健壮性、可扩展性和可观测性直接决定了整个系统的稳定上限。从“小鸿AI WS63”到MCP Server的这条路我走通了希望这份详尽的协议拆解和实战记录能成为你搭建自己桥梁时的一张可靠蓝图。