@fastcar/mcp-vision-tools

v0.1.3

Published

a month ago

Universal MCP vision tools (image + video frame understanding). Delegates to any OpenAI-compatible multimodal model, so text-only agents like DeepSeek can "see" via tool calls.

0High
0Medium
0Low

fastcar

mcp vision multimodal image video gpt deepseek codex claude-code kimi-code

👁️ @fastcar/mcp-vision-tools

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

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

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

发布验证：npm 包 · GitHub 源码 · 问题反馈。@fastcar 是 npm 发布 scope，源码由该 GitHub 仓库维护。

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

🧭 导航

✨ 能力概览

| 能力 | 状态 | 说明 | | --- | :---: | --- | | 🖼️ 图片理解 | ✅ | 综合分析、OCR、摘要、主体定位 | | 🎞️ 视频分析 | ✅ | 视频探测、均匀抽帧、多帧结构化理解 | | 🧠 多模型 profile | ✅ | 添加、编辑、删除并切换默认视觉模型 | | 🎨 图片生成 | 可选 | OpenAI Images 兼容的图片生成 | | 🪄 图片编辑 | 可选 | 1–16 张参考图和可选 alpha 蒙版 | | 🧱 自定义生图模型 | 可选 | 通过受信任的 ESM adapter 扩展非标准 Provider | | 🌐 双传输 | ✅ | localhost Streamable HTTP 与 stdio MCP | | 🔗 客户端配置 | ✅ | 自动检测并配置 Codex、Claude Code、Kimi、Cursor、DeepSeek Harness (dsh) | | ⏳ 异步任务 | ✅ | 长时工具立即返回 taskId，以事件等待获取结果，支持恢复查询与取消 | | 🛡️ 稳定性保护 | ✅ | 持久化终态、重启中断、超时、FIFO 队列、原子写入 | | 🤖 Agent Skill | ✅ | 首次 CLI 运行时同步到用户级 Skill 目录 |

支持的媒体来源：

本地绝对路径或相对路径；
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 会：

读取默认视觉模型；
校验 Chat Completions 端点；
在校验成功后替换旧 daemon；
启动只监听 127.0.0.1 的 HTTP MCP；
执行 MCP initialize 和 tools/list；
更新已检测到的客户端注册。

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

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 会话。

📦 安装与环境要求

环境要求

| 项目 | 要求 | | --- | --- | | Node.js | >= 20.0.0 | | 操作系统 | Windows、macOS、Linux | | 视觉模型 | OpenAI Chat Completions 兼容，并支持图片输入 | | 图片模型 | 可选；OpenAI Images 兼容或自定义 adapter | | FFmpeg | 默认使用依赖中的 ffmpeg-static |

全局安装

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 命令

命令总览

| 命令 | 作用 | | --- | --- | | mcp-vision-tools | TTY 中打开交互菜单；管道中启动 stdio MCP | | mcp-vision-tools stdio | 显式启动 stdio MCP | | mcp-vision-tools config | 打开视觉模型配置向导 | | mcp-vision-tools models list | 列出视觉模型 profiles | | mcp-vision-tools models add [name] | 添加视觉模型 profile | | mcp-vision-tools models edit [name] | 编辑视觉模型 profile | | mcp-vision-tools models use <name> | 设置默认视觉模型 | | mcp-vision-tools models remove <name> | 删除视觉模型 | | mcp-vision-tools image-models list | 列出生图 profiles、能力和默认项 | | mcp-vision-tools image-models add [name] | 添加生图 profile | | mcp-vision-tools image-models edit [name] | 编辑生图 profile | | mcp-vision-tools image-models use <name> [generate\|edit\|both] | 设置分操作默认生图 profile | | mcp-vision-tools image-models remove <name> | 删除生图 profile | | mcp-vision-tools artifacts status [directory] | 统计托管或指定目录中的生图产物 | | mcp-vision-tools artifacts cleanup [directory] | 清理超过保留期的生图产物 | | mcp-vision-tools artifacts cleanup [directory] --all | 删除目录中全部由本工具命名的生图产物 | | mcp-vision-tools start | 校验视觉端点；首次交互启动用复选框选择客户端，之后只刷新已选择客户端 | | mcp-vision-tools restart | 重新执行完整启动流程；首次交互启动用复选框选择客户端 | | mcp-vision-tools start --daemon-only | 启动 daemon，不修改客户端配置 | | mcp-vision-tools restart --daemon-only | 重启 daemon，不修改客户端配置 | | mcp-vision-tools stop | 无活动任务时停止 daemon | | mcp-vision-tools start\|restart\|stop --force | 强制中断活动任务后执行；仅限用户明确授权 | | mcp-vision-tools status | 查看 daemon 状态和 MCP URL | | mcp-vision-tools logs [lines] | 查看 daemon 日志，默认 80 行 | | mcp-vision-tools setup | 启动或复用 HTTP daemon，并配置客户端 | | mcp-vision-tools setup stdio | 将客户端配置为 stdio transport | | mcp-vision-tools clients configure | 通过复选框重新选择并更新客户端注册 | | mcp-vision-tools clients remove [client] | 移除单个客户端的 fastcar-vision MCP；无参数时显示选择项 | | mcp-vision-tools doctor | 执行配置、端点、daemon、MCP、Skill 和客户端诊断 | | mcp-vision-tools skill status | 检查用户级 Agent Skill | | mcp-vision-tools skill sync | 启用并同步 Agent Skill | | mcp-vision-tools skill uninstall | 删除并持久禁用 Agent Skill | | mcp-vision-tools --help | 显示帮助 | | mcp-vision-tools --version | 显示版本 |

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
mcp-vision-tools artifacts status --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",
  "clientSetup": {
    "selected": ["dsh"]
  }
}

