👁️ @fastcar/mcp-vision-tools

为 Coding Agent 提供看图、OCR、主体定位、视频抽帧分析，以及可选的图片生成与编辑能力。

@fastcar/mcp-vision-tools 是一个本地 MCP 服务。它把图片或视频帧交给 OpenAI Chat Completions 兼容的多模态模型，并将经过校验的结构化结果返回给 Codex、Claude Code、Kimi、Cursor 或其他 MCP 客户端。

生图能力是独立的可选模块：未配置生图 profile 时，不注册相关工具，也不影响视觉理解服务。

图片 / 视频 / 生图指令
          │
          ▼
   Coding Agent / MCP Client
          │  MCP
          ▼
 @fastcar/mcp-vision-tools
    ├─ 视觉理解 → OpenAI-compatible Chat Completions
    └─ 图片生成 → OpenAI Images 或自定义 adapter
          │
          ▼
 结构化 JSON / 本地图片文件

🧭 导航

• ✨ 能力概览

• ⚡ 五分钟开始

• 📦 安装与环境要求

• ⌨️ CLI 命令

• ⚙️ 模型配置

• 🔌 MCP 接入

• 🧰 MCP 工具

• 🎨 Image2 与自定义生图模型

• 🌊 进度、兼容性与资源边界

• 🩺 运维与诊断

• 🔐 安全边界

• 🧩 Agent Skill

• 🛠️ 开发与发布

Related MCP server: MCP Vision Server

✨ 能力概览

支持的媒体来源：

• 本地绝对路径或相对路径；

• file: URL；

• HTTP(S) URL，包括重定向后的资源。

⚡ 五分钟开始

1. 安装

npm install -g @fastcar/mcp-vision-tools

确认 CLI：

mcp-vision-tools --version
mcp-vision-tools --help

2. 添加视觉模型

mcp-vision-tools config

也可以直接进入 profile 添加流程：

mcp-vision-tools models add

向导会安全收集 profile 名称、API Base URL、API key、模型名和超时时间。API key 输入不回显，不会出现在命令参数中。

3. 启动并接入客户端

mcp-vision-tools start

start 会：

1. 读取默认视觉模型；

2. 校验 Chat Completions 端点；

3. 在校验成功后替换旧 daemon；

4. 启动只监听 127.0.0.1 的 HTTP MCP；

5. 执行 MCP initialize 和 tools/list；

6. 更新已检测到的客户端注册。

成功后会返回实际地址，例如：

http://127.0.0.1:32123/mcp

端口由服务选择并持久化。不要把示例端口手工写死到客户端配置中。

4. 检查状态

mcp-vision-tools status
mcp-vision-tools doctor

客户端注册更新后，通常需要重启客户端或创建新的 Agent 会话，才能重新发现 MCP 工具。

5. 可选：启用生图

mcp-vision-tools image-models add image2
mcp-vision-tools restart

没有生图配置时，只暴露视觉理解工具；增加或移除生图能力后，需要重启 daemon 或重新连接 stdio 会话。

📦 安装与环境要求

环境要求

全局安装

npm install -g @fastcar/mcp-vision-tools

使用 npx

npx -y @fastcar/mcp-vision-tools --help
npx -y @fastcar/mcp-vision-tools stdio

无参数行为

• TTY 终端：打开交互菜单；

• 非 TTY / 管道环境：自动启动 stdio MCP。

普通终端管理建议显式使用 status、start、doctor 等子命令。

⌨️ CLI 命令

命令总览

Agent 与 JSON 模式

管理命令可附加：

mcp-vision-tools doctor --agent --json
mcp-vision-tools status --agent --json
mcp-vision-tools models list --agent --json
mcp-vision-tools image-models list --agent --json

• --agent 自动启用单行稳定 JSON；

• --json 启用 JSON 输出；

• models add/edit、image-models add/edit 和 config 需要安全交互输入，因此拒绝 --agent。

⚙️ 模型配置

视觉理解和图片生成使用两个相互独立的配置文件。建议始终通过 CLI 修改，避免手工处理 API key。

👁️ 视觉模型配置

默认文件：

~/.mcp-vision-tools.json

{
  "version": 1,
  "defaultProfile": "office-vl",
  "profiles": {
    "office-vl": {
      "baseUrl": "https://api.example.com/v1",
      "apiKey": "<YOUR_API_KEY>",
      "model": "qwen2.5-vl",
      "timeoutMs": 120000
    }
  },
  "defaultFrames": 6,
  "ffmpegPath": "C:/tools/ffmpeg/bin/ffmpeg.exe"
}

