Metadata-Version: 2.4
Name: peek-mcp
Version: 0.3.0
Summary: Let AI agents see your UI — point at elements, annotate, and get instant visual context for AI-powered code editing.
Project-URL: Homepage, https://github.com/zly1203/peek
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.100.0
Requires-Dist: mcp<2.0.0,>=1.20.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: uvicorn[standard]>=0.20.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Peek

Point at your UI. Your AI agent sees it.

## Why

AI coding agents can edit code, but they can't see your page. You end up describing layouts in words, copy-pasting HTML, or dragging screenshots into chat.

Peek fixes this. Your AI agent can screenshot any local page on its own. You can also point at specific elements with a bookmarklet, and the agent gets the screenshot plus element data (selectors, styles, bounding boxes).

## Quick Start

### Claude Code (CLI or VS Code) — recommended

```bash
pip install peek-mcp
peek setup
```

`peek setup` does everything for you: installs Playwright Chromium, registers Peek as an MCP server in Claude Code (user scope, all projects), opens the bookmarklet page in your browser. Just drag the blue button to your bookmark bar.

### Other AI tools (Cursor / Windsurf / Claude Desktop)

```bash
pip install peek-mcp
playwright install chromium   # ~150 MB, one-time
```

Add to your MCP config file (e.g. `.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, or `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "peek": {
      "command": "/absolute/path/to/peek",
      "args": ["mcp"]
    }
  }
}
```

Run `which peek` in your terminal to get the absolute path. Then visit http://localhost:8899 to grab the bookmarklet.

### Recommended: tell your agent your dev port

Add this to your project's `CLAUDE.md` (or `.cursorrules`, etc.):

```
Dev server runs on http://localhost:3000

When using Peek's screenshot tool and you don't know the dev server URL, ask me which port the app is running on before taking a screenshot.
```

Replace `3000` with your actual port. **This prevents your agent from guessing the wrong port.**

### Use it

**Agent-driven screenshots (no bookmarklet needed):**

Just ask your agent — "screenshot the page", "take a look at localhost:3000", "check if the button looks right". The agent calls `screenshot(url)` directly.

**User-pointed captures (bookmarklet):**

1. Run `peek mcp` (or let your AI tool start it via MCP)
2. Open http://localhost:8899, drag the blue button to your bookmark bar
3. Open your app, click the bookmarklet, pick a mode:

| Mode | Shortcut | You do | Agent gets |
|------|----------|--------|------------|
| **Region** | `Alt+R` | Drag a rectangle | Screenshot + elements in that area |
| **Element** | `Alt+S` | Click an element | Screenshot + selector, styles, HTML |
| **Annotate** | `Alt+A` | Draw (pen, box, arrow) | Screenshot + your drawings + elements |

4. Tell your agent: "check what I just selected" — it calls `get_latest_capture()`

## Supported URLs

Peek works with local and LAN addresses:

| URL | Supported |
|-----|-----------|
| `http://localhost:3000` | Yes |
| `http://127.0.0.1:8080` | Yes |
| `http://0.0.0.0:5000` | Yes |
| `http://192.168.1.5:3000` | Yes (LAN) |
| `http://myapp.local:3000` | Yes (.local domain) |
| `http://myapp.test:8080` | Yes (.test domain) |
| `https://google.com` | No (public URLs blocked) |

## MCP Tools

| Tool | What it does |
|------|-------------|
| `screenshot(url)` | Takes a screenshot of a local/LAN URL |
| `get_latest_capture()` | Returns your latest bookmarklet selection — screenshot + element data + DOM context |

For `Element` mode captures, the agent gets structural context to find the right code:

- **ancestor chain** (`body > main > section.settings > div.flex`)
- **sibling position** (`2 of 3 <button> siblings`)
- **nearest heading** (`h2: Settings`)
- **parent layout** (`flex, row`)

This means when you point at a button, the agent knows *which* button on which section — no guessing.

## How It Works

```
Your AI agent calls screenshot(url)
    -> Playwright takes a headless screenshot
    -> Agent sees the page and can reason about the UI

You point at something with the bookmarklet
    -> Peek grabs element data + takes a Playwright screenshot
    -> Agent calls get_latest_capture() and sees everything
    -> "The chart legend overlaps the bars. Fixing the CSS..."
```

One process, two jobs: MCP server talks to your AI agent over stdio, bridge server receives bookmarklet data on port 8899. `peek mcp` runs both.

## Troubleshooting

**`Playwright Chromium is not installed`**

Run `playwright install chromium`. This downloads the headless browser engine (~150 MB). Only needed once.

**`ERR_CONNECTION_REFUSED` when taking a screenshot**

Your dev server isn't running on that port. Start your dev server first, then ask the agent to screenshot. If you see this repeatedly, make sure the port in your `CLAUDE.md` matches your actual dev server.

**Agent screenshots the wrong port**

Add the `CLAUDE.md` snippet from step 3 above. Without it, the agent will guess.

**Bookmarklet not working**

Delete it from your bookmark bar and re-drag from http://localhost:8899. Make sure `peek mcp` is running.

**`peek: command not found` after pip install**

Your Python scripts directory may not be in your PATH. Try:
```bash
python -m peek mcp
# or find the path:
pip show peek-mcp | grep Location
```

## Limitations

- **Local/LAN only.** Public URLs are blocked for security (SSRF prevention).
- **No auth.** Playwright uses a fresh browser context — no cookies, no login state.
- **Captures may contain sensitive data.** Passwords and hidden inputs are redacted, but visible text and screenshots are saved as-is to `~/.peek/captures/` (outside your project).

## CLI

```bash
peek mcp                  # start everything (recommended)
peek mcp --port 9000      # different bridge port
```

## Requirements

- Python 3.10+
- Playwright Chromium (`playwright install chromium`)
