# tablekit-mcp

**A tiny, dependency-free MCP server for tabular data — convert, align, reshape and inspect tables without breaking them.**

Tables are where language models quietly fail: they drop rows when converting a big CSV to JSON, they misalign Markdown columns, they transpose a table and shuffle the wrong cell. tablekit does those jobs with plain deterministic code instead of guessing.

Zero network access. Zero file system access. Pure Python standard library. It takes a string and returns a string.

---

## Why this exists

| Task | Asking the model to do it | Letting tablekit do it |
| --- | --- | --- |
| CSV → JSON, 200 rows | Rows get silently dropped or truncated | Every row survives |
| Fix a ragged Markdown table | Columns drift, especially with CJK text | Re-aligned by real display width |
| Transpose / sort / filter | Off-by-one row errors | Deterministic |
| "What's wrong with this table?" | Vague guess | Type inference, empty counts, duplicate report |

**Chinese / Japanese / Korean tables line up correctly.** Most tools measure string length; tablekit measures *display width*, so `苹果` counts as 4 cells and the pipes actually match.

---

## Tools

| Tool | What it does |
| --- | --- |
| `table_convert` | Convert between `markdown`, `csv`, `tsv`, `json`, `html` |
| `table_align` | Re-align a messy Markdown table so every column lines up |
| `table_transform` | `transpose` · `select_columns` · `rename_columns` · `sort` · `dedupe` · `drop_empty_rows` · `filter` |
| `table_inspect` | Structure report: row/column counts, per-column type, empty counts, distinct values, dirty-data warnings |

Formats accept the aliases `.md`, `.csv`, `.htm` — paste a filename extension and it just works.

---

## Install

### Option 1 — run straight from GitHub (uv)

```bash
uvx --from git+https://github.com/Orange123Eleven/tablekit-mcp tablekit-mcp
```

### Option 2 — clone and install

```bash
git clone https://github.com/Orange123Eleven/tablekit-mcp
cd tablekit-mcp
uv venv && uv pip install -e .
```

---

## Configure your client

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "tablekit": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Orange123Eleven/tablekit-mcp",
        "tablekit-mcp"
      ]
    }
  }
}
```

**Cursor / Cline / Windsurf / VS Code** — same shape, e.g. `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "tablekit": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Orange123Eleven/tablekit-mcp",
        "tablekit-mcp"
      ]
    }
  }
}
```

Restart the client and the four tools appear in the tool list.

---

## What it looks like in use

**1. A CSV with Chinese headers, converted to a readable Markdown table**

Input:

```
名称,数量,单价
苹果,3,5.50
进口香蕉,150,2.00
```

Ask: *"turn this into a Markdown table, right-align the numbers"*

Output:

```
| 名称     | 数量 | 单价 |
| -------- | ---: | ---: |
| 苹果     |    3 | 5.50 |
| 进口香蕉 |  150 | 2.00 |
```

**2. A broken table gets repaired**

Input (note the short row):

```
| name   | team      | score |
| ------ | --------- | ----- |
| Ana    | Red       | 91 |
| Ben    | Blue |
```

`table_inspect` reports:

```
Rows: 2  |  Columns: 3

| Column | Type | Empty | Distinct | Most frequent |
| --- | --- | --- | --- | --- |
| name | text | 0 | 2 | Ana (1) |
| team | text | 0 | 2 | Red (1) |
| score | integer | 1 | 1 | 91 (1) |

Issues found:
- 各行列数不一致（少则 2 列，多则 3 列），已按最大列数补空。
```

**3. HTML table scraped from a page → CSV**

Ask: *"here's the HTML, give me a CSV I can paste into Excel"* — one call, no row loss.

---

## Safety

This server is deliberately boring, and that is the point:

- **No network requests.** It never phones home.
- **No file system access.** It cannot read or write your files. You paste text in, you get text back.
- **No third-party dependencies.** Only the MCP SDK itself.
- **Stateless.** Nothing is stored between calls.
- **Deterministic.** Same input, same output, every time.

---

## 中文说明

给中文用户的一句话：**表格数据的小工具，专治中文表格对不齐、大表格转换丢行。**

- 四种工具：格式互转 / 对齐美化 / 转置排序筛选 / 结构体检
- 支持 Markdown、CSV、TSV、JSON、HTML 五种格式
- **中文按 2 格宽度对齐**，`| 名称 | 数量 |` 这种表格能真正对齐（大多数工具做不到）
- 纯本地、不联网、不碰你的文件、无第三方依赖

上面「Configure your client」里的配置直接抄就行。

---

## Development

```bash
python3 tests/test_core.py -v     # 42 tests, standard library only
```

The processing logic lives in `src/tablekit_mcp/core.py` and has no MCP dependency, so it can be tested and reused on its own. `src/tablekit_mcp/server.py` is a thin wrapper that exposes it over MCP.

## License

MIT