Plan de implementación del servidor Supabase MCP

Este documento describe el plan para crear un servidor de Protocolo de contexto de modelo (MCP) que se conecta a Supabase, lo que permite que los asistentes de IA como GitHub Copilot interactúen con su base de datos de Supabase.

Tabla de contenido

Descripción general
Prerrequisitos
Pasos de implementación
Arquitectura del servidor
Configuración
Consideraciones de seguridad
Guía de instalación
Ejemplos de uso
Solución de problemas

Descripción general

El servidor MCP de Supabase actuará como puente entre los asistentes de IA (como GitHub Copilot) y su base de datos de Supabase. Esto permite que la IA:

Comprenda el esquema de su base de datos
Conozca las tablas y relaciones
Ayudar con la redacción de consultas
Proporcionar sugerencias sensibles al contexto relacionadas con su modelo de datos

Prerrequisitos

Node.js 18+ instalado
gestor de paquetes npm o yarn
Proyecto Supabase con clave API de administrador
VS Code con soporte para Copilot/MCP
Git

Pasos de implementación

1. Crear paquete de servidor

mkdir mcp-server-supabase
cd mcp-server-supabase
npm init -y

2. Instalar dependencias

npm install @supabase/supabase-js @modelcontextprotocol/server dotenv

3. Estructura básica del servidor

Crea estos archivos:

src/index.js - Punto de entrada principal
src/supabase-client.js - Manejo de conexión de Supabase
src/schema-provider.js - Extracción del esquema de la base de datos
src/query-handler.js - Ejecución segura de consultas
.env.example - Plantilla de variable de entorno
config.js - Gestión de configuración

4. Detalles de la implementación del servidor

src/index.js

Este archivo inicializará el servidor MCP y conectará los componentes:

const { MCPServer } = require('@modelcontextprotocol/server');
const { getSupabaseClient } = require('./supabase-client');
const { SchemaProvider } = require('./schema-provider');
const { QueryHandler } = require('./query-handler');
const config = require('./config');

async function main() {
  try {
    // Initialize Supabase client
    const supabaseClient = getSupabaseClient(config.supabase.url, config.supabase.key);
    
    // Create providers
    const schemaProvider = new SchemaProvider(supabaseClient);
    const queryHandler = new QueryHandler(supabaseClient, config.security.allowedQueries);
    
    // Initialize MCP server
    const server = new MCPServer({
      name: 'mcp-server-supabase',
      version: '1.0.0',
    });
    
    // Register handlers
    server.registerHandler('getSchema', async () => {
      return await schemaProvider.getFullSchema();
    });
    
    server.registerHandler('getTableInfo', async (params) => {
      return await schemaProvider.getTableInfo(params.tableName);
    });
    
    server.registerHandler('executeQuery', async (params) => {
      return await queryHandler.execute(params.query, params.params);
    });
    
    // Start the server
    await server.start();
    console.log('MCP Supabase server is running');
  } catch (error) {
    console.error('Failed to start MCP server:', error);
    process.exit(1);
  }
}

main();

src/subabase-client.js

const { createClient } = require('@supabase/supabase-js');

function getSupabaseClient(url, apiKey) {
  if (!url || !apiKey) {
    throw new Error('Supabase URL and API key must be provided');
  }
  
  return createClient(url, apiKey, {
    auth: { persistSession: false },
  });
}

module.exports = { getSupabaseClient };

src/schema-provider.js

class SchemaProvider {
  constructor(supabaseClient) {
    this.supabase = supabaseClient;
  }
  
  async getFullSchema() {
    // Query Supabase for full database schema
    const { data, error } = await this.supabase
      .rpc('get_schema_information', {});
    
    if (error) throw new Error(`Failed to get schema: ${error.message}`);
    
    return data;
  }
  
  async getTableInfo(tableName) {
    // Get detailed information about a specific table
    const { data, error } = await this.supabase
      .rpc('get_table_information', { table_name: tableName });
    
    if (error) throw new Error(`Failed to get table info: ${error.message}`);
    
    return data;
  }
}

module.exports = { SchemaProvider };

src/query-handler.js

class QueryHandler {
  constructor(supabaseClient, allowedQueryTypes = ['SELECT']) {
    this.supabase = supabaseClient;
    this.allowedQueryTypes = allowedQueryTypes; 
  }
  
  validateQuery(queryString) {
    // Basic SQL injection prevention and query type validation
    const normalizedQuery = queryString.trim().toUpperCase();
    
    // Check if the query starts with allowed query types
    const isAllowed = this.allowedQueryTypes.some(
      type => normalizedQuery.startsWith(type)
    );
    
    if (!isAllowed) {
      throw new Error(`Query type not allowed. Allowed types: ${this.allowedQueryTypes.join(', ')}`);
    }
    
    return true;
  }
  
