mcp-supabase-selfhosted 1.0.0 → 1.2.0

package/.gemini/skills/supabase-selfhosted/SKILL.md

@@ -9,11 +9,11 @@ This skill guides the agent on how to correctly and safely utilize the `supabase
 
 ## 1. When to Use
 Activate this skill whenever the user asks to:
-- "Configurar un usuario de prueba en auth."
-- "Crear un bucket para mis imágenes."
-- "Revisar las políticas de seguridad RLS."
-- "Corregir problemas de rendimiento de la base de datos."
-- "Ver qué columnas tiene una tabla en mi Supabase."
+- "Setup a test user in auth."
+- "Create a bucket for my images."
+- "Review RLS security policies."
+- "Fix database performance issues."
+- "See what columns a table has in my Supabase."
 
 ## 2. Security and RLS (Row Level Security) Mandates
 **Critical:** Because this MCP uses the `SUPABASE_SERVICE_ROLE_KEY` and direct PostgreSQL connections, **it bypasses Row Level Security (RLS) entirely.**
@@ -25,17 +25,18 @@ Activate this skill whenever the user asks to:
 
 ### A. Exploring the Database
 1. Run `list_tables` to see what exists.
-2. Run `get_schema({ table_name: "X" })` to understand the columns before writing any SQL.
-3. Run `get_advisors()` to check if there are missing indexes or security gaps.
+2. Run `get_schema({ table_name: "X" })` to understand columns before writing any SQL.
+3. Run `get_advisors()` to check for missing indexes or security gaps.
+4. Access the source of truth schema via the resource `supabase://database/schema`.
 
 ### B. Configuring Auth
 1. Use `list_users` to see who is registered.
-2. Use `create_user({ email, password, email_confirm: true })` to bootstrap administrative or test accounts without needing an email SMTP server configured locally.
-3. If asked to clean up, use `delete_user({ user_id })`.
+2. Use `create_user({ email, password, email_confirm: true })` to bootstrap administrative or test accounts without needing an SMTP server configured locally.
+3. If asked to clean up, use `delete_user({ user_id, confirm: true })`.
 
 ### C. Configuring Storage (Buckets)
 1. Use `list_buckets()` to check existing buckets.
-2. Use `create_bucket({ bucket: "name", public: true/false })` to make a new one. Remember: making a bucket public allows read access without auth, but RLS policies are still recommended via `storage.objects` table.
+2. Use `create_bucket({ bucket: "name", public: true/false })` to make a new one. Remember: making a bucket public allows read access without auth, but RLS policies are still recommended via the `storage.objects` table.
 3. Use `list_files({ bucket: "name" })` to verify uploads.
 
 ### D. Debugging and Infrastructure

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-06-04
+
+### Changed
+- Translated the entire project to English for global distribution.
+- Updated all tool descriptions and documentation.
+
+## [1.1.0] - 2026-06-04
+
+### Added
+- Full support for MCP Resources (`supabase://database/schema`).
+- Full support for MCP Prompts (`audit-security`).
+- One-command execution support via `npx`.
+- GitHub Actions CI for automated build/test/lint.
+
 ## [1.0.0] - 2026-06-01
 
 ### Added
@@ -14,6 +28,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Auth tools: `list_users`, `create_user`, `delete_user`.
 - Storage tools: `list_buckets`, `create_bucket`, `delete_bucket`, `list_files`.
 - Docker support with Multi-stage builds.
-- One-command execution support via `npx`.
 - Initial test suite and linting configuration.
 - MIT License and community health files.

package/CONTRIBUTING.md

@@ -9,12 +9,12 @@ By participating in this project, you are expected to uphold our Code of Conduct
 ## How Can I Contribute?
 
 ### Reporting Bugs
-- Use the [GitHub Bug Report template](.github/ISSUE_TEMPLATE/bug_report.md).
+- Use the [GitHub Bug Report template](.github/ISSUE_TEMPLATE/bug_report.yml).
 - Provide a clear and descriptive title.
 - Describe the exact steps which reproduce the problem.
 
 ### Suggesting Enhancements
-- Use the [GitHub Feature Request template](.github/ISSUE_TEMPLATE/feature_request.md).
+- Use the [GitHub Feature Request template](.github/ISSUE_TEMPLATE/feature_request.yml).
 - Explain why this enhancement would be useful to most users.
 
 ### Pull Requests

package/README.md

@@ -1,52 +1,55 @@
 # Supabase Self-Hosted MCP Server
 
-Un servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) diseñado específicamente para instancias **Self-Hosted de Supabase**. 
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server designed specifically for **Self-Hosted Supabase** instances.
 
