npm package: @neuit/gemini-vision-skill
Description: 一个用于Claude的识图技能，调用VectorEngine API进行图像分析
Author: neuit
Latest version: 1.0.4

# Gemini Vision Skill

一个用于 Claude 的图像识别技能，调用 VectorEngine API 进行图像分析。

## 功能特性

- 🖼️ 支持三种图片输入方式：URL、Base64、本地文件
- 🔄 支持流式和非流式两种响应模式
- 📝 自定义分析提示词
- 🔧 简洁的命令行接口
- 🤖 支持 MCP 协议，可注册到 Claude Desktop / Claude Code
- 📦 可作为 Node.js 模块导入使用

## 安装

```bash
# 全局安装
npm install -g @neuit/gemini-vision-skill

# 或作为项目依赖安装
npm install @neuit/gemini-vision-skill
```

## 配置

在使用前，需要先设置 VectorEngine API 密钥：

```bash
node cli.js --set-key YOUR_API_KEY
```

密钥将保存在 `~/.gemini_vision_config.json` 文件中。

---

## 注册到 Claude Desktop / Claude Code

### 方法一：配置 claude_desktop_config.json

编辑 Claude Desktop 配置文件：

**macOS 路径：**

```text
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows 路径：**

```text
%APPDATA%\Claude\claude_desktop_config.json
```

添加以下配置：

```json
{
  "mcpServers": {
    "gemini-vision": {
      "command": "node",
      "args": ["/Users/[user]/Desktop/Mcp/gemini-vision-skill/mcp_server.js"]
    }
  }
}
```

### 方法二：使用 npx 方式（推荐）

```json
{
  "mcpServers": {
    "gemini-vision": {
      "command": "npx",
      "args": ["-y", "@neuit/gemini-vision-skill"]
    }
  }
}
```

### 重启 Claude Desktop

配置完成后，重启 Claude Desktop 即可在对话中使用 `analyze_image` 工具。

---

## 使用方法

### 命令行使用

```bash
# 分析网络图片
node cli.js --image https://example.com/photo.jpg

# 分析本地图片
node cli.js --image ./my-photo.png

# 分析 Base64 图片
node cli.js --image "data:image/png;base64,iVBORw0KGgo..."

# 自定义提示词
node cli.js --image ./photo.jpg --prompt "这张图片里有几个人?"

# 使用流式输出
node cli.js --image https://example.com/photo.jpg --stream

# 查看帮助
node cli.js --help
```

### 作为模块使用

```javascript
const { analyzeImage, saveApiKey } = require('@neuit/gemini-vision-skill');

// 设置 API 密钥（只需执行一次）
saveApiKey('your-api-key');

// 分析图片
async function main() {
  // 方式1: 分析网络图片 URL
  const result1 = await analyzeImage({
    image: 'https://example.com/photo.jpg',
    prompt: '描述这张图片的内容'
  });
  console.log(result1);

  // 方式2: 分析 Base64 编码的图片
  const result2 = await analyzeImage({
    image: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...',
    prompt: '这张图片里有什么?'
  });
  console.log(result2);

  // 方式3: 分析本地图片文件
  const result3 = await analyzeImage({
    image: './local-image.png',
    prompt: '分析这张图片'
  });
  console.log(result3);
}

main();
```

### 在 Claude 中使用 (MCP)

配置完成后，在 Claude Desktop 中可以使用以下方式：

**方式1: 使用图片 URL**
> "帮我分析这张图片：<https://example.com/photo.jpg>"

**方式2: 使用 Base64 数据**
> 使用 `analyze_image` 工具，传入 `image_base64` 参数：
> `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...`

Claude 会自动调用 `analyze_image` 工具进行图像分析。

---

## MCP 工具参数

### analyze_image

支持三种图片输入方式（三选一）：

| 参数 | 类型 | 说明 |
| ---- | ---- | ---- |
| image_url | string | 图片 URL，例如 `https://example.com/image.jpg` |
| image_base64 | string | Base64 编码的图片数据，格式为 `data:image/png;base64,BASE64_STRING` |
| image_path | string | 本地图片文件路径 |
| prompt | string | 分析提示词（可选，默认："这张图片里有什么?请详细描述。"） |
| model | string | 模型名称（可选，默认：claude-sonnet-4-20250514） |

---

## 模块 API 参数

### analyzeImage(options)

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| ---- | ---- | ---- | ------ | ---- |
| image | string | 是 | - | 图片 URL、Base64 数据或本地文件路径 |
| prompt | string | 否 | "这张图片里有什么?请详细描述。" | 分析提示词 |
| apiKey | string | 否 | 从配置文件读取 | API 密钥 |
| model | string | 否 | "claude-sonnet-4-20250514" | 模型名称 |
| stream | boolean | 否 | false | 是否使用流式输出 |
| systemPrompt | string | 否 | "You are a helpful assistant." | 系统提示词 |

## 文件结构

```text
gemini-vision-skill/
├── package.json      # 项目配置
├── index.js          # 核心模块
├── cli.js            # 命令行接口
├── mcp_server.js     # MCP 服务器 (用于 Claude Desktop)
└── README.md         # 使用文档
```

## 依赖

- `node-fetch`: HTTP 请求库
- `@modelcontextprotocol/sdk`: MCP 协议 SDK

## 许可证

MIT