Metadata-Version: 2.5
Name: shieldpi-mcp
Version: 0.5.1
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://shieldpi.io/docs
Project-URL: Leaderboard, https://shieldpi.io/leaderboard
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<2,>=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 the LLM attack catalog, 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-22c55e)](https://shieldpi.io/leaderboard)

ShieldPi is the AI SOC platform:

- **Scanner** — an attack catalog with Browser / API / Agent / Model scan modes, 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 configured 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.

Catalog and model availability change over time. Query `list_attack_categories`,
`list_attack_techniques`, and `get_model_registry` for the current data and any
reported totals; consult `get_methodology` for the published scope and scoring
method. A registry entry does not by itself mean a model has been tested. See the
[leaderboard](https://shieldpi.io/leaderboard) for published results and dates.

## Available tools

| Tier | Tool | API key? | Use it for |
|------|------|----------|-----------|
| 1 | `get_methodology` | no | Pull the published 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 | Published leaderboard data |
| 1 | `get_leaderboard` | no | Top models by best security score |
| 1 | `get_model_registry` | no | Query the current model registry |
| 2 | `list_attack_categories` | yes | Current attack categories + OWASP mappings |
| 2 | `list_attack_techniques` | yes | Browse the current attack 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 |
| 2 | `set_incident_status` | yes | Human override: escalate / resolve / suppress |
| 2 | `get_onboarding_status` 🆕 | yes | Account setup checklist — derived from live account state |
| 2 | `download_scan_bundle` 🆕 | yes | CI bundle manifest (report + available 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 reflects the returned account data. `download_scan_bundle` returns a manifest + `curl` command for a zip containing report.json + report.pdf + the available 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). Scheduled triage depends on the deployment configuration; `trigger_triage` requests an on-demand run.

Tier-1 does not require an API key, but requires access to the configured ShieldPi API. Tier-2 needs a ShieldPi API key — get one at [shieldpi.io/dashboard/api-keys](https://shieldpi.io/dashboard/api-keys).

## Companion: the `shieldpi` SDK

The MCP server queries scans, alerts, and guardrails and provides explicit actions such as scan creation and alert updates. Agent event capture is handled by 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 list its available 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 my configured target `<target-uuid>` and report its scan ID."*

> *"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."*

## Starting scans

Use `start_scan(target_id="<target-uuid>", mode="model")` for an existing model
target configured with a BYOK credential in the dashboard. The tool loads that
target and starts the scan using its stored mode and credentials. It does not
create a model target from a slug or URL, accept provider secrets, or provision
BYOK credentials. A model request without `target_id` is refused locally.

For browser, API, or agent scans, supply an existing `target_id` or create a new
target by passing `target_url` and `mode`. For new API targets, `api_format` and
`api_model` describe the endpoint; configure any required endpoint credentials
on a saved target first. Existing target configuration takes precedence over
new-target arguments. Backend permissions, plan limits, and scan validation
still apply.

The JSON result includes `target_id`, `scan_id`, status, and the dashboard URL.
Agent scans also return `agent_session` when supplied by the backend. Use its
connection details to connect the agent before polling `get_scan_status`; an
unconnected agent cannot answer scan requests. Model/provider credentials are
not included in scan requests made by this MCP tool.

## 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

Start from the sdist on PyPI, which ships the package and its tests:

```bash
pip download shieldpi-mcp --no-deps --no-binary :all:
tar xzf shieldpi_mcp-*.tar.gz
cd shieldpi_mcp-*/
pip install -e ".[dev]"
pytest
```

The test suite runs offline with `httpx.MockTransport`; it does not contact a
live API, create a real target, or start a real scan. Ambient API credentials are
removed in fixtures. It covers client authentication and errors, MCP tool
registration, existing model targets with BYOK, local model-creation refusal,
API format fields, and agent-session propagation. Live service behavior requires
a separate authorized integration check.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│            Claude Desktop / Claude Code / Cursor                 │
│                  (MCP Client over stdio)                         │
└──────────────────────────────┬──────────────────────────────────┘
                               │ MCP (JSON-RPC over stdio)
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    shieldpi-mcp (Python)                         │
│  ┌──────────────┐  ┌─────────────────┐                          │
│  │  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 leaderboard](https://shieldpi.io/leaderboard)
- **Methodology:** [shieldpi.io/methodology](https://shieldpi.io/methodology)
- **Research:** [shieldpi.io/research](https://shieldpi.io/research)
- **Support:** [support@shieldpi.io](mailto:support@shieldpi.io)