-A diferencia del servidor MCP oficial que depende en gran medida de las APIs de la nube de Supabase y del `project-ref`, esta versión se conecta directamente a tu base de datos PostgreSQL local y a las APIs locales (Auth/Storage) usando tu `SUPABASE_URL` y tu `SERVICE_ROLE_KEY`.
+Unlike the official Supabase MCP server which heavily relies on Supabase Cloud APIs and the `project-ref`, this version connects directly to your local PostgreSQL database and local APIs (Auth/Storage) using your `SUPABASE_URL` and `SERVICE_ROLE_KEY`.
 
-##  Características
+## Features
 
--  **Introspección de Base de Datos:** Lista tablas y esquemas de tu Postgres.
--  **Ejecución SQL Raw:** Ejecuta consultas SQL directamente, permitiendo a la IA leer datos o modificar la estructura (bypass de RLS).
--  **Gestión de Autenticación:** Lista usuarios registrados en tu instancia.
--  **Gestión de Storage:** Lista buckets de almacenamiento.
+- **Database Introspection:** List tables and schemas in your Postgres database.
+- **Raw SQL Execution:** Execute SQL queries directly, allowing the AI to read data or modify the structure (bypassing RLS).
+- **Authentication Management:** List and manage users registered in your instance.
+- **Storage Management:** List buckets and files.
+- **Resources:** Access the complete database schema via URI (`supabase://database/schema`).
+- **Prompts:** Integrated prompt templates for security audits and optimization.
+- **Infrastructure Diagnostics:** Monitor active connections and get performance advisors (unused indexes, cache health).
 
-##  Requisitos
+## Requirements
 
 - Node.js >= 18
-- Docker (opcional, pero recomendado)
+- Docker (optional, but recommended)
 
-##  Instalación y Uso (Local)
+## Installation and Usage (Local)
 
-1. Clona el repositorio:
+1. Clone the repository:
    ```bash
-   git clone https://github.com/tu-usuario/mcp-supabase-selfhosted.git
+   git clone https://github.com/adiego-101/mcp-supabase-selfhosted.git
    cd mcp-supabase-selfhosted
    ```
 
-2. Instala las dependencias y compila:
+2. Install dependencies and build:
    ```bash
    npm install
    npm run build
    ```
 
-3. Crea tu archivo de entorno:
+3. Create your environment file:
    ```bash
    cp .env.example .env
    ```
-   Rellena tus credenciales (asegúrate de usar la **Service Role Key**, ¡nunca la anónima!).
+   Fill in your credentials (ensure you use the **Service Role Key**, never the anonymous one!).
 
-##  Uso con Docker (Recomendado)
+## Usage with Docker (Recommended)
 
-La forma más limpia de utilizar este servidor en clientes IA (Cursor, Claude, Gemini) sin ensuciar tu entorno local es usar la imagen de Docker.
+The cleanest way to use this server in AI clients (Cursor, Claude, Gemini) without cluttering your local environment is to use the Docker image.
 
-1. Construye la imagen localmente:
+1. Build the image locally:
    ```bash
    docker build -t supabase-selfhosted-mcp .
    ```
 
-### Configuración en Claude Desktop / Cursor
-Añade lo siguiente a tu archivo `claude_desktop_config.json` o configuración de Cursor:
+### Configuration in Claude Desktop / Cursor
+Add the following to your `claude_desktop_config.json` or Cursor configuration:
 
 ```json
 {
@@ -58,7 +61,7 @@ Añade lo siguiente a tu archivo `claude_desktop_config.json` o configuración d
         "-i",
         "--rm",
         "-e", "SUPABASE_URL=http://host.docker.internal:8000",
-        "-e", "SUPABASE_SERVICE_ROLE_KEY=tu-clave-aqui",
+        "-e", "SUPABASE_SERVICE_ROLE_KEY=your-key-here",
         "-e", "DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/postgres",
         "supabase-selfhosted-mcp"
       ]
@@ -66,39 +69,24 @@ Añade lo siguiente a tu archivo `claude_desktop_config.json` o configuración d
   }
 }
 ```
-*(Nota: usa `host.docker.internal` en lugar de `localhost` si tu base de datos corre en tu máquina host).*
+*(Note: use `host.docker.internal` instead of `localhost` if your database is running on your host machine).*
 
