内容
# VLM MCP 服务器
[中文文档](README.zh-CN.md) |
一款提供视觉和视频分析工具的模型上下文协议（MCP）服务器，**可与任何模型提供商配置**。
本服务器是 `@z_ai/mcp-server` 的逆向工程和扩展实现（Apache-2.0，鸣谢 Chao Gong, Lei Yuan / Z.AI）。它引入了一个**提供商抽象层**，使得同一套工具可以针对三个 API 系列运行：
- **聊天补全** — OpenAI 兼容的 `POST {base}/chat/completions`（OpenAI, Z.AI, Zhipu, OpenRouter, Together, Groq, DeepSeek, Moonshot, 本地 Ollama / LM Studio, …）
- **响应** — OpenAI `POST {base}/responses`（gpt-4o, o-series 推理模型）
- **Anthropic 消息** — `POST {base}/v1/messages`（Claude, 以及 Anthropic 兼容网关）
## 快速开始
```shell
npx -y @syntx-ai/vlm-mcp-server
```
服务器端就此完成 — 它通过 stdio 使用 MCP。你需要在 MCP 客户端中配置它。选择你的提供商并设置三个环境变量：
| 提供商 | 环境变量 |
|----------|----------------------|
| 聊天补全 | `OPENAI_CHAT_COMPLETIONS_API_KEY` · `OPENAI_CHAT_COMPLETIONS_BASE_URL` · `OPENAI_CHAT_COMPLETIONS_MODEL` |
| 响应 | `OPENAI_RESPONSES_API_KEY` · `OPENAI_RESPONSES_BASE_URL` · `OPENAI_RESPONSES_MODEL` |
| Anthropic | `OPENAI_ANTHROPIC_API_KEY` · `OPENAI_ANTHROPIC_BASE_URL` · `OPENAI_ANTHROPIC_MODEL` |
**Claude Code 一行命令** （聊天补全示例 — 替换为你的值）：
```shell
claude mcp add -s user vlm-mcp-server \
--env OPENAI_CHAT_COMPLETIONS_API_KEY=sk-... \
OPENAI_CHAT_COMPLETIONS_BASE_URL=https://api.openai.com/v1/ \
OPENAI_CHAT_COMPLETIONS_MODEL=gpt-4o \
-- npx -y @syntx-ai/vlm-mcp-server
```
对于其他客户端（Cline, OpenCode, Crush, Roo Code, …），请参阅 [客户端配置](docs/clients.md)。
## 可用工具
### 图片分析
| 工具 | 描述 |
|------|-------------|
| `ui_to_artifact` | 将 UI 截图转换为代码、提示、规格或描述 |
| `extract_text_from_screenshot` | OCR — 从截图中提取代码、终端输出或文本 |
| `diagnose_error_screenshot` | 分析错误消息和堆栈跟踪，提供修复建议 |
| `understand_technical_diagram` | 分析架构、流程图、UML、ER 和序列图 |
| `analyze_data_visualization` | 从图表中提取洞察、趋势和异常 |
| `ui_diff_check` | 视觉回归 — 比较预期和实际 UI，优先显示问题 |
| `analyze_image` | 通用图片分析（备用） |
### 视频分析
| 工具 | 描述 |
|------|-------------|
| `analyze_video` | 视频内容分析（本地文件或 URL，≤8MB，MP4/MOV/M4V） |
## 配置
服务器在启动时从 `.env` 文件中加载变量（实际环境变量优先）。支持三层配置；优先级为 **每提供商组 > 通用 > 旧版**。
### 每提供商组
独立配置每个 API 系列。`auto` 会选择第一个同时设置了密钥和基准 URL 的组。
| 变量组 | API 系列 |
|----------------|------------|
| `OPENAI_CHAT_COMPLETIONS_API_KEY` / `_BASE_URL` / `_MODEL` | 聊天补全 |
| `OPENAI_RESPONSES_API_KEY` / `_BASE_URL` / `_MODEL` | 响应 |
| `OPENAI_ANTHROPIC_API_KEY` / `_BASE_URL` / `_MODEL` | Anthropic 消息 |
### 通用变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `VLM_API_KEY` | API 密钥 | *(必填)* |
| `VLM_BASE_URL` | 提供商 API 根 | Zhipu 默认值 |
| `VLM_VISION_MODEL` | 模型名称 | `glm-4.6v` |
| `VLM_PROVIDER` | 提供商系列：`auto` / `chat-completions` / `responses` / `anthropic` | `auto` |
| `VLM_VISION_MODEL_TEMPERATURE` | 采样温度 | `0.8` |
| `VLM_VISION_MODEL_TOP_P` | Top-p | `0.6` |
| `VLM_VISION_MODEL_MAX_TOKENS` | 最大输出令牌 | `32768` |
| `VLM_TIMEOUT` | 请求超时（毫秒） | `300000` |
| `VLM_RETRY_COUNT` | 重试次数 | `1` |
| `VLM_ENABLE_THINKING` | 启用提供商特定的推理 / 思考请求字段。默认关闭，以支持广泛的 OpenAI 兼容聊天补全。 | `false` |
| `VLM_ANTHROPIC_VERSION` | `anthropic-version` 头部（仅限 Anthropic） | `2023-06-01` |
| `VLM_LOG_PATH` | 自定义日志文件路径 | `~/.vlm/vlm-mcp-YYYY-MM-DD.log` |
### 提供商自动检测
在 `auto` 模式下（未设置 `OPENAI_*` 组时），提供商的推断如下：
- 基准 URL 包含 `anthropic`，或密钥以 `sk-ant` 开头 → `anthropic`
- 否则 → `chat-completions`（最广泛兼容的默认值）
## 使用示例
一旦服务器在客户端安装完成，就可以通过对话使用它。例如，在 Claude Code 中输入 `describe this demo.png` — MCP 服务器将处理图像并返回描述（图像必须存在于当前目录中）。
> 在 Claude Code 之外，直接在客户端粘贴图像不会调用此 MCP 服务器 — 客户端会编码图像并直接调用模型 API。**最佳实践**：将图像放在本地目录中，并在对话中通过名称或路径引用它们，例如 `What does demo.png describe?`
## 故障排除
直接从命令行运行服务器，以验证其启动，隔离环境 / 权限问题：
```bash
# Linux / macOS
OPENAI_CHAT_COMPLETIONS_API_KEY=sk-... \
OPENAI_CHAT_COMPLETIONS_BASE_URL=https://api.openai.com/v1/ \
OPENAI_CHAT_COMPLETIONS_MODEL=gpt-4o \
npx -y @syntx-ai/vlm-mcp-server
# Windows CMD
set OPENAI_CHAT_COMPLETIONS_API_KEY=sk-... && set OPENAI_CHAT_COMPLETIONS_BASE_URL=https://api.openai.com/v1/ && set OPENAI_CHAT_COMPLETIONS_MODEL=gpt-4o && npx -y @syntx-ai/vlm-mcp-server
# Windows PowerShell
$env:OPENAI_CHAT_COMPLETIONS_API_KEY="sk-..."; $env:OPENAI_CHAT_COMPLETIONS_BASE_URL="https://api.openai.com/v1/"; $env:OPENAI_CHAT_COMPLETIONS_MODEL="gpt-4o"; npx -y @syntx-ai/vlm-mcp-server
```
- 如果启动成功，则环境正确 — 问题可能出在客户端的 MCP 配置中；请仔细检查。
- 如果失败，请调查错误消息（建议将其粘贴到 LLM 进行分析）。
### 常见问题
**连接失败**
1. 确保已安装 Node.js 18 或更高版本。
2. 运行 `node -v` 和 `npx -v` 以确认运行时可用。
3. 验证环境变量 (`OPENAI_*` 三元组或 `VLM_*`) 是否设置正确。
**无效 API 密钥**
1. 确认 API 密钥是否正确复制。
2. 检查 API 密钥是否已激活。
3. 确保所选提供商系列与 API 密钥（聊天补全 / 响应 / Anthropic）匹配。
4. 检查 API 密钥是否有足够的余额。
**连接超时**
1. 检查网络连接。
2. 检查防火墙设置。
3. 尝试切换到不同的提供商系列或基准 URL。
4. 增加超时时间（`VLM_TIMEOUT`，默认 300000 毫秒）。
## 架构
```
src/
├── index.ts # 入口点：启动 MCP 服务器，注册所有工具
├── types/ # 错误类型（McpError, ApiError, ValidationError, …）
├── core/
│ ├── environment.ts # 环境配置（VLM_* + OPENAI_* 组），URL 解析
│ ├── chat-service.ts # 委托给活动的 VisionProvider
│ ├── file-service.ts # 文件验证 + base64 编码（图像/视频）
│ ├── base-image-service.ts # 共享图像处理逻辑，用于所有图像工具
│ ├── api-common.ts # 消息构建器，响应帮助程序，重试包装器
│ ├── error-handler.ts # 错误层次结构 + 处理/恢复策略
│ └── logger.ts # stderr + 文件日志记录（保持 stdout JSON-clean）
├── providers/ # 可插拔模型提供商抽象
│ ├── types.ts # VisionProvider 接口，ChatMessage，postJson 帮助程序
│ ├── chat-completions.ts # OpenAI 兼容聊天补全
│ ├── responses.ts # OpenAI 响应 API
│ ├── anthropic.ts # Anthropic 消息 API
│ └── index.ts # 提供商选择（VLM_PROVIDER / 自动推断）
├── prompts/ # 每个专用工具的系统提示
└── tools/ # 8 个工具注册（7 个图像 + 1 个视频）
```
**提供商层**（`src/providers/`）是关键扩展。每个提供商都实现了 `VisionProvider` 接口，该接口接受标准化的 `ChatMessage[]`（OpenAI 聊天补全内容部分的格式作为内部通用语言）并将其转换为提供商的线缆格式。`chat-service.ts` 简单地委托给已解析的提供商，因此工具代码无需更改。
## 许可证
Apache-2.0