视觉 profile 选择顺序：

工具参数 profile
  → VISION_PROFILE
  → defaultProfile
  → "default"

只设置部分 VISION_BASE_URL、VISION_API_KEY 或 VISION_MODEL 时，会覆盖所选 profile 的对应字段，并保留其余存储字段。

旧版扁平配置会在读取时兼容为名为 default 的 profile：

{
  "baseUrl": "https://api.example.com",
  "apiKey": "<YOUR_API_KEY>",
  "model": "vision-model"
}

🎨 生图模型配置

默认文件：

~/.mcp-vision-tools.images.json

{
  "version": 1,
  "defaults": {
    "generate": "image2",
    "edit": "image2"
  },
  "profiles": {
    "image2": {
      "baseUrl": "https://api.example.com/v1",
      "apiKey": "<YOUR_IMAGE_API_KEY>",
      "model": "gpt-image-2",
      "timeoutMs": 300000,
      "operations": ["generate", "edit"],
      "adapter": {
        "kind": "openai-images"
      }
    }
  }
}

生图配置规则：

• operations 必须是非空的 generate、edit 或两者；

• defaults.generate 与 defaults.edit 可指向不同 profile；

• 默认项只能指向真实存在且支持对应操作的 profile；

• 环境变量可覆盖已有 profile；

• 完整的纯环境配置会创建一个仅在当前进程有效的 profile，名称来自 VISION_IMAGE_PROFILE，未设置时为 image2；

• 不完整的纯环境配置和空的 VISION_IMAGE_OPERATIONS 会被拒绝；

• 列表、Doctor、工具注册和实际调用使用同一份有效配置；任何列表都不会返回 API key。

单次操作的 profile 选择顺序：

工具参数 profile
  → 支持该操作的 VISION_IMAGE_PROFILE
  → 支持该操作的 defaults.generate / defaults.edit
  → 第一个支持该操作的有效 profile

Profile 名称

profile 名称支持字母、数字、Unicode、点号、下划线和连字符，例如：

office-vl
qwen2.5-vl
内部视觉模型
image2-prod

URL 规范化

配置应填写 API 根地址或 /v1 地址，不要填写 /chat/completions。以下输入都会规范化为 https://api.example.com/v1：

https://api.example.com
https://api.example.com/
https://api.example.com/v1
https://api.example.com/v1/chat/completions

配置写入保证

• 配置使用跨进程文件锁；

• 临时文件写入后原子替换；

• Windows 短暂的文件占用会有限重试；

• 锁包含唯一 token、PID 和创建时间；

• 配置损坏、schema 错误或权限失败不会被当成空配置覆盖；

• 并发 Agent 更新不会静默丢失正常写入。

环境变量

视觉模型与媒体

生图模型

并发与队列

队列采用有界 FIFO。超过上限时新任务立即失败，不会无限占用内存；等待中的任务支持取消。

🔌 MCP 接入

MCP server 信息：

name: fastcar-vision
version: 0.1.0

推荐：localhost HTTP

mcp-vision-tools start
# 或仅做客户端配置
mcp-vision-tools setup

daemon 只监听 127.0.0.1：

stdio

mcp-vision-tools stdio

stdio 模式下：

• stdout 仅输出 MCP JSON-RPC；

• 日志写入 stderr；

• 每个客户端进程拥有独立的 MCP server 生命周期。

自动配置客户端

mcp-vision-tools setup
mcp-vision-tools setup stdio

写入客户端配置前会先验证 MCP initialize 和 tools/list。验证失败时不会修改配置。

支持：

手工配置 stdio 时可使用：

codex mcp add fastcar-vision -- mcp-vision-tools stdio
claude mcp add --scope user fastcar-vision -- mcp-vision-tools stdio

客户端配置安全保证：

• 子进程有超时和输出上限；

• 替换 CLI 注册前读取并解析旧注册；

• 新增失败时尝试恢复旧注册；

• JSON 配置保留其他 MCP server 和未知字段；

• 写入采用临时文件与原子替换；

• doctor 检查客户端是否精确指向当前 daemon URL。

🧰 MCP 工具

工具注册条件

🖼️ analyze_image

{
  "image": "D:/screenshots/error.png",
  "instruction": "识别报错并解释可能原因",
  "intent": "ocr",
  "imageMode": "quality",
  "reasoningEffort": "medium",
  "profile": "office-vl"
}

intent

