@nexabase/mcp

Servidor MCP (Model Context Protocol) de NexaBase. Conecta tu editor de código (Cursor, VS Code, etc.) con las herramientas y recursos de NexaBase.

¿Qué es MCP?

El Model Context Protocol (MCP) es un protocolo abierto que permite a los editores de código conectarse con servidores que proveen herramientas, recursos y prompts para asistir en el desarrollo.

Instalación

No necesitas instalar nada manualmente. El paquete está diseñado para ejecutarse directamente con npx:

npx -y @nexabase/mcp

Configuración Rápida

1. Obtén tu API Key

1. Inicia sesión en NexaBase
2. Ve a Settings → API Keys
3. Crea una nueva API Key
4. Copia la key (empieza con nxb_)

2. Configura tu Editor

Cursor

Abre la configuración de MCP en Cursor (Cursor → Settings → MCP) y agrega:

{
  "mcpServers": {
    "nexabase": {
      "command": "npx",
      "args": ["-y", "@nexabase/mcp"],
      "env": {
        "NEXABASE_API_KEY": "nxb_tu_api_key_aqui"
      }
    }
  }
}

VS Code (con extensión MCP)

{
  "mcpServers": {
    "nexabase": {
      "command": "npx",
      "args": ["-y", "@nexabase/mcp"],
      "env": {
        "NEXABASE_API_KEY": "nxb_tu_api_key_aqui"
      }
    }
  }
}

Claude Desktop

Edita el archivo de configuración:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nexabase": {
      "command": "npx",
      "args": ["-y", "@nexabase/mcp"],
      "env": {
        "NEXABASE_API_KEY": "nxb_tu_api_key_aqui"
      }
    }
  }
}

3. Reinicia tu Editor

Después de guardar la configuración, reinicia el editor para que cargue el servidor MCP.

Métodos de Configuración

Opción 1: Variables de Entorno en el Editor (Recomendado)

Como se muestra arriba, configura las variables directamente en la configuración del editor.

Opción 2: Archivo .env

Crea un archivo .env en tu proyecto:

NEXABASE_API_KEY=nxb_tu_api_key_aqui
NEXABASE_SERVER_URL=https://api.nexabase.online/api/mcp/sse

Luego en la configuración del editor:

{
  "mcpServers": {
    "nexabase": {
      "command": "npx",
      "args": ["-y", "@nexabase/mcp"]
    }
  }
}

Opción 3: Argumentos CLI

{
  "mcpServers": {
    "nexabase": {
      "command": "npx",
      "args": [
        "-y",
        "@nexabase/mcp",
        "--api-key",
        "nxb_tu_api_key_aqui",
        "--server-url",
        "https://api.nexabase.online/api/mcp/sse"
      ]
    }
  }
}

Variables de Entorno

| Variable | Descripción | Default | Requerida | |----------|-------------|---------|-----------| | NEXABASE_API_KEY | Tu API Key de NexaBase | - | ✅ Sí | | NEXABASE_SERVER_URL | URL del servidor MCP | https://api.nexabase.online/api/mcp/sse | ❌ No | | NEXABASE_VERBOSE | Habilitar logs detallados (true/false) | false | ❌ No |

Argumentos CLI

| Argumento | Alias | Descripción | |-----------|-------|-------------| | --api-key | -k | API Key de NexaBase | | --server-url | -s | URL del servidor MCP remoto | | --verbose | -v | Habilitar logs detallados | | --help | -h | Mostrar ayuda | | --version | - | Mostrar versión |

Herramientas Disponibles

Una vez conectado, tendrás acceso a todas las herramientas de NexaBase. Las herramientas disponibles dependen de tu configuración y permisos.

📚 Descubrir Herramientas Disponibles

Para la IA: Hay varias formas de descubrir qué herramientas están disponibles:

1. Recurso de documentación: Lee system://tools para obtener documentación completa de todas las herramientas

2. Prompt especializado: Usa el prompt tools_info con la categoría que necesites:

   • tools_info(category="all") - Todas las herramientas
   • tools_info(category="collections") - Herramientas de colecciones
   • tools_info(category="workflows") - Herramientas de workflows
   • etc.

3. Lista dinámica: Solicita ListTools para ver la lista actualizada de herramientas registradas

