MCP 与工具

zqagent 运行时可通过 MCP（Model Context Protocol）注入外部工具，内置 OCR 开箱即用，也可用 /tool add 创建命令工具。

安装 MCP 服务器

命令	说明
`/mcp`	列出服务器、连接状态与工具数量
`/mcp add`	交互式安装：选模板 → 填参数 → 连接并保存
`/mcp add <name> stdio <cmd...>`	手动添加本地进程
`/mcp add <name> http\|sse <url>`	手动添加远程端点
`/mcp import [file]`	导入配置；不带文件时粘贴 JSON 并以 `EOF` 结束
`/mcp rm\|enable\|disable\|refresh [name]`	移除 / 启用 / 禁用 / 刷新工具列表

内置安装模板：Filesystem、Memory、Sequential Thinking、GitHub、Fetch、PostgreSQL、OCR。

导入已有配置

/mcp import 支持裸数组、{ "servers": [...] } 以及 Claude Desktop / Cursor 的 mcpServers 对象格式：

json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "remote": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

省略 type 时按 builtin / url / command 推断；url 以 /sse 结尾时推断为 SSE。
command 可以是字符串，配合 args 数组自动合并；也支持 ${VAR} / ${env:VAR} 环境变量展开。
保存时统一写为数组格式到 .agent/mcp.json（随项目走，可提交 git）。同名条目导入时会逐个询问覆盖或跳过。

内置 OCR

内置 OCR 默认启用（{ "name": "ocr", "type": "builtin", "builtin": "ocr" }），工具名为 mcp__ocr__recognize。

输入：imagePath（推荐，工作区内路径）、imageBase64、imageUrl；PDF 会逐页识别（maxPages 默认 5，dpi 默认 150）。
引擎自动降级：macOS Vision（需 Xcode Command Line Tools）→ tesseract + pdftoppm → 已配置的多模态模型。
全部不可用时返回 error 与 how_to_fix，不会阻塞启动或其它工具。
如需关闭：/mcp disable ocr。

Linux 服务器镜像已内置 tesseract-ocr、tesseract-ocr-chi-sim 与 poppler-utils；本地环境可用系统包管理器安装：

# macOS
brew install tesseract tesseract-lang poppler
# Debian / Ubuntu
apt-get install -y tesseract-ocr tesseract-ocr-chi-sim poppler-utils

按需加载

当 MCP 工具较多（默认 ≥16 个或 schema 合计 ≥24000 字符）时自动切换为按需加载：

不再全量下发 mcp__*，改为 mcp_search_tools（检索）与 mcp_call_tool（调用）；
模型先检索，命中工具会在下一轮加载（单会话上限 40 个），也可直接用元工具调用；
小规模场景仍全量注入，行为不变；ZQAGENT_MCP_LAZY=1|0 可强制开关。

命令工具

命令	说明
`/tool add <name> <cmd...>`	添加命令工具（执行 shell 命令）
`/tool rm\|disable\|enable <name>`	移除 / 禁用 / 启用工具

即时生效与保存

工具的新增 / 移除 / 禁用 / 替换对下一次对话立即生效，无需重启。

MCP 服务器与命令工具的配置会随项目保存，可提交 git 与团队共享。 MCP 注入的工具（含内置 OCR）默认按高风险处理，交互模式下需逐次审批。

MCP 与工具 ​

安装 MCP 服务器 ​

导入已有配置 ​

内置 OCR ​

按需加载 ​

命令工具 ​

即时生效与保存 ​

下一步 ​