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，架构决策见 docs/adr/。

前置条件

• 已安装 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 块里加一行：

"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 并安装插件

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. 验证

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 工具。

更新

源码改动后，在本仓库目录执行：

npm install
npm run release     # 重新构建 dist/index.cjs

然后把改动（包含 dist/index.cjs）提交并推送。目标机器执行：

claude plugin update doubao-image-recognition

开发

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 服务端入口，注册两个工具