tabular-mcp

السجل الرسمي البيانات وقواعدها

CSV/JSONL/xlsx toolkit: schema inference, dirty-row reports, format conversion, seeded sampling

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

NPM package @nopilot/tabular-mcp
Claude Code
claude mcp add tabular-mcp -- npx -y @nopilot/tabular-mcp@1.0.1
إعداد JSON (Claude Desktop وCursor وVS Code)
{
    "mcpServers": {
        "tabular-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@nopilot/tabular-mcp@1.0.1"
            ]
        }
    }
}

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. tabular-tools
  2. The local-first difference
  3. Tools (MCP)
  4. Install & run
  5. Engine usage (npm)
  6. Development
  7. Dependencies & licenses
  8. Publishing

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 serverstabular-mcp
Where your data goesuploaded to their gatewaynever leaves the process
Works offlinenoyes
Extra accounts / API keysusually yesnone
Deterministic outputnot guaranteedbyte-identical (seeded sampling)
Source availablemostly closedMIT, 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

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):

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

Engine usage (npm)

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

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):

packageversionlicenserole
papaparse^5.7.1MITCSV parse/unparse (handles BOM, quoted newlines, delimiter detection)
exceljs^4.4.0MITxlsx read (first community-edition xlsx reader with no exploit history; no SheetJS CDN needed)
@modelcontextprotocol/sdk^1.32.2MITofficial MCP TypeScript SDK (server only)
zod^4.6.7MITtool input schema
express^5.2.1MITHTTP 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).

Publishing

This repo ships to zero registries by itself. See PUBLISH.md for the manual npm publish + MCP registry submission steps.

الأسئلة الشائعة

ما هو tabular-mcp؟

CSV/JSONL/xlsx toolkit: schema inference, dirty-row reports, format conversion, seeded sampling

كيف أثبّت tabular-mcp؟

يعمل على جهازك. في Claude Code: claude mcp add tabular-mcp -- npx -y @nopilot/tabular-mcp@1.0.1. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج tabular-mcp إلى مفتاح API؟

لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.

هل tabular-mcp مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون tabular-mcp؟

ينشره latbert. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.