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 ツールは意図的に存在しません。

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

プロンプト → シート生成

generate_sheet_json と create_importer_from_prompt は LLM を使用して、自由形式のリクエストを完全な CSVBox シート（title、sheet_columns、destinations、webhooks、security_settings、steps）に変換します。実際のデータフィールドのみが列になります。宛先、ウェブフック、ドメイン、リージョン、ファイルアップロード、ステップ設定はそれぞれ適切な設定セクションに配置され、列に変換されることはありません。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 を呼び出しません。正規表現によるフォールバックはありません。

カテゴリ / モジュールの展開

ジェネレーターはプロンプトから自動的に選択される2つのモードのいずれかで動作します:

• 抽出（デフォルト）— プロンプトが具体的なフィールドを指定します（例: "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 はグローバルに一意です。

データ型と検証は、フィールド名と要求された型から推論されます:

大規模スキーマ: デフォルトモデル（claude-haiku-4-5、gpt-4o-mini）は安価ですが、LLM_MODEL でより強力なモデル（例: claude-sonnet-4-6）を指定すると、100列以上のスキーマで顕著に良い結果が得られます。出力上限は大きなシートに合わせて引き上げられます。それでもリクエストが大きすぎる場合、レスポンスは TRUNCATED としてフラグ付けされ（パースエラーとは異なる明確な結果）、CSVBox API は呼び出されません — 列数 / モジュールを減らすか、より大きな出力予算を持つモデルを使用して再試行してください。

Related MCP server: mcp-tabular

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

6つのシートプロパティに加えて、CSVBox Sheet API は3つのコレクションを受け入れます。各項目には js_code 文字列が含まれ、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 — 適用前に必ずお読みください

生成された関数を適用するには 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 が必要です。次のいずれか1つを設定してください:

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

サーバーは 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 vs 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 の組み込みテストランナーで実行します — テストフレームワークもモッキングライブラリもありません。

このスイートは**密閉型（hermetic）**です。外部ホストに接続することはなく、環境の CSVBOX_API_* / ANTHROPIC_API_KEY / OPENAI_API_KEY を読み取ることも、実際の CSVBox アカウントに触れることもないため、認証情報が設定されているかどうかに関係なく同じように合格します。HTTP は axios アダプターでインターセプトされ、LLM はスクリプト化されたフェイクです。実際のリクエストエンコーディングを必要とする1つのテストは、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）、実際のビルド済みサーバー（dist/index.js）を MCP Inspector 経由で、それらのモックを指すフェイクの認証情報を使って駆動します — 実際の 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