{ "markdown": "\n# AIR Blackbox MCP Server\n\n

\n \"AIR\n

\n\nEU AI Act compliance scanning for **Claude Desktop**, **Claude Code**, **Cursor**, and any MCP-compatible client.\n\nUnlike other compliance scanners that only report problems, AIR Blackbox also **remediates** - generating working code fixes, trust layer integrations, GDPR compliance checks, bias analysis, and full compliance reports. Under the hood, the scanning feeds into **air-trust**, a cryptographic audit chain (HMAC-SHA256) with Ed25519 signed handoffs that ensures compliance data integrity.\n\n## 14 Tools (10 base + 4 SDK-powered)\n\n| Tier | Tool | What it does | Requires SDK |\n|------|------|-------------|---|\n| Scanning | `scan_code` | Scan Python code string for all 6 EU AI Act articles | No |\n| Scanning | `scan_file` | Read and scan a single Python file | No |\n| Scanning | `scan_project` | Recursively scan all .py files in a directory | No |\n| Analysis | `analyze_with_model` | Deep analysis via local fine-tuned model (Ollama) | No |\n| Analysis | `check_injection` | Detect prompt injection attacks (15 patterns) | No |\n| Analysis | `classify_risk` | Classify tools by EU AI Act risk level | No |\n| Remediation | `add_trust_layer` | Generate trust layer integration code | No |\n| Remediation | `suggest_fix` | Get article-specific fix recommendations | No |\n| Documentation | `explain_article` | Technical explanation of EU AI Act articles | No |\n| Documentation | `generate_compliance_report` | Full markdown compliance report | No |\n| GDPR | `scan_gdpr` | GDPR-specific compliance scan | Yes |\n| Bias | `scan_bias` | Bias and fairness analysis | Yes |\n| Validation | `validate_action` | Validate agent actions before execution (Article 14) | Yes |\n| History | `compliance_history` | View past scans, trends, and compliance scores | Yes |\n\n## Supported Frameworks\n\nLangChain, CrewAI, AutoGen, OpenAI, Haystack, LlamaIndex, Semantic Kernel, Google ADK, Claude Agent SDK, and generic RAG pipelines.\n\n## Installation\n\n### Basic (10 tools, no SDK features)\n\n```bash\npip install air-blackbox-mcp\n```\n\nWorks standalone with just the lightweight built-in scanner.\n\n### Full (14 tools with GDPR, bias, validation, and history)\n\n```bash\npip install air-blackbox-mcp[full]\n```\n\nInstalls the full `air-blackbox` SDK (`>=1.13,<2`) for advanced compliance\nfeatures. The floor is the version this package is tested against, and the\nmajor cap means a 2.x SDK cannot silently change your findings.\n\n## MCP SDK compatibility (mcp 2.0)\n\n**This package supports both MCP SDK generations — `mcp>=1.0`, no upper bound.**\n\nmcp 2.0 removed `mcp.server.fastmcp` and replaced `FastMCP` with `MCPServer`.\nRather than pin away from it, the server detects which generation is installed\nand binds to the right class, so it runs on 1.x and 2.x alike:\n\n| installed | server class |\n|---|---|\n| `mcp` 1.x | `FastMCP` |\n| `mcp` 2.x | `MCPServer` |\n\nBoth paths are covered by tests that launch `python -m air_blackbox_mcp` as a\nreal subprocess and drive it over stdio — the same way Claude Desktop and\nCursor do — and the full suite runs green on both.\n\n**If you are on 0.2.3, upgrade.** That version declared an unpinned\n`mcp>=1.0.0`, so once mcp 2.0 shipped, every fresh install produced a server\nthat died on import:\n\n```\nModuleNotFoundError: No module named 'mcp.server.fastmcp'\n```\n\n```bash\npip install --upgrade air-blackbox-mcp\n```\n\n0.2.4 fixed it by capping at `mcp<2`; 0.3.0 removes the cap entirely, so this\nserver no longer conflicts with anything built for mcp 2.x sharing the same\nenvironment.\n\n## Claude Desktop Setup\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"air-blackbox\": {\n \"command\": \"python3\",\n \"args\": [\"-m\", \"air_blackbox_mcp\"]\n }\n }\n}\n```\n\nRestart Claude Desktop. The 14 tools will appear automatically.\n\n## Claude Code / Cursor Setup\n\nAdd to `.cursor/mcp.json` in your project:\n\n```json\n{\n \"mcpServers\": {\n \"air-blackbox\": {\n \"command\": \"python3\",\n \"args\": [\"-m\", \"air_blackbox_mcp\"]\n }\n }\n}\n```\n\nOr add to `.claude/mcp.json` for Claude Code.\n\n## Usage Examples\n\nIn Claude Desktop, Claude Code, or Cursor, just ask:\n\n- \"Scan this code for EU AI Act compliance\"\n- \"Add a trust layer to this LangChain agent\"\n- \"Check this text for prompt injection\"\n- \"What does Article 12 require?\"\n- \"Generate a compliance report for ~/myproject\"\n- \"Classify the risk level of `send_email`\"\n- \"Scan this code for GDPR issues\" (requires full SDK)\n- \"Check for bias in this AI model code\" (requires full SDK)\n- \"Can my agent call this shell function?\" (requires full SDK)\n- \"Show me my compliance trends\" (requires full SDK)\n\n## SDK Features (Optional)\n\nThe full `air-blackbox` SDK unlocks 4 additional tools:\n\n1. **GDPR Scanning** (`scan_gdpr`)\n - Personal data handling without consent\n - Data retention and erasure policies\n - Cross-border transfer safeguards\n - Data processing agreements\n\n2. **Bias Analysis** (`scan_bias`)\n - Disparate impact risk detection\n - Protected attribute handling\n - Training data bias indicators\n - Fairness metric awareness\n\n3. **Action Validation** (`validate_action`)\n - Pre-execution approval gates (Article 14)\n - ConsentGate policy enforcement\n - Risk-based action filtering\n - Audit trail generation\n\n4. **Compliance History** (`compliance_history`)\n - Track past scan results\n - Analyze compliance trends\n - Export audit trails\n - Monitor improvement over time\n\n## Optional: Deep Analysis with Ollama\n\nFor AI-powered analysis beyond regex patterns:\n\n```bash\n# Install Ollama\nbrew install ollama\n\n# Pull the fine-tuned compliance model\nollama pull air-compliance-v2\n\n# The analyze_with_model tool will automatically use it\n```\n\n## What Makes This Different\n\nOther MCP compliance tools only scan. AIR Blackbox:\n\n1. **Scans + Remediates** - finds issues across 6 EU AI Act articles AND generates working code fixes\n2. **Analyzes deeply** - regex patterns + AI-powered model analysis + prompt injection detection (15 patterns)\n3. **Validates before execution** - pre-approval gates and risk classification for agent actions (Article 14)\n4. **Tracks compliance** - GDPR checks, bias analysis, full reports, and historical trend monitoring (SDK)\n\n## Architecture\n\n**Which engine runs is fixed per tool, not a runtime fallback.** Earlier versions\nof this README described a \"try the SDK first, fall back to built-in\" pattern.\nThat was never what the code did, and it mattered: a reader could not tell\nwhether two reports came from the same rules. The actual behavior:\n\n| Tools | Engine | If the SDK is missing |\n|---|---|---|\n| Tiers 1–4 (`scan_code`, `scan_file`, `scan_project`, `check_injection`, `classify_risk`, …) | Always the built-in rule-based scanner | No effect — these never use the SDK |\n| Tier 5 (`scan_gdpr`, `scan_bias`, `validate_action`, `compliance_history`) | Always the full `air-blackbox` SDK | Explicit error telling you to install `[full]` |\n\nSo a given tool produces results from the same engine on every install, and\nthere is no silent switch between engines.\n\n### Result provenance\n\nBecause a compliance finding is only comparable to another if you know what\nproduced it, **every machine-readable result carries a `provenance` block**:\n\n```json\n{\n \"findings\": [ ... ],\n \"provenance\": {\n \"engine\": \"builtin-rules\",\n \"scanner_version\": \"0.2.4\",\n \"ruleset_id\": \"eu-ai-act-art9-15\",\n \"ruleset_version\": \"cee71577c486\",\n \"sdk_version\": null\n }\n}\n```\n\n- `engine` — `builtin-rules` or `air-blackbox-sdk`, whichever actually ran.\n- `ruleset_version` — a content hash of the active rules, not a hand-maintained\n string. Change a regex and it changes by itself; a version someone must\n remember to bump is one that eventually misreports which rules ran.\n- `sdk_version` — the SDK that *produced* this result, so it is `null` for\n built-in results even when the SDK is installed alongside. Reporting a\n version that contributed nothing would imply its rules ran.\n\nTwo reports with the same `engine` + `ruleset_version` were produced by\nbyte-identical rules and can be diffed directly. Different values mean the\nrules moved, and the diff needs that context to be meaningful.\n\nErrors carry provenance too — knowing which version produced an error is as\nuseful as knowing which version produced a finding.\n\nInstall `[full]` to unlock the Tier 5 SDK tools; the base install works\nstandalone.\n\n## Part of AIR Blackbox\n\nThis MCP server is part of the **AIR Blackbox ecosystem**:\n\n- **air-trust** on [PyPI](https://pypi.org/project/air-trust/) - the cryptographic audit chain that backs compliance scanning\n- **air-blackbox** on [PyPI](https://pypi.org/project/air-blackbox/) - the full compliance SDK and CLI scanner\n- **[airblackbox.ai](https://airblackbox.ai)** - the project homepage and docs\n\n## Links\n\n- [EU AI Act](https://eur-lex.europa.eu/eli/reg/2024/1689/oj) - the regulation\n- [GDPR](https://gdpr-info.eu/) - data protection regulation\n", "bytes": 9107, "sha": "0298b6550a11f143909f349fcb3c5b8ab6ecc0836043005700be95b835ff462f", "repo_slug": "airblackbox/air-blackbox-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_shotwellj_air_blackbox_82ea7fce/readme" }