# zai-mcp-plus

基于 [`@z_ai/mcp-server`](https://www.npmjs.com/package/@z_ai/mcp-server)（Z.AI 视觉理解 MCP Server，Apache-2.0）的**本地增强版**，主要解决原版无法对接自定义 OpenAI 兼容接口的问题。

> 项目路径：`/path/to/zai-mcp-plus`
> 启动命令：`node /path/to/zai-mcp-plus/build/index.js`

---

## 基于什么修改

- **基线版本**：npm 包 [`@z_ai/mcp-server@0.1.4`](https://www.npmjs.com/package/@z_ai/mcp-server)（Z.AI 出品，Apache-2.0）。
- **修改方式**：直接在该版本发布包的 `build/`（已编译代码）基础上修改，未重新走 TypeScript 编译；`package.json` 版本号标记为 `0.1.4-plus` 以示区分。
- **未改动**：8 个视觉工具的定义、prompt、以及发给模型的请求体结构均保持原版不变。

## 改动了哪些功能

在原版只支持官方 `ZAI` / `ZHIPU` 平台、且不暴露自定义 endpoint 的基础上，新增 / 修复了以下功能：

1. **自定义接口地址**：支持通过环境变量配置任意符合 OpenAI 规范的多模态接口地址，不再写死官方域名。
2. **自动补全地址斜杠**：接口地址无论是否带结尾 `/`，都会自动规范为正确请求路径，避免路径拼接导致的 404。
3. **自定义视觉模型**：支持通过环境变量指定视觉模型名称（默认 `glm-4.6v`），可指向后端任意视觉模型。
4. **图片/视频 URL 自动转 base64**：传入图片或视频 URL 时，会先在本地下载并转为 base64 再发送，兼容那些自身不抓取远程 URL 的接口。
5. **内联图片兼容**：客户端若直接传入 `data:` URI 或裸 base64 图片，也能正确封装为合法格式，不再误报文件找不到或 `image_url` 格式错误。
6. **可选调试日志**：开启后记录实际发出的图片类型，便于排查黑图 / `image_url` 报错等问题。

---

## 目录结构

```
zai-mcp-plus/
├── build/                 # 编译后的运行代码（直接由 node 运行）
│   ├── index.js           # MCP Server 入口
│   ├── core/              # 核心：environment / chat-service / file-service / base-image-service
│   ├── tools/             # 8 个视觉工具
│   ├── prompts/
│   └── utils/
├── node_modules/          # 依赖（zod, @modelcontextprotocol/sdk）
├── package.json
└── README.md
```

---

## 安装 / 运行

依赖已安装好。若需重新安装：

```bash
cd /path/to/zai-mcp-plus
npm install
node build/index.js        # 由 MCP 客户端以 stdio 方式拉起，无需手动运行
```

---

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `Z_AI_BASE_URL` | ✅（用接口时） | 官方域名 | 接口地址，**会自动补 `/`**。例如 `http://your-openai-host/v1` |
| `Z_AI_API_KEY` | ✅ | — | 接口 / 平台 API Key |
| `Z_AI_VISION_MODEL` | ❌ | `glm-4.6v` | 视觉模型名（需后端真支持视觉） |
| `Z_AI_VISION_MODEL_TEMPERATURE` | ❌ | `0.8` | 温度 |
| `Z_AI_VISION_MODEL_TOP_P` | ❌ | `0.6` | top_p |
| `Z_AI_VISION_MODEL_MAX_TOKENS` | ❌ | `32768` | 最大输出 token |
| `Z_AI_TIMEOUT` | ❌ | `300000` | 请求超时（ms） |
| `Z_AI_RETRY_COUNT` | ❌ | `1` | 失败重试次数 |
| `ZAI_DEBUG` | ❌ | 关闭 | 设为 `1` 写调试日志到 `/tmp/zai_debug.log` |

> 兼容原版：`Z_AI_MODE`（或 `PLATFORM_MODE`）仍可设为 `ZAI` / `ZHIPU` 选择官方平台；但接接口时直接用 `Z_AI_BASE_URL` 即可。

---

## 客户端配置示例

### Claude Code

支持用户级、项目级配置与命令行三种方式。

**方式 A：用户级（`~/.claude.json`）**

在 `mcpServers` 中追加：

```json
{
  "mcpServers": {
    "zai-mcp-plus": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/zai-mcp-plus/build/index.js"],
      "env": {
        "Z_AI_BASE_URL": "http://your-openai-host/v1",
        "Z_AI_VISION_MODEL": "你的视觉模型名",
        "Z_AI_API_KEY": "你的 API Key"
      }
    }
  }
}
```

**方式 B：项目级（`.mcp.json`）**

在项目根目录创建 `.mcp.json`：

```json
{
  "mcpServers": {
    "zai-mcp-plus": {
      "command": "node",
      "args": ["/path/to/zai-mcp-plus/build/index.js"],
      "env": {
        "Z_AI_BASE_URL": "http://your-openai-host/v1",
        "Z_AI_VISION_MODEL": "你的视觉模型名",
        "Z_AI_API_KEY": "你的 API Key"
      }
    }
  }
}
```

**方式 C：命令行**

```bash
claude mcp add zai-mcp-plus -s user \
  -e Z_AI_BASE_URL=http://your-openai-host/v1 \
  -e Z_AI_VISION_MODEL=你的视觉模型名 \
  -e Z_AI_API_KEY=你的APIKey \
  -- node /path/to/zai-mcp-plus/build/index.js
```

### CodeBuddy

支持用户级与项目级 JSON 配置（无 TOML 配置）。

**方式 A：用户级（`~/.codebuddy/mcp.json`）**

```json
{
  "mcpServers": {
    "zai-mcp-plus": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/zai-mcp-plus/build/index.js"],
      "env": {
        "Z_AI_BASE_URL": "http://your-openai-host/v1",
        "Z_AI_VISION_MODEL": "你的视觉模型名",
        "Z_AI_API_KEY": "你的 API Key"
      }
    }
  }
}
```

**方式 B：项目级（`.codebuddy/mcp.json`）**

在项目根目录创建 `.codebuddy/mcp.json`，内容与方式 A 的 `mcpServers` 结构一致。

### Codex（OpenAI Codex CLI）

Codex 支持两种配置方式，任选其一即可。

**方式 A：`mcp.json`（JSON，格式与 Claude Code 一致）**

写入 `~/.codex/mcp.json`（或项目级 `.codex/mcp.json`）：

```json
{
  "mcpServers": {
    "zai-mcp-plus": {
      "command": "node",
      "args": ["/path/to/zai-mcp-plus/build/index.js"],
      "env": {
        "Z_AI_BASE_URL": "http://your-openai-host/v1",
        "Z_AI_VISION_MODEL": "你的视觉模型名",
        "Z_AI_API_KEY": "你的 API Key"
      }
    }
  }
}
```

**方式 B：`config.toml`（TOML）**

写入 `~/.codex/config.toml`（或项目级 `.codex/config.toml`）：

```toml
[mcp_servers.zai-mcp-plus]
command = "node"
args = ["/path/to/zai-mcp-plus/build/index.js"]

[mcp_servers.zai-mcp-plus.env]
Z_AI_BASE_URL = "http://your-openai-host/v1"
Z_AI_VISION_MODEL = "你的视觉模型名"
Z_AI_API_KEY = "你的 API Key"
```

**方式 C：命令行添加**

```bash
codex mcp add zai-mcp-plus \
  --node \
  -- /path/to/zai-mcp-plus/build/index.js \
  -e Z_AI_BASE_URL=http://your-openai-host/v1 \
  -e Z_AI_VISION_MODEL=你的视觉模型名 \
  -e Z_AI_API_KEY=你的APIKey
```

修改配置后**重启客户端**让 MCP 重新加载。

---

## 提供的工具（与原版一致，共 8 个）

- `analyze_image`：通用图片理解（兜底工具）
- `ui_to_artifact`：UI 截图转前端代码 / prompt / 规格 / 描述
- `extract_text_from_screenshot`：截图 OCR 与文本提取
- `diagnose_error_screenshot`：报错截图诊断与修复建议
- `understand_technical_diagram`：架构图 / 流程图 / UML 理解
- `analyze_data_visualization`：图表数据洞察
- `ui_diff_check`：UI 视觉回归对比
- `analyze_video`：视频内容理解

调用示例（在客户端对话里）：

```
用 mcp 工具 zai-mcp-plus 的 analyze_image 理解一下 /绝对路径/不登录.png
```

---

## 常见问题排查

**1. 启动即报 404**
`Z_AI_BASE_URL` 没带结尾 `/` 时原版会拼出 `.../v1chat/completions`。本 fork 已自动补 `/`，若仍 404 请确认接口路径本身是否就是 `.../chat/completions`。

**2. 报 `image_url must be base64-encoded image or a URL`**
说明发给接口的 `image_url` 不是合法的 `data:` URL。本 fork 已对路径 / URL / `data:` URI / 裸 base64 做了全面兜底；若仍出现，开启 `ZAI_DEBUG=1` 后看 `/tmp/zai_debug.log` 里 `url_kind` 是 `data` / `http` / `OTHER`，据此定位。

**3. 模型说"图片是黑的"**
先确认源图本身是否正常（本机用图片查看器打开）。本 fork 对本地文件会读成 `data:image/png;base64,...` 发送。若客户端**自身**把图读进上下文时渲染成黑块（与 MCP 无关），属于客户端图片预览问题，可让模型改走 MCP 工具、避免客户端直接读图。

**4. 只想清掉调试日志**
`ZAI_DEBUG` 不设或设为 `0` 即可；日志文件在 `/tmp/zai_debug.log`，可手动删除。

---

## 许可

基于 `@z_ai/mcp-server` 修改，原项目 Apache-2.0。