csvbox-mcp-server

Универсальный Model Context Protocol (MCP) сервер для CSVBox. Он предоставляет управление листами импортера CSVBox в виде MCP-инструментов, позволяя создавать, заменять, обновлять, генерировать, проверять и создавать каркасы импортеров из любого MCP-совместимого клиента — Claude Desktop, Cursor, Windsurf, Roo Code, Cline, VS Code, ChatGPT MCP и других.

Работает через stdio, поэтому одинаково функционирует во всех клиентах.

Инструменты

В CSVBox в настоящее время нет конечных точек GET или LIST, поэтому инструментов get_sheet / list_sheet намеренно нет.

Также предоставляются два MCP-промпта:

Генерация листа из промпта

generate_sheet_json и create_importer_from_prompt используют LLM для преобразования свободного запроса в полный лист CSVBox — title, sheet_columns, destinations, webhooks, security_settings и steps. Только реальные поля данных становятся колонками; destinations, webhooks, домены, регионы, настройки загрузки файлов и шагов помещаются в соответствующие разделы конфигурации и никогда не превращаются в колонки. Есть три уровня:

1. Серверная LLM — когда задан ANTHROPIC_API_KEY или OPENAI_API_KEY, сервер вызывает LLM напрямую. Работает в MCP Inspector и в headless-режиме.

2. MCP-промпт (create_csvbox_sheet) — если у вас нет серверного ключа, клиенты-хосты (Cursor, Claude Desktop, Cline) выполняют генерацию своей собственной моделью, а затем вызывают validate_schema и create_sheet. Бесплатно.

3. Ничего не настроено — generate_sheet_json возвращает структурированную ошибку «провайдер LLM не настроен» со ссылкой на MCP-промпт, а create_importer_from_prompt не вызывает API CSVBox. Нет запасного варианта на основе регулярных выражений.

Развёртывание категорий / модулей

Генератор работает в одном из двух режимов, выбираемых автоматически из промпта:

• Извлечение (по умолчанию) — в промпте названы конкретные поля (например, «колонки name, email, phone»). Только они становятся колонками; ничего не выдумывается.

• Развёртывание — в промпте названы бизнес-модули / категории списком (например, «модули для: Company Information, Suppliers, Payroll, Invoice»), запрашивается всеобъемлющая/детальная схема или запрашивается количество колонок («не менее 100 колонок»). Каждый названный модуль разворачивается в несколько реалистичных колонок с префиксами и корректными типами (например, Suppliers → supplier_id, supplier_name, supplier_gstin, supplier_email, …). Явно заданный минимум соблюдается, и каждый column_name глобально уникален.

Типы данных и валидации выводятся из имён полей и любых запрошенных типов:

Большие схемы: модели по умолчанию (claude-haiku-4-5, gpt-4o-mini) дёшевы, но дают заметно лучшие схемы на 100+ колонок, если переопределить их более сильной моделью через LLM_MODEL (например, claude-sonnet-4-6). Лимит вывода увеличен, чтобы вместить большие листы; если запрос всё ещё слишком велик, ответ помечается TRUNCATED (отдельный результат, а не ошибка парсинга), и API CSVBox не вызывается — уменьшите количество колонок / модулей или используйте модель с большим бюджетом вывода и повторите попытку.

Related MCP server: mcp-tabular

Коллекции функций (виртуальные колонки, функции валидации, преобразования данных)

Помимо шести свойств листа, API листов CSVBox принимает три коллекции, элементы которых содержат строку js_code, которую CSVBox выполняет во время импорта:

Внутри js_code объект csvbox предоставляет row, column, virtual, user, import и environment. Два аксессора не взаимозаменяемы — виртуальная колонка работает по строкам и использует csvbox.row.<name> (скаляр), а функция с областью "column" видит всю колонку через csvbox.column.<name> (массив).

Общие необязательные поля: scope (column | row; не для виртуальных колонок), run_at (before_validation | after_validation; только для преобразований данных), columns / dynamic_columns, active, dependencies и _delete (только PATCH).

Их создание

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

Возвращает { "virtual_columns": [...], "validation_functions": [...], "source": ..., "validation": {...} }. Коллекции, которые не подразумеваются запросом, опускаются и никогда не возвращаются как пустые массивы.

Этот инструмент не вызывает API CSVBox. Прочитайте сгенерированный js_code, затем примените его самостоятельно с помощью patch_sheet. Передайте sheet, чтобы модель ссылалась на реальные имена колонок, а валидатор мог проверить эти ссылки — у CSVBox нет конечной точки чтения, поэтому её нужно передавать встроенно. Без LLM-ключа используйте вместо этого MCP-промпт csvbox_sheet_functions.

PUT против PATCH — прочитайте перед применением

Используйте patch_sheet для применения сгенерированных функций. Сначала проверьте с помощью соответствующего глагола:

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

mode — create (по умолчанию), put или patch. Он влияет только на коллекции функций — при put пустой массив является жёсткой ошибкой, а не предупреждением, а _delete отклоняется вне patch.

Зависимости

Элемент может загружать до 5 сторонних скриптов:

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

Разрешены только cdn.jsdelivr.net, unpkg.com и cdnjs.cloudflare.com; только https, путь .js/.mjs, без строки запроса, фрагмента, userinfo или порта.

Безопасность. Этот сервер никогда не выполняет js_code — здесь это непрозрачная строка. Сгенерированный JavaScript — это непроверенный вывод модели, поэтому прочитайте его перед тем, как применить через PATCH к рабочему импортеру. Зависимость без дайджеста integrity может измениться под вашими клиентами в любой момент; validate_schema предупреждает, когда он отсутствует.

