csvbox-mcp-server

# csvbox-mcp-server

A universal [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [CSVBox](https://csvbox.io). It exposes CSVBox importer-sheet management as MCP tools so you can create, replace, patch, generate, validate, and scaffold importers from any MCP-compatible client — Claude Desktop, Cursor, Windsurf, Roo Code, Cline, VS Code, ChatGPT MCP, and more.

Runs over **stdio**, so it works the same way in every client.

## Tools

| Tool | Purpose | API call |
| --- | --- | --- |
| `create_sheet` | Create a CSVBox sheet | `POST /1.1/sheet` |
| `update_sheet` | Replace an existing sheet | `PUT /1.1/sheet/{key}` |
| `patch_sheet` | Partially update a sheet | `PATCH /1.1/sheet/{key}` |
| `generate_sheet_json` | NL prompt → complete sheet JSON (via LLM) | none (calls LLM) |
| `create_importer_from_prompt` | NL prompt → validate → create | `POST /1.1/sheet` (+ LLM) |
| `generate_import_code` | Integration code (vanilla-js/react/vue/angular) | none |
| `generate_sheet_functions` | NL prompt → virtual columns / validation functions / data transforms (via LLM) | none (calls LLM) |
| `validate_schema` | Local schema validation | none |

> CSVBox currently has **no GET or LIST endpoints**, so there are intentionally no `get_sheet` / `list_sheet` tools.

It also exposes two **MCP prompts**:

| Prompt | Purpose |
| --- | --- |
| `create_csvbox_sheet` | Make the host client's own LLM build a complete CSVBox sheet (no server-side LLM key needed). |
| `csvbox_sheet_functions` | Make the host client's own LLM author virtual columns, validation functions, and data transforms (no server-side LLM key needed). |

### Prompt → sheet generation

`generate_sheet_json` and `create_importer_from_prompt` use an LLM to convert a free-form request into a **complete** CSVBox sheet — `title`, `sheet_columns`, `destinations`, `webhooks`, `security_settings`, and `steps`. Only actual data fields become columns; destinations, webhooks, domains, regions, file-upload and step settings are placed in their proper configuration sections, never turned into columns. There are three tiers:

1. **Server LLM** — when `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` is set, the server calls the LLM directly. Works in MCP Inspector and headless.
2. **MCP prompt** (`create_csvbox_sheet`) — when you have no server key, host clients (Cursor, Claude Desktop, Cline) run the generation with their own model, then call `validate_schema` and `create_sheet`. Free.
3. **None configured** — `generate_sheet_json` returns a structured "no LLM provider configured" error pointing to the MCP prompt, and `create_importer_from_prompt` does not call the CSVBox API. There is **no** regex fallback.

#### Category / module expansion

The generator runs in one of two modes, chosen automatically from the prompt:

- **Extraction** (default) — the prompt names concrete fields (e.g. *"columns name, email, phone"*). Only those become columns; nothing is invented.
- **Expansion** — the prompt names business **modules / categories** as a list (e.g. *"modules for: Company Information, Suppliers, Payroll, Invoice"*), asks for a *comprehensive*/*detailed* schema, or asks for a column count (*"at least 100 columns"*). Each named module is expanded into several realistic, prefixed, correctly-typed columns (e.g. Suppliers → `supplier_id`, `supplier_name`, `supplier_gstin`, `supplier_email`, …). An explicit minimum count is honored and every `column_name` is globally unique.

Data types and validations are inferred from the field names and any requested types:

| Requested / implied | Column `type` | Validators |
| --- | --- | --- |
| Dropdown / status / category with fixed options | `list` | `values: [...]` candidate options |
| Percentage / percent | `number` | `min_value: 0`, `max_value: 100` |
| Positive numeric (quantity, count, stock, cost, age) | `number` | `min_value: 0` |
| ID / code / reference number | `text` | — |
| Email | `email` | — |
| Phone / mobile | `phone_number` | — |
| URL / website | `url` | — |
| Price / cost / amount / salary | `currency` | — |
| Date fields | `date` | `format: "YYYY-MM-DD"` |
| Boolean / is_* / active | `boolean` | — |
| GST / GSTIN / tax id | `regex` | GSTIN pattern |
| PIN code / postal code (India) | `regex` | `^[1-9][0-9]{5}$` |

> **Large schemas:** the default models (`claude-haiku-4-5`, `gpt-4o-mini`) are cheap but produce noticeably better 100+ column schemas when you override with a stronger model via `LLM_MODEL` (e.g. `claude-sonnet-4-6`). The output cap is raised to fit big sheets; if a request is still too large the response is flagged **`TRUNCATED`** (a distinct result, not a parse error) and the CSVBox API is **not** called — reduce the column count / modules or use a model with a larger output budget and retry.

## Function collections (virtual columns, validation functions, data transforms)

Beyond the six sheet properties, the CSVBox Sheet API accepts three collections whose items carry a `js_code` string that **CSVBox executes during an import**:

| Collection | Identified by | Max | `js_code` must… |
| --- | --- | --- | --- |
| `virtual_columns` | `column_name` | 20 | return the computed cell value |
| `validation_functions` | `function_name` | 10 | return an array of error strings (`[]` = valid) |
| `data_transforms` | `transform_name` | 10 | mutate the `csvbox` object and **return it** |

Inside `js_code` the `csvbox` object exposes `row`, `column`, `virtual`, `user`, `import`, and `environment`. The two accessors are **not** interchangeable — a virtual column is per-row and uses `csvbox.row.<name>` (a scalar), while a `"column"`-scoped function sees the whole column via `csvbox.column.<name>` (an array).

Shared optional fields: `scope` (`column` | `row`; not on virtual columns), `run_at` (`before_validation` | `after_validation`; data transforms only), `columns` / `dynamic_columns`, `active`, `dependencies`, and `_delete` (PATCH only).

### Authoring them

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

Returns `{ "virtual_columns": [...], "validation_functions": [...], "source": ..., "validation": {...} }`. Collections the request does not imply are **omitted**, never returned as empty arrays.

This tool **does not call the CSVBox API**. Read the generated `js_code`, then apply it yourself with `patch_sheet`. Pass `sheet` so the model references real column names and the validator can check those references — CSVBox has no read endpoint, so it must be supplied inline. Without an LLM key, use the `csvbox_sheet_functions` MCP prompt instead.

### PUT vs PATCH — read this before applying

| | `update_sheet` (PUT) | `patch_sheet` (PATCH) |
| --- | --- | --- |
| Collection you send | **authoritative** — any existing item not named is **deleted** | **merged** — unnamed items are left alone |
| `"virtual_columns": []` | **deletes all 20** | no-op |
| Key omitted | untouched | untouched |
| `_delete: true` | not valid | removes that item (all its other fields ignored) |

Use `patch_sheet` to apply generated functions. Validate first with the matching verb:

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

`mode` is `create` (default), `put`, or `patch`. It only affects the function collections — under `put` an empty array is a hard error rather than a warning, and `_delete` is rejected outside `patch`.

### Dependencies

An item may load up to 5 third-party scripts:

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

Only `cdn.jsdelivr.net`, `unpkg.com`, and `cdnjs.cloudflare.com` are allowed; https only, `.js`/`.mjs` path, no query string, fragment, userinfo, or port.

> **Security.** This server never executes `js_code` — it is an opaque string here. Generated JavaScript is unreviewed model output, so read it before you PATCH it into a live importer. A dependency without an `integrity` digest can change under your customers at any time; `validate_schema` warns when one is missing.

See `docs/sheet-functions-example.json` for a full payload.

## Installation

```bash
npm install @csvbox/mcp-server
```

Or build from source:

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

This produces `dist/index.js` — the entrypoint MCP clients launch.

## Environment variables

Copy `.env.example` to `.env` and fill in your CSVBox credentials:

```bash
CSVBOX_API_KEY=your_api_key
CSVBOX_API_SECRET=your_api_secret
```

CSVBox credentials are **only** required for the API-backed tools (`create_sheet`, `update_sheet`, `patch_sheet`, `create_importer_from_prompt`). `validate_schema` and `generate_import_code` work without any credentials.

> **Auth header note:** the client sends `x-csvbox-api-key` and `x-csvbox-secret-api-key` (matching the CSVBox reference payloads). These are defined as constants in `src/services/csvbox-api.ts` if your account uses different header names.

### LLM provider (for prompt → sheet generation)

`generate_sheet_json` and `create_importer_from_prompt` need an LLM. Set **one** of:

```bash
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
```

The provider is auto-detected:

| Condition | Provider | Default model |
| --- | --- | --- |
| `LLM_PROVIDER=anthropic` (and its key set) | Anthropic | `claude-haiku-4-5` |
| `LLM_PROVIDER=openai` (and its key set) | OpenAI | `gpt-4o-mini` |
| `ANTHROPIC_API_KEY` set (no `LLM_PROVIDER`) | Anthropic | `claude-haiku-4-5` |
| `OPENAI_API_KEY` set (no `LLM_PROVIDER`) | OpenAI | `gpt-4o-mini` |
| neither key set | none — tools return an error pointing to the `create_csvbox_sheet` MCP prompt | — |

`LLM_PROVIDER` disambiguates when both keys are present; `LLM_MODEL` overrides the model fo