1. 为什么我要给 WorkBuddy 接一个自定义 MCP 连接器WorkBuddy 这个工具我用了一段时间它的强项在于把日常的重复性工作流串起来比如批量处理文件、定时抓取信息、自动整理笔记。但它默认的能力边界是固定的遇到需要调用外部 AI 服务、访问特定 API 或者操作本地工具的场景就得靠 MCP 来扩展。MCP 全称 Model Context Protocol直译过来是“模型上下文协议”。你可以把它理解成一套标准化的插座WorkBuddy 是电器外部服务是电网MCP 就是中间那个统一的插头标准。没有它的时候每接一个外部服务都得写一套私有适配代码有了它只要服务端按 MCP 规范暴露接口客户端就能即插即用。这次我选的目标是「腾讯混元生图」的 SSE 云托管服务。为什么拿它当例子一是生图这个需求足够典型很多人都有“让 WorkBuddy 帮我根据文字描述生成配图”的诉求二是它走的是 SSEServer-Sent Events协议和常见的请求-响应式 API 不太一样踩坑点集中讲透了之后你接别的 SSE 类服务也能照搬。SSE 是什么简单说它是一种服务器单向推送数据给客户端的长连接机制。普通 HTTP 请求像你打电话问客服一个问题对方答完就挂断SSE 像你打开收音机听广播电台持续往你这边推内容你只管接收。生图这种任务耗时较长服务端往往先返回“任务已创建”再陆续推送进度和最终结果用 SSE 就很合适。这篇文章适合三类人看一是已经在用 WorkBuddy、想扩展它能力边界的老用户二是手上有 SSE 接口、不知道怎么接进 AI 工具链的开发者三是对 MCP 协议好奇、想找一个完整案例上手的新手。我会从配置文件的字段含义讲起到实际调试时遇到的连接超时、事件解析失败等问题把整个流程拆开揉碎。需要提前说明的是下面涉及的具体配置参数、字段命名一部分来自我实际调试的记录一部分是基于 MCP 通用规范和 SSE 标准做的合理推断。不同版本的 WorkBuddy 在细节上可能有差异你照着做的时候以自己工具里的实际提示为准。2. 动手之前先把 MCP 和 SSE 这两个概念吃透2.1 MCP 到底解决了什么问题在没有 MCP 之前给 AI 工具接外部能力是一件很痛苦的事。假设你有五个外部服务要接——一个生图、一个查天气、一个读数据库、一个发邮件、一个操作浏览器——每个服务都有自己的认证方式、参数格式、返回结构。你得为每一个写一套适配层WorkBuddy 升级一次接口你可能就得改一遍代码。MCP 的思路是把“工具怎么被调用”这件事标准化。它定义了一套描述语言服务端告诉客户端“我有哪些工具、每个工具需要什么参数、返回什么格式”客户端负责把这些信息转成模型能理解的上下文。模型决定调用某个工具时客户端按标准格式发请求服务端按标准格式回结果。这里有个容易混淆的点MCP 是软件协议不是硬件协议。热搜里有人问“MCP 是软件协议硬件协议那个概念叫什么来着”硬件领域对应的概念通常叫“总线标准”或“接口规范”比如 USB、I2C、SPI 这些。MCP 借鉴的正是这种“统一接口”的思想只不过它统一的是 AI 模型和外部工具之间的交互方式。MCP 支持多种传输方式常见的有 stdio标准输入输出适合本地进程和 SSE适合远程服务。stdio 模式下WorkBuddy 会启动一个本地子进程通过标准输入输出和它通信SSE 模式下WorkBuddy 直接连一个远程 URL服务端通过事件流推送数据。这次我们用的是后者。2.2 SSE 的工作机制和它的脾气SSE 基于 HTTP但和普通 HTTP 有几个关键区别。第一它的响应头里Content-Type必须是text/event-stream这是识别 SSE 流的标志。第二连接建立后不会立即关闭服务端可以持续往客户端写数据。第三数据有固定的格式每条消息以data:开头以两个换行符结束还可以带event:、id:、retry:等字段。我画个简单的例子帮你理解。服务端推送一条消息实际传输的内容长这样event: progress data: {status:generating,percent:45} event: result data: {status:done,image_url:https://...}客户端解析时先看event:确定事件类型再看data:里的 JSON 内容。两个换行符是消息分隔符少了它客户端就不知道一条消息到哪儿结束。SSE 有几个“脾气”你得顺着它。第一它是单向的只能服务端推、客户端收客户端想发数据得另开一个 HTTP 请求。第二很多代理和网关会在连接空闲一段时间后强制断开这就是热搜里那个stream disconnected before completion: idle timeout waiting for SSE报错的来源。第三浏览器对 SSE 有连接数限制虽然 WorkBuddy 作为桌面工具不受这个限制但服务端可能有限制。2.3 为什么选腾讯混元生图做案例生图服务的交互模式天然适合 SSE。你提交一个生图请求服务端不可能瞬间返回图片它要排队、要推理、要后处理。如果做成普通 HTTP客户端要么一直等着容易超时要么轮询查状态浪费请求。SSE 让服务端在任务完成时主动推结果客户端只管挂着连接效率高得多。腾讯混元生图提供了云托管方式意味着你不需要自己部署模型拿一个服务地址和凭证就能用。这对个人开发者和小团队很友好。它的 SSE 接口通常包含几个阶段连接建立、任务提交确认、进度推送、结果推送、连接关闭。每个阶段对应不同的事件类型我们在配置 MCP 连接器时要把这些事件类型映射到 WorkBuddy 能理解的动作上。3. 配置文件 mcp.json 的字段逐个拆解3.1 mcp.json 的整体结构WorkBuddy 通过一个叫mcp.json的配置文件来管理所有 MCP 连接器。这个文件通常放在 WorkBuddy 的配置目录下具体路径因操作系统而异。Windows 一般在用户目录的AppData下macOS 在~/Library/Application Support下Linux 在~/.config下。如果你找不到可以在 WorkBuddy 的设置里搜“MCP”或“配置文件”通常会有一个“打开配置目录”的按钮。文件的基本结构是一个 JSON 对象顶层有一个mcpServers字段里面每个键是一个连接器的名字值是这个连接器的配置。名字你可以随便起但建议起得有意义比如hunyuan-image方便以后在 WorkBuddy 里识别。{ mcpServers: { hunyuan-image: { type: sse, url: https://your-hunyuan-endpoint/sse, headers: { Authorization: Bearer YOUR_TOKEN }, timeout: 120000, retry: { maxAttempts: 3, delayMs: 2000 } } } }上面是一个最小可用的 SSE 连接器配置。type指定传输方式SSE 就写sse。url是服务端的 SSE 端点地址。headers里放认证信息通常是 Bearer Token。timeout是单次请求的超时时间单位毫秒生图任务耗时长我设了 120 秒。retry是重试策略网络抖动时自动重连。3.2 认证字段的坑认证这块我踩过坑。腾讯混元的云托管服务通常要求你在请求头里带 Token格式是Authorization: Bearer token。但有些服务端实现要求 Token 放在查询参数里或者用自定义的 Header 名。你得先看服务端的文档确认。还有一个细节Token 里如果包含特殊字符比如、/、在某些 HTTP 客户端里可能被转义导致认证失败。我遇到过一次Token 末尾有个结果请求发出去变成了%3D服务端不认。解决办法是把 Token 用 Base64 编码后再放进去或者确认 WorkBuddy 的 HTTP 客户端是否正确处理了特殊字符。提示不要把真实 Token 直接提交到版本控制系统。如果 mcp.json 要共享给团队用环境变量引用比如Authorization: Bearer ${HUNYUAN_TOKEN}然后在系统环境变量里设置实际值。3.3 超时和重试参数的取舍超时时间设多少合适这取决于你的生图任务平均耗时。我实测下来一张 1024x1024 的图从提交到返回大约 15 到 40 秒高峰期可能到 60 秒。所以超时设 120 秒比较稳妥留了足够的缓冲。但超时不是越长越好。如果服务端真的挂了你设 600 秒WorkBuddy 就会傻等 10 分钟才报错体验很差。我的经验是设成“平均耗时 × 3”既能覆盖长尾情况又不会等太久。重试策略也要注意。SSE 连接断开后重连如果服务端不支持断点续传重连意味着任务要重新提交可能产生重复扣费。所以重试次数不宜多我设了 3 次每次间隔 2 秒。如果 3 次都失败说明不是偶发问题该人工介入排查了。3.4 事件类型映射MCP 连接器需要知道服务端推送的每种事件对应什么含义。有些 WorkBuddy 版本支持在配置里显式声明事件映射有些不支持靠连接器代码内部处理。如果支持配置大概长这样{ eventMapping: { task_created: acknowledge, progress: update, result: complete, error: fail } }这个映射告诉 WorkBuddy收到task_created事件时标记任务已受理收到progress时更新进度收到result时任务完成收到error时任务失败。如果你的 WorkBuddy 版本没有这个字段跳过即可不影响基本功能。4. 从零开始接入的完整实操流程4.1 准备工作拿到服务端地址和凭证第一步是确认你有一个可用的腾讯混元生图云托管服务。通常你需要在服务商的控制台创建一个实例拿到两个关键信息SSE 端点 URL 和访问 Token。端点 URL 一般长这样https://api.example.com/v1/hunyuan/image/sseToken 是一串长字符串。拿到之后先用命令行工具验证一下服务是否可达。我用的是curl它能直接看到 SSE 流的原始输出方便排查问题curl -N -H Authorization: Bearer YOUR_TOKEN \ -H Accept: text/event-stream \ https://your-endpoint/sse-N参数关闭 curl 的缓冲让输出实时显示。如果服务正常你会看到类似这样的输出event: connected data: {session_id:abc123} event: progress data: {percent:10}如果卡住不动或者报 401、403说明认证有问题如果报连接超时说明网络或地址有问题。这一步能过后面就顺了。4.2 编写 mcp.json 配置确认服务可达后打开 WorkBuddy 的配置目录找到或创建mcp.json。把前面那个配置模板填进去替换成你自己的 URL 和 Token。保存后重启 WorkBuddy或者如果有“重新加载配置”的选项点一下。重启后在 WorkBuddy 的 MCP 管理界面应该能看到你新加的连接器状态显示为“已连接”或“可用”。如果显示“连接失败”先检查 JSON 格式有没有语法错误比如多了个逗号、少了引号。JSON 对格式很严格一个字符错了整个文件都解析不了。注意修改 mcp.json 后一定要重启 WorkBuddy 或重新加载配置热更新不一定生效。我遇到过改了配置没重启折腾半天以为配置写错了其实是没生效。4.3 测试连接器是否真正可用配置显示“已连接”不代表功能正常。有些连接器只是 TCP 层连上了但 MCP 协议层握手失败。真正的测试是让 WorkBuddy 调用一次生图工具。在 WorkBuddy 的对话界面输入类似“帮我生成一张猫在草地上晒太阳的图片”的指令。如果连接器工作正常WorkBuddy 会识别出这是一个生图任务调用你配置的 MCP 工具然后返回图片链接或直接显示图片。如果没反应检查 WorkBuddy 的日志。日志通常在配置目录下的logs文件夹里找最新的那个文件搜“mcp”或“sse”关键词。常见错误有“tool not found”工具没注册成功、“invalid response”返回格式不符合 MCP 规范、“timeout”超时。4.4 参数传递的细节处理生图任务通常需要传几个参数提示词、图片尺寸、生成数量、风格等。MCP 连接器要把 WorkBuddy 传来的参数转成服务端要求的格式。这里有个容易出问题的地方参数名不一致。比如 WorkBuddy 内部可能用prompt表示提示词但腾讯混元的接口要求字段名叫text或input。你需要在连接器配置里做映射或者在 WorkBuddy 的工具定义里直接写服务端要求的参数名。如果 WorkBuddy 支持自定义工具 schema可以这样定义{ tools: [ { name: generate_image, description: 根据文字描述生成图片, parameters: { type: object, properties: { prompt: { type: string, description: 图片描述文字 }, size: { type: string, enum: [1024x1024, 768x768], default: 1024x1024 } }, required: [prompt] } } ] }这样 WorkBuddy 就知道调用generate_image时要传prompt和可选的size连接器再把这些参数转成服务端格式。5. 调试过程中遇到的典型问题和排查方法5.1 连接建立后立刻断开这是最常见的现象。WorkBuddy 显示“已连接”但一调用工具就报“连接已关闭”。原因通常是服务端在握手阶段就拒绝了请求但错误信息没有正确传递到客户端。排查方法用 curl 手动连一次看服务端返回什么。如果 curl 也立刻断开说明是服务端问题可能是 Token 过期、IP 白名单限制、或者服务端要求特定的 Header。如果 curl 正常但 WorkBuddy 断开说明是 WorkBuddy 的 HTTP 客户端配置问题比如它没发送Accept: text/event-stream头。我遇到过一次服务端要求User-Agent必须是特定值WorkBuddy 默认的 User-Agent 被拒绝了。解决办法是在 mcp.json 的 headers 里手动加上User-Agent: WorkBuddy/1.0。5.2 事件解析失败服务端推送的数据格式和 WorkBuddy 期望的不一致时会出现“事件解析失败”或“无效的 JSON”错误。SSE 的data:字段里必须是合法 JSON如果服务端推的是纯文本或格式错误的 JSON客户端就解析不了。排查方法用 curl 抓原始流把data:后面的内容复制出来用 JSON 校验工具检查。如果确实不是 JSON看服务端文档有没有说明格式或者联系服务端开发者确认。还有一种情况是编码问题。如果服务端返回的 JSON 里有中文但没声明 UTF-8 编码客户端可能按 Latin-1 解析导致乱码。解决办法是在请求头里加Accept-Charset: utf-8或者确认服务端响应头里有Content-Type: text/event-stream; charsetutf-8。5.3 空闲超时导致连接中断热搜里那个stream disconnected before completion: idle timeout waiting for SSE就是这个问题。生图任务在排队阶段可能几十秒没有数据推送中间的网络设备路由器、负载均衡、代理认为连接空闲了就把它掐断。解决办法有两个方向。一是让服务端定期发送心跳事件比如每 15 秒推一个event: heartbeat保持连接活跃。这需要服务端配合你控制不了的话就走第二个方向。二是在客户端配置里加心跳检测和自动重连。WorkBuddy 如果支持keepAlive配置设一个小于超时时间的间隔{ keepAlive: { intervalMs: 15000, message: ping } }这样 WorkBuddy 每 15 秒往连接里写一个 ping中间设备看到有数据流动就不会断。如果 WorkBuddy 不支持这个配置那就只能缩短超时时间让任务在超时前完成或者把大任务拆成小任务。5.4 工具调用成功但结果没返回有时候 WorkBuddy 日志显示工具调用成功了但界面上没显示图片。这通常是结果解析的问题。服务端返回的图片可能是一个 URL也可能是一段 Base64 编码的数据。WorkBuddy 需要知道怎么处理这个返回值。如果返回的是 URLWorkBuddy 应该能直接显示或下载。如果返回的是 Base64可能需要连接器把它转成临时文件或 Data URI。检查服务端返回的result事件里image_url字段是 URL 还是 Base64 字符串。如果是 Base64 且没有data:image/png;base64,前缀WorkBuddy 可能识别不了。5.5 常见问题速查表现象可能原因排查动作解决方向连接立即断开认证失败或 Header 缺失用 curl 手动测试检查 Token 和必需 Header事件解析失败数据非 JSON 或编码错误抓原始流检查格式修正服务端输出或加编码声明空闲超时中断中间设备掐断空闲连接观察断开时间是否固定加心跳或缩短超时结果不显示返回格式不被识别查看日志中的返回值转换 URL 或 Base64 格式工具找不到工具未注册或名称不匹配检查工具定义和调用名统一命名或重新注册重复扣费重试导致任务重复提交检查重试日志减少重试次数或加幂等键6. 几个让连接更稳的实战技巧6.1 用幂等键避免重复生图生图是要花钱的重复提交就是重复扣费。SSE 连接不稳定时WorkBuddy 可能重试服务端如果没做幂等处理就会生成多张图。解决办法是在请求里带一个唯一的request_id服务端看到相同的request_id就返回已有结果不重新生成。这个request_id可以由 WorkBuddy 生成也可以由连接器生成。如果 WorkBuddy 支持在工具调用时传自定义参数加一个idempotency_key字段。如果不支持就在连接器代码里根据提示词和时间戳生成一个哈希值作为键。6.2 日志分级方便定位问题WorkBuddy 的日志默认可能只记录错误调试时你需要更详细的信息。如果支持日志级别配置把它设成debug或verbose这样能看到每次请求的完整 URL、Header、请求体以及每次响应的原始数据。但 debug 日志量很大长期开着会影响性能也占磁盘。我的做法是平时用info级别出问题时临时切到debug问题解决后切回来。如果 WorkBuddy 不支持动态调整就在 mcp.json 里加一个logLevel字段重启生效。6.3 给连接器加一个健康检查WorkBuddy 启动时不会自动检查每个 MCP 连接器是否可用你得手动触发一次调用才知道。如果连接器很多逐个测试很麻烦。可以在配置里加一个健康检查端点WorkBuddy 启动时自动 ping 一下。健康检查的实现很简单服务端暴露一个/health路径返回 200 和{status:ok}。WorkBuddy 在加载连接器时请求这个路径通了就标记为可用不通就标记为不可用并给出提示。这样你一眼就能看出哪个连接器有问题。6.4 处理服务端限流云服务通常有 QPS 限制比如每秒最多 10 个请求。如果你短时间内提交大量生图任务会被限流返回 429 状态码。WorkBuddy 的重试策略如果没考虑 429可能会一直重试反而加重限流。正确的做法是遇到 429 时读取响应头里的Retry-After字段等指定时间后再重试。如果服务端没返回这个头就用指数退避第一次等 1 秒第二次等 2 秒第三次等 4 秒以此类推。在 mcp.json 里可以配置退避策略{ retry: { maxAttempts: 5, backoff: exponential, initialDelayMs: 1000, maxDelayMs: 30000 } }6.5 跨平台路径问题mcp.json 的路径在不同操作系统下写法不同。Windows 用反斜杠\macOS 和 Linux 用正斜杠/。如果你在配置里写了绝对路径换系统后可能找不到文件。建议用相对路径或者用环境变量。WorkBuddy 通常支持在配置里引用环境变量比如${HOME}/config/mcp.json。这样在不同机器上只要环境变量设置对了配置就能通用。如果 WorkBuddy 不支持环境变量那就每个系统单独维护一份配置虽然麻烦但稳妥。7. 这套方案还能怎么扩展接完腾讯混元生图之后我发现这套 MCP SSE 的模式可以复用到很多场景。比如接一个语音合成服务把文字转成音频接一个翻译服务实时翻译长文本接一个数据查询服务让 WorkBuddy 直接查数据库返回结果。只要服务端支持 SSE配置文件的骨架基本不用大改换 URL、Token 和事件映射就行。如果你想让连接器更智能可以在 WorkBuddy 侧加一层参数预处理。比如用户说“生成一张适合做公众号封面的图”连接器自动把尺寸设成 900x383风格设成“简洁商务”。这需要在工具定义里加一些默认值和条件逻辑WorkBuddy 如果支持自定义脚本就能做不支持的话就在服务端做。还有一个方向是把多个 MCP 连接器串起来。比如先生图再把图传给一个 OCR 服务提取文字最后把文字传给翻译服务。WorkBuddy 如果支持工作流编排可以把这几个连接器按顺序调用形成一个自动化流水线。这比单个连接器的价值大得多也是我接下来打算尝试的方向。最后分享一个小技巧调试 SSE 连接时在服务端加一个“回声”事件客户端发什么它就原样推回来。这样你能确认连接是双向通的排除单向网络问题。虽然 SSE 名义上是单向的但通过额外的 HTTP 请求可以实现双向通信回声测试能帮你快速定位问题出在哪一侧。