调用方 Agent 决定 intent；服务不会覆盖显式选择。

imageMode

auto 策略：summarize → 1536、ocr → 4096、locate → 2560、analyze → 2048。处理过程不裁剪、不放大小图；没有缩放且重编码更大时继续使用原图。

reasoningEffort

auto 不发送 reasoning_effort。端点不支持显式推理程度时，服务会省略该字段重试，并在 metadata 中提供 warning。

推荐组合：

🎞️ analyze_video

处理流程：

1. 本地视频先做文件检查；远程视频流式写入唯一临时目录；

2. FFmpeg 验证视频轨道并探测时长；

3. 在完整时间轴上均匀选择采样点；

4. 抽取按时间排序的 JPEG 帧；

5. 一次性提交给多模态模型；

6. 使用真实帧标签校正 samples[].source；

7. 无论成功或失败都清理远程临时文件。

📋 list_vision_models

{
  "defaultProfile": "office-vl",
  "profiles": [
    {
      "name": "office-vl",
      "model": "qwen2.5-vl",
      "baseUrl": "https://api.example.com/v1",
      "isDefault": true
    }
  ]
}

🎨 generate_image

🪄 edit_image

包含 generate_image 的全部参数，另外接受：

结果总是保存为本地文件，不以内联 Base64 返回。HTTP daemon 无法知道每个客户端的工作区，因此 Agent 应尽量显式传入绝对 outputDirectory。

📋 list_image_models

返回有效生图 profiles、Base URL、模型名、adapter、generate/edit 能力和分操作默认项，不返回 API key。纯环境配置也会出现在有效列表中。

视觉结构化结果

{
  "status": "ok",
  "model": "qwen2.5-vl",
  "profile": "office-vl",
  "summary": "图片包含一张销售数据表格。",
  "details": "表格按月份列出销售额。",
  "ocr": "January 12000 ...",
  "regions": [
    {
      "label": "销售表格",
      "confidence": 0.98,
      "bbox": { "x": 0.08, "y": 0.12, "w": 0.84, "h": 0.72 }
    }
  ]
}

bbox 使用 0–1 归一化坐标，并要求 x + w <= 1、y + h <= 1。

生图结构化结果

{
  "status": "ok",
  "operation": "generate",
  "profile": "image2",
  "model": "gpt-image-2",
  "images": [
    {
      "path": "D:/project/generated-2026-08-09T00-00-00-000Z-uuid.png",
      "mimeType": "image/png",
      "width": 1024,
      "height": 1024,
      "bytes": 123456,
      "revisedPrompt": "optional provider prompt"
    }
  ],
  "warnings": []
}

可能的 status：

• ok

• not_configured

• unsupported_operation

• provider_error

• invalid_response

• error

成功响应的 MCP metadata 包含准备、Provider、保存和总耗时，以及请求/返回数量和输出目录。

🎨 Image2 与自定义生图模型

内置 OpenAI Images adapter

内置 adapter 调用：

• POST /v1/images/generations：JSON 请求；

• POST /v1/images/edits：multipart 请求；

• 单参考图字段为 image，多参考图重复使用 image[]；

• 支持已知响应字段 b64_json、image_base64、base64、有效 image、有效 result 和 url；

• 最多扫描 64 个候选，并验证真实图片内容后才接受；

• 无效候选会被跳过并产生有界 warning。

Image2 几何规则

以下内置模型名启用 Image2 编辑归一化：

image2
gpt-image-2
任何以 -image-2 结尾的模型名，例如 gpt-5.4-image-2

Provider 画布合同：

编辑准备行为：

• 物理应用 EXIF orientation；

• 每张参考图独立居中到合规的透明 PNG 画布；

• 小图不放大，只增加透明填充；

• 超大图按比例缩小；

• 蒙版按第一张图应用 EXIF 后的显示尺寸校验；

• 蒙版随首图 placement 缩放和嵌入，填充区域为不允许编辑的 opaque 区域；

• size=auto 时仍以合规工作画布请求 Provider；若返回工作画布，则裁出首图 placement 并恢复首图原始显示尺寸；

• size=auto 时若 Provider 返回原图尺寸或其他有效尺寸，则直接保存实际结果并通过 warnings 说明尺寸差异，不因尺寸不一致丢弃有效图片；

• 显式 WIDTHxHEIGHT 时，匹配结果原样保存；不匹配结果会等比 cover、居中裁剪为请求尺寸并产生 warning；

