# mcp-permaudit

Servidor MCP para auditar configuraciones de permisos de Claude Code
(`.claude/settings.json`).

Aplica la jerarquía **primitivas → custom → MCP**:

- `cli_bash.py` representa la opción primitiva (bash + Python).
- `audit.py` encapsula la lógica para reutilizarla como tool custom.
- `server.py` publica la capacidad como servidor MCP compartido.

## Instalación

```bash
cd mcp-permaudit
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Uso

### Servidor MCP

```bash
source .venv/bin/activate
python server.py
```

### Cliente de prueba

```bash
source .venv/bin/activate
python client_test.py
```

### CLI primitiva

```bash
source .venv/bin/activate
python cli_bash.py fixtures/settings-destructive.json
python cli_bash.py /ruta/a/.claude/settings.json
```

### Medir costo de contexto

```bash
source .venv/bin/activate
python measure_tokens.py
```

## Configuración en clientes MCP

### Claude Code

Copia o adapta `.claude/mcp.json` en tu proyecto o `~/.claude/mcp.json`.

### Claude Desktop

Copia `claude_desktop_config.json` como:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Actualiza la ruta absoluta a `server.py`.

## Decisiones de diseño

Ver `docs/decision.md` para la comparación completa:

- primitiva + ejecución de código
- tool custom local
- servidor MCP publicado

Incluye justificación de los cuatro criterios de MCP, costo de contexto medido,
caso real reescrito como bash+Python, uso de MCP existente (Playwright MCP) y
notas de seguridad/allowlist para producción.

## Herramienta expuesta

- `audit_settings(settings_json: str) -> dict`: audita el JSON de permisos y
  devuelve findings, summary, hasSettings, ruleCount y hasConflict.

## Estructura

```
mcp-permaudit/
├── audit.py                    # Lógica pura de auditoría
├── server.py                   # Servidor MCP (FunctionTool + stdio)
├── client_test.py              # Cliente MCP de prueba
├── cli_bash.py                 # Alternativa primitiva
├── measure_tokens.py           # Costo de contexto
├── fixtures/                   # JSON de ejemplo
├── docs/decision.md            # Comparativa y justificación
├── .claude/mcp.json            # Config para Claude Code
├── claude_desktop_config.json  # Config para Claude Desktop
└── requirements.txt
```