Picsense README

picsense

本地图片/视频识别 MCP，让单模态基座模型获得多模态视觉能力。

picsense 是一款本地安装的 MCP（Model Context Protocol）服务。它通过调用多模态视觉模型 API，让任何单模态基座模型（如 GLM-5.2 这类无法直接处理图片/视频的模型）也能识别图片与视频内容。

核心差异化：支持多轮迭代识别——基座模型可在处理任务的过程中多次调用，边干边查，逐步精修对图片/视频的理解。

功能

四个工具，按输入形态划分（不按场景拆工具，把 prompt 控制权交给基座模型）：

工具	输入	用途
`analyze_images`	图片数组 + prompt + 可选 `session_id`	图片识别 + 多轮迭代（核心工具；传一张是单图，传多张是批量/对比）
`analyze_video`	视频（URL / 本地路径）+ prompt + 可选 `session_id`	视频识别（抽帧后送视觉模型）+ 多轮迭代
`list_sessions`	无	查看当前所有识别会话的列表与简介
`analyze_document`	文档（URL / HTML / markdown）	解析文档，识别其中所有图片，返回标注了图片描述的完整文档

多轮迭代识别

传统图片识别 MCP 是一次性的：给一张图 + 一个 prompt，返回描述，结束。但一次性描述往往不够详细或不够准确。

picsense 通过 session 机制支持多轮：

首次调用 analyze_images（不传 session_id）→ 创建 session，返回描述 + session_id
基座模型判断描述是否满足需求，不满足则再次调用（传入 session_id）→ 在已有对话基础上追加提问
重复直到满足，基座模型基于最终描述继续处理任务

Code

第 1 轮：analyze_images(图 + 初始 prompt) → description A + session_id
第 2 轮：analyze_images(session_id + "重点描述导航栏样式") → description B
... 直到满足 ...

这是「边干边查」的能力——基座模型在写代码过程中发现细节不清，可以随时重新读取图片的某个局部。

安装

需要 Node.js ≥ 20。无需克隆仓库——直接用 npx 即可：

Terminal

npx @honlnk/picsense

或全局安装：

Terminal

npm install -g @honlnk/picsense
picsense

本地开发：克隆仓库后 pnpm install && pnpm build，入口在 dist/index.js。

视频识别的 ffmpeg 依赖

视频识别（analyze_video）需要 ffmpeg。安装时会自动下载内置的 ffmpeg-static 二进制。若该二进制下载失败（如 --ignore-scripts、企业内网代理屏蔽 GitHub releases），picsense 会自动 fallback 到系统的 ffmpeg——因此只要系统装了 ffmpeg 即可：

bash

# macOS
brew install ffmpeg
# Debian / Ubuntu
apt install ffmpeg

pnpm 用户：pnpm 默认不运行第三方包的安装脚本，若用 pnpm 全局安装发现二进制未下载，确认 package.json 的 pnpm.onlyBuiltDependencies 已包含 ffmpeg-static，或直接装系统 ffmpeg 走 fallback。

配置

通过环境变量配置，代码内零硬编码。环境变量在 MCP 客户端的配置里通过 env 字段传入（见下方接入示例），本地开发时也可用 .env 文件。

环境变量

变量	必填	默认值	说明
`DEFAULT_PROVIDER`	否	`openai`	默认 provider（`openai` / `chat` / `anthropic`；`qwen` / `kimi` 规划中）
`OPENAI_API_KEY`	是*	—	OpenAI API Key（当 provider=openai 时必填）
`OPENAI_MODEL`	是*	—	OpenAI 模型名（如 `gpt-5.6-sol`）
`OPENAI_BASE_URL`	否	`https://api.openai.com/v1`	自定义 base URL（代理或兼容网关）。会自动规范化：不带 `/v1` 则补上
`CHAT_API_KEY`	是*	—	Chat Completions 协议的 API Key（当 provider=chat 时必填）
`CHAT_MODEL`	是*	—	模型名（如 `hy4-preview`、`deepseek-v4-flash`）
`CHAT_BASE_URL`	否	`https://api.openai.com/v1`	兼容网关 base URL（腾讯传 `https://copilot.tencent.com/v2` 等）。自动规范化同上（`/v2` 等版本后缀原样保留）
`ANTHROPIC_API_KEY`	是*	—	Anthropic 协议的 API Key（当 provider=anthropic 时必填）
`ANTHROPIC_MODEL`	是*	—	模型名（如 `claude-sonnet-4`、`deepseek-v4-flash-vision-exp`）
`ANTHROPIC_BASE_URL`	否	`https://api.anthropic.com`	兼容端点 base URL（如 `https://api.deepseek.com/anthropic`）。自动补 `/v1` 后请求 `/v1/messages`
`MAX_IMAGE_MB`	否	`5`	单张图片大小上限（MB）
`MAX_VIDEO_MB`	否	`100`	单个视频大小上限（MB）
`VIDEO_MAX_FRAMES`	否	`30`	视频抽帧的最大帧数（覆盖大多数 30 秒以内的短视频）
`VIDEO_FPS`	否	`1`

* 默认 provider 的 Key/Model 必填；其他 provider 仅在切换使用时才需要。

