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 ​

按需載入 ​

命令工具 ​

即時生效與儲存 ​

下一步 ​