# vision-opencode-mcp

Give opencode (or any MCP client) visual reference by calling an
OpenAI-compatible vision model API. Exposes one tool:

- **`vision_describe(image_path?, question?)`** — read a local image and return
  what the vision model sees. When `image_path` is omitted, it automatically
  picks the **newest image** (by `LastWriteTime`) from the pasted-images dir,
  which is where opencode stores clipboard-pasted images.

Requires only `python>=3.10` and the `mcp` SDK (installed automatically).

## Requirements

- Python 3.10+
- A `VISION_API_KEY` for an OpenAI-compatible vision endpoint
  (base URL and model are baked in as defaults; override if needed)

## Install

```bash
# from this repo
python -m venv .venv
# Windows:
.venv\Scripts\pip install -e .
# macOS/Linux:
# .venv/bin/pip install -e .

# or with uv (faster)
uv sync
```

This installs the `vision-mcp` console script and all dependencies
(`mcp`, which pulls in `mcp-types`).

## Configure for opencode

Add an `mcp` entry to your opencode config
(`opencode.json` or `~/.config/opencode/opencode.json`):

```jsonc
{
  "mcp": {
    "vision": {
      "type": "local",
      "command": [
        "C:\\path\\to\\vision-opencode-mcp\\.venv\\Scripts\\python.exe",
        "C:\\path\\to\\vision-opencode-mcp\\server.py"
      ],
      "enabled": true,
      "environment": {
        "VISION_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

If you installed with `uv sync`, you can also point at the `vision-mcp`
console script instead of the venv python:

```jsonc
{
  "mcp": {
    "vision": {
      "type": "local",
      "command": ["C:\\path\\to\\vision-opencode-mcp\\.venv\\Scripts\\vision-mcp.exe"],
      "enabled": true,
      "environment": {
        "VISION_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Restart opencode. The `vision_describe` tool then appears under the `vision`
MCP server.

## Environment variables

| Variable | Default | Required | Description |
|---|---|---|---|
| `VISION_API_KEY` | *(none)* | **yes** | API key for the vision endpoint. Never hardcoded. |
| `VISION_API_BASE` | `http://opencode.ai/zen/v1` | no | Base URL of the OpenAI-compatible API. |
| `VISION_MODEL` | `mimo-v2.5-free` | no | Vision model name. |
| `VISION_USER_AGENT` | Chrome UA | no | Sent as `User-Agent`; some endpoints (Cloudflare-protected) return 403 without a browser UA. |
| `VISION_TIMEOUT` | `180000` | no | HTTP timeout in ms. |
| `VISION_MAX_TOKENS` | `8192` | no | `max_tokens` for the completion (thinking models need headroom). |
| `VISION_PASTED_DIR` | `%TEMP%\opencode\pasted_images` | no | Directory scanned for the newest image when `image_path` is empty. |

## Usage

With `image_path`:

```
call vision_describe  image_path="D:\pics\shot.png"  question="这个截图里报了什么错？"
```

Without `image_path` (auto-picks the newest pasted image):

```
call vision_describe  question="这张图片里有什么？"
```

## CLI (debug)

The repo also ships `vision.py`, a small command-line version of the same call:

```bash
python vision.py <image_path> [question]
```

Prints the model text to stdout; exits `0` on success, `1` on error
(prints `ERROR: ...`). It reads the same environment variables as the server.

## Notes

- The API key is read from the environment only — it never appears in the
  code, so this repo is safe to share.
- For clipboard-pasted images in opencode desktop, the tool auto-picks the
  newest file under the pasted-images dir, so you can just say "看这张图"
  and the tool picks it up.