air-blackbox-mcp

AIR Blackbox MCP 服务

面向 Claude Desktop、Claude Code、Cursor 和任何兼容 MCP 的客户端进行欧盟《人工智能法案》合规扫描。

与其他只报告问题的合规扫描工具不同，AIR Blackbox 还会修复问题——生成可运行的代码修复方案、信任层集成、GDPR 合规检查、偏见分析和完整的合规报告。在底层，扫描结果会送入 air-trust：一种加密审计链（HMAC-SHA256），采用 Ed25519 签名交接，确保合规数据的完整性。

14 个工具（10 个基础工具 + 4 个由 SDK 提供支持的工具）

层级	工具	功能	是否需要 SDK
扫描	scan_code	扫描代码字符串，检查欧盟《人工智能法案》的全部 6 项条款（安装 SDK 后支持 Python、notebook、TypeScript、JavaScript、Java、Kotlin；未安装时仅支持 Python）	建议安装
扫描	scan_file	读取并扫描单个源文件	建议安装
扫描	scan_project	递归扫描项目目录	建议安装
分析	analyze_with_model	通过本地微调模型（Ollama）进行深度分析	否
分析	check_injection	检测提示词注入攻击（15 种模式）	否
分析	classify_risk	按欧盟《人工智能法案》的风险等级对工具进行分类	否
修复	add_trust_layer	生成信任层集成代码	否
修复	suggest_fix	获取针对具体条款的修复建议	否
文档	explain_article	对欧盟《人工智能法案》条款进行技术说明	否
文档	generate_compliance_report	生成完整的 Markdown 合规报告	否
GDPR	scan_gdpr	GDPR 专项合规扫描	是
偏见	scan_bias	偏见与公平性分析	是
验证	validate_action	在执行前验证 Agent 操作（第 14 条）	是
历史	compliance_history	查看以往扫描、趋势和合规评分	是

支持的框架

LangChain、CrewAI、AutoGen、OpenAI、Haystack、LlamaIndex、Semantic Kernel、Google ADK、Claude Agent SDK 和通用 RAG 工作流。

安装

推荐（14 个工具，支持所有语言）

pip install air-blackbox-mcp[full]

安装 air-blackbox SDK（>=1.17,<2）。随后，扫描工具会运行与 air-blackbox CLI 相同的引擎，并读取 Python、Jupyter notebook、TypeScript、JavaScript、Java 和 Kotlin；对于相同代码，判定结果也与 CLI 一致。此最低版本是本包经过测试的版本，而主版本上限可避免 2.x SDK 悄然改变扫描结果。

基础（10 个工具，仅支持 Python）

pip install air-blackbox-mcp

可独立运行，使用轻量级内置扫描器：仅支持 Python 文件，规则集也较小。

MCP SDK 兼容性（mcp 2.0）

本包同时支持两代 MCP SDK——mcp>=1.0，无上限。

mcp 2.0 移除了 mcp.server.fastmcp，并以 MCPServer 替代了 FastMCP。本服务不会通过固定版本来规避这一变化，而是会检测已安装的版本并绑定到相应的类，因此可同时运行于 1.x 和 2.x：

已安装版本	服务类
mcp 1.x	FastMCP
mcp 2.x	MCPServer

两种路径均经过测试：测试会启动 python -m air_blackbox_mcp 作为真实子进程，并通过 stdio 与其交互——这与 Claude Desktop 和 Cursor 的工作方式相同；完整测试套件在两个版本上都能通过。

如果你使用的是 0.2.3，请升级。 该版本声明了未固定版本上限的 mcp>=1.0.0，因此 mcp 2.0 发布后，每次全新安装都会生成一个在导入时崩溃的服务：

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

pip install --upgrade air-blackbox-mcp

0.2.4 通过将上限设为 mcp<2 修复了此问题；0.3.0 则彻底移除了上限，因此本服务不再与共享同一环境中的任何基于 mcp 2.x 构建的组件发生冲突。

Claude Desktop 设置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "air-blackbox": {
      "command": "python3",
      "args": ["-m", "air_blackbox_mcp"]
    }
  }
}

重启 Claude Desktop。14 个工具将自动显示。

Claude Code / Cursor 配置

将以下内容添加到项目的 .cursor/mcp.json 中：

{
  "mcpServers": {
    "air-blackbox": {
      "command": "python3",
      "args": ["-m", "air_blackbox_mcp"]
    }
  }
}

或者，为 Claude Code 添加到 .claude/mcp.json 中。

使用示例

在 Claude Desktop、Claude Code 或 Cursor 中，直接询问：