clientSetup.selected 控制启动时自动维护哪些客户端。首次交互式 start 或 restart 会显示复选框，默认勾选 dsh，其他未配置客户端默认不勾选；已有注册会标记为“已配置”并保持勾选。取消勾选已有客户端后，程序会再次确认是否删除旧注册。选择结果会保存到该配置。非 TTY、--agent、--json 和 --daemon-only 启动不会弹窗，也不会自动修改客户端配置。显式 setup 会配置检测到的客户端并同步更新该选择。

视觉 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 更新不会静默丢失正常写入。

环境变量

视觉模型与媒体

| 变量 | 默认值 | 说明 | | --- | --- | --- | | VISION_PROFILE | 配置默认项 | 本次运行的视觉 profile | | VISION_BASE_URL | profile 值 | 覆盖 API Base URL | | VISION_API_KEY | profile 值 | 覆盖 API key | | VISION_MODEL | profile 值 | 覆盖模型名 | | VISION_TIMEOUT_MS | 120000 | 模型与媒体总超时，毫秒 | | VISION_FRAMES | 6 | 视频默认抽帧数，最大 16 | | VISION_FFMPEG_PATH | ffmpeg-static | 自定义 FFmpeg 路径 | | MCP_VISION_CONFIG | ~/.mcp-vision-tools.json | 视觉配置文件 | | MCP_VISION_STATE_DIR | 平台状态目录 | daemon 与能力缓存目录 |

生图模型

| 变量 | 默认值 | 说明 | | --- | --- | --- | | MCP_VISION_IMAGE_CONFIG | ~/.mcp-vision-tools.images.json | 生图配置文件 | | VISION_IMAGE_PROFILE | 分操作默认项 | 当前生图 profile | | VISION_IMAGE_BASE_URL | profile 值 | 覆盖图片 API Base URL | | VISION_IMAGE_API_KEY | profile 值 | 覆盖图片 API key | | VISION_IMAGE_MODEL | profile 值 | 覆盖图片模型名 | | VISION_IMAGE_TIMEOUT_MS | 300000 | 整次生图操作超时，毫秒 | | VISION_IMAGE_OPERATIONS | 保留已有能力；纯环境配置默认两项 | 逗号分隔的 generate,edit | | VISION_IMAGE_ADAPTER_MODULE | 内置 adapter | 自定义 .mjs / .js 绝对路径 |

并发与队列

