# Vision MCP Server

A small, production-shaped **Model Context Protocol (MCP) server** that gives any MCP client (Claude Desktop / Code, etc.) **multimodal vision** tools — describe, OCR, visual Q&A, object detection — backed by any vision model via **OpenRouter**.

> Built to be **governed by default**: every tool instructs the model to *abstain* ("cannot determine from image") rather than guess — the same source-over-derived discipline I apply across my AI automation work.

- **Pluggable backend** — swap providers/models without touching tool logic. Ships with a real `OpenRouter` backend (**standard-library only**, no HTTP dependency) and a deterministic `Mock` backend for offline demos and tests.
- **Runs offline for inspection** — the tool logic is verifiable with **zero dependencies and no API key**.

## Tools

| Tool | What it does |
|---|---|
| `describe_image` | Concise or full description of an image |
| `extract_text` | OCR-style verbatim text extraction |
| `ask_image` | Visual question answering (abstains when unsupported) |
| `detect_items` | Lists distinct objects/items (optionally scoped to categories) |

Images are accepted as a local **path**, an **http(s) URL**, or a **`data:` URI**.

## Quickstart

**Offline — zero dependencies, no key:**
```bash
python3 examples/offline_demo.py
python3 -m unittest discover -s tests -q
```

**As a real MCP server:**
```bash
pip install -r requirements.txt        # installs the `mcp` SDK
export OPENROUTER_API_KEY=sk-...
python -m vision_mcp.server             # stdio MCP server
```
Then register it in your MCP client. Env: `VISION_MCP_MOCK=1` runs without a key; `VISION_MCP_MODEL` picks the model.

## Architecture

```mermaid
flowchart LR
  C["MCP client<br/>(Claude, etc.)"] -->|stdio / MCP| S["Vision MCP Server<br/>(FastMCP)"]
  S --> T["Tools<br/>describe · extract · ask · detect"]
  T --> BE["VisionBackend<br/>(pluggable)"]
  BE --> M["Mock<br/>(offline)"]
  BE --> O["OpenRouter<br/>(any vision model)"]
  classDef gov fill:#e9ecff,stroke:#5560aa,color:#222;
  class T gov;
```

See [`docs/design.md`](docs/design.md) for the design rationale.

## About

**Gerardo Dellán** — AI Transformation & Automation Program Manager. I lead AI programs *and* build them hands-on.
[linkedin.com/in/gerry-df](https://www.linkedin.com/in/gerry-df) · more patterns: [agentic-automation-patterns](https://github.com/gerardodellan/agentic-automation-patterns)

## License

MIT — see [LICENSE](LICENSE).