cwtwb

generar archivo de tableau

Documentación

cwtwb

Ingeniería de libros de trabajo de Tableau para generación, validación y migración reproducibles de .twb / .twbx.

cwtwb hero image

cwtwb es un kit de herramientas de Python y un servidor de Protocolo de Contexto de Modelo (MCP) para construir libros de trabajo de Tableau Desktop desde código o llamadas a herramientas de agentes.

Está pensado para ser una capa de ingeniería de libros de trabajo, no un agente conversacional de análisis. El enfoque está en la reproducibilidad, la inspeccionabilidad y la automatización segura en flujos de trabajo locales, scripts y CI.

Referencia del flujo de trabajo de diseño

El flujo de trabajo de diseño del agente y la habilidad design_advisor se basan en las habilidades de flujo de trabajo de Tableau de Adam Mico adammico-lab Tableau workflow skills, especialmente el enfoque de construcción a partir de una especificación de diseño de Tableau Dashboard Blueprint. cwtwb adapta de forma independiente esas ideas a la creación reproducible de .twb / .twbx; no depende de, no incluye ni copia código o contenido de habilidades de adammico-lab. cwtwb no está afiliado con Adam Mico, Salesforce ni Tableau.

El cw en cwtwb proviene de Cooper Wenhua.

Autor: Cooper Wenhua <imgwho@gmail.com>

Sitio web · Código fuente · Registro de cambios

Historial de estrellas

Prueba el flujo de trabajo de ejemplo · Lee la guía

Inicio rápido

Instalación

pip install cwtwb

Si también quieres el ejemplo incluido con soporte Hyper:

pip install "cwtwb[examples]"

Si quieres validación en la nube (subida a Tableau Cloud/Server):

pip install "cwtwb[validate]"

Ejecutar como servidor MCP

uvx cwtwb

La forma corta anterior sigue siendo la opción más simple y es la configuración predeterminada que se muestra en este repositorio. cwtwb es un punto de entrada inteligente: sin argumentos en una terminal interactiva imprime la ayuda de la CLI; cuando lo lanza un cliente MCP a través de stdio, inicia el servidor.

Añade el servidor a tu cliente MCP con el mismo comando. Por ejemplo:

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

Para Claude Code:

claude mcp add cwtwb -- uvx cwtwb

Para VSCode, añade cwtwb a tu espacio de trabajo o mcp.json de usuario y usa uvx cwtwb como comando.

Si prefieres un nombre de script explícito, estos estilos de lanzamiento equivalentes también funcionan:

uvx cwtwb mcp
uvx --from cwtwb cwtwb-mcp
python -m cwtwb.mcp_server

Uso como CLI

El mismo paquete también expone flujos de trabajo de línea de comandos de primera clase para humanos, scripts, CI y agentes que necesitan operaciones directas con archivos en lugar de llamadas a herramientas MCP.

cwtwb --help
cwtwb doctor
cwtwb status --json
cwtwb inspect workbook.twb --json
cwtwb validate workbook.twb
cwtwb analyze workbook.twb --json
cwtwb run examples/specs/basic_cli.yaml

Los comandos de escritura comunes requieren una ruta de salida explícita por defecto:

cwtwb create --out output/base.twb
cwtwb chart add output/base.twb --worksheet "Sales by Category" --mark Bar --rows Category --columns "SUM(Sales)" --out output/chart.twb
cwtwb dashboard add output/chart.twb --name Overview --worksheets "Sales by Category" --out output/dashboard.twb

Usa --in-place solo cuando quieras sobrescribir intencionalmente el libro de trabajo de entrada, y --force solo al reemplazar un archivo de salida existente.

Estabilidad del cliente MCP

Cuando cwtwb está conectado como servidor MCP, los agentes deben llamar a las herramientas MCP expuestas directamente a través de su cliente. No deben ejecutar comandos de shell como mcp call cwtwb ..., mcp list-tools cwtwb o gh api .../mcp/...; esos comandos no forman parte de cwtwb y normalmente no están disponibles en entornos normales de Claude, Codex, Cursor o VSCode.

Si un agente no puede ver herramientas como create_workbook, add_worksheet o save_workbook, reinicia o vuelve a conectar el cliente MCP y verifica la configuración del servidor. Limpiar la caché de uv solo actualiza los paquetes instalados; no corrige una superficie de herramientas de cliente obsoleta.

