Multi Database MCP Server

Descripción General

El Servidor DB MCP proporciona una forma estandarizada para que los modelos de IA interactúen con múltiples bases de datos simultáneamente. Construido sobre el framework FreePeak/cortex, permite a los asistentes de IA ejecutar consultas SQL, gestionar transacciones, explorar esquemas y analizar el rendimiento en diferentes sistemas de bases de datos a través de una interfaz unificada.

Conceptos Clave

Soporte Multi-Base de Datos

A diferencia de los conectores de bases de datos tradicionales, el Servidor DB MCP puede conectarse e interactuar con múltiples bases de datos de forma concurrente:

{
  "connections": [
    {
      "id": "mysql1",
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "name": "db1",
      "user": "user1",
      "password": "password1"
    },
    {
      "id": "postgres1",
      "type": "postgres",
      "host": "localhost",
      "port": 5432,
      "name": "db2",
      "user": "user2",
      "password": "password2"
    },
    {
      "id": "oracle1",
      "type": "oracle",
      "host": "localhost",
      "port": 1521,
      "service_name": "XEPDB1",
      "user": "user3",
      "password": "password3"
    }
  ]
}

Generación Dinámica de Herramientas

Para cada base de datos conectada, el servidor genera automáticamente herramientas especializadas:

// For a database with ID "mysql1", these tools are generated:
query_mysql1       // Execute SQL queries
execute_mysql1     // Run data modification statements
transaction_mysql1 // Manage transactions
schema_mysql1      // Explore database schema
performance_mysql1 // Analyze query performance

Arquitectura Limpia

El servidor sigue los principios de Arquitectura Limpia con estas capas:

1. Capa de Dominio: Entidades de negocio e interfaces principales
2. Capa de Repositorio: Implementaciones de acceso a datos
3. Capa de Casos de Uso: Lógica de negocio de la aplicación
4. Capa de Entrega: Interfaces externas (herramientas MCP)

Características

• Soporte Multi-Base de Datos Simultáneo: Conéctese a múltiples bases de datos MySQL, PostgreSQL, SQLite y Oracle de forma concurrente
• Modo de Carga Perezosa: Diferir el establecimiento de conexiones hasta el primer uso: perfecto para configuraciones con 10+ bases de datos (habilite con la bandera --lazy-loading)
• Generación de Herramientas Específicas por Base de Datos: Crea automáticamente herramientas especializadas para cada base de datos conectada
• Arquitectura Limpia: Diseño modular con separación clara de responsabilidades
• Compatibilidad con OpenAI Agents SDK: Compatibilidad total para una integración fluida con asistentes de IA
• Herramientas Dinámicas de Base de Datos: Ejecute consultas, ejecute sentencias, gestione transacciones, explore esquemas, analice el rendimiento
• Interfaz Unificada: Patrones de interacción consistentes entre diferentes tipos de bases de datos
• Gestión de Conexiones: Configuración simple para múltiples conexiones de bases de datos
• Verificación de Salud: Validación automática de la conectividad de la base de datos al inicio
• Protecciones de Producción: Aplicación de read_only por base de datos (bloquea escrituras a través de las herramientas query_* y execute_*), truncamiento de resultados max_rows con avisos explícitos y tiempos de espera por consulta

Protecciones de Producción

Proteja las sesiones de agentes contra consultas descontroladas y escrituras accidentales:

