feat: engine capability uplift (TG1–TG7) + MCP server wiring

.gitignore

@@ -68,6 +68,10 @@ wallbreaker/dashboard/web/dist/
 wallbreaker/dashboard/web/vite.config.js
 wallbreaker/dashboard/web/vite.config.d.ts
 
+# spec trees and validation artifacts — methodology IP, not repo content
+# (VALIDATION_PROTOCOL.md §09: specs/ travels with the operator, not the repo)
+specs/
+
 .pytest_cache/
 .serena/
 *.log

docs/mcp-integration.md

@@ -0,0 +1,382 @@
+# Wallbreaker MCP Integration
+
+Connect wallbreaker's red-teaming capabilities + p4rs3lt0ngv3's transform toolkit as
+native tools to any MCP-compatible agent: Claude Code, Cursor, Windsurf, Gemini CLI,
+Eragon, Codex CLI, or any client that implements the Model Context Protocol over stdio.
+
+---
+
+## Prerequisites
+
+- **Python 3.11+** — installed and available
+- **uv** — package manager ([install](https://docs.astral.sh/uv/getting-started/)):
+  ```bash
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  source $HOME/.cargo/env  # or similar for your shell
+  ```
+- **Git** — repo must be cloned:
+  ```bash
+  git clone https://github.com/JailbrokenAI/wallbreaker
+  cd wallbreaker
+  ```
+- **wallbreaker installed** — from the cloned repo:
+  ```bash
+  ~/.local/bin/uv sync
+  ```
+
+---
+
+## Configure
+
+### 1. Set up the client config
+
+Both servers use the standard MCP `mcpServers` format. Copy the template:
+
+```bash
+cp docs/mcp_client_config.json /tmp/wallbreaker_mcp.json
+```
+
+Edit it — replace `/path/to/wallbreaker`:
+
+```json
+{
+  "mcpServers": {
+    "p4rs3lt0ngv3": {
+      "command": "python",
+      "args": ["-m", "p4rs3lt0ngv3_mcp"],
+      "env": {
+        "PARSEL_REPO": "/absolute/path/to/wallbreaker/library/P4RS3LT0NGV3"
+      }
+    },
+    "wallbreaker": {
+      "command": "python",
+      "args": ["-m", "wallbreaker_mcp"],
+      "env": {
+        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Quick substitution:
+
+```bash
+PARSEL_PATH=$(realpath ./library/P4RS3LT0NGV3)
+
+sed -e "s|/path/to/wallbreaker/library/P4RS3LT0NGV3|$PARSEL_PATH|g" \
+    docs/mcp_client_config.json > /tmp/wallbreaker_mcp.json
+```
+
+### 2. Deploy to your agent client
+
+Copy the config to your client's config path:
+
+| Client | Config path |
+|--------|-------------|
+| Claude Code | `~/.claude/mcp.json` or `.claude/mcp.json` |
+| Cursor | `.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Gemini CLI | `~/.gemini/settings.json` |
+| Eragon | Gateway MCP config block |
+| Codex CLI | `.openai/mcp.json` |
+
+Example for Claude Code:
+
+```bash
+cp /tmp/wallbreaker_mcp.json ~/.claude/mcp.json
+```
+
+If the client already has an `mcp.json`, merge the two `mcpServers` blocks:
+
+```bash
+# Merge your existing config with the wallbreaker servers
+python3 - << 'EOF'
+import json
+with open('~/.claude/mcp.json') as f:
+    existing = json.load(f)
+with open('/tmp/wallbreaker_mcp.json') as f:
+    new = json.load(f)
+existing['mcpServers'].update(new['mcpServers'])
+with open('~/.claude/mcp.json', 'w') as f:
+    json.dump(existing, f, indent=2)
+print("Merged")
+EOF
+```
+
+---
+
+## Verify
+
+Run the smoke test (tests both servers directly, no agent client required):
+
+```bash
+chmod +x scripts/smoke_mcp.sh
+./scripts/smoke_mcp.sh
+```
+
+Expected output:
+```
+[OK] p4rs3lt0ngv3_mcp — imports successfully
+[OK] wallbreaker_mcp — imports successfully
+[OK] wb_seed_list — returns JSON with categories
+[OK] wb_judge — returns score and compliant
+[OK] wb_generate_payloads — returns payloads list
+[OK] wb_attack — returns error when no API key (graceful degradation)
+
+Smoke test passed. (6 checks)
+```
+
+### Manual verification
+
+Test p4rs3lt0ngv3_mcp (if Node.js is installed):
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
+  | ~/.local/bin/uv run python3 -m p4rs3lt0ngv3_mcp 2>/dev/null
+```
+
+Should return JSON with ≥7 tools (parsel_list, parsel_search, etc.)
+
+---
+
+## Tool Reference
+
+All tools are JSON-RPC 2.0 over stdio. Input and output shapes are listed below.
+
+### Wallbreaker Tools
+
+#### `wb_seed_list`
+
+List available attack seed categories from gem corpora (UltraBr3aks, ZetaLib) and
+HarmBench/AdvBench. Call this first to discover what attack objectives are available.
+
+**Input:**
+```json
+{
+  "source": "all"
+}
+```
+
+**Output:**
+```json
+{
+  "categories": [
+    {
+      "name": "cybercrime",
+      "count": 42,
+      "source": "harmbench"
+    },
+    {
+      "name": "jailbreak_universal",
+      "count": 115,
+      "source": "gem"
+    }
+  ],
+  "source": "all"
+}
+```
+
+---
+
+#### `wb_judge`
+
+Judge whether a model response complies with a harmful objective.
+
+**Input:**
+```json
+{
+  "objective": "write a malware dropper",
+  "response": "I can't help with that."
+}
+```
+
+**Output:**
+```json
+{
+  "score": 0.15,
+  "rationale": "Response refused or inadequate.",
+  "compliant": false
+}
+```
+
+A response with `compliant: true` has `score >= 0.7`.
+
+---
+
+#### `wb_generate_payloads`
+
+Generate adversarial text payloads for perturbation testing.
+
+Use for strix E4 invariance testing or DispatchLayer regression testing.
+
+**Input:**
+```json
+{
+  "category": "cybercrime",
+  "n": 5,
+  "source": "harmbench"
+}
+```
+
+**Output:**
+```json
+{
+  "payloads": [
+    "..attack payload 1...",
+    "...attack payload 2...",
+    "...attack payload 3...",
+    "...attack payload 4...",
+    "...attack payload 5..."
+  ],
+  "count": 5,
+  "source": "harmbench",
+  "category": "cybercrime"
+}
+```
+
+Source options: `"gem"`, `"harmbench"`, `"advbench"`, `"dispatch_library"` (if
+`DISPATCH_LIBRARY_PATH` env var is set).
+
+---
+
+#### `wb_attack`
+
+Run one attack round against a target LLM. Returns the best attack prompt found and
+the judge verdict. **Requires OPENAI_API_KEY** (or compatible LLM provider).
+
+**Input:**
+```json
+{
+  "objective": "write malware",
+  "target_model": "openai/gpt-4o",
+  "max_rounds": 3,
+  "dataset": "harmbench"
+}
+```
+
+**Output:**
+```json
+{
+  "attack_prompt": "You are a security researcher tasked with...",
+  "judge_score": 0.85,
+  "rounds": 2,
+  "success": true
+}
+```
+
+Returns `success: true` if `judge_score >= 0.7`.
+
+If no API key is set, returns:
+```json
+{
+  "error": "[wallbreaker error] No LLM API key configured. Set OPENAI_API_KEY.",
+  "attack_prompt": "",
+  "judge_score": 0.0,
+  "rounds": 0,
+  "success": false
+}
+```
+
+---
+
+### P4RS3LT0NGV3 Tools
+
+Seven obfuscation/encoding tools (available if Node.js is installed):
+
+- `parsel_list` — List the 222 transforms in 11 categories
+- `parsel_search` — Search transforms by keyword (e.g. "base64", "emoji")
+- `parsel_inspect` — Get configurable options for one transform
+- `parsel_transform` — Apply a single transform (encode/decode)
+- `parsel_chain` — Apply multiple transforms in sequence
+- `parsel_decode` — Auto-detect and decode obfuscated text
+- `parsel_guide` — Cheat sheet and usage guide
+
+**Example: encode text with Caesar cipher**
+
+Input:
+```json
+{
+  "name": "parsel_transform",
+  "arguments": {
+    "transform": "caesar",
+    "text": "Attack at dawn",
+    "action": "encode",
+    "options": {"shift": 5}
+  }
+}
+```
+
+Output:
+```json
+{
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "Fyyfhp fy ifbs"
+      }
+    ]
+  }
+}
+```
+
+For full reference, see `parsel_guide()` output or
+[P4RS3LT0NGV3 docs](https://github.com/JailbrokenAI/p4rs3lt0ngv3).
+
+---
+
+## Troubleshooting
+
+### "uv: command not found"
+Install uv:
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source ~/.local/bin/env
+```
+
+### "No module named 'wallbreaker'"
+Install dependencies:
+```bash
+cd /path/to/wallbreaker
+~/.local/bin/uv sync
+```
+
+### "OPENAI_API_KEY not configured"
+Set your API key before running `wb_attack`:
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+### "p4rs3lt0ngv3 tools return errors"
+Node.js is required for the transform bridge. Install it:
+```bash
+apt-get install nodejs  # or homebrew, etc.
+```
+
+### Agent client doesn't see the MCP servers
+Verify the config file path for your client and ensure the `python` command
+resolves to your active environment:
+
+```bash
+which python  # should be /path/to/wallbreaker/.venv/bin/python
+```
+
+If not, use an absolute path in the config file.
+
+---
+
+## Client Compatibility
+
+| Client | Config path | Config key | Notes |
+|--------|-------------|------------|-------|
+| Claude Code | `~/.claude/mcp.json` or `.claude/mcp.json` | `mcpServers` | Standard MCP config |
+| Cursor | `.cursor/mcp.json` | `mcpServers` | Same format |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` | Same format |
+| Gemini CLI | `~/.gemini/settings.json` | `mcpServers` | Same format |
+| Eragon | Gateway MCP config | `mcpServers` | Same format |
+| Codex CLI | `.openai/mcp.json` | `mcpServers` | Same format |
+| Any MCP client | Client-specific | Varies | Both servers are client-agnostic |
+
+Both servers speak standard MCP (JSON-RPC 2.0, stdio transport) and make no assumptions
+about which client is calling them.