| 变量 | 自适应默认值 | 合法范围 | | --- | --- | --- | | VISION_PROVIDER_CONCURRENCY | clamp(CPU × 2, 8, 16) | 1–256 | | VISION_IMAGE_CONCURRENCY | clamp(ceil(CPU / 2), 2, 8) | 1–256 | | VISION_VIDEO_CONCURRENCY | clamp(floor(CPU / 4), 1, 4) | 1–256 | | VISION_ANALYSIS_QUEUE_LIMIT | min(providerConcurrency × 4, 64) | 0–4096 | | VISION_GENERATION_CONCURRENCY | 2 | 1–32 | | VISION_GENERATION_QUEUE_LIMIT | 8 | 0–256 |

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

🔌 MCP 接入

MCP server 信息：

name: fastcar-vision
version: 0.1.1

推荐：localhost HTTP

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

daemon 只监听 127.0.0.1：

| 路径 | 作用 | | --- | --- | | /mcp | Streamable HTTP MCP endpoint | | /health | 实例身份与健康检查 | | /shutdown | 使用内部随机 token 的关闭接口 |

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。验证失败时不会修改配置。

首次执行交互式 start 或 restart 时，会以复选框列出已检测到的客户端。默认只勾选 dsh，已有注册会标记并默认保留；取消已有客户端后会询问是否同时删除旧配置。后续启动只维护配置中 clientSetup.selected 的客户端。非首次需要调整客户端时执行：

mcp-vision-tools clients configure

该命令会复用同一组选项：已有注册默认勾选，新增客户端可以直接勾选，取消已有客户端后会确认是否删除旧注册，并只更新最终选中的客户端。已有 HTTP 注册会更新到当前 daemon URL，已有 stdio 注册会保留原 command/args；新客户端默认使用 HTTP。普通交互模式只显示简短的完成提示，不输出完整配置对象。需要移除某个客户端时执行：

mcp-vision-tools clients remove

交互终端会显示单选列表并要求确认。脚本可直接指定客户端并请求稳定 JSON：

mcp-vision-tools clients remove codex --agent --json

移除只删除 fastcar-vision 注册，不会影响同一客户端中的其他 MCP；重复移除是幂等的。

支持：

| 客户端 | HTTP | stdio | 配置方式 | | --- | :---: | :---: | --- | | Codex | ✅ | ✅ | 优先调用 codex mcp CLI | | Claude Code | ✅ | ✅ | 优先调用 claude mcp CLI | | Kimi | ✅ | ✅ | CLI 或原子合并 ~/.kimi-code/mcp.json | | Cursor | ✅ | ✅ | 原子合并 ~/.cursor/mcp.json | | DeepSeek Harness (dsh) | ✅ | ✅ | 原子合并 ~/.dsh/cordis.patch.yml（或各 profile 的 cordis.patch.yml），注册 @deepseek-ai/dsh-mcp-client 插件 |

dsh 需要先单独安装并确保 dsh --version 可执行；mcp-vision-tools setup 只负责检测已有 dsh 并写入 MCP 配置，不会安装 dsh 本体。

手工配置 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 | 始终 | 提交图片理解、OCR、摘要和定位任务 | | analyze_video | 始终 | 提交视频抽帧分析任务 | | list_vision_models | 始终 | 列出视觉 profiles，不返回 API key | | get_vision_task | 始终 | 立即查询任务，供断线恢复或人工检查 | | wait_vision_task | 始终 | 事件驱动等待终态；完成即返回，超时返回精简心跳 | | cancel_vision_task | 始终 | 幂等取消未完成任务 | | list_image_models | 至少一个有效生图操作 | 列出生图 profiles，不返回 API key | | generate_image | 至少一个 profile 支持 generate | 提交图片生成与保存任务 | | edit_image | 至少一个 profile 支持 edit | 提交多参考图编辑与保存任务 |

⏳ 统一异步调用合同

analyze_image、analyze_video、generate_image 和 edit_image 都只负责受理任务，不等待 Provider 完成。成功受理后立即返回：

{
  "taskId": "7db2c542-3f79-45e3-b470-4f23656610c4",
  "operation": "generate_image",
  "status": "queued",
  "createdAt": "2026-08-09T12:00:00.000Z",
  "terminal": false,
  "resultAvailable": false,
  "mayHaveIncurredCost": false,
  "retryPolicy": "not_applicable",
  "recommendedAction": "wait_vision_task"
}

调用方随后调用 wait_vision_task。服务端订阅任务终态事件，任务在等待窗口内完成时立即返回，不会固定等满 20 秒，也不会在内部每 5 秒轮询。

