csvbox-mcp-server

Ein universeller Model Context Protocol-Server (MCP) für CSVBox. Er stellt die CSVBox-Importer-Sheet-Verwaltung als MCP-Tools bereit, sodass du Importer aus jedem MCP-kompatiblen Client erstellen, ersetzen, patchen, generieren, validieren und aufsetzen kannst – Claude Desktop, Cursor, Windsurf, Roo Code, Cline, VS Code, ChatGPT MCP und mehr.

Läuft über stdio und funktioniert daher in jedem Client gleich.

Tools

CSVBox hat derzeit keine GET- oder LIST-Endpunkte, daher gibt es bewusst keine get_sheet- / list_sheet-Tools.

Außerdem stellt es zwei MCP-Prompts bereit:

Prompt → Sheet-Generierung

generate_sheet_json und create_importer_from_prompt nutzen eine LLM, um eine frei formulierte Anfrage in ein vollständiges CSVBox-Sheet umzuwandeln – title, sheet_columns, destinations, webhooks, security_settings und steps. Nur tatsächliche Datenfelder werden zu Spalten; Destinations, Webhooks, Domains, Regionen, Datei-Upload- und Schritt-Einstellungen werden in ihren jeweiligen Konfigurationsabschnitten platziert und niemals zu Spalten. Es gibt drei Stufen:

1. Server-LLM – wenn ANTHROPIC_API_KEY oder OPENAI_API_KEY gesetzt ist, ruft der Server die LLM direkt auf. Funktioniert im MCP Inspector und headless.

2. MCP-Prompt (create_csvbox_sheet) – wenn du keinen Server-Schlüssel hast, führen Host-Clients (Cursor, Claude Desktop, Cline) die Generierung mit ihrem eigenen Modell aus und rufen dann validate_schema und create_sheet auf. Kostenlos.

3. Nichts konfiguriert – generate_sheet_json gibt einen strukturierten Fehler „kein LLM-Provider konfiguriert“ zurück, der auf den MCP-Prompt verweist, und create_importer_from_prompt ruft die CSVBox-API nicht auf. Es gibt keinen Regex-Fallback.

Kategorie-/Modul-Erweiterung

Der Generator läuft in einem von zwei Modi, die automatisch anhand des Prompts gewählt werden:

• Extraktion (Standard) – der Prompt nennt konkrete Felder (z. B. „Spalten name, email, phone“). Nur diese werden zu Spalten; nichts wird erfunden.

• Erweiterung – der Prompt nennt Geschäfts-Module / Kategorien als Liste (z. B. „Module für: Company Information, Suppliers, Payroll, Invoice“), fordert ein umfassendes/detailliertes Schema an oder fragt nach einer Spaltenanzahl („mindestens 100 Spalten“). Jedes genannte Modul wird in mehrere realistische, präfixierte, korrekt typisierte Spalten erweitert (z. B. Suppliers → supplier_id, supplier_name, supplier_gstin, supplier_email, …). Eine explizite Mindestanzahl wird eingehalten und jede column_name ist global eindeutig.

Datentypen und Validierungen werden aus den Feldnamen und etwaigen angeforderten Typen abgeleitet:

Große Schemas: Die Standardmodelle (claude-haiku-4-5, gpt-4o-mini) sind günstig, erzeugen aber spürbar bessere Schemas mit 100+ Spalten, wenn du über LLM_MODEL ein stärkeres Modell überschreibst (z. B. claude-sonnet-4-6). Das Ausgabelimit wird angehoben, um große Sheets zu fassen; wenn eine Anfrage dennoch zu groß ist, wird die Antwort als TRUNCATED markiert (ein eigenes Ergebnis, kein Parse-Fehler) und die CSVBox-API wird nicht aufgerufen – reduziere die Spaltenanzahl / Module oder verwende ein Modell mit größerem Ausgabebudget und versuche es erneut.

Related MCP server: mcp-tabular

Funktionssammlungen (virtuelle Spalten, Validierungsfunktionen, Datentransformationen)

Über die sechs Sheet-Eigenschaften hinaus akzeptiert die CSVBox-Sheet-API drei Sammlungen, deren Elemente einen js_code-String enthalten, den CSVBox während eines Imports ausführt:

Im js_code stellt das csvbox-Objekt row, column, virtual, user, import und environment bereit. Die beiden Zugriffe sind nicht austauschbar – eine virtuelle Spalte ist pro Zeile und verwendet csvbox.row.<name> (ein Skalar), während eine auf "column" bezogene Funktion die gesamte Spalte über csvbox.column.<name> (ein Array) sieht.

