Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@lutery/vision-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Vision MCP

一个基于 STDIO 的 MCP Server，为不具备视觉能力（或视觉模型成本较高）的 LLM 提供统一的图片分析能力。通过切换 Provider（环境变量配置），即可使用不同平台/厂商的多模态模型。

支持的模型 / Provider

通过 VISION_MODEL_TYPE 选择提供商：

type	Provider	默认 `VISION_API_BASE_URL`	默认 `VISION_MODEL_NAME`	备注
`glm`	智谱 GLM-4.6V	`https://open.bigmodel.cn/api/paas/v4`	`glm-4.6v`	GLM-4.6V 智谱视觉模型
`siliconflow`	SiliconFlow（OpenAI 兼容）	`https://api.siliconflow.cn/v1`	`Qwen/Qwen2-VL-72B-Instruct`	视觉模型丰富
`modelscope`	ModelScope API-Inference（OpenAI 兼容）	`https://api-inference.modelscope.cn/v1`	`ZhipuAI/GLM-4.6V`	需实名/绑定阿里云，受限额影响
`openai`	OpenAI	`https://api.openai.com/v1`	`gpt-4o`	适配 Chat Completions
`claude`	Anthropic Claude（Messages API）	`https://api.anthropic.com`	`claude-3-5-sonnet-20241022`	`baseUrl` 不要带 `/v1`
`gemini`	Google Gemini（generateContent API）	`https://generativelanguage.googleapis.com`	`gemini-2.0-flash-exp`	官方入口；代理/网关可通过 `VISION_API_BASE_URL` 覆盖

获取 API Key / Token（各平台控制台）：

GLM（智谱）：https://open.bigmodel.cn/
SiliconFlow：https://cloud.siliconflow.cn/
ModelScope：https://modelscope.cn/my/myaccesstoken
OpenAI：https://platform.openai.com/
Claude（Anthropic）：https://console.anthropic.com/
Gemini（Google AI）：https://ai.google.dev/

特性

多 Provider 一键切换（仅需改环境变量）
图片输入：URL / base64 data URL / 本地文件路径
内置系统提示词模板：UI 分析、OCR、目标检测、结构化提取等
安全：日志自动脱敏 API Key，且会过滤模型返回的 thinking/reasoning 内容
严格遵守 MCP：stdout 仅用于 JSON-RPC，日志走 stderr

安装与运行

要求：Node.js >= 18

作为 NPM 包被 MCP 客户端启动（推荐）

在 MCP 客户端（如 Claude Desktop）里配置命令为 npx：

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": ["-y", "@lutery/vision-mcp"],
      "env": {
        "VISION_MODEL_TYPE": "siliconflow",
        "VISION_API_KEY": "sk-your-key",
        "VISION_MODEL_NAME": "Qwen/Qwen2-VL-72B-Instruct",
        "VISION_API_BASE_URL": "https://api.siliconflow.cn/v1"
      }
    }
  }
}

说明：

VISION_MODEL_NAME / VISION_API_BASE_URL 可省略（会使用该 provider 的默认值）
如需更详细的配置项，建议直接参考 .env.example

也可以全局安装后直接使用可执行文件（bin 名称为 vision-mcp）：

npm i -g @lutery/vision-mcp
vision-mcp

本地开发运行

cd mcp/vision_mcp
npm install
npm run build
node dist/index.js

成功启动后，会在 stderr 输出 Vision MCP Server is running on stdio。

配置（环境变量）

最小必填：

VISION_MODEL_TYPE：选择 provider
VISION_API_KEY：对应 provider 的 key/token

常用可选：

变量	说明	默认
`VISION_MODEL_NAME`	模型名称	各 provider 内置默认值
`VISION_API_BASE_URL`	API 基础地址（不要带具体 endpoint）	各 provider 内置默认值
`VISION_API_TIMEOUT`	超时时间（毫秒）	`60000`
`VISION_MAX_RETRIES`	最大重试次数	`2`
`VISION_STRICT_URL_VALIDATION`	严格校验图片 URL 是否以 `.jpg/.jpeg/.png/.webp` 结尾	`true`
`LOG_LEVEL`	日志级别：`debug`/`info`/`warn`/`error`	`info`

Provider 特有配置：

Claude
- VISION_CLAUDE_API_VERSION：Anthropic API 版本（默认 2023-06-01）

MCP 工具（Tools）

本服务注册了 3 个工具：

1) `analyze_image`

参数：

{
  "image": "https://example.com/a.png",
  "prompt": "请描述这个界面有哪些组件",
  "output_format": "text",
  "template": "ui-analysis"
}

字段说明：

image：支持 URL / base64 data URL / 本地路径
prompt：你的分析任务描述
output_format：text 或 json（提示偏好；不会强制校验 JSON）
template：可选系统模板（见下方 list_templates）

2) `list_templates`

列出内置系统提示词模板（包含 id、用途说明等）。

3) `get_config`

返回当前生效的模型配置（API Key 会脱敏）。

图片输入规范

支持三种输入：

https://example.com/image.png

默认开启严格校验：URL 必须以 .jpg/.jpeg/.png/.webp 结尾，否则报错。可通过 VISION_STRICT_URL_VALIDATION=false 放宽（仅告警）。

Base64 Data URL

data:image/png;base64,iVBORw0KGgo...

支持的 MIME：image/jpeg / image/jpg / image/png / image/webp。

本地文件路径

./test/image.png
D:\\path\\to\\image.jpg

要求 MCP Server 进程对该路径可读；仅支持 .jpg/.jpeg/.png/.webp。

补充：Gemini provider 不支持直接传 URL 图片，本项目会在 Gemini 适配器内下载 URL 并转 base64（有大小与超时限制）。

关于流式响应（Streaming）

所有适配器均强制 stream: false，并按“完整 JSON 响应”进行解析。

如果某个上游只支持 SSE / text/event-stream，目前不支持（需要额外实现流式解析器）。

开发与测试

cd mcp/vision_mcp
npm install
npm run build

测试：

仅跑单测（不需要任何 API Key）：

npm run test:unit

跑集成测试（需要配置好 VISION_* 环境变量）：

npm test

常见问题（Troubleshooting）

1) 配置加载失败：`Missing VISION_MODEL_TYPE` / `Unsupported model type`

确认设置了 VISION_MODEL_TYPE
可用值：glm / siliconflow / modelscope / openai / claude / gemini

2) `Missing VISION_API_KEY`

确认 VISION_API_KEY 已设置（在 .env 或 MCP 客户端 env 里）

3) 404 / endpoint 错误

VISION_API_BASE_URL 必须是“base”，不要带具体 endpoint
- OpenAI / SiliconFlow / ModelScope：会自动拼 /chat/completions
- Claude：会自动拼 /v1/messages（baseUrl 不要写成 .../v1）
- Gemini：会自动拼 /{apiVersion}/models/{model}:generateContent

4) 图片 URL 校验失败

默认要求 URL 以 .jpg/.jpeg/.png/.webp 结尾
如需放宽：VISION_STRICT_URL_VALIDATION=false

安全说明

不要在 stdout 打日志（stdout 仅用于 MCP JSON-RPC），本项目日志统一走 stderr
API Key 会在日志中脱敏
会无条件过滤模型返回的 thinking/reasoning 内容，避免泄露内部推理信息

@lutery/vision-mcp