Configuración	Alcance	Efecto
"read_only": true	por base de datos	Bloquea sentencias de escritura (INSERT, UPDATE, DELETE, DDL, CTEs que modifican datos, escrituras apiladas) a través de ambas herramientas de consulta y ejecución, y aplica el rechazo en el propio motor de la base de datos en PostgreSQL/TimescaleDB (default_transaction_read_only=on) y MySQL (transaction_read_only=1); SQLite abre mode=ro. La clasificación elimina comentarios y literales de cadena y se establece en denegar por defecto para sentencias no reconocidas.
"max_rows": 1000	por base de datos	Trunca los conjuntos de resultados en N filas y agrega un aviso explícito de [Truncated] para que el modelo sepa que debe refinar su consulta en lugar de perder contexto. 0 (predeterminado) significa ilimitado.
"masking_rules": [...]	por base de datos	Enmascara los valores de las columnas de resultados cuyo nombre coincide con la expresión regular de una regla antes de que salgan del servidor: se aplica a todas las formas de consulta, incluido SELECT *. Estrategias: "fixed_string" (reemplazar con value), "null" y "partial" (keep_last caracteres finales visibles; valores más cortos completamente enmascarados). La primera regla que coincida gana; patrones no válidos o estrategias desconocidas abortan la carga de configuración (fallo cerrado); los recuentos de celdas enmascaradas se informan en el pie de página del resultado. Renombrar una columna con un alias evita la coincidencia de nombres por diseño. Consulte docs/design/column-masking-scoping.md.
"query_timeout": 30	por base de datos	Cancela sentencias que exceden el tiempo de espera en segundos; se aplica en la capa de repositorio para cada herramienta (consultas, sentencias, transacciones, explicación, inspección de esquemas). Sin configurar, el valor predeterminado es 30s; -1 lo desactiva. Los despliegues solo con variables de entorno pueden configurar QUERY_TIMEOUT_SECONDS para completar conexiones sin un valor explícito (JSON mantiene precedencia).

| DB_MCP_AUDIT_LOG=/path/audit.jsonl | proceso | Agrega un registro JSONL por sentencia ejecutada: marca de tiempo, operación (query/execute/tx_*), base de datos, sentencia (limitada a 10k caracteres), duración, error. Incluye intentos rechazados contra bases de datos de solo lectura. Las escrituras de mejor esfuerzo nunca fallan una consulta; el archivo se crea con 0600. |

Defensa en profundidad: el modo de solo lectura se aplica en tres capas: clasificador de aplicación, valores predeterminados de sesión del motor y (recomendado) usuarios de base de datos con privilegios mínimos. Oracle actualmente depende del clasificador más los privilegios de usuario.

Bases de Datos Compatibles

Base de Datos	Estado	Características
MySQL	✅ Soporte Completo	Consultas, Transacciones, Análisis de Esquemas, Información de Rendimiento
PostgreSQL	✅ Soporte Completo (v9.6-17)	Consultas, Transacciones, Análisis de Esquemas, Información de Rendimiento
SQLite	✅ Soporte Completo	Bases de datos basadas en archivos y en memoria, soporte de cifrado SQLCipher
Oracle	✅ Soporte Completo (10g-23c)	Consultas, Transacciones, Análisis de Esquemas, RAC, Cloud Wallet, TNS
TimescaleDB	✅ Soporte Completo	Consultas de Series Temporales, Descubrimiento de Hipertablas (políticas de escritura vía SQL)

Opciones de Despliegue

El Servidor DB MCP se puede desplegar de múltiples maneras para adaptarse a diferentes entornos y necesidades de integración:

Despliegue con Docker

# Pull the latest image
docker pull freepeak/db-mcp-server:latest

# Run with mounted config file
docker run -p 9092:9092 \
  -v $(pwd)/config.json:/app/my-config.json \
  -e TRANSPORT_MODE=sse \
  -e CONFIG_PATH=/app/my-config.json \
  -e DB_MCP_API_KEY=replace-me-with-a-long-random-string \
  freepeak/db-mcp-server

Nota: Monte en /app/my-config.json ya que el contenedor tiene un archivo predeterminado en /app/config.json.

Autenticación con Clave API

Los transportes SSE y streamable-HTTP aceptan un encabezado Authorization: Bearer <key>. Configure DB_MCP_API_KEY (o pase -api-key) al lanzar el contenedor Docker; los clientes deben entonces enviar el token de portador correspondiente en cada solicitud:

curl -H "Authorization: Bearer replace-me-with-a-long-random-string" \
     http://localhost:9092/sse

