👁️ @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
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"
}

视觉 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、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 次等待调用。

任务状态：

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

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

Agent 必须遵守：

1. 提交长时工具并保存 taskId；

2. 优先调用 wait_vision_task，心跳超时后继续调用同一工具；

3. 仅把 get_vision_task 用于恢复或即时检查，不用它轮询；

4. 视觉分析成功时执行 use_result；生图或编辑成功时执行 report_result，直接报告 result.images[].path；

5. 生成后视觉复查是可选项。普通生成/编辑请求不授权 Agent 再调用 analyze_image、view_image 或其他看图工具；只有用户明确要求执行检查、比较、质量验证或迭代验收时才能复查。提示词中的风格、质量、构图或布局要求只是生成约束，不是复查授权；意图不明确时直接交付，不为自检额外询问；

6. failed 或 interrupted 时说明错误及可能成本，询问用户是否重新提交；得到明确确认前不得重提；

7. cancelled 或 not_found 时报告终态，不自动重试；

8. 只有用户明确要求时才调用 cancel_vision_task。

🖼️ 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 返回。省略 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 画布合同：

编辑准备行为：

• 物理应用 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 天策略管理，自定义输出目录不自动删除。

🧹 存储生命周期

查看托管目录占用：

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

媒体与响应限制

本地文件先通过 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；只有用户明确接受任务中断及潜在重复计费风险时才能强制执行。

状态目录

目录文件：

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

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

测试覆盖配置迁移和并发写入、媒体真实性与限制、Provider fallback、SSE、队列、任务 TTL 与异常残留、托管图片保留策略、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