Gemeinsame optionale Felder: scope (column | row; nicht bei virtuellen Spalten), run_at (before_validation | after_validation; nur bei Datentransformationen), columns / dynamic_columns, active, dependencies und _delete (nur PATCH).

Erstellen

// 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": [ ... ] }
}

Gibt { "virtual_columns": [...], "validation_functions": [...], "source": ..., "validation": {...} } zurück. Sammlungen, die die Anfrage nicht impliziert, werden weggelassen und niemals als leere Arrays zurückgegeben.

Dieses Tool ruft die CSVBox-API nicht auf. Lies den generierten js_code und wende ihn dann selbst mit patch_sheet an. Übergib sheet, damit das Modell echte Spaltennamen referenziert und der Validator diese Referenzen prüfen kann – CSVBox hat keinen Lese-Endpunkt, daher muss er inline angegeben werden. Ohne LLM-Schlüssel verwende stattdessen den csvbox_sheet_functions-MCP-Prompt.

PUT vs. PATCH – lies das, bevor du es anwendest

Verwende patch_sheet, um generierte Funktionen anzuwenden. Validiere zuerst mit dem passenden Verb:

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

mode ist create (Standard), put oder patch. Es betrifft nur die Funktionssammlungen – unter put ist ein leeres Array ein harter Fehler statt einer Warnung, und _delete wird außerhalb von patch abgelehnt.

Abhängigkeiten

Ein Element kann bis zu 5 Drittanbieter-Skripte laden:

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

Nur cdn.jsdelivr.net, unpkg.com und cdnjs.cloudflare.com sind erlaubt; nur https, .js/.mjs-Pfad, keine Query-String, kein Fragment, keine Benutzerinfo und kein Port.

Sicherheit. Dieser Server führt js_code niemals aus – es ist hier ein undurchsichtiger String. Generiertes JavaScript ist ungeprüfte Modellausgabe, lies es also, bevor du es per PATCH in einen Live-Importer einspielst. Eine Abhängigkeit ohne integrity-Digest kann sich jederzeit bei deinen Kunden ändern; validate_schema warnt, wenn einer fehlt.

Ein vollständiges Payload-Beispiel findest du in docs/sheet-functions-example.json.

Installation

npm install @csvbox/mcp-server

Oder aus dem Quellcode bauen:

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

Das erzeugt dist/index.js – den Einstiegspunkt, den MCP-Clients starten.

Umgebungsvariablen

Kopiere .env.example nach .env und trage deine CSVBox-Zugangsdaten ein:

CSVBOX_API_KEY=your_api_key
CSVBOX_API_SECRET=your_api_secret

CSVBox-Zugangsdaten sind nur für die API-gestützten Tools erforderlich (create_sheet, update_sheet, patch_sheet, create_importer_from_prompt). validate_schema und generate_import_code funktionieren ohne jegliche Zugangsdaten.

Hinweis zum Auth-Header: Der Client sendet x-csvbox-api-key und x-csvbox-secret-api-key (passend zu den CSVBox-Referenz-Payloads). Diese sind als Konstanten in src/services/csvbox-api.ts definiert, falls dein Konto andere Header-Namen verwendet.

LLM-Provider (für Prompt → Sheet-Generierung)

generate_sheet_json und create_importer_from_prompt benötigen ein LLM. Setze eine der folgenden:

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

Der Provider wird automatisch erkannt:

LLM_PROVIDER legt fest, welcher Anbieter verwendet wird, wenn beide Schlüssel vorhanden sind; LLM_MODEL überschreibt das Modell für den gewählten Anbieter. Für große Kategorie-/Modul-Schemas (100+ Spalten) setzen Sie LLM_MODEL auf ein stärkeres Modell (z. B. claude-sonnet-4-6) — siehe Kategorie-/Modul-Erweiterung.

MCP Inspector: Setzen Sie den LLM-Schlüssel im Umgebungsvariablen-Bereich des Inspectors, um den Server-LLM-Pfad zu verwenden. Der Inspector hat keinen eigenen Host-LLM, kann also den create_csvbox_sheet-Prompt rendern, aber nicht ausführen — für den schlüssellosen Pfad verwenden Sie einen Client mit einem Modell (Cursor, Claude Desktop, Cline).

Lokale Ausführung

# After building:
npm start

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

Der Server spricht MCP über stdio und protokolliert csvbox-mcp-server running on stdio auf stderr (stdout ist für das Protokoll reserviert).

Client-Konfiguration