Cuando no se configura una clave API, el transporte permanece abierto (uso de un solo usuario / desarrollo). El middleware reside en internal/delivery/mcp.APIKeyAuth y se exporta para que pueda componerlo con su propio proxy inverso si coloca el contenedor detrás de nginx, Caddy o Traefik.

Modo STDIO (Integración con IDE)

# Run the server in STDIO mode
./bin/server -t stdio -c config.json

Para la integración con Cursor IDE, agregue a .cursor/mcp.json:

{
  "mcpServers": {
    "stdio-db-mcp-server": {
      "command": "/path/to/db-mcp-server/server",
      "args": ["-t", "stdio", "-c", "/path/to/config.json"]
    }
  }
}

Modo SSE (Eventos Enviados por el Servidor)

# Default configuration (localhost:9092)
./bin/server -t sse -c config.json

# Custom host and port
./bin/server -t sse -host 0.0.0.0 -port 8080 -c config.json

Punto de conexión del cliente: http://localhost:9092/sse

Instalación desde Código Fuente

# Clone the repository
git clone https://github.com/FreePeak/db-mcp-server.git
cd db-mcp-server

# Build the server
make build

# Run the server
./bin/server -t sse -c config.json

Configuración

Archivo de Configuración de Bases de Datos

Cree un archivo config.json con sus conexiones de bases de datos:

{
  "connections": [
    {
      "id": "mysql1",
      "type": "mysql",
      "host": "mysql1",
      "port": 3306,
      "name": "db1",
      "user": "user1",
      "password": "password1",
      "query_timeout": 60,
      "max_open_conns": 20,
      "max_idle_conns": 5,
      "conn_max_lifetime_seconds": 300,
      "conn_max_idle_time_seconds": 60,
      "read_only": false,
      "max_rows": 1000,
      "masking_rules": [
        { "pattern": "(?i)email", "strategy": "fixed_string", "value": "***MASKED***" },
        { "pattern": "(?i)(ssn|tax_id)", "strategy": "null" }
      ]
    },
    {
      "id": "postgres1",
      "type": "postgres",
      "host": "postgres1",
      "port": 5432,
      "name": "db1",
      "user": "user1",
      "password": "password1"
    },
    {
      "id": "sqlite_app",
      "type": "sqlite",
      "database_path": "./data/app.db",
      "journal_mode": "WAL",
      "cache_size": 2000,
      "read_only": false,
      "use_modernc_driver": true,
      "query_timeout": 30,
      "max_open_conns": 1,
      "max_idle_conns": 1
    },
    {
      "id": "sqlite_encrypted",
      "type": "sqlite",
      "database_path": "./data/secure.db",
      "encryption_key": "your-secret-key-here",
      "journal_mode": "WAL",
      "use_modernc_driver": false
    },
    {
      "id": "sqlite_memory",
      "type": "sqlite",
      "database_path": ":memory:",
      "cache_size": 1000,
      "use_modernc_driver": true
    }
  ]
}

Opciones de Línea de Comandos

# Basic syntax
./bin/server -t <transport> -c <config-file>

# SSE transport options
./bin/server -t sse -host <hostname> -port <port> -c <config-file>

# Lazy loading mode (recommended for 10+ databases)
./bin/server -t stdio -c <config-file> --lazy-loading

# Customize log directory (useful for multi-project setups)
./bin/server -t stdio -c <config-file> -log-dir /tmp/db-mcp-logs

# Inline database configuration
./bin/server -t stdio -db-config '{"connections":[...]}'

# Environment variable configuration
export DB_CONFIG='{"connections":[...]}'
./bin/server -t stdio

Banderas Disponibles:

• -t, -transport: Modo de transporte (stdio o sse)
• -c, -config: Ruta al archivo de configuración de bases de datos
• -p, -port: Puerto del servidor para modo SSE (predeterminado: 9092)
• -h, -host: Host del servidor para modo SSE (predeterminado: localhost)
• -log-level: Nivel de registro (debug, info, warn, error)
• -log-dir: Directorio para archivos de registro (predeterminado: ./logs en el directorio actual)
• -db-config: Configuración de bases de datos JSON en línea

Variables de Entorno

