# shottr-mcp

An Effect-native MCP server that lets local agents silently capture macOS windows, displays, and exact regions, then produce Shottr-style PNGs with programmable annotations, backgrounds, padding, rounded corners, and shadows.

This is an AI-assisted project, developed collaboratively with coding agents and reviewed through automated type, integration, and image-processing tests.

## Requirements

- macOS
- Node.js 22 or newer
- Shottr 1.8 or newer installed at `/Applications/Shottr.app`
- pnpm 11

Shottr needs **Screen Recording** permission. The app that launches this MCP server also needs:

- **Screen Recording** to enumerate windows and capture exact regions.

Grant these in **System Settings → Privacy & Security**, then restart the MCP host.

## Install

```sh
pnpm install
pnpm build
```

Use the absolute path to `dist/main.js` in an MCP client. For Codex:

```toml
[mcp_servers.shottr]
command = "node"
args = ["/absolute/path/to/shottr-mcp/dist/main.js"]
```

For clients using JSON configuration:

```json
{
  "mcpServers": {
    "shottr": {
      "command": "node",
      "args": ["/absolute/path/to/shottr-mcp/dist/main.js"]
    }
  }
}
```

Run `shottr_doctor` after connecting. It reports the installed Shottr version and any permission action still needed.

## Tools

- `shottr_doctor` — check platform, Shottr, and window-metadata access.
- `shottr_list_displays` — return connected displays, IDs, types, main status, and logical bounds.
- `shottr_list_windows` — return visible windows in front-to-back order, optionally filtered by app name or bundle ID.
- `shottr_capture` — preferred smart capture tool; defaults safely to the active window.
- `shottr_capture_window` — silently capture one uniquely selected window without opening capture UI.
- `shottr_capture_fullscreen` — silently capture the main display without opening capture UI.
- `shottr_capture_region` — capture an exact macOS logical-coordinate rectangle.
- `shottr_annotate_image` — add pen, spotlight, measurement, and text annotations to an existing PNG.
- `shottr_beautify_image` — beautify an existing local image.

Capture tools always return inline PNG image content and metadata. They write a file only when given an absolute `.png` `outputPath` whose parent directory already exists.

### Automatic targeting

Use `shottr_capture` for normal agent requests. It resolves ordinary language without asking the user to repeat information:

- No target or a vague “take a screenshot” request captures only the active window.
- A named app/window captures that visible window without focusing it.
- “Current screen/display/monitor” selects the display containing the active window. If no active window can be identified, it uses the display containing the pointer, then the main display.
- “External monitor” selects the only connected non-built-in display.
- “Built-in Retina display” selects the built-in display.
- An explicit display ID selects the matching result from `shottr_list_displays`.
- Explicit coordinates select that exact region.

The server asks for clarification only when the target is genuinely ambiguous, such as when multiple external displays are connected. It returns the matching display candidates so the user can choose once. It never expands an unspecified screenshot into a full-display capture.

### Window selection

Use a returned window ID for the strongest targeting:

```json
{
  "selector": { "windowId": 1234 }
}
```

Or select by an exact app name/bundle ID and optional case-insensitive title substring:

```json
{
  "selector": {
    "app": "com.apple.Safari",
    "title": "Effect"
  }
}
```

If more than one window matches, the server returns candidates instead of guessing.

Window capture never activates an app or switches tabs. It captures only the pixels currently rendered in the selected visible window. A background browser tab cannot be captured pixel-accurately without making it visible, so agents must not focus it automatically; they should explain the limitation and wait until the user makes that tab visible.

### Beautification

Before adding `beautify`, agents must ask the user to choose the background, padding, corner radius, and shadow settings. The server requires every choice explicitly and rejects partial styling instead of inventing visual values.

```json
{
  "selector": { "app": "Safari" },
  "beautify": {
    "background": {
      "type": "image",
      "path": "/absolute/path/to/background.jpg"
    },
    "padding": 80,
    "cornerRadius": 20,
    "shadow": {
      "color": "#000000",
      "opacity": 0.2,
      "blur": 30,
      "offsetX": 0,
      "offsetY": 14
    }
  },
  "outputPath": "/absolute/existing/folder/safari.png"
}
```

Background images are center-cropped to cover. Solid and linear-gradient backgrounds are also supported:

```json
{
  "background": {
    "type": "linearGradient",
    "from": "#7C3AED",
    "to": "#2563EB",
    "angle": 135
  },
  "padding": { "top": 48, "right": 64, "bottom": 48, "left": 64 },
  "cornerRadius": 20,
  "shadow": {
    "color": "#000000",
    "opacity": 0.2,
    "blur": 30,
    "offsetX": 0,
    "offsetY": 14
  }
}
```

### Annotations

Capture tools accept an `annotations` array, and `shottr_annotate_image` applies the same annotations to an existing local image. Coordinates are normalized from `0` to `1` relative to the screenshot: `(0, 0)` is the top-left, `(1, 1)` is the bottom-right, and `(0.5, 0.5)` is the centre.

Draw a red pen stroke and place “Hello” in the centre:

```json
{
  "annotations": [
    {
      "type": "pen",
      "points": [
        { "x": 0.1, "y": 0.2 },
        { "x": 0.3, "y": 0.1 },
        { "x": 0.5, "y": 0.2 }
      ],
      "color": "#FF0000",
      "width": 6
    },
    {
      "type": "text",
      "text": "Hello",
      "position": { "x": 0.5, "y": 0.5 },
      "color": "#FF0000",
      "fontSize": 32,
      "backgroundColor": "#FFFFFF"
    }
  ]
}
```

Spotlight the centre of the image:

```json
{
  "type": "spotlight",
  "region": { "x": 0.3, "y": 0.25, "width": 0.4, "height": 0.5 },
  "shape": "ellipse",
  "dimOpacity": 0.7,
  "color": "#FFD60A",
  "width": 4
}
```

Measure the full width and height of a captured window:

```json
{
  "annotations": [
    {
      "type": "measurement",
      "from": { "x": 0, "y": 0.05 },
      "to": { "x": 1, "y": 0.05 },
      "color": "#FF3B30",
      "width": 3,
      "fontSize": 24
    },
    {
      "type": "measurement",
      "from": { "x": 0.05, "y": 0 },
      "to": { "x": 0.05, "y": 1 },
      "color": "#FF3B30",
      "width": 3,
      "fontSize": 24
    }
  ]
}
```

Measurement labels default to the calculated image-pixel distance, such as `1440 px`. The same values are returned in structured MCP metadata so agents can report dimensions without reading the pixels back from the image. Set `label` to override the visible text while preserving the calculated numeric result.

## Behavior and privacy

Shottr exposes capture actions through URL schemes, but those actions can show capture UI and do not support headless coordinate targeting. Therefore captures use macOS `screencapture` for a silent agent workflow, and Shottr-style annotations and beautification are rendered locally with Sharp.

Every successful capture leaves the final PNG on the macOS clipboard, including beautified and exact-window fallback results, so it can be pasted immediately. Existing clipboard content is replaced, matching normal screenshot-tool behavior.

Images remain local. The server has no HTTP transport, upload tool, telemetry, or remote-background download support.

## Development

```sh
pnpm check
pnpm test
pnpm build
```

Real Shottr capture is intentionally not part of the default test suite because it needs macOS permissions and captures visible user content. Run it explicitly when the current display is safe to capture:

```sh
pnpm test:e2e
```