# vision-mcp-worker

部署在 Cloudflare Worker 上的 MCP 服务器，给 AI 提供"看图"能力（`describe_image` 工具），附带一个果味模型状态展示页。

- **MCP 端点**：`https://<your-domain>/mcp`（Streamable HTTP，建议用 Cloudflare Access Service Auth 保护）
- **状态页**：`https://<your-domain>/`（模型与健康状态一览）
- **详细接入文档**：见 [MCP_SETUP.md](./MCP_SETUP.md)
- **部署配置模板**：见 [wrangler.toml.example](./wrangler.toml.example)（真实 `wrangler.toml` 不提交）

## 模型配置与切换（环境变量）

**模型完全通过环境变量配置，不用改代码。** 修改后 `pnpm run deploy` 生效。

### 1. Workers AI 模型（默认，免费额度）

在 `wrangler.toml` 的 `[vars]` 里设置 `VISION_MODEL`：

```toml
[vars]
VISION_MODEL = "@cf/meta/llama-3.2-11b-vision-instruct"
```

默认回退模型为 Meta Llama 3.2 11B Vision（稳定、抠文字/数字细节强、便宜）。

### 2. 第三方 OpenAI 兼容模型（可选，优先于 Workers AI）

任意 OpenAI 兼容的视觉模型提供商（OpenAI / DeepSeek / 智谱 / 中转站 / Ollama 等）：

```toml
[vars]
OPENAI_API_BASE = "https://api.example.com/v1"   # 提供商 OpenAI 兼容端点
OPENAI_API_MODEL = "gpt-4o-mini"                  # 第三方模型名（不填则复用 VISION_MODEL）
```

```bash
# API Key 用 secret 存，不要写进仓库：
npx wrangler secret put OPENAI_API_KEY
```

**优先级**：配置了 `OPENAI_API_BASE` + `OPENAI_API_KEY` → 走第三方（`chat/completions`，图片以 `image_url` 传入）；否则走 Workers AI 的 `VISION_MODEL`。

### 3. 切换示例

| 想要的效果 | 配置 |
|---|---|
| 用 Workers AI 的 llama（回退默认） | `VISION_MODEL` 设为 llama，注释掉 `OPENAI_API_BASE` |
| 用第三方模型 | 设置 `OPENAI_API_BASE` + `OPENAI_API_MODEL` + `OPENAI_API_KEY` |
| 换其他第三方模型 | 改 `OPENAI_API_MODEL` 即可，不用动代码 |

### 注意事项

- `OPENAI_API_KEY` 是 secret，存于 Cloudflare（`wrangler secret`），状态页只显示"已配置/未配置"
- 第三方中转若不稳定，健康检查会如实显示 `DEGRADED`，属正常现象
- 多模态模型才能做图片识别；纯文本模型（如 `kimi-k2` 系列）不能用于 `describe_image`

## 开发

```bash
pnpm install     # 依赖
pnpm run deploy  # 部署到 Cloudflare
pnpm test        # 测试
```

## 目录

| 文件 | 说明 |
|---|---|
| `src/index.js` | Worker 入口：MCP 端点 / 状态页 / 健康检查 / 模型路由 |
| `wrangler.toml.example` | 部署配置模板（真实配置见本地 `wrangler.toml`） |
| `tools/vision.js` | 本地截图识别脚本 |
| `tools/dashboard-demo.html` | 测试页（仪表盘） |
| `MCP_SETUP.md` | 完整接入与排障文档 |