csvbox-mcp-server

Un servidor universal Model Context Protocol (MCP) para CSVBox. Expone la gestión de hojas de importación de CSVBox como herramientas MCP para que puedas crear, reemplazar, parchear, generar, validar y estructurar importadores desde cualquier cliente compatible con MCP — Claude Desktop, Cursor, Windsurf, Roo Code, Cline, VS Code, ChatGPT MCP y más.

Se ejecuta sobre stdio, por lo que funciona igual en todos los clientes.

Herramientas

CSVBox actualmente no tiene endpoints GET o LIST, por lo que intencionalmente no hay herramientas get_sheet / list_sheet.

También expone dos prompts MCP:

Generación de hoja a partir de prompt

generate_sheet_json y create_importer_from_prompt usan un LLM para convertir una solicitud de forma libre en una hoja CSVBox completa — title, sheet_columns, destinations, webhooks, security_settings y steps. Solo los campos de datos reales se convierten en columnas; los destinos, webhooks, dominios, regiones, configuración de carga de archivos y pasos se colocan en sus secciones de configuración correspondientes, nunca se convierten en columnas. Hay tres niveles:

1. LLM del servidor — cuando se establece ANTHROPIC_API_KEY o OPENAI_API_KEY, el servidor llama directamente al LLM. Funciona en MCP Inspector y sin interfaz.

2. Prompt MCP (create_csvbox_sheet) — cuando no tienes clave de servidor, los clientes anfitriones (Cursor, Claude Desktop, Cline) ejecutan la generación con su propio modelo y luego llaman a validate_schema y create_sheet. Gratis.

3. Ninguno configurado — generate_sheet_json devuelve un error estructurado de "no hay proveedor de LLM configurado" que apunta al prompt MCP, y create_importer_from_prompt no llama a la API de CSVBox. No hay respaldo con regex.

Expansión de categoría / módulo

El generador se ejecuta en uno de dos modos, elegidos automáticamente según el prompt:

• Extracción (predeterminado) — el prompt nombra campos concretos (p. ej. "columnas nombre, correo, teléfono"). Solo esos se convierten en columnas; no se inventa nada.

• Expansión — el prompt nombra módulos / categorías de negocio como lista (p. ej. "módulos para: Información de la empresa, Proveedores, Nómina, Factura"), solicita un esquema completo/detallado, o pide un número de columnas ("al menos 100 columnas"). Cada módulo nombrado se expande en varias columnas realistas, con prefijo y tipo correcto (p. ej. Proveedores → supplier_id, supplier_name, supplier_gstin, supplier_email, …). Se respeta un recuento mínimo explícito y cada column_name es globalmente único.

Los tipos de datos y las validaciones se infieren de los nombres de los campos y de cualquier tipo solicitado:

Esquemas grandes: los modelos predeterminados (claude-haiku-4-5, gpt-4o-mini) son baratos pero producen esquemas de 100+ columnas notablemente mejores cuando se sobrescribe con un modelo más potente mediante LLM_MODEL (p. ej. claude-sonnet-4-6). El límite de salida se eleva para adaptarse a hojas grandes; si una solicitud sigue siendo demasiado grande, la respuesta se marca como TRUNCATED (un resultado distinto, no un error de análisis) y no se llama a la API de CSVBox — reduce el número de columnas / módulos o usa un modelo con mayor presupuesto de salida y reintenta.

Related MCP server: mcp-tabular

Colecciones de funciones (columnas virtuales, funciones de validación, transformaciones de datos)

Además de las seis propiedades de la hoja, la API de hojas de CSVBox acepta tres colecciones cuyos elementos llevan una cadena js_code que CSVBox ejecuta durante una importación:

Dentro de js_code, el objeto csvbox expone row, column, virtual, user, import y environment. Los dos accesores no son intercambiables: una columna virtual es por fila y usa csvbox.row.<name> (un escalar), mientras que una función con ámbito "column" ve toda la columna mediante csvbox.column.<name> (un array).