{
  "taskId": "7db2c542-3f79-45e3-b470-4f23656610c4",
  "maxWaitMs": 20000
}

maxWaitMs 可取 1000–25000，默认 20000。如果任务仍未完成，工具只返回精简心跳：

{
  "taskId": "7db2c542-3f79-45e3-b470-4f23656610c4",
  "operation": "generate_image",
  "status": "running",
  "progress": 46,
  "elapsedMs": 20431,
  "waitTimedOut": true,
  "terminal": false,
  "resultAvailable": false,
  "mayHaveIncurredCost": true,
  "retryPolicy": "not_applicable",
  "recommendedAction": "wait_vision_task"
}

收到 waitTimedOut: true 后，立即以同一 taskId 再调用 wait_vision_task。等待本身已经覆盖整个窗口，不需要再 sleep；不要重新提交原任务，也不要改用 get_vision_task 循环查询。短任务例如 6 秒完成，会在约 6 秒时返回；70 秒任务通常只需要约 4 次等待调用。

任务状态：

| status | 含义 | 是否终态 | | --- | --- | :---: | | queued | 已持久化，等待后台执行 | — | | running | 正在准备媒体、调用 Provider 或保存结果 | — | | succeeded | 已完成，权威结果位于 result | ✅ | | failed | 执行失败，脱敏原因位于 error | ✅ | | cancelled | 调用方显式取消 | ✅ | | interrupted | daemon/stdio 进程在完成前关闭或重启 | ✅ | | not_found | taskId 不存在或 24 小时元数据已过期 | ✅ |

每个响应都提供面向 Agent 的结构化决策字段：

| 字段 | 语义 | | --- | --- | | terminal | 是否已经进入终态；false 时继续等待 | | resultAvailable | 是否存在可使用的权威 result | | mayHaveIncurredCost | Provider 调用是否可能已经产生费用；这是保守提示，不是账单确认 | | retryPolicy | not_applicable、user_confirmation_required 或 do_not_retry | | recommendedAction | wait_vision_task、use_result、report_result、ask_user_before_resubmit 或 report_terminal_state |

get_vision_task 会立即返回完整的当前快照，包括运行中的 progress、截断后的 message、实时 elapsedMs 和时间戳。它只用于断线恢复、人工检查或确认未知 taskId，不是常规等待路径。业务失败、取消和中断是可读取的结构化终态，不应作为传输错误重试；未知 taskId 才返回 MCP isError: true。

如果工具在受理或查询阶段发生同步错误，会返回 isError: true，并同时提供文本内容和可机器读取的错误对象；消息会先清理凭据再截断：

{
  "ok": false,
  "error": {
    "code": "TOOL_CALL_FAILED",
    "tool": "analyze_image",
    "message": "已脱敏的错误消息"
  }
}

长时任务已经成功受理后的 Provider 错误仍通过 wait_vision_task 的 failed 终态返回，不会被改写为同步工具错误。

Agent 必须遵守：

提交长时工具并保存 taskId；
优先调用 wait_vision_task，心跳超时后继续调用同一工具；
仅把 get_vision_task 用于恢复或即时检查，不用它轮询；
视觉分析成功时执行 use_result；生图或编辑成功时执行 report_result，直接报告 result.images[].path；
生成后视觉复查是可选项。普通生成/编辑请求不授权 Agent 再调用 analyze_image、view_image 或其他看图工具；只有用户明确要求执行检查、比较、质量验证或迭代验收时才能复查。提示词中的风格、质量、构图或布局要求只是生成约束，不是复查授权；意图不明确时直接交付，不为自检额外询问；
failed 或 interrupted 时说明错误及可能成本，询问用户是否重新提交；得到明确确认前不得重提；
cancelled 或 not_found 时报告终态，不自动重试；
只有用户明确要求时才调用 cancel_vision_task。

🖼️ `analyze_image`

| 参数 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | :---: | --- | --- | | image | string | ✅ | — | 本地路径、file: URL 或 HTTP(S) URL | | instruction | string | — | 按 intent 生成 | 补充分析指令 | | intent | enum | — | analyze | analyze、ocr、summarize、locate | | imageMode | enum | — | auto | auto、fast、balanced、quality、original | | reasoningEffort | enum | — | auto | auto、low、medium、high | | profile | string | — | 默认视觉 profile | 显式选择模型 |

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

