twilize

Kit de herramientas de generación de libros de trabajo de Tableau (.twb/.twbx) para paneles reproducibles e ingeniería de libros de trabajo Cree libros de trabajo de Tableau mediante programación con primitivas analíticas estables, composición de paneles y validación estructural integrada.

Descripción general

twilize es un servidor del Protocolo de Contexto de Modelo (MCP) y un kit de herramientas de Python para generar archivos de libro de trabajo de Tableau Desktop (.twb / .twbx) a partir de código o llamadas a herramientas impulsadas por IA.

Está diseñado como una capa de ingeniería de libros de trabajo, no como un agente de exploración de datos conversacional. El objetivo es hacer que la generación de libros de trabajo sea reproducible, inspeccionable y segura de automatizar en flujos de trabajo locales, scripts e integración continua (CI).

El flujo de trabajo predeterminado es:

1. Comenzar desde una plantilla conocida (.twb o .twbx) o la plantilla integrada de configuración cero

2. Agregar campos calculados y parámetros

3. Crear hojas de trabajo a partir de primitivas de gráficos estables

4. Ensamblar paneles e interacciones

5. Guardar y validar un .twb o .twbx que se abra en Tableau Desktop

                            Interfaces
  ┌───────────────────────────────────────────────────────────────┐
  │  ┌──────────────────────────┐  ┌───────────────────────────┐  │
  │  │        MCP Server        │  │      Python Library       │  │
  │  │  tools_workbook          │  │  from twilize.twb_editor    │  │
  │  │  tools_layout            │  │  import TWBEditor         │  │
  │  │  tools_migration         │  │                           │  │
  │  │  tools_support           │  │  editor.add_...()         │  │
  │  │                          │  │  editor.configure_...()   │  │
  │  │  (Claude / Cursor /      │  │  editor.save(...)         │  │
  │  │   VSCode / Claude Code)  │  │                           │  │
  │  └─────────────┬────────────┘  └──────────────┬────────────┘  │
  │                └──────────────┬────────────────┘               │
  └─────────────────────────────  ┼  ─────────────────────────────┘
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                          TWBEditor                            │
  │       ParametersMixin  ·  ConnectionsMixin                    │
  │       ChartsMixin      ·  DashboardsMixin                     │
  └──────────┬──────────────────┬──────────────────┬─────────────┘
             ▼                  ▼                  ▼
  ┌──────────────────┐  ┌──────────────┐  ┌──────────────────────┐
  │  Chart Builders  │  │  Dashboard   │  │  Analysis &          │
  │                  │  │  System      │  │  Migration           │
  │  Basic  DualAxis │  │              │  │                      │
  │  Pie    Text     │  │  layouts     │  │  migration.py        │
  │  Map    Recipes  │  │  actions     │  │  twb_analyzer.py     │
  │                  │  │  dependencies│  │  capability_registry │
  └────────┬─────────┘  └──────┬───────┘  └──────────┬───────────┘
           └───────────────────┼──────────────────────┘
                               ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                     XML Engine  (lxml)                        │
  │    template.twb/.twbx  →  patch  →  validate  →  save        │
  └───────────────────────────────┬───────────────────────────────┘
                                  ▼
                      output.twb  /  output.twbx

Instalación

pip install twilize

Para ejecutar el ejemplo incluido respaldado por Hyper que inspecciona archivos .hyper y resuelve automáticamente la tabla física Orders_*, instale también la dependencia de ejemplo opcional:

pip install "twilize[examples]"

Requisitos

• Python >= 3.10

• lxml >= 5.0

• uv

• mcp >= 1.0

Inicio rápido

Como servidor MCP

Para permitir que un cliente MCP cree libros de trabajo de Tableau automáticamente, agregue twilize a la configuración MCP de ese cliente.

El comando de inicio es el mismo en todos los clientes:

uvx twilize

Cada cliente almacena este comando en un formato de configuración diferente. Utilice el ejemplo correspondiente a continuación.

Claude Desktop

Abra ~/Library/Application Support/Claude/claude_desktop_config.json en macOS o %APPDATA%\Claude\claude_desktop_config.json en Windows y agregue:

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

Cursor IDE

1. Abra Cursor Settings -> Features -> MCP