-### Configuración en Gemini CLI
-Puedes añadirlo en tu archivo `~/.gemini/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "supabase-selfhosted": {
-      "command": "docker",
-      "args": [
-        "run",
-        "-i",
-        "--rm",
-        "-e", "SUPABASE_URL=...",
-        "-e", "SUPABASE_SERVICE_ROLE_KEY=...",
-        "-e", "DATABASE_URL=...",
-        "supabase-selfhosted-mcp"
-      ]
-    }
-  }
-}
+### One-Command Usage (via npx)
+If you have the package installed or want to run it directly:
+```bash
+npx mcp-supabase-selfhosted
 ```
 
-##  Seguridad y Buenas Prácticas
+## Security and Best Practices
 
-- **Acceso Directo:** Este MCP utiliza conexiones directas a DB y la `SERVICE_ROLE_KEY`. Esto significa que la IA conectada tendrá acceso **total y sin restricciones (bypassing RLS)** a tu instancia.
-- **Entornos:** Se recomienda encarecidamente utilizar esto **sólo en entornos de desarrollo local**, nunca apuntando a una base de datos de producción con datos reales sensibles.
-- **Transporte:** El servidor usa `stdio` (entrada/salida estándar), lo cual es el protocolo de seguridad predeterminado en aplicaciones de escritorio como Cursor y Claude.
+- **Direct Access:** This MCP uses direct DB connections and the `SERVICE_ROLE_KEY`. This means the connected AI will have **full, unrestricted access (bypassing RLS)** to your instance.
+- **Environments:** It is strongly recommended to use this **only in local development environments**, never pointing to a production database with sensitive real data.
+- **Transport:** The server uses `stdio` (standard input/output), which is the default security protocol in desktop applications like Cursor and Claude.
+- **Destructive Actions:** Tools like `delete_user` or `delete_bucket` require an explicit `confirm: true` flag to prevent accidental data loss.
 
-##  Contribuir
+## Contributing
 
-¡Las contribuciones son bienvenidas! Sientete libre de abrir Issues o Pull Requests. Si planeas añadir una herramienta nueva, añádela en el directorio `src/tools/`.
+Contributions are welcome! Feel free to open Issues or Pull Requests. If you plan to add a new tool, add it to the `src/tools/` directory.
 
-## Licencia
+## License
 MIT

package/SECURITY.md

@@ -4,10 +4,10 @@
 
 Currently, only the latest version of the Supabase Self-Hosted MCP server is supported with security updates.
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 1.0.x   | :white_check_mark: |
-| < 1.0   | :x:                |
+| Version | Supported |
+| ------- | --------- |
+| 1.x.x   | ✅        |
+| < 1.0   | ❌        |
 
 ## Reporting a Vulnerability
 

package/dist/config/env.js

@@ -5,12 +5,9 @@ dotenv.config();
 // Esquema de validación para las variables de entorno
 const envSchema = z
     .object({
-    SUPABASE_URL: z.string().url('La URL de Supabase debe ser válida').optional(),
+    SUPABASE_URL: z.string().url('Supabase URL must be a valid URL').optional(),
     SUPABASE_SERVICE_ROLE_KEY: z.string().optional(),
-    DATABASE_URL: z
-        .string()
-        .url('La URL de la base de datos (Postgres) debe ser válida')
-        .optional(),
+    DATABASE_URL: z.string().url('Database URL (Postgres) must be a valid URL').optional(),
 })
     .refine((data) => {
     // Al menos una de las dos formas de conexión debe estar configurada
@@ -18,7 +15,7 @@ const envSchema = z
     const hasDBConnection = !!data.DATABASE_URL;
     return hasSupabaseAPI || hasDBConnection;
 }, {
-    message: 'Debes configurar al menos DATABASE_URL o (SUPABASE_URL y SUPABASE_SERVICE_ROLE_KEY)',
+    message: 'You must configure at least DATABASE_URL or (SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY)',
 });
 export function getConfig() {
     try {
@@ -27,7 +24,7 @@ export function getConfig() {
     }
     catch (error) {
         if (error instanceof z.ZodError) {
-            console.error(' Error de configuración. Faltan variables de entorno o son inválidas:');
+            console.error(' Configuration error. Environment variables are missing or invalid:');
             error.issues.forEach((e) => console.error(`  - ${e.message}`));
             process.exit(1);
         }

package/dist/db/postgres.js

@@ -10,26 +10,26 @@ export async function getDbPool() {
     }
     const config = getConfig();
     if (!config.DATABASE_URL) {
-        throw new Error('DATABASE_URL no está configurada. Las herramientas de base de datos directa no funcionarán.');
+        throw new Error('DATABASE_URL is not configured. Direct database tools will not work.');
     }
     pgPool = new Pool({
         connectionString: config.DATABASE_URL,
-        max: 10, // Límite máximo de conexiones activas para este MCP
-        idleTimeoutMillis: 30000, // Cerrar conexiones inactivas después de 30s
-        connectionTimeoutMillis: 5000, // Abortar intentos de conexión lentos
-        statement_timeout: 10000, // (10s) Abortar consultas pesadas/erróneas generadas por la IA
+        max: 10, // Maximum active connections for this MCP
+        idleTimeoutMillis: 30000, // Close idle connections after 30s
+        connectionTimeoutMillis: 5000, // Abort slow connection attempts
+        statement_timeout: 10000, // (10s) Abort heavy/incorrect queries generated by the AI
     });
     try {
-        // Verificamos la conexión con una consulta sencilla
+        // Verify connection with a simple query
         const client = await pgPool.connect();
         client.release();
-        console.error(' Conectado exitosamente a PostgreSQL (Pool con timeouts configurados).');
+        console.error(' Successfully connected to PostgreSQL (Pool with timeouts configured).');
         return pgPool;
     }
     catch (error) {
         pgPool = null;
         const msg = error instanceof Error ? error.message : String(error);
-        console.error(' Error conectando a PostgreSQL:', msg);
+        console.error(' Error connecting to PostgreSQL:', msg);
         throw error;
     }
 }
@@ -44,7 +44,7 @@ export async function query(sql, params = []) {
     }
     catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
-        console.error(' Error ejecutando query:', msg);
+        console.error(' Error executing query:', msg);
         throw error;
     }
 }

package/dist/index.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { getConfig } from './config/env.js';
 import { toolsDefinitions, handleExecuteSql, handleListBuckets, handleCreateBucket, handleDeleteBucket, handleListTables, handleListUsers, handleCreateUser, handleDeleteUser, handleGetSchema, handleGetAdvisors, handleListFiles, handleListRlsPolicies, handleGetActiveConnections, } from './tools/index.js';
+import { query } from './db/postgres.js';
 async function main() {
     // 1. Validar la configuración al inicio
     getConfig();
@@ -14,8 +15,72 @@ async function main() {
     }, {
         capabilities: {
             tools: {},
+            resources: {},
+            prompts: {},
         },
     });
+    // --- RECURSOS (Resources) ---
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        return {
+            resources: [
+                {
+                    uri: 'supabase://database/schema',
+                    name: 'Complete database schema',
+                    description: 'Returns the structure of all tables and columns in the public schema.',
+                    mimeType: 'application/json',
+                },
+            ],
+        };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        if (request.params.uri === 'supabase://database/schema') {
+            const sql = `
+        SELECT table_name, column_name, data_type 
+        FROM information_schema.columns 
+        WHERE table_schema = 'public'
+        ORDER BY table_name, ordinal_position;
+      `;
+            const rows = await query(sql);
+            return {
+                contents: [
+                    {
+                        uri: request.params.uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(rows, null, 2),
+                    },
+                ],
+            };
+        }
+        throw new Error('Resource not found');
+    });
+    // --- PROMPTS ---
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        return {
+            prompts: [
+                {
+                    name: 'audit-security',
+                    description: 'Performs a complete security audit of the Supabase instance.',
+                },
+            ],
+        };
+    });
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        if (request.params.name === 'audit-security') {
+            return {
+                description: 'Supabase Security Audit',
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: 'Please perform the following steps to audit my instance:\n1. Use get_advisors to detect performance and RLS issues.\n2. Use list_rls_policies to review all active access rules.\n3. Use get_active_connections to see if there are suspicious accesses or blocks.\n4. Finally, provide a detailed report with security recommendations.',
+                        },
+                    },
+                ],
+            };
+        }
+        throw new Error('Prompt not found');
+    });
     // 3. Registrar el manejador para listar herramientas (Tools)
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         return {
@@ -59,9 +124,9 @@ async function main() {
     // 5. Configurar el transporte stdio (entrada/salida estándar)
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error(' Servidor MCP de Supabase Self-Hosted iniciado correctamente.');
+    console.error(' Supabase Self-Hosted MCP Server started successfully.');
 }
 main().catch((error) => {
-    console.error(' Error fatal al iniciar el servidor MCP:', error);
+    console.error(' Fatal error starting MCP server:', error);
     process.exit(1);
 });

package/dist/supabase/client.js

@@ -10,17 +10,17 @@ export function getSupabaseClient() {
     }
     const config = getConfig();
     if (!config.SUPABASE_URL || !config.SUPABASE_SERVICE_ROLE_KEY) {
-        throw new Error('SUPABASE_URL y SUPABASE_SERVICE_ROLE_KEY son obligatorias para utilizar las herramientas de Auth y Storage.');
+        throw new Error('SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are required to use Auth and Storage tools.');
     }
-    // Creamos el cliente usando la service role key.
-    // IMPORTANTE: En el contexto de un MCP (que actúa como un super admin), es seguro
-    // y necesario usar la service role key, pero el usuario debe estar consciente de esto.
+    // Create client using the service role key.
+    // IMPORTANT: In an MCP context (acting as super admin), it is safe
+    // and necessary to use the service role key, but the user should be aware of this.
     supabaseClient = createClient(config.SUPABASE_URL, config.SUPABASE_SERVICE_ROLE_KEY, {
         auth: {
             autoRefreshToken: false,
             persistSession: false,
         },
     });
-    console.error(' Cliente Supabase API inicializado.');
+    console.error(' Supabase API client initialized.');
     return supabaseClient;
 }