csvbox-mcp-server

CSVBox용 범용 Model Context Protocol(MCP) 서버입니다. CSVBox 임포터 시트 관리를 MCP 도구로 노출하여 Claude Desktop, Cursor, Windsurf, Roo Code, Cline, VS Code, ChatGPT MCP 등 모든 MCP 호환 클라이언트에서 임포터를 생성, 교체, 패치, 생성, 검증, 스캐폴딩할 수 있습니다.

stdio로 실행되므로 모든 클라이언트에서 동일하게 작동합니다.

도구

CSVBox에는 현재 GET 또는 LIST 엔드포인트가 없으므로 의도적으로 get_sheet / list_sheet 도구가 없습니다.

또한 두 개의 MCP 프롬프트를 노출합니다:

프롬프트 → 시트 생성

generate_sheet_json 및 create_importer_from_prompt는 LLM을 사용하여 자유 형식 요청을 완전한 CSVBox 시트(title, sheet_columns, destinations, webhooks, security_settings, steps)로 변환합니다. 실제 데이터 필드만 컬럼이 되며, destinations, webhooks, domains, regions, 파일 업로드 및 단계 설정은 해당 구성 섹션에 배치되고 절대 컬럼으로 변환되지 않습니다. 세 가지 계층이 있습니다:

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를 호출하지 않습니다. 정규식 폴백은 없습니다.

카테고리 / 모듈 확장

생성기는 프롬프트에서 자동으로 선택되는 두 가지 모드 중 하나로 실행됩니다:

• 추출 (기본값) — 프롬프트가 구체적인 필드를 지정합니다 (예: "컬럼 name, email, phone"). 해당 필드만 컬럼이 되며, 그 외에는 아무것도 생성되지 않습니다.

• 확장 — 프롬프트가 비즈니스 모듈 / 카테고리를 목록으로 지정하거나 (예: "모듈: 회사 정보, 공급업체, 급여, 인보이스"), 포괄적/상세 스키마를 요청하거나, 컬럼 수를 요청합니다 ("최소 100개 컬럼"). 각 지정 모듈은 여러 개의 현실적이고 접두사가 붙은 올바른 유형의 컬럼으로 확장됩니다 (예: 공급업체 → 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는 항목에 CSVBox가 가져오기 중에 실행하는 js_code 문자열을 포함하는 세 가지 컬렉션을 허용합니다:

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 vs 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 경로, 쿼리 문자열, 프래그먼트, userinfo 또는 포트 없음.

보안. 이 서버는 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

이렇게 하면 MCP 클라이언트가 실행하는 진입점인 dist/index.js가 생성됩니다.

환경 변수

.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: 서버-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). 대상(destination)과 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 vs 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의 내장 테스트 러너로 실행합니다 — 테스트 프레임워크도, 모킹 라이브러리도 없습니다.

이 테스트 스위트는 격리(hermetic) 되어 있습니다. 외부 호스트에 절대 접촉하지 않고, 사용자의 환경에 있는 CSVBOX_API_* / ANTHROPIC_API_KEY / OPENAI_API_KEY를 절대 읽지 않으며, 실제 CSVBox 계정에 절대 접촉하지 않으므로 자격 증명이 구성되어 있든 없든 동일하게 통과합니다. HTTP는 axios 어댑터에서 가로채고, LLM은 스크립트로 작성된 가짜(fake)입니다. 실제 요청 인코딩이 필요한 하나의 테스트는 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로 구성됩니다. 단위 테스트 스위트와 마찬가지로 이 스위트도 격리(hermetic) 되어 있습니다. 루프백에서 모의 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()는 엔트리 모듈에서 내보내집니다. 모든 도구와 프롬프트를 등록하고 전송(transport)을 연결하지 않은 McpServer를 반환하므로, 사용자 자신의 전송에 연결할 수 있습니다:

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

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

모듈을 가져와도 아무것도 시작되지 않습니다. stdio 서버는 dist/index.js가 직접 실행될 때만 실행됩니다.

라이선스

MIT