Für eine veröffentlichte Installation verwenden Sie das npm-Paket mit npx. Setzen Sie CSVBOX_API_KEY / CSVBOX_API_SECRET im env-Block.

Hinweis: Das npm-Paket ist @csvbox/mcp-server und die ausführbare Datei ist csvbox-mcp-server.

Claude Desktop

Fügen Sie Folgendes zu Ihrer Claude-Desktop-MCP-Konfiguration hinzu:

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

Bearbeiten Sie ~/.cursor/mcp.json (global) oder .cursor/mcp.json (pro Projekt):

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

Bearbeiten Sie ~/.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

In den Roo-Code-MCP-Einstellungen (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

In den Cline-MCP-Einstellungen (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

Fügen Sie zu .vscode/mcp.json (oder der globalen mcp.json) hinzu:

{
  "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"
      }
    }
  }
}

Beispiel-Tool-Aufrufe

Ein vollständiges Sheet aus einem Prompt generieren (LLM, kein CSVBox-API-Aufruf):

// 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" }

Gibt { "sheet": { "title": ..., "sheet_columns": [...], "destinations": [...], "steps": {...} }, "source": "llm:anthropic:claude-haiku-4-5", "validation": { "valid": true, ... } } zurück. Datenfelder werden zu Spalten (salary → currency, joining date → date); das Ziel und die xlsx-Einstellung gehen in destinations / steps, nicht in Spalten. Ohne LLM-Schlüssel wird ein Fehler zurückgegeben, der auf den create_csvbox_sheet-Prompt verweist.

Ein Schema validieren, bevor es gesendet wird:

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

Gibt { "valid": true, "errors": [], "warnings": [ ... ] } zurück.

Ein Sheet erstellen:

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

Generieren + Erstellen in einem Schritt:

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

Gibt { "generated_schema": { ... }, "source": ..., "validation": { ... }, "api_response": { ... } } zurück. Bricht ab, ohne die API aufzurufen, wenn kein LLM-Provider konfiguriert ist oder das generierte Schema die Validierung nicht besteht.

Ein Sheet ersetzen:

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

Zerstörend für jede Sammlung, die Sie senden — siehe PUT vs. PATCH.

Ein Sheet patchen:

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

Eine Funktion entfernen, ohne den Rest anzufassen:

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

Integrationscode generieren:

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

Unterstützte Spaltentypen

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.

Entwicklung

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)

Tests

npm test kompiliert src/tests/ und führt es mit dem integrierten Test-Runner von Node aus — kein Test-Framework, keine Mocking-Bibliothek.

Die Testsuite ist hermetisch. Sie kontaktiert nie einen externen Host, liest nie Ihre Umgebungsvariablen CSVBOX_API_* / ANTHROPIC_API_KEY / OPENAI_API_KEY und berührt nie ein echtes CSVBox-Konto, sodass sie identisch besteht, unabhängig davon, ob Sie Anmeldedaten konfiguriert haben. HTTP wird am axios-Adapter abgefangen; der LLM ist ein skriptgesteuerter Fake; der eine Test, der echte Request-Kodierung benötigt, startet einen kurzlebigen Listener auf 127.0.0.1 und schließt ihn danach wieder. Tests, die Umgebungsvariablen lesen, setzen explizit, was sie benötigen, und stellen die vorherigen Werte wieder her.

E2E-Tests

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

Die Specs liegen in e2e/, konfiguriert durch playwright.config.ts. Wie die Unit-Testsuite ist auch diese Suite hermetisch: Sie startet Mock-CSVBox- und LLM-Server auf Loopback (e2e/support/mock-csvbox-server.ts, e2e/support/mock-llm-server.ts) und steuert den echten gebauten Server (dist/index.js) über MCP Inspector mit gefälschten Anmeldedaten, die auf diese Mocks zeigen — sie kontaktiert nie ein echtes CSVBox-Konto oder einen echten LLM-Provider und liest nie Ihre .env. Eine separate Inspector-Instanz ohne Anmeldedaten deckt die Fehlerpfade für „fehlende Anmeldedaten“ ab. Erfordert zuerst npm run build (die test:e2e-webServer-Einträge bauen automatisch).

Einbetten des Servers

createServer() wird aus dem Einstiegsmodul exportiert. Es registriert jedes Tool und jeden Prompt und gibt den McpServer zurück, ohne einen Transport anzuhängen, sodass Sie ihn mit einem eigenen verbinden können:

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

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

Das Importieren des Moduls startet nichts; der stdio-Server läuft nur, wenn dist/index.js direkt ausgeführt wird.

Lizenz

MIT