csvbox-mcp-server

一个用于 CSVBox 的通用 Model Context Protocol（MCP）服务器。它将 CSVBox 导入器工作表管理以 MCP 工具的形式暴露出来，使您可以从任何兼容 MCP 的客户端（Claude Desktop、Cursor、Windsurf、Roo Code、Cline、VS Code、ChatGPT MCP 等）创建、替换、修补、生成、验证和搭建导入器。

通过 stdio 运行，因此在每个客户端中的工作方式都相同。

工具

CSVBox 目前没有 GET 或 LIST 端点，因此有意不提供 get_sheet / list_sheet 工具。

它还暴露了两个 MCP 提示（prompts）：

提示 → 工作表生成

generate_sheet_json 和 create_importer_from_prompt 使用 LLM 将自由格式的请求转换为完整的 CSVBox 工作表 — title、sheet_columns、destinations、webhooks、security_settings 和 steps。只有实际数据字段才会成为列；目标、Webhook、域名、区域、文件上传和步骤设置会被放置在其相应的配置部分中，绝不会变成列。共有三个层级：

1. 服务器 LLM — 当设置了 ANTHROPIC_API_KEY 或 OPENAI_API_KEY 时，服务器直接调用 LLM。适用于 MCP Inspector 和无头环境。

2. MCP 提示（create_csvbox_sheet）— 当您没有服务器密钥时，宿主客户端（Cursor、Claude Desktop、Cline）使用自己的模型运行生成，然后调用 validate_schema 和 create_sheet。免费。

3. 未配置 — generate_sheet_json 返回一个结构化的"未配置 LLM 提供商"错误，指向 MCP 提示，而 create_importer_from_prompt 不会调用 CSVBox API。没有正则表达式回退。

类别 / 模块扩展

生成器以两种模式之一运行，根据提示自动选择：

• 提取（默认）— 提示指定了具体字段（例如 "列：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）价格便宜，但当您通过 LLM_MODEL 覆盖为更强的模型（例如 claude-sonnet-4-6）时，生成的 100+ 列模式会明显更好。输出上限已提高以容纳大型工作表；如果请求仍然过大，响应会被标记为 TRUNCATED（一个独立的结果，不是解析错误），并且不会调用 CSVBox API — 请减少列数 / 模块数，或使用输出预算更大的模型后重试。

Related MCP server: mcp-tabular

函数集合（虚拟列、验证函数、数据转换）

除了六个工作表属性之外，CSVBox Sheet API 还接受三个集合，其项目携带一个 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": {...} }。请求未隐含的集合会被省略，绝不会作为空数组返回。

此工具不会调用 CSVBox API。请阅读生成的 js_code，然后使用 patch_sheet 自行应用。传入 sheet 以便模型引用真实的列名，并且验证器可以检查这些引用 — CSVBox 没有读取端点，因此必须内联提供。如果没有 LLM 密钥，请改用 csvbox_sheet_functions MCP 提示。

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 路径，无查询字符串、片段、用户信息或端口。

安全性。 此服务器从不执行 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：**在 Inspector 的环境变量面板中设置 LLM 密钥，即可使用服务器 LLM 路径。Inspector 本身没有宿主 LLM，因此它可以渲染 create_csvbox_sheet 提示词，但无法执行它——对于无密钥路径，请使用带模型的客户端（Cursor、Claude Desktop、Cline）。

本地运行

# After building:
npm start

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

服务器通过 stdio 使用 MCP 协议通信，并将 csvbox-mcp-server running on stdio 记录到 stderr（stdout 保留给协议使用）。

客户端配置

对于已发布的安装，请使用 npx 运行 npm 包。在 env 块中设置 CSVBOX_API_KEY / CSVBOX_API_SECRET。

**注意：**npm 包名为 @csvbox/mcp-server，可执行文件为 csvbox-mcp-server。

Claude Desktop

将以下内容添加到你的 Claude Desktop MCP 配置中：

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

在 Roo Code MCP 设置（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

在 Cline MCP 设置（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，不调用 CSVBox API）：

// 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": { ... } }。如果未配置 LLM 提供方或生成的架构未通过验证，则中止且不调用 API。

替换表格：

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

对你发送的任何集合都具有破坏性——参见 PUT 与 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 服务器（e2e/support/mock-csvbox-server.ts、e2e/support/mock-llm-server.ts），并通过 MCP Inspector 使用指向这些模拟服务器的假凭据驱动真实构建的服务器（dist/index.js）——它从不联系真实的 CSVBox 账户或 LLM 提供方，也从不读取你的 .env。另一个独立的、零凭据的 Inspector 实例覆盖了"缺少凭据"的错误路径。需要先运行 npm run build（test:e2e 的 webServer 条目会自动构建）。

嵌入服务器

createServer() 从入口模块导出。它注册所有工具和提示词，并返回 McpServer，不附加传输层，因此你可以将其连接到自己的传输层：

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

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

导入该模块不会启动任何内容；stdio 服务器仅在直接执行 dist/index.js 时运行。

许可证

MIT