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

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):

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

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):

(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:

Ejecutando con npx desde GitHub

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

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 (

   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.