# compy-mcp

**Let your AI agent search and read the notes you captured on the web with [Compy](https://chromewebstore.google.com/detail/compy).**

[Compy](https://github.com/alameddinc/compy) is a local-first Chrome extension for highlighting and note-taking on any web page. `compy-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes those notes to an MCP client (Claude Code, Claude Desktop, …) so your agent can pull the relevant highlights and tasks **on demand** — no copy-paste.

100% local. Read-only. No account, no network — it just reads a JSON file that Compy writes on your machine.

## How it works

```
Compy (browser)  ──"Sync for AI"──▶  ~/Downloads/compy/compy-export.json
                                              │  (watched)
                                       compy-mcp (stdio)
                                              │  tools + resources
                                        Claude Code / any MCP client
```

1. In Compy's dashboard, open the **Copy for AI** menu → **Sync for AI**. This writes `~/Downloads/compy/compy-export.json`. Re-run it whenever you want the agent to see your latest notes.
2. Register this server with your MCP client (below).
3. Ask your agent things like *"check Compy for anything I flagged on the billing page"* — it calls `search_notes` and gets your notes, quotes, tags and URLs.

## Install

Requires Node 18+.

### Claude Code

```bash
claude mcp add compy -- npx -y compy-mcp
```

### Claude Desktop / other clients

Add to your MCP config:

```json
{
  "mcpServers": {
    "compy": { "command": "npx", "args": ["-y", "compy-mcp"] }
  }
}
```

### Pin a project to one site (optional)

If you work across several sites, bind a project's server to one site with
`COMPY_SITE` so `search_notes` / `list_tasks` default to it (the agent doesn't
have to know which site your notes are on):

```bash
claude mcp add compy -e COMPY_SITE=https://app.example.com -- npx -y compy-mcp
```

Pass `site: "*"` in any call to search across all sites anyway. Without
`COMPY_SITE`, everything is unfiltered by default — the agent searches by
keywords and can call `list_sites` to discover what's available.

### Custom file location

By default it reads `~/Downloads/compy/compy-export.json`. Override with an env var or flag:

```bash
COMPY_FILE=/path/to/compy-export.json npx compy-mcp
# or
npx compy-mcp --file /path/to/compy-export.json
```

## Tools

| Tool | What it does |
|------|--------------|
| `search_notes` | Ranked keyword search over note text, quotes, titles and tags. Filter by `site` / `label`. |
| `list_tasks` | List notes/tasks, optionally filtered by `site` / `label`. |
| `list_sites` | Sites you have notes on, with counts. Good first call. |
| `get_note` | Fetch one note by `id`. |
| `get_markdown` | Render notes as a Markdown task list (optionally scoped to a site). |

Resource: `compy://sites` — overview of sites + counts.

## Why keyword search, not embeddings?

The note set is small (tens to a few hundred short notes) and the calling model *is* the semantic layer — it reasons over what `search_notes` returns. Fast substring/token ranking is plenty at this scale and keeps everything local, with zero setup and no API keys.

## License

MIT