npm package: @nexabase/mcp
Description: NexaBase MCP Server - Connect your editor to NexaBase AI tools and resources
Author: NexaBase Team
Latest version: 1.0.7

# @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`:

```bash
npx -y @nexabase/mcp
```

## Configuración Rápida

### 1. Obtén tu API Key

1. Inicia sesión en [NexaBase](https://dashboard.nexabase.online)
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:

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

#### VS Code (con extensión MCP)

```json
{
  "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`

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

```bash
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:

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

### Opción 3: Argumentos CLI

```json
{
  "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:

```typescript
// 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:

```json
{
  "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:

```json
{
  "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:

```bash
# 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](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:** support@nexabase.online

## 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