• “扫描此代码，检查是否符合 EU AI Act”
• “为此 LangChain Agent 添加信任层”
• “检查此文本是否存在提示词注入”
• “第 12 条有什么要求？”
• “为 ~/myproject 生成合规报告”
• “对 send_email 的风险级别进行分类”
• “扫描此代码，检查是否存在 GDPR 问题”（需要完整 SDK）
• “检查此 AI 模型代码是否存在偏见”（需要完整 SDK）
• “我的 Agent 能调用此 shell 函数吗？”（需要完整 SDK）
• “显示我的合规趋势”（需要完整 SDK）

SDK 功能（可选）

完整的 air-blackbox SDK 可解锁另外 4 种工具：

1. GDPR 扫描（scan_gdpr）

   • 未经同意处理个人数据
   • 数据保留和删除政策
   • 跨境传输保障措施
   • 数据处理协议

2. 偏见分析（scan_bias）

   • 检测差别影响风险
   • 处理受保护属性
   • 训练数据偏见指标
   • 公平性指标意识

3. 操作验证（validate_action）

   • 执行前审批关卡（第 14 条）
   • ConsentGate 政策执行
   • 基于风险的操作筛选
   • 生成审计跟踪

4. 合规历史记录（compliance_history）

   • 跟踪过去的扫描结果
   • 分析合规趋势
   • 导出审计跟踪
   • 监控随时间的改进情况

可选：使用 Ollama 进行深度分析

如需超越正则表达式模式的 AI 驱动分析：

# Install Ollama
brew install ollama

# Pull the fine-tuned compliance model
ollama pull air-compliance-v2

# The analyze_with_model tool will automatically use it

与众不同之处

其他 MCP 合规工具只能扫描。AIR Blackbox：

1. 扫描并修复——检查 6 项 EU AI Act 条款中的问题，并生成可用的代码修复方案
2. 深入分析——结合正则表达式模式、AI 驱动的模型分析和提示词注入检测（15 种模式）
3. 执行前验证——为 Agent 操作提供预审批关卡和风险分类（第 14 条）
4. 跟踪合规情况——提供 GDPR 检查、偏见分析、完整报告和历史趋势监控（SDK）

架构

运行哪个引擎由已安装的组件决定，并在导入时确定一次；每个结果都会注明所用引擎。 在 0.4.0 之前，即使已安装 SDK，扫描工具也始终使用内置扫描器；两者逐渐出现差异（内置扫描器的检查项更少、仅支持 Python，而且 SDK 已修复的招聘检测错误仍然存在），导致相同代码在 CLI 和 Claude 中得到不同的判定结果。

工具	引擎	缺少 SDK 时
scan_code、scan_file、scan_project（以及 analyze_with_model 中基于规则的部分）	如果已安装，则使用 air-blackbox SDK；否则使用内置的基于规则的扫描器	内置扫描器：仅支持 Python，规则集较小
check_injection、classify_risk	始终使用内置规则	不受影响
Tier 5（scan_gdpr、scan_bias、validate_action、compliance_history）	始终使用完整的 air-blackbox SDK	明确报错并提示安装 [full]

该选择在服务启动时确定，不会针对每次调用重新选择；每个结果都会通过 provenance.engine 标明引擎，因此只有 engine 和 ruleset_version 相同时，两份报告才可直接比较。

结果溯源

只有了解结果的产生方式，合规检查结果才具有可比性。因此，每个机器可读结果都包含一个 provenance 块：

{
  "findings": [ ... ],
  "provenance": {
    "engine": "builtin-rules",
    "scanner_version": "0.2.4",
    "ruleset_id": "eu-ai-act-art9-15",
    "ruleset_version": "cee71577c486",
    "sdk_version": null
  }
}

• engine — 实际运行的引擎：builtin-rules 或 air-blackbox-sdk。
• ruleset_version — 当前规则的内容哈希，而不是人工维护的字符串。修改正则表达式后，哈希会自动变化；必须由人记得更新的版本号，最终总会错误地报告实际运行的规则。
• sdk_version — 生成此结果的 SDK，因此内置规则的结果中为 null，即使同时安装了 SDK 也是如此。报告一个毫无贡献的版本，会让人误以为它的规则曾参与运行。

如果两份报告的 engine 和 ruleset_version 相同，则它们由字节级完全相同的规则生成，可以直接比较差异。值不同则表示规则发生了变化；要让差异有意义，就需要了解相关背景。

错误也会包含溯源信息——了解哪个版本生成了错误，与了解哪个版本生成了检查结果同样有用。

安装 [full] 即可启用 Tier 5 SDK 工具；基础安装可独立运行。

AIR Blackbox 的组成部分

此 MCP 服务属于 AIR Blackbox 生态系统：

• PyPI 上的 air-trust (PyPI) — 为合规扫描提供支持的加密审计链
• PyPI 上的 air-blackbox (PyPI) — 完整的合规 SDK 和 CLI 扫描器
• airblackbox.ai — 项目主页和文档

链接

• EU AI Act — 相关法规
• GDPR — 数据保护法规