tablestakes

tablestakes

Un servidor MCP que brinda a los LLM acceso limpio y quirúrgico a tablas atrapadas en HTML desordenado.

El problema

Herramientas como GitBook, exportaciones de Notion y plataformas CMS colapsan las tablas en HTML de una sola línea al sincronizar con archivos Markdown. El resultado se ve así en tu 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>

Esto es ilegible para los humanos y poco fiable para los LLM. Los modelos tienen dificultades para analizar tablas HTML colapsadas, con frecuencia alucinan los límites de las celdas y no pueden editarlas sin corromper la estructura.

tablestakes arregla esto. Se sitúa entre el LLM y el archivo, convirtiendo las tablas a un formato pipe limpio al leer y escribiendo de vuelta en el formato original al guardar — preservando la compatibilidad con GitBook, los atributos HTML y el formato en línea.

Lo que ve el LLM

Descubrimiento — escanea un documento de 26 tablas en una sola llamada:

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

Lectura — el HTML colapsado se convierte en una tabla pipe limpia:

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

Escritura — edición quirúrgica de celdas, con verificación de versión:

v:5749c94ffb1f

14 caracteres. El archivo se actualiza, el formato HTML de GitBook se conserva, los atributos width intactos.

Eficiencia de Tokens

Línea base: las herramientas integradas de Lectura + Edición de Claude Code operando sobre el mismo archivo. Medido en una tabla sintética de 18 filas y 4 columnas con contenido realista de estilo requisito (IDs en negrita, énfasis en línea, celdas de longitud mixta).

De dónde provienen los ahorros:

• Lectura (HTML): las etiquetas HTML colapsadas (<td>, <tr>, <th>, <strong>, width="...") son pura sobrecarga. Las tablas pipe llevan la misma información sin marcado. La herramienta de lectura también añade prefijos de número de línea cat -n.

• Lectura (GFM): ahorros modestos al eliminar prefijos de número de línea y contexto circundante del documento. El contenido de la tabla ya está limpio.

• Escritura: la herramienta de edición requiere old_string (suficiente contexto para ser único en el archivo) + new_string (la versión modificada), ambos generados como tokens de salida. Para GFM, old_string es la línea completa de la fila (~190 caracteres). tablestakes solo necesita {"row": 0, "column": "B", "value": "Should"} (~18 tokens).

• Descubrimiento: sin tablestakes, el LLM lee todo el archivo para encontrar tablas. list_tables devuelve un índice compacto — metadatos + 1 fila de vista previa por tabla.

• Tablas pipe compactas sin relleno de columnas. Según el benchmark ImprovingAgents, las tablas pipe GFM logran la mejor relación token-precisión: 1.24x costo CSV con 51.9% de precisión QA, superando a JSON (2.08x, 52.3%) y YAML (1.88x, 54.7%).

Inicio 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

O instala desde PyPI directamente: pip install tablestakes

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

Herramientas

Descubrimiento y Lectura

Operaciones de Celda, Fila y Columna

Todas las herramientas de escritura requieren un hash version de read_table — concurrencia optimista que evita sobrescrituras obsoletas sin bloqueos.

Formatos de Tabla Soportados

Aunque GitBook es la motivación principal, tablestakes funciona con cualquier documento Markdown que contenga tablas HTML — exportaciones de CMS, volcados de Notion, migraciones de wiki, o HTML escrito a mano en archivos .md.

Direccionamiento de Columnas

Las columnas se pueden referenciar por:

• Letra: "A", "B", "AA" (base-26 biyectiva, como Excel)
• Nombre: "Priority" (debe ser único)
• Compuesto: "B:Priority" (para desambiguación)
• Índice: "0", "1" (basado en 0)

Desarrollo

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

Licencia

Apache-2.0

mcp-name: io.github.oborchers/tablestakes