Полный пример полезной нагрузки см. в docs/sheet-functions-example.json.

Установка

npm install @csvbox/mcp-server

Или сборка из исходников:

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

В результате получается dist/index.js — точка входа, которую запускают MCP-клиенты.

Переменные окружения

Скопируйте .env.example в .env и заполните свои учётные данные CSVBox:

CSVBOX_API_KEY=your_api_key
CSVBOX_API_SECRET=your_api_secret

Учётные данные CSVBox требуются только для инструментов, работающих через API (create_sheet, update_sheet, patch_sheet, create_importer_from_prompt). validate_schema и generate_import_code работают без каких-либо учётных данных.

Примечание о заголовке аутентификации: клиент отправляет x-csvbox-api-key и x-csvbox-secret-api-key (в соответствии с эталонными полезными нагрузками CSVBox). Они определены как константы в src/services/csvbox-api.ts, если ваша учётная запись использует другие имена заголовков.

Провайдер LLM (для генерации листа из промпта)

generate_sheet_json и create_importer_from_prompt требуют LLM. Задайте один из:

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

Провайдер определяется автоматически:

LLM_PROVIDER устраняет неоднозначность, когда заданы оба ключа; LLM_MODEL переопределяет модель для выбранного провайдера. Для больших схем категорий/модулей (100+ колонок) задайте LLM_MODEL более сильной моделью (например, claude-sonnet-4-6) — см. Расширение категорий / модулей.

MCP Inspector: задайте ключ LLM на панели переменных окружения Inspector, чтобы использовать путь серверного LLM. У Inspector нет собственного хост-LLM, поэтому он может отображать промпт create_csvbox_sheet, но не может выполнять его — для пути без ключа используйте клиент с моделью (Cursor, Claude Desktop, Cline).

Локальный запуск

# After building:
npm start

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

Сервер общается по MCP через stdio и пишет csvbox-mcp-server running on stdio в stderr (stdout зарезервирован для протокола).

Конфигурация клиента

Для опубликованной установки используйте npm-пакет с npx. Задайте CSVBOX_API_KEY / CSVBOX_API_SECRET в блоке env.

Примечание: npm-пакет называется @csvbox/mcp-server, а исполняемый файл — csvbox-mcp-server.

Claude Desktop

Добавьте следующее в конфигурацию MCP 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

Отредактируйте ~/.cursor/mcp.json (глобально) или .cursor/mcp.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"
      }
    }
  }
}

Windsurf

Отредактируйте ~/.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

В настройках MCP 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

В настройках MCP 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

Добавьте в .vscode/mcp.json (или глобальный mcp.json):

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

Примеры вызовов инструментов

Создание полного листа по промпту (LLM, без вызова API 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" }

Возвращает { "sheet": { "title": ..., "sheet_columns": [...], "destinations": [...], "steps": {...} }, "source": "llm:anthropic:claude-haiku-4-5", "validation": { "valid": true, ... } }. Поля данных становятся колонками (salary → currency, joining date → date); назначение и настройка xlsx попадают в destinations / steps, а не в колонки. Без ключа LLM возвращается ошибка со ссылкой на промпт create_csvbox_sheet.

Проверка схемы перед отправкой:

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

Возвращает { "valid": true, "errors": [], "warnings": [ ... ] }.

Создание листа:

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

Генерация + создание за один шаг:

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

Возвращает { "generated_schema": { ... }, "source": ..., "validation": { ... }, "api_response": { ... } }. Прерывается без вызова API, если не настроен ни один LLM-провайдер или сгенерированная схема не проходит проверку.

Замена листа:

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

Разрушительно для любой отправляемой коллекции — см. PUT vs PATCH.

Частичное обновление листа (PATCH):

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

Удаление одной функции, не затрагивая остальные:

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

Генерация интеграционного кода:

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

Поддерживаемые типы колонок

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.

Разработка

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)

Тесты

npm test компилирует src/tests/ и запускает его встроенным тестовым раннером Node — без тестового фреймворка и библиотеки моков.

Набор тестов герметичен. Он никогда не обращается к внешним хостам, не читает ваши переменные окружения CSVBOX_API_* / ANTHROPIC_API_KEY / OPENAI_API_KEY и не касается реального аккаунта CSVBox, поэтому проходит одинаково независимо от того, настроены ли у вас учётные данные. HTTP перехватывается на уровне адаптера axios; LLM — это скриптовый фейк; единственный тест, которому нужна реальная кодировка запроса, запускает временный слушатель на 127.0.0.1 и закрывает его после. Тесты, читающие переменные окружения, явно задают нужные значения и восстанавливают предыдущие.

E2E-тесты

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

Спецификации находятся в e2e/ и настраиваются через playwright.config.ts. Как и модульный набор, этот набор герметичен: он запускает мок-серверы CSVBox и LLM на loopback (e2e/support/mock-csvbox-server.ts, e2e/support/mock-llm-server.ts) и управляет реальным собранным сервером (dist/index.js) через MCP Inspector с фейковыми учётными данными, указывающими на эти моки — он никогда не обращается к реальному аккаунту CSVBox или LLM-провайдеру и не читает ваш .env. Отдельный экземпляр Inspector без учётных данных покрывает пути ошибок «отсутствуют учётные данные». Требуется сначала выполнить npm run build (записи webServer в test:e2e собираются автоматически).

Встраивание сервера

createServer() экспортируется из входного модуля. Он регистрирует все инструменты и промпты и возвращает McpServer без подключения транспорта, так что вы можете подключить его к своему собственному:

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

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

Импорт модуля ничего не запускает; stdio-сервер работает только при непосредственном выполнении dist/index.js.

Лицензия

MIT