SupaMCP Server

SupaMCPBuilder

Un servidor MCP (Model Context Protocol) configurable en tiempo de ejecución para bases de datos Supabase con soporte de configuración JSON en línea. ¡Crea herramientas dinámicas para tu base de datos Supabase sin escribir código!

Características

• 🚀 Configuración Cero: Funciona de inmediato con cualquier proyecto de Supabase
• 🔧 Configurable en Tiempo de Ejecución: Define herramientas usando configuración JSON
• 🔐 Autenticación Integrada: Renovación automática de tokens JWT y gestión de sesiones
• 📊 Generación Dinámica de Herramientas: Crea operaciones de base de datos personalizadas mediante JSON
• 🎯 Soporte de Plantillas: Usa plantillas estilo Jinja2 en tus configuraciones
• 🔄 Soporte Base64: Maneja configuraciones JSON complejas de forma segura

Inicio Rápido

Uso con npx (Recomendado)

npx supamcpbuilder --url YOUR_SUPABASE_URL --anon-key YOUR_ANON_KEY --email YOUR_EMAIL --password YOUR_PASSWORD --tools-json-base64 BASE64_ENCODED_TOOLS

Instalación

npm install -g supamcpbuilder

Opciones de Configuración

Uso Básico

supamcpbuilder \
  --url "https://your-project.supabase.co" \
  --anon-key "your-anon-key" \
  --email "your-email@example.com" \
  --password "your-password"

Con Archivo de Configuración JSON

supamcpbuilder \
  --url "https://your-project.supabase.co" \
  --anon-key "your-anon-key" \
  --email "your-email@example.com" \
  --password "your-password" \
  --config-path "./tools-config.json"

Con Herramientas Codificadas en Base64

supamcpbuilder \
  --url "https://your-project.supabase.co" \
  --anon-key "your-anon-key" \
  --email "your-email@example.com" \
  --password "your-password" \
  --tools-json-base64 "W3sibmFtZSI6Imxpc3QtdXNlcnMiLCJkZXNjcmlwdGlvbiI6Ikxpc3QgYWxsIHVzZXJzIn1d"

Formato de Configuración de Herramientas

Estructura Básica de Herramientas

[
  {
    "name": "list-users",
    "description": "List all users from the users table",
    "parameters": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "number",
          "description": "Number of users to return",
          "default": 10
        }
      }
    },
    "action": {
      "type": "select",
      "table": "users",
      "columns": ["id", "name", "email"],
      "limit": "{{limit}}"
    }
  }
]

Tipos de Acción Soportados

• select: Consulta datos de tablas
• insert: Crea nuevos registros
• update: Modifica registros existentes
• delete: Elimina registros

Variables de Plantilla

Usa plantillas estilo Jinja2 en tus configuraciones:

{
  "action": {
    "type": "select",
    "table": "{{table_name}}",
    "filters": {
      "id": "{{user_id}}"
    }
  }
}

Configuración del Cliente MCP

Configuración de Cursor IDE

Añade a tu ~/.cursor/mcp.json:

{
  "mcpServers": {
    "supamcpbuilder": {
      "command": "npx",
      "args": [
        "-y",
        "supamcpbuilder",
        "--url", "https://your-project.supabase.co",
        "--anon-key", "your-anon-key",
        "--email", "your-email@example.com",
        "--password", "your-password",
        "--tools-json-base64", "YOUR_BASE64_ENCODED_TOOLS"
      ]
    }
  }
}

Configuración de Claude Desktop

Añade a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "supamcpbuilder": {
      "command": "npx",
      "args": [
        "-y",
        "supamcpbuilder",
        "--url", "https://your-project.supabase.co",
        "--anon-key", "your-anon-key",
        "--email", "your-email@example.com",
        "--password", "your-password",
        "--config-path", "/path/to/your/tools-config.json"
      ]
    }
  }
}

Variables de Entorno

También puedes usar variables de entorno:

export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_ANON_KEY="your-anon-key"
export SUPABASE_EMAIL="your-email@example.com"
export SUPABASE_PASSWORD="your-password"

supamcpbuilder --config-path "./tools-config.json"

Configuración Avanzada

Ejemplo de Herramienta Compleja

[
  {
    "name": "create-user-with-profile",
    "description": "Create a new user with profile information",
    "parameters": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "User's full name"
        },
        "email": {
          "type": "string",
          "description": "User's email address"
        },
        "bio": {
          "type": "string",
          "description": "User's biography"
        }
      },
      "required": ["name", "email"]
    },
    "action": {
      "type": "insert",
      "table": "users",
      "values": {
        "name": "{{name}}",
        "email": "{{email}}",
        "bio": "{{bio}}",
        "created_at": "now()"
      },
      "returning": ["id", "name", "email"]
    }
  }
]

Autenticación y Seguridad

• Autenticación de Usuario: Usa correo electrónico/contraseña con renovación automática de JWT
• Seguridad a Nivel de Fila: Todas las operaciones respetan tus políticas RLS de Supabase
• Seguro por Defecto: Sin acceso de administrador, se centra en operaciones a nivel de usuario
• Renovación Automática de Tokens: Maneja la expiración de JWT automáticamente

Solución de Problemas

Problemas Comunes

1. Errores de Autenticación: Asegúrate de que tu combinación de correo electrónico/contraseña sea correcta
2. Permiso Denegado: Revisa tus políticas RLS y permisos de usuario
3. Herramienta No Encontrada: Verifica la sintaxis de tu configuración JSON
4. Problemas de Conexión: Confirma tu URL de Supabase y tus claves API

Modo de Depuración

Habilita el registro de depuración:

DEBUG=supamcpbuilder supamcpbuilder --url ... --anon-key ...

Ejemplos

Revisa el directorio examples/ para:

• Configuraciones de ejemplo de herramientas
• Ejemplos de configuración de clientes MCP
• Casos de uso comunes

Contribuciones

1. Haz un fork del repositorio
2. Crea tu rama de características (git checkout -b feature/amazing-feature)
3. Haz commit de tus cambios (git commit -m 'Add some amazing feature')
4. Haz push a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Soporte

• 🐛 Reportes de Errores: GitHub Issues
• 💡 Solicitudes de Funciones: GitHub Discussions
• 📖 Documentación: Consulta el directorio de ejemplos para más detalles

Registro de Cambios

v1.0.0

• Lanzamiento inicial
• Funcionalidad básica del servidor MCP
• Soporte de configuración JSON
• Soporte de codificación Base64
• Manejo de autenticación
• Soporte de variables de plantilla