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

QUOR
2 阅读3分钟

1. 引言

在 AI Agent 快速演进的今天，如何让模型安全、统一地接入外部工具与数据源，是决定其能力上限的关键。MCP（Model Context Protocol，模型上下文协议） 正是为此而生的开放标准。而 ZorvAI 作为一款开源项目，将 MCP 与「连接器（Connector）」机制深度融合，让 Agent 得以轻松调用浏览器、飞书、Git、云盘、数据库等第三方能力，而无需把每种集成写死进代码。

🔗 开源地址：github.com/Quor-a/Zorv…

本文将从架构分层、核心组件、接入流程三个维度，带你完整拆解 ZorvAI 的 MCP 设计。

2. 架构介绍

在 ZorvAI 体系中，MCP 与「连接器」一体两面：连接器是面向用户的托管入口，MCP 是背后的协议实现。两者共同扩展了主理人的行动半径。

其核心设计理念可概括为三点：

  • 配置即接入：所有服务器集中于 ~/.workbuddy/mcp.json 的 mcpServers 字段，按官方文档填写 command/args/env 或 url 即可。
  • 信任即启用：写入配置后服务器不会自动激活，须到连接器管理页面对新服务器点「信任」才生效——这是一道重要的安全闸门。
  • 三种传输方式：stdio（本地进程，如 npx @playwright/mcp）、SSE / Streamable HTTP（远程服务）。

3. 技术架构（分层设计）

ZorvAI 的 MCP 架构采用清晰的分层设计，从底层服务到顶层业务逐层解耦：

flowchart TD
  subgraph L5["L5 业务层"]
    A1["Agent Loop 调用 mcp 工具"]
    A2["飞书 / Git / 云盘 业务流"]
    A3["浏览器自动化 (agent-browser)"]
  end

  subgraph L4["L4 集成层"]
    B1["连接器管理页 (Connector Mgmt)"]
    B2["信任 / 启用闸门"]
    B3["recommend-connectors"]
  end

  subgraph L3["L3 客户层"]
    C1["WorkBuddy MCP Client"]
    C2["工具发现 (tools/list)"]
    C3["工具调用 (tools/call)"]
  end

  subgraph L2["L2 协议层"]
    D1["JSON-RPC 2.0"]
    D2["initialize / ping"]
    D3["resources / prompts"]
    D4["notifications"]
  end

  subgraph L1["L1 传输层"]
    E1["stdio (本地子进程)"]
    E2["SSE / Streamable HTTP"]
    E3["鉴权 (headers / env / token)"]
  end

  subgraph L0["L0 服务层"]
    F1["MCP Server (command/args)"]
    F2["MCP Server (url)"]
    F3["~/.workbuddy/mcp.json"]
  end

  L0 --> L1 --> L2 --> L3 --> L4 --> L5

各层职责如下：

层级名称核心职责
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 服务器，只需遵循以下五步：

  1. 查文档：先读目标提供方官方 MCP 文档，取准确 command/args/env/url，不臆测字段。
  2. 读配置：若 ~/.workbuddy/mcp.json 已存在则合并，不覆盖其它服务器。
  3. 写配置：以官方格式写入 mcpServers（stdio 用 npx；远程用 url）。
  4. 信任：到连接器管理页面对新服务器点「信任」启用（写入不会自动激活）。
  5. 调用：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 实现——它或许能给你带来不少启发。

🔗 项目地址：github.com/Quor-a/Zorv…

avatar
文章
阅读
粉丝