AIR Blackbox

Servidor MCP AIR Blackbox

Varredura de conformidade com o AI Act da UE para Claude Desktop, Claude Code, Cursor e qualquer cliente compatível com MCP.

Diferente de outros scanners de conformidade que apenas relatam problemas, o AIR Blackbox também remedia — gerando correções de código funcionais, integrações de camada de confiança, verificações de conformidade com GDPR, análise de viés e relatórios completos de conformidade. Por baixo dos panos, a varredura alimenta o air-trust, uma cadeia de auditoria criptográfica (HMAC-SHA256) com transferências assinadas por Ed25519 que garante a integridade dos dados de conformidade.

14 Ferramentas (10 básicas + 4 com SDK)

Nível	Ferramenta	O que faz	Requer SDK
Varredura	scan_code	Escanear string de código Python para todos os 6 artigos do AI Act da UE	Não
Varredura	scan_file	Ler e escanear um único arquivo Python	Não
Varredura	scan_project	Escanear recursivamente todos os arquivos .py em um diretório	Não
Análise	analyze_with_model	Análise profunda via modelo local ajustado (Ollama)	Não
Análise	check_injection	Detectar ataques de injeção de prompt (15 padrões)	Não
Análise	classify_risk	Classificar ferramentas pelo nível de risco do AI Act da UE	Não
Remediação	add_trust_layer	Gerar código de integração de camada de confiança	Não
Remediação	suggest_fix	Obter recomendações de correção específicas por artigo	Não
Documentação	explain_article	Explicação técnica dos artigos do AI Act da UE	Não
Documentação	generate_compliance_report	Relatório completo de conformidade em markdown	Não
GDPR	scan_gdpr	Varredura de conformidade específica para GDPR	Sim
Viés	scan_bias	Análise de viés e imparcialidade	Sim
Validação	validate_action	Validar ações do agente antes da execução (Artigo 14)	Sim
Histórico	compliance_history	Visualizar varreduras passadas, tendências e pontuações de conformidade	Sim

Frameworks Suportados

LangChain, CrewAI, AutoGen, OpenAI, Haystack, LlamaIndex, Semantic Kernel, Google ADK, Claude Agent SDK e pipelines RAG genéricos.

Instalação

Básico (10 ferramentas, sem recursos do SDK)

pip install air-blackbox-mcp

Funciona de forma autônoma apenas com o scanner leve integrado.

Completo (14 ferramentas com GDPR, viés, validação e histórico)

pip install air-blackbox-mcp[full]

Instala o SDK completo do air-blackbox (>=1.13,<2) para recursos avançados de conformidade. O mínimo é a versão testada com este pacote, e o limite máximo significa que um SDK 2.x não pode alterar silenciosamente seus resultados.

Compatibilidade com o SDK MCP (mcp 2.0)

Este pacote suporta ambas as gerações do SDK MCP — mcp>=1.0, sem limite superior.

O mcp 2.0 removeu mcp.server.fastmcp e substituiu FastMCP por MCPServer. Em vez de fixar a versão antiga, o servidor detecta qual geração está instalada e se liga à classe correta, rodando tanto na 1.x quanto na 2.x:

instalado	classe do servidor
mcp 1.x	FastMCP
mcp 2.x	MCPServer

Ambos os caminhos são cobertos por testes que lançam python -m air_blackbox_mcp como um subprocesso real e o controlam via stdio — da mesma forma que Claude Desktop e Cursor fazem — e a suíte completa roda verde em ambos.

Se você está na 0.2.3, atualize. Essa versão declarou um mcp>=1.0.0 sem fixação, então assim que o mcp 2.0 foi lançado, toda instalação nova produzia um servidor que morria no import:

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

pip install --upgrade air-blackbox-mcp

A 0.2.4 corrigiu limitando a mcp<2; a 0.3.0 remove o limite completamente, então este servidor não conflita mais com nada construído para mcp 2.x compartilhando o mesmo ambiente.

Configuração do Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Reinicie o Claude Desktop. As 14 ferramentas aparecerão automaticamente.

Configuração do Claude Code / Cursor

Adicione a .cursor/mcp.json no seu projeto:

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

Ou adicione a .claude/mcp.json para Claude Code.

Exemplos de Uso

No Claude Desktop, Claude Code ou Cursor, basta perguntar:

• "Escanear este código para conformidade com o AI Act da UE"
• "Adicionar uma camada de confiança a este agente LangChain"
• "Verificar este texto para injeção de prompt"
• "O que o Artigo 12 exige?"
• "Gerar um relatório de conformidade para ~/myproject"
• "Classificar o nível de risco de send_email"
• "Escanear este código para problemas de GDPR" (requer SDK completo)
• "Verificar viés neste código de modelo de IA" (requer SDK completo)
• "Meu agente pode chamar esta função de shell?" (requer SDK completo)
• "Mostrar minhas tendências de conformidade" (requer SDK completo)

Recursos do SDK (Opcional)

O SDK completo air-blackbox desbloqueia 4 ferramentas adicionais:

1. Varredura GDPR (scan_gdpr)

   • Tratamento de dados pessoais sem consentimento
   • Políticas de retenção e apagamento de dados
   • Salvaguardas para transferências transfronteiriças
   • Acordos de processamento de dados

2. Análise de Viés (scan_bias)

   • Detecção de risco de impacto desproporcional
   • Tratamento de atributos protegidos
   • Indicadores de viés em dados de treinamento
   • Consciência de métricas de imparcialidade

3. Validação de Ações (validate_action)

   • Portões de aprovação pré-execução (Artigo 14)
   • Aplicação de políticas ConsentGate
   • Filtragem de ações baseada em risco
   • Geração de trilha de auditoria

4. Histórico de Conformidade (compliance_history)

   • Rastrear resultados de varreduras passadas
   • Analisar tendências de conformidade
   • Exportar trilhas de auditoria
   • Monitorar melhoria ao longo do tempo

Opcional: Análise Profunda com Ollama

Para análise com IA além dos padrões regex:

# 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

O Que Torna Isso Diferente

Outras ferramentas MCP de conformidade apenas escaneiam. O AIR Blackbox:

1. Escaneia + Remedia — encontra problemas em 6 artigos do AI Act da UE E gera correções de código funcionais
2. Analisa profundamente — padrões regex + análise de modelo com IA + detecção de injeção de prompt (15 padrões)
3. Valida antes da execução — portões de pré-aprovação e classificação de risco para ações do agente (Artigo 14)
4. Rastreia conformidade — verificações GDPR, análise de viés, relatórios completos e monitoramento de tendências históricas (SDK)

Arquitetura

Qual motor é executado é fixo por ferramenta, não um fallback em tempo de execução. Versões anteriores deste README descreviam um padrão "tente o SDK primeiro, caia para o integrado". Isso nunca foi o que o código fazia, e importava: um leitor não conseguia dizer se dois relatórios vinham das mesmas regras. O comportamento real:

Ferramentas	Motor	Se o SDK estiver ausente
Níveis 1–4 (scan_code, scan_file, scan_project, check_injection, classify_risk, …)	Sempre o scanner integrado baseado em regras	Sem efeito — estes nunca usam o SDK
Nível 5 (scan_gdpr, scan_bias, validate_action, compliance_history)	Sempre o SDK completo air-blackbox	Erro explícito informando para instalar [full]

Portanto, uma determinada ferramenta produz resultados do mesmo motor em toda instalação, e não há troca silenciosa entre motores.

Proveniência dos resultados

Como uma descoberta de conformidade só é comparável a outra se você souber o que a produziu, todo resultado legível por máquina carrega um bloco 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 ou air-blackbox-sdk, o que realmente executou.
• ruleset_version — um hash de conteúdo das regras ativas, não uma string mantida manualmente. Mude um regex e ele muda sozinho; uma versão que alguém precisa lembrar de incrementar é uma que eventualmente relata incorretamente quais regras rodaram.
• sdk_version — o SDK que produziu este resultado, portanto é null para resultados integrados mesmo quando o SDK está instalado junto. Relatar uma versão que não contribuiu em nada implicaria que suas regras rodaram.

Dois relatórios com o mesmo engine + ruleset_version foram produzidos por regras byte-idênticas e podem ser comparados diretamente. Valores diferentes significam que as regras mudaram, e a comparação precisa desse contexto para ser significativa.

Erros também carregam proveniência — saber qual versão produziu um erro é tão útil quanto saber qual versão produziu uma descoberta.

Instale [full] para desbloquear as ferramentas SDK do Nível 5; a instalação básica funciona de forma autônoma.

Parte do AIR Blackbox

Este servidor MCP faz parte do ecossistema AIR Blackbox:

• air-trust no PyPI — a cadeia de auditoria criptográfica que sustenta a varredura de conformidade
• air-blackbox no PyPI — o SDK completo de conformidade e scanner CLI
• airblackbox.ai — a página inicial do projeto e documentação

Links

• AI Act da UE — o regulamento
• GDPR — regulamento de proteção de dados