Tablestakes

io.github.oborchersPublished by GitHub account oborchersv1.1.0Updated Oct 24, 2026

Read and edit HTML/Markdown tables in GitBook-synced documents via MCP tools.

VerifiedSTDIODesktop onlyFiles & StorageDeveloper Tools

Overview

AI-generated overview

MCP server that lets an assistant list, read and surgically edit HTML and Markdown tables in local files, converting collapsed GitBook HTML to pipe tables and…

What you can do
  • List tables in a Markdown file with metadata and a preview row, and read a full table as a clean pipe table with a version hash
  • Edit cells in batches, insert or delete rows, and insert, delete or rename columns
  • Replace a whole table from pipe input or create a new table in HTML or pipe format
  • Round-trip GitBook collapsed HTML and general HTML tables, preserving width and data attributes and inline formatting
When to use it
Useful when documents synced from GitBook, Notion or a CMS contain tables collapsed into single-line HTML that are hard to read and risky to edit, and you want token-efficient, structure-preserving table edits instead of whole-file reads and rewrites.
Requirements
Runs locally as a stdio process; install from PyPI (pip install tablestakes) or run with uvx tablestakes. No accounts, API keys or environment variables are declared. Needs access to the Markdown files being edited.
Before you install
Write tools modify files on disk: cell updates, row and column insertions and deletions, table replacement and creation. Deletions and full-table replacement can lose content. Writes require a version hash from read_table, so stale edits are rejected rather than merged.

Installation

In SourceWeft

  1. Open Tablestakes in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

tablestakes

[PyPI version] [Python versions] [CI] [License]

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.

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-3

Read — 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:5749c94ffb1f

14 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).

OperationRead + EdittablestakesSavings
list_tables (26 HTML tables)~28,400 tokens~2,500 tokens91%
read_table (18-row HTML)~1,100 tokens~690 tokens39%
read_table (18-row GFM)~780 tokens~690 tokens11%
Cell edit (18-row HTML)~35 tokens~27 tokens23%
Cell edit (18-row GFM)~99 tokens~27 tokens73%
10-edit workflow (HTML)~1,470 tokens~960 tokens35%

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 adds cat -n line-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_string is 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_tables returns 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%).

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

preview_rowsTokensSavings
0 (metadata only)~1,23096%
1 (default)~2,53091%
2~3,51088%
3~4,42084%

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"]    }  }}
ClientConfig file
Cursor.cursor/mcp.json
Windsurf~/.codeium/windsurf/mcp_config.json
Claude Desktopclaude_desktop_config.json

Tools

Discovery & Read

ToolPurpose
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

ToolPurpose
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

FormatReadWriteRound-trip
GFM pipe tablesPass-throughIn-place editLossless
GitBook collapsed HTMLHTML → pipePipe → collapsed HTMLPreserves width, data-*, inline formatting
General HTML tablesHTML → pipe or pretty HTMLReconstructs HTMLPreserves 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 hooksmake check     # All checks: format + lint + typecheck + testmake test      # Run tests onlymake test-cov  # Tests with coverage report

Author

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

Source: README.md at commit d1b96b6

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts