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 )

Related MCP server: PostgreSQL MCP Server

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

1. Clonar el repositorio:

   git clone <repository-url>
   cd mcp-db

2. Instalar dependencias (se recomienda utilizar Devbox para mantener la coherencia):

   devbox install
   # Or using npm directly if not using Devbox
   # npm install

3. Copie .env.example a .env y complete sus variables de entorno.

   cp .env.example .env
   # Edit .env with your details

4. 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).

• duckdb_update : ejecuta una declaración UPDATE en la base de datos PostgreSQL adjunta a través de DuckDB.

• 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 : enumera los objetos en el depósito GCS configurado.

• mcp://db/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:

1. 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

2. 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.

3. 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.