MCP Vision Tools

基于 Node.js 的 MCP (Model Context Protocol) 服务器，为 AI 客户端（Claude Desktop、Cursor 等）提供文档/图像处理工具。所有工具支持本地解析（隐私可控），并可选择启用 LLM 进行增强分析。

工具

| 工具 | 功能 | 本地解析 | LLM 增强 | |------|------|----------|----------| | process_excel | 解析 .xlsx/.xls，输出所有 sheet + 跨 sheet 公式依赖 | ✅ xlsx | 可选 | | process_word | 解析 .docx，输出 Markdown | ✅ mammoth | 可选 | | process_pdf | 解析 .pdf，输出分页文本 | ✅ pdf-parse | 可选 | | process_image | 批量图片处理，支持视觉 LLM 分析 | ✅ sharp + exifr | 可选（视觉模型） |

返回格式

所有工具统一返回 [{filePath, fileContent}] 数组：

[
  {"filePath": "C:\\docs\\report.pdf", "fileContent": "[Page 1]\n...文本内容..."},
  {"filePath": "C:\\docs\\report.pdf", "fileContent": "LLM 分析结果..."}
]

• filePath：原始文件路径
• fileContent：LLM 分析结果（启用时）或工具提取的原始内容（未启用时）；出错时为错误信息
• Excel 多 sheet 时每个 sheet 产生一条结果，公式引用单独一条

快速开始

npm install
npm run build
mcp-file-read-tools

启动后自带 HTTP API + Vue 管理界面，默认端口 3000（可配置）。浏览器打开 http://localhost:3000 即可使用：

• 工具列表 → 选择工具 → 填写参数 → 执行调试
• 配置管理 → 在线修改 LLM/API 配置

CLI 子命令

无参数启动时默认进入 serve 模式（向后兼容），也可显式指定子命令：

# 启动服务（默认行为）
mcp-file-read-tools
mcp-file-read-tools serve

# 直接处理单个文件（无需启动服务）
mcp-file-read-tools process image.png
mcp-file-read-tools process report.pdf --prompt "提取关键数据"
mcp-file-read-tools process data.xlsx

# 查看或修改配置
mcp-file-read-tools config get tools.image.llm.enabled
mcp-file-read-tools config set tools.image.maxFiles 5

# 查看帮助
mcp-file-read-tools --help
mcp-file-read-tools process --help
mcp-file-read-tools config --help

process 命令按文件扩展名自动路由到对应工具，输出 JSON 到 stdout，便于管道处理。

config 命令直接读写配置文件（config/mcp-vision.config.json），无需启动 HTTP 服务。

Claude Desktop 集成

支持两种连接方式：

方式一：Stdio（本地命令行）

{
  "mcpServers": {
    "vision-tools": {
      "command": "node",
      "args": ["/绝对路径/dist/index.js"],
      "env": { "LLM_API_KEY": "sk-xxx" }
    }
  }
}

方式二：HTTP 远程连接（SSE / Streamable HTTP）

{
  "mcpServers": {
    "vision-tools": {
      "url": "http://localhost:3000/api/mcp"
    }
  }
}

旧版 SSE 客户端使用：

{
  "mcpServers": {
    "vision-tools": {
      "url": "http://localhost:3000/api/mcp/sse",
      "transport": "sse"
    }
  }
}

MCP HTTP 端点：

• http://localhost:3000/api/mcp — Streamable HTTP（新协议 2025-11-25）
• http://localhost:3000/api/mcp/sse — SSE（旧协议 2024-11-05，兼容更多客户端）

Claude Code 集成

Claude Code 支持两种接入方式：

方式一：MCP Server 连接（推荐用于手动调用工具）

在项目 .claude/settings.json 中配置：

{
  "mcpServers": {
    "vision-tools": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp"
    }
  }
}

配置后即可在 Claude Code 中通过 MCP 工具直接调用 process_image、process_excel、process_word、process_pdf、process_file 等。

方式二：Read Hook 自动拦截（推荐用于图片/文档自动识别）

当 Claude Code 读取图片、PDF、Word、Excel 文件时，PreToolUse hook 自动调用 vision-tools REST API 替代原始 Read 工具，返回结构化的分析内容而非原始二进制数据。

1. 将 read-vision.py 放入 .claude/hooks/ 目录
2. 在 .claude/settings.json 中配置 hook：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/read-vision.py",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Hook 工作原理：

• 读取 .png/.jpg/.jpeg/.gif/.bmp/.webp/.svg/.pdf/.docx/.xlsx/.xls/.doc 文件 → 调用 vision-tools 处理，返回分析结果（exit 2）
• 读取普通文本文件 → 直接通过原始 Read 工具（exit 0）
• vision-tools 服务不可用 → 自动 fallback 到原始 Read（exit 0）

REST API 直接调用（hook 内部使用）：

POST /api/tools/process_image/call   {"files": ["path1", "path2"]}
POST /api/tools/process_pdf/call     {"file": "path"}
POST /api/tools/process_word/call    {"file": "path"}
POST /api/tools/process_excel/call   {"file": "path"}
POST /api/tools/process_file/call    {"files": ["path1", "path2"]}

配置

优先级：CLI 参数 > 环境变量 > 配置文件 > 默认值

配置文件

创建 mcp-vision.config.json 在项目根目录：

{
  "tools": {
    "excel": { "maxFiles": 2, "llm": { "enabled": true } }
  }
}

CLI 覆盖

mcp-file-read-tools serve --tools.image.maxFiles=2 --tools.image.llm.enabled=true
mcp-file-read-tools --tools.image.maxFiles=2

--key=value 格式的配置覆盖在 serve 命令（含无参数默认）中生效，与 yargs 子命令共存。

环境变量占位符

所有 API key 字段支持 ${VAR_NAME} 和 ${VAR_NAME:-default} 语法，可嵌套使用：

{ "apiKey": "${EXCEL_KEY:-${LLM_API_KEY}}" }

开发

npm run dev        # tsx watch 模式
npm test           # vitest
npm run build      # tsc