Los valores en un archivo .env se cargan primero; las variables de entorno reales tienen precedencia. Un archivo de configuración JSON (CONFIG_PATH/DB_CONFIG_FILE) anula las variables de entorno por base de datos.

Variable	Predeterminado	Propósito
CONFIG_PATH / DB_CONFIG_FILE	config.json	Ruta a la configuración JSON multi-base de datos
DB_CONFIG	—	Configuración de bases de datos JSON en línea (alternativa a un archivo)
TRANSPORT_MODE	sse	Modo de transporte cuando no se pasa -t
SERVER_PORT	9090	Puerto HTTP para modo SSE
LOG_LEVEL	info	Verbosidad del registro (debug, info, warn, error)
DISABLE_LOGGING	false	true/1 silencia el registro por completo
DB_TYPE, DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME	valores predeterminados del motor	Respaldo de una sola base de datos cuando no existe configuración JSON
QUERY_TIMEOUT_SECONDS	sin configurar	Completa conexiones que no establecen su propio query_timeout; negativo desactiva el límite. Las configuraciones JSON mantienen precedencia.

Opciones de Configuración de SQLite

Al usar bases de datos SQLite, puede aprovechar estas opciones de configuración adicionales:

Parámetros de Conexión de SQLite

Parámetro	Tipo	Predeterminado	Descripción
database_path	string	Requerido	Ruta al archivo de base de datos SQLite o :memory: para en memoria
encryption_key	string	-	Clave para bases de datos cifradas con SQLCipher
read_only	boolean	false	Abrir la base de datos en modo de solo lectura
max_rows	integer	ilimitado	Máximo de filas devueltas por consulta; los resultados más grandes se truncan con un aviso explícito. Funciona en todos los tipos de bases de datos
cache_size	integer	2000	Tamaño de caché de SQLite en páginas
journal_mode	string	"WAL"	Modo de diario: DELETE, TRUNCATE, PERSIST, WAL, OFF
use_modernc_driver	boolean	true	Usar modernc.org/sqlite (sin CGO) o mattn/go-sqlite3

Ejemplos de SQLite

Base de Datos Básica de Archivo

{
  "id": "my_sqlite_db",
  "type": "sqlite",
  "database_path": "./data/myapp.db",
  "journal_mode": "WAL",
  "cache_size": 2000
}

Base de Datos Cifrada (SQLCipher)

{
  "id": "encrypted_db",
  "type": "sqlite",
  "database_path": "./data/secure.db",
  "encryption_key": "your-secret-encryption-key",
  "use_modernc_driver": false
}

Base de Datos en Memoria

{
  "id": "memory_db",
  "type": "sqlite",
  "database_path": ":memory:",
  "cache_size": 1000
}

Base de Datos de Solo Lectura

{
  "id": "reference_data",
  "type": "sqlite",
  "database_path": "./data/reference.db",
  "read_only": true,
  "journal_mode": "DELETE"
}

Opciones de Configuración de Oracle

Al usar bases de datos Oracle, puede aprovechar estas opciones de configuración adicionales:

Parámetros de Conexión de Oracle

Parámetro	Tipo	Predeterminado	Descripción
host	string	Requerido	Host de la base de datos Oracle
port	integer	1521	Puerto del listener de Oracle
service_name	string	-	Nombre del servicio (recomendado para RAC)
sid	string	-	Identificador del sistema (heredado, use service_name en su lugar)
user	string	Requerido	Nombre de usuario de la base de datos
password	string	Requerido	Contraseña de la base de datos
wallet_location	string	-	Ruta al directorio de Oracle Cloud wallet
tns_admin	string	-	Ruta al directorio que contiene tnsnames.ora
tns_entry	string	-	Entrada nombrada de tnsnames.ora
edition	string	-	Nombre de edición para Redefinición Basada en Ediciones
pooling	boolean	false	Habilitar agrupación de conexiones a nivel de controlador
standby_sessions	boolean	false	Permitir consultas en bases de datos en espera
nls_lang	string	AMERICAN_AMERICA.AL32UTF8	Configuración del conjunto de caracteres

