ZorvAI 架构解析：MCP 连接器如何扩展 Agent 的行动半径

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)

各层职责如下：

4. 核心组件

ZorvAI 的 MCP 体系由以下核心组件构成：

5. 接入流程

接入一个新的 MCP 服务器，只需遵循以下五步：

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