# retrace-mcp

Read-only [MCP](https://modelcontextprotocol.io) server over the local
[Retrace](https://retrace.io) screen-history database, so Claude can search
what has been on your screen.

Six tools. No write path anywhere in the code — not a disabled one, none.

> **Read [SECURITY.md](SECURITY.md) before connecting this to anything.** It
> exposes the OCR'd text of everything you have had on screen, and the
> prompt-injection section describes a risk the deny-list does not cover.

```
search_text("quarterly planning")
  2026-02-11T09:00:00-08:00  Google Chrome   Quarterly planning - Docs
    ...Quarterly <mark>planning</mark> document. Revenue targets for the...
```

## Requirements

macOS with Retrace installed, [uv](https://docs.astral.sh/uv/), and the
`claude` CLI. Python ≥3.11 (uv provisions its own, so a system Anaconda will
not be picked up). Built and verified against **Retrace 0.8.7**.

## Install

```bash
git clone https://github.com/calvingunther66/retracemcpclaude.git
cd retracemcpclaude
bash install.sh
```

Installs **systemwide** (`claude mcp add --scope user`) — available in every
Claude session on the machine. The installer creates your config from the
example, verifies your database schema matches what the server expects, runs
the test suite, and only then registers the server.

Remove it at any time:

```bash
claude mcp remove retrace
```

## Tools

Every tool takes an optional `limit` (default 20, maximum 100). Timestamps
cross the boundary as **ISO 8601 local time** in both directions — pass
`2026-02-11` or `2026-02-11T09:30:00`, get back `2026-02-11T09:30:00-08:00`.
Raw epoch milliseconds never leak out. Every tool applies the deny-list inside
its SQL.

| Tool | Returns |
|---|---|
| `search_text(query, start?, end?, bundle_ids?, limit?)` | Full-text search over screen OCR. One hit per frame with a `<mark>`-highlighted snippet, app, window title, URL, and the video id / frame index. |
| `list_segments(start?, end?, bundle_id?, limit?)` | Capture segments — one contiguous stretch in one app window — with start, end and duration. |
| `get_frame(frame_id, limit?)` | One frame with its OCR text boxes and parent segment. |
| `app_usage(start, end, limit?)` | Time per app across a window, ordered descending, with display names. |
| `list_tags(limit?)` / `segments_by_tag(tag, limit?)` | Retrace's segment tags. |

`search_text` accepts FTS5 syntax: `invoice`, `"exact phrase"`,
`budget NEAR/5 forecast`, `sched*`.

**OCR box geometry is normalised 0.0–1.0, not pixels.** Multiply by the
video's width and height for pixel coordinates.

`processing_queue` is never queried — it is the hot live OCR queue.

## Configuration

`retrace_mcp.toml` in the repo root, created from `retrace_mcp.example.toml`
on install. Changes take effect on restart.

```toml
[database]
path = "~/Library/Application Support/Retrace/retrace.db"

[privacy]
exclude_bundles         = ["com.apple.Terminal", "com.1password.1password", ...]
exclude_url_patterns    = ["chase.com", "vanguard.com", ...]
exclude_window_patterns = ["1Password", "Online Banking", ...]
exclude_hidden_segments = true
skip_redacted           = true
```

| Key | Effect |
|---|---|
| `exclude_bundles` | App bundle IDs hidden from every tool. |
| `exclude_url_patterns` | Substrings matched against the segment's browser URL. |
| `exclude_window_patterns` | Substrings matched against the window title. |
| `exclude_hidden_segments` | Honour Retrace's own `hidden` tag. |
| `skip_redacted` | Drop rows whose snippet is `rtx1.` redaction ciphertext. |

**Why URL and window patterns exist.** Excluding applications is not enough on
its own. Banking, webmail and health portals run *inside a browser*, under an
allowed bundle ID — a bundle-only deny-list leaves every one of those pages
fully searchable. The URL and window lists are what actually close that gap,
and they are the ones worth maintaining.

Filters are applied inside each query, never as a post-filter. Post-filtering
leaks through `LIMIT`: an excluded row would consume a result slot, and its
text would have been read into the process regardless. `%` and `_` in patterns
are escaped and matched literally.

**Defaults ship excluding terminals**, which costs you the ability to ask
"what was that command I ran earlier". Terminals show secrets in the clear —
keys echoed by a command, tokens in an error message, anything pasted — and
all of it is OCR'd into plaintext. Delete the terminal block if you want that
capability back.

With no config file present, a built-in deny-list applies. `git clone && run`
can never produce zero filtering.

## Development

```bash
uv venv --python 3.12 && uv pip install -e . pytest
python -m pytest tests/test_tools.py -q
```

Tests build a **synthetic database** — you do not need Retrace, or a Mac, to
work on this. The fixture deliberately contains a terminal session with a fake
API key, a password-manager window, and a banking URL in a browser, so the
deny-list tests assert real behaviour rather than passing against data that
never had anything to hide.

`tests/test_live.py` is separate and runs against a real database while
Retrace is capturing: concurrency under write load, torn reads, WAL growth,
and write refusal. See [CONTRIBUTING.md](CONTRIBUTING.md).

Useful scripts:

| Script | Purpose |
|---|---|
| `tools/verify_schema.py` | Check your database against what the server expects. Run this before filing a bug. |
| `tools/make_fixture.py` | Regenerate the synthetic test database. |
| `tools/snapshot.sh` | Consistent read-only copy of a live database, via SQLite's backup API. |
| `tools/exercise_tools.py` | Drive all six tools over real MCP stdio. |

## How it reads the database safely

| Rule | Why |
|---|---|
| `file:<path>?mode=ro`, never `immutable=1` | The capture daemon writes continuously. `immutable` lets SQLite skip locking, producing torn reads that fail silently. |
| `PRAGMA query_only = ON` | Belt-and-braces alongside `mode=ro`. |
| `busy_timeout` 5000 ms, 2 retries | FTS5 index writes hold locks during capture. |
| Fresh connection per call | Nothing is held across calls. |
| `isolation_level=None` | A long-lived read transaction blocks the WAL checkpointer and the WAL grows unbounded. |
| No write statement in the package | Enforced by an AST-parsing test. |

Verified against a live database under active capture: 200 concurrent calls
across 8 threads with zero errors, WAL flat throughout, and `CREATE`,
`DELETE`, `UPDATE`, `INSERT` and journal-mode changes all refused.

## Notes on the schema

Observations from a Retrace 0.8.7 install that are not obvious from the
outside, and cost time to discover:

- **`PRAGMA user_version` reads 0.** Migration state lives in a
  `schema_migrations` table, not in `user_version`.
- **Timestamps are epoch milliseconds**, not seconds.
- **OCR box coordinates are normalised 0–1**, not pixels.
- **`searchRanking` is a content-ful FTS5 table** (`text`, `otherText`,
  `title`). Were it contentless, `snippet()` would raise.
- **Roughly half of frames are not in the search index** — they have no
  `doc_segment` row and are invisible to `search_text` by design.
- **The schema is much larger than the six tools use.** `audio`,
  `transcript_word`, `event`, `summary`, `segment_comment` and
  `in_page_url_text` all exist. No tool here reads them. Some contain material
  more sensitive than screen OCR — audio transcripts and calendar
  participants — so think carefully before adding one that does.
- Video segments live at `chunks/YYYYMM/DD/<13-digit-epoch-ms>`, extensionless
  but real MP4.

Other Retrace versions may differ. `tools/verify_schema.py` will tell you.

## License

MIT — see [LICENSE](LICENSE).

Not affiliated with Retrace.