csvbox-mcp-server

csvbox-mcp-server

适用于 CSVBox 的通用 Model Context Protocol（MCP）服务。它将 CSVBox 导入器工作表管理功能作为 MCP 工具开放，因此你可以通过任何兼容 MCP 的客户端（Claude Desktop、Cursor、Windsurf、Roo Code、Cline、VS Code、ChatGPT MCP 等）创建、替换、修补、生成、验证导入器并搭建其基本结构。

通过 stdio 运行，因此在所有客户端中的运行方式都相同。

工具

工具	用途	API 调用
create_sheet	创建 CSVBox 工作表	POST /1.1/sheet
update_sheet	替换现有工作表	PUT /1.1/sheet/{key}
patch_sheet	部分更新工作表	PATCH /1.1/sheet/{key}
generate_sheet_json	自然语言提示词 → 完整工作表 JSON（通过大模型）	无（调用大模型）
create_importer_from_prompt	自然语言提示词 → 验证 → 创建	POST /1.1/sheet（+ 大模型）
generate_import_code	集成代码（vanilla-js/react/vue/angular）	无
generate_sheet_functions	自然语言提示词 → 虚拟列 / 验证函数 / 数据转换（通过大模型）	无（调用大模型）
validate_schema	本地架构验证	无

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

它还提供两个 MCP 提示词：

提示词	用途
create_csvbox_sheet	让宿主客户端自己的大模型构建完整的 CSVBox 工作表（无需服务端大模型密钥）。
csvbox_sheet_functions	让宿主客户端自己的大模型编写虚拟列、验证函数和数据转换（无需服务端大模型密钥）。

提示词 → 工作表生成

generate_sheet_json 和 create_importer_from_prompt 使用大模型将自由格式请求转换为完整的 CSVBox 工作表，包括 title、sheet_columns、destinations、webhooks、security_settings 和 steps。只有实际数据字段会成为列；目标位置、webhook、域名、区域、文件上传和步骤设置都会放在各自对应的配置部分，不会被转换成列。共有三种方式：

1. 服务端大模型 — 设置 ANTHROPIC_API_KEY 或 OPENAI_API_KEY 后，服务会直接调用大模型。适用于 MCP Inspector 和无头模式。
2. MCP 提示词（create_csvbox_sheet）— 如果没有服务端密钥，宿主客户端（Cursor、Claude Desktop、Cline）会使用自己的模型生成工作表，然后调用 validate_schema 和 create_sheet。免费。
3. 均未配置 — generate_sheet_json 会返回结构化的“未配置大模型提供方”错误，并指向 MCP 提示词；create_importer_from_prompt 不会调用 CSVBox API。没有正则表达式回退方案。

类别 / 模块扩展

生成器会根据提示词自动选择以下两种模式之一：

• 提取（默认）——提示词列出具体字段（例如 "columns name, email, phone"）。只有这些字段会成为列；不会虚构字段。
• 扩展——提示词将业务模块 / 类别列为清单（例如 "modules for: Company Information, Suppliers, Payroll, Invoice"），要求生成全面 / 详细的架构，或指定列数（"at least 100 columns"）。每个指定模块都会扩展为多个合理、带前缀且类型正确的列（例如 Suppliers → supplier_id、supplier_name、supplier_gstin、supplier_email、……）。明确指定的最少数量会得到满足，并确保所有 column_name 全局唯一。

系统会根据字段名称和所请求的类型推断数据类型和验证规则：

请求 / 暗示	列 type	验证器
下拉菜单 / 状态 / 固定选项类别	list	values: [...] 候选选项
百分比 / percent	number	min_value: 0、max_value: 100
正数值（数量、计数、库存、成本、年龄）	number	min_value: 0
ID / 代码 / 参考编号	text	—
电子邮件	email	—
电话 / 手机号码	phone_number	—
URL / 网站	url	—
价格 / 成本 / 金额 / 薪资	currency	—
日期字段	date	format: "YYYY-MM-DD"
布尔值 / is_* / active	boolean	—
GST / GSTIN / 纳税人 ID	regex	GSTIN 模式
PIN 码 / 邮政编码（印度）	regex	^[1-9][0-9]{5}$

大型架构：默认模型（claude-haiku-4-5、gpt-4o-mini）成本较低，但使用 LLM_MODEL 指定更强的模型（例如 claude-sonnet-4-6）后，生成 100 列以上的架构效果会明显更好。输出上限会提高，以适应大型工作表；如果请求仍然过大，响应会标记为 TRUNCATED（这是独立结果，不是解析错误），且不会调用 CSVBox API——请减少列数 / 模块数量，或改用输出预算更大的模型后重试。

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