Recomendación: Al iniciar una nueva conversación o cuando necesites usar una herramienta que no conoces, consulta system://tools o usa el prompt tools_info para obtener información detallada sobre:

• Lista completa de herramientas categorizadas
• Descripción de cada herramienta
• Casos de uso recomendados
• Parámetros requeridos
• Mejores prácticas

Herramientas de Colecciones (CRUD)

• list_collections - Listar todas las colecciones del tenant
• get_collection_schema - Obtener el schema de una colección
• create_collection - Crear una nueva colección con schema
• update_collection - Actualizar el schema de una colección
• delete_collection - Eliminar una colección
• get_collection_data - Consultar datos con filtros, paginación y ordenamiento
• insert_collection_data - Insertar un registro individual
• insert_many_records - Insertar múltiples registros en lote (ideal para migraciones de datos)
• update_collection_data - Actualizar un registro existente
• delete_collection_data - Eliminar un registro

Herramientas de Workflows

• list_workflows - Listar todos los workflows
• get_workflow - Obtener detalles de un workflow
• create_workflow - Crear un nuevo workflow
• update_workflow - Actualizar un workflow existente
• delete_workflow - Eliminar un workflow
• execute_workflow - Ejecutar un workflow manualmente
• get_workflow_executions - Obtener historial de ejecuciones

Herramientas de Hooks

• list_hooks - Listar todos los hooks
• create_hook - Crear un nuevo hook
• update_hook - Actualizar un hook existente
• delete_hook - Eliminar un hook

Herramientas de Funciones

• list_functions - Listar todas las funciones
• get_function - Obtener detalles de una función
• create_function - Crear una nueva función
• update_function - Actualizar una función existente
• delete_function - Eliminar una función
• invoke_function - Invocar una función

Herramientas de Storage

• list_files - Listar archivos del storage
• upload_file - Subir un archivo
• download_file - Descargar un archivo
• delete_file - Eliminar un archivo

Herramientas de Vector Store

• list_collections - Listar colecciones vectoriales
• create_collection - Crear colección vectorial
• upsert_document - Insertar/actualizar documento vectorial
• search_documents - Buscar documentos por similitud
• delete_document - Eliminar documento vectorial

Herramientas de Usuarios

• list_users - Listar usuarios del tenant
• create_user - Crear un nuevo usuario
• update_user - Actualizar un usuario
• delete_user - Eliminar un usuario

Herramientas de Tenants

• list_tenants - Listar tenants
• create_tenant - Crear un nuevo tenant
• update_tenant - Actualizar un tenant
• delete_tenant - Eliminar un tenant

Herramientas de Base de Datos

• execute_sql - Ejecutar consultas SQL de solo lectura (SELECT)

Ejemplo: Inserción Masiva de Datos

La herramienta insert_many_records es ideal para migraciones de datos. Ejemplo de uso:

// La IA puede usar esta herramienta automáticamente cuando detecte
// que necesitas insertar múltiples registros

// Ejemplo: Importar 500 productos desde un CSV
insert_many_records({
  collectionName: "productos",
  records: [
    { nombre: "Producto 1", precio: 100, stock: 50 },
    { nombre: "Producto 2", precio: 200, stock: 30 },
    // ... hasta 500 registros
  ],
  batchSize: 100  // Procesa de 100 en 100 para evitar timeouts
})

Características de insert_many_records:

• ✅ Transaccional: Si un registro falla, se revierte todo
• ✅ Validación: Verifica tipos y campos requeridos contra el schema
• ✅ Batching: Procesa en lotes para grandes volúmenes (>1000 registros)
• ✅ Tenant-aware: Inyecta automáticamente el tenant_id
• ✅ Timestamps: Agrega created_at/updated_at si está configurado

Para ver las herramientas disponibles en tu editor:

• Cursor: En la ventana de chat, haz clic en el ícono de herramientas
• VS Code: Revisa la vista de MCP en la barra lateral

Ejemplos de Uso

Ejemplo 1: Inserción Masiva de Datos

@nexabase Necesito importar 500 productos desde este archivo JSON. 
¿Puedes usar insert_many_records para cargarlos en la colección "productos"?

Aquí están los datos:
[
  { "nombre": "Producto 1", "precio": 100, "stock": 50 },
  { "nombre": "Producto 2", "precio": 200, "stock": 30 },
  ...
]