Ejemplos de Oracle

Conexión Básica de Oracle (Desarrollo)

{
  "id": "oracle_dev",
  "type": "oracle",
  "host": "localhost",
  "port": 1521,
  "service_name": "XEPDB1",
  "user": "testuser",
  "password": "testpass",
  "max_open_conns": 50,
  "max_idle_conns": 10,
  "conn_max_lifetime_seconds": 1800
}

Oracle con SID (Heredado)

{
  "id": "oracle_legacy",
  "type": "oracle",
  "host": "oracledb.company.com",
  "port": 1521,
  "sid": "ORCL",
  "user": "app_user",
  "password": "app_password"
}

Oracle Cloud Autonomous Database (con Wallet)

{
  "id": "oracle_cloud",
  "type": "oracle",
  "user": "ADMIN",
  "password": "your-cloud-password",
  "wallet_location": "/path/to/wallet_DBNAME",
  "service_name": "dbname_high"
}

Oracle RAC (Clústeres de Aplicaciones Reales)

{
  "id": "oracle_rac",
  "type": "oracle",
  "host": "scan.company.com",
  "port": 1521,
  "service_name": "production",
  "user": "app_user",
  "password": "app_password",
  "max_open_conns": 100,
  "max_idle_conns": 20
}

Oracle con Entrada TNS

{
  "id": "oracle_tns",
  "type": "oracle",
  "tns_admin": "/opt/oracle/network/admin",
  "tns_entry": "PROD_DB",
  "user": "app_user",
  "password": "app_password"
}

Oracle con Redefinición Basada en Ediciones

{
  "id": "oracle_ebr",
  "type": "oracle",
  "host": "oracledb.company.com",
  "port": 1521,
  "service_name": "production",
  "user": "app_user",
  "password": "app_password",
  "edition": "v2_0"
}

Prioridad de la Cadena de Conexión de Oracle

Cuando se configuran múltiples métodos de conexión, se utiliza la siguiente prioridad:

1. Entrada TNS (si tns_entry y tns_admin están configurados)
2. Wallet (si wallet_location está configurado) - para Oracle Cloud
3. Estándar (host:puerto/nombre_servicio) - método predeterminado

Herramientas Disponibles

Para cada base de datos conectada, DB MCP Server genera automáticamente estas herramientas especializadas:

Herramientas de Consulta

Nombre de la Herramienta	Descripción
query_<db_id>	Ejecuta consultas SELECT y obtiene resultados como un conjunto de datos tabular
execute_<db_id>	Ejecuta sentencias de manipulación de datos (INSERT, UPDATE, DELETE)
transaction_<db_id>	Inicia, confirma y revierte transacciones

Herramientas de Esquema

Nombre de la Herramienta	Descripción
schema_<db_id>	Obtiene información sobre tablas, columnas, índices y claves foráneas
generate_schema_<db_id>	Genera SQL o código a partir del esquema de la base de datos

Herramientas de Rendimiento

Nombre de la Herramienta	Descripción
performance_<db_id>	Analiza el rendimiento de consultas mediante acciones: stats / slow_queries (rastreador en proceso), engine_slow_queries (pg_stat_statements / tablas de resumen de MySQL / v$sqlarea de Oracle), suggest (lint estático de SQL), suggest_indexes (consejo heurístico de CREATE INDEX para una sentencia, compuestos con prioridad de igualdad, verificar con EXPLAIN), validate_suggestions (PostgreSQL: instala las mismas sugerencias como índices hipotéticos sin costo mediante la extensión hypopg e informa si el planificador realmente elige cada uno — validación de verdad fundamental en lugar de EXPLAIN manual), workload_suggestions (mismo análisis en las N sentencias de trabajo más costosas, ponderadas por ejecuciones), index_health (índices duplicados/redundantes/no utilizados/inválidos y hallazgos de bloat de tablas desde catálogos; evidencia de uso donde existen estadísticas del motor), db_health (todo lo que cubre index_health más presión de utilización de conexiones vs max_connections), reset
explain_<db_id>	Muestra el plan de ejecución de una sentencia SQL sin ejecutarla; analyze: true ejecuta con estadísticas de tiempo/búfer (PostgreSQL/MySQL). Las escrituras permanecen bloqueadas en bases de datos de solo lectura
describe_<db_id>	Inspecciona las columnas, índices y estimación de filas de una tabla mediante consultas al catálogo del motor
health_<db_id>	Informa conectividad, latencia de ping, estado del grupo de conexiones y estadísticas del motor (proporción de aciertos de caché de búfer de PostgreSQL, eficiencia del búfer InnoDB de MySQL)

