▣ gabysql

Estado: ✅ Aceptada Fecha: 2026-05-07 (propuesta) → 2026-05-07 (aceptada con la implementación del bloque siguiente) Contexto que la motiva: apertura de Fase 5 (AI-native) en ROADMAP.md. Implementación entregada en src/bin/gabysql-mcp.rs.

🧭 Contexto

gabysql se posiciona hoy como base embebida tipo SQLite (ver ADR-0007). El producto se consume por dos rutas:

  1. CLI single-process (gabysql.rs) → SQL directo contra un archivo .db.
  2. Server HTTP/JSON (gabysql-server.rs) → POST /sql con { "sql": "..." }, autorización opcional vía bearer token, tope de conexiones simultáneas configurable.

Ambos hablan SQL. Ambos asumen que el cliente sabe qué tablas existen, qué columnas tiene cada una, qué índices son útiles, y cómo se forma un WHERE válido para el subset SQL que gabysql soporta hoy.

El consumidor que está creciendo más rápido en el ecosistema no cumple ninguno de esos supuestos: agentes LLM (Claude, Cursor, Copilot, asistentes propios) que necesitan descubrir el schema, generar SQL, ejecutarlo y leer resultados sin un humano traduciendo entre lenguaje natural y SQL en cada vuelta. Hoy ese consumidor tiene que:

Cada agente reimplementa este pegamento. El protocolo MCP (Model Context Protocol) es la respuesta estándar emergente a ese problema: define cómo un servidor expone tools (funciones invocables), resources (datos legibles) y prompts a cualquier cliente compatible (Claude Desktop, Claude Code, Cursor, etc.) sobre stdio o HTTP. Si gabysql habla MCP de fábrica, cualquier agente lo enchufa directo sin código de pegamento.

Restricciones que esta decisión debe respetar:

💡 Decisión

Implementar gabysql-mcp como un binario adaptador separado que:

  1. Vive en src/bin/gabysql-mcp.rs, junto a gabysql.rs y gabysql-server.rs.
  2. Habla el protocolo MCP por stdio (transporte primario, el que usan Claude Desktop y Claude Code) y opcionalmente HTTP (transporte secundario para integraciones server-to-server).
  3. Internamente es un cliente del HTTP/JSON existente (POST /sql contra gabysql-server). No abre el .db directamente, no toca el Pager, no instancia un Engine.
  4. Expone un set acotado y estable de tools MCP:
    • gabysql_list_databases → wrap de SHOW DATABASES.
    • gabysql_describe_database(db) → wrap de SHOW TABLES + DESCRIBE por tabla, devuelto como un único bundle JSON estructurado (no SQL crudo).
    • gabysql_query(db, sql) → wrap de POST /sql para SELECT/SHOW/DESCRIBE.
    • gabysql_execute(db, sql) → wrap de POST /sql para INSERT/UPDATE/DELETE/DDL, separado por seguridad (un cliente puede tener un gabysql-mcp configurado en modo read-only y el binario rechaza la tool de escritura antes de tocar la red).
    • gabysql_integrity_check(db) → wrap de INTEGRITY CHECK.
  5. Expone como resources MCP (legibles vía URI, sin invocar tool):
    • gabysql://schema/<db> → schema completo en JSON, cacheado en el gateway con invalidación por TTL corto (default 30s).
    • gabysql://catalog → lista de DBs disponibles.
  6. Las dependencias externas (JSON-RPC, MCP SDK, etc.) viven solo en el target binario gabysql-mcp — Cargo.toml las declara como [[bin]] required-features o detrás de un feature flag opcional mcp. El crate library (src/lib.rs) sigue con cero dependencias externas.

Diagrama:

┌───────────────────┐   stdio MCP   ┌──────────────┐  HTTP/JSON   ┌─────────────────┐  Pager  ┌──────┐
│ Claude / Cursor / │ ────────────► │ gabysql-mcp  │ ───────────► │ gabysql-server  │ ──────► │ .db  │
│ agente cualquiera │               │ (adaptador)  │              │ (sin cambios)   │         │      │
└───────────────────┘               └──────────────┘              └─────────────────┘         └──────┘
                                          ▲
                                    cero dependencias
                                    en el core; el SDK
                                    MCP vive aquí

🔄 Alternativas consideradas

Embeber MCP dentro de gabysql-server

Implementar MCP a mano sin SDK, dentro del server

Adaptador en otro lenguaje (Python/Node)

Binario Rust separado, cliente del HTTP existente (decisión)

📊 Consecuencias

Positivas

Negativas

Neutras

🔗 Referencias