除六项工作表属性外，CSVBox Sheet API 还接受三个集合，其中的条目包含一个 js_code 字符串，CSVBox 会在导入期间执行该字符串：

集合	标识字段	上限	js_code 必须……
virtual_columns	column_name	20	返回计算所得的单元格值
validation_functions	function_name	10	返回错误字符串数组（[] = 有效）
data_transforms	transform_name	10	修改 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 没有读取端点，因此必须内联提供 sheet。如果没有 LLM 密钥，请改用 csvbox_sheet_functions MCP 提示词。

PUT 与 PATCH — 应用前请先阅读

	update_sheet（PUT）	patch_sheet（PATCH）
发送的集合	权威 — 任何未列出的现有项都会被删除	合并 — 未列出的项保持不变
"virtual_columns": []	删除全部 20 项	无操作
省略键	不变	不变
_delete: true	无效	移除该项（忽略其所有其他字段）

使用 patch_sheet 应用生成的函数。先使用匹配的动词进行验证：

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

mode 为 create（默认值）、put 或 patch。它只影响函数集合——在 put 模式下，空数组会导致硬错误，而不是警告；在 patch 模式以外使用 _delete 会被拒绝。

依赖项

一个项目最多可加载 5 个第三方脚本：

{ "url": "https://cdn.jsdelivr.net/npm/[email protected]/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

只有 API 支持的工具（create_sheet、update_sheet、patch_sheet、create_importer_from_prompt）需要 CSVBox 凭据。validate_schema 和 generate_import_code 无需任何凭据即可运行。

认证标头说明： 客户端会发送 x-csvbox-api-key 和 x-csvbox-secret-api-key（与 CSVBox 参考载荷一致）。如果你的账户使用不同的标头名称，这些名称在 src/services/csvbox-api.ts 中定义为常量。

客户端标识

此服务发送到 CSVBox API 的每个请求都会附带两个额外标头：

x-csvbox-client: mcp
x-csvbox-client-version: <the version in package.json>

CSVBox 会记录每个工作表的创建方式；如果没有这些标头，通过 MCP 创建的工作表和导入器将无法与其他 REST 调用者区分。版本号从 package.json 中读取，与服务向 MCP 客户端声明的版本号相同，因此两者绝不会不一致。

这些标头始终会发送——没有任何环境变量或工具输入可以禁用或更改它们。它们不包含凭据，也不包含任何源自工具输入的内容。不调用 API 的工具（generate_sheet_json、generate_sheet_functions、generate_import_code、validate_schema）不会发送请求，因此也不会发送标头。

LLM 提供方（用于 prompt → 表格生成）

generate_sheet_json 和 create_importer_from_prompt 需要 LLM。设置以下选项中的一个：

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

系统会自动检测提供方：

条件	提供方	默认模型
设置了 LLM_PROVIDER=anthropic（且设置了相应密钥）	Anthropic	claude-haiku-4-5
设置了 LLM_PROVIDER=openai（且设置了相应密钥）	OpenAI	gpt-4o-mini
设置了 ANTHROPIC_API_KEY（未设置 LLM_PROVIDER）	Anthropic	claude-haiku-4-5
设置了 OPENAI_API_KEY（未设置 LLM_PROVIDER）	OpenAI	gpt-4o-mini
两个密钥都未设置	无 — 工具会返回错误，提示使用 create_csvbox_sheet MCP 提示词	—

如果两个密钥都已设置，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 适配器处拦截；大模型使用脚本化的模拟对象；唯一需要真实请求编码的测试会在 127.0.0.1 上启动一个临时监听器，并在之后将其关闭。读取环境变量的测试会显式设置所需变量，并在结束后恢复之前的值。

端到端测试

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 和大模型服务（e2e/support/mock-csvbox-server.ts、e2e/support/mock-llm-server.ts），并通过 MCP Inspector 使用指向这些模拟服务的虚假凭据调用真实构建的服务（dist/index.js）——它绝不会联系真实的 CSVBox 账户或大模型提供商，也不会读取你的 .env。另有一个不使用任何凭据的 Inspector 实例，用于覆盖“缺少凭据”的错误路径。需要先运行 npm run build（test:e2e 的 webServer 配置项会自动构建）。

嵌入服务

入口模块导出了 createServer()。它会注册所有工具和提示词，并返回尚未关联传输方式的 McpServer，因此你可以将它连接到自己的传输方式：

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

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

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

许可证

MIT