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

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

MCP 配置示例

[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 会生成：

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。

快速测试

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

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

{
  "describe_mode": "heuristic"
}