# readpic-mcp

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



## 安装

**环境要求**：Node.js 18+

```bash
# 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 站地址与密钥：

```json
{
  "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 |
| `max_tokens` | 模型最大输出 token 数 | 4096 |
| `log_level` | 日志级别 `debug/info/warn/error` | `info` |

## 在 CodeBuddy 中注册

设置 → MCP → Add MCP，填入：

```json
{
  "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
```