Servidor de base de datos MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) creado con mcp-framework que proporciona herramientas y recursos para interactuar con bases de datos (PostgreSQL a través de DuckDB) y Google Cloud Storage (GCS).

Prerrequisitos

Node.js 22 o superior
Mecanografiado
PostgreSQL (necesario para las funciones de la base de datos)
Credenciales de Google Cloud (opcionales, para funciones de GCS)
Devbox (para desarrollo local usando comandos make )

Estructura del proyecto

.
├── docs
│   ├── assets
│   │   └── etl.png
│   ├── etl-workflow.md
│   └── setup-with-claude-desktop.md
├── migrations
│   ├── 1743322886782_initial-schema.cjs
│   └── 1743323460433_continuous-aggregates.cjs
├── scripts
│   └── setup-continuous-aggregates.sql
├── src
│   ├── resources       # MCP Resource definitions
│   │   ├── gcs_objects.ts
│   │   └── sql_tables.ts
│   ├── services        # Service initializers (DB connections, GCS client)
│   │   ├── duckdb.ts
│   │   ├── gcs.ts
│   │   └── postgres.ts
│   ├── tools           # MCP Tool definitions
│   │   ├── duckdb_insert.ts
│   │   ├── duckdb_query.ts
│   │   ├── duckdb_read_parquet.ts
│   │   └── gcs_directory_tree.ts
│   ├── utils           # Utility functions (logging, formatting)
│   │   ├── index.ts
│   │   └── logger.ts
│   ├── config.ts       # Configuration loading and validation
│   ├── index.ts        # Main server entry point
│   └── utils.ts        # Deprecated utils? (Consider removing if unused)
├── .env.example        # Example environment variables
├── .gitignore
├── CLAUDE.md
├── Dockerfile
├── MIGRATION.md
├── Makefile            # Development commands
├── README.md
├── database.json       # Migration configuration
├── devbox.json         # Devbox configuration
├── devbox.lock
├── docker-compose.yml  # Docker setup for DBs
├── fly.toml            # Fly.io deployment config
├── package-lock.json
├── package.json
└── tsconfig.json

Instalación

Clonar el repositorio:
git clone <repository-url> cd mcp-db
Instalar dependencias (se recomienda utilizar Devbox para mantener la coherencia):
devbox install # Or using npm directly if not using Devbox # npm install
Copie .env.example a .env y complete sus variables de entorno.
cp .env.example .env # Edit .env with your details
Construir el proyecto:
# Using make (requires Devbox) make build # Or using npm directly # npm run build

Configuración

Variables de entorno

Configure el servidor utilizando estas variables de entorno (o argumentos de línea de comandos):

DATABASE_URL : cadena de conexión PostgreSQL (obligatoria a menos que se ejecute con supergateway).
DATABASE_URLS : Lista separada por comas de pares alias=url para múltiples conexiones de base de datos (alternativa a DATABASE_URL ).
LOG_LEVEL : Nivel de registro ( debug , info , error ). Predeterminado: info .
GCS_BUCKET : nombre del depósito de Google Cloud Storage predeterminado (opcional).
GCP_SERVICE_ACCOUNT : clave JSON de cuenta de servicio de Google Cloud codificada en Base64 (opcional, para la autenticación de GCS).
GCS_KEY_ID / GCS_SECRET : Credenciales GCS alternativas específicamente para la extensión httpfs de DuckDB (opcional).
TRANSPORT : Tipo de transporte ( stdio o sse ). Predeterminado: stdio .
PORT : Número de puerto para el transporte SSE. Predeterminado: 3001 .
HOST : Nombre de host para el transporte SSE. Predeterminado: localhost .
API_KEY : Clave API opcional para proteger el servidor (si se configura, los clientes deben proporcionarla en el encabezado Authorization: Bearer <key> ).

Los argumentos de la línea de comandos (p. ej., --port 8080 , --gcs-bucket my-bucket ) anulan las variables de entorno. Consulte src/config.ts para obtener más información.

Migraciones de bases de datos

El proyecto utiliza node-pg-migrate para gestionar los cambios de esquema de PostgreSQL. Consulte la sección "Migraciones de bases de datos" del archivo README original (arriba) para obtener más información sobre cómo ejecutar y crear migraciones.

Nota: El comando npm run setup:db mencionado anteriormente podría necesitar revisión o actualizaciones según la configuración actual.

Ejecución del servidor

Utilice el Makefile para comandos de desarrollo convenientes (requiere Devbox):

# Run in development mode (builds and starts with nodemon for auto-restarts)
# Uses SSE transport by default on port 3001
make dev

# Run tests (if configured)
# make test

# Build for production
# make build

Para ejecutar sin make (después de npm run build ):

# Run with stdio transport
node dist/index.js --transport stdio

# Run with SSE transport on default port 3001
node dist/index.js --transport sse

# Run with SSE on a different port
node dist/index.js --transport sse --port 8080

Configuración del cliente

Para conectar su cliente MCP (por ejemplo, mcp-cli , Claude Desktop) al servidor local:

