# ai-vision

支持 OpenAI 兼容协议的视觉识别 MCP 服务器。让 Claude Desktop / Cline / Cherry Studio 等 MCP 客户端获得图片识别能力，可接入 OpenAI、通义千问、智谱、Moonshot 等任意 OpenAI 兼容服务商。

> 📖 **完整使用说明（中文）**: [docs/使用说明.html](docs/使用说明.html)

## 快速开始

```bash
pnpm install
pnpm build

# 方式一：环境变量（也可直接在 MCP 客户端的 env 字段里注入）
OPENAI_API_KEY=sk-xxx node dist/index.js

# 方式二：配置文件（支持多服务商，参考 sample-config.json）
cp sample-config.json config.json
node dist/index.js --config=config.json
```

## MCP 客户端配置（推荐：env 注入，无需配置文件）

```json
{
  "mcpServers": {
    "vision": {
      "command": "ai-vision",
      "args": [],
      "env": {
        "OPENAI_API_KEY": "sk-你的密钥",
        "OPENAI_BASE_URL": "https://api.openai.com/v1",
        "OPENAI_MODEL": "gpt-4o"
      }
    }
  }
}
```

## 提供的 MCP 工具

| 工具 | 功能 |
| --- | --- |
| `analyze_image` | 分析本地图片（路径 / base64） |
| `analyze_image_url` | 分析远程图片 URL |
| `analyze_images` | 多图对比（最多 10 张） |
| `list_models` | 查询服务商可用模型 |

## 技术栈

- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) — MCP 服务器框架（stdio / Streamable HTTP）
- [openai](https://github.com/openai/openai-node) — OpenAI 兼容协议客户端
- TypeScript + pnpm

## 测试

```bash
pnpm test   # 本地 mock 服务器验证协议格式，无需真实 API Key
```