Skip to content

Latest commit

 

History

History
204 lines (166 loc) · 6.4 KB

03-mcp-database.md

File metadata and controls

204 lines (166 loc) · 6.4 KB

Projet 03 — MCP Database : tools PostgreSQL

Contexte

Tu implémentes un serveur MCP qui donne à Claude un accès direct à PostgreSQL.
Ce projet réutilise la base de données de api-rest-axum (même connexion, mêmes tables).
Au lieu de passer par l'API REST, Claude peut requêter, inspecter et modifier la DB directement via des tools MCP — avec des garde-fous : requêtes en lecture seule par défaut, validation SQL, timeout.

Prérequis : projet 01-api-rest-axum terminé (DB api_rest_axum existante)
Focus : pool SQLx dans un contexte MCP, sécurité SQL, introspection de schéma


Objectifs du projet

  1. Connecter un serveur MCP à PostgreSQL avec sqlx (réutiliser le pool)
  2. Implémenter 5 tools couvrant lecture, écriture (opt-in) et introspection de schéma
  3. Implémenter une validation SQL basique : bloquer les requêtes dangereuses en mode lecture seule
  4. Gérer les timeouts : une requête ne doit jamais bloquer le serveur MCP indéfiniment
  5. Exposer les tables comme Resources MCP (schéma lisible directement)

Spécifications techniques

Structure du projet

mcp-database/
├── Cargo.toml
├── .env                         ← DATABASE_URL, ALLOW_MUTATIONS
└── src/
    ├── main.rs
    ├── server.rs
    ├── db.rs                    ← PgPool setup (même pattern que api-rest-axum)
    ├── query_guard.rs           ← validation SQL read-only
    └── tools/
        ├── execute_query.rs     ← SELECT libre (avec guard)
        ├── list_tables.rs       ← information_schema.tables
        ├── describe_table.rs    ← colonnes, types, contraintes
        ├── execute_mutation.rs  ← INSERT/UPDATE/DELETE (ALLOW_MUTATIONS=true)
        └── explain_query.rs     ← EXPLAIN ANALYZE d'une requête

Les 5 tools

execute_query

{
  "name": "execute_query",
  "description": "Executes a read-only SQL SELECT query against the database. Mutations (INSERT, UPDATE, DELETE, DROP) are blocked. Returns rows as JSON array. Limited to 500 rows.",
  "inputSchema": {
    "properties": {
      "sql": { "type": "string", "description": "A SELECT SQL query" },
      "limit": { "type": "integer", "description": "Max rows to return (default 50, max 500)" }
    },
    "required": ["sql"]
  }
}

list_tables

{
  "name": "list_tables",
  "description": "Lists all tables in the database with their row counts and sizes.",
  "inputSchema": {
    "properties": {
      "schema": { "type": "string", "description": "PostgreSQL schema name (default: public)" }
    }
  }
}

describe_table

{
  "name": "describe_table",
  "description": "Returns the full schema of a table: columns, types, nullability, defaults, primary keys, foreign keys, indexes.",
  "inputSchema": {
    "properties": {
      "table": { "type": "string" },
      "schema": { "type": "string", "description": "Default: public" }
    },
    "required": ["table"]
  }
}

execute_mutation

{
  "name": "execute_mutation",
  "description": "Executes an INSERT, UPDATE or DELETE query. Only available when ALLOW_MUTATIONS=true. Returns affected row count.",
  "inputSchema": {
    "properties": {
      "sql": { "type": "string" },
      "confirm": { "type": "boolean", "description": "Must be true to execute. Safety check." }
    },
    "required": ["sql", "confirm"]
  }
}

explain_query

{
  "name": "explain_query",
  "description": "Runs EXPLAIN ANALYZE on a SQL query and returns the execution plan. Useful to check if a query uses indexes.",
  "inputSchema": {
    "properties": {
      "sql": { "type": "string" }
    },
    "required": ["sql"]
  }
}

Query Guard — sécurité SQL

pub struct QueryGuard {
    allow_mutations: bool,
}

impl QueryGuard {
    /// Vérifie qu'une requête est sûre à exécuter selon la config.
    pub fn validate(&self, sql: &str) -> Result<(), GuardError> {
        let normalized = sql.trim().to_uppercase();
        
        // Mots-clés interdits en mode lecture seule
        let mutation_keywords = ["INSERT", "UPDATE", "DELETE", "DROP", 
                                  "CREATE", "ALTER", "TRUNCATE", "GRANT", "REVOKE"];
        
        if !self.allow_mutations {
            for kw in &mutation_keywords {
                if normalized.contains(kw) {
                    return Err(GuardError::MutationBlocked { keyword: kw });
                }
            }
        }
        
        // Toujours bloqué (même en mode mutation)
        let always_blocked = ["--", "/*", "COPY", "\\i", "pg_read_file"];
        for pattern in &always_blocked {
            if normalized.contains(pattern) {
                return Err(GuardError::DangerousPattern { pattern });
            }
        }
        
        Ok(())
    }
}

Timeout sur les requêtes

use tokio::time::{timeout, Duration};

async fn execute_with_timeout(pool: &PgPool, sql: &str) -> Result<Vec<PgRow>, Error> {
    timeout(Duration::from_secs(10), sqlx::query(sql).fetch_all(pool))
        .await
        .map_err(|_| Error::QueryTimeout)?
        .map_err(Error::Database)
}

Resources MCP — schémas de tables

resource URI : "db://public/products"
             : "db://public/users"

Chaque Resource retourne le CREATE TABLE correspondant (reconstitué depuis information_schema), permettant au modèle de consulter le schéma sans appeler describe_table.


Livrables attendus

  • 5 tools fonctionnels connectés à la DB api_rest_axum
  • execute_query bloque INSERT/UPDATE/DELETE/DROP en mode par défaut
  • execute_mutation refuse si confirm !== true (double protection)
  • Timeout de 10s sur toutes les requêtes
  • Resources MCP : schéma de chaque table lisible via son URI
  • Tests : requête bloquée par guard, timeout simulé, table inexistante

Critères de qualité

  • Pool SQLx partagé via Arc dans AppState du serveur MCP
  • ALLOW_MUTATIONS=false par défaut — opt-in explicite
  • Les résultats de execute_query sont limités à 500 lignes même si LIMIT est absent de la requête (ajout automatique)
  • Log des requêtes exécutées vers stderr avec durée

Ressources