1. 引言
在 AI Agent 快速演进的今天，如何让模型安全、统一地接入外部工具与数据源，是决定其能力上限的关键。MCP（Model Context Protocol，模型上下文协议） 正是为此而生的开放标准。而 ZorvAI 作为一款开源项目，将 MCP 与「连接器（Connector）」机制深度融合，让 Agent 得以轻松调用浏览器、飞书、Git、云盘、数据库等第三方能力，而无需把每种集成写死进代码。
🔗 开源地址 ：https://github.com/Quor-a/ZorvAI
本文将从架构分层、核心组件、接入流程三个维度，带你完整拆解 ZorvAI 的 MCP 设计。
2. 架构介绍
在 ZorvAI 体系中，MCP 与「连接器」一体两面：连接器是面向用户的托管入口，MCP 是背后的协议实现。两者共同扩展了主理人的行动半径。
其核心设计理念可概括为三点：
- 配置即接入 ：所有服务器集中于
~/.workbuddy/mcp.json的mcpServers字段，按官方文档填写command/args/env或url即可。 - 信任即启用：写入配置后服务器不会自动激活，须到连接器管理页面对新服务器点「信任」才生效------这是一道重要的安全闸门。
- 三种传输方式 ：
stdio（本地进程，如npx @playwright/mcp）、SSE/Streamable HTTP（远程服务）。
3. 技术架构（分层设计）
ZorvAI 的 MCP 架构采用清晰的分层设计，从底层服务到顶层业务逐层解耦：
#mermaid-svg-VqpaXdHCallMl62E{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-VqpaXdHCallMl62E .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-VqpaXdHCallMl62E .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-VqpaXdHCallMl62E .error-icon{fill:#552222;}#mermaid-svg-VqpaXdHCallMl62E .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-VqpaXdHCallMl62E .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-VqpaXdHCallMl62E .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-VqpaXdHCallMl62E .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-VqpaXdHCallMl62E .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-VqpaXdHCallMl62E .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-VqpaXdHCallMl62E .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-VqpaXdHCallMl62E .marker{fill:#333333;stroke:#333333;}#mermaid-svg-VqpaXdHCallMl62E .marker.cross{stroke:#333333;}#mermaid-svg-VqpaXdHCallMl62E svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-VqpaXdHCallMl62E p{margin:0;}#mermaid-svg-VqpaXdHCallMl62E .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-VqpaXdHCallMl62E .cluster-label text{fill:#333;}#mermaid-svg-VqpaXdHCallMl62E .cluster-label span{color:#333;}#mermaid-svg-VqpaXdHCallMl62E .cluster-label span p{background-color:transparent;}#mermaid-svg-VqpaXdHCallMl62E .label text,#mermaid-svg-VqpaXdHCallMl62E span{fill:#333;color:#333;}#mermaid-svg-VqpaXdHCallMl62E .node rect,#mermaid-svg-VqpaXdHCallMl62E .node circle,#mermaid-svg-VqpaXdHCallMl62E .node ellipse,#mermaid-svg-VqpaXdHCallMl62E .node polygon,#mermaid-svg-VqpaXdHCallMl62E .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-VqpaXdHCallMl62E .rough-node .label text,#mermaid-svg-VqpaXdHCallMl62E .node .label text,#mermaid-svg-VqpaXdHCallMl62E .image-shape .label,#mermaid-svg-VqpaXdHCallMl62E .icon-shape .label{text-anchor:middle;}#mermaid-svg-VqpaXdHCallMl62E .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-VqpaXdHCallMl62E .rough-node .label,#mermaid-svg-VqpaXdHCallMl62E .node .label,#mermaid-svg-VqpaXdHCallMl62E .image-shape .label,#mermaid-svg-VqpaXdHCallMl62E .icon-shape .label{text-align:center;}#mermaid-svg-VqpaXdHCallMl62E .node.clickable{cursor:pointer;}#mermaid-svg-VqpaXdHCallMl62E .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-VqpaXdHCallMl62E .arrowheadPath{fill:#333333;}#mermaid-svg-VqpaXdHCallMl62E .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-VqpaXdHCallMl62E .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-VqpaXdHCallMl62E .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-VqpaXdHCallMl62E .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-VqpaXdHCallMl62E .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-VqpaXdHCallMl62E .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-VqpaXdHCallMl62E .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-VqpaXdHCallMl62E .cluster text{fill:#333;}#mermaid-svg-VqpaXdHCallMl62E .cluster span{color:#333;}#mermaid-svg-VqpaXdHCallMl62E div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-VqpaXdHCallMl62E .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-VqpaXdHCallMl62E rect.text{fill:none;stroke-width:0;}#mermaid-svg-VqpaXdHCallMl62E .icon-shape,#mermaid-svg-VqpaXdHCallMl62E .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-VqpaXdHCallMl62E .icon-shape p,#mermaid-svg-VqpaXdHCallMl62E .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-VqpaXdHCallMl62E .icon-shape .label rect,#mermaid-svg-VqpaXdHCallMl62E .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-VqpaXdHCallMl62E .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-VqpaXdHCallMl62E .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-VqpaXdHCallMl62E :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} L0 服务层
MCP Server (command/args)
MCP Server (url)
~/.workbuddy/mcp.json
L1 传输层
stdio (本地子进程)
SSE / Streamable HTTP
鉴权 (headers / env / token)
L2 协议层
JSON-RPC 2.0
initialize / ping
resources / prompts
notifications
L3 客户层
WorkBuddy MCP Client
工具发现 (tools/list)
工具调用 (tools/call)
L4 集成层
连接器管理页 (Connector Mgmt)
信任 / 启用闸门
recommend-connectors
L5 业务层
Agent Loop 调用 mcp 工具
飞书 / Git / 云盘 业务流
浏览器自动化 (agent-browser)
各层职责如下：
| 层级 | 名称 | 核心职责 |
|---|---|---|
| L5 | 业务层 | Agent Loop 调用 mcp 工具，承载飞书/Git/云盘等业务流 |
| L4 | 集成层 | 连接器管理页、信任/启用闸门、推荐连接器 |
| L3 | 客户层 | WorkBuddy MCP Client，负责工具发现与调用 |
| L2 | 协议层 | JSON-RPC 2.0、initialize/ping、resources/prompts |
| L1 | 传输层 | stdio、SSE/Streamable HTTP、鉴权机制 |
| L0 | 服务层 | MCP Server 实例与配置文件 |
4. 核心组件
ZorvAI 的 MCP 体系由以下核心组件构成：
| 组件 | 职责 | 说明 |
|---|---|---|
| mcp.json | 服务器注册表 | 路径 ~/.workbuddy/mcp.json（注意无 dot 前缀）；合并写入，保留其它服务器 |
| MCP Client | 协议实现 / 工具路由 | 自动把远程工具映射为 mcp__server__tool |
| 连接器管理 | 信任与启用 | 新服务器写入后须手动「信任」激活 |
| Tools / Resources / Prompts | 三类能力面 | 工具可调用、资源可读取、提示可模板化 |
5. 接入流程
接入一个新的 MCP 服务器，只需遵循以下五步：
- 查文档 ：先读目标提供方官方 MCP 文档，取准确
command/args/env/url，不臆测字段。 - 读配置 ：若
~/.workbuddy/mcp.json已存在则合并，不覆盖其它服务器。 - 写配置 ：以官方格式写入
mcpServers（stdio 用npx；远程用url）。 - 信任：到连接器管理页面对新服务器点「信任」启用（写入不会自动激活）。
- 调用 ：Agent Loop 经
tools/list发现、tools/call执行远程能力。
6. 典型服务器示例
ZorvAI 已接入 / 可接入的代表性服务器包括：
- Playwright：浏览器自动化
- 飞书 Lark：IM / 文档 / 多维表格 / 日历
- GitHub：基于 gh CLI
- 云盘 / 空间：文件存储与同步
- 数据库 / 搜索引擎：数据查询与检索
- 自定义 stdio 工具：按需扩展
⚠️ 安全提示 ：凡涉及凭据（token / API key）的服务器，凭据应写入官方文档指定的位置（
env/headers/args）；缺失则向用户索取，切勿外泄。
7. 总结
ZorvAI 通过 MCP 协议与连接器机制的巧妙结合，构建了一套配置即接入、信任即启用的开放工具生态。无论是本地子进程还是远程服务，都能以统一的方式被 Agent 发现与调用，真正实现了「一次接入，处处可用」。
如果你正在构建自己的 AI Agent，或希望为现有系统扩展工具能力，不妨深入研究 ZorvAI 的 MCP 实现------它或许能给你带来不少启发。
🔗 项目地址 ：https://github.com/Quor-a/ZorvAI