# Safe Vision MCP

通过 MCP 安全、高效地查看本地图片，避免把大图片直接塞进主模型上下文。

Safe Vision MCP 可以生成缩略图、联系表、图片统计信息、清单文件，以及可选的视觉模型描述。工具返回的结果只包含路径和简短文本，不会返回图片字节、base64 或 data URL。

## 为什么需要它？

大截图和批量图片很容易占满 LLM 的上下文窗口。Safe Vision MCP 通过以下方式保持上下文轻量：

- 将派生文件写入本地磁盘；
- 只返回文件路径、数量、统计信息和简短描述；
- 使用缩略图和联系表快速浏览图片；
- 在 MCP 服务器内部，每次最多只向视觉模型发送一张原图或派生图。

## 工具列表

| 工具                  | 用途                                     |
| --------------------- | ---------------------------------------- |
| `review_images`       | 对指定图片路径或目录进行一站式批量审查   |
| `inspect_image`       | 查看单张图片的尺寸、基础统计信息和缩略图 |
| `prepare_image_batch` | 生成缩略图、联系表、特征 CSV 和 manifest |
| `make_contact_sheet`  | 为指定图片生成联系表                     |
| `sample_images`       | 从目录中确定性地抽取代表性图片           |

## 环境要求

- Node.js 18+
- Python 3.10+
- Python 包：`Pillow`

```bash
npm install
python -m pip install -r requirements.txt
```

## MCP 配置示例

```toml
[mcp_servers.safe_vision]
command = "node"
args = ["/absolute/path/to/safe-vision-mcp/src/server.js"]
cwd = "/absolute/path/to/safe-vision-mcp"
type = "stdio"
startup_timeout_sec = 20
tool_timeout_sec = 3600

[mcp_servers.safe_vision.env]
SAFE_VISION_PYTHON = "python"
SAFE_VISION_OPENAI_BASE_URL = "https://api.openai.com/v1"
SAFE_VISION_MODEL = "gpt-5.4-mini"
SAFE_VISION_OPENAI_API_KEY_ENV = "OPENAI_API_KEY"
```

如需使用 OpenAI 兼容服务，请配置：

- `SAFE_VISION_OPENAI_BASE_URL`
- `SAFE_VISION_MODEL`
- `SAFE_VISION_OPENAI_API_KEY` 或 `SAFE_VISION_OPENAI_API_KEY_ENV`

不要将私有接口地址、模型别名、`.env` 文件或 API Key 提交到公开仓库。

## 环境变量

| 名称                                      | 默认值                      | 作用                                |
| ----------------------------------------- | --------------------------- | ----------------------------------- |
| `SAFE_VISION_PYTHON`                      | `py`                        | Node MCP 服务器调用的 Python 启动器 |
| `SAFE_VISION_OPENAI_API_KEY`              | 空                          | 视觉模型服务的直接 API Key          |
| `SAFE_VISION_OPENAI_API_KEY_ENV`          | 空                          | 指向 API Key 的环境变量名           |
| `OPENAI_API_KEY`                          | 空                          | 备用 API Key                        |
| `SAFE_VISION_OPENAI_BASE_URL`             | `https://api.openai.com/v1` | OpenAI 兼容 Responses API 地址      |
| `OPENAI_BASE_URL`                         | 空                          | 备用 API 地址                       |
| `SAFE_VISION_MODEL`                       | `gpt-4.1-mini`              | MCP 服务器内部使用的视觉模型        |
| `SAFE_VISION_HTTP_TIMEOUT_SECONDS`        | `300`                       | 单张图片的视觉模型请求超时          |
| `SAFE_VISION_REVIEW_BASE_TIMEOUT_MS`      | `120000`                    | `review_images` 的基础超时          |
| `SAFE_VISION_REVIEW_PER_IMAGE_TIMEOUT_MS` | `300000`                    | `review_images` 每张图片的额外超时  |

## 视觉输入策略

启用视觉模型描述时，MCP 服务器会向配置的视觉服务发送以下图片之一：

- 原图：当图片格式为 JPEG/PNG/WebP、长边 `<= 2048px`、文件大小 `<= 8MB`；
- 派生 JPEG：保存在 `vision_inputs/` 下，长边缩放到 `2048px`，应用 EXIF 方向，质量为 `90`。

无论哪种模式，MCP 返回结果仍然只包含路径、文本、数量和紧凑统计信息。

## 输出内容

`review_images` 会生成：

```text
descriptions.json
manifest.json
features.csv
thumbnails/
sheets/
vision_inputs/   # 可选
```

每条图片描述包含：

- `index`
- `path`
- `filename`
- `thumbnail_path`
- `description_source`
- `description`
- `features`

语义输出统一放在单个 `description` 字符串中，没有单独的 `observation` 对象。

## 隐私说明

- MCP 响应永远不会包含图片字节、base64 字符串或 data URL。
- 视觉模式只会把图片内容发送给你在私有环境变量中配置的服务商。
- 启发式模式不会调用远程模型，只在本地生成派生文件。
- 请勿提交 `.env`、私有 MCP 配置、私有 base URL、模型别名或 API Key。

## 快速测试

```bash
node --check src/server.js
python -m py_compile src/vision_tools.py
```

如需在不调用远程模型的情况下测试，可以在 MCP 客户端中调用 `review_images`，并设置：

```json
{
  "describe_mode": "heuristic"
}
```