2. Haga clic en Add New MCP Server

3. Establezca Type en command

4. Establezca Name en twilize

5. Establezca Command en uvx twilize

Claude Code

claude mcp add twilize -- uvx twilize

VSCode

Abra el archivo .vscode/mcp.json del área de trabajo o su archivo mcp.json de perfil de usuario y agregue:

{
  "servers": {
    "twilize": {
      "command": "uvx",
      "args": ["twilize"]
    }
  }
}

En VSCode, puede abrir estos archivos desde la Paleta de comandos con MCP: Open Workspace Folder Configuration o MCP: Open User Configuration. También puede usar MCP: Add Server e ingresar el mismo comando uvx twilize a través del flujo guiado.

Como biblioteca de Python

Use TWBEditor(...) para comenzar desde una plantilla y reconstruir el contenido del libro de trabajo. Use TWBEditor.open_existing(...) cuando desee mantener las hojas de trabajo y paneles existentes y reconfigurar una hoja en su lugar.

from twilize.twb_editor import TWBEditor

editor = TWBEditor("")  # "" uses the built-in Superstore template
editor.clear_worksheets()
editor.add_calculated_field("Profit Ratio", "SUM([Profit])/SUM([Sales])")

editor.add_worksheet("Sales by Category")
editor.configure_chart(
    worksheet_name="Sales by Category",
    mark_type="Bar",
    rows=["Category"],
    columns=["SUM(Sales)"],
)

editor.add_worksheet("Segment Pie")
editor.configure_chart(
    worksheet_name="Segment Pie",
    mark_type="Pie",
    color="Segment",
    wedge_size="SUM(Sales)",
)

editor.add_dashboard(
    dashboard_name="Overview",
    worksheet_names=["Sales by Category", "Segment Pie"],
    layout="horizontal",
)

editor.save("output/my_workbook.twb")

Trabajo con libros de trabajo empaquetados (.twbx)

Los archivos .twbx son archivos ZIP que agrupan el XML del libro de trabajo junto con extractos de datos (.hyper) y activos de imagen. twilize los lee y escribe de forma transparente:

from twilize.twb_editor import TWBEditor

# Open a packaged workbook — extracts and images are preserved automatically
editor = TWBEditor.open_existing("templates/dashboard/MyDashboard.twbx")

# Make changes as usual
editor.add_calculated_field("Profit Ratio", "SUM([Profit])/SUM([Sales])")

# Save as .twbx — re-bundles the updated .twb with the original extracts/images
editor.save("output/MyDashboard_v2.twbx")

# Or extract just the XML when the packaged format isn't needed
editor.save("output/MyDashboard_v2.twb")

Un .twb simple también se puede empaquetar:

editor = TWBEditor("templates/twb/superstore.twb")
# ...
editor.save("output/superstore.twbx")  # produces a single-entry ZIP with the .twb inside

Herramientas MCP

Modelo de capacidad

Primitivas principales

Estos son los bloques de construcción estables que el proyecto debe seguir prometiendo:

• Barra

• Línea

• Área

• Circular

• Mapa

• Texto / Tarjetas KPI

• Parámetros y campos calculados

• Composición básica de paneles

Patrones avanzados

Estos son compatibles, pero son composiciones de nivel superior o características de interacción en lugar del área de superficie predeterminada:

• Gráfico de dispersión

• Mapa de calor

• Mapa de árbol

• Gráfico de burbujas

• Doble eje — mark_color_1/2, color_map_1, reverse_axis_1, hide_zeroline, synchronized

• Cálculos de tabla — RANK_DENSE, RUNNING_SUM, WINDOW_SUM mediante add_calculated_field(table_calc="Rows")

• Insignias de diferencia de KPI — eje ficticio MIN(1) + axis_fixed_range + color_map + customized_label

• Donut (mediante extra_axes) — gráfico circular multipanel + círculo blanco usando configure_dual_axis(extra_axes=[...]); admite color_map para la paleta :Measure Names

• Etiquetas de texto enriquecido — configure_chart(label_runs=[...]) para tarjetas KPI de estilo múltiple y títulos dinámicos con valores de campo en línea