Campos opcionales compartidos: scope (column | row; no en columnas virtuales), run_at (before_validation | after_validation; solo transformaciones de datos), columns / dynamic_columns, active, dependencies y _delete (solo PATCH).

Creación de estas funciones

// generate_sheet_functions  (requires ANTHROPIC_API_KEY or OPENAI_API_KEY)
{
  "prompt": "add a virtual column joining first and last name, and check every email contains an @",
  "sheet": { "title": "Customers", "sheet_columns": [ ... ] }
}

Devuelve { "virtual_columns": [...], "validation_functions": [...], "source": ..., "validation": {...} }. Las colecciones que la solicitud no implica se omiten, nunca se devuelven como arrays vacíos.

Esta herramienta no llama a la API de CSVBox. Lee el js_code generado y luego aplícalo tú mismo con patch_sheet. Pasa sheet para que el modelo haga referencia a nombres de columna reales y el validador pueda comprobar esas referencias — CSVBox no tiene endpoint de lectura, por lo que debe proporcionarse en línea. Sin una clave LLM, usa el prompt MCP csvbox_sheet_functions en su lugar.

PUT vs PATCH — lee esto antes de aplicar

Usa patch_sheet para aplicar las funciones generadas. Valida primero con el verbo correspondiente:

// validate_schema
{ "sheet": { "data_transforms": [ ... ] }, "mode": "patch" }

mode es create (predeterminado), put o patch. Solo afecta a las colecciones de funciones: bajo put, un array vacío es un error grave en lugar de una advertencia, y _delete se rechaza fuera de patch.

Dependencias

Un elemento puede cargar hasta 5 scripts de terceros:

{ "url": "https://cdn.jsdelivr.net/npm/dayjs@1.11.10/dayjs.min.js",
  "globals": ["dayjs"],
  "integrity": "sha384-..." }

Solo se permiten cdn.jsdelivr.net, unpkg.com y cdnjs.cloudflare.com; solo https, ruta .js/.mjs, sin cadena de consulta, fragmento, información de usuario ni puerto.

Seguridad. Este servidor nunca ejecuta js_code — aquí es una cadena opaca. El JavaScript generado es salida de modelo sin revisar, así que léelo antes de aplicarlo con PATCH a un importador en vivo. Una dependencia sin un resumen integrity puede cambiar bajo tus clientes en cualquier momento; validate_schema advierte cuando falta uno.

Consulta docs/sheet-functions-example.json para un payload completo.

Instalación

npm install @csvbox/mcp-server

O compilar desde el código fuente:

git clone <this-repo> csvbox-mcp-server
cd csvbox-mcp-server
npm install
npm run build

Esto produce dist/index.js — el punto de entrada que lanzan los clientes MCP.

Variables de entorno

Copia .env.example a .env y completa tus credenciales de CSVBox:

CSVBOX_API_KEY=your_api_key
CSVBOX_API_SECRET=your_api_secret

Las credenciales de CSVBox solo son necesarias para las herramientas respaldadas por API (create_sheet, update_sheet, patch_sheet, create_importer_from_prompt). validate_schema y generate_import_code funcionan sin credenciales.

Nota sobre el encabezado de autenticación: el cliente envía x-csvbox-api-key y x-csvbox-secret-api-key (coincidiendo con los payloads de referencia de CSVBox). Estos se definen como constantes en src/services/csvbox-api.ts si tu cuenta usa nombres de encabezado diferentes.

Proveedor de LLM (para generación de hoja a partir de prompt)

generate_sheet_json y create_importer_from_prompt necesitan un LLM. Establece uno de:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

El proveedor se detecta automáticamente:

LLM_PROVIDER desambigua cuando ambas claves están presentes; LLM_MODEL anula el modelo para el proveedor elegido. Para esquemas grandes de categorías/módulos (más de 100 columnas), establece LLM_MODEL a un modelo más potente (p. ej. claude-sonnet-4-6) — consulta Expansión de categorías / módulos.