Herramientas de TimescaleDB

Para bases de datos PostgreSQL con la extensión timescaledb instalada, estas herramientas especializadas adicionales se registran automáticamente al inicio (el registro está controlado por configuración, por lo que también funciona bajo --lazy-loading; cada manejador verifica la extensión en el momento de la llamada y devuelve un error accionable cuando está ausente):

Nombre de la Herramienta	Descripción
timescaledb_timeseries_query_<db_id>	Ejecuta consultas de series temporales optimizadas con agrupación de tiempo (time_bucket), filtrado y funciones de ventana
timescaledb_analyze_timeseries_<db_id>	Analiza patrones de series temporales (tendencia, resumen de estacionalidad) para una tabla/columna
timescaledb_list_hypertables_<db_id>	Lista hypertables con su columna de tiempo y número de dimensiones (solo lectura)
timescaledb_compression_settings_<db_id>	Muestra la configuración de compresión para hypertables (solo lectura)
timescaledb_retention_policy_<db_id>	Muestra las políticas de retención configuradas (solo lectura)
timescaledb_list_continuous_aggregates_<db_id>	Lista agregados continuos con intervalo de cubo y política de actualización (solo lectura)
timescaledb_continuous_aggregate_info_<db_id>	Inspecciona un agregado continuo en detalle (solo lectura)

En modo unificado, las mismas siete herramientas aparecen una vez como timescaledb_timeseries_query, timescaledb_analyze_timeseries, timescaledb_list_hypertables, timescaledb_compression_settings, timescaledb_retention_policy, timescaledb_list_continuous_aggregates y timescaledb_continuous_aggregate_info, cada una tomando un parámetro database obligatorio.

Nota de alcance: el descubrimiento de solo lectura anterior pasa por el pipeline de consultas y, por lo tanto, permanece utilizable en bases de datos read_only; cada manejador verifica la extensión timescaledb primero. Las operaciones de políticas de escritura (creación de hypertables, alternancia de compresión, agregar/eliminar políticas de retención o actualización) permanecen no expuestas — use SQL simple a través de las herramientas de consulta/ejecución mientras tanto. Para documentación detallada, consulte TIMESCALEDB_TOOLS.md.

Modo de Herramienta Unificada

Si conecta muchas bases de datos (5+), la nomenclatura de herramientas por base de datos genera una gran cantidad de herramientas (5 × N). Algunos clientes MCP — Claude en particular — aplican límites estrictos en el número total de herramientas y el tamaño de la descripción de herramientas que pueden hacer que el agente falle al cargar el servidor, ignore herramientas o se niegue a llamarlas. El problema #18 documenta este síntoma exacto: "db-mcp-server no funciona correctamente con Claude, aunque funciona bien con OpenAI".

Para estos clientes, inicie el servidor con la bandera --unified-tools para registrar seis herramientas consolidadas (query, execute, transaction, performance, explain, describe, schema, filter_tables) en lugar de herramientas por base de datos:

./bin/server -t stdio -c config.json --unified-tools

Costo de ventana de contexto (medido, TestToolTokenBenchmark, re-verificado 2026-08 mediante scripts/token-benchmark.sh): el modo unificado cuesta ~1.25–1.6k tokens independientemente de cuántas bases de datos estén conectadas, mientras que el modo por base de datos cuesta ~800 tokens por base de datos (7 herramientas cada una) — 10 bases de datos conectadas ≈ 8k tokens, un ahorro del 80% en la carga útil del cable con unificado. Con una sola base de datos, la nomenclatura por base de datos es ligeramente más barata; unificado gana desde dos bases de datos en adelante y escala plano después. Vuelva a medir la carga útil real del cable usted mismo con scripts/token-benchmark.sh; metodología y resultados en docs/benchmark-token-efficiency.md.