Al usar un .twb existente como referencia visual, los agentes no deben copiar tokens de instancia de columna del XML de Tableau en las entradas de gráficos. Valores como [sum:Sales:qk], [none:Category:nk], [mn:Order Date:ok] o [federated.xxx].[sum:Profit:qk] son internos generados. Pasa expresiones orientadas al usuario como Sales, SUM(Sales), Category o MONTH(Order Date) en su lugar.

Recursos útiles para agentes:

cwtwb://tool-surface
cwtwb://skills/index
cwtwb://skills/data_quality
cwtwb://skills/design_advisor
cwtwb://skills/metric_blueprint
cwtwb://skills/dashboard_designer
cwtwb://skills/quality_review
cwtwb://skills/documentation
file://docs/tableau_all_functions.json

También hay alias de compatibilidad disponibles para URI comunes adivinadas como cwtwb://docs/manual-editing, pero los nuevos prompts deben preferir cwtwb://tool-surface y cwtwb://skills/index.

Para detalles específicos del cliente y la referencia completa, consulta https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md.

Archivos de diseño de dashboard

Los diseños de dashboard personalizados ahora se pueden crear como JSON o YAML usando el mismo DSL declarativo. Para flujos de trabajo de agentes, genera primero un archivo de diseño y luego pasa esa ruta de archivo a add_dashboard(layout=...).

generate_layout_json("output/layout.json", layout_tree, ascii_preview)
generate_layout_yaml("output/layout.yaml", layout_tree, ascii_preview)

Ambos formatos admiten la misma estructura contenedora:

layout_schema: árbol de diseño de dashboard canónico
_ascii_layout_preview: ayuda opcional de revisión para humanos/agentes

Galería de dashboards explicables

cwtwb incluye siete plantillas de Galería empaquetadas para estructuras analíticas comunes. Las recomendaciones usan requisitos explícitos y devuelven sus puntuaciones, razones de coincidencia y penalizaciones; no inspeccionan datos ni generan gráficos silenciosamente.

from cwtwb import DashboardRequirements, recommend_gallery_templates

recommendations = recommend_gallery_templates(
    DashboardRequirements(
        primary_intent="trend",
        has_temporal_data=True,
        kpi_count=2,
        chart_count=3,
        chart_types=("Line", "Bar"),
    )
)

Después de llamar a list_worksheets, vincula los nombres exactos de las hojas de trabajo con materialize_gallery_layout(...) o la herramienta MCP generate_gallery_layout. El resultado generado usa el mismo DSL canónico aceptado por add_dashboard.

Seguridad de cálculos

add_calculated_field verifica los identificadores usados como llamadas a funciones contra el catálogo de Tableau empaquetado antes de editar el XML. Por ejemplo, CHR(10) se rechaza con una sugerencia de CHAR(). Esta es una verificación ligera de nombres de funciones, no un analizador completo de Tableau ni un sustituto de la validación semántica de Tableau Cloud.

Usa validate_formula=False solo cuando apuntes a una función de Tableau más reciente que aún no esté en el catálogo empaquetado. Los libros de trabajo existentes se pueden revisar con audit_calculated_fields(). Las reparaciones son independientes y por defecto usan dry_run=True.

Características destacadas

Área	Lo que obtienes
Creación de libros de trabajo	Genera archivos `.twb` / `.twbx` a partir de plantillas o desde cero; añade jerarquías, conjuntos, títulos dinámicos enriquecidos y marcadores de parámetros
Construcción de gráficos	Construye libros de trabajo de barras, líneas, circulares, mapas, KPI, doble eje, en capas y tablas ordenadas de múltiples columnas
Cálculos de tabla	Crea metadatos de direccionamiento de cálculos, finalización de dominios, subtotales y dependencias anidadas de cálculos de tabla
Acciones de dashboard	Añade acciones de filtro, resaltado, URL, navegación, parámetros y conjuntos a través de Python o MCP
Seguridad	Valida nombres de funciones y roles de campos calculados, luego valida la estructura, el XSD de Tableau (2026.1/2026.2) y la semántica de la API REST antes de publicar
Galería de dashboards	Clasifica siete diseños explicables y vincula nombres exactos de hojas de trabajo al DSL canónico
Validación en la nube	Validación sintáctica/semántica de la API REST + subida a Tableau Cloud/Server con captura de pantalla opcional
Migración	Reorienta libros de trabajo existentes a nuevas fuentes de datos con pasos explícitos
Soporte MCP	Impulsa flujos de trabajo de libros de trabajo desde Claude, Cursor, VSCode u otros clientes MCP

