tablestakes
You can discover, read, search, and safely edit tables embedded in Markdown files, including GFM pipe tables and collapsed HTML/GitBook tables.
List all tables in a file with metadata, previews, column descriptors, and version hashes.
Read a full table as a clean pipe table while preserving inline formatting.
Search table rows across one or all tables using substring or regex matching.
Batch-update cell values by row and column identifier.
Insert or delete rows and columns.
Rename column headers.
Replace an entire table from pipe-table input.
Create new tables as collapsed HTML (GitBook-compatible) or GFM pipe format.
Use version hashes for optimistic concurrency and stale-write protection.
Preserve original table format and HTML attributes when writing back to GitBook/HTML tables.
Provides read/write access to tables in GitBook HTML/Markdown exports, converting collapsed HTML tables to compact pipe format and writing changes back while preserving GitBook-compatible HTML attributes and inline formatting.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tablestakes list the tables in this HTML file"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tablestakes
An MCP server that gives LLMs clean, surgical access to tables trapped in messy HTML.
The Problem
Tools like GitBook, Notion exports, and CMS platforms collapse tables into single-line HTML when syncing to Markdown files. The result looks like this in your editor:
<table><thead><tr><th width="520.11">Requirement</th><th width="122.07">Priority</th><th>Priority 1-2-3</th></tr></thead><tbody><tr><td><strong>1.1</strong> Agent sees only their Salesforce-assigned cases <strong>in the currently selected organization</strong> (case is "assigned" when SF <code>Case.OwnerId</code> matches the agent's linked SF user ID)...</td><td>Must</td><td>1</td></tr></tbody></table>This is unreadable for humans and unreliable for LLMs. Models struggle to parse collapsed HTML tables, frequently hallucinate cell boundaries, and cannot edit them without corrupting the structure.
tablestakes fixes this. It sits between the LLM and the file, converting tables to clean pipe format on read and writing back in the original format on save — preserving GitBook compatibility, HTML attributes, and inline formatting.
Related MCP server: tablekit-mcp
What the LLM Sees
Discovery — scan a 26-table document in one call:
26 tables
T0 pipe 5r 3c v:485f65f7b470 [Cross-Domain Dependencies]
A:Integration | B:Source | C:Requirements
T2 gitbook 18r 3c v:77a9495fd328 [Case List]
A:Requirement | B:Priority | C:Priority 1-2-3
T7 gitbook 3r 4c v:d9a9a45a370f [Attachments]
A:Requirement | B:Priority | C:Dependency | D:Priority 1-2-3Read — collapsed HTML becomes a clean pipe table:
v:d9a9a45a370f gitbook 3r 4c [Attachments]
A:Requirement | B:Priority | C:Dependency | D:Priority 1-2-3
| Requirement | Priority | Dependency | Priority 1-2-3 |
| --- | --- | --- | --- |
| **5.1** View inbound attachments in-app... | Must | — | 1 |
| **5.2** Send outbound attachments... | Must | Blocked on SF API | 1 |
| **5.3** Attachment file size limits... | Should | — | |Write — surgical cell edit, version-checked:
v:5749c94ffb1f14 characters. The file is updated, GitBook HTML format preserved, width attributes intact.
Token Efficiency
Baseline: Claude Code's built-in Read + Edit tools operating on the same file. Measured on a synthetic 18-row, 4-column table with realistic requirement-style content (bold IDs, inline emphasis, mixed-length cells).
Operation | Read + Edit | tablestakes | Savings |
| ~28,400 tokens | ~2,500 tokens | 91% |
| ~1,100 tokens | ~690 tokens | 39% |
| ~780 tokens | ~690 tokens | 11% |
Cell edit (18-row HTML) | ~35 tokens | ~27 tokens | 23% |
Cell edit (18-row GFM) | ~99 tokens | ~27 tokens | 73% |
10-edit workflow (HTML) | ~1,470 tokens | ~960 tokens | 35% |
Where the savings come from:
Read (HTML): collapsed HTML tags (
<td>,<tr>,<th>,<strong>,width="...") are pure overhead. Pipe tables carry the same information without markup. The Read tool also addscat -nline-number prefixes.Read (GFM): modest savings from stripping line-number prefixes and surrounding document context. The table content itself is already clean.
Write: the Edit tool requires
old_string(enough context to be unique in the file) +new_string(the modified version), both generated as output tokens. For GFM,old_stringis the entire row line (~190 chars). tablestakes needs only{"row": 0, "column": "B", "value": "Should"}(~18 tokens).Discovery: without tablestakes, the LLM reads the entire file to find tables.
list_tablesreturns a compact index — metadata + 1 preview row per table.Compact pipe tables with no column padding. Per the ImprovingAgents benchmark, GFM pipe tables achieve the best token-to-accuracy ratio: 1.24x CSV cost at 51.9% QA accuracy, beating JSON (2.08x, 52.3%) and YAML (1.88x, 54.7%).
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 <td> 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:
| 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:
claude mcp add tablestakes -- uvx tablestakesCodex CLI:
codex mcp add tablestakes -- uvx tablestakesGemini CLI:
gemini mcp add tablestakes -- uvx tablestakesOr install from PyPI directly: pip install tablestakes
Add the following JSON to your client's MCP config file:
{
"mcpServers": {
"tablestakes": {
"command": "uvx",
"args": ["tablestakes"]
}
}
}Client | Config file |
Cursor |
|
Windsurf |
|
Claude Desktop |
|
Tools
Discovery & Read
Tool | Purpose |
| Scan file, return all tables with metadata + preview |
| Full table normalized to pipe format + version hash |
Cell, Row & Column Operations
Tool | Purpose |
| Batch |
| Insert row at position (-1 to append) |
| Remove row by index |
| Insert column with default value |
| Remove column |
| Rename header |
| Full table replacement from pipe input |
| 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 |
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
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 reportAuthor
Built by Dr. Oliver Borchers, Executive AI and Automation Partner and Head of AI Engineering at IU Group.
License
Apache-2.0
mcp-name: io.github.oborchers/tablestakes
Available Tools
11 toolscreate_tableA
Create a new table in a Markdown file. Provide content as a pipe table.
The table is written in the specified format: "html" (default, collapsed single-line HTML suitable for GitBook) or "pipe" (GFM pipe table).
No version hash needed — this creates, not edits.
On success returns v:{hash} of the new table. Use this hash with
read_table and write tools to edit the table immediately.
On error returns JSON with "error" and "message" fields.
Args: file_path: Absolute path to the Markdown file. Created if it doesn't exist. content: Table in pipe format (header row + delimiter + data rows). Example: "| Name | Age |\n| --- | --- |\n| Alice | 30 |" position: 1-based line number to insert AFTER. -1 appends (default). 0 inserts at top. format: "html" (default) or "pipe". HTML produces collapsed single-line GitBook-compatible output. GitBook will auto-add width/data-* attributes on sync.
Inputs: content (required), file_path (required), format, position.
delete_columnA
Delete a column. Requires version hash from read_table.
On success returns ONLY v:{new_hash}.
On error returns JSON with "error" and "message" fields.
Args: file_path: Absolute path to the Markdown file. table_index: 0-based table index from list_tables. version: 12-char hex hash from read_table (after "v:"). column: Column letter ("A"), name ("Priority"), or composite ("B:Priority").
Inputs: column (required), version (required), file_path (required), table_index (required).
delete_rowA
Delete a row. Requires version hash from read_table.
On success returns ONLY v:{new_hash}.
On error returns JSON with "error" and "message" fields.
Args: file_path: Absolute path to the Markdown file. table_index: 0-based table index from list_tables. version: 12-char hex hash from read_table (after "v:"). row_index: 0-based data row index to delete (header row is NOT counted).
Inputs: version (required), file_path (required), row_index (required), table_index (required).
insert_columnA
Insert a new column. Requires version hash from read_table.
All existing rows are populated with default_value (empty string if omitted).
On success returns ONLY v:{new_hash}.
On error returns JSON with "error" and "message" fields.
Args: file_path: Absolute path to the Markdown file. table_index: 0-based table index from list_tables. version: 12-char hex hash from read_table (after "v:"). name: Header text for the new column. default_value: Value for all existing rows (default: empty string). position: 0-based column index for insertion. -1 appends to the right (default).
Inputs: name (required), version (required), file_path (required), table_index (required), +2 more.
insert_rowA
Insert a new row. Requires version hash from read_table.
Provide values as a dict mapping column identifiers to cell content. Column identifiers: letter ("A"), name ("Priority"), or composite ("B:Priority"). Omitted columns default to empty string.
On success returns ONLY v:{new_hash}.
On error returns JSON with "error" and "message" fields.
Args: file_path: Absolute path to the Markdown file. table_index: 0-based table index from list_tables. version: 12-char hex hash from read_table (after "v:"). position: 0-based row index for insertion. Use -1 to append at the end. values: Dict mapping column identifiers to cell values. Example: {"Name": "Alice", "B": "30", "C:City": "NYC"}
Inputs: values (required), version (required), position (required), file_path (required), +1 more.
list_tablesA
List all tables in a Markdown file with column descriptors and row previews.
Prefer this over grep for discovering table structure — returns column names, row counts, formats, and version hashes. Use search_tables to find specific data across tables.
Output format per table: T{index} {format} {rows}r {cols}c v:{hash} [{section heading}] {column descriptors as A:Name | B:Age | ...} row0: {first row cell values}
Use table_index (the number after T) with read_table and write tools.
Args: file_path: Absolute path to the Markdown file. preview_rows: Number of data rows to preview (default 1, 0 for none).
Inputs: file_path (required), preview_rows.
read_tableA
Read a full table as a clean pipe table with version hash.
Prefer this over reading files directly — handles HTML tables, preserves inline formatting, and returns the version hash needed for any edit.
First line of output is metadata: v:{hash} {format} {rows}r {cols}c [{section}] Extract the 12-char hex hash after "v:" (e.g. "a1b2c3d4e5f6") and pass it as the version argument to any write tool.
If a write returns STALE_READ, call read_table again for a fresh version.
Args: file_path: Absolute path to the Markdown file. table_index: 0-based table index from list_tables (the number after T).
Inputs: file_path (required), table_index (required).
rename_columnA
Rename a column header. Row data is unchanged. Requires version from read_table.
On success returns ONLY v:{new_hash}.
On error returns JSON with "error" and "message" fields.
Args: file_path: Absolute path to the Markdown file. table_index: 0-based table index from list_tables. version: 12-char hex hash from read_table (after "v:"). old_name: Current column identifier: letter ("A"), name, or composite ("B:Priority"). new_name: New header text for the column.
Inputs: version (required), new_name (required), old_name (required), file_path (required), +1 more.
replace_tableA
Replace an entire table with new content. Requires version from read_table.
Provide new_content as a pipe table string (header row + delimiter + data rows). The server writes back in the ORIGINAL file format: pipe stays pipe, GitBook HTML stays GitBook HTML (attributes preserved).
On success returns ONLY v:{new_hash}.
On error returns JSON with "error" and "message" fields.
Args: file_path: Absolute path to the Markdown file. table_index: 0-based table index from list_tables. version: 12-char hex hash from read_table (after "v:"). new_content: Full pipe table string including header and delimiter rows.
Inputs: version (required), file_path (required), new_content (required), table_index (required).
search_tablesA
Search for rows matching a value across one or all tables in a file.
Returns matching rows with table index, row index, and version hash so you can immediately follow up with a write tool. Prefer this over grep for table data — it understands column structure and handles HTML tables.
Two search modes (regex overrides pattern if both given):
pattern: case-insensitive substring match (simple, no escaping needed)
regex: full regex via re.search (e.g.
D 1\.\d+for sub-items)
If neither pattern nor regex is provided, returns all rows.
Args: file_path: Absolute path to the Markdown file. pattern: Case-insensitive substring to match in cell values. regex: Regular expression to match in cell values (overrides pattern). table_index: Search a specific table (0-based), or -1 for all tables. column: Restrict search to a column (letter, name, or composite). Empty string searches all columns.
Inputs: file_path (required), regex, column, pattern, +1 more.
update_cellsA
Batch-update cells. Requires version hash from read_table.
Each update is {row, column, value} where:
row: 0-based data row index (header row is NOT counted)
column: letter ("A"), name ("Priority"), or composite ("B:Priority")
value: new cell content (Markdown inline formatting supported)
On success returns ONLY v:{new_hash}.
On error returns JSON: {"error": "STALE_READ"|"EDIT_ERROR"|..., "message": "..."}.
If STALE_READ: call read_table again for current version, then retry.
Args: file_path: Absolute path to the Markdown file. table_index: 0-based table index from list_tables. version: 12-char hex hash from read_table (after "v:", e.g. "a1b2c3d4e5f6"). updates: List of {row: int, column: str, value: str} objects.
Inputs: updates (required), version (required), file_path (required), table_index (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct operation: reading, listing, searching, creating/replacing tables, and row/column/cell mutations. Potential overlap between list_tables and read_table is resolved by their clearly different purposes (preview metadata vs full content).
All tools follow a consistent action_noun snake_case pattern: update_cells, insert_row, delete_row, list_tables, read_table, etc. Verb choice is predictable and the pattern makes the operation and target clear at a glance.
With 11 tools, the server is well-scoped for Markdown table management. Each tool covers a meaningful operation without redundancy, and the count sits comfortably within the ideal range.
The surface covers table CRUD, row insertion/deletion, column insertion/deletion/renaming, cell updates, searching, and reading. A notable minor gap is the lack of a delete_table tool, though replace_table can approximate it in some cases.
Maintenance
Related MCP Connectors
Convert PDF, DOCX, HTML, and URLs to clean, LLM-ready markdown with tables preserved
Convert PDF, Word, Excel, PowerPoint, e-mails and web pages to clean Markdown for LLMs.
Pull tables out of a PDF as rows and cells, ready for a spreadsheet or a data pipeline.
Convert any web page into clean, LLM-ready Markdown. Strips ads, navigation and clutter; keeps headings, tables, code and links.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceProvides multimodal OCR table grid and merged-cell reconstruction into Markdown, and integrates with MCP-compliant clients like Claude Desktop and Cursor.1-
- AlicenseAqualityCmaintenanceConverts, aligns, reshapes, and inspects tabular data across Markdown, CSV, TSV, JSON, and HTML with CJK-aware alignment and deterministic transformations, entirely offline and without file access.4MIT
- AlicenseNot gradedqualityBmaintenanceEnables deterministic reconstruction of complex tables from OCR bounding-box payloads, recovering multi-column layouts, merged headers, and grid hierarchies. It also supports formula consistency auditing and sensitive PII redaction for document processing pipelines.7MIT
- AlicenseNot gradedqualityBmaintenanceEnables converting Markdown and HTML tables into structured JSON records with automatic column type inference and format normalization. It also offers supporting web-agent primitives such as DOM semantic pruning, form field auto-mapping, and execution trajectory evaluation, all via a zero-dependency MCP server.7MIT