readpic-mcp

一个 MCP（Model Context Protocol）服务，把图片交给视觉模型分析、返回详细的中文文本描述，让不支持多模态的文本模型也能"看懂"图片。专为软件开发场景设计（截图、UI 设计稿、错误日志、架构图等）。

安装

环境要求：Node.js 18+

# 1. 克隆仓库
git clone git@github.com:Alzeros/readpic-mcp.git
cd readpic-mcp

# 2. 一键安装（安装依赖 → 复制配置模板 → 打印 MCP 配置）
node setup.js

# 3. 编辑配置，填入你的 API 信息
# 用编辑器打开 config.json，修改 api_base_url 和 api_key

安装完成后，将 setup.js 打印的 MCP 配置粘贴到你的 AI 客户端（CodeBuddy/Cursor 等）即可使用。

配置

复制 config.example.json 为 config.json，填入自建 API 站地址与密钥：

{
  "api_base_url": "https://your-api-server.com/v1/chat/completions",
  "api_key": "your-api-key",
  "model_name": "auto-vl",
  "default_prompt": "",
  "timeout_ms": 30000,
  "max_retries": 2,
  "retry_backoff_ms": 500,
  "max_image_bytes": 5242880,
  "max_image_long_edge": 1568,
  "log_level": "info"
}

配置查找顺序（取第一个存在的）：

1. 环境变量 READPIC_CONFIG_PATH 指定的路径
2. 可执行文件（dist/index.js）同目录的 config.json
3. 进程 cwd 下的 config.json
4. ~/.readpic/config.json

config.json 已加入 .gitignore。代码容忍 UTF-8 BOM，Windows 编辑器加 BOM 也不影响。

配置项

字段	说明	默认值
api_base_url	API 服务站完整请求地址（OpenAI 兼容）	—
api_key	认证密钥	—
model_name	视觉模型名称	auto-vl
default_prompt	默认分析提示词；留空则用内置（软件开发场景）	内置提示词
timeout_ms	HTTP 请求超时（毫秒）	30000
max_retries	API 失败重试次数	2
retry_backoff_ms	重试退避基数，第 n 次等待 base * 2^(n-1)	500
max_image_bytes	单图原始体积上限（字节），超出触发缩放	5242880
max_image_long_edge	等比缩放长边像素上限	1568
log_level	日志级别 debug/info/warn/error	info

在 CodeBuddy 中注册

设置 → MCP → Add MCP，填入：

{
  "mcpServers": {
    "readpic": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-tool/dist/index.js"],
      "description": "图片识读工具 - 将截图/图片转为详细文本描述"
    }
  }
}

运行 node setup.js 会自动打印好带本机路径的配置，直接复制粘贴即可。

工具：read_picture

参数	类型	必填	说明
image_source	string	否	本地文件路径或图片 URL；为空读取系统剪贴板
prompt	string	否	自定义分析提示词；为空用默认提示词

返回：图片内容的详细中文文本描述（Markdown 分节，与默认提示词的 6 个分节对齐）。

实现说明

• 图片来源：URL 由 MCP 端下载后转 base64（不依赖 API 站拉取，兼容内网/鉴权图）；本地文件、剪贴板同样转 data URI，请求体结构统一。
• 缩放：用 sharp 等比缩放到长边 ≤ max_image_long_edge；GIF 取首帧转 PNG；缩放后仍超 max_image_bytes 则报错不发送。
• 剪贴板：Windows 用 PowerShell（STA 模式 System.Windows.Forms.Clipboard）；macOS 用 pngpaste；Linux 用 xclip。（未使用 clipboard-image，避免不维护的依赖。）
• API 重试：仅对网络错误 / 5xx / 429 重试（指数退避），4xx（除 429）不重试；错误消息报告实际重试次数。
• 日志：全部写 stderr（MCP 协议占用 stdout），用 READPIC_LOG_LEVEL 环境变量覆盖级别。

项目结构

mcp-tool/
├── src/
│   ├── index.ts          # MCP Server 入口，注册 read_picture
│   ├── config.ts         # 配置加载（查找路径 + BOM 容忍 + 校验）
│   ├── logger.ts         # 日志（stderr）
│   ├── api-client.ts     # OpenAI 兼容请求 + 重试
│   └── image-loader.ts   # 文件/URL/剪贴板 -> base64 + sharp 缩放
├── config.example.json   # 配置模板
├── package.json
├── tsconfig.json
└── README.md