Metadata-Version: 2.4
Name: mcp-drift-watch
Version: 0.1.0
Summary: Pin approved MCP servers by fingerprint, alert when their tool descriptions change, and keep changed servers frozen until a person re-approves them.
Keywords: mcp,model-context-protocol,ai-security,tool-poisoning,rug-pull,ai-agents
Author: hsarikan
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Dist: anthropic>=1
Requires-Dist: anyio>=4.16
Requires-Dist: httpx2>=2.16
Requires-Dist: jsonschema>=4.18
Requires-Dist: mcp>=2.3.0
Requires-Dist: mcp-types>=2.3.0
Requires-Dist: pydantic>=2
Requires-Dist: python-dotenv>=1
Requires-Dist: pyyaml>=6
Requires-Dist: referencing>=0.37
Requires-Dist: rich>=13
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: typer>=0.12
Requires-Dist: psycopg[binary]>=3.2 ; extra == 'postgres'
Requires-Dist: fastapi>=0.115 ; extra == 'web'
Requires-Dist: jinja2>=3.1 ; extra == 'web'
Requires-Dist: markupsafe>=3.0 ; extra == 'web'
Requires-Dist: python-multipart>=0.0.18 ; extra == 'web'
Requires-Dist: starlette>=1.10 ; extra == 'web'
Requires-Dist: uvicorn>=0.30 ; extra == 'web'
Requires-Python: >=3.12
Provides-Extra: postgres
Provides-Extra: web
Description-Content-Type: text/markdown

# MCP Drift Watch

**Your AI agents trust what MCP servers say about their tools. Drift Watch makes sure it's still what you approved.**

An MCP server can change its tool descriptions at any time after you approve it: a "rug pull". The AI model reads those descriptions as instructions, so a changed description can tell it to read files or send data somewhere. Nothing in MCP tells you when this happens.

Drift Watch pins every approved server by a SHA-256 fingerprint of everything the model reads:
- the tool names and descriptions
- the parameters
- the server's instructions
- how the server is started or reached

When any of it changes, the server is **frozen** and you get an alert. It stays frozen until a person looks at the change and approves or rejects it.

## Install

```sh
uv tool install mcp-drift-watch          # or: pipx install mcp-drift-watch
driftwatch --version
```

The package is called `mcp-drift-watch`, and the command is `driftwatch`. A different, unrelated package on PyPI is called `driftwatch`, so `pip install driftwatch` and `uvx driftwatch` install that one, not this.

Optional parts:
- `mcp-drift-watch[web]` adds the review site and the HTTP gateway
- `mcp-drift-watch[postgres]` adds a hosted Postgres database, instead of a local SQLite file

## Quick start

List the servers you approved in `servers.yaml`. Write secrets as `${VAR}`: they're read from the environment and never stored.

```yaml
servers:
  - name: notes
    transport: stdio
    command: npx
    args: ["-y", "@example/notes-mcp@1.4.2"]   # pin the version
  - name: tickets
    transport: http
    url: https://tickets.example.com/mcp
    headers: {Authorization: "Bearer ${TICKETS_TOKEN}"}
```

```sh
driftwatch pin servers.yaml       # approve what's there now, pinned by fingerprint
driftwatch check servers.yaml     # later: compare with the approved version (exit 1 if anything changed)
driftwatch diff notes             # what changed, with red flags and OWASP MCP Top 10 IDs
driftwatch approve notes --fingerprint <id>   # the id diff shows; or: driftwatch reject notes
```

`check` approves nothing, so it fits a CI job or a cron.

## Before you start: what Drift Watch trusts

- **`servers.yaml` is like code.** `pin` and `check` start the programs it names, and each `${VAR}` hands that environment variable to them. Only use a `servers.yaml` you trust: never one from someone else's pull request.
- **A `.env` file in the current folder is read too** (keys and settings). Trust it like `servers.yaml`.
- **The first `pin` trusts what the server serves at that moment.** It warns about high red flags in that first version, and `driftwatch diff <server>` shows them.
- **The review site and the HTTP gateway have no sign-in.** They answer only on 127.0.0.1 and refuse web pages, but any program on your computer can use them.

## What else is included

- **AI second opinion:** `driftwatch review notes` labels a change, quotes the risky text and gives a reason. It uses Claude Haiku with your own `ANTHROPIC_API_KEY` (or `OPENROUTER_API_KEY`), for about $0.0005 per change, within a monthly budget you set. Without a key, it uses a local model through Ollama if one is running. It never approves anything: only a person does.
- **Alerts:** `driftwatch check servers.yaml --review --alert` sends each change once to Slack (an incoming webhook) and by email.
- **Scheduled watcher:** `driftwatch watch servers.yaml` checks only the servers that are due, by risk, from every 6 hours to every 7 days.
- **Review site:** `driftwatch serve` shows the approved list, the alerts, and for each change a side-by-side diff with hidden text highlighted, plus Approve and Reject buttons. It listens on 127.0.0.1 only.
- **Guard, for agents you write:** `driftwatch.guard` wraps the MCP Python SDK client, so the model only ever sees approved tools, even from the SDK's cache. Calls with unapproved arguments are refused before they leave.
- **Gateway, for apps you can't change** (like desktop AI apps and IDEs): `driftwatch gateway stdio <server>` or `driftwatch gateway http` stands between the app and its servers. It passes on only approved tools and calls. It starts a local server only if its launch command was approved.
- **Login setup check:** `driftwatch conform servers.yaml` checks remote servers' published OAuth metadata against the MCP authorization spec. It sends only GET requests for public documents.

`driftwatch export --lock approved.lock.json` writes the approved list that the guard and the gateway enforce.

## What it never does

- **Passive only.** It reads what a server publishes to every client. No login attempts, and no attack traffic.
- **No telemetry.** The CLI sends nothing to us. It contacts only your servers (and, with `conform`, the login servers they name), plus your AI provider, a local model, Slack and email when you turn those on.
- **The AI never approves.** It only gives a second opinion.

## Limits

- Drift Watch compares what a server *says* about its tools, never its source code. A change to what a tool *does*, with the same description, isn't seen. Neither are instructions inside a tool's results.
- It pins tools and server instructions, not prompts or resources.
- The gateway checks tool lists and tool calls. Through `gateway stdio`, requests that start from the server, such as asking the app's model to write something or asking the user for input, pass through unchecked.

## License

Apache-2.0
