# Reversee

> Reversee is a free, open-source (MIT) reverse-proxy web debugger for macOS, Windows, and Linux. It sits between a client and a destination server so you can see, intercept, and edit HTTP/HTTPS traffic. It ships an MCP server so AI agents (Claude Code, Cursor, or any MCP client) can inspect and control the proxy, and a headless mode for automation.

## What it does

- Acts as a reverse proxy: point a client at Reversee's listen address and it forwards to a destination, recording every request and response.
- Inspect traffic: method, path, status, content type, headers, request/response bodies (gzip/brotli decoded, syntax-highlighted), per-request timings, and a copy-as-curl command.
- Interceptors: rewrite requests (`requestParams`: host, path, method, port, headers, body) or responses (`responseParams`: statusCode, headers, body) with JavaScript, live.
- Breakpoints: hold requests matching a URL regex + HTTP methods, edit the URL/headers/body, then resume.
- gRPC: enable an HTTP/2 listener (h2 via ALPN on https, cleartext h2c on http) to proxy native gRPC; import `.proto` or compiled `.desc` protobuf definitions and Reversee decodes every message — unary and server/client/bidi streaming — into JSON, matched by method (`/package.Service/Method`), and captures the grpc-status trailer.
- Redirect and Host-header rewriting; a locally generated root CA for trusting HTTPS interception.
- Source: https://github.com/galusben/reversee — License: MIT.

## For AI agents (MCP)

Reversee exposes its capabilities to LLM agents through the Model Context Protocol. The MCP server is published on npm as `reversee-mcp`.

Setup (with the Reversee app running):
- Claude Code: `claude mcp add reversee -- npx -y reversee-mcp`
- Cursor (~/.cursor/mcp.json): `{ "mcpServers": { "reversee": { "command": "npx", "args": ["-y", "reversee-mcp"] } } }`

Security model: the MCP bridge talks to the app over a token-authenticated local unix socket / Windows named pipe — never a TCP port. Read-only tools are always available; mutating tools (start/stop/restart the proxy, change config, add/remove proto specs) require the user to enable "Allow MCP to Control the Proxy" in the app, or launching headless with `--allow-mcp-control`.

MCP tools:
- `get_status`: app version, proxy run state, listen/destination config, traffic and breakpoint counts.
- `get_config` / `update_config`: read / change the proxy configuration (update is gated).
- `start_proxy` / `stop_proxy` / `restart_proxy`: control the proxy process (gated).
- `list_traffic`: captured requests, paged, bodies elided.
- `search_traffic`: filter captured requests server-side (method, status incl. classes/comparisons, url/regex, content-type, header, body, timing, errors) so you fetch only what matters instead of dumping everything.
- `summarize_session`: aggregate view — counts by status class and method, content types, top hosts, the error requests, and the slowest requests.
- `get_traffic_entry`: one request in full — headers, bodies, timings, curl command, upstream target, and any JWTs decoded from its Authorization header or cookies.
- `replay_request`: re-send a captured request to its upstream with optional edits (method/url/headers/body) — agent hypothesis testing; records a new entry (gated).
- `set_interceptor`: install/toggle a request or response interceptor (arbitrary JavaScript that rewrites traffic) for mocking and fault injection (gated).
- `decode_jwt`: decode a JWT's header and claims (inspection only; signature not verified).
- `list_breakpoints`: configured breakpoint rules.
- `list_proto_specs`: saved protobuf specs used to decode gRPC, plus compile errors.
- `add_proto_spec` / `remove_proto_spec`: save (`.proto` text or base64 FileDescriptorSet) / delete a protobuf spec (gated).
- `validate_setup`: setup checks (destination, ports, root cert, proxy process).
- `export_diagnostics`: versions, platform, settings, state — for bug reports.

Every captured request has a stable, monotonic `trafficId` (never reset across clear or proxy restart) — a durable handle for get_traffic_entry and replay_request.

The Reversee app owns the tool catalog and serves it to the bridge at startup, so tools added in app updates reach agents automatically without reinstalling `reversee-mcp`.

Full tool reference (every tool, exact parameters, verbatim descriptions, and agent workflows): https://galusben.github.io/reversee/mcp.html — Markdown source: https://github.com/galusben/reversee/blob/main/docs/mcp-tools.md

Headless mode (agent- or CI-driven, no UI):
- `reversee --headless --allow-mcp-control` runs with no window on just the proxy + MCP socket, until killed.
- Use a separate `REVERSEE_USER_DATA` directory to isolate an agent's instance from a GUI instance (each gets its own control socket).

## Install

- macOS (Homebrew): `brew tap galusben/reversee && brew install --cask reversee`
- macOS / Linux (one-liner): `curl -fsSL https://raw.githubusercontent.com/galusben/reversee/main/install.sh | bash`
- All platforms (incl. Windows): https://github.com/galusben/reversee/releases/latest
- MCP server only (npm): https://www.npmjs.com/package/reversee-mcp

## Documentation

- [README](https://github.com/galusben/reversee/blob/main/README.md): features, install, MCP setup, headless mode, development.
- [Agent guide](https://github.com/galusben/reversee/blob/main/AGENTS.md): the canonical entry point for AI agents working in the repo.
- [Knowledge base](https://github.com/galusben/reversee/blob/main/docs/README.md): code map, feature catalog, conventions, and decisions.
- [Architecture](https://github.com/galusben/reversee/blob/main/docs/architecture.md): where to find what in the codebase.
- [Contributing](https://github.com/galusben/reversee/blob/main/CONTRIBUTING.md): setup and the change workflow.
- [Decision records](https://github.com/galusben/reversee/blob/main/docs/adr/README.md): the key architecture decisions and why.
- [Testing](https://github.com/galusben/reversee/blob/main/TESTING.md): the test layers and how they map to CI.
- [Releasing](https://github.com/galusben/reversee/blob/main/RELEASING.md): the tag-driven release pipeline.
- [reversee-mcp package](https://github.com/galusben/reversee/blob/main/mcp/README.md): the MCP bridge's tools and security model.
- [MCP tools reference](https://github.com/galusben/reversee/blob/main/docs/mcp-tools.md): every MCP tool with exact parameters, verbatim descriptions, examples, and agent workflows ([web version](https://galusben.github.io/reversee/mcp.html)).