• Estilo avanzado de hoja de trabajo — configure_worksheet_style admite estilos de celda/etiqueta de datos/marca a nivel de panel, formatos de etiqueta/celda/encabezado por campo, control de marcas de eje, desactivación de información sobre herramientas y todas las supresiones de ruido visual de Tableau

• Supresión de encabezado de dimensión de fila — configure_worksheet_style(hide_row_label="FieldName")

• Zonas de filtro, controles de parámetros, leyendas de color

• Acciones de filtro y resaltado de panel

• Flujos de trabajo de diseño JSON declarativos

• Control de título de zona de panel mediante show_title: false en diccionarios de diseño

Recetas y patrones de muestra

Estos se pueden generar hoy, pero deben tratarse como recetas o ejemplos en lugar de promesas de primera clase:

• Donut

• Lollipop

• Bullet

• Bump

• Butterfly

• Calendar

Los gráficos de receta se exponen intencionalmente a través de una única herramienta configure_chart_recipe para que la superficie pública de MCP no crezca una herramienta a la vez para cada patrón de muestra.

Esta distinción es importante porque twilize no intenta convertirse en un zoológico de gráficos ni competir con las propias herramientas de análisis conversacional de Tableau. El proyecto es más fuerte cuando proporciona una capa de generación de libros de trabajo confiable y automatizable.

Flujo de trabajo de capacidad primero

Cuando no esté seguro de si algo pertenece a la superficie estable del SDK:

1. Use list_capabilities para inspeccionar el límite declarado

2. Use describe_capability para verificar un gráfico, codificación o característica específica

3. Use analyze_twb o diff_template_gap antes de buscar una plantilla de muestra

Esto mantiene el trabajo de nuevas características alineado con el límite real del producto del proyecto en lugar de con lo que sea que aparezca en un libro de trabajo de muestra.

Validación integrada

Validación estructural

save() valida automáticamente la estructura XML del TWB antes de escribir:

• Errores fatales como la falta de <workbook> o <datasources> generan TWBValidationError

• Advertencias como la falta de <view> o <panes> se registran pero no bloquean el guardado

• La validación se puede desactivar con editor.save("output.twb", validate=False) o editor.save("output.twbx", validate=False)

Validación de esquema XSD

TWBEditor.validate_schema() verifica el libro de trabajo frente al esquema XSD oficial de Tableau TWB (2026.1), vendido en vendor/tableau-document-schemas/:

result = editor.validate_schema()
print(result.to_text())
# PASS  Workbook is valid against Tableau TWB XSD schema (2026.1)
# — or —
# FAIL  Schema validation failed (2 error(s)):
#   * Element 'workbook': Missing child element(s)...

result.valid          # bool
result.errors         # list[str] — lxml error messages
result.schema_available  # False if the vendor submodule is not checked out

La misma verificación está disponible como una herramienta MCP:

validate_workbook()                       # validate current open workbook in memory
validate_workbook(file_path="out.twb")    # validate a file on disk (.twb or .twbx)

Los errores XSD son informativos — Tableau mismo genera libros de trabajo que ocasionalmente se desvían del esquema — pero los errores recurrentes señalan problemas estructurales que vale la pena solucionar.

Diseños de panel

Los diseños personalizados se pueden construir mediante programación utilizando un diccionario de layout anidado o mediante generate_layout_json para flujos de trabajo MCP.

Ejemplo respaldado por Hyper

El ejemplo examples/hyper_and_new_charts.py utiliza el extracto Sample - EU Superstore.hyper incluido directamente en el paquete (src/twilize/references/) y resuelve la tabla física Orders_* a través de la API de Tableau Hyper antes de cambiar la conexión del libro de trabajo. No se necesita clonar el repositorio: instálelo con pip install "twilize[examples]" y ejecútelo directamente.

Migración de libros de trabajo

twilize incluye un subsistema de migración para cambiar un .twb existente a una nueva fuente de datos; por ejemplo, redirigir un libro de trabajo creado en un archivo de Excel a un Excel diferente con un esquema diferente, o migrar entre variantes de idioma del mismo conjunto de datos.

Cómo funciona

La migración es un flujo de trabajo de varios pasos. Cada paso está disponible tanto como herramienta MCP como función de Python:

1. inspect_target_schema   →  Scan the target Excel and list its columns
2. profile_twb_for_migration  →  Inventory which fields the workbook uses
3. propose_field_mapping   →  Match source fields to target columns (fuzzy)
4. preview_twb_migration   →  Dry-run: show what would change, blockers/warnings
5. apply_twb_migration     →  Write the migrated .twb + JSON reports

migrate_twb_guided es un contenedor de conveniencia que ejecuta los pasos 2–5 en secuencia y se pausa automáticamente cuando solo quedan coincidencias de campo de baja confianza, devolviendo un warning_review_bundle para revisión humana antes de continuar.

Ejemplo de Python

from twilize.migration import migrate_twb_guided_json
import json

# One-call guided migration
result = migrate_twb_guided_json(
    file_path="templates/SalesDashboard.twb",
    target_source="data/new_data_source.xlsx",
    output_path="output/SalesDashboard_migrated.twb",
)
bundle = json.loads(result)

if bundle["status"] == "warning_review_required":
    # Inspect low-confidence matches and confirm or override them
    print(bundle["warning_review_bundle"])
    # Re-run with confirmed mappings
    result = migrate_twb_guided_json(
        file_path="templates/SalesDashboard.twb",
        target_source="data/new_data_source.xlsx",
        output_path="output/SalesDashboard_migrated.twb",
        mapping_overrides={"Old Field Name": "New Column Name"},
    )

Ejemplo de herramienta MCP

Cuando se usa twilize como servidor MCP, un agente de IA puede ejecutar el flujo de trabajo completo:

inspect_target_schema(target_source="data/new_data_source.xlsx")
→ returns column list and data types

migrate_twb_guided(
    file_path="templates/SalesDashboard.twb",
    target_source="data/new_data_source.xlsx",
    output_path="output/SalesDashboard_migrated.twb"
)
→ returns status: "applied" or "warning_review_required"

Archivos de salida

Una migración completada escribe tres archivos:

Parámetro de alcance

scope="workbook" migra todas las hojas de trabajo. Pase un nombre de hoja de trabajo para limitar la migración a una sola hoja.

Ejemplo autónomo

examples/migrate_workflow/ contiene una plantilla .twb, el Excel original de Superstore, un Excel de Superstore de configuración regional china de destino y un script ejecutable:

python examples/migrate_workflow/test_migration_workflow.py

Estructura del proyecto

twilize/
|-- src/twilize/
|   |-- __init__.py
|   |-- capability_registry.py
|   |-- config.py
|   |-- charts/
|   |-- connections.py
|   |-- dashboard_actions.py
|   |-- dashboard_dependencies.py
|   |-- dashboard_layouts.py
|   |-- dashboards.py
|   |-- field_registry.py
|   |-- layout.py
|   |-- layout_model.py
|   |-- layout_rendering.py
|   |-- mcp/
|   |-- parameters.py
|   |-- twb_analyzer.py
|   |-- twb_editor.py
|   |-- validator.py
|   `-- server.py
|-- tests/
|-- examples/
|-- docs/
|-- pyproject.toml
`-- README.md

Desarrollo

# Install in editable mode
pip install -e .

# Run test suite
pytest --basetemp=output/pytest_tmp

# Run the mixed showcase example
python examples/scripts/demo_all_supported_charts.py

# Run the advanced Hyper-backed example
python examples/scripts/demo_hyper_and_new_charts.py

# Run the guided migration example
python examples/migrate_workflow/test_migration_workflow.py

# Start MCP server
twilize

Manifiesto del servidor MCP

twilize se envía con un manifiesto de servidor MCP completo (mcp-server.json), el equivalente MCP de un archivo .trex de extensión de Tableau. Declara:

Además, el manifiesto declara las 40 herramientas con categorías, 6 recursos y configuraciones de cliente preconstruidas para Claude Desktop, Cursor, VS Code y Claude Code.

Para obtener la referencia completa de herramientas con esquemas de parámetros, consulte docs/MCP_SERVER.md.

Publicación

PyPI

pip install build twine
python -m build
twine upload dist/*

Registro MCP de Smithery

El archivo smithery.yaml está listo para enviarse a Smithery.

Registro de servidor MCP

El archivo mcp-server.json sigue el esquema del servidor MCP para el envío al registro.

Licencia

AGPL-3.0-or