Véalo en acción

Este GIF muestra el flujo de herramientas MCP que construye un dashboard paso a paso.

cwtwb demo GIF

Arquitectura

                            Interfaces
  ┌───────────────────────────────────────────────────────────────┐
  │  ┌──────────────────────────┐  ┌───────────────────────────┐  │
  │  │        MCP Server        │  │      Python Library       │  │
  │  │  tools_workbook          │  │  from cwtwb.twb_editor    │  │
  │  │  tools_validate          │  │  import TWBEditor         │  │
  │  │                          │  │                           │  │
  │  │                          │  │  editor.add_...()         │  │
  │  │                          │  │  editor.configure_...()   │  │
  │  │                          │  │  editor.validate_schema() │  │
  │  │  (Claude / Cursor /      │  │  editor.save(...)         │  │
  │  │   VSCode / Claude Code)  │  │                           │  │
  │  └─────────────┬────────────┘  └──────────────┬────────────┘  │
  │                └──────────────┬────────────────┘               │
  └─────────────────────────────  ┼  ─────────────────────────────┘
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                          TWBEditor                            │
  │       ParametersMixin  ·  ConnectionsMixin                    │
  │       ChartsMixin      ·  DashboardsMixin                     │
  │       validate_schema()  ·  save()                            │
  └──────────┬──────────────────┬──────────────────┬─────────────┘
             ▼                  ▼                  ▼
  ┌──────────────────┐  ┌──────────────┐  ┌──────────────────────┐
  │  Chart Builders  │  │  Dashboard   │  │  Analysis &          │
  │                  │  │  System      │  │  Migration           │
  │  Basic  DualAxis │  │              │  │                      │
  │  Pie    Text     │  │  layouts     │  │  migration.py        │
  │  Map    Recipes  │  │  actions     │  │  twb_analyzer.py     │
  │                  │  │  dependencies│  │  capability_registry │
  └────────┬─────────┘  └──────┬───────┘  └──────────┬───────────┘
           └───────────────────┼──────────────────────┘
                               ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                    Packaged References                        │
  │    empty_template.twb  ·  Superstore XLS/Hyper                │
  │    tableau_all_functions.json  ·  dataset profiles            │
  │    vendored Tableau TWB XSD schemas (2026.1 / 2026.2)         │
  └───────────────────────────────┬───────────────────────────────┘
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                     XML Engine  (lxml)                        │
  │    template.twb/.twbx  →  patch  →  validate  →  save        │
  └───────────────────────────────┬───────────────────────────────┘
                                  ▼
                      output.twb  /  output.twbx
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │               Cloud Validation (optional)                    │
  │    validate_workbook_api → REST API semantic validation      │
  │    upload_workbook       → Tableau Cloud/Server publish      │
  │    screenshot_workbook   → capture view for visual check     │
  └───────────────────────────────────────────────────────────────┘

Vista Mermaid:

flowchart TD
    subgraph Interfaces
        MCP["MCP Server<br/>tools_workbook<br/>tools_validate"]
        PY["Python Library<br/>TWBEditor API"]
    end

    subgraph Editor["Core Editor"]
        TWB["TWBEditor<br/>parameters · connections<br/>charts · dashboards<br/>validate_schema · save"]
    end

    subgraph Builders["Workbook Systems"]
        CHARTS["Chart Builders<br/>basic · dual-axis<br/>pie · text · map · recipes"]
        DASH["Dashboard System<br/>layouts · actions<br/>dependencies"]
        ANALYSIS["Analysis & Migration<br/>migration.py<br/>twb_analyzer.py<br/>capability_registry"]
    end

    subgraph References["Packaged References"]
        REFS["empty_template.twb<br/>Superstore XLS/Hyper<br/>Tableau functions<br/>TWB XSD schemas"]
    end

    subgraph Engine["XML Engine"]
        XML["lxml patch pipeline<br/>template.twb/.twbx → patch → validate → save"]
    end

    subgraph Outputs
        OUT["output.twb / output.twbx"]
        CLOUD["Cloud Validation<br/>REST semantic validation<br/>upload · screenshot"]
    end

    MCP --> TWB
    PY --> TWB
    TWB --> CHARTS
    TWB --> DASH
    TWB --> ANALYSIS
    CHARTS --> XML
    DASH --> XML
    ANALYSIS --> XML
    REFS --> TWB
    REFS --> XML
    XML --> OUT
    OUT --> CLOUD