API 格式（三协议并存）：

openai — OpenAI Responses API（/v1/responses 原生格式），兼容任何实现了 Responses API 的网关；

chat — OpenAI Chat Completions（/chat/completions，内部始终流式以兼容强制流式的网关），适配腾讯 Coding Copilot、DeepSeek 官方及绝大多数 OpenAI 兼容网关；

anthropic — Anthropic Messages API（/v1/messages，x-api-key 鉴权，图片自动转 base64），适配 Anthropic 官方与 DeepSeek 官方 /anthropic 端点。

多 provider 配置示例

OpenAI Responses（首版推荐）：

bash

DEFAULT_PROVIDER=openai
OPENAI_API_KEY=sk-xxx
OPENAI_MODEL=gpt-5.6-sol

Chat Completions（腾讯 Coding Copilot 示例）：

bash

DEFAULT_PROVIDER=chat
CHAT_API_KEY=ck-xxx
CHAT_MODEL=hy4-preview
CHAT_BASE_URL=https://copilot.tencent.com/v2

Anthropic（DeepSeek 官方 anthropic 端点示例）：

bash

DEFAULT_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-xxx
ANTHROPIC_MODEL=deepseek-v4-flash-vision-exp
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic

Qwen（后续支持） / Kimi（后续支持）： 适配器规划中（两者协议均为 Chat Completions 兼容，可直接先用 chat provider 配置）。新增 provider 只需实现 VisionProvider 接口。

接入 AI 客户端

ZCode

在 ZCode 的 MCP 配置中加入：

config.json

{
  "mcpServers": {
    "picsense": {
      "command": "npx",
      "args": ["-y", "@honlnk/picsense"],
      "env": {
        "DEFAULT_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-xxx",
        "OPENAI_MODEL": "gpt-5.6-sol"
      }
    }
  }
}

-y 让 npx 首次运行时自动确认安装，避免阻塞。

Claude Desktop / Cursor / 其他 MCP 客户端

配置 JSON 结构相同（command + args + env），按各客户端的 MCP 配置位置填入即可。

Windows

Windows 上 npx 需通过 cmd 包裹：

config.json

{
  "mcpServers": {
    "picsense": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@honlnk/picsense"],
      "env": {
        "DEFAULT_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-xxx",
        "OPENAI_MODEL": "gpt-5.6-sol"
      }
    }
  }
}

单模态模型场景说明： 在 ZCode + 单模态模型（如 GLM-5.2）下，用户粘贴的图片会被 ZCode 自动上传图床，以 http URL 形态到达 MCP 工具。image_sources 已设计为自动识别 URL / 本地路径 / base64，无需额外处理。

图片限制

格式：jpg / jpeg / png
单张大小：≤ 5MB

视频识别说明

由于默认 provider（OpenAI Responses API）原生不支持视频，analyze_video 采用抽帧方案：用 ffmpeg 把视频解码成 JPEG 帧序列，再作为多张图发送给视觉模型。ffmpeg 优先用内置的 ffmpeg-static 二进制，下载失败时自动 fallback 到系统 ffmpeg（见上方安装说明）。

默认每秒抽 1 帧、最多 30 帧（可通过 VIDEO_FPS / VIDEO_MAX_FRAMES 调整）
视频格式：mp4 / mov / m4v / avi / wmv / webm / mkv / flv / mpeg / mpg
单个视频大小：≤ 100MB（可通过 MAX_VIDEO_MB 调整）
URL 视频会先下载到临时目录再抽帧，用完即清理

使用示例

单图识别：

Code

analyze_images({
  image_sources: ["https://example.com/screenshot.png"],
  prompt: "描述这张 UI 截图的整体布局"
})

多轮迭代——细化某个局部：

Code

// 第 2 轮（复用上一轮返回的 session_id）
analyze_images({
  session_id: "<上一轮返回的 session_id>",
  prompt: "重点描述导航栏的样式，包括颜色、间距、字体"
})

多图对比：

Code

analyze_images({
  image_sources: ["https://example.com/expected.png", "https://example.com/actual.png"],
  prompt: "对比这两张图，找出差异"
})

视频识别：

Code

analyze_video({
  video_source: "https://example.com/demo.mp4",
  prompt: "描述这段视频的内容和关键画面"
})

文档图片标注：

Code

analyze_document({
  document: "https://example.com/article-with-images"
})
// 返回标注了每张图片描述的完整文档

技术栈

TypeScript + Node.js（stdio 本地 MCP）
@modelcontextprotocol/sdk 官方 SDK
多 provider 架构（VisionProvider 接口）
零第三方 HTTP 库（仅用内置 fetch）

开发

bash

pnpm install
pnpm build         # 编译
pnpm typecheck     # 类型检查
pnpm dev           # tsx watch 调试
pnpm smoke         # image-loader 冒烟（无需 API Key）
pnpm smoke:session # session-manager 单元测试（mock provider）
pnpm smoke:tools   # 四个工具逻辑测试（mock provider）
pnpm smoke:video   # 视频抽帧 + 工具逻辑测试（真实 ffmpeg，无需 API Key）
pnpm e2e           # 端到端 stdio 协议测试

许可证

Apache-2.0