tablestakes

tablestakes

Um servidor MCP que dá aos LLMs acesso limpo e cirúrgico a tabelas presas em HTML bagunçado.

O Problema

Ferramentas como GitBook, exportações do Notion e plataformas CMS colapsam tabelas em HTML de linha única ao sincronizar com arquivos Markdown. O resultado fica assim no seu 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>

Isso é ilegível para humanos e não confiável para LLMs. Modelos têm dificuldade em analisar tabelas HTML colapsadas, frequentemente alucinam limites de células e não conseguem editá-las sem corromper a estrutura.

tablestakes resolve isso. Ele fica entre o LLM e o arquivo, convertendo tabelas para o formato pipe limpo na leitura e gravando de volta no formato original ao salvar — preservando compatibilidade com GitBook, atributos HTML e formatação inline.

O que o LLM Vê

Descoberta — escaneie um documento com 26 tabelas em uma única chamada:

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

Leitura — HTML colapsado vira uma tabela pipe limpa:

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

Escrita — edição cirúrgica de célula, com verificação de versão:

v:5749c94ffb1f

14 caracteres. O arquivo é atualizado, o formato HTML do GitBook é preservado, atributos width intactos.

Eficiência de Tokens

Linha de base: ferramentas integradas de Leitura + Edição do Claude Code operando no mesmo arquivo. Medido em uma tabela sintética de 18 linhas e 4 colunas com conteúdo realista de requisitos (IDs em negrito, ênfase inline, células de comprimentos variados).

De onde vêm as economias:

• Leitura (HTML): tags HTML colapsadas (<td>, <tr>, <th>, <strong>, width="...") são puro overhead. Tabelas pipe carregam a mesma informação sem marcação. A ferramenta de Leitura também adiciona prefixos de número de linha cat -n.

• Leitura (GFM): economias modestas ao remover prefixos de número de linha e contexto do documento ao redor. O conteúdo da tabela em si já é limpo.

• Escrita: a ferramenta de Edição exige old_string (contexto suficiente para ser único no arquivo) + new_string (a versão modificada), ambos gerados como tokens de saída. Para GFM, old_string é a linha inteira (~190 caracteres). tablestakes precisa apenas de {"row": 0, "column": "B", "value": "Should"} (~18 tokens).

• Descoberta: sem tablestakes, o LLM lê o arquivo inteiro para encontrar tabelas. list_tables retorna um índice compacto — metadados + 1 linha de pré-visualização por tabela.

• Tabelas pipe compactas sem preenchimento de colunas. De acordo com o benchmark ImprovingAgents, tabelas pipe GFM alcançam a melhor relação token-precisão: 1,24x o custo de CSV com 51,9% de precisão em QA, superando JSON (2,08x, 52,3%) e YAML (1,88x, 54,7%).

Início Rápido

Claude Code:

claude mcp add tablestakes -- uvx tablestakes

Codex CLI:

codex mcp add tablestakes -- uvx tablestakes

Gemini CLI:

gemini mcp add tablestakes -- uvx tablestakes

Ou instale diretamente do PyPI: pip install tablestakes

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

Ferramentas

Descoberta e Leitura

Operações de Célula, Linha e Coluna

Todas as ferramentas de escrita exigem um hash version de read_table — concorrência otimista que previne sobrescritas desatualizadas sem locks.

Formatos de Tabela Suportados

Embora GitBook seja a motivação principal, tablestakes funciona com qualquer documento Markdown contendo tabelas HTML — exportações de CMS, dumps do Notion, migrações de wiki ou HTML escrito à mão em arquivos .md.

Endereçamento de Colunas

Colunas podem ser referenciadas por:

• Letra: "A", "B", "AA" (base-26 bijetiva, como Excel)
• Nome: "Priority" (deve ser único)
• Composto: "B:Priority" (para desambiguação)
• Índice: "0", "1" (baseado em 0)

Desenvolvimento

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

Licença

Apache-2.0

mcp-name: io.github.oborchers/tablestakes