• 本地裁切或尺寸适配失败时会保留 Provider 原始有效图片并 warning；对于已经返回的图片，只有空数据、无法解码、超过安全限制或请求取消才会失败。

这些规则只应用于内置 Image2 模型。其他内置模型和外部 module adapter 保持原始输入行为。

自定义 Provider 钩子

当 Provider 不兼容 OpenAI Images 请求、认证或响应格式时，可以配置受信任的绝对 .mjs / .js 模块。

export const apiVersion = 1;

export function createImageProviderAdapter() {
  return {
    async generate(request, context) {
      // 使用 context.profile、context.signal、context.fetch
      return {
        images: [{ bytes: new Uint8Array(/* real image bytes */), mimeType: "image/png" }],
      };
    },

    async edit(request, context) {
      // request.images 和 request.mask 已解析为字节
      return {
        images: [{ bytes: new Uint8Array(/* real image bytes */), mimeType: "image/png" }],
      };
    },
  };
}

合同要求：

• apiVersion 必须为 1；

• adapter 至少实现一个操作；

• profile 声明的每个 operation 都必须有对应方法；

• 返回 { images, warnings? }，每张图片包含非空 Uint8Array bytes；

• adapter 不负责写文件，核心服务统一校验并发布产物；

• 必须响应 context.signal；

• 长轮询可调用 context.reportProgress(message, progress)；

• API key 只从 context.profile 读取，禁止写入 adapter 源码和日志；

• 外部模块是可执行代码，只能使用用户明确批准的可信路径；

• doctor 只检查 adapter 文件是否存在，不执行模块代码。

配置示例：

{
  "adapter": {
    "kind": "module",
    "modulePath": "D:/trusted/image-adapter.mjs"
  }
}

完整合同见随包 Skill：skills/fastcar-vision-tools/references/image-provider-adapter.md。

🌊 进度、兼容性与资源边界

MCP progress

客户端提供 progress token 时，图片理解和生图任务会报告阶段与部分结果。进度仅用于展示，最终 structuredContent 才是权威结果。

保护策略：

• progress 最多积压 8 条；

• 通知发送不阻塞主分析；

• 最终最多等待 250 ms 刷新；

• 客户端通知失败不会导致任务失败。

Chat Completions 兼容降级

视觉 Provider 优先使用严格 json_schema。端点明确拒绝能力时按需降级：

json_schema → prompt 约束 JSON
SSE         → 普通响应
reasoning_effort → 省略
max_tokens  → max_completion_tokens → 省略 token 参数

兼容性尝试共享同一个总 deadline，不会为每次重试重新计算完整超时。

能力缓存按 profile、Base URL、model、API key 的 SHA-256 hash 和 reasoning effort 隔离，不保存明文 API key。

输出 token 上限

媒体与响应限制

本地文件先通过 stat 预检，远程媒体按实际流式字节数限制。图片内容由 Sharp 识别，不信任扩展名或响应头。

图片处理原则

• 支持 JPEG、PNG、WebP、GIF；

• MIME 来自实际图片格式；

• 默认不裁剪、不放大；

• OCR 使用更高质量编码；

• original 保持原始字节；

• 产物先写同目录临时文件，再以无覆盖方式发布；

• 文件系统不支持 hardlink 时回退到同目录原子 rename；

• 多图保存失败时回滚本次已发布文件。

视频处理原则

• 本地视频不整体读入内存；

• 远程视频有界流式下载；

• FFmpeg 子进程具有总超时、输出上限和取消；

• 每个远程任务使用独立临时目录；

• 完成、失败或取消后清理临时文件。

🩺 运维与诊断

daemon 生命周期

• 首次启动选择可用端口，后续优先复用；

• 并发 start 通过 owner lock 收敛到一个实例；

• 状态保存失败时立即关闭监听，避免孤儿服务；

• stop 校验 health、instance ID 和 PID；

• 先取消活动任务，再等待最多 5 秒优雅退出；

• 替换启动失败时尽力恢复旧 daemon。

状态目录

目录文件：

daemon.json
daemon-settings.json
daemon.log
provider-capabilities.json

启动校验

start 和 restart 在停止旧实例前验证默认视觉模型：

• /v1/chat/completions 可连接；

• 没有明显认证、限流或模型不存在错误；

• HTTP 200 body 至少具有 Chat Completions 基本结构。

校验不上传图片，因此：

{
  "reachable": true,
  "endpointVerified": true,
  "visionVerified": false
}

表示端点可用，不证明模型一定支持图片输入。

Doctor

