# 智谱图片理解 MCP（可配置模型）

基于智谱AI 视觉大模型的图片内容理解 MCP（Model Context Protocol）工具，支持通过 URL 上传图片并进行 AI 分析。默认模型为 `GLM-4V-Plus-0111`，可通过环境变量覆盖。

## 功能特性

- 🖼️ **图片内容分析**: 使用智谱视觉模型（默认：GLM-4V-Plus-0111）分析图片内容
- 🌐 **URL支持**: 支持HTTP/HTTPS图片链接和base64编码
- 🎯 **可配置模型**: 通过环境变量 `GLM_VISION_MODEL` 配置默认模型
- ⚙️ **灵活配置**: 可自定义分析提示词、温度参数、最大token数等
- 🔐 **安全认证**: 通过环境变量管理API密钥
- 📊 **详细反馈**: 提供token使用情况和错误信息

## 支持的模型

默认支持：

- `GLM-4V-Plus-0111`：Plus 版本图像理解能力，适用于需要较高质量图像理解与更强推理的场景。

## 安装和设置

### 1. 安装依赖

```bash
npm install
```

### 2. 构建项目

```bash
npm run build
```

### 3. 设置API密钥

从[智谱AI开放平台](https://bigmodel.cn/)获取 API 密钥，然后设置环境变量：

```bash
# 方式1：设置GLM_API_KEY
export GLM_API_KEY=your_api_key_here

# 方式2：设置ZHIPU_API_KEY
export ZHIPU_API_KEY=your_api_key_here
```

### 4. 启动MCP服务器

```bash
npm start
```

## 使用方法

### 可用工具

#### `analyze_image` - 分析图片内容

分析指定URL的图片内容，返回AI生成的描述。

**参数**:
- `imageUrl` (必需): 图片的URL地址
- `prompt` (可选): 分析提示词，默认为"请详细描述这张图片的内容"
- `model` (可选): 使用的模型，默认来自环境变量或配置，通常为 "GLM-4V-Plus-0111"
- `temperature` (可选): 随机性控制(0-1)，默认0.7
- `maxTokens` (可选): 最大输出token数，默认1024

**示例**:
```json
{
  \"name\": \"analyze_image\",
  \"arguments\": {
    \"imageUrl\": \"https://example.com/image.jpg\",
    \"prompt\": \"这张图片中有什么动物？\",
    \"model\": \"GLM-4V-Plus-0111\"
  }
}
```

## 配置示例

### Claude Desktop配置

在`claude_desktop_config.json`中添加：

```json
{
  \"mcpServers\": {
    \"image-understanding\": {
      \"command\": \"node\",
      \"args\": [\"/path/to/image-understanding-mcp/dist/index.js\"],
      \"env\": {
        \"GLM_API_KEY\": \"your_api_key_here\"
      }
    }
  }
}
```

## API响应格式

### 成功响应
```json
{
  \"success\": true,
  \"analysis\": \"图片分析结果...\",
  \"model\": \"GLM-4V-Plus-0111\",
  \"tokenUsage\": {
    \"promptTokens\": 150,
    \"completionTokens\": 200,
    \"totalTokens\": 350
  }
}
```

### 错误响应
```json
{
  \"success\": false,
  \"error\": \"错误信息\",
  \"model\": \"GLM-4V-Plus-0111\"
}
```

## 开发脚本

- `npm run build` - 构建TypeScript代码
- `npm run dev` - 开发模式（监听文件变化）
- `npm start` - 启动MCP服务器
- `npm run clean` - 清理构建文件

## 错误处理

工具包含完善的错误处理机制：

- **参数验证**: 使用Zod进行输入参数验证
- **网络错误**: 处理API请求超时和网络连接问题
- **认证错误**: 识别API密钥无效、权限不足等问题
- **限流处理**: 识别API调用频率限制
- **服务器错误**: 处理API服务器内部错误

## 注意事项

1. **API密钥安全**: 请妥善保管您的API密钥，不要在代码中硬编码
2. **计费与额度**: 具体计费与额度以智谱AI官网为准
3. **图片格式**: 支持常见的图片格式（JPEG、PNG、GIF等）
4. **图片大小**: 建议图片大小不超过10MB
5. **URL访问**: 确保图片URL可以公开访问，不需要特殊权限

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request来改进这个工具。

## 相关链接

- [智谱AI开放平台](https://bigmodel.cn/)
- [GLM-4V API文档](https://docs.bigmodel.cn/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
## 配置默认模型

通过环境变量覆盖默认视觉模型：

```bash
export GLM_VISION_MODEL=GLM-4V-Plus-0111
```

若将来要切换为其它兼容模型，只需修改该环境变量，无需改代码。