Metadata-Version: 2.4
Name: glm-4.6v-flash-mcp
Version: 0.1.0
Summary: MCP Server：基于智谱开放平台 API 底层调用 GLM-4.6V-Flash 多模态模型
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: httpx>=0.27
Requires-Dist: python-dotenv>=1.0

# GLM-4.6V-Flash MCP Server

一个基于智谱开放平台 HTTP API 的 MCP（Model Context Protocol）服务器。
底层直接调用 **GLM-4.6V-Flash** 免费多模态模型，把图片 / 视频 / 文件理解能力封装成 MCP 工具，
可接入 Codex、Cursor、Claude Desktop 等支持 MCP 的客户端。

## 底层 API

- 接口地址：`https://open.bigmodel.cn/api/paas/v4/chat/completions`
- 模型 ID：`glm-4.6v-flash`
- 鉴权方式：`Authorization: Bearer <ZHIPU_API_KEY>`
- 请求库：`httpx` 直接调用 HTTP 接口，不依赖智谱 SDK

## 提供的 MCP 工具

| MCP 工具 | 说明 |
| --- | --- |
| `analyze_image` | 图片理解：OCR、内容描述、表格解析、缺陷检测、Image2Prompt 等 |
| `analyze_video` | 视频理解（传入视频 URL 或本地视频文件） |
| `analyze_file` | 文件理解（PDF / TXT 等，传入 URL 或本地文件） |

所有工具均支持：

- `thinking`：开关深度思考模式
- `temperature`：采样温度（0~1）
- `max_tokens`：最大输出 token 数
- 本地文件路径自动转成 Base64 data URI 上传

## 快速开始

### 1. 获取 API Key

到智谱开放平台申请：<https://open.bigmodel.cn/usercenter/apikeys>

### 2. 安装

方式一：从源码安装（GitHub 克隆）

```powershell
git clone https://github.com/<你的用户名>/glm-4.6v-flash-mcp.git
cd glm-4.6v-flash-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install -e .   # 安装为 glm-mcp 命令
```

方式二：从 PyPI 安装（发布后，推荐）

```powershell
pip install glm-4.6v-flash-mcp
```

### 3. 配置 API Key

把 `.env.example` 复制为 `.env` 并填入 Key（服务器启动时自动读取），
或者设置系统环境变量：

```powershell
$env:ZHIPU_API_KEY = "你的Key"
```

Key 只需写在项目目录的 `.env` 里，**不需要**写进 `.mcp.json`：
服务器会固定读取自己项目目录下的 `.env`，无论从哪个目录启动。

### 4. 验证

```powershell
.\.venv\Scripts\python.exe scripts\smoke_test.py
.\.venv\Scripts\python.exe scripts\test_payload.py
```

## 接入客户端

### Codex / Cursor

先完成上面的安装，确保 `glm-mcp` 命令可用，然后：

项目级（把 `.mcp.json` 放到项目根目录）：

```json
{
  "mcpServers": {
    "glm-4-6v-flash": {
      "command": "glm-mcp"
    }
  }
}
```

全局（编辑 `~/.codex/config.toml`）：

```toml
[mcp_servers.glm-4-6v-flash]
command = "glm-mcp"
```

保存后重启 Codex / Cursor（或新开一个会话），MCP 服务器会自动启动，
工具 `analyze_image`、`analyze_video`、`analyze_file` 就会出现。

### Claude Desktop

把 `claude_desktop_config.example.json` 的内容合并到 Claude Desktop 的
`claude_desktop_config.json`（通常位于 `%APPDATA%\Claude\`）：

```json
{
  "mcpServers": {
    "glm-4-6v-flash": {
      "command": "glm-mcp"
    }
  }
}
```

Key 通过环境变量 `ZHIPU_API_KEY` 设置，或放在启动目录的 `.env` 中。

### 其他支持 stdio 的 MCP 客户端

安装后启动命令：

```powershell
glm-mcp
```

或使用 uvx（发布到 PyPI 后）：

```powershell
uvx glm-4.6v-flash-mcp
```

## 手动调用示例（等价于工具内部行为）

```bash
curl -X POST https://open.bigmodel.cn/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $ZHIPU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-4.6v-flash",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "https://cdn.bigmodel.cn/static/logo/register.png"}},
        {"type": "text", "text": "这张图片讲了什么？"}
      ]
    }],
    "thinking": {"type": "disabled"}
  }'
```

## 注意事项

- 官方文档说明：一次请求内不支持同时理解文件、视频和图像，每个工具一次只传一种媒体。
- API Key 属于敏感信息，不要把 `.env` 提交到仓库（已加入 `.gitignore`）；
`.mcp.json` 只包含启动命令，不含密钥，可以放心提交。
- 如需切换接口地址或模型 ID，可通过 `GLM_API_BASE`、`GLM_MODEL` 环境变量覆盖。


## 在 Codex 桌面版中使用（资源方式）

当前 Codex 桌面版不会把外部 MCP 工具暴露为 `mcp__*` 函数，而是通过资源接口使用。
本服务器额外提供了资源：

- 资源 `glm://help`：使用说明与可直接使用的示例 URI
- 资源模板 `glm://analyze/{payload}`：`payload` 为 base64url 编码的 JSON

在新会话里让 Codex 按以下步骤操作：

1. 调用 `list_mcp_resources(server="glm-4-6v-flash")` 查看资源；
2. 调用 `read_mcp_resource(server="glm-4-6v-flash", uri="glm://help")` 读取说明；
3. 按说明构造 `glm://analyze/<payload>`，再调用 `read_mcp_resource` 读取分析结果。
