MCP 服务器

readpic-mcp

Analyzes images using a vision model and returns detailed Chinese text descriptions, enabling text-only models to understand pictures from screenshots, UI designs, error logs, and architecture diagrams.

README

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"
}

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

环境变量 READPIC_CONFIG_PATH 指定的路径
可执行文件（dist/index.js）同目录的 config.json
进程 cwd 下的 config.json
~/.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