# Vision Helper MCP Server

An MCP server that adds **vision capability to any LLM**. Models that cannot see images
(the text-only LLM driving your MCP client) call `vision_helper_analyze_image`, and this server
forwards the image to a **vision-capable model on [OpenRouter](https://openrouter.ai)**,
then returns the analysis as text.

## Requirements

- Node.js 18+ (tested on 22)
- An [OpenRouter API key](https://openrouter.ai/keys) (`sk-or-v1-...`)

## Install

```powershell
npm install -g vision-helper-mcp-server
```

This installs the `vision-helper-mcp` command globally (the compiled `dist` is the
only published content). Quick check:

```powershell
vision-helper-mcp --help
```

### Development / from source

```powershell
git clone https://github.com/<you>/vision-helper-mcp-server.git
cd vision-helper-mcp-server
npm install
npm run build
node dist\index.js --help
```

## Configuration

The API key and options are resolved, in priority order:

1. **Process environment variables** — set in your MCP client's `env`/`environment`
   config (recommended; this is also where `OPENROUTER_MODEL` usually lives).
2. **Windows user environment variables** — read directly from the registry
   (`HKCU\Environment`), i.e. what `setx` writes. This matters: GUI apps (VS Code,
   Kilo, Claude Desktop, ...) do **not** re-read user env vars changed after they
   were launched, so a key set with `setx` after launching the client would otherwise
   be invisible. The server reads the registry itself (re-read on a short refresh
   cycle), so `setx` values work with no client restart.
3. **Windows system environment variables** — registry
   `HKLM\SYSTEM\...\Session Manager\Environment`.

On non-Windows platforms only step 1 applies.

| Variable | Purpose | Default |
|---|---|---|
| `OPENROUTER_API_KEY` | OpenRouter API key (required for analysis) | — |
| `OPENROUTER_MODEL` | Default vision model ID | `qwen/qwen3.8-max` |
| `OPENROUTER_FALLBACK_MODEL` | Fallback model tried automatically when the primary model's provider is busy or fails | `google/gemini-3.7-flash` |
| `OPENROUTER_QUICK_MODEL` | Default model when `quick: true` is passed to `vision_helper_analyze_image` | `meta/muse-glimmer-30b` |
| `MAX_IMAGE_SIZE` | Max image payload bytes | `10485760` (10 MB) |
| `OPENROUTER_TIMEOUT_MS` | Per-request timeout | `120000` (120 s) |

> The model can also be chosen **per call** via the `model` argument of
> `vision_helper_analyze_image`, overriding the environment default.

### Kilo (VS Code extension) configuration

Add this server as its **own** MCP entry. This example appends a `vision-helper` entry
to the `mcp` object in your Kilo config file (e.g. `~/.config/kilo/kilo.json` on
Windows):

```json
"vision-helper": {
  "type": "local",
  "command": ["vision-helper-mcp"],
  "enabled": true,
  "timeout": 120000,
  "environment": {
    "OPENROUTER_MODEL": "qwen/qwen3.8-max"
  }
}
```

`OPENROUTER_API_KEY` is optional here: if the key is set as a Windows user environment
variable (`setx OPENROUTER_API_KEY sk-or-v1-...`), the server picks it up automatically
by reading the registry — no client restart needed. Add the key to the `environment`
block only if you want it explicit in the config.

### Claude Desktop / other clients

```json
{
  "mcpServers": {
    "vision-helper": {
      "command": "vision-helper-mcp",
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-...",
        "OPENROUTER_MODEL": "qwen/qwen3.8-max"
      }
    }
  }
}
```

## Tools

This server exposes its tools under its own `vision_helper_*` names.

### `vision_helper_analyze_image`

Analyze one or more images with an OpenRouter vision model.

| Argument | Type | Description |
|---|---|---|
| `image` | `string \| string[]` | **Required.** An http(s) URL, local file path, `file://` URI, `data:` URI, or raw base64 string. Pass an array (up to 5) to analyze several images together, e.g. to compare screenshots. Only PNG, JPEG, WebP, and GIF are accepted (the formats OpenRouter supports for vision input); relative file paths resolve against the server's working directory, so prefer absolute paths or URLs. |
| `prompt` | `string` | Optional instruction, e.g. `"Transcribe all text in this screenshot"`. Defaults to a general detailed description. |
| `model` | `string` | OpenRouter model ID, e.g. `qwen/qwen3.8-max`. Defaults to `OPENROUTER_MODEL`, then to the built-in default. |
| `max_tokens` | `number` | Max tokens for the answer (64–16000). |
| `temperature` | `number` | Sampling temperature (0–2). |
| `quick` | `boolean` | Set `true` for a fast, cheap analysis — a yes/no, a short caption, an object/color check, or a quick comparison of several images (array, up to 5). Uses `OPENROUTER_QUICK_MODEL` (default `meta/muse-glimmer-30b`), caps output at 1024 tokens, and forces minimal reasoning. |

If the model's provider is busy or a request fails transiently (HTTP 429, 5xx,
timeout, or network error), the server automatically retries with the
`OPENROUTER_FALLBACK_MODEL` model (`google/gemini-3.7-flash` by default) so the
analysis does not fail. This fallback applies to the default detailed mode
(`quick: true` does not fall back). The response header shows which model
actually answered and notes when a fallback was used.

Examples of things to ask your assistant:

- "What is in this image? https://example.com/photo.jpg"
- "Analyze the screenshot at C:\Users\me\Pictures\shot.png"
- "Compare these two images: img1.png and img2.png" (pass an array)
- "Read the text from this image and list the objects: <path>"

### Detailed vs quick analysis

`vision_helper_analyze_image` runs in two modes:

| Need | Mode |
|---|---|
| Detailed, thorough understanding — transcribe all text, describe objects/people/layout, reason about complex content, or compare several images at once | default |
| A fast, cheap, concise answer — a yes/no, a short caption, an object/color check, "is this blurry?", or a high-volume/time-sensitive check (multiple images allowed, up to 5) | `quick: true` |

Prefer the default mode when completeness, precision, or detail matters more than
speed (it can take an **array** of up to 5 images to compare). Prefer `quick: true`
when latency and cost matter more than detail and a concise read is enough.

### `vision_helper_list_models`

List vision-capable models currently on OpenRouter (filtered to image-input models) so
you or the user can pick one. Arguments: `search` (substring on ID/name, e.g. `gemini`,
`qwen`, `claude`), `limit` (default 25), `offset`.

### `vision_helper_check_config`

Diagnose setup: shows whether an API key was found, **which source it came from**
(client env / Windows user vars / Windows system vars), the default model, and the
size/time limits. The key is always masked (e.g. `sk-or-…40a0`).

## Reliability notes

- The server starts even when no key is configured; key resolution is lazy, so a key
  set with `setx` works without restarting anything.
- Chat-completion requests retry up to 3 times on 429 / 5xx / network errors, honoring
  `Retry-After` when present (capped at 15 s). If a model's provider is still busy after retries,
  `vision_helper_analyze_image` automatically falls back (in the default detailed mode) to the
  `OPENROUTER_FALLBACK_MODEL` model (`google/gemini-3.7-flash` by default) before giving up.
- Image downloads are streamed with a hard byte cap and a 30 s timeout; MIME type is
  sniffed from magic bytes, so raw base64 payloads need no explicit type. Only the
  formats OpenRouter supports for vision input are accepted: PNG, JPEG, WebP, GIF
  (others are rejected with conversion guidance before anything is uploaded).
- Remote image URLs are validated before fetching: redirects are followed manually
  (max 3 hops) and every hop must be a public http(s) host — private, loopback,
  link-local, and unresolved hosts are refused.
- The model catalog used by `vision_helper_list_models` is cached in-process for
  10 minutes.
- Errors returned to the model are actionable: invalid key (401), insufficient credits
  (402), unknown model (404, with a hint to call `vision_helper_list_models`), rate limit
  (429), oversized images (with the exact limit), and unsupported formats.

## Troubleshooting

| Symptom | Fix |
|---|---|
| `vision_helper_analyze_image` returns "No OpenRouter API key found" | Run `vision_helper_check_config`. Set the key in the client's `environment`, or `setx OPENROUTER_API_KEY sk-or-v1-...` and start the client fresh. |
| "resolved from: Windows user environment variables" but the key is stale | Registry values are re-read on a short refresh cycle (about once a minute), so an updated `setx` is picked up without restarting the client or server. |
| "Error: Model not found on OpenRouter (HTTP 404)" | The model ID is invalid, renamed, or deprecated. Run `vision_helper_list_models` and pass a current ID via the `model` argument. |
| "Error: Insufficient OpenRouter credits (HTTP 402)" | Add credits at https://openrouter.ai/settings/credits. |
| "Image is N bytes, which exceeds MAX_IMAGE_SIZE" | Shrink/compress the image, or raise `MAX_IMAGE_SIZE` (cap 50 MB). |
| "The N images total X bytes, exceeding the aggregate limit" | Analyzes are capped at 25 MB total across all images per request — split into multiple calls. |
| "OpenRouter vision models only accept PNG, JPEG, WebP, or GIF" | Convert the image (e.g. to PNG/JPEG) and retry — these are the formats OpenRouter supports for vision input. |
| "Error: OpenRouter rate limit or quota exceeded (HTTP 429)" | Wait a moment and retry; the server already retries transient 429s automatically. |
| HTTP 400 on a valid image | Some models accept fewer formats — try `qwen/qwen3.8-max` or `openai/gpt-5` family, or convert the image to PNG/JPEG. |

## Security

- The API key is only sent to OpenRouter over HTTPS; it is never logged, and
  `vision_helper_check_config` reports only a masked prefix.
- Keys are read from environment variables / the registry — never from files in this
  repository.
- The analysis tool reads local files only when explicitly requested, validates remote
  URLs against private/internal hosts, and only ever uploads image content in the four
  formats OpenRouter accepts.

## License

MIT