Metadata-Version: 2.4
Name: shieldpi-mcp
Version: 0.5.0
Summary: MCP server for ShieldPi Watchtower — run LLM security scans, generate drop-in guardrails from scan findings, operate the AI SOC analyst (incident triage + kill-chain reconstruction), and query the live agent monitor from Claude Desktop / Cursor / Continue.
Project-URL: Homepage, https://shieldpi.io
Project-URL: Documentation, https://github.com/ShieldPi1/shieldpi-watchtower/tree/main/mcp-server
Project-URL: Repository, https://github.com/ShieldPi1/shieldpi-watchtower
Project-URL: Issues, https://github.com/ShieldPi1/shieldpi-watchtower/issues
Project-URL: Leaderboard, https://shieldpi.info
Project-URL: Methodology, https://shieldpi.io/methodology
Author-email: ShieldPi <support@shieldpi.io>
License: MIT
License-File: LICENSE
Keywords: ai-security,anthropic,claude,jailbreak,llm-security,mcp,owasp,prompt-injection,red-team
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# shieldpi-mcp

> **MCP server for [ShieldPi Watchtower](https://shieldpi.io)** — query 27,000+ LLM attack techniques, run scans, pull breach forensics, generate drop-in runtime guardrails from scan findings, and operate the Live Agent Monitor SOC from Claude Desktop / Cursor / Continue.

[![PyPI](https://img.shields.io/pypi/v/shieldpi-mcp.svg)](https://pypi.org/project/shieldpi-mcp/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Leaderboard](https://img.shields.io/badge/leaderboard-shieldpi.info-22c55e)](https://shieldpi.info)

ShieldPi is the AI SOC platform:

- **Scanner** — 27,024+ attack techniques × 4 scan modes (Browser / API / Agent / Model), ExploitDepth L1–L4 scoring, and forensic kill-chain narratives with extracted breach evidence.
- **Runtime monitor** — the [`shieldpi`](https://pypi.org/project/shieldpi/) SDK. Zero-code-change install for LangChain / LangGraph / OpenAI Assistants / Anthropic SDK: `pip install "shieldpi[all]"` then `import shieldpi.auto`. Every tool call, LLM call, and user message streams to ShieldPi's six detectors in real time.
- **Auto-guardrails (new in v0.3.0)** — every L2+ finding from a scan becomes a deployable runtime guardrail. Export as drop-in Python middleware, LangChain callback, or NeMo Colang.

This MCP server exposes all three surfaces inside any MCP-compatible LLM session.

## What you get — 25 tools

| Tier | Tool | API key? | Use it for |
|------|------|----------|-----------|
| 1 | `get_methodology` | no | Pull the V7 scoring + dedup + judge methodology |
| 1 | `get_attack_graph` | no | Cross-customer success-rate graph by technique × model family |
| 1 | `get_model_families` | no | ShieldPi's family taxonomy + similarity edges |
| 1 | `get_leaderboard_feed` | no | Live data behind shieldpi.info |
| 1 | `get_leaderboard` | no | Top models by best security score |
| 1 | `get_model_registry` | no | All 38+ models ShieldPi can test |
| 2 | `list_attack_categories` | yes | The 15 categories + OWASP mappings |
| 2 | `list_attack_techniques` | yes | Browse the 27k catalog with filters |
| 2 | `start_scan` | yes | Kick off a scan against a target |
| 2 | `get_scan_status` | yes | Poll an in-progress scan |
| 2 | `get_scan_intelligence` | yes | Breach-forensics package for a completed scan |
| 2 | `get_scan_guardrails` | yes | Auto-generated runtime guardrails from scan findings |
| 2 | `export_scan_guardrails` | yes | Export guardrails as Python / LangChain / NeMo Colang |
| 2 | `get_incidents` | yes | AI-triaged incidents (clusters of related alerts) |
| 2 | `get_incident_detail` | yes | Kill chain + linked alerts + AI verdict for one incident |
| 2 | `trigger_triage` | yes | Run an on-demand triage pass (sync; beat also runs 60s) |
| 2 | `set_incident_status` | yes | Human override: escalate / resolve / suppress |
| 2 | `get_onboarding_status` 🆕 | yes | 6-step setup checklist — derived from live account state |
| 2 | `download_scan_bundle` 🆕 | yes | CI bundle manifest (report + all 4 guardrail formats + stats) |
| 2 | `get_live_alerts` | yes | Runtime alerts from deployed monitored agents |
| 2 | `get_alert_detail` | yes | Full forensic detail for one alert (kill chain replay) |
| 2 | `acknowledge_alert` | yes | Mark an alert as triaged |
| 2 | `resolve_alert` | yes | Mark an alert as resolved |
| 2 | `list_monitor_sessions` | yes | Sessions across all monitored agents |
| 2 | `get_session_events` | yes | Full event chain for one session |

🆕 = new in v0.5.0 (customer onboarding + CI bundle). `get_onboarding_status` returns a live checklist (API key → first target → monitored agent → SDK event → webhook → first alert) derived from account state, so progress is always honest. `download_scan_bundle` returns a manifest + `curl` command for a zip containing report.json + report.pdf + all 4 guardrail formats, shaped for CI pipelines that want one curl + one unzip.

v0.4.0 shipped the AI SOC analyst (incident triage, kill-chain reconstruction, human override). A background Celery beat job runs triage every 60 seconds; `trigger_triage` forces an immediate run.

Tier-1 works the moment you install. Tier-2 needs a free ShieldPi API key — get one at [shieldpi.io/dashboard/api-keys](https://shieldpi.io/dashboard/api-keys).

## Companion: the `shieldpi` SDK

The MCP server is the **read** side of ShieldPi — it queries scans, alerts, and guardrails. The **write** side (capturing agent events in the first place) is the [`shieldpi`](https://pypi.org/project/shieldpi/) Python SDK. In any monitored agent:

```bash
pip install "shieldpi[all]"
export SHIELDPI_SDK_KEY=shpi_live_...
```

```python
import shieldpi.auto   # ONE line, zero code changes
```

That's it — LangChain / LangGraph / OpenAI Assistants / Anthropic tool-use calls are auto-captured. Alerts land in your dashboard, flow to Slack via webhook, and are queryable here via `get_live_alerts`. See the [docs](https://shieldpi.io/docs/live-agent-monitor) for the full wiring.

## Install

**Recommended (works on every OS, puts `shieldpi-mcp` on your `$PATH`):**

```bash
pipx install shieldpi-mcp
```

Don't have `pipx`? `brew install pipx && pipx ensurepath` (macOS) or `python3 -m pip install --user pipx && pipx ensurepath` (Linux/Windows).

Why pipx: Claude Desktop / Cursor / Continue look up `shieldpi-mcp` on `$PATH`. `pipx` handles that automatically. Plain `pip install` may put the entry point somewhere your MCP client can't find.

**Alternative — `pip` with an explicit modern Python (Python 3.10+ is required):**

```bash
python3.11 -m pip install --user shieldpi-mcp
# then add ~/Library/Python/3.11/bin (macOS) or ~/.local/bin (Linux) to your PATH
```

If you see `ERROR: Could not find a version that satisfies the requirement shieldpi-mcp`, your default `pip` is using a Python older than 3.10 (common on macOS, where the system `python3` is 3.9). Use `pipx` or pick a modern Python explicitly as above.

**Or with `uv`:**

```bash
uv tool install shieldpi-mcp
```

The package ships a `shieldpi-mcp` console entry point that runs the server over stdio — that's what every MCP client expects.

## Configure your client

### Claude Desktop

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

```json
{
  "mcpServers": {
    "shieldpi": {
      "command": "shieldpi-mcp",
      "env": {
        "SHIELDPI_API_KEY": "shpi_live_..."
      }
    }
  }
}
```

Restart Claude Desktop. Look for the 🔌 plug icon — `shieldpi` should be listed with 25 tools.

### Claude Code

```bash
claude mcp add shieldpi -- shieldpi-mcp
```

Then set the env var in the same shell or in your `.envrc`:

```bash
export SHIELDPI_API_KEY="shpi_live_..."
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "shieldpi": {
      "command": "shieldpi-mcp",
      "env": { "SHIELDPI_API_KEY": "shpi_live_..." }
    }
  }
}
```

### Continue (VS Code / JetBrains)

In `~/.continue/config.json`:

```json
{
  "mcpServers": {
    "shieldpi": {
      "command": "shieldpi-mcp",
      "env": { "SHIELDPI_API_KEY": "shpi_live_..." }
    }
  }
}
```

## Try it

Once installed and configured, ask your LLM:

> *"Using the shieldpi tools, what's the current security ranking of Claude Sonnet 4.5 vs GPT-4o?"*

> *"Pull the ShieldPi methodology and explain ExploitDepth scoring in plain English."*

> *"Browse the prompt_injection category in the ShieldPi attack catalog and pick 3 techniques worth testing on my agent."*

> *"Start a model-mode scan against `anthropic/claude-sonnet-4.5` and report when it's done."*

> *"Get the auto-generated guardrails for scan `<uuid>` as a LangChain callback I can paste into my agent."*

> *"Check `get_live_alerts` for anything critical on my production agents in the last hour, group by detector, and walk me through the worst one via `get_alert_detail`."*

> *"Call `get_incidents` with severity=critical. For each incident that isn't already suppressed, pull `get_incident_detail`, summarize the AI kill-chain reconstruction, and tell me which one deserves human escalation."*

> *"Run `trigger_triage` on target {uuid} to get fresh verdicts on the last hour of alerts, then list any new incidents flagged as false positives."*

> *"Use `get_onboarding_status` to check my setup. For every step that's still pending, tell me exactly what to click and give me the copy-paste snippet."*

> *"Call `download_scan_bundle` for scan {uuid} and give me a curl command I can drop into our GitHub Actions workflow so every CI run writes guardrails to our repo."*

## Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `SHIELDPI_API_KEY` | (none) | Required for tier-2 tools (techniques catalog, scans). Free tier works. |
| `SHIELDPI_API_BASE` | `https://api.shieldpi.io` | Override for self-hosted ShieldPi or staging. |
| `SHIELDPI_TIMEOUT` | `30` | Per-request timeout in seconds. |

## Develop

```bash
git clone https://github.com/ShieldPi1/shieldpi-watchtower.git
cd shieldpi-watchtower/mcp-server
pip install -e ".[dev]"
pytest
```

The test suite hits live `api.shieldpi.io` for tier-1 endpoints and skips tier-2 unless `SHIELDPI_API_KEY` is set.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│            Claude Desktop / Claude Code / Cursor                 │
│                  (MCP Client over stdio)                         │
└──────────────────────────────┬──────────────────────────────────┘
                               │ MCP (JSON-RPC over stdio)
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    shieldpi-mcp (Python)                         │
│  ┌──────────────┐  ┌─────────────────┐                          │
│  │  10 MCP      │  │ ShieldPiClient  │                          │
│  │  tools       │  │   (httpx)       │                          │
│  └──────┬───────┘  └────────┬────────┘                          │
└─────────┼───────────────────┼────────────────────────────────────┘
          │                   │ HTTPS outbound only
          │                   ▼
          │       ┌─────────────────────────────┐
          │       │  https://api.shieldpi.io   │
          │       │  (FastAPI on Hetzner)       │
          │       └─────────────────────────────┘
          ▼
   stdout (MCP responses)
```

Outbound HTTPS only. No inbound ports. API keys are read from env vars, never logged. The server is single-process, stateless across requests — safe to drop into any client.

## License

MIT. See [LICENSE](LICENSE).

## Links

- **Product:** [shieldpi.io](https://shieldpi.io)
- **Leaderboard:** [shieldpi.info](https://shieldpi.info)
- **Methodology:** [shieldpi.io/methodology](https://shieldpi.io/methodology)
- **Research:** [shieldpi.io/research](https://shieldpi.io/research)
- **Issues:** [github.com/ShieldPi1/shieldpi-watchtower/issues](https://github.com/ShieldPi1/shieldpi-watchtower/issues)
