# mcp-csv-server

> An [MCP](https://modelcontextprotocol.io) server that lets an AI assistant **preview, query, aggregate, and convert CSV/TSV data** — safely, with no API key.

[![CI](https://github.com/takuyahoritacromtech/mcp-csv-server/actions/workflows/ci.yml/badge.svg)](https://github.com/takuyahoritacromtech/mcp-csv-server/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
![Node](https://img.shields.io/badge/node-%3E%3D18.18-brightgreen)
![MCP](https://img.shields.io/badge/MCP-1.x-7C3AED)

Give Claude (or any MCP client) the ability to actually *work with spreadsheets*: filter rows,
sum/average/group columns, and turn CSV into JSON — instead of eyeballing a pasted table and
guessing. Pure TypeScript, dependency-light, and **runnable with zero credentials**, so a
reviewer can try it in one command.

## 日本語の概要

AIアシスタント（Claude等）に「CSV/業務データを正しく扱う力」を与えるMCPサーバです。表をそのまま
読ませて推測させるのではなく、**行の絞り込み・列の集計（合計/平均/最大最小）・グループ集計・JSON変換**を
ツールとして提供します。APIキー不要で動くので、その場で試せます。

- **壊れにくいCSVパーサ**：引用符・エスケープ（`""`）・引用符内のカンマ/改行に対応（素朴な`split(',')`が壊れる実データを正しく処理）。
- **型付きエラー＋対処ヒント**：`[UNKNOWN_COLUMN] Unknown column "x". Hint: Available columns: ...` のように、AIにも人にも原因と対処が分かる。
- **責務分離**：`csv/`（パース・クエリの純粋ロジック）/ `tools/`（MCPツール定義）/ `server.ts`（薄い配線）。
- **テスト**：パーサ・クエリ・ツールを19本のユニットテストで検証（全エラー経路含む）。CI緑。

## Tools

| Tool | What it does | Key inputs |
| --- | --- | --- |
| `csv_preview` | Columns, total row count, and a sample | `csv`, `delimiter?`, `limit?` |
| `csv_query` | Filter / select / aggregate / group / limit | `csv`, `where?`, `select?`, `aggregate?`, `groupBy?`, `limit?` |
| `csv_to_json` | Convert CSV/TSV to JSON records | `csv`, `delimiter?`, `limit?` |

`aggregate` supports `count`, `sum`, `avg`, `min`, `max`; `where` ops are
`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains` (ANDed together). Numbers tolerate
thousands separators (`"2,000"` → `2000`).

## Install & run

```bash
git clone https://github.com/takuyahoritacromtech/mcp-csv-server.git
cd mcp-csv-server
npm install
npm run build
```

### Use with Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "csv": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-csv-server/dist/index.js"]
    }
  }
}
```

Restart the client; the `csv_preview`, `csv_query`, and `csv_to_json` tools appear.

### Quick smoke test (no client needed)

```bash
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  | node dist/index.js
# → {"result":{...,"serverInfo":{"name":"mcp-csv-server",...}},"jsonrpc":"2.0","id":1}
```

## Example: "total sales by region"

Given a `csv_query` call with:

```json
{ "csv": "region,amount\nEast,1000\nWest,2000\nEast,500",
  "groupBy": "region",
  "aggregate": { "fn": "sum", "column": "amount" } }
```

the tool returns:

```json
{ "columns": ["region", "sum_amount"],
  "rows": [{ "region": "East", "sum_amount": 1500 }, { "region": "West", "sum_amount": 2000 }],
  "rowCount": 2 }
```

## Design notes (the "why")

- **A real CSV parser, not `split(',')`** — a small RFC 4180 state machine handles quoting,
  escaped quotes, and embedded delimiters/newlines. This is where naive tools silently corrupt data.
- **Pure core, thin MCP shell** — all logic lives in `csv/` and `tools/` as pure functions, so it
  is unit-tested without the protocol. `server.ts` only maps tools to the SDK and converts
  `CsvError` into clean tool errors.
- **Typed errors with hints** — every failure (`UNKNOWN_COLUMN`, `NON_NUMERIC_COLUMN`,
  `CSV_PARSE_ERROR`, …) is actionable from the message alone.
- **Validated inputs** — every tool input is a Zod schema, so malformed calls are rejected before
  any work happens.

## Testing

```bash
npm run check   # typecheck + lint + test
```

19 unit tests cover CSV parsing (quoting, TSV, CRLF, ragged rows, empty, unterminated quotes),
the query engine (filter/select/aggregate/group/limit + every error code), and the three tools.

## License

MIT © Takuya Horita