tablestakes

tablestakes

一个 MCP 服务，为大模型提供对杂乱 HTML 中表格的清晰、精准访问。

问题

GitBook、Notion 导出文件和 CMS 平台等工具在将内容同步到 Markdown 文件时，会把表格压缩成单行 HTML。结果在编辑器中看起来是这样的：

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

这对人类来说难以阅读，对大模型来说也不可靠。模型难以解析压缩后的 HTML 表格，经常会幻觉出错误的单元格边界，而且无法在不破坏结构的情况下编辑它们。

tablestakes 可以解决这个问题。 它位于大模型与文件之间，读取时将表格转换为清晰的管道格式，保存时再以原始格式写回，同时保留 GitBook 兼容性、HTML 属性和内联格式。

大模型看到的内容

发现 — 一次调用即可扫描包含 26 个表格的文档：

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

读取 — 压缩后的 HTML 会变成清晰的管道表格：

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

写入 — 经过版本检查的精准单元格编辑：

v:5749c94ffb1f

14 个字符。文件已更新，GitBook HTML 格式得到保留，width 属性也完好无损。

令牌效率

基准：Claude Code 内置的 Read + Edit 工具对同一文件进行操作。使用一个合成表格进行测量，该表格包含 18 行、4 列，并含有符合真实需求文档风格的内容（粗体 ID、行内强调、长度不一的单元格）。

节省来自以下方面：

• 读取（HTML）：折叠后的 HTML 标签（<td>、<tr>、<th>、<strong>、width="..."）都是纯粹的额外开销。管道表格无需标记即可承载相同信息。Read 工具还会添加 cat -n 行号前缀。

• 读取（GFM）：移除行号前缀和周围文档上下文可带来适度的节省。表格内容本身已经很简洁。

• 写入：Edit 工具要求提供 old_string（足够的上下文，以确保其在文件中唯一）和 new_string（修改后的版本），两者都会作为输出令牌生成。对于 GFM，old_string 是整行（约 190 个字符）。tablestakes 只需 {"row": 0, "column": "B", "value": "Should"}（约 18 个令牌）。

• 发现：如果没有 tablestakes，大模型需要读取整个文件才能找到表格。list_tables 会返回紧凑索引——元数据加上每个表格的 1 行预览。

• 紧凑管道表格不填充列宽。根据 ImprovingAgents 基准测试，GFM 管道表格的令牌与准确率比最佳：成本为 CSV 的 1.24 倍，QA 准确率为 51.9%；优于 JSON（2.08 倍，52.3%）和 YAML（1.88 倍，54.7%）。

快速开始

Claude Code：

claude mcp add tablestakes -- uvx tablestakes

Codex CLI：

codex mcp add tablestakes -- uvx tablestakes

Gemini CLI：

gemini mcp add tablestakes -- uvx tablestakes

也可以直接从 PyPI 安装：pip install tablestakes

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

工具

发现与读取

单元格、行和列操作

所有写入工具都需要从 read_table 获取 version 哈希值——乐观并发机制无需锁定即可防止基于过时数据覆盖内容。

支持的表格格式

虽然 GitBook 是该项目的主要开发动机，但 tablestakes 适用于任何包含 HTML 表格的 Markdown 文档，包括 CMS 导出文件、Notion 转储、wiki 迁移内容，或 .md 文件中手写的 HTML。

列寻址

列可以通过以下方式引用：

• 字母："A"、"B"、"AA"（双射 26 进制，类似 Excel）
• 名称："Priority"（必须唯一）
• 组合形式："B:Priority"（用于消除歧义）
• 索引："0"、"1"（从 0 开始）

开发

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

作者

由 Dr. Oliver Borchers 构建。他是 IU Group 的执行级 AI 与自动化合作伙伴兼 AI 工程负责人。

许可证

Apache-2.0

mcp-name: io.github.oborchers/tablestakes