一个用于 CSVBox 的通用 Model Context Protocol（MCP）服务器。它将 CSVBox 导入器工作表管理以 MCP 工具的形式暴露出来，使您可以从任何兼容 MCP 的客户端（Claude Desktop、Cursor、Windsurf、Roo Code、Cline、VS Code、ChatGPT MCP 等）创建、替换、修补、生成、验证和搭建导入器。
通过 stdio 运行，因此在每个客户端中的工作方式都相同。
工具 | 用途 | API 调用 |
| 创建 CSVBox 工作表 |
|
| 替换现有工作表 |
|
| 部分更新工作表 |
|
| 自然语言提示 → 完整的工作表 JSON（通过 LLM） | 无（调用 LLM） |
| 自然语言提示 → 验证 → 创建 |
|
| 集成代码（vanilla-js/react/vue/angular） | 无 |
| 自然语言提示 → 虚拟列 / 验证函数 / 数据转换（通过 LLM） | 无（调用 LLM） |
| 本地模式验证 | 无 |
CSVBox 目前没有 GET 或 LIST 端点，因此有意不提供
get_sheet/list_sheet工具。
它还暴露了两个 MCP 提示（prompts）：
提示 | 用途 |
| 让宿主客户端自己的 LLM 构建完整的 CSVBox 工作表（无需服务器端 LLM 密钥）。 |
| 让宿主客户端自己的 LLM 编写虚拟列、验证函数和数据转换（无需服务器端 LLM 密钥）。 |
generate_sheet_json 和 create_importer_from_prompt 使用 LLM 将自由格式的请求转换为完整的 CSVBox 工作表 — title、sheet_columns、destinations、webhooks、security_settings 和 steps。只有实际数据字段才会成为列；目标、Webhook、域名、区域、文件上传和步骤设置会被放置在其相应的配置部分中，绝不会变成列。共有三个层级：
服务器 LLM — 当设置了 ANTHROPIC_API_KEY 或 OPENAI_API_KEY 时，服务器直接调用 LLM。适用于 MCP Inspector 和无头环境。
MCP 提示（create_csvbox_sheet）— 当您没有服务器密钥时，宿主客户端（Cursor、Claude Desktop、Cline）使用自己的模型运行生成，然后调用 validate_schema 和 create_sheet。免费。
未配置 — 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 都是全局唯一的。
数据类型和验证规则根据字段名称和任何请求的类型推断：
请求 / 隐含的 | 列 | 验证器 |
下拉 / 状态 / 带有固定选项的类别 |
|
|
百分比 / percent |
|
|
正数数值（数量、计数、库存、成本、年龄） |
|
|
ID / 代码 / 参考编号 |
| — |
电子邮件 |
| — |
电话 / 手机 |
| — |
URL / 网站 |
| — |
价格 / 成本 / 金额 / 薪资 |
| — |
日期字段 |
|
|
布尔值 / is_* / active |
| — |
GST / GSTIN / 税号 |
| GSTIN 模式 |
PIN 码 / 邮政编码（印度） |
|
|
大型模式： 默认模型（
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 在导入期间会执行该字符串：
集合 | 标识字段 | 最大数量 |
|
|
| 20 | 返回计算出的单元格值 |
|
| 10 | 返回错误字符串数组（ |
|
| 10 | 修改 |
在 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 提示。
|
| |
您发送的集合 | 权威性的 — 任何未命名的现有项目都会被删除 | 合并的 — 未命名的项目保持不变 |
| 删除全部 20 个 | 无操作 |
省略的键 | 不受影响 | 不受影响 |
| 无效 | 删除该项目（其所有其他字段被忽略） |
使用 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_secretCSVBox 凭据仅在基于 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中定义为常量。
generate_sheet_json 和 create_importer_from_prompt 需要 LLM。设置其中一个：
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...提供商是自动检测的：
条件 | 提供方 | 默认模型 |
| Anthropic |
|
| OpenAI |
|
已设置 | Anthropic |
|
已设置 | OpenAI |
|
两个密钥均未设置 | 无——工具会返回一个指向 | — |
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 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/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"
}
}
}
}编辑 ~/.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 设置（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_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"
}
}
}
}添加到 .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 上启动一个临时监听器，之后将其关闭。读取环境变量的测试会显式设置所需变量，并在之后恢复先前的值。
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
Generate a COMPLETE CSVBox sheet from a natural-language prompt via a configured LLM, validate it locally, then create it via POST /1.1/sheet. Returns { generated_schema, source, validation, api_response }. Aborts (no API call) if no LLM provider is configured or if validation fails. Requires ANTHROPIC_API_KEY or OPENAI_API_KEY plus CSVBox credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Natural-language description of the importer, e.g. "Create customer importer with columns name, email, phone; allow for example.com". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the full sequence (generate, validate locally, create via POST), the return object, the abort condition (no LLM provider or validation failure), and the required credentials (ANTHROPIC_API_KEY or OPENAI_API_KEY plus CSVBox credentials). This is comprehensive and honest about side effects (it creates a sheet).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences deliver the purpose, flow, return value, abort conditions, and required credentials without waste. The main action is front-loaded, followed by essential caveats. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, no output schema, and no annotations, the description covers the essential decision points: what it does, what it returns, when it aborts, and what credentials are needed. Missing is any detail on the validation failure behavior beyond aborting, and there is no example output or error handling guidance, but these are not critical for invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description for 'prompt' in the schema already explains it as a natural-language description of the importer. The tool description adds no extra detail about how the prompt is used, format expectations, or examples beyond what the schema provides. Baseline 3 is appropriate when schema fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Generate ... then create') and a clear resource (CSVBox sheet via POST /1.1/sheet). It is distinct from siblings like create_sheet (which likely creates without generation) and generate_sheet_json (which likely generates without creation). The flow is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly implies use when you have a natural-language prompt and want a complete, validated sheet. It notes that an LLM provider must be configured and that it aborts if not, which hints at alternative workflows, but it does not explicitly name alternatives or state when to prefer create_sheet or generate_sheet_json over this tool. The context is clear but exclusions are not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new CSVBox sheet via POST /1.1/sheet. Input: { sheet }. Returns the API response.
| Name | Required | Description | Default |
|---|---|---|---|
| sheet | Yes | The full CSVBox sheet object to create. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description bears full responsibility for disclosing behavior. It only states that it returns the API response, but gives no detail on side effects, error handling, idempotency, or what happens on duplicate creation. For a creation tool this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the action, which is good. However, its brevity comes at the cost of essential context, so it is under-specified rather than appropriately concise. A few extra sentences clarifying behavior and usage would be justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should clarify what the response contains, but it only says 'Returns the API response' without specifics. The nested 'sheet' object is intentionally open-ended, but the description doesn't hint at required fields or validation. Given the simplicity of the tool and sibling complexity, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full coverage of the sole parameter, describing the 'sheet' as 'The full CSVBox sheet object to create.' The tool description adds nothing beyond restating the parameter name and format. Since coverage is 100%, the description meets the baseline but adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action: creating a new CSVBox sheet via a POST request, and identifies the resource explicitly. It distinguishes from siblings like update_sheet and patch_sheet by indicating creation, though it doesn't explicitly call out the distinction. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as update_sheet or patch_sheet. It does not mention any prerequisites, when creation is appropriate, or when another sibling might be better. An agent would have to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate complete CSVBox importer integration code for a framework (vanilla-js, react, vuejs2 [Vue 2], vuejs3 [Vue 3], angular [Angular 8-13], angular2 [Angular 14+]). Input: { framework }. Replace the license key placeholder with your sheet's license key.
| Name | Required | Description | Default |
|---|---|---|---|
| framework | Yes | Target framework: vanilla-js | react | vuejs2 (Vue 2) | vuejs3 (Vue 3) | angular (Angular 8-13) | angular2 (Angular 14+). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions replacing the license key placeholder, which is a useful note, but it does not state whether the tool has side effects, what the output format is, or any prerequisites. The agent is left guessing about the return value and if any state changes occur. This is a notable gap for a tool that generates code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence. It front-loads the main action, immediately lists the supported frameworks with version clarifications, and includes the only crucial auxiliary instruction (replacing the license key placeholder). There is zero redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description covers the essential information: what it does, the input, and a critical post-processing step. While it doesn't explicitly describe the return format, the term 'integration code' makes it obvious. Minor omission: it doesn't state whether the code is returned as a string, file, or other, but this is not critical for invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter `framework` is already fully documented via enum and description. The tool description merely repeats 'Input: { framework }' without adding new parameter-specific details. The license key placeholder note concerns the output, not the input, so it doesn't enhance parameter understanding. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('generate complete CSVBox importer integration code'), a specific resource (CSVBox importer integration), and the parameter (framework). It lists all supported values, distinguishing it from sibling tools like generate_sheet_json or create_sheet. It is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description is self-contained and clearly implies when to use it: whenever you need integration code for a listed framework. It does not explicitly mention alternatives or exclusions, but the context is clear enough that an agent can infer appropriate usage without confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Author CSVBox virtual_columns, validation_functions, and data_transforms from a natural-language prompt using a configured LLM. Does NOT call the CSVBox API — it returns JSON so you can REVIEW the generated JavaScript before applying it with patch_sheet. Collections the request does not imply are omitted, never returned as empty arrays. Returns { virtual_columns?, validation_functions?, data_transforms?, source, validation }. Requires ANTHROPIC_API_KEY or OPENAI_API_KEY; without one it returns an error pointing to the csvbox_sheet_functions MCP prompt. Input: { prompt, sheet? }.
| Name | Required | Description | Default |
|---|---|---|---|
| sheet | No | The existing sheet the functions will be applied to. Supplying it lets the model reference real column names and lets validation check those references. CSVBox exposes no read endpoint, so this must be passed inline. | |
| prompt | Yes | Natural-language description of the functions to author, e.g. "add a virtual column joining first and last name, and validate that every email contains an @". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses that the tool does not call the API, omits unmentioned collections rather than returning empty arrays, returns a specific JSON shape, requires ANTHROPIC_API_KEY or OPENAI_API_KEY, and names the error fallback. This is unusually transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose, non-API behavior, output contract, authentication requirement, error handling, and input shape. The structure front-loads the main purpose before moving to constraints and fallbacks.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though there is no output schema, the description provides the return contract, omission behavior, auth prerequisites, and the downstream patch_sheet step. With only two parameters and one required, nothing essential is left for the agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters well. The description only restates the input shape as '{ prompt, sheet? }' and adds no new meaning beyond what the schema's per-parameter descriptions provide. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb and resource ('Author CSVBox virtual_columns, validation_functions, and data_transforms') and clearly states it returns reviewable JSON rather than calling the CSVBox API. This distinguishes it from patch_sheet, create_sheet, and generate_import_code even before reading schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Establishes a clear workflow: generate functions, review the returned JSON, then apply with patch_sheet. It also says the tool does not call the API and warns about missing API keys, but it does not explicitly contrast itself with generation siblings like generate_sheet_json or generate_import_code.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a COMPLETE CSVBox sheet (title, sheet_columns, destinations, webhooks, security_settings, steps) from a natural-language prompt using a configured LLM. Does NOT call the CSVBox API. Returns { sheet, source, validation }. Requires ANTHROPIC_API_KEY or OPENAI_API_KEY; without one it returns an error pointing to the create_csvbox_sheet MCP prompt. Input: { prompt }.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Natural-language description of the importer, e.g. "Create employee importer with columns name, email, salary, joining date; destination as testapi; allow only xlsx files". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses several key behaviors: no API call, key requirements, error fallback, and the return shape { sheet, source, validation }. However, it does not describe whether the call is synchronous, how long it may take, token/rate-limit considerations, or the meaning of the returned 'source' and 'validation' fields — moderate disclosure but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all load-bearing: the exclusions ('Does NOT call...') and key requirement ('Requires ANTHROPIC_API_KEY...') are front-loaded before the input spec. The use of ALL-CAPS for emphasis is a minor stylistic distraction, but overall it is compact with no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-input-parameter tool with no output schema and no annotations, the description covers the essentials: what it returns, its prerequisites, a common failure mode, and what the prompt parameter expects. The only notable gap is the absence of a minimal output/JSON example structure, which would help the agent gauge the result format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter prompt is fully documented in the schema (100% coverage, with a concrete example). The description adds only 'natural-language prompt' context, which marginally reinforces but does not extend the schema. Baseline 3 is appropriate where the schema already carries the parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Generate a COMPLETE CSVBox sheet') and enumerates the exact fields produced (title, sheet_columns, destinations, webhooks, security_settings, steps). It distinguishes itself from the API-calling siblings by explicitly stating 'Does NOT call the CSVBox API,' which is the key differentiator among the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the enabling condition (ANTHROPIC_API_KEY or OPENAI_API_KEY required) and the failure behavior when absent (returns an error pointing to create_csvbox_sheet). It clearly implies this tool generates JSON only and is the predecessor to an API-calling tool, though it doesn't name an explicit 'when not to use' sibling or a direct comparison to create_importer_from_prompt.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partially update a CSVBox sheet via PATCH /1.1/sheet/{sheet_license_key}. Sends only the changes object. Input: { sheet_license_key, changes }. Returns the API response. PATCH MERGES: only the items you list are touched and nothing is deleted implicitly, so an empty array is a no-op. Items in virtual_columns, validation_functions and data_transforms are matched by column_name / function_name / transform_name respectively — an unmatched name creates a new item. To remove one, send it with _delete: true; every other field on a _delete item is ignored, including js_code. This is the safe verb for applying generated functions. Run validate_schema with mode 'patch' first.
| Name | Required | Description | Default |
|---|---|---|---|
| changes | Yes | Only the partial changes to apply to the sheet. | |
| sheet_license_key | Yes | The license key of the sheet to patch. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and discloses substantial behavior: PATCH merges, only listed items are touched, empty array is a no-op, matching by names with unmatched creating new items, _delete: true for removal, and that other fields on a _delete item are ignored. It also mentions the return is 'the API response.' This exceeds typical descriptions, though it omits error handling or permission nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but each sentence earns its place: purpose, input/output, merge semantics, matching rules, deletion, and usage advice. It's front-loaded with the purpose, and while it's longer than average, the complexity of the operation justifies the length. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested objects, merge behavior, deletion), the description covers all critical aspects: how partial updates work, how to target items, how to delete, and the prerequisite validation step. It returns the API response but doesn't detail error cases, which is acceptable without an output schema. The description is sufficient for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant meaning to the 'changes' object by explaining the internal structure (virtual_columns, validation_functions, data_transforms), how items are matched by names, and the _delete flag semantics. This goes well beyond the schema's minimal 'Only the partial changes to apply to the sheet.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Partially update'), resource ('CSVBox sheet'), and the HTTP method (PATCH /1.1/sheet/{sheet_license_key}'). It clearly differentiates from sibling tools like update_sheet by emphasizing 'partial' and 'PATCH', and from create_sheet by 'update'. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: 'This is the safe verb for applying generated functions' and instructs to 'Run validate_schema with mode patch first.' While it doesn't explicitly name update_sheet as an alternative, the 'partial' vs full update distinction and the 'safe verb' guidance effectively imply when to prefer this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a file for import via POST /1.1/file. Provide exactly one of public_file_url (JSON submission) or file_base64 + file_name (multipart direct upload — file_base64 is decoded server-side and sent to CSVBox as true binary multipart content, never as a base64 string). Input: { sheet_license_key, public_file_url? | (file_base64?, file_name?), file_sheet_name?, user?, options?, dynamic_columns? }. Returns the API response.
| Name | Required | Description | Default |
|---|---|---|---|
| user | No | Custom user reference object attached to the import. | |
| options | No | Import options: has_header (0/1), max_rows, auto_map. | |
| file_name | No | File name for the direct upload. Required with file_base64. | |
| file_base64 | No | Base64-encoded file content for direct upload. This is an MCP-transport-only encoding: the server decodes it into raw bytes and sends CSVBox a true multipart/form-data 'file' part, never a base64 string. Mutually exclusive with public_file_url. Requires file_name. Prefer public_file_url for large files. | |
| dynamic_columns | No | Dynamic column definitions with validators. | |
| file_sheet_name | No | Worksheet name to import, for multi-tab files. | |
| public_file_url | No | Public URL of the file to import. Mutually exclusive with file_base64. | |
| sheet_license_key | Yes | The license key of the sheet to import into. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses key behavior: it explains the server-side decoding of file_base64 into true binary multipart content, the alternative JSON path, and that it returns the API response. It does not mention authentication or side effects, but the mutation is implied by 'submit for import' and the transport detail goes beyond basic expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the endpoint and the primary decision (which submission mode), then presents the full input structure compactly. Every clause contributes information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, nested objects, and two mutually exclusive alternatives, the description is thorough: it maps the parameter combos, explains the encoding nuance, and notes the return value. It omits authentication prerequisites and error handling, but those are commonly left to the API docs and the schema already covers required fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds real value beyond the schema by showing the exact input structure with alternatives and grouping, clarifying the mutual exclusivity already hinted in properties, and adding the file-size preference. This is more than the baseline 3 would require.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (submit a file for import), the resource (via POST /1.1/file), and the two distinct submission modes (JSON vs multipart). It distinguishes this tool from siblings like create_sheet or generate_import_code by focusing on the file submission action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lays out the mutually exclusive parameter combinations ('Provide exactly one of...') and even adds a practical preference ('Prefer public_file_url for large files'). It does not explicitly contrast with sibling tools, but the sibling set is clearly different in function, so this gap is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace an existing CSVBox sheet via PUT /1.1/sheet/{sheet_license_key}. Input: { sheet_license_key, sheet }. Returns the API response. DESTRUCTIVE: PUT is authoritative for every collection it sends — items listed are created or updated in place, and any existing item the array does not name is DELETED. This applies to virtual_columns, validation_functions and data_transforms: sending an empty array DELETES ALL of that collection's items, while OMITTING the key leaves them untouched. _delete is not valid here; use patch_sheet to remove a single item. Run validate_schema with mode 'put' first to catch a destructive body.
| Name | Required | Description | Default |
|---|---|---|---|
| sheet | Yes | The full replacement CSVBox sheet object. | |
| sheet_license_key | Yes | The license key of the sheet to replace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden — and it excels. It discloses the destructive PUT semantics (unnamed items are DELETED), which collections are affected (virtual_columns, validation_functions, data_transforms), the critical empty-array-deletes vs omit-preserves distinction, and invalidates `_delete`. The safety warnings cover all dangerous behavior an agent needs to avoid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but every sentence earns its place for a destructive operation — the PUT-authoritative semantics, collection scope, and empty-vs-omit warning are all essential safety information. Core purpose is front-loaded before the behavioral warnings. Slightly verbose, justified by the risk profile.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation with zero annotations and no output schema, this is complete. It covers what gets destroyed, the collection semantics, the invalid `_delete`, and pre-validates via validate_schema. Return value is minimally stated ('Returns the API response'), which is acceptable given no output schema exists. Nothing an agent needs to call this safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (sheet_license_key, sheet) are already documented inline, warranting baseline 3. The description adds some value by clarifying the destructive behavior of collections inside the `sheet` object, but it doesn't add syntax or format details beyond the schema's 'full replacement CSVBox sheet object'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Replace'), resource ('an existing CSVBox sheet'), and HTTP method (PUT /1.1/sheet/{sheet_license_key}'). The title reinforces the replace-vs-patch distinction, and the description names patch_sheet for partial updates, making it distinguishable from siblings without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes to alternatives with conditions: 'use patch_sheet to remove a single item', declares `_delete` is not valid here, and instructs 'Run validate_schema with mode put first'. This gives clear when-to/when-not guidance and names the safety pre-check, which is ideal for a destructive tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a CSVBox sheet schema locally (no API call). Requires a non-empty title; sheet_columns is optional (absent passes, empty yields a warning). When columns are present, checks for missing column_name/display_label/type, unsupported types, duplicate names, duplicate positions, and invalid dependent column references. Also checks virtual_columns, validation_functions, and data_transforms: per-sheet caps, duplicate and colliding names, missing or oversized js_code, scope/run_at enums, column references against sheet_columns, and dependency URLs (https, allowed CDN hosts, .js/.mjs, integrity digest). Pass mode ('create' | 'put' | 'patch', default 'create') so empty-array and _delete rules match the verb you are about to use. Returns { valid, errors, warnings }.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Which write verb this payload is headed for. "create" (default) for POST, "put" for a full replace, "patch" for a partial update. Affects only the function collections: an empty array is an error under "put" (it deletes every item); `_delete` is fully valid under "patch", redundant (warning only) under "put", and an error under "create". | |
| sheet | Yes | The CSVBox sheet object to validate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly describes what the tool does: it performs a local validation, enumerates all the checks (missing fields, duplicates, types, references, dependency rules), explains the mode-dependent behavior (empty array vs _delete), and states the return shape { valid, errors, warnings }. This is exceptionally transparent and leaves no ambiguity about side effects or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense paragraph that front-loads the core purpose and then systematically covers prerequisites, specific checks, mode handling, and return format. Every sentence adds value; there is no filler or repetition. The structure is logical and allows an agent to quickly grasp the tool's behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (many validation rules), the minimal schema, and absence of annotations, the description is remarkably complete. It covers all relevant inputs (sheet, mode), the exact validation logic, the behavior under different modes, and the output structure. There is no critical information missing for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema descriptions cover both parameters, the tool description adds significant meaning. For 'mode', it explains the impact of each enum value on validation rules, which the schema description only partially hints at. For 'sheet', since the schema only says 'object', the description is the sole source of truth for what the sheet object should contain (sheet_columns, virtual_columns, validation_functions, data_transforms). This goes well beyond the schema's generic definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Validate a CSVBox sheet schema locally (no API call).' This clearly distinguishes it from sibling tools like create_sheet or update_sheet, which perform mutations. The phrase 'no API call' further separates it from any network-dependent tool. The purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys when to use this tool: before an API call to validate the schema against the intended write verb, as shown by the mode parameter explanation ('Pass mode... so empty-array and _delete rules match the verb you are about to use'). However, it does not explicitly name alternative tools or state 'use this instead of X,' so it stops short of full exclusion guidance. The context is adequate for an agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.1create_importer_from_promptcreate_sheetgenerate_import_codegenerate_sheet_functionsgenerate_sheet_jsonpatch_sheetsubmit_fileupdate_sheetvalidate_schemaScored across 9 tools
Tools are mostly distinct: create/update/patch/validate/submit/generate each target different actions. The three 'generate_' tools produce different outputs (sheet JSON, code, functions), but 'create_importer_from_prompt' and 'generate_sheet_json' both involve prompt-based sheet generation, with the former actually creating while the latter only returns JSON, which could cause minor confusion.
Most names follow a verb_noun pattern (create_sheet, update_sheet, patch_sheet, validate_schema, submit_file, generate_sheet_json, generate_import_code, generate_sheet_functions). The exception is 'create_importer_from_prompt', which uses 'importer' instead of the more consistent 'sheet' and breaks the pattern slightly.
With 9 tools, the surface is well-scoped for a CSV import integration server. Each tool covers a distinct aspect (schema creation, modification, validation, file submission, and generation helpers) without redundancy, and the count fits comfortably in the ideal range.
The set covers create, update (PUT/PATCH), validation, and file submission, but lacks read operations (e.g., get_sheet, list_sheets) and explicit sheet deletion. While patch supports _delete, there is no direct delete_sheet tool. This creates a gap for agents that need to inspect or manage existing sheets outside of updates.
Remote MCP: JSON repair, JSON Schema validation, JSON to TypeScript, CSV to JSON and JSON to CSV.
Manage Pipefork API projects, drafts, connections, secrets, and deployments through MCP.
Create and manage trading strategies, bots, webhooks and signals from any MCP client.