# @privacytracker/mcp

Model Context Protocol server for [PrivacyTracker](https://github.com/privacykey/privacytracker). Exposes the local privacy library — apps, privacy labels, change history, AI policy summaries — to any MCP-compatible client (Claude Desktop, Claude Code, Cline, etc.).

This is a **read-only proxy**. It talks to a running PrivacyTracker instance over its existing HTTP API; it does not touch the SQLite database directly and never mutates state.

## Prerequisites

- A running PrivacyTracker instance (local `pnpm dev`, Docker, or remote install).
- Node.js 20 or newer on the machine running the MCP client.

## Install

You don't need to clone this repo to use the server — every MCP client can spawn it via `npx`:

```bash
npx -y @privacytracker/mcp
```

For local development from a clone:

```bash
pnpm install
pnpm build
node dist/index.js
```

## Configuration

The server reads three environment variables:

| Variable | Required | Default | Notes |
|---|---|---|---|
| `PRIVACYTRACKER_BASE_URL` | no | `http://localhost:3000` | Origin of the running PrivacyTracker instance. No trailing slash. |
| `PRIVACYTRACKER_ADMIN_TOKEN` | conditional | — | Required when the upstream server has `AUDITOR_ADMIN_TOKEN` set, OR when the MCP server is reaching it across a non-local hostname. Sent as `x-auditor-admin-token` on every request. |
| `PRIVACYTRACKER_TIMEOUT_MS` | no | `30000` | Per-request timeout. |

A 401 response from the server triggers a clear MCP error explaining which side of the token contract is wrong.

## Claude Desktop config

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "privacytracker": {
      "command": "npx",
      "args": ["-y", "@privacytracker/mcp"],
      "env": {
        "PRIVACYTRACKER_BASE_URL": "http://localhost:3000",
        "PRIVACYTRACKER_ADMIN_TOKEN": "..."
      }
    }
  }
}
```

Restart Claude Desktop and the `privacytracker` server will appear in the tools menu.

## Available tools

All tools are read-only and map 1:1 to existing PrivacyTracker API endpoints.

| Tool | Description |
|---|---|
| `list_apps` | Every tracked app with identity + change counts. Optional `grouped` view. |
| `get_app` | Full privacy dossier for one app (privacy types, categories, last snapshot, policy summary). |
| `search_apps` | iTunes Store search by name and/or bundle id. Returns App Store URLs. |
| `get_changelog` | Universal cross-app change feed with filtering (app, time, type, category) and pagination. |
| `get_app_changelog` | Full changelog for one app in chronological order. |
| `get_history_stats` | Per-quarter category trend and change-event sparkline for one app (Q1 2021 forward). |
| `get_policy_status` | Privacy-policy AI run status for one app (idle/running/done/error + log). |
| `get_policy_version_diff` | Line+word diff between a policy version and its predecessor. |
| `compare_apps` | Side-by-side privacy comparison of two apps (tracked or untracked URL). |
| `get_notifications` | 30 most recent privacy-change notifications + unread count. |
| `get_sync_status` | Background sync scheduler state (running, last/next run, interval). |

## Available resources

| URI | Description |
|---|---|
| `apps://list` | Flat JSON list of every tracked app. |
| `app://{appId}` | Full privacy dossier for one app. Replace `{appId}` with the numeric Apple track ID. |

## Local development

```bash
pnpm install
pnpm dev          # tsx watch mode
pnpm typecheck
pnpm test
pnpm lint
pnpm build
```

To smoke-test against a running PrivacyTracker instance:

```bash
PRIVACYTRACKER_BASE_URL=http://localhost:3000 pnpm start
```

The server speaks JSON-RPC over stdio. Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for interactive exploration:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## Versioning

This package versions independently of PrivacyTracker itself. Tag a release (`v0.x.y`) on `main` and the publish workflow ships it to npm automatically.

## License

Apache-2.0. See [LICENSE](./LICENSE).