La capa de referencia se empaqueta con la biblioteca para que los agentes y scripts puedan partir de activos de libros de trabajo conocidos y correctos, resolver la sintaxis de cálculos de Tableau, ejecutar ejemplos con soporte Hyper y validar contra esquemas XSD locales sin depender de un repositorio clonado.

Arquitectura de agentes

cwtwb está diseñado para agentes que usan herramientas, no solo para llamadas directas de Python. El servidor MCP ofrece a los agentes una superficie pequeña y con estado para editar libros de trabajo; los recursos de habilidades proporcionan orientación específica de Tableau por fase antes de cada conjunto de llamadas a herramientas.

Human or agent prompt
        |
        v
MCP server instructions
        |
        v
Skill resources
data_quality -> governance -> synthetic_data -> design_advisor -> metric_blueprint
-> calculation_builder -> chart_builder -> dashboard_designer -> formatting
-> validation -> quality_review -> documentation
        |
        v
Workbook tools
create/open -> list_fields -> add/configure -> layout -> save -> validate/upload
        |
        v
TWB/TWBX artifact + validation evidence

Los prompts explican qué construir. Las habilidades explican cómo construirlo bien. Las herramientas hacen que los cambios en el libro de trabajo sean inspeccionables y repetibles.

La arquitectura de habilidades empaquetada está documentada en src/cwtwb/skills/README.md, incluido su diagrama de flujo de trabajo y el límite entre orientación, mutaciones explícitas y evidencia de validación.

Límite de capacidades

cwtwb mantiene su superficie pública intencionalmente pequeña:

Nivel	Significado
Núcleo	Primitivas estables para documentación normal del SDK, ejemplos y flujos de trabajo MCP
Avanzado	Composiciones y patrones de interacción compatibles con más partes móviles
Receta	Patrones de demostración expuestos a través de `configure_chart_recipe`, no una herramienta por gráfico

Usa list_capabilities o describe_capability cuando un agente necesite comprobar si un gráfico solicitado o una característica del libro de trabajo pertenece a la superficie estable.

Decisiones de diseño

El servidor MCP usa un modelo de sesión con estado: abre o crea un libro de trabajo, modifícalo mediante herramientas explícitas y luego llama a save_workbook.
Las habilidades son guías operativas específicas por fase, no relleno genérico de prompts.
save_workbook, validate_workbook, validate_workbook_api y upload_workbook tienen responsabilidades separadas para que los agentes no confundan la escritura, las comprobaciones locales, la validación semántica y la publicación.
El registro de capacidades mantiene explícito el límite del producto en lugar de permitir que los ejemplos de demostración se conviertan en promesas accidentales de la API.

Validación

cwtwb proporciona cuatro niveles de validación de libros de trabajo:

Nivel	Descripción	Requiere
1. XSD local	Valida contra el esquema XSD oficial de Tableau TWB (consciente de versión: 2026.1 o 2026.2)	Ninguno (integrado)
2. Sintáctico de API REST	Valida la sintaxis XML mediante la API REST de Tableau Cloud	Credenciales de Tableau + Tableau Cloud 2026.2+
3. Semántico de API REST	Validación semántica completa sin publicar — comprobación de nube predeterminada para `.twb`	Credenciales de Tableau + Tableau Cloud 2026.2+
4. Subida + captura de pantalla	Publica en Tableau Cloud/Server y captura una imagen de la vista	Credenciales de Tableau + `pip install "cwtwb[validate]"`

# Level 1 — Local XSD (in-memory, no save required)
result = editor.validate_schema()
print(result.to_text())

# Level 3 — REST API semantic validation
from cwtwb.validate.uploader import TableauUploader
uploader = TableauUploader(env_path="project/.env")
result = uploader.validate("output.twb", validation_level="semantic")

# Save with local XSD validation; REST API semantic validation also runs when .env is configured
editor.save("output.twb")

# MCP tools
validate_workbook(file_path="output.twb")                                       # Local XSD validation
validate_workbook_api(twb_path="output.twb", validation_level="semantic")        # Default cloud semantic validation, no publish
validate_workbook_api(twb_path="output.twb", env_path="project/.env")            # Runtime credentials
upload_workbook(twb_path="output.twb")                                          # Publish/openability evidence or TWBX validation
screenshot_workbook(workbook_id="...", view_name="Sheet 1")                     # Visual check after upload_workbook

Preguntas frecuentes

¿Cuál es la diferencia entre `.twb` y `.twbx`?

