# glm-vision MCP Server

给任意 AI Agent 加上「看图」能力。底层调用智谱**完全免费**的视觉推理模型，
通过 MCP 协议暴露成标准工具，任何支持 MCP 的客户端都能直接用，**零 API 费用**。

> 💡 **免费保证**：全部使用智谱福利专区的免费模型（GLM-4.6V-Flash / GLM-4.1V-Thinking-Flash / GLM-4V-Flash），
> 不包含任何付费模型，长期使用也不会产生费用。

## 暴露的工具

### `analyze_image(image_input, question, thinking)`

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `image_input` | string | 必填 | 图片的 http/https URL **或本地文件绝对路径** |
| `question` | string | `请详细描述这张图片` | 要向模型提的问题 |
| `thinking` | bool | `false` | 开启思考模式，复杂图表/GUI/推理场景更准 |

返回：模型输出的文字分析结果。

**特性**
- 本地图片自动读成裸 base64 传输，**不需要图床、不需要公网 URL**
- 单图 5MB 上限校验（智谱限制）
- 遇到 429 限流自动退避重试 3 次（1.5s / 3s / 4.5s）
- 仍失败则自动降级：`glm-4.6v-flash` → `glm-4.1v-thinking-flash` → `glm-4v-flash`（全免费），
  降级时会在回答开头标明用了哪个模型

---

## 部署三步

### 1. 装依赖

```bash
pip install -r requirements.txt
```

> ⚠️ **关键坑**：`mcp` 必须装 1.x。最新的 `mcp 2.0.0` 移除了内置的
> `mcp.server.fastmcp` 模块，装了会直接 ImportError。所以是 `pip install "mcp<2"`。
>
> ⚠️ **另一个坑**：不要装 `zai` 或 `zhipuai` —— PyPI 上这两个名字都是无关的占位包
> （`zai` 是 Zalando 的、`zhipuai` 导入名已变）。本 server 走 **OpenAI 兼容客户端**
> 直连智谱接口（`base_url=https://open.bigmodel.cn/api/paas/v4`），只需要 `openai` 包。

### 2. 配 API Key

去 [bigmodel.cn](https://open.bigmodel.cn) 手机号注册 → 控制台「API Keys」新建，免费。

Key 有两种给法，**环境变量优先级更高**：

- **方式 A（推荐）**：设环境变量 `ZHIPU_API_KEY=你的key`
- **方式 B**：把 `zhipu_key.txt.example` 改名为 `zhipu_key.txt`，里面填上 Key
  （脚本会自动读同目录下的这个文件）

### 3. 配到客户端

在客户端的 MCP 配置文件里加一段（路径换成你自己的）：

```json
{
  "mcpServers": {
    "glm-vision": {
      "command": "python",
      "args": ["/绝对路径/到/glm_vision_mcp.py"],
      "env": {
        "ZHIPU_API_KEY": "你的key"
      }
    }
  }
}
```

各客户端的配置文件位置：

| 客户端 | 配置文件路径 |
|---|---|
| WorkBuddy | `~/.workbuddy/mcp.json` |
| Claude Desktop (Win) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Desktop (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Cursor | 项目内 `.cursor/mcp.json` 或全局 `~/.cursor/mcp.json` |
| Cline / Roo (VSCode) | 插件设置里的 `cline_mcp_settings.json` |
| Continue | `~/.continue/config.json` 的 `mcpServers` 段 |

> `command` 建议写 Python 解释器的**绝对路径**（如 `D:/python/python.exe`），
> 避免客户端启动时 PATH 里找不到 `python`。

**配完必须重启客户端** —— MCP 进程只在客户端启动时 spawn 一次，改配置或改代码都不会热重载。

---

## 验证是否成功

重启客户端后，让 Agent 分析一张图即可：

> 帮我看看 `D:\test.png` 这张图里有什么

如果 Agent 说找不到工具，检查：配置文件 JSON 语法、脚本绝对路径是否正确、
是否重启了客户端、客户端是否需要手动「信任/启用」这个 server（WorkBuddy、Cursor 都有这一步）。

## 常见错误对照

| 现象 | 原因 |
|---|---|
| `429` / `1305` | 免费模型限流，不是 Key 无效。server 已自动重试+降级 |
| `401` | Key 真的无效或没读到 |
| `ModuleNotFoundError: mcp.server.fastmcp` | 装成 mcp 2.x 了，重装 `pip install "mcp<2"` |
| `未配置智谱 API Key` | 环境变量和 `zhipu_key.txt` 都没有 |
| `图片过大` | 单图超 5MB，先压缩 |

## 文件清单

| 文件 | 必需 | 说明 |
|---|---|---|
| `glm_vision_mcp.py` | ✅ | server 本体，唯一的核心文件 |
| `requirements.txt` | 建议 | 依赖清单 |
| `zhipu_key.txt` | 可选 | 不用环境变量时才需要，内容就是一行 Key |
| `README.md` | 可选 | 本文档 |