  async execute(queryString, params = {}) {
    // Validate query before execution
    this.validateQuery(queryString);
    
    // Execute the query through Supabase
    const { data, error } = await this.supabase
      .rpc('execute_query', { query_string: queryString, query_params: params });
    
    if (error) throw new Error(`Query execution failed: ${error.message}`);
    
    return data;
  }
}

module.exports = { QueryHandler };

config.js

require('dotenv').config();

module.exports = {
  supabase: {
    url: process.env.SUPABASE_URL,
    key: process.env.SUPABASE_SERVICE_KEY,
  },
  server: {
    port: process.env.PORT || 3000,
  },
  security: {
    allowedQueries: process.env.ALLOWED_QUERY_TYPES 
      ? process.env.ALLOWED_QUERY_TYPES.split(',') 
      : ['SELECT'],
  }
};

.env.ejemplo

SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_SERVICE_KEY=your-service-key
PORT=3000
ALLOWED_QUERY_TYPES=SELECT

5. Funciones de la base de datos Supabase

Necesitarás crear estos procedimientos almacenados en Supabase:

get_schema_information() - Devuelve el esquema de la base de datos
get_table_information(table_name TEXT) - Devuelve información sobre una tabla específica
execute_query(query_string TEXT, query_params JSONB) - Ejecuta consultas de forma segura

Arquitectura del servidor

┌─────────────────────┐      ┌───────────────────┐
│                     │      │                   │
│  VS Code + Copilot  │◄────►│   MCP Protocol    │
│                     │      │                   │
└─────────────────────┘      └─────────┬─────────┘
                                      │
                                      ▼
                            ┌─────────────────────┐
                            │                     │
                            │ Supabase MCP Server │
                            │                     │
                            └─────────┬───────────┘
                                      │
                                      ▼
                            ┌─────────────────────┐
                            │                     │
                            │  Supabase Database  │
                            │                     │
                            └─────────────────────┘

Configuración

Agregue el servidor Supabase MCP a su settings.json de VS Code:

"mcp": {
  "inputs": [],
  "servers": {
    // ...existing servers...
    "mcp-server-supabase": {
      "command": "node",
      "args": [
        "/path/to/mcp-server-supabase/src/index.js"
      ],
      "env": {
        "SUPABASE_URL": "https://your-project-ref.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-key",
        "ALLOWED_QUERY_TYPES": "SELECT"
      }
    }
  }
}

Consideraciones de seguridad

Gestión de claves API :
- Utilice una clave API con alcance y con los permisos mínimos requeridos
- Almacene las claves API de forma segura, nunca se comprometa con el control de versiones
- Considere utilizar una estrategia de rotación de claves
Restricciones de consulta :
- El valor predeterminado es SELECCIONAR únicamente por seguridad
- Considere implementar un enfoque de lista de consultas permitidas
- Añadir limitación de velocidad para evitar el abuso
Protección de datos :
- Evite exponer información personal identificable (PII) o datos confidenciales
- Implementar seguridad a nivel de fila en Supabase
- Considere agregar enmascaramiento de datos para campos sensibles

Guía de instalación

Desarrollo local

Clonar el repositorio
git clone https://github.com/yourusername/mcp-server-supabase.git cd mcp-server-supabase
Instalar dependencias
npm install
Crear un archivo .env a partir del ejemplo
cp .env.example .env
Edite .env con sus credenciales de Supabase
Iniciar el servidor
node src/index.js

Integración de VS Code

Actualice su settings.json de VS Code con la configuración del servidor
Reiniciar VS Code
Verifique que el servidor se esté ejecutando en el panel MCP de VS Code

Ejemplos de uso

Una vez integrado, puede utilizar el servidor Supabase MCP de varias maneras:

Exploración de esquemas:
What tables do I have in my Supabase database?
Información de la tabla:
What columns are in the users table?
Asistencia en consultas:
Help me write a query to get all users who signed up in the last 7 days

Solución de problemas

El servidor no se inicia

Comprueba tu versión de Node.js (debe ser mayor de 18 años)
Verifique sus credenciales de Supabase
Comprobar registros de errores en la terminal

El esquema no se carga

Verifique que su clave de servicio de Supabase tenga los permisos necesarios
Compruebe que las funciones de la base de datos se hayan creado correctamente

VS Code no se puede conectar

Verifique que la ruta del servidor en settings.json sea correcta
Reiniciar VS Code después de los cambios de configuración
Verifique que el proceso del servidor se esté ejecutando

Integrations