.twb es el XML del libro de trabajo. .twbx es la versión empaquetada que agrupa el libro de trabajo junto con extractos e imágenes.

¿Guarda archivos `validate_workbook`?

No. validate_workbook() realiza validación XSD local en el libro de trabajo activo en memoria o en un archivo .twb / .twbx existente. No escribe salida. save_workbook() es la herramienta que escribe archivos.

¿Qué validación realiza `save()`?

save() ejecuta la validación XSD local automáticamente antes de reemplazar el archivo de salida final. Para salida .twb, la validación semántica de la API REST también se ejecuta cuando las credenciales de Tableau están configuradas y el servidor lo admite. Usa validate_workbook_api(..., validation_level="semantic") cuando quieras solicitar directamente el paso de validación de Tableau Cloud/Server.

¿Para qué sirve `upload_workbook`?

upload_workbook publica un .twb o .twbx en Tableau Cloud/Server. Úsalo cuando necesites explícitamente evidencia de publicación/apertura, un ID de libro de trabajo para capturas de pantalla o validación de paquete .twbx. Para la comprobación semántica de nube predeterminada de .twb, prefiere validate_workbook_api porque no publica ni almacena el libro de trabajo. Requiere pip install "cwtwb[validate]" y credenciales de Tableau de variables de entorno, un env_path explícito, TABLEAU_ENV_FILE o un archivo .env junto al libro de trabajo.

¿Cómo configuro la validación de Tableau Cloud/Server?

Instala: pip install "cwtwb[validate]"
Copia .env.example a .env
Completa tus credenciales PAT de Tableau Cloud/Server
Llama a save_workbook para escribir el .twb o .twbx
Llama a validate_workbook_api para la validación semántica predeterminada de la API REST, o upload_workbook solo cuando también quieras evidencia de publicación/apertura, capturas de pantalla o validación de .twbx

El orden de búsqueda de credenciales es: env_path explícito primero, luego variables de entorno, TABLEAU_ENV_FILE, el .env hermano del libro de trabajo, el .env del directorio de trabajo actual, el .env del proyecto cwtwb y finalmente el .env del directorio de inicio del usuario. Prefiere env_path para llamadas MCP puntuales en lugar de editar la configuración del servidor MCP y reiniciar el servidor. Si la validación informa que falta tableauserverclient, llama primero a get_mcp_status. Este reporta el ejecutable de Python del proceso MCP, la versión de cwtwb y si el cliente de Tableau es importable sin exponer credenciales. Un cambio de env_path está limitado al tiempo de ejecución y no requiere reiniciar el MCP; instalar dependencias en un entorno de Python diferente no corrige el servidor en ejecución, así que instala el extra de validación en el intérprete reportado por get_mcp_status y reconéctate solo cuando el tiempo de ejecución o el esquema de herramientas cambie.

¿Cuándo debo usar `uvx cwtwb` en lugar de `python -m cwtwb.mcp_server`?

Usa uvx cwtwb para el flujo de trabajo normal de MCP. Usa python -m cwtwb.mcp_server para pruebas locales sin uvx.

Para compatibilidad hacia atrás, uvx --from cwtwb cwtwb-mcp, python -m cwtwb.server y python -m cwtwb.mcp continúan funcionando.

¿Dónde está la guía completa?

Consulta la guía en línea.

cwtwb

Documentación

cwtwb

Referencia del flujo de trabajo de diseño

Historial de estrellas

Inicio rápido

Instalación

Ejecutar como servidor MCP

Uso como CLI

Estabilidad del cliente MCP

Archivos de diseño de dashboard

Galería de dashboards explicables

Seguridad de cálculos

Características destacadas

Véalo en acción

Arquitectura

Arquitectura de agentes

Límite de capacidades

Decisiones de diseño

Validación

Preguntas frecuentes

¿Cuál es la diferencia entre .twb y .twbx?

¿Guarda archivos validate_workbook?

¿Qué validación realiza save()?

¿Para qué sirve upload_workbook?

¿Cómo configuro la validación de Tableau Cloud/Server?

¿Cuándo debo usar uvx cwtwb en lugar de python -m cwtwb.mcp_server?

¿Dónde está la guía completa?

Documentación

¿Cuál es la diferencia entre `.twb` y `.twbx`?

¿Guarda archivos `validate_workbook`?

¿Qué validación realiza `save()`?

¿Para qué sirve `upload_workbook`?

¿Cuándo debo usar `uvx cwtwb` en lugar de `python -m cwtwb.mcp_server`?