# doubao-seed image recognition MCP

一个 Claude Code 插件，提供基于火山方舟（Volcano Ark）`doubao-seed-2.1-turbo` 多模态模型的图片理解能力，以 MCP 工具形式对外暴露：

- **`describe_image`** - 自然语言描述图片内容（caption），可接受可选 `prompt` 指引重点。
- **`extract_text`** - OCR，只返回识别到的文字本身（程序友好，零结构、无前缀）。

两个工具都接受 `image_url`（公网 URL）或 `image_path`（本地文件路径），二选一。

> 设计与领域术语见 [`CONTEXT.md`](./CONTEXT.md)，架构决策见 [`docs/adr/`](./docs/adr/)。

## 前置条件

- 已安装 [Claude Code](https://claude.com/claude-code) CLI。
- 目标机器已安装 **Node.js ≥ 20**（插件用 `node` 启动预构建的 `dist/index.cjs`，无需 `npm install`）。
- 一个有效的火山方舟 API Key（Coding Plan）。

## 安装

### 1. 设置 API Key

插件通过环境变量 `${ARK_API_KEY}` 注入密钥，**不会**把 key 写进本仓库任何文件。推荐两种方式（任选其一）：

**方式 A - Claude Code 全局配置（推荐，省去 shell 环境变量）：**
在 Claude Code 全局 `settings.json`（Windows 通常为 `C:\Users\<你>\.claude\settings.json`）的顶层 `env` 块里加一行：
```json
"env": {
  "ARK_API_KEY": "你的key"
}
```
若已有 `env` 块，只加这一行，勿整体替换。改完重启 Claude Code。

**方式 B - 系统环境变量：**
- Linux / macOS：`echo 'export ARK_API_KEY=你的key' >> ~/.bashrc && source ~/.bashrc`
- Windows PowerShell（持久化）：`[Environment]::SetEnvironmentVariable("ARK_API_KEY","你的key","User")`，然后重启终端。

> 可选覆盖（不设则用默认值）：
> - `ARK_BASE_URL`（默认 `https://ark.cn-beijing.volces.com/api/coding/v3`，火山方舟 Coding Plan 的 OpenAI 兼容端点，支持 Responses API）
> - `ARK_MODEL`（默认 `doubao-seed-2.1-turbo`）

### 2. 添加 marketplace 并安装插件

```bash
claude plugin marketplace add https://github.com/xuhs8832/doubao-seed-image-recognition-mcp.git
claude plugin install doubao-image-recognition@doubao-image-recognition
```

> marketplace 名与插件名都来自仓库内的清单文件，无需在命令里另指定。

### 3. 验证

```bash
claude mcp list
```
应看到 `plugin:doubao-image-recognition:doubao-image-recognition ... ✔ Connected`。

启动 Claude Code，运行 `/mcp` 应能看到 `doubao-image-recognition` 服务及其两个工具。

## 使用

在 Claude Code 对话中直接让 Claude 看图即可，例如：
- "描述一下 `C:/path/to/image.png` 这张图"
- "提取 `C:/path/to/screenshot.png` 里的文字"

Claude 会自动选择 `describe_image` 或 `extract_text` 工具。

## 更新

源码改动后，在本仓库目录执行：
```bash
npm install
npm run release     # 重新构建 dist/index.cjs
```
然后把改动（**包含 `dist/index.cjs`**）提交并推送。目标机器执行：
```bash
claude plugin update doubao-image-recognition
```

## 开发

```bash
npm install
npm run build       # esbuild 打包成自包含 dist/index.cjs
npm run dev         # watch 模式
```

源码在 `src/`：
- `config.ts` - 环境变量加载
- `image.ts` - 图片输入解析（URL 透传 / 本地 base64 data URL / media_type 推断）
- `ark.ts` - 火山方舟 Responses API 调用 + 错误归一化
- `index.ts` - MCP 服务端入口，注册两个工具