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.

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

Output is optimized for LLM context windows. Measured against a real 26-table document:

Key optimizations:

• Write tools return only v:{hash} (4 tokens) instead of echoing the full table (~1,500 tokens). The LLM already has the table from read_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%).
• No structuredContent duplication — output_schema=None on all tools prevents FastMCP from sending the response twice.

Quick Start

Claude Code:

claude mcp add tablestakes -- uvx tablestakes

Codex CLI:

codex mcp add tablestakes -- uvx tablestakes

Gemini CLI:

gemini mcp add tablestakes -- uvx tablestakes

Or install from PyPI directly: pip install tablestakes

{
  "mcpServers": {
    "tablestakes": {
      "command": "uvx",
      "args": ["tablestakes"]
    }
  }
}

Tools

Discovery & Read

Cell, Row & Column Operations

All write tools require a version hash from read_table — optimistic concurrency that prevents stale overwrites without locks.

Supported Table Formats

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 report

License

Apache-2.0

mcp-name: io.github.oborchers/tablestakes