La IA debería:

1. Consultar el schema: get_collection_schema({ collectionName: "productos" })
2. Validar que los datos coincidan
3. Ejecutar: insert_many_records({ collectionName: "productos", records: [...], batchSize: 100 })

Ejemplo 2: Consultar Documentación de Herramientas

@nexabase ¿Qué herramientas tengo disponibles para trabajar con colecciones?

La IA debería:

1. Leer el recurso: system://tools
2. O usar el prompt: tools_info(category="collections")
3. Mostrar la lista de herramientas con descripciones

Ejemplo 3: Migración de Datos desde CSV

@nexabase ¿Puedes buscar información sobre cómo configurar autenticación JWT en NestJS?

Ejemplo 2: Generar Código

@nexabase Crea un servicio de usuarios con TypeORM que tenga métodos para crear, listar y actualizar usuarios.

Ejemplo 3: Analizar Código

@nexabase Analiza este archivo en busca de posibles vulnerabilidades de seguridad.

Troubleshooting

Error: "NEXABASE_API_KEY no configurada"

Causa: La API Key no está configurada correctamente.

Solución:

1. Verifica que la variable NEXABASE_API_KEY esté configurada
2. Asegúrate de que la key empiece con nxb_
3. Reinicia el editor después de configurar

Error: "Failed to connect to server"

Causa: No se puede conectar con el servidor remoto.

Solución:

1. Verifica tu conexión a internet
2. Confirma que la URL del servidor sea correcta
3. Verifica que tu API Key sea válida y no haya expirado
4. Intenta con modo verbose para más detalles:

{
  "mcpServers": {
    "nexabase": {
      "command": "npx",
      "args": ["-y", "@nexabase/mcp", "--verbose"],
      "env": {
        "NEXABASE_API_KEY": "nxb_...",
        "NEXABASE_VERBOSE": "true"
      }
    }
  }
}

Error: "Timeout al conectar"

Causa: El servidor no responde en el tiempo esperado.

Solución:

1. Verifica que el servidor de NexaBase esté disponible
2. Revisa tu firewall/proxy
3. Intenta nuevamente más tarde

Error: "401 Unauthorized"

Causa: La API Key es inválida o expiró.

Solución:

1. Genera una nueva API Key en NexaBase
2. Actualiza la configuración de tu editor
3. Reinicia el editor

Los logs no aparecen

Causa: El modo verbose no está habilitado.

Solución:

• Agrega --verbose a los argumentos o configura NEXABASE_VERBOSE=true

Logs y Debugging

Para habilitar logs detallados:

{
  "mcpServers": {
    "nexabase": {
      "command": "npx",
      "args": ["-y", "@nexabase/mcp", "--verbose"],
      "env": {
        "NEXABASE_API_KEY": "nxb_...",
        "NEXABASE_VERBOSE": "true"
      }
    }
  }
}

Los logs se escriben en stderr y puedes verlos en:

• Cursor: View → Output → NexaBase MCP
• VS Code: View → Output → MCP Servers

Desarrollo Local

Si quieres contribuir o modificar el paquete:

# Clonar repositorio
git clone https://github.com/nexabase/nexabase-mcp.git
cd nexabase-mcp

# Instalar dependencias
npm install

# Desarrollo con hot-reload
npm run dev

# Build para producción
npm run build

# Test local con tu API Key
NEXABASE_API_KEY=nxb_... npm run dev

Requisitos

• Node.js 18.0.0 o superior
• Conexión a internet
• API Key válida de NexaBase

Seguridad

• Nunca compartas tu API Key
• El paquete no almacena tu API Key, solo la usa para autenticar las solicitudes
• Toda la comunicación es HTTPS
• Los logs no incluyen la API Key completa (solo los últimos 4 caracteres)

Licencia

MIT License - ver archivo LICENSE para más detalles.

Soporte

• Documentación: https://docs.nexabase.online
• Issues: https://github.com/nexabase/nexabase-mcp/issues
• Discord: https://discord.gg/nexabase
• Email: [email protected]

Changelog

v1.0.0

• Lanzamiento inicial
• Soporte para herramientas, recursos y prompts
• Conexión SSE con reconexión automática
• Configuración flexible (env, CLI, .env)
• Logs detallados para debugging