In unified mode, each tool accepts a required `database` parameter that names
which database the call should target. See the [Configuration](#configuration)
section for the full list of available databases. This dramatically reduces the
tool count and the cumulative description size, which resolves the Claude
compatibility issues.

For very large configurations, also enable `--lazy-loading` so that startup
doesn't open connections to databases that may never be queried during the
session.

## Examples

### Querying Multiple Databases

```sql
-- Query the MySQL database
query_mysql1("SELECT * FROM users LIMIT 10")

-- Query the PostgreSQL database in the same context
query_postgres1("SELECT * FROM products WHERE price > 100")

-- Query the SQLite database
query_sqlite_app("SELECT * FROM local_data WHERE created_at > datetime('now', '-1 day')")

-- Query the Oracle database
query_oracle_dev("SELECT * FROM employees WHERE hire_date > SYSDATE - 30")

Gestión de Transacciones

La herramienta transaction_<db_id> admite acciones begin, execute, commit y rollback. Cada begin devuelve un transactionId; páselo de vuelta para preparar sentencias y para confirmar o revertir:

// 1. Start a transaction
{ "action": "begin" }
// → { "transactionId": "tx_mysql1_1730000000000000000" }

// 2. Execute statements within the transaction
{
  "action": "execute",
  "transactionId": "tx_mysql1_1730000000000000000",
  "statement": "INSERT INTO orders (customer_id, product_id) VALUES (1, 2)"
}

// 3a. Commit — persists all staged statements
{ "action": "commit", "transactionId": "tx_mysql1_1730000000000000000" }

// 3b. OR rollback — discards all staged statements
{ "action": "rollback", "transactionId": "tx_mysql1_1730000000000000000" }

Los ID de transacción desconocidos o ya retirados devuelven un error claro en lugar de un éxito silencioso, para que los agentes puedan detectar y recuperarse de situaciones de transacciones perdidas.

Exploración del Esquema de la Base de Datos

-- Get all tables in the database
schema_mysql1("tables")

-- Get columns for a specific table
schema_mysql1("columns", "users")

-- Get constraints
schema_mysql1("constraints", "orders")

Trabajo con Características Específicas de SQLite

-- Create a table in SQLite
execute_sqlite_app("CREATE TABLE IF NOT EXISTS local_cache (key TEXT PRIMARY KEY, value TEXT, timestamp DATETIME)")

-- Use SQLite-specific date functions
query_sqlite_app("SELECT * FROM events WHERE date(created_at) = date('now')")

-- Query SQLite master table for schema information
query_sqlite_app("SELECT name, sql FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")

-- Performance optimization with WAL mode
execute_sqlite_app("PRAGMA journal_mode = WAL")
execute_sqlite_app("PRAGMA synchronous = NORMAL")

Trabajo con Características Específicas de Oracle

-- Query user tables (excludes system schemas)
query_oracle_dev("SELECT table_name FROM user_tables ORDER BY table_name")

-- Use Oracle-specific date functions
query_oracle_dev("SELECT employee_id, hire_date FROM employees WHERE hire_date >= TRUNC(SYSDATE, 'YEAR')")

-- Oracle sequence operations
execute_oracle_dev("CREATE SEQUENCE emp_seq START WITH 1000 INCREMENT BY 1")
query_oracle_dev("SELECT emp_seq.NEXTVAL FROM DUAL")

-- Oracle-specific data types
query_oracle_dev("SELECT order_id, TO_CHAR(order_date, 'YYYY-MM-DD HH24:MI:SS') FROM orders")

-- Get schema metadata from Oracle data dictionary
query_oracle_dev("SELECT column_name, data_type, nullable FROM user_tab_columns WHERE table_name = 'EMPLOYEES'")

-- Use Oracle analytic functions
query_oracle_dev("SELECT employee_id, salary, RANK() OVER (ORDER BY salary DESC) as salary_rank FROM employees")

Solución de Problemas

Problemas Comunes

• Fallos de Conexión: Verifique la conectividad de red y las credenciales de la base de datos
• Errores de Permisos: Asegúrese de que el usuario de la base de datos tenga los permisos apropiados
• Problemas de Tiempo de Espera: Verifique la configuración de query_timeout en su configuración

Registros

Habilite el registro detallado para la solución de problemas:

./bin/server -t sse -c config.json -v

Pruebas

Ejecución de Pruebas

El proyecto incluye pruebas unitarias y de integración completas para todas las bases de datos compatibles.

Pruebas Unitarias

Ejecute pruebas unitarias (no se requiere base de datos):

make test
# or
go test -short ./...

Pruebas de Integración

Las pruebas de integración requieren instancias de base de datos en ejecución. Proporcionamos configuraciones de Docker Compose para una configuración fácil.

Probar Todas las Bases de Datos:

# Start test databases
docker-compose -f docker-compose.test.yml up -d

# Run all integration tests
go test ./... -v

# Stop test databases
docker-compose -f docker-compose.test.yml down -v

Probar Base de Datos Oracle:

# Start Oracle test environment
./oracle-test.sh start

# Run Oracle tests
./oracle-test.sh test
# or manually
ORACLE_TEST_HOST=localhost go test -v ./pkg/db -run TestOracle
ORACLE_TEST_HOST=localhost go test -v ./pkg/dbtools -run TestOracle

# Stop Oracle test environment
./oracle-test.sh stop

# Full cleanup (removes volumes)
./oracle-test.sh cleanup

Probar TimescaleDB:

# Start TimescaleDB test environment
./timescaledb-test.sh start

# Run TimescaleDB tests
TIMESCALEDB_TEST_HOST=localhost go test -v ./pkg/db/timescale ./internal/delivery/mcp

# Stop TimescaleDB test environment
./timescaledb-test.sh stop

Pruebas de Regresión

Ejecute pruebas de regresión completas en todos los tipos de base de datos:

# Ensure all test databases are running
docker-compose -f docker-compose.test.yml up -d
./oracle-test.sh start

# Run regression tests
MYSQL_TEST_HOST=localhost \
POSTGRES_TEST_HOST=localhost \
ORACLE_TEST_HOST=localhost \
go test -v ./pkg/db -run TestRegression

# Run connection pooling tests
go test -v ./pkg/db -run TestConnectionPooling

Integración Continua

Todas las pruebas se ejecutan automáticamente en cada solicitud de extracción mediante GitHub Actions. El pipeline de CI incluye:

• Pruebas Unitarias: Pruebas rápidas que no requieren conexiones de base de datos
• Pruebas de Integración: Pruebas contra bases de datos MySQL, PostgreSQL, SQLite y Oracle
• Pruebas de Regresión: Pruebas completas que garantizan compatibilidad hacia atrás
• Linting: Verificaciones de calidad de código con golangci-lint

Contribuciones

¡Damos la bienvenida a contribuciones al proyecto DB MCP Server! Para contribuir:

1. Haga un fork del repositorio
2. Cree una rama de características (git checkout -b feature/amazing-feature)
3. Confirme sus cambios (git commit -m 'feat: add amazing feature')
4. Empuje a la rama (git push origin feature/amazing-feature)
5. Abra una Solicitud de Extracción

Consulte nuestro archivo CONTRIBUTING.md para obtener pautas detalladas.

Pruebas de Sus Cambios

Antes de enviar una solicitud de extracción, asegúrese de:

1. Todas las pruebas unitarias pasen: go test -short ./...
2. Las pruebas de integración pasen para las bases de datos afectadas
3. El código siga las pautas de estilo del proyecto: golangci-lint run ./...
4. Las nuevas características incluyan cobertura de pruebas apropiada

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para más detalles.