Skip to main content
Glama
tabular-mcp

tabular-mcp

by latbert
README.md
# tabular-tools

Deterministic tabular-file tools for agents and humans: **CSV / JSONL / xlsx local read → validate → convert → sample**, as an npm engine (`@nopilot/tabular-engine`) plus a local-first MCP server (`@nopilot/tabular-mcp`).

**Why not just "read the file"?** Agents burn context reading raw files and still miscount rows, miss dirty rows, and mangle quoted CSV. These tools do it deterministically: same input → byte-identical output, every time.

## The local-first difference

Most tabular-file MCP servers in the wild (e.g. the Pipeworx "CSV Tools" family, ~235 weekly visitors) run behind a **hosted gateway**: your file leaves your machine, hits their servers, and comes back. That is a non-starter for anything proprietary, personal, or offline.

`tabular-mcp` runs **entirely on your machine**:

| | hosted CSV/xlsx MCP servers | tabular-mcp |
|---|---|---|
| Where your data goes | uploaded to their gateway | never leaves the process |
| Works offline | no | yes |
| Extra accounts / API keys | usually yes | none |
| Deterministic output | not guaranteed | byte-identical (seeded sampling) |
| Source available | mostly closed | MIT, full tests |

Three hard guarantees (enforced by design and tests):

1. **Deterministic action tools, not AI wrappers** — no LLM calls anywhere; identical input produces identical output.
2. **Pure local computation** — zero network requests, zero external data sources; the whole test suite runs offline.
3. **Runs locally, no hosted gateway** — stdio or localhost HTTP, bind 127.0.0.1 by default.

## Tools (MCP)

### `tabular_inspect`

Inspect a local CSV / JSONL / xlsx file: row count, column list, inferred schema (per-column dominant type + full type distribution + empty counts) and a **dirty-row report with 1-based file row numbers**: format errors, missing/extra columns, type drift vs the inferred schema. CSV header = file row 1; JSONL rows are line numbers.

### `tabular_convert`

Convert: `csv → jsonl`, `jsonl → csv`, `xlsx → csv/jsonl`. Returns content inline and optionally writes to a path. xlsx reads the first sheet by default; `allSheets: true` reads every non-empty sheet (multi-sheet CSV uses `# sheet: <name>` separators; JSONL gains a `sheet` field). Same input → byte-identical output.

### `tabular_sample`

Stream-sample without loading the file: `head` / `tail` / seeded `random`. Random sampling uses a deterministic seeded reservoir — same file + count + seed ⇒ the exact same rows, regardless of stream chunking. Each sampled row carries its file row number.

## Install & run

```bash
npm install -g @nopilot/tabular-mcp
tabular-mcp                          # stdio (default)
tabular-mcp --transport http --port 9420   # stateless Streamable HTTP on 127.0.0.1
```

MCP client config (stdio):

```json
{
  "mcpServers": {
    "tabular": { "command": "tabular-mcp" }
  }
}
```

## Engine usage (npm)

```js
import { inspectFile, convertFile, sampleFile } from '@nopilot/tabular-engine';

const report = await inspectFile('data.csv');
// → { format: 'csv', rowCount, columns, columnStats, issues: [{ row, code, column, message }], bom }

await convertFile('data.csv', { to: 'jsonl' });        // → { content, rowCount, sheets }
await convertFile('book.xlsx', { to: 'csv', allSheets: true });

const s = await sampleFile('huge.jsonl', { mode: 'random', count: 50, seed: 'k1' });
// → { mode, totalRows, rows: [{ row: 1234, data: {...} }] } — deterministic
```

## Development

```bash
npm install
npm test          # build + typecheck + vitest + determinism harness
npm run determinism   # byte-equality spot checks only
npm run publish:dry   # npm publish --dry-run for both packages
```

The determinism harness (`scripts/determinism-check.mjs`) runs every capability twice on identical inputs and asserts byte-equal outputs.

## Dependencies & licenses

Runtime dependencies (chosen to be mature, permissive, and maintained; no GPL/AGPL anywhere in the tree):

| package | version | license | role |
|---|---|---|---|
| papaparse | ^5.7.1 | MIT | CSV parse/unparse (handles BOM, quoted newlines, delimiter detection) |
| exceljs | ^4.4.0 | MIT | xlsx read (first community-edition xlsx reader with no exploit history; no SheetJS CDN needed) |
| @modelcontextprotocol/sdk | ^1.32.2 | MIT | official MCP TypeScript SDK (server only) |
| zod | ^4.6.7 | MIT | tool input schema |
| express | ^5.2.1 | MIT | HTTP transport host |

Transitive notes: all transitive runtime dependencies are MIT/Apache-2.0/BSD/ISC/BlueOak-1.0.0/Unlicense except `buffers@0.1.1` (via exceljs → unzipper chain), which ships **no license field**; its upstream repo (substack/node-buffers) is MIT/X11, matching the author's other packages (`binary`: MIT, `chainsaw`: MIT/X11). Recorded here rather than assumed.

License of this project: **MIT** (see [LICENSE](./LICENSE)).

## Publishing

This repo ships to **zero** registries by itself. See [PUBLISH.md](./PUBLISH.md) for the manual npm publish + MCP registry submission steps.