mcp-vision-tools doctor
mcp-vision-tools doctor --agent --json

显式禁用 Skill 是合法的附属状态，不会单独导致 Doctor 失败。

常见问题

找不到 mcp-vision-tools

npm install -g @fastcar/mcp-vision-tools
npm prefix -g

也可以直接运行：

npx -y @fastcar/mcp-vision-tools doctor

Agent 看不到 MCP 工具

mcp-vision-tools status
mcp-vision-tools doctor
mcp-vision-tools setup

随后重启客户端或创建新 Agent 会话。

添加了生图模型，但没有生图工具

mcp-vision-tools image-models list
mcp-vision-tools restart

确认 profile 的 operations 包含需要的 generate 或 edit。

客户端仍使用旧端口

mcp-vision-tools setup

API 地址缺少 /v1

CLI 会自动规范化。不要填写完整 /chat/completions 路径。

API key 或模型错误

mcp-vision-tools models edit <profile>
mcp-vision-tools restart

生图配置使用：

mcp-vision-tools image-models edit <profile>
mcp-vision-tools restart

OCR 不清晰

使用 intent: "ocr"、imageMode: "quality" 或 original，并选择适合 OCR 的视觉模型。

视频分析过慢

减少 frames，优先使用本地文件，并避免设置过高的 VISION_VIDEO_CONCURRENCY。

FFmpeg 无法启动

VISION_FFMPEG_PATH=/path/to/ffmpeg

Windows 上的 spawn EBUSY 通常来自杀毒软件、索引器或其他进程短暂锁定二进制文件，可等待重试或改用独立 FFmpeg。

🔐 安全边界

API key

• 交互式输入不回显；

• 不写入 CLI 参数和普通日志；

• Provider 错误会清理当前 API key 与 Bearer token；

• capability cache 只保存凭据 hash；

• 配置文件尽力设置为仅当前用户可读写；

• 模型列表和 MCP 列表不返回 API key。

本地文件权限

MCP server 可以读取启动用户有权限访问的本地路径。不要让不可信远程用户直接控制文件路径参数。

远程 URL 与 SSRF

媒体 HTTP(S) URL 有意保持开放，包括 localhost、私网 IP、内网域名和重定向目标。这便于分析本地开发资源，但存在明确的 SSRF 风险。

不要将本 MCP 直接暴露给可任意提交 URL 的不可信公网用户。面向此类场景时，应在外层增加网络隔离、URL allowlist、代理和访问控制。

localhost MCP

HTTP daemon 只监听 127.0.0.1，校验 Host 与 Origin；/shutdown 需要随机内部 token。

外部 adapter

module adapter 拥有代码执行能力并可访问 profile API key。服务不会自动发现或下载 adapter，只接受显式配置的绝对 .mjs / .js 路径。

🧩 Agent Skill

npm postinstall 默认把包内 fastcar-vision-tools Skill 同步到用户级目录：

~/.agents/skills/fastcar-vision-tools

它是每个用户安装一份，不会为每个 Agent 重复安装。

mcp-vision-tools skill status
mcp-vision-tools skill sync
mcp-vision-tools skill uninstall

生命周期：

使用 npm --ignore-scripts 时不会执行 postinstall；首次 CLI 调用仍会尝试修复未禁用的 Skill。

🛠️ 开发与发布

本地开发

npm install
npm run build
npm test

核心目录：

src/
  cli.ts                    # CLI 与 Doctor
  config-store.ts           # 视觉配置持久化
  image-config-store.ts     # 生图配置持久化
  file-lock.ts              # 跨进程锁与原子替换
  server.ts                 # MCP 工具注册
  media/                    # 图片与视频解析
  provider/                 # Provider 与 Image2 几何
  tools/                    # MCP 工具实现
skills/                     # 随包 Agent Skill
scripts/                    # smoke 与安装脚本
test/                       # Node.js 测试

验证

npm test
node scripts/smoke-mcp.mjs
node scripts/smoke-call.mjs
npm pack --dry-run

测试覆盖配置迁移和并发写入、媒体真实性与限制、Provider fallback、SSE、队列、daemon 生命周期、客户端注册回滚、Image2 几何、真实 stdio MCP 调用、自定义 adapter、Skill 和 postinstall。

真实视觉模型和付费图片模型调用需要有效凭据，不属于默认自动化测试。

发布

npm test
npm pack --dry-run
npm publish --access public

prepublishOnly 会运行 TypeScript 构建。scoped public package 发布时必须使用 --access public。

📄 License

MIT