# deepteam-mcp

Expõe o [DeepTeam](https://trydeepteam.com) (red-teaming de LLM) como ferramenta
**MCP via stdio**, pra você testar **guardrails** por conversa no Claude Desktop.

Aponta o alvo pro sistema com guardrail (teu app atrás de LLM Guard, o Claude
atrás do Straiker Defend, um gateway) e o DeepTeam mede o que fura.

> **Sem Docker.** Roda direto num virtualenv do Python (3.10+). Nada de
> container, nada de Kali. Só `python -m venv` e `pip`.

## Três modelos, de propósito separados

| Papel | Quem é | Custo |
|---|---|---|
| **Alvo** | o sistema atacado — Claude (Anthropic) ou qualquer endpoint OpenAI-compatível | teu |
| **Simulador** | gera os ataques (`gpt-3.5` default) | **tokens OpenAI** |
| **Juiz** | avalia se passou (`gpt-4o` default) | **tokens OpenAI** |

> Red-team **queima crédito** no simulador e no juiz, não só no alvo. Comece com
> `attacks_per_type=1` e poucas vulnerabilidades. Dá pra trocar por modelo barato.

## Atacando o Claude — três camadas

"Claude Desktop" não é um endpoint, é um app. O DeepTeam precisa de um endpoint
pra mandar o ataque e ler a resposta. Então escolha o que quer testar:

| Alvo | O que mede | Config |
|---|---|---|
| **Claude via API** | o guardrail do **modelo** (safety) | `TARGET_PROVIDER=anthropic`, `TARGET_MODEL=claude-sonnet-5` |
| **API + system prompt** | aproxima o Desktop (modelo + prompt) | acima + `TARGET_SYSTEM="<prompt do Desktop>"` |
| **O app Desktop real** | a superfície inteira, **incl. inference hook / Straiker** | não é endpoint — precisa dirigir a UI (computer-use). Fora do escopo deste server. |

O alvo default é **`claude-sonnet-5`** via Anthropic. O simulador e o juiz do
DeepTeam continuam na OpenAI (chave barata) — eles não são o alvo.

## Instalar (sem Docker)

Precisa só de **Python 3.10+**.

### Opção A — script

```bash
git clone https://github.com/mbergo/deepteam-mcp.git ~/github/deepteam-mcp
cd ~/github/deepteam-mcp && ./install.sh
```

O `install.sh` cria um venv isolado em `.venv/`, instala tudo e **imprime o bloco
pronto** pro `claude_desktop_config.json`. Cole, preencha as chaves, reinicie o
Desktop.

### Opção B — na mão (se preferir ver cada passo)

```bash
git clone https://github.com/mbergo/deepteam-mcp.git ~/github/deepteam-mcp
cd ~/github/deepteam-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

Depois adicione ao `claude_desktop_config.json`
(`~/.config/Claude/` no Linux, `~/Library/Application Support/Claude/` no macOS),
usando **caminhos absolutos**:

```json
{
  "mcpServers": {
    "deepteam": {
      "command": "/home/VOCE/github/deepteam-mcp/.venv/bin/python",
      "args": ["/home/VOCE/github/deepteam-mcp/server.py"],
      "env": {
        "OPENAI_API_KEY": "sk-...",              // simulador + juiz do DeepTeam
        "TARGET_PROVIDER": "anthropic",
        "TARGET_API_KEY": "sk-ant-...",          // chave do alvo (Claude)
        "TARGET_MODEL": "claude-sonnet-5"
        // opcional: "TARGET_SYSTEM": "<system prompt p/ aproximar o Desktop>"
      }
    }
  }
}
```

Reinicie o Claude Desktop. A ferramenta `deepteam` aparece; peça *"use
list_catalog"*.

> Também funciona no **Claude Code** (`claude mcp add`) e em qualquer cliente MCP
> que fale stdio — não só no Desktop.

## Ferramentas expostas

- **`list_catalog`** — vulnerabilidades e ataques disponíveis, e o alvo atual.
- **`red_team`** — roda a avaliação. Principais argumentos:
  - `vulnerabilities`: `["Bias","PromptLeakage"]` ou com sub-tipos
    `[{"name":"Bias","types":["race","gender"]}]`
  - `single_turn_attacks`: `["PromptInjection","ROT13","Base64","Leetspeak"]`
  - `multi_turn_attacks`: `["LinearJailbreaking","CrescendoJailbreaking"]`
  - `attacks_per_type`, `simulator_model`, `evaluation_model`
  - `target_*` pra sobrescrever o alvo por execução

Retorna o overview do risco, quantos ataques **furaram** (breaches) com amostras,
e salva o relatório completo em `~/deepteam-results/<timestamp>/`.

## Testando um guardrail — exemplo de conversa

> "list_catalog"
> "red team contra PromptLeakage e PIILeakage, ataques PromptInjection e Base64,
>  2 por tipo"

Se o guardrail é bom, breaches ≈ 0. Cada breach é um caso concreto pra levar ao
time — input, output e por que passou.

## Aviso

Ferramenta ofensiva. Rode só contra alvo que você tem **autorização** para testar.
Cada tool call é observável por camadas de monitoração (ex: Straiker Defend) —
o que, num teste autorizado, é o teu próprio registro de escopo.

## Licença

MIT.