Metadata-Version: 2.4
Name: page-vision-mcp
Version: 0.1.0
Summary: Structured visual analysis pipeline for coding agents - give your AI agent the ability to see
Author: 666666999999666
License-Expression: MIT
Project-URL: Homepage, https://github.com/666666999999666/page-vision-mcp
Project-URL: Repository, https://github.com/666666999999666/page-vision-mcp
Project-URL: Issues, https://github.com/666666999999666/page-vision-mcp/issues
Keywords: mcp,vision,ui-analysis,ocr,screenshot,coding-agent,vlm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: Pillow>=10.0
Requires-Dist: httpx>=0.25
Requires-Dist: python-dotenv>=1.0
Requires-Dist: openai>=1.0
Provides-Extra: playwright
Requires-Dist: playwright>=1.40; extra == "playwright"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Page Vision MCP

> Structured visual analysis pipeline for coding agents — give your AI agent the ability to **see**.

[![PyPI](https://img.shields.io/pypi/v/page-vision-mcp.svg)](https://pypi.org/project/page-vision-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/page-vision-mcp.svg)](https://pypi.org/project/page-vision-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## What It Does

Page Vision MCP turns visual analysis from a prompt into a **tool**. Instead of asking an LLM to "look at this image," your coding agent calls a structured API that returns consistent, machine-readable results with coordinates.

**5 Tools:**

| Tool | What It Does | VLM | Playwright |
|------|-------------|:---:|:----------:|
| `capture_page` | Screenshot a webpage (fallback) | - | Yes |
| `analyze_ui` | Structured UI analysis with region-level localization | Yes | - |
| `compare_ui` | Screenshot diff with mode constraints | Yes | - |
| `extract_text` | Block-level OCR with coordinates | Yes | - |
| `crop_analyze` | Progressive crop refinement with depth guards | Yes | - |

**3 Resources:** `vision://health` | `vision://version` | `vision://models`

## Pipeline

```
Screenshot ──> analyze_ui ──> Structured JSON
                  │
                  ├── Need detail? ──> crop_analyze (depth +1)
                  ├── Need text?   ──> extract_text
                  └── Need diff?   ──> compare_ui
```

## Quick Start

### Install

```bash
pip install page-vision-mcp

# Optional: Playwright for screenshot fallback
pip install "page-vision-mcp[playwright]"
playwright install chromium
```

### Configure

Set environment variables (or create a `.env` file, see `.env.example`):

```bash
VISION_API_KEY=your-api-key
VISION_BASE_URL=https://api.openai.com/v1
VISION_MODEL_ID=gpt-4o
```

Works with any OpenAI-compatible VLM: GPT-4o, GLM-4V, Qwen-VL, etc.

### MCP Client Config

Add to your MCP client configuration (Claude Code, Trae, Cursor, etc.):

```json
{
  "mcpServers": {
    "page-vision-mcp": {
      "command": "page-vision-mcp",
      "env": {
        "VISION_API_KEY": "your-api-key",
        "VISION_BASE_URL": "https://api.openai.com/v1",
        "VISION_MODEL_ID": "gpt-4o"
      }
    }
  }
}
```

See `examples/mcp_config.json` for the full configuration with all options.

## Tool Details

### `analyze_ui` — UI Analysis

```python
analyze_ui(
    image_source="screenshot.png",  # URL/path/base64/data_url
    prompt="",                       # optional focus
    task="ui",                       # ui/screenshot/qa/general
    detail="high"                    # low/auto/high
)
```

Returns structured observations with region-level localization (page → section → component → text), inferences, uncertainties, and suggested regions for further analysis.

### `compare_ui` — Screenshot Diff

```python
compare_ui(
    image_before="before.png",
    image_after="after.png",
    mode="viewport",     # viewport/fullpage/component
    focus="changes"      # changes/layout/text/colors/general
)
```

Returns structured differences (added/removed/modified/moved) with coordinates.

### `extract_text` — OCR

```python
extract_text(
    image_source="screenshot.png",
    language="auto",        # auto/chinese/english/japanese/korean
    preserve_layout=True
)
```

Returns text blocks with type, confidence, and bounding box coordinates.

### `crop_analyze` — Progressive Refinement

```python
crop_analyze(
    image_source="screenshot.png",
    x=0.15, y=0.02, width=0.6, height=0.07,  # normalized 0.0-1.0
    depth=1,       # agent-managed, max 3
    task="ui"
)
```

Use coordinates from `analyze_ui`'s `suggested_regions`. Max depth 3 prevents infinite recursion.

### `capture_page` — Screenshot Fallback

```python
capture_page(
    url="http://localhost:3000",
    viewport_width=1280,
    viewport_height=720,
    full_page=False,
    wait_for="networkidle"  # networkidle/domcontentload/load/none
)
```

**Note:** If your agent has built-in browser capability (Computer Use, Trae browser, Playwright MCP), use that instead and pass the screenshot path to `analyze_ui`.

## Response Format

All tools return a structured JSON envelope:

```json
{
  "status": "success",
  "tool": "analyze_ui",
  "result": { ... },
  "warnings": []
}
```

Status can be: `success` | `partial` | `error` | `unavailable` | `unsupported` | `completed`

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `VISION_API_KEY` | - | VLM API key (required) |
| `VISION_BASE_URL` | `https://api.openai.com/v1` | VLM API endpoint |
| `VISION_MODEL_ID` | `gpt-4o` | Model to use |
| `VISION_TIMEOUT` | `60` | Request timeout (seconds) |
| `VISION_MAX_RETRIES` | `3` | Max retry attempts |
| `VISION_ALLOW_LOCAL_FILES` | `true` | Allow local file paths |
| `VISION_ALLOWED_PATHS` | - | Allowed directories (comma-separated) |
| `VISION_BLOCK_PRIVATE_IPS` | `true` | Block SSRF to private IPs |
| `VISION_MAX_IMAGE_SIZE_MB` | `10` | Max image size |
| `VISION_MAX_IMAGE_PIXELS` | `40000000` | Max pixel count |

## Development

```bash
pip install -e ".[dev]"
pytest tests/
```

## License

[MIT](LICENSE)
