Metadata-Version: 2.4
Name: medusa-mcp
Version: 2.1.0
Summary: Endpoint security agent for Model Context Protocol (MCP) servers
License: Apache-2.0
License-File: LICENSE
Keywords: mcp,security,agent,gateway,endpoint,model-context-protocol
Author: Joshua Bukshpan
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Dist: Pillow (>=10.0)
Requires-Dist: click (>=8.0)
Requires-Dist: httpx (>=0.27)
Requires-Dist: keyring (>=25.0)
Requires-Dist: mcp (>=1.26.0)
Requires-Dist: numpy (>=1.24)
Requires-Dist: onnxruntime (>=1.17)
Requires-Dist: openpyxl (>=3.1)
Requires-Dist: packaging (>=23.0)
Requires-Dist: psutil (>=5.9)
Requires-Dist: pydantic (>=2.0)
Requires-Dist: pymupdf (>=1.24)
Requires-Dist: pytesseract (>=0.3.10)
Requires-Dist: python-docx (>=1.1)
Requires-Dist: pyyaml (>=6.0)
Requires-Dist: rich (>=13.0)
Requires-Dist: starlette (>=0.37)
Requires-Dist: tokenizers (>=0.19)
Requires-Dist: tomli_w (>=1.0)
Requires-Dist: uvicorn[standard] (>=0.29)
Project-URL: Homepage, https://github.com/joshmaster2165/medusa-agent
Project-URL: Repository, https://github.com/joshmaster2165/medusa-agent
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/logo.svg" alt="Medusa Logo" width="300">
</p>
<p align="center">
  <strong>Open-source endpoint DLP for Model Context Protocol (MCP)</strong>
</p>

<p align="center">
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green.svg" alt="License: Apache 2.0"></a>
  <a href="https://github.com/joshmaster2165/medusa-agent/releases"><img src="https://img.shields.io/github/v/release/joshmaster2165/medusa-agent" alt="Latest Release"></a>
</p>

<p align="center">
  AI assistants — Claude Desktop, Cursor, Codex, Claude Code — now use tools
  through MCP servers, and most security teams have no idea what data flows
  through them. Medusa is a CLI agent that sits between every AI assistant and
  every MCP server, scans the traffic on-device for secrets, PII, and 9 more
  categories of sensitive data, and blocks or redacts what shouldn't leave.
</p>

<p align="center">
  <strong>It runs 100% locally. No account, no cloud, no telemetry — unless you choose to connect one.</strong>
</p>

---

## Install

The agent installs in **standalone mode** — local policy, local event store,
zero network calls.

```bash
# One-liner (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/joshmaster2165/medusa-agent/main/packaging/install.sh | sh

# Homebrew
brew tap joshmaster2165/medusa
brew install medusa-agent

# pip / pipx
pipx install medusa-mcp
medusa-agent install
```

Native signed installers (`.pkg` / `.deb` / `.msi`) are on the
[releases page](https://github.com/joshmaster2165/medusa-agent/releases).

Verify it:

```bash
medusa-agent doctor
```

That's it. The agent has auto-discovered every MCP client on the machine,
wrapped each server with a gateway proxy, and is enforcing DLP policy from
`~/.medusa/gateway-policy.yaml`.

---

## How it works

```
   AI assistant                  Medusa gateway proxy                MCP server
  (Cursor, Claude   ──JSON-RPC──▶   ┌────────────────────┐  ──────▶  (filesystem,
   Desktop, Codex)                  │  Policy engine     │            Supabase,
                                    │  ALLOW / BLOCK /   │            Stripe, …)
                                    │  COACH  / REDACT   │
                                    │        │           │
                                    │  DLP scanner       │
                                    │  on-device model   │
                                    │  + regex patterns  │
                                    │        │           │
                                    │  WriteAccumulator  │
                                    │  cross-request     │
                                    │  evasion detection │
                                    └────────────────────┘
```

Every JSON-RPC message — request and response, stdio and Streamable HTTP — is
intercepted and evaluated. Nothing is sent anywhere; inference runs on the CPU.

---

## What it catches

- **9 DLP categories** via an on-device ONNX model: secrets, PII, financial,
  health/PHI, source code, legal, insurance, HR, business-confidential — plus
  prompt-injection detection on tool *results*.
- **Deterministic regex detectors** for SSN, credit card, AWS keys, GitHub
  tokens, RSA private keys, email, phone, and more — fire at confidence 1.0
  alongside the model.
- **Cross-request evasion** — `WriteAccumulator` reassembles content split
  across multiple `write_file` / `append_file` / `edit_file` calls and rescans
  the whole thing, so an agent can't smuggle a secret out one chunk at a time.
- **Tamper resistance** — the agent detects and auto-repairs attempts to strip
  its own gateway wrapper from MCP config files, and refuses tool calls that
  target its protected paths.

Verdicts: **ALLOW** (forward unchanged) · **BLOCK** (stop at the gateway) ·
**REDACT** (forward with sensitive spans masked) · **COACH** (block + tell the
LLM agent why, so it stops retrying).

---

## Standalone vs connected

| | Standalone *(default)* | Connected |
|---|---|---|
| Account | None | API key from a control plane |
| Network | Zero calls | Policy sync + telemetry |
| Policy | Local `gateway-policy.yaml` | Pushed from the control plane |
| Events | Local SQLite only | Uploaded to a dashboard |

A **control plane** is an optional service that distributes policy to a fleet
of agents and aggregates their telemetry — useful once you're running Medusa on
more than one machine. It can be Medusa's hosted dashboard or a self-hosted
one; the agent speaks the same open
[Control Plane API](docs/control-plane-api.md) either way.

```bash
# Attach this agent to a control plane
medusa-agent connect --control-plane <url> --api-key <key>

# Detach — back to fully local
medusa-agent disconnect
```

The agent is open source and free, forever. The fleet dashboard is the
commercial product.

---

## CLI

| Command | Description |
|---|---|
| `medusa-agent install` | Install the agent (standalone by default) |
| `medusa-agent doctor` | Run diagnostic checks |
| `medusa-agent connect` | Attach to a control plane |
| `medusa-agent disconnect` | Detach — back to standalone |
| `medusa-agent download-model` | Fetch the DLP model (pip installs) |
| `medusa-agent status` | Daemon health, proxy count, policy version |
| `medusa-agent monitor` | Security posture and findings |
| `medusa-agent test` | Dry-run a tool call against the policy |
| `medusa-agent logs` | Tail the agent log (`-f` to follow) |
| `medusa-agent start` / `stop` / `restart` | Daemon control |
| `medusa-agent store list` / `stats` / `clear` | Local event store |
| `medusa-agent uninstall` | Remove the agent |

---

## Gateway policy

A standalone agent reads `~/.medusa/gateway-policy.yaml`:

```yaml
block_secrets: true
block_pii: true
block_financial: true
block_health: true
block_injections: true
scan_responses: true
coaching_enabled: true
sandbox_mode: false        # true = observe-only (log, don't enforce)
max_calls_per_minute: 60
blocked_tools: []
dlp_category_thresholds:
  pii: 0.65
  secret: 0.5
  financial: 0.5
```

Edit it and the daemon hot-reloads within seconds. A connected agent receives
this same object, HMAC-signed, from its control plane.

---

## Supported MCP clients

Claude Desktop · Cursor · Claude Code · OpenAI Codex · Windsurf · VS Code
(Copilot) · Gemini CLI · Zed · Cline · Roo Code · Continue.dev · Amazon Q —
plus a system-wide scan that picks up MCP servers from unknown clients.

Both stdio and Streamable HTTP MCP servers are proxied.

---

## Platform support

| Platform | Service | Installer |
|---|---|---|
| macOS | launchd LaunchAgent | `.pkg` |
| Linux | systemd user service | `.deb` |
| Windows | Windows Service | `.msi` |

---

## Development

```bash
git clone https://github.com/joshmaster2165/medusa-agent.git
cd medusa-agent
poetry install
poetry run pytest tests/ -q          # test suite
poetry run ruff check src/ tests/    # lint
poetry run ruff format src/ tests/   # format
```

```
src/medusa/
  gateway/      # proxy, policy engine, DLP scanner, write accumulator
  agent/        # daemon, installer, control_plane client, doctor
  cli/          # the medusa-agent CLI
  connectors/   # MCP client auto-discovery
  models/       # tokenizer + label map (ONNX model fetched separately)
```

See [CONTRIBUTING.md](CONTRIBUTING.md) to get started, and
[docs/control-plane-api.md](docs/control-plane-api.md) for the agent↔control-plane
wire contract.

---

## Security

To report a vulnerability, see [SECURITY.md](SECURITY.md). Please do not open a
public issue for security problems.

## License

[Apache 2.0](LICENSE). The agent is free and open source. A commercial fleet
dashboard is available separately.