MCP Inspector: establece la clave LLM en el panel de variables de entorno del Inspector para usar la ruta del LLM del servidor. El Inspector no tiene un LLM anfitrión propio, por lo que puede renderizar el prompt create_csvbox_sheet pero no puede ejecutarlo — para la ruta sin clave, usa un cliente con modelo (Cursor, Claude Desktop, Cline).

Ejecución local

# After building:
npm start

# Or run the built file directly:
node dist/index.js

El servidor habla MCP sobre stdio y registra csvbox-mcp-server running on stdio en stderr (stdout está reservado para el protocolo).

Configuración del cliente

Para una instalación publicada, usa el paquete npm con npx. Establece CSVBOX_API_KEY / CSVBOX_API_SECRET en el bloque env.

Nota: El paquete npm es @csvbox/mcp-server y el ejecutable es csvbox-mcp-server.

Claude Desktop

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

{
  "mcpServers": {
    "csvbox": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@csvbox/mcp-server",
        "csvbox-mcp-server"
      ],
      "env": {
        "CSVBOX_API_KEY": "your_api_key",
        "CSVBOX_API_SECRET": "your_api_secret"
      }
    }
  }
}

Cursor

Edita ~/.cursor/mcp.json (global) o .cursor/mcp.json (por proyecto):

{
  "mcpServers": {
    "csvbox": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@csvbox/mcp-server",
        "csvbox-mcp-server"
      ],
      "env": {
        "CSVBOX_API_KEY": "your_api_key",
        "CSVBOX_API_SECRET": "your_api_secret"
      }
    }
  }
}

Windsurf

Edita ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "csvbox": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@csvbox/mcp-server",
        "csvbox-mcp-server"
      ],
      "env": {
        "CSVBOX_API_KEY": "your_api_key",
        "CSVBOX_API_SECRET": "your_api_secret"
      }
    }
  }
}

Roo Code

En la configuración MCP de Roo Code (mcp_settings.json):

{
  "mcpServers": {
    "csvbox": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@csvbox/mcp-server",
        "csvbox-mcp-server"
      ],
      "env": {
        "CSVBOX_API_KEY": "your_api_key",
        "CSVBOX_API_SECRET": "your_api_secret"
      }
    }
  }
}

Cline

En la configuración MCP de Cline (cline_mcp_settings.json):

{
  "mcpServers": {
    "csvbox": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@csvbox/mcp-server",
        "csvbox-mcp-server"
      ],
      "env": {
        "CSVBOX_API_KEY": "your_api_key",
        "CSVBOX_API_SECRET": "your_api_secret"
      }
    }
  }
}

VS Code MCP

Añade a .vscode/mcp.json (o al mcp.json global):

{
  "servers": {
    "csvbox": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@csvbox/mcp-server",
        "csvbox-mcp-server"
      ],
      "env": {
        "CSVBOX_API_KEY": "your_api_key",
        "CSVBOX_API_SECRET": "your_api_secret"
      }
    }
  }
}

Ejemplos de llamadas a herramientas

Genera una hoja completa a partir de un prompt (LLM, sin llamada a la API de CSVBox):

// generate_sheet_json  (requires ANTHROPIC_API_KEY or OPENAI_API_KEY)
{ "prompt": "Create employee importer with name, email, salary, joining date; destination as testapi; allow only xlsx files" }

Devuelve { "sheet": { "title": ..., "sheet_columns": [...], "destinations": [...], "steps": {...} }, "source": "llm:anthropic:claude-haiku-4-5", "validation": { "valid": true, ... } }. Los campos de datos se convierten en columnas (salary → currency, joining date → date); el destino y la configuración de xlsx van a destinations / steps, no a columnas. Sin clave LLM, devuelve un error que apunta al prompt create_csvbox_sheet.

Valida un esquema antes de enviarlo:

// validate_schema
{ "sheet": { "title": "Customers", "sheet_columns": [
  { "column_name": "email", "display_label": "Email", "type": "email" }
] } }

Devuelve { "valid": true, "errors": [], "warnings": [ ... ] }.

Crea una hoja:

// create_sheet
{ "sheet": { "title": "Customer Import", "sheet_columns": [
  { "column_name": "name", "display_label": "Name", "type": "text" },
  { "column_name": "email", "display_label": "Email", "type": "email" }
] } }

Genera y crea en un solo paso:

// create_importer_from_prompt  (requires an LLM key + CSVBox credentials)
{ "prompt": "Create customer importer with name, email, phone; allow for example.com" }

Devuelve { "generated_schema": { ... }, "source": ..., "validation": { ... }, "api_response": { ... } }. Se aborta sin llamar a la API si no hay un proveedor LLM configurado o si el esquema generado falla la validación.

Reemplaza una hoja:

// update_sheet
{ "sheet_license_key": "abc123", "sheet": { "title": "Updated", "sheet_columns": [ ... ] } }

Destructivo para cualquier colección que envíes — consulta PUT vs PATCH.

Parchea una hoja:

// patch_sheet
{ "sheet_license_key": "abc123", "changes": { "title": "New Title" } }

Elimina una función sin tocar el resto:

// patch_sheet
{ "sheet_license_key": "abc123",
  "changes": { "virtual_columns": [ { "column_name": "full_name", "_delete": true } ] } }

Genera código de integración:

// generate_import_code
{ "framework": "react" }

Tipos de columna admitidos

text, number, email, date, time, boolean, regex, ip, url, credit_card, phone_number, currency, list, dependent_list, dynamic_list, dependent_dynamic_list, multiselect_list, multiselect_dynamic_list.

Desarrollo

npm run build   # compile TypeScript → dist/
npm start       # run the built server
npm run lint    # type-check without emitting
npm test        # compile and run the unit suite (alias: npm run test:unit)

Pruebas

npm test compila src/tests/ y lo ejecuta con el ejecutor de pruebas integrado de Node — sin framework de pruebas, sin librería de mocking.

La suite es hermética. Nunca contacta con un host externo, nunca lee tus CSVBOX_API_* / ANTHROPIC_API_KEY / OPENAI_API_KEY ambientales, y nunca toca una cuenta real de CSVBox, por lo que pasa de forma idéntica tengas o no credenciales configuradas. HTTP se intercepta en el adaptador de axios; el LLM es un fake con guion; la única prueba que necesita codificación real de solicitudes inicia un listener efímero en 127.0.0.1 y lo cierra después. Las pruebas que leen variables de entorno establecen lo que necesitan explícitamente y restauran los valores anteriores.

Pruebas E2E

npm run test:e2e         # run the Playwright suite
npm run test:e2e:report  # open the HTML report from the last run

Las especificaciones viven en e2e/, configuradas por playwright.config.ts. Al igual que la suite de unidades, esta suite es hermética: inicia servidores mock de CSVBox y LLM en loopback (e2e/support/mock-csvbox-server.ts, e2e/support/mock-llm-server.ts) y maneja el servidor real compilado (dist/index.js) a través de MCP Inspector con credenciales falsas apuntando a esos mocks — nunca contacta con una cuenta real de CSVBox ni con un proveedor LLM, y nunca lee tu .env. Una instancia separada de Inspector sin credenciales cubre las rutas de error de "credenciales faltantes". Requiere npm run build primero (las entradas de webServer de test:e2e se compilan automáticamente).

Incrustar el servidor

createServer() se exporta desde el módulo de entrada. Registra cada herramienta y prompt y devuelve el McpServer sin adjuntar un transporte, para que puedas conectarlo a uno propio:

import { createServer } from "@csvbox/mcp-server";

const server = createServer();
await server.connect(myTransport);

Importar el módulo no inicia nada; el servidor stdio solo se ejecuta cuando dist/index.js se ejecuta directamente.

Licencia

MIT