# mcp-postgres

Serveur **MCP (Model Context Protocol)** d'administration **PostgreSQL** — périmètre
**lecture + maintenance non destructive**. Conçu pour brancher un assistant (Claude
Code, Claude Desktop, IDE) sur une base afin de l'inspecter, la monitorer et lancer
des opérations de maintenance sûres, **sans jamais pouvoir écrire de données ni altérer
la structure**.

## Périmètre

| Autorisé | Interdit (aucun tool exposé) |
|----------|------------------------------|
| Introspection du schéma | `DROP`, `TRUNCATE`, `DELETE`, `UPDATE`, `INSERT` |
| Monitoring / activité / verrous | `ALTER SYSTEM`, gestion de rôles, `GRANT`/`REVOKE` |
| Statistiques & plans (`EXPLAIN`, sans `ANALYZE`) | `VACUUM FULL`, `pg_terminate_backend` |
| `SELECT` ad hoc borné (LIMIT forcé) | Tout SQL modifiant des données |
| `VACUUM` / `ANALYZE` / `REINDEX CONCURRENTLY` (opt-in) | |

## Défense en profondeur

1. **Rôle SQL à moindre privilège** ([deploy/roles/mcp_readonly_role.sql](deploy/roles/mcp_readonly_role.sql)) — rempart final.
2. **Séparation physique** des connexions lecture (READ ONLY) et maintenance ([src/mcp_postgres/db/session.py](src/mcp_postgres/db/session.py)).
3. **Validateur SQL** par vrai parseur (`pglast`), pas de regex ([src/mcp_postgres/db/guard.py](src/mcp_postgres/db/guard.py)).
4. Maintenance **opt-in** (`MCP_MAINTENANCE_ENABLED=false` par défaut), `statement_timeout`, `LIMIT` plafonné, secrets jamais loggés.

## Installation

```bash
python -m venv .venv && . .venv/Scripts/activate   # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"
cp .env.example .env   # puis renseigner les identifiants d'un rôle à moindre privilège
```

## Lancement

```bash
# stdio (défaut) — pour un client MCP local
mcp-postgres

# ou en HTTP
MCP_TRANSPORT=http mcp-postgres
```

### Intégration Claude Code / Desktop (stdio)

```json
{
  "mcpServers": {
    "postgres": {
      "command": "mcp-postgres",
      "env": { "PG_HOST": "localhost", "PG_USER": "mcp_readonly", "PG_PASSWORD": "..." }
    }
  }
}
```

## Tests

```bash
pytest                 # unitaires (guard, config) sans base
pytest tests/integration  # intégration (nécessite Docker via testcontainers)
```

## Structure

Voir [docs/capabilities.md](docs/capabilities.md) (carte des tools/resources/prompts) et
[docs/security.md](docs/security.md) (points de vigilance).