shieldpi-mcp 0.1.0__tar.gz

shieldpi_mcp-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store

shieldpi_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShieldPi (support@shieldpi.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shieldpi_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: shieldpi-mcp
+Version: 0.1.0
+Summary: MCP server for ShieldPi Watchtower — query 27,000+ LLM attack techniques, run scans, fetch breach forensics from any MCP-compatible client (Claude Desktop, Claude Code, Cursor).
+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, and pull breach forensics from any MCP-compatible client (Claude Desktop, Claude Code, 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 security forensics platform for LLMs and agents. It runs **27,024+ attack techniques** across 4 scan modes (Browser / API / Agent / Model), classifies findings on the **ExploitDepth L1–L4 scale**, and produces a forensic kill-chain narrative + extracted breach evidence (credentials, PII, code, tools, blast radius) for every successful attack.
+
+This MCP server lets you talk to ShieldPi from inside any LLM session.
+
+## What you get
+
+| 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_intelligence` | yes | Pull the breach-forensics package for a scan |
+
+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).
+
+## Install
+
+```bash
+pip install shieldpi-mcp
+```
+
+Or with `uv`:
+
+```bash
+uv pip 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 10 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."*
+
+## 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)

shieldpi_mcp-0.1.0/README.md

@@ -0,0 +1,176 @@
+# shieldpi-mcp
+
+> **MCP server for [ShieldPi Watchtower](https://shieldpi.io)** — query 27,000+ LLM attack techniques, run scans, and pull breach forensics from any MCP-compatible client (Claude Desktop, Claude Code, 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 security forensics platform for LLMs and agents. It runs **27,024+ attack techniques** across 4 scan modes (Browser / API / Agent / Model), classifies findings on the **ExploitDepth L1–L4 scale**, and produces a forensic kill-chain narrative + extracted breach evidence (credentials, PII, code, tools, blast radius) for every successful attack.
+
+This MCP server lets you talk to ShieldPi from inside any LLM session.
+
+## What you get
+
+| 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_intelligence` | yes | Pull the breach-forensics package for a scan |
+
+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).
+
+## Install
+
+```bash
+pip install shieldpi-mcp
+```
+
+Or with `uv`:
+
+```bash
+uv pip 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 10 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."*
+
+## 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)

shieldpi_mcp-0.1.0/SUBMISSION.md

@@ -0,0 +1,112 @@
+# Distribution checklist — shieldpi-mcp
+
+End-to-end checklist for getting `shieldpi-mcp` in front of every Claude Desktop / Code / Cursor / Continue user. Each step is small; the order matters.
+
+## 1. PyPI publish (10 min — do this first)
+
+The `publish-mcp.yml` GitHub Action publishes on a `mcp-v*` tag push, but it needs a PyPI token first.
+
+### One-time PyPI setup
+
+1. Sign in (or create account) at https://pypi.org/ as `support@shieldpi.io`.
+2. Reserve the project name: https://pypi.org/manage/account/projects/ → it'll auto-claim on first upload, but you can manually create it.
+3. Create an API token scoped to `shieldpi-mcp` only:
+   - https://pypi.org/manage/account/token/
+   - Token name: `shieldpi-mcp-github-actions`
+   - Scope: project `shieldpi-mcp` (after first upload). Until first upload, scope it to "Entire account" temporarily.
+4. Add the token to the repo as a secret named `PYPI_MCP_TOKEN`:
+   - https://github.com/ShieldPi1/shieldpi-watchtower/settings/secrets/actions
+   - Name: `PYPI_MCP_TOKEN` · Value: the `pypi-...` token from step 3.
+
+### First publish
+
+```bash
+cd /Users/calvin/shieldpi-deploy
+git tag mcp-v0.1.0
+git push origin mcp-v0.1.0
+```
+
+GitHub Actions runs `publish-mcp.yml` → tests → `python -m build` → `twine upload`. Within ~3 min the package appears at https://pypi.org/project/shieldpi-mcp/.
+
+After the first successful upload, narrow the PyPI token scope from "Entire account" to "shieldpi-mcp" only, and rotate `PYPI_MCP_TOKEN` to the narrowed token.
+
+### Verify
+
+```bash
+pip install shieldpi-mcp
+shieldpi-mcp --help 2>&1 | head -3   # should print MCP server startup info
+```
+
+## 2. Anthropic MCP directory (1–4 weeks review)
+
+Anthropic maintains a curated list at https://github.com/modelcontextprotocol/servers. Submission is a PR to that repo.
+
+### Submission steps
+
+1. Fork https://github.com/modelcontextprotocol/servers.
+2. Add an entry to `README.md` in the **"Third-Party Servers"** → **"Official Integrations"** (since we're an established product) or **"Community Servers"** section. Format follows the existing entries:
+
+   ```markdown
+   - **[ShieldPi](https://github.com/ShieldPi1/shieldpi-watchtower/tree/main/mcp-server)** — Query 27,000+ LLM attack techniques, run security scans, and pull breach forensics. Powers the [ShieldPi Watchtower](https://shieldpi.io) AI security platform.
+   ```
+
+3. Open PR with a short description:
+   > Adding `shieldpi-mcp` — production MCP server for ShieldPi Watchtower (LLM security forensics platform). 10 tools across 6 public + 4 authenticated endpoints. MIT-licensed, on PyPI as `shieldpi-mcp`. Tested against live api.shieldpi.io. Public methodology + leaderboard at shieldpi.io and shieldpi.info.
+
+4. Anthropic policy review (per their MCP directory policy: https://support.anthropic.com/en/articles/11697096):
+   - Outbound HTTPS only ✅
+   - API keys never logged ✅
+   - Private IPs not exposed ✅
+   - Clear error messages ✅
+   - LICENSE present (MIT) ✅
+   - README documents tools + auth ✅
+
+5. Approval typically takes 1–4 weeks. They may ask for changes — respond fast.
+
+### Smithery (parallel — same day)
+
+Smithery (https://smithery.ai/) is a community MCP marketplace that auto-discovers from GitHub. Listing happens automatically once the repo is public + tagged. You can also submit manually at https://smithery.ai/new for fast indexing.
+
+## 3. ClawHub (OpenClaw skill registry — same day)
+
+OpenClaw's ClawHub at https://clawhub.ai accepts MCP servers as well. Submit at https://clawhub.ai/submit.
+
+## 4. Inbound funnel — wire the MCP install URL into shieldpi.io
+
+After PyPI publish:
+
+1. Add a "Connect via MCP" CTA on shieldpi.io homepage hero — single line:
+   ```
+   pip install shieldpi-mcp && shieldpi-mcp
+   ```
+2. Add a `/mcp` page documenting the 10 tools (mirror the README).
+3. Update the leaderboard footer at shieldpi.info: "Use this data in your own LLM session — `pip install shieldpi-mcp`".
+4. Add `MCP server: pip install shieldpi-mcp` to every blog post sidebar.
+
+## 5. Distribution announcement (next sprint, after PyPI is live)
+
+- **HN Show post:** "Show HN: shieldpi-mcp — query 27,000+ LLM jailbreaks from inside Claude Desktop"
+- **LinkedIn post** (Calvin) — focus on the use case ("ask Claude about the security posture of any model, get a real answer from a real scanner")
+- **X thread** — 5 tweets walking through the 10 tools with a real example each
+- **Reddit:** r/LocalLLaMA, r/MachineLearning, r/cybersecurity (read each sub's rules first; some require account history)
+- **Direct outreach:** any AI security researcher who's ever cited a leaderboard
+
+## Timeline (optimistic)
+
+| Day | Item |
+|-----|------|
+| Today | Code shipped to GitHub ✅ (commit `ae839f8`) |
+| Today | PyPI token set up + first tag → PyPI publish |
+| Day +1 | Anthropic MCP directory PR opened |
+| Day +1 | Smithery + ClawHub submissions |
+| Day +1 | shieldpi.io `/mcp` page + homepage CTA |
+| Day +2–3 | HN Show + LinkedIn + X thread |
+| Day +7 to +28 | Anthropic directory approval lands |
+| Day +30 | First inbound usage signal (PyPI download count, ShieldPi API key signups attributable to MCP) |
+
+## Success metrics (90 days)
+
+Per [[decision-shieldpi-v8-growth-adoption]]:
+- 1,000+ PyPI installs
+- 10+ inbound enterprise inquiries with MCP attribution
+- Listed on Anthropic MCP directory

shieldpi_mcp-0.1.0/examples/claude-code.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Add ShieldPi MCP server to Claude Code.
+#
+# Prereq: pip install shieldpi-mcp  (or pipx install shieldpi-mcp)
+#
+# Usage: ./claude-code.sh
+
+set -euo pipefail
+
+if ! command -v shieldpi-mcp >/dev/null 2>&1; then
+  echo "shieldpi-mcp not found. Install with: pip install shieldpi-mcp"
+  exit 1
+fi
+
+claude mcp add shieldpi -- shieldpi-mcp
+echo
+echo "Added. Tier-2 tools (techniques catalog, scans) need an API key."
+echo "Set it in your shell or in ~/.envrc:"
+echo "  export SHIELDPI_API_KEY=\"shpi_live_...\""
+echo
+echo "Get a free key: https://shieldpi.io/dashboard/api-keys"

shieldpi_mcp-0.1.0/examples/claude-desktop.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "shieldpi": {
+      "command": "shieldpi-mcp",
+      "env": {
+        "SHIELDPI_API_KEY": "shpi_live_REPLACE_ME"
+      }
+    }
+  }
+}

shieldpi_mcp-0.1.0/examples/cursor-mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "shieldpi": {
+      "command": "shieldpi-mcp",
+      "env": {
+        "SHIELDPI_API_KEY": "shpi_live_REPLACE_ME"
+      }
+    }
+  }
+}

shieldpi_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shieldpi-mcp"
+version = "0.1.0"
+description = "MCP server for ShieldPi Watchtower — query 27,000+ LLM attack techniques, run scans, fetch breach forensics from any MCP-compatible client (Claude Desktop, Claude Code, Cursor)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "ShieldPi", email = "support@shieldpi.io" }
+]
+keywords = [
+  "mcp",
+  "llm-security",
+  "ai-security",
+  "red-team",
+  "jailbreak",
+  "prompt-injection",
+  "owasp",
+  "anthropic",
+  "claude"
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Information Technology",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+  "mcp>=1.2.0",
+  "httpx>=0.27.0",
+  "pydantic>=2.0.0"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "pytest-httpx>=0.30",
+  "ruff>=0.5"
+]
+
+[project.scripts]
+shieldpi-mcp = "shieldpi_mcp.server:main"
+
+[project.urls]
+Homepage = "https://shieldpi.io"
+Documentation = "https://github.com/ShieldPi1/shieldpi-watchtower/tree/main/mcp-server"
+Repository = "https://github.com/ShieldPi1/shieldpi-watchtower"
+Issues = "https://github.com/ShieldPi1/shieldpi-watchtower/issues"
+Leaderboard = "https://shieldpi.info"
+Methodology = "https://shieldpi.io/methodology"
+
+[tool.hatch.build.targets.wheel]
+packages = ["shieldpi_mcp"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

shieldpi_mcp-0.1.0/shieldpi_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""ShieldPi MCP — Model Context Protocol server for ShieldPi Watchtower."""
+
+__version__ = "0.1.0"

shieldpi_mcp-0.1.0/shieldpi_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m shieldpi_mcp` to launch the server."""
+
+from shieldpi_mcp.server import main
+
+if __name__ == "__main__":
+    main()

shieldpi_mcp-0.1.0/shieldpi_mcp/client.py

@@ -0,0 +1,104 @@
+"""Async HTTP client for api.shieldpi.io.
+
+Wraps the public + authenticated REST surface so MCP tools can call it without
+each one re-implementing auth, retries, and error formatting.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = os.getenv("SHIELDPI_API_BASE", "https://api.shieldpi.io")
+DEFAULT_TIMEOUT = float(os.getenv("SHIELDPI_TIMEOUT", "30"))
+USER_AGENT = "shieldpi-mcp/0.1.0 (+https://shieldpi.io)"
+
+
+class ShieldPiAPIError(RuntimeError):
+    """Raised when api.shieldpi.io returns a non-2xx response."""
+
+    def __init__(self, status: int, body: str, url: str) -> None:
+        super().__init__(f"ShieldPi API {status} on {url}: {body[:300]}")
+        self.status = status
+        self.body = body
+        self.url = url
+
+
+class ShieldPiClient:
+    """Thin async wrapper around api.shieldpi.io.
+
+    Public endpoints work without an API key. Authenticated endpoints require
+    `SHIELDPI_API_KEY` (set in env or passed to the constructor) — the client
+    sends it as both `X-API-Key` and `Authorization: Bearer` because different
+    routes accept different conventions.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        self.api_key = api_key or os.getenv("SHIELDPI_API_KEY")
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout or DEFAULT_TIMEOUT
+        self._client: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> "ShieldPiClient":
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            headers={"User-Agent": USER_AGENT, "Accept": "application/json"},
+        )
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    def _auth_headers(self) -> dict[str, str]:
+        if not self.api_key:
+            return {}
+        return {
+            "X-API-Key": self.api_key,
+            "Authorization": f"Bearer {self.api_key}",
+        }
+
+    def require_key(self, tool_name: str) -> None:
+        if not self.api_key:
+            raise ShieldPiAPIError(
+                status=401,
+                body=(
+                    f"Tool `{tool_name}` requires a ShieldPi API key. "
+                    f"Set SHIELDPI_API_KEY in your MCP client config "
+                    f"(get one at https://shieldpi.io/dashboard/api-keys)."
+                ),
+                url=f"{self.base_url}/_local",
+            )
+
+    async def get(
+        self, path: str, params: dict[str, Any] | None = None, auth: bool = False
+    ) -> Any:
+        assert self._client is not None, "ShieldPiClient must be used as `async with`"
+        headers = self._auth_headers() if auth else {}
+        resp = await self._client.get(path, params=params, headers=headers)
+        return self._parse(resp)
+
+    async def post(
+        self, path: str, json: dict[str, Any] | None = None, auth: bool = True
+    ) -> Any:
+        assert self._client is not None, "ShieldPiClient must be used as `async with`"
+        headers = self._auth_headers() if auth else {}
+        resp = await self._client.post(path, json=json, headers=headers)
+        return self._parse(resp)
+
+    @staticmethod
+    def _parse(resp: httpx.Response) -> Any:
+        if resp.status_code >= 400:
+            raise ShieldPiAPIError(resp.status_code, resp.text, str(resp.url))
+        if resp.headers.get("content-type", "").startswith("application/json"):
+            return resp.json()
+        return resp.text

shieldpi_mcp-0.1.0/shieldpi_mcp/server.py

@@ -0,0 +1,251 @@
+"""ShieldPi MCP server.
+
+Exposes 10 tools that wrap api.shieldpi.io so any MCP-compatible client
+(Claude Desktop, Claude Code, Cursor, Continue, etc.) can:
+
+- Query the ShieldPi V7 methodology, attack graph, model families, leaderboard
+- Look up models in the registry + their tested security posture
+- Browse the 27,000+ attack technique library by category
+- Kick off scans against a target and pull back forensic results
+
+Tier-1 tools (no API key required):
+  get_methodology, get_attack_graph, get_model_families,
+  get_leaderboard_feed, get_leaderboard, get_model_registry
+
+Tier-2 tools (require SHIELDPI_API_KEY env var):
+  list_attack_categories, list_attack_techniques,
+  start_scan, get_scan_intelligence
+
+Run as a stdio MCP server: `shieldpi-mcp` (entry point) or
+`python -m shieldpi_mcp.server`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+from mcp.server.fastmcp import FastMCP
+
+from shieldpi_mcp.client import ShieldPiAPIError, ShieldPiClient
+
+mcp = FastMCP(
+    name="shieldpi",
+    instructions=(
+        "ShieldPi is an LLM security scanner with 27,000+ attack techniques, "
+        "4 scan modes (Browser/API/Agent/Model), and a forensic platform that "
+        "extracts breach evidence from successful attacks. Use these tools to "
+        "look up the methodology, browse the attack catalog, query the public "
+        "leaderboard, and (with an API key) run scans + fetch forensic results. "
+        "Public docs: https://shieldpi.io/methodology · Leaderboard: https://shieldpi.info"
+    ),
+)
+
+
+# ---------------------------------------------------------------------------
+# Tier-1 tools (public, no API key required)
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+async def get_methodology() -> str:
+    """Return ShieldPi's full V7 scoring + dedup + judge + breach-layer methodology.
+
+    Use this when the user asks "how does ShieldPi score a model?", "what does
+    ExploitDepth L3 mean?", or wants to cite the methodology in a report.
+    Returns the same JSON document published at /api/intelligence/methodology.
+    """
+    async with ShieldPiClient() as client:
+        data = await client.get("/api/intelligence/methodology")
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+async def get_attack_graph() -> str:
+    """Return the cross-customer anonymized attack-success graph.
+
+    Maps attack technique → success rate per model family. The graph gets
+    smarter as more scans complete (network effect). Useful when the user
+    asks "which jailbreaks work on Claude / GPT / Gemini today?"
+    """
+    async with ShieldPiClient() as client:
+        data = await client.get("/api/intelligence/attack-graph")
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+async def get_model_families() -> str:
+    """Return ShieldPi's model-family taxonomy + similarity edges.
+
+    Useful when the user wants to know what families ShieldPi recognizes
+    (anthropic / openai / google / meta / qwen / kimi / deepseek / etc.) and
+    how findings transfer across families.
+    """
+    async with ShieldPiClient() as client:
+        data = await client.get("/api/intelligence/families")
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+async def get_leaderboard_feed() -> str:
+    """Return the live leaderboard feed — the data behind shieldpi.info.
+
+    Gives every model with a recent ShieldPi scan: best security score, grade,
+    last-tested timestamp, weakest category. Updated as scans complete.
+    """
+    async with ShieldPiClient() as client:
+        data = await client.get("/api/intelligence/leaderboard-feed")
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+async def get_leaderboard(limit: int = 30) -> str:
+    """Return the public model leaderboard sorted by best security score.
+
+    Args:
+        limit: max number of models to return (default 30, capped server-side).
+    """
+    async with ShieldPiClient() as client:
+        data = await client.get("/api/models/leaderboard", params={"limit": limit})
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+async def get_model_registry(family: str | None = None) -> str:
+    """Return the registry of models ShieldPi knows how to test.
+
+    Args:
+        family: optional family filter (anthropic, openai, google, meta, qwen, ...).
+            When omitted, returns all 38+ supported models.
+    """
+    async with ShieldPiClient() as client:
+        data = await client.get("/api/models/registry")
+    if family:
+        # Server doesn't filter; do it client-side so the LLM only sees what it asked for.
+        if isinstance(data, dict) and "models" in data:
+            data = {
+                **data,
+                "models": [
+                    m for m in data["models"]
+                    if m.get("family", "").lower() == family.lower()
+                ],
+            }
+    return json.dumps(data, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Tier-2 tools (require API key)
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+async def list_attack_categories() -> str:
+    """List the 15 attack categories ShieldPi tests against.
+
+    Requires SHIELDPI_API_KEY (free tier works). Each category includes the
+    technique count, OWASP LLM mapping, and OWASP Agentic mapping.
+    """
+    async with ShieldPiClient() as client:
+        client.require_key("list_attack_categories")
+        data = await client.get("/api/attacks/categories", auth=True)
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+async def list_attack_techniques(
+    category: str | None = None,
+    source: str | None = None,
+    limit: int = 25,
+    offset: int = 0,
+) -> str:
+    """Browse the 27,000+ attack technique library.
+
+    Args:
+        category: optional category filter (e.g. "prompt_injection", "jailbreak",
+            "agent_exploitation", "data_exfiltration").
+        source: optional source filter (e.g. "github:elder-plinius/L1B3RT45",
+            "shieldpi:agent_attack_library", "agentdojo").
+        limit: max techniques per page (default 25, max 100).
+        offset: pagination offset.
+
+    Requires SHIELDPI_API_KEY.
+    """
+    params: dict[str, Any] = {"limit": min(limit, 100), "offset": offset}
+    if category:
+        params["category"] = category
+    if source:
+        params["source"] = source
+    async with ShieldPiClient() as client:
+        client.require_key("list_attack_techniques")
+        data = await client.get("/api/attacks", params=params, auth=True)
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+async def start_scan(
+    target_url: str,
+    mode: Literal["browser", "api", "agent", "model"] = "browser",
+    target_name: str | None = None,
+    depth: Literal["quick", "standard", "deep"] = "standard",
+) -> str:
+    """Start a ShieldPi scan against a target URL.
+
+    Args:
+        target_url: URL or model identifier to scan. For `mode=model`, pass an
+            OpenRouter slug like "anthropic/claude-sonnet-4.5" or "openai/gpt-4o".
+        mode: scan mode — browser (web app), api (REST), agent (live agent),
+            model (LLM via OpenRouter). Default: browser.
+        target_name: human-readable label for the target. Defaults to the URL.
+        depth: quick (~5min, 50 techniques), standard (~30min, 500 techniques),
+            deep (~2h, 5000 techniques). Default: standard.
+
+    Returns the scan_id you can pass to `get_scan_intelligence`.
+    Requires SHIELDPI_API_KEY.
+    """
+    body = {
+        "target_url": target_url,
+        "mode": mode,
+        "target_name": target_name or target_url,
+        "depth": depth,
+    }
+    async with ShieldPiClient() as client:
+        client.require_key("start_scan")
+        data = await client.post("/api/scans", json=body, auth=True)
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+async def get_scan_intelligence(scan_id: str) -> str:
+    """Pull the full intelligence + breach-forensics package for a scan.
+
+    Returns: security score + grade + per-category results + extracted breach
+    artifacts (creds / PII / code / tools) + kill chain narrative + business
+    impact estimate.
+
+    Args:
+        scan_id: UUID returned by `start_scan` or visible in the dashboard URL.
+
+    Requires SHIELDPI_API_KEY.
+    """
+    async with ShieldPiClient() as client:
+        client.require_key("get_scan_intelligence")
+        data = await client.get(f"/api/scans/{scan_id}/intelligence", auth=True)
+    return json.dumps(data, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    """Run the MCP server over stdio (Claude Desktop / Code / Cursor default)."""
+    try:
+        mcp.run()
+    except ShieldPiAPIError as exc:
+        # FastMCP catches tool errors per-call; this only fires if the loop itself dies.
+        raise SystemExit(f"shieldpi-mcp fatal: {exc}") from exc
+
+
+if __name__ == "__main__":
+    main()

shieldpi_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,71 @@
+"""Smoke tests for shieldpi-mcp.
+
+Hits live api.shieldpi.io for tier-1 endpoints (no auth). Skips tier-2
+unless SHIELDPI_API_KEY is set.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from shieldpi_mcp.client import ShieldPiAPIError, ShieldPiClient
+
+
+@pytest.mark.asyncio
+async def test_get_methodology_returns_v7_document() -> None:
+    async with ShieldPiClient() as client:
+        data = await client.get("/api/intelligence/methodology")
+    assert isinstance(data, dict)
+    assert data.get("document_version", "").startswith("v7")
+    assert "breach_layer_v7" in data
+    assert "scoring" in data and "judge" in data and "dedup" in data
+
+
+@pytest.mark.asyncio
+async def test_get_leaderboard_returns_models() -> None:
+    async with ShieldPiClient() as client:
+        data = await client.get("/api/models/leaderboard", params={"limit": 5})
+    assert isinstance(data, dict)
+    assert "models" in data
+    assert isinstance(data["models"], list)
+
+
+@pytest.mark.asyncio
+async def test_get_attack_graph_responds() -> None:
+    async with ShieldPiClient() as client:
+        data = await client.get("/api/intelligence/attack-graph")
+    assert data is not None  # endpoint returns 200 even with empty graph
+
+
+@pytest.mark.asyncio
+async def test_tier2_without_key_raises() -> None:
+    # Force no-key path (env var must be unset for the test process)
+    client = ShieldPiClient(api_key=None)
+    async with client:
+        with pytest.raises(ShieldPiAPIError) as excinfo:
+            client.require_key("list_attack_categories")
+        assert excinfo.value.status == 401
+        assert "API key" in excinfo.value.body
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(
+    not os.getenv("SHIELDPI_API_KEY"),
+    reason="SHIELDPI_API_KEY not set; skipping authenticated smoke test",
+)
+async def test_list_attack_categories_with_key() -> None:
+    async with ShieldPiClient() as client:
+        data = await client.get("/api/attacks/categories", auth=True)
+    assert isinstance(data, (list, dict))
+
+
+def test_server_imports_cleanly() -> None:
+    """Importing the FastMCP server registers all tools without error."""
+    from shieldpi_mcp.server import mcp  # noqa: F401
+
+    # FastMCP internal: tools are stored in `_tool_manager`. Just confirm at
+    # least one tool was registered. The exact internal API is private; if it
+    # changes upstream this test gets a clear failure pointing to the upgrade.
+    assert hasattr(mcp, "_tool_manager") or hasattr(mcp, "tools")