mysql-pro-mcp — MCP MySQL/MariaDB con separación por clase de sentencia

Servidor MCP (stdio, Node) con dos herramientas separadas por clase de sentencia, pensado para que un hook de permisos (o el modo del cliente) pueda aprobar las lecturas y confirmar las escrituras:

| Herramienta | Acepta | Uso típico en allowlist | |---|---|---| | query | SELECT, WITH (CTE de lectura), SHOW, DESCRIBE/DESC, EXPLAIN (y EXPLAIN ANALYZE), ANALYZE (MariaDB ANALYZE SELECT), TABLE | ✅ auto-aprobada | | execute | INSERT, UPDATE, DELETE, REPLACE, CREATE, ALTER, DROP, TRUNCATE, RENAME | ❌ pide confirmación |

Instalación vía npx (registrado)

"mysql-pro": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@yurdeth/mysql-pro-mcp"],
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "tu_usuario",
    "MYSQL_PASSWORD": "tu_password"
  }
}

Sin MYSQL_DATABASE: la base es dinámica (ver abajo). Herramientas resultantes: mcp__mysql-pro__query y mcp__mysql-pro__execute.

Diseño

• Clasificación por prefijo (primera palabra clave de la sentencia), NO parser gramatical. Esto evita de raíz los bugs de los paquetes con parser estricto (DESCRIBE db.tabla y ANALYZE SELECT fallaban en @benborla29).
• Guardas extra en query (defensa en profundidad):
  • INTO OUTFILE / INTO DUMPFILE rechazados (un SELECT puede escribir archivos).
  • ANALYZE TABLE rechazado (actualiza estadísticas = escritura).
  • WITH ... INSERT/UPDATE/DELETE/REPLACE rechazado (CTE que modifica datos).
  • multipleStatements: false en el driver (bloqueo duro contra ; DROP ...).
• Conexión dinámica: las variables de entorno dan los defaults, y cada llamada puede sobreescribir host, port, user, password, database. Sin MYSQL_DATABASE en el env no hay base por defecto: se usa nombre calificado (oswa_inv.products) o el parámetro database por llamada.
• Pools por tupla de conexión (host, port, user, database): cambiar de base o de usuario es simplemente otro pool. Máximo MYSQL_PRO_MAX_POOLS (default 8, se evicta el más viejo). Pool con credenciales malas se descarta solo para que el siguiente intento use las corregidas.
• Resultados de query limitados a MYSQL_PRO_MAX_ROWS (default 1000) con aviso truncated. Fechas como strings (dateStrings: true, sin re-interpretación TZ).

Variables de entorno

| Var | Default | Uso | |---|---|---| | MYSQL_HOST | localhost | Host por defecto | | MYSQL_PORT | 3306 | Puerto por defecto | | MYSQL_USER | — | Usuario por defecto | | MYSQL_PASSWORD | — | Password por defecto | | MYSQL_DATABASE | (vacío) | Base por defecto. Dejar vacía = totalmente dinámico | | MYSQL_PRO_MAX_ROWS | 1000 | Tope de filas devueltas por query | | MYSQL_PRO_MAX_POOLS | 8 | Máximo de pools simultáneos |

Registro local (sin npx, ruta directa)

"mysql-pro": {
  "type": "stdio",
  "command": "node",
  "args": ["/ruta/al/checkout/mcp-servers/mysql-pro/index.mjs"],
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "…",
    "MYSQL_PASSWORD": "…"
  }
}

En el hook de auto-aprobación de ZCode (~/.zcode/cli/hooks/mcp-autopass.js) está agregado SOLO mcp__mysql-pro__query; execute queda fuera para que pida confirmación.

Limitaciones conocidas (a propósito)

• Una sentencia por llamada (sin multi-statements).
• Sin CALL (procedimientos), SET, USE, LOCK/UNLOCK TABLES, GRANT, LOAD DATA.
• ANALYZE TABLE no está en ninguna herramienta (es escritura de metadatos); si algún día hace falta, agregar 'analyze' con cuidado a WRITE_PREFIXES.
• Un WITH de lectura cuyo texto contenga las palabras insert/update/delete/ replace (p.ej. en un literal de string) se rechaza por falso positivo: reescribir la consulta sin esa palabra.

Pruebas

node /home/angel/.zcode/cli/mcp-servers/mysql-pro/test-client.mjs

Corre la matriz completa: lecturas, nombres calificados, EXPLAIN, ANALYZE de MariaDB, DB dinámica, rechazos de seguridad y ciclo CREATE/DROP de una base scratch (mcp_pro_selftest). Última corrida: 2026-08-21, todo en verde.