csvbox-mcp-server

csvbox-mcp-server

CSVBox 向けの汎用 Model Context Protocol（MCP）サーバーです。CSVBox のインポーターシート管理機能を MCP ツールとして公開するため、Claude Desktop、Cursor、Windsurf、Roo Code、Cline、VS Code、ChatGPT MCP など、あらゆる 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（LLM 経由）	なし（LLM を呼び出します）
create_importer_from_prompt	自然言語プロンプト → 検証 → 作成	POST /1.1/sheet（+ LLM）
generate_import_code	統合コード（vanilla-js/react/vue/angular）	なし
generate_sheet_functions	自然言語プロンプト → 仮想列／検証関数／データ変換（LLM 経由）	なし（LLM を呼び出します）
validate_schema	ローカルでのスキーマ検証	なし

CSVBox には現在、GET または LIST エンドポイントがないため、get_sheet／list_sheet ツールは意図的に用意していません。

また、2 つの MCP プロンプトも公開しています。

プロンプト	目的
create_csvbox_sheet	ホストクライアント独自の LLM を使って、完全な CSVBox シートを作成します（サーバー側の LLM キーは不要です）。
csvbox_sheet_functions	ホストクライアント独自の LLM を使って、仮想列、検証関数、データ変換を作成します（サーバー側の LLM キーは不要です）。

プロンプト → シート生成

generate_sheet_json と create_importer_from_prompt は、LLM を使って自由形式のリクエストを 完全な CSVBox シート（title、sheet_columns、destinations、webhooks、security_settings、steps）に変換します。実際のデータフィールドだけが列になり、送信先、Webhook、ドメイン、リージョン、ファイルアップロード、ステップの設定は適切な設定セクションに配置され、列に変換されることはありません。利用方法は次の 3 つです。

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 は MCP プロンプトを案内する構造化された「LLM プロバイダーが設定されていません」というエラーを返し、create_importer_from_prompt は CSVBox API を呼び出しません。正規表現によるフォールバックはありません。

カテゴリー／モジュールの拡張

ジェネレーターは、プロンプトに基づいて自動的に選択される次のいずれかのモードで実行されます。

• 抽出（デフォルト） — プロンプトで具体的なフィールドが指定されます（例：「列名、メール、電話番号」）。指定されたフィールドだけが列になり、項目が勝手に追加されることはありません。
• 拡張 — プロンプトでビジネスのモジュール／カテゴリーがリストとして指定される場合（例：「次のモジュール：会社情報、サプライヤー、給与計算、請求書」）、包括的な／詳細なスキーマを求める場合、または列数を指定する場合（「少なくとも100列」）です。指定された各モジュールは、現実的で、プレフィックスが付き、適切な型の複数の列に展開されます（例：サプライヤー → supplier_id、supplier_name、supplier_gstin、supplier_email、…）。明示された最小数は守られ、すべてのcolumn_nameは全体で一意になります。

データ型とバリデーションは、フィールド名と指定された型から推測されます。

指定／推測される内容	列のtype	バリデーター
固定の選択肢を持つドロップダウン／ステータス／カテゴリー	list	values: [...]の候補
パーセンテージ／パーセント	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_*／有効状態	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は呼び出されません。列数／モジュールを減らすか、出力上限の大きいモデルを使用して再試行してください。

関数コレクション（仮想列、バリデーション関数、データ変換）

6つのシートプロパティに加えて、CSVBox Sheet APIは、インポート中にCSVBoxが実行するjs_code文字列を含む項目からなる、次の3つのコレクションを受け付けます。

コレクション	識別子	最大数	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を参照できます。2つのアクセサーは互換性がありません。仮想列は行ごとに評価され、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 — 適用前にお読みください

	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

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 で定数として定義されています。

クライアントの識別

このサーバーが CSVBox API に送信するすべてのリクエストには、追加のヘッダーが 2 つ付加されます。

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 プロバイダー（プロンプト → シート生成用）

generate_sheet_json と create_importer_from_prompt には LLM が必要です。次のいずれか 1 つを設定してください。

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： サーバーの 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

サーバーは 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" }
] } }

生成と作成を 1 ステップで行う：

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

ほかの部分に触れずに関数を 1 つ削除する：

// 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