# Vision QA MCP

An [MCP](https://modelcontextprotocol.io) server that gives an AI agent **automated quality control for generated images**. After a model produces an image, the agent calls `qa_check` and gets back a structured verdict — character accuracy, style consistency, quality, and composition, scored against your reference images and rules — powered by **Claude vision**.

Built for AI media pipelines where a human can't eyeball every frame: generate → QA → regenerate-if-failed, automatically.

## Why

Image models drift. A character loses a feature, the style wobbles, a hand comes out wrong. In a production pipeline that ships dozens of images, you need the *agent itself* to catch this before a human ever sees it. This server makes "QA every image" a single tool call with a pass/fail and actionable issues — and it pairs naturally with [claude-vision-mcp](https://github.com/wonderstone843/claude-vision-mcp) (let the agent see) for a full see-and-verify loop.

## Tools

- **`qa_check`** — review one image and return a structured verdict:
  - `passed` (bool), `overall_score`, and per-axis scores (`character_accuracy`, `style_consistency`, `quality_score`, `composition_score`) on a 0–1 scale
  - `issues` — a list of `{severity, category, description, recommendation}` (severity: critical / warning / minor)
  - `should_regenerate` (bool) and a one-line `notes` summary
  - Fails automatically on any **critical** issue, regardless of score.
- **`list_scene_types`** — the supported `scene_type` values and what each expects.

You pass your own rules and references, so it works for any project:

```
qa_check(
  image_path="/path/to/generated.png",
  reference_images=["/refs/hero_front.png", "/refs/hero_face.png"],
  character_rules="The pilot has NO eyebrows in this form. Jacket has horizontal stripes, not clouds.",
  style_notes="High-contrast anime cel shading, cosmic purple lighting.",
  scene_type="solo",          # solo | portrait | battle | combat | group | action | interview
  pass_threshold=0.7,
)
```

`scene_type` adjusts composition expectations — e.g. a `portrait` may face the camera, while `battle` characters should face each other.

## Requirements

- Python ≥ 3.10
- An Anthropic API key (`ANTHROPIC_API_KEY`)
- Dependencies: `mcp[cli]`, `anthropic`, `Pillow`

## Install

```bash
git clone https://github.com/wonderstone843/vision-qa-mcp.git
cd vision-qa-mcp
pip install -e .
export ANTHROPIC_API_KEY=sk-ant-...
```

## Use with Claude Code

```bash
claude mcp add vision-qa -- vision-qa-mcp
```

Or add to your MCP config:

```json
{
  "mcpServers": {
    "vision-qa": { "command": "vision-qa-mcp" }
  }
}
```

Then instruct your agent: *"After generating each image, run qa_check against the character refs; regenerate any that don't pass."*

## Configuration

- `ANTHROPIC_API_KEY` (required)
- `ANTHROPIC_MODEL` (optional, default `claude-opus-4-8`) — for QA on every generation, `claude-haiku-4-5` or `claude-sonnet-4-6` are cheaper and usually sufficient.

## How it works

The image is downscaled to stay under the vision API limits, sent to Claude alongside any reference images and your rules, and the model is **forced to call a `submit_qa` tool** whose schema defines the four scores plus the issues list — so the output is always structured and parseable. The pass decision is `overall_score >= pass_threshold AND no critical issues`.

```
vision_qa_mcp/
  server.py   FastMCP server: qa_check + list_scene_types
  review.py   prompt, scoring rubric, forced-tool call to Claude vision
  images.py   downscale + base64-encode for the vision API
```

## License

MIT — see [LICENSE](LICENSE). Author: Joshua Penn.