Para el transporte SSE (por ejemplo, en el puerto 3001):

{
  "mcpServers": {
    "mcp-db-local": {
      "command": "node",
      "args": [
        "/path/to/mcp-db/dist/index.js", // Adjust path if needed
        "--transport", "sse",
        "--port", "3001" // Match the port the server is running on
      ],
      // Add "env" if API_KEY is set
      // "env": { "API_KEY": "your-secret-key" }
    }
  }
}

(Nota: el ejemplo de Docker/supergateway del README anterior podría estar desactualizado o ser específico para una configuración de implementación diferente).

Para el transporte de Stdio:

{
  "mcpServers": {
    "mcp-db-local": {
      "command": "node",
      "args": [
        "/path/to/mcp-db/dist/index.js", // Adjust path if needed
        "--transport", "stdio"
      ],
      // Add "env" if API_KEY is set
      // "env": { "API_KEY": "your-secret-key" }
    }
  }
}

Ejecutando con npx desde GitHub

Puede ejecutar el servidor directamente usando npx (requiere el paso de compilación en el paquete):

# Ensure required env vars are set
export DATABASE_URL="postgresql://user:password@localhost:5432/db"
export GCS_BUCKET="my-bucket"

npx github:dwarvesf/mcp-db --transport sse --port 3001

Herramientas disponibles

duckdb_insert : Ejecuta una instrucción INSERT en la base de datos PostgreSQL adjunta mediante DuckDB. Solo se permiten consultas INSERT .
duckdb_query : Ejecuta una consulta SQL de solo lectura directamente en la base de datos PostgreSQL adjunta ( postgres_db ) mediante la función postgres_query de DuckDB. Prefija automáticamente los nombres de tabla no calificados (p. ej., my_table se convierte en postgres_db.public.my_table ).
duckdb_read_parquet : consulta archivos Parquet utilizando DuckDB (probablemente desde GCS si está configurado).
gcs_directory_tree : obtiene la estructura del árbol de directorios de un depósito GCS con soporte de paginación.

Recursos disponibles

mcp://gcs/objects ( gcs_objects ): enumera los objetos en el depósito GCS configurado.
mcp://db/tables ( sql_tables ): enumera todas las tablas y sus columnas en la base de datos PostgreSQL configurada.

Desarrollo: Integración de una nueva herramienta/recurso

Este proyecto utiliza mcp-framework . Para añadir una nueva herramienta o recurso:

Crear la clase:
- Cree un nuevo archivo .ts en src/tools/ o src/resources/ .
- Defina una clase que extienda MCPTool o MCPResource .
- Implemente las propiedades requeridas ( name , description , schema para herramientas) y métodos ( execute para herramientas, read para recursos).
- Utilice Zod en la propiedad schema para la validación de entrada (herramientas).
- Inicialice cualquier dependencia (como conexiones de base de datos o clientes GCS) dentro de la clase, a menudo en el constructor, potencialmente usando servicios de src/services/ o configuración de src/config.ts .
Herramienta de ejemplo ( src/tools/my_tool.ts ):
import { MCPTool } from "mcp-framework"; import { z } from "zod"; import { formatSuccessResponse } from "../utils.js"; import { getDuckDBConnection } from "../services/duckdb.js"; // Example dependency const MyToolInputSchema = z.object({ param1: z.string().describe("Description for parameter 1"), }); type MyToolInput = z.infer<typeof MyToolInputSchema>; export class MyTool extends MCPTool<MyToolInput> { name = "my_tool"; description = "Description of what my tool does."; schema = { // Matches Zod schema structure param1: { type: z.string(), description: "Description for parameter 1" }, }; async execute(args: MyToolInput): Promise<any> { console.error(`Handling tool request: ${this.name}`); const duckDBConn = getDuckDBConnection(); // Get dependency // ... implement logic using args and duckDBConn ... const result = { message: `Processed ${args.param1}` }; return formatSuccessResponse(result); } } export default MyTool; // Ensure default export
Descubrimiento automático:
- mcp-framework descubre y registra automáticamente las clases de herramientas/recursos que se exportan de forma predeterminada desde los archivos dentro de los directorios src/tools y src/resources .
- Asegúrese de que su nueva clase sea la default export en su archivo.
Prueba:
- Ejecute el servidor ( make dev ).
- Verifique los registros de inicio para asegurarse de que su nueva herramienta/recurso esté en la lista.
- Utilice un cliente MCP (como mcp-cli o MCP Inspector) para llamar a la herramienta o leer el recurso y verificar su funcionalidad.

Mejores prácticas

Defina esquemas de entrada claros utilizando Zod para herramientas.
Maneje los errores con elegancia dentro de execute / read y devuelva respuestas de error formateadas usando formatErrorResponse (o arroje errores).
Utilice la configuración centralizada ( src/config.ts ) a través de getConfig() cuando sea necesario.
Aproveche los inicializadores de servicio en src/services/ para dependencias como conexiones de base de datos.
Agregue registro ( console.error ) para mayor visibilidad.

MCP Database Server

Integrations