# doubao-tools

一个给 Claude Code + DeepSeek 工作流使用的 MCP 视觉分析工具。

当你主要用 Claude Code 接入 DeepSeek/其他模型写代码时，DeepSeek 侧可能不方便直接查看本地图片、截图或 UI 截图。这个 MCP 服务把本地图片交给豆包视觉模型分析，再把分析结果返回给 Claude Code，方便后续定位界面问题、阅读截图内容或给出修改建议。

## 适合场景

- Claude Code 接 DeepSeek 写代码，但需要分析本地截图
- 让 AI 查看 UI 截图，指出布局、文字、交互、可访问性问题
- 根据图片内容生成修改建议，再回到代码里处理
- 不想把截图手动上传到多个网页工具

## 功能

- 提供 `doubao_vision_analyze` MCP 工具
- 读取本地图片文件并转成 data URL
- 调用火山方舟兼容 OpenAI SDK 的 Chat Completions 接口
- 支持自定义 prompt，适合 UI 截图检查、图片描述和视觉问题排查

## 环境要求

- Node.js 18 或更高版本
- 火山方舟 API Key
- 可用的豆包视觉模型 ID（如 `doubao-seed-2-0-mini-260428`，后面的模型 ID填写时要有模型的版本号）
- Claude Code 或其他支持 MCP 的客户端

## 获取凭证

### API Key

1. 访问火山方舟控制台
3. 在「模型推理」→「API Key 管理」中创建 API Key
4. 复制 Key 备用

### 视觉模型 ID

在火山方舟控制台的「在线推理」页面，找到你可用的豆包视觉模型（如图像理解、UI 截图分析等模型），复制其模型 ID（格式通常为 `doubao-seed-2-0-mini-260428` 或类似）。

## 安装

```bash
# 克隆仓库
git clone https://github.com/amazing1102/doubao-tools-MCP.git
cd doubao-tools

# 安装依赖
npm install
```

## 配置环境变量

复制示例文件并填入自己的配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件，填入实际值：

```bash
ARK_API_KEY=your_ark_api_key
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
DOUBAO_VISION_MODEL=your_doubao_vision_model
```

> Windows 用户也可以把这些变量设置到系统环境变量中，然后通过 `run-server.cmd` 启动，无需 `.env` 文件。

## Claude Code MCP 配置

编辑 Claude Code 的 MCP 配置文件（通常位于 `~/.claude/claude_desktop_config.json` 或通过 `/mcp` 命令管理），添加以下内容：

```json
{
  "mcpServers": {
    "doubao-tools": {
      "command": "node",
      "args": ["/path/to/doubao-tools/server.js"],
      "env": {
        "ARK_API_KEY": "your_ark_api_key",
        "ARK_BASE_URL": "https://ark.cn-beijing.volces.com/api/v3",
        "DOUBAO_VISION_MODEL": "your_doubao_vision_model"
      }
    }
  }
}
```

> **注意**：将 `/path/to/doubao-tools/server.js` 替换为本机仓库的实际路径。
> - Windows 示例: `C:/Users/你的用户名/doubao-tools/server.js`
> - macOS/Linux 示例: `/home/你的用户名/doubao-tools/server.js`

如果已经把环境变量设置到系统中，MCP 配置可以简化为：

```json
{
  "mcpServers": {
    "doubao-tools": {
      "command": "node",
      "args": ["/path/to/doubao-tools/server.js"]
    }
  }
}
```

## Windows 启动脚本

如果你把环境变量保存到了 Windows 用户环境变量里，可以使用启动脚本：

```bat
run-server.cmd
```

该脚本会从用户环境变量中读取 `ARK_API_KEY`、`ARK_BASE_URL`、`DOUBAO_VISION_MODEL` 并启动服务。

## 工具参数

### `doubao_vision_analyze`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `image_path` | string | 是 | - | 本地图片的绝对路径 |
| `prompt` | string | 否 | 详细中文 prompt | 分析图片时使用的提示词 |

支持的图片格式：PNG、JPG、JPEG、GIF、BMP、WebP、TIFF。

## 使用方式示例

在 Claude Code 中可以让模型调用这个工具，例如：

```text
请用 doubao_vision_analyze 分析这张截图：C:\Users\me\Desktop\screenshot.png
重点看 UI 有没有文字溢出、布局错位和可访问性问题。
```

豆包视觉模型会先读图并返回分析结果，然后你可以继续让 Claude Code/DeepSeek 根据结果修改代码。

## 常见问题

### 工具在 Claude Code 中不可用

检查 MCP 配置是否正确加载，确认 `command` 为 `node`，`args` 路径正确指向 `server.js`。

### 认证失败 (401/403)

检查 `ARK_API_KEY` 是否正确配置，确认 API Key 未过期且拥有对应模型的调用权限。

### 模型未找到 (404)

检查 `DOUBAO_VISION_MODEL` 模型 ID 是否拼写正确，确认该模型已在火山方舟控制台开通。

### 网络连接失败

如果不在中国内地，可能需要确认能否正常访问 `ark.cn-beijing.volces.com`，必要时配置代理。

## 许可协议

[ISC](LICENSE)