intent

| 值 | 输出要求 | | --- | --- | | analyze | summary、details、ocr、regions | | ocr | summary、ocr | | summarize | summary | | locate | summary、regions |

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

imageMode

| 值 | 最长边目标 | 说明 | | --- | ---: | --- | | auto | 按 intent | 通用默认值 | | fast | 1536 px | 快速预览和摘要 | | balanced | 2048 px | 常规分析 | | quality | 4096 px | OCR、小字和细节 | | original | 不处理 | 保留原始字节 |

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

reasoningEffort

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

推荐组合：

| 场景 | intent | imageMode | reasoningEffort | | --- | --- | --- | --- | | 快速看图 | summarize | fast | low | | 常规分析 | analyze | balanced | medium | | 小字 OCR | ocr | quality | low / medium | | 主体定位 | locate | balanced | medium | | 深度细节 | analyze | quality | high |

🎞️ `analyze_video`

| 参数 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | :---: | --- | --- | | video | string | ✅ | — | 本地路径、file: URL 或 HTTP(S) URL | | instruction | string | — | 视频综合分析提示 | 补充分析要求 | | frames | integer | — | 配置值或 6 | 1–16 帧 | | profile | string | — | 默认视觉 profile | 显式选择模型 |

处理流程：

本地视频先做文件检查；远程视频流式写入唯一临时目录；
FFmpeg 验证视频轨道并探测时长；
在完整时间轴上均匀选择采样点；
抽取按时间排序的 JPEG 帧；
一次性提交给多模态模型；
使用真实帧标签校正 samples[].source；
无论成功或失败都清理远程临时文件。

📋 `list_vision_models`

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

🎨 `generate_image`

| 参数 | 类型 | 必填 | 默认值 | 限制 | | --- | --- | :---: | --- | --- | | prompt | string | ✅ | — | 1–32000 字符 | | profile | string | — | generate 默认项 | 必须支持 generate | | count | integer | — | 1 | 1–4 | | size | string | — | auto | auto 或 WIDTHxHEIGHT；边长不超过 16384 | | quality | enum | — | auto | auto、high、medium、low | | outputDirectory | string | — | 工具托管目录 | 相对路径基于服务进程 cwd |

🪄 `edit_image`

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

| 参数 | 类型 | 必填 | 限制 | | --- | --- | :---: | --- | | images | string[] | ✅ | 1–16 张本地、file: 或 HTTP(S) 参考图 | | mask | string | — | 包含 alpha 通道，显示尺寸必须与第一张参考图一致 |

结果总是保存为本地文件，不以内联 Base64 返回。省略 outputDirectory 时，文件进入状态目录下的 image-artifacts/，由服务自动保留 7 天，适合预览和临时结果。正式交付到项目的素材应显式传入绝对 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 }
    }
  ]
}

成功任务中的视觉结果固定为 status: "ok"。Provider 输出无法满足 schema、配置错误、媒体错误、网络错误或超时会转为任务级 failed，脱敏原因位于 error，不会把不完整的视觉对象伪装成成功结果。

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
    }
  ],
  "warnings": []
}

以上对象位于成功任务的 result 字段。任务失败时不返回部分图片路径，错误通过任务级 error 提供。

生图或编辑成功任务返回 recommendedAction: "report_result"。Agent 默认直接交付图片路径，不自行打开或再次分析图片；复查仅在用户明确要求执行检查、比较、质量验证或迭代验收时进行。诸如“高质量、写实、指定构图”的提示词仍只是生成约束，不构成复查授权，从而避免额外视觉调用、耗时和费用。

🎨 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 画布合同：

| 约束 | 值 | | --- | ---: | | 最小像素 | 655360 | | 最大像素 | 8294400 | | 最大边长 | 3840 | | 最大宽高比 | 3:1 | | 尺寸倍数 | 16 |

编辑准备行为：

物理应用 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 客户端在拿到 taskId 后断开或结束原请求，不会取消后台任务。任务自己的 Provider 超时仍由对应 profile 的 timeoutMs 控制。

wait_vision_task 是普通 MCP 工具调用，不要求客户端实现后台推送通知，因而同时适用于 stdio 和 localhost HTTP。服务端为每个等待请求注册一次性终态监听器；成功、失败、取消或 shutdown 都会立即唤醒所有监听同一任务的请求。等待请求断开只释放监听器，不会取消可能已经计费的 Provider 操作。

为避开常见客户端的工具调用超时，每次等待默认限制为 20 秒、最多 25 秒。窗口结束时返回不含长 message 的精简心跳，Agent 续订下一次等待；任务一旦完成则立即返回完整终态。若某个客户端的硬超时短于 20 秒，可显式传入更小的 maxWaitMs。客户端仍需允许 Agent 发起后续工具调用，因此不承诺依赖“后台通知自动唤醒 Agent”；原生 MCP progress/notification 也不作为结果交付通道。

get_vision_task 每次立即返回，供恢复和诊断使用。没有 Provider 原生进度时仍会显示当前阶段和实时 elapsedMs；有进度时会更新 progress 与最多 240 个字符的 message。最终以 succeeded 中的 result 为唯一权威结果。

任务元数据按任务单独原子写入，终态后保留 24 小时；持久化内容不含输入 prompt、参考图字节、API key 或 Provider 请求体。任务 TTL 只删除任务 JSON，不级联删除图片；托管图片由独立的 7 天策略管理，自定义输出目录不自动删除。

🧹 存储生命周期

| 数据 | 默认位置 | 自动清理 | 说明 | | --- | --- | --- | --- | | 任务 JSON | vision-tasks/ | 终态后 24 小时 | 终态记录在启动、每小时及任务访问时清理；损坏 JSON 和陈旧写入临时文件在启动或每小时扫描时回收 | | 默认生图产物 | image-artifacts/ | 7 天 | daemon / stdio 启动时立即发起后台清理，运行期间每小时清理；写入临时文件超过 24 小时后回收 | | 显式 outputDirectory | 用户指定目录 | 不自动清理 | 视为正式用户产物；只能通过明确的清理命令或用户自己的流程删除 | | 远程视频临时文件 | 系统临时目录 | 任务结束时 | 成功、失败和取消都会清理 | | daemon 日志 | daemon.log | 按容量轮转 | 单份最多 10 MiB，保留当前日志和 2 份历史日志 |

查看托管目录占用：

mcp-vision-tools artifacts status
mcp-vision-tools artifacts status --agent --json

清理超过 7 天的托管图片，或明确清空全部托管图片：

mcp-vision-tools artifacts cleanup
mcp-vision-tools artifacts cleanup --all

也可以显式指定自定义输出目录：

mcp-vision-tools artifacts status "D:\project\images"
mcp-vision-tools artifacts cleanup "D:\project\images"
mcp-vision-tools artifacts cleanup "D:\project\images" --all

清理只检查目标目录的第一层，不递归进入子目录，并且只识别 generated-*、edited-* 及对应原子写临时文件；其他文件、目录和符号链接始终忽略。为避免破坏正在保存的图片，不足 24 小时的写入临时文件即使使用 --all 也会保留。--all 是显式删除操作，只应在确认正式产物不再需要时使用。

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 上限

| intent | 上限 | | --- | ---: | | summarize | 512 | | locate | 2048 | | analyze | 4096 | | ocr | 8192 | | video | 8192 |

媒体与响应限制

| 资源 | 限制 | | --- | ---: | | 单张输入图片 | 64 MiB | | 图片像素 | 100 MP | | 自动压缩阈值 | 4 MiB | | 输入视频 | 512 MiB | | 视频抽帧 | 1–16 帧 | | 编辑参考图 | 最多 16 张 | | 编辑图片与蒙版合计 | 128 MiB | | 生图输出数量 | 1–4 张 | | 单张生图结果 | 64 MiB | | 生图结果合计 | 128 MiB | | 生图成功 JSON | 192 MiB | | 生图非 2xx body | 2 MiB | | 生图候选扫描 | 64 个 | | Chat Completions 响应 | 2 MiB | | 单个 SSE event | 256 KiB | | FFmpeg 输出 | 1 MiB |

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

图片处理原则

支持 JPEG、PNG、WebP、GIF；
MIME 来自实际图片格式；
默认不裁剪、不放大；
OCR 使用更高质量编码；
original 保持原始字节；
产物先写同目录临时文件，再以无覆盖方式发布；
文件系统不支持 hardlink 时回退到同目录原子 rename；
多图保存失败时回滚本次已发布文件。

视频处理原则

本地视频不整体读入内存；
远程视频有界流式下载；
FFmpeg 子进程具有总超时、输出上限和取消；
每个远程任务使用独立临时目录；
完成、失败或取消后清理临时文件。

🩺 运维与诊断

daemon 生命周期

首次启动选择可用端口，后续优先复用；
并发 start 通过 owner lock 收敛到一个实例；
状态保存失败时立即关闭监听，避免孤儿服务；
stop 校验 health、instance ID 和 PID；默认检测到活动任务时返回 ACTIVE_VISION_TASKS，daemon 保持运行且继续接受任务；
start、restart 和 stop 只有在用户明确授权 --force 后，才会把活动任务持久化为 interrupted、取消执行并关闭 daemon；
重启发现遗留的 queued/running 任务时标记为 interrupted，不自动恢复或重试；
启动和每小时扫描任务目录，回收损坏元数据与陈旧原子写临时文件；
daemon 日志写入前按 10 MiB 轮转，最多保留 3 份；
替换启动失败时尽力恢复旧 daemon。

Agent 收到 ACTIVE_VISION_TASKS 后，应读取 activeTasks[].taskId，逐个使用 wait_vision_task 等待终态，再重试原生命周期命令。不得自行追加 --force；只有用户明确接受任务中断及潜在重复计费风险时才能强制执行。

状态目录

| 平台 | 默认目录 | | --- | --- | | Windows | %LOCALAPPDATA%/fastcar-vision | | macOS | ~/Library/Application Support/fastcar-vision | | Linux | $XDG_STATE_HOME/fastcar-vision 或 ~/.local/state/fastcar-vision |

目录文件：

daemon.json
daemon-settings.json
daemon.log
daemon.log.1
daemon.log.2
provider-capabilities.json
vision-tasks/
image-artifacts/

启动校验

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

| 检查项 | 内容 | | --- | --- | | config | 视觉配置、profiles、默认项 | | endpoint | 默认视觉模型端点 | | imageGeneration | 有效生图配置、工具表面、adapter 文件 | | daemon | PID、instance ID、health | | MCP | server name、initialize、tools/list | | Skill | current、missing、mismatch、disabled 或 error | | clients | 客户端是否指向当前精确 URL |

显式禁用 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。

子进程

后台 daemon 必须在 CLI 退出后继续运行，视频抽帧也必须调用随包的 ffmpeg-static 或用户明确配置的 FFmpeg 二进制，因此这两处子进程不可由纯 JavaScript 库等价替代。两处都使用 shell: false 和独立参数数组，不拼接或解释 shell 命令；daemon 只启动包内 bootstrap，媒体路径只作为 FFmpeg 参数传递。

外部 adapter

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

🧩 Agent Skill

任意 CLI 命令首次运行时会检查包内 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

生命周期：

| 操作 | 行为 | | --- | --- | | 任意 CLI 启动 | missing / mismatch 时尝试自动修复 | | skill uninstall | 删除 Skill，并创建 .fastcar-vision-tools.disabled 标记 | | 后续 CLI 启动 | 发现禁用标记后保持禁用，不自动装回 | | skill sync | 删除禁用标记并显式重新安装 |

本包不使用 preinstall 或 postinstall 生命周期脚本；安装 npm 包本身不会写入用户级 Skill 目录。

🛠️ 开发与发布

本地开发

npm install
npm run build
npm test

核心目录：

src/
  cli.ts                    # CLI 与 Doctor
  daemon-log.ts             # 有界 daemon 日志轮转
  image-artifacts.ts        # 生图产物发布、统计与清理
  vision-task.ts            # 异步任务、事件等待与 TTL
  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

测试覆盖全部 MCP 工具合同、配置迁移和并发写入、媒体真实性与限制、Provider fallback、SSE、队列、任务 TTL 与异常残留、托管图片保留策略、daemon 生命周期与日志轮转、客户端注册回滚、Image2 几何、真实 stdio MCP 调用、自定义 adapter、Skill 和 CLI 自动修复。

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

发布

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

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

📄 License

MIT