# sitelens-mcp

Local companion MCP for the SiteLens Chrome extension.

**Flow (no manual export):**

1. Cursor starts this MCP over **stdio** (see config below).
2. MCP also listens on **`127.0.0.1:19527`** (bridge).
3. In Chrome, run SiteLens analysis → click **Send to MCP** on the floating panel.
4. The extension `POST`s the current `AnalysisReport` to the bridge.
5. Agent tools (`sitelens_get_latest_report`, …) read the in-memory cache.

Everything stays on your machine. No cloud upload.

## Install

```bash
git clone https://github.com/SiteLens-team/sitelens-mcp.git
cd sitelens-mcp
pnpm install
pnpm build
```

Requires Node.js ≥ 18.

## Cursor `mcp.json`

Point at the built entry (use your absolute path):

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

Optional port override:

```json
{
  "mcpServers": {
    "sitelens": {
      "command": "node",
      "args": [
        "/absolute/path/to/sitelens-mcp/dist/index.js"
      ],
      "env": {
        "SITELENS_MCP_PORT": "19527"
      }
    }
  }
}
```

## Pairing

| Step | Who | What |
|------|-----|------|
| 1 | Cursor | Starts `sitelens-mcp` → stdio + `http://127.0.0.1:19527` |
| 2 | You | Analyze a page with the SiteLens extension |
| 3 | You | Click **Send to MCP** on the panel toolbar |
| 4 | Extension | `POST /report` with `{ report, source: "sitelens-extension" }` |
| 5 | Agent | Calls `sitelens_get_latest_report` / `sitelens_export_checklist` |

Health probe:

```bash
curl -s http://127.0.0.1:19527/health
```

## Tools

| Tool | Purpose |
|------|---------|
| `sitelens_ping` | Bridge up?, port, cached report count |
| `sitelens_get_latest_report` | Full latest `AnalysisReport` (optional `url` filter) |
| `sitelens_list_reports` | Summaries only (last ~20) |
| `sitelens_export_checklist` | Severity-ordered fix checklist (no AI) |

## Environment

| Variable | Default | Meaning |
|----------|---------|---------|
| `SITELENS_MCP_PORT` | `19527` | Localhost bridge port |

The Chrome extension defaults to the same port. Optional override in extension storage key `mcpPort`.

## Privacy

- Bridge binds **only** `127.0.0.1`.
- Logs never include full report bodies (url + timestamp only).
- Reports live in MCP process memory (ring buffer of 20); they vanish when the MCP process exits.

## License

MIT