# glm-vision-mcp

自建的 MCP（Model Context Protocol）服务器，底层调用智谱免费视觉模型 **GLM-4.6V-Flash**（`glm-4.6v-flash`，OpenAI 兼容接口）。任何支持 MCP 的客户端（Codex、Claude Desktop 等）都可以直接调用图片/视频/文件理解能力。

> ⚠️ **隐私与安全**：调用本服务器时，图片、视频、PDF/Word 等文件的**完整内容会发送到智谱云端**处理。请勿上传身份证、银行卡、合同、内部办公文件等涉密资料；普通截图、公开文档可正常使用。API Key 只放在本地 `.env`（已被 `.gitignore` 排除），切勿提交到仓库。

> 详细安装、配置、注册与使用示例见 [USAGE.md](USAGE.md)。

## 功能

| 工具 | 用途 |
| --- | --- |
| `analyze_image` | 单张或多张图片理解：OCR、复杂表格解析、内容理解、缺陷检测、Image2Prompt 等 |
| `analyze_video` | 视频内容理解、关键帧描述、时间线生成 |
| `analyze_file` | PDF / TXT / Word 等文档问答、对比、关键信息抽取 |
| `check_config` | 检查 API Key、模型、接口地址是否就绪 |

支持本地文件路径（自动转成 data URI）、http(s) URL、data URI；支持思考模式开关（`enabled` / `disabled` / `auto`）。

调用前会自动做本地校验：文件大小（图片 20 MB / 视频 500 MB / 文件 50 MB）、图片分辨率（上限 5000 万像素）、加密 PDF、视频时长（30 分钟，需本机有 ffprobe）。超限会在上传前直接给出中文提示，不浪费请求。

## 快速开始

1. 到 [智谱开放平台](https://open.bigmodel.cn/) 注册并创建 API Key（GLM-4.6V-Flash 免费）。
2. 复制 `.env.example` 为 `.env`，填入你的 Key：

   ```ini
   ZHIPU_API_KEY=你的_API_KEY
   ```

3. 安装依赖并启动：

   ```bat
   python -m venv .venv
   .venv\Scripts\python.exe -m pip install -r requirements.txt
   .venv\Scripts\python.exe server.py
   ```

   也可以直接双击 `run.bat`（自动建虚拟环境、装依赖、启动）。

4. 自检（不需要 Key）：

   ```bat
   .venv\Scripts\python.exe tests\smoke_test.py
   ```

   正常会输出可用工具列表。

## 注册到 MCP 客户端

核心就是让客户端用以下命令拉起本服务器：

```
command: <项目绝对路径>\.venv\Scripts\python.exe
args:    ["<项目绝对路径>\\server.py"]
```

### Codex CLI（`~/.codex/config.toml`）

```toml
[mcp_servers.glm-vision]
command = "C:\\path\\to\\glm-vision-mcp\\.venv\\Scripts\\python.exe"
args = ["C:\\path\\to\\glm-vision-mcp\\server.py"]
cwd = "C:\\path\\to\\glm-vision-mcp"
```

### Codex 桌面版

在「设置 → MCP 服务器」中新增一条，command 填 `.venv\Scripts\python.exe` 的绝对路径，args 填 `server.py` 的绝对路径。

### Claude Desktop（`claude_desktop_config.json`）

```json
{
  "mcpServers": {
    "glm-vision": {
      "command": "C:\\path\\to\\glm-vision-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\glm-vision-mcp\\server.py"]
    }
  }
}
```

API Key 放在项目 `.env` 里即可，客户端进程会自动读取，不需要写进客户端配置。

## 可选配置

通过环境变量或 `.env` 覆盖：

```ini
GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
GLM_MODEL=glm-4.6v-flash
```

## 常用问题

- **API Key 无效或已过期（401/403）**：检查 `ZHIPU_API_KEY` 配置，去智谱平台重新生成。
- **余额或免费额度不足（402）**：到智谱开放平台查看账户额度。
- **限流/访问量过大（429/1305）**：免费模型高峰期常见，服务器会自动重试，仍失败请稍后再试。
- **内容过大（413）**：本地前置校验已拦截大部分超限文件；仍出现请进一步压缩。
- **服务端故障（5xx）**：智谱服务暂时不可用，稍后重试。
- **“未配置 API Key”**：`.env` 没创建，或变量名不是 `ZHIPU_API_KEY`。
- **不支持同时输入**：GLM-4.6V-Flash 不允许图片、视频、文件混用，一次调用只传一种类型。
- **启动后无输出**：stdio 模式下服务器静默等待客户端连接，属正常现象。

## 测试

```bat
rem 单元测试（请求构造、图片编码、响应解析，mock 方式，不需要 Key）
.venv\Scripts\python.exe -m unittest discover -s tests -v

rem MCP 握手测试（启动 stdio 服务器并列出工具，不需要 Key）
.venv\Scripts\python.exe tests\smoke_test.py

rem 真实调用测试（需要 .env 里有 Key，会自动重试限流）
.venv\Scripts\python.exe tests\live_test.py <你的图片路径>
```