zai-mcp-plus

基于 @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（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

---

安装 / 运行

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

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 中追加：

{
  "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：

{
  "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：命令行

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）

{
  "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）：

{
  "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）：

[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：命令行添加

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。