Experiment details
Tokenizer: tiktoken `cl100k_base` (GPT-4). Claude uses a different tokenizer, but relative comparisons hold. The benchmark script (`script.py`) constructs tables programmatically and generates tablestakes output using the actual converter code — no hardcoded strings.
**Read baseline**: `simulate_read_tool()` wraps file content in `cat -n` format (line-number prefix per line), matching what Claude Code's Read tool returns. The full file (document text + table) enters the LLM context.
**Write baseline**: for each cell edit, the script computes the minimum unique `old_string` by expanding leftward from the target `` until the substring is unique in the file. `new_string` is the same context with the cell value replaced. This is a best-case scenario for the Edit tool — a human might include more context than the minimum.
**list_tables baseline**: 26 copies of an 18-row GitBook HTML table in a markdown document. Naive = Read the full file (~28k tokens). tablestakes = `list_tables` output with `preview_rows=0..3`:
| `preview_rows` | Tokens | Savings |
|---|---|---|
| 0 (metadata only) | ~1,230 | 96% |
| 1 (default) | ~2,530 | 91% |
| 2 | ~3,510 | 88% |
| 3 | ~4,420 | 84% |
Reproduce: `uv run --with tiktoken python scripts/script.py`
## Quick Start
**Claude Code:**
```bash
claude mcp add tablestakes -- uvx tablestakes
```
**Codex CLI:**
```bash
codex mcp add tablestakes -- uvx tablestakes
```
**Gemini CLI:**
```bash
gemini mcp add tablestakes -- uvx tablestakes
```
Or install from PyPI directly: `pip install tablestakes`
Other clients (Cursor, Windsurf, Claude Desktop)
Add the following JSON to your client's MCP config file:
```json
{
"mcpServers": {
"tablestakes": {
"command": "uvx",
"args": ["tablestakes"]
}
}
}
```
| Client | Config file |
|---|---|
| Cursor | `.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Claude Desktop | `claude_desktop_config.json` |
## Tools
### Discovery & Read
| Tool | Purpose |
|---|---|
| `list_tables(file_path, preview_rows=1)` | Scan file, return all tables with metadata + preview |
| `read_table(file_path, table_index)` | Full table normalized to pipe format + version hash |
### Cell, Row & Column Operations
| Tool | Purpose |
|---|---|
| `update_cells(file_path, table_index, version, updates)` | Batch `{row, column, value}` patches |
| `insert_row(file_path, table_index, version, position, values)` | Insert row at position (-1 to append) |
| `delete_row(file_path, table_index, version, row_index)` | Remove row by index |
| `insert_column(file_path, table_index, version, name, ...)` | Insert column with default value |
| `delete_column(file_path, table_index, version, column)` | Remove column |
| `rename_column(file_path, table_index, version, old_name, new_name)` | Rename header |
| `replace_table(file_path, table_index, version, new_content)` | Full table replacement from pipe input |
| `create_table(file_path, content, position, format)` | Create new table from pipe input (default: HTML) |
All write tools require a `version` hash from `read_table` — optimistic concurrency that prevents stale overwrites without locks.
## Supported Table Formats
| Format | Read | Write | Round-trip |
|---|---|---|---|
| GFM pipe tables | Pass-through | In-place edit | Lossless |
| GitBook collapsed HTML | HTML → pipe | Pipe → collapsed HTML | Preserves `width`, `data-*`, inline formatting |
| General HTML tables | HTML → pipe or pretty HTML | Reconstructs HTML | Preserves structure |
While GitBook is the primary motivation, tablestakes works with any Markdown document containing HTML tables — CMS exports, Notion dumps, wiki migrations, or hand-written HTML in `.md` files.
## Column Addressing
Columns can be referenced by:
- **Letter**: `"A"`, `"B"`, `"AA"` (bijective base-26, like Excel)
- **Name**: `"Priority"` (must be unique)
- **Composite**: `"B:Priority"` (for disambiguation)
- **Index**: `"0"`, `"1"` (0-based)
## Development
```bash
make init # First-time setup: venv + deps + pre-commit hooks
make check # All checks: format + lint + typecheck + test
make test # Run tests only
make test-cov # Tests with coverage report
```
## Author
Built by [Dr. Oliver Borchers](https://www.drborchers.com), Executive AI and Automation Partner and Head of AI Engineering at IU Group.
## License
Apache-2.0
---
mcp-name: io.github.oborchers/tablestakes
|