cwtwb

gerar arquivo tableau

Documentação

cwtwb

Engenharia de workbooks do Tableau para geração, validação e migração reproduzíveis de .twb / .twbx.

cwtwb hero image

cwtwb é um kit de ferramentas Python e um servidor Model Context Protocol (MCP) para criar workbooks do Tableau Desktop a partir de código ou chamadas de ferramentas de agentes.

Ele foi projetado para ser uma camada de engenharia de workbooks, não um agente de análise conversacional. O foco está na reprodutibilidade, inspecionabilidade e automação segura em fluxos de trabalho locais, scripts e CI.

Referência de Fluxo de Trabalho de Design

O fluxo de trabalho de design do agente e a habilidade design_advisor são baseados nas habilidades de fluxo de trabalho Tableau do adammico-lab de Adam Mico, especialmente na abordagem de construção a partir de uma especificação de design do Tableau Dashboard Blueprint. O cwtwb adapta essas ideias de forma independente para a criação reproduzível de .twb / .twbx; ele não depende, não inclui e não copia código ou conteúdo de habilidades do adammico-lab. O cwtwb não é afiliado à Adam Mico, Salesforce ou Tableau.

O cw em cwtwb vem de Cooper Wenhua.

Autor: Cooper Wenhua <imgwho@gmail.com>

Site · Código-fonte · Changelog

Histórico de Estrelas

Experimente o fluxo de trabalho de exemplo · Leia o guia

Início Rápido

Instalação

pip install cwtwb

Se você também quiser o exemplo empacotado com Hyper:

pip install "cwtwb[examples]"

Se você quiser validação em nuvem (upload para Tableau Cloud/Server):

pip install "cwtwb[validate]"

Executar Como Um Servidor MCP

uvx cwtwb

A forma curta acima continua sendo a opção mais simples e é a configuração padrão mostrada neste repositório. cwtwb é um ponto de entrada inteligente: sem argumentos em um terminal interativo, ele imprime a ajuda da CLI; quando iniciado por um cliente MCP via stdio, ele inicia o servidor.

Adicione o servidor ao seu cliente MCP com o mesmo comando. Por exemplo:

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

Para Claude Code:

claude mcp add cwtwb -- uvx cwtwb

Para VSCode, adicione cwtwb ao seu workspace ou mcp.json do usuário e use uvx cwtwb como comando.

Se você preferir um nome de script explícito, estes estilos de inicialização equivalentes também funcionam:

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

Usar Como CLI

O mesmo pacote também expõe fluxos de trabalho de linha de comando de primeira classe para humanos, scripts, CI e agentes que precisam de operações diretas de arquivos em vez de chamadas de ferramentas 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

Comandos de escrita comuns exigem um caminho de saída explícito por padrão:

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

Use --in-place somente quando você quiser sobrescrever intencionalmente o workbook de entrada, e --force somente ao substituir um arquivo de saída existente.

Estabilidade do Cliente MCP

Quando o cwtwb está conectado como servidor MCP, os agentes devem chamar as ferramentas MCP expostas diretamente pelo seu cliente. Eles não devem executar comandos de shell como mcp call cwtwb ..., mcp list-tools cwtwb ou gh api .../mcp/...; esses comandos não fazem parte do cwtwb e geralmente não estão disponíveis em ambientes normais de Claude, Codex, Cursor ou VSCode.

Se um agente não conseguir ver ferramentas como create_workbook, add_worksheet ou save_workbook, reinicie ou reconecte o cliente MCP e verifique a configuração do servidor. Limpar o cache do uv apenas atualiza os pacotes instalados; isso não corrige uma superfície de ferramentas desatualizada no cliente.

Ao usar um .twb existente como referência visual, os agentes não devem copiar tokens de instância de coluna do XML do Tableau para as entradas de gráficos. Valores como [sum:Sales:qk], [none:Category:nk], [mn:Order Date:ok] ou [federated.xxx].[sum:Profit:qk] são internos gerados. Passe expressões voltadas ao usuário, como Sales, SUM(Sales), Category ou MONTH(Order Date), em vez disso.

Recursos úteis 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

Aliases de compatibilidade também estão disponíveis para URIs comuns adivinhados, como cwtwb://docs/manual-editing, mas novos prompts devem preferir cwtwb://tool-surface e cwtwb://skills/index.

Para detalhes específicos do cliente e a referência completa, consulte https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md.

Arquivos de Layout de Dashboard

Layouts de dashboard personalizados agora podem ser criados em JSON ou YAML usando o mesmo DSL declarativo. Para fluxos de trabalho de agentes, gere um arquivo de layout primeiro e depois passe o caminho desse arquivo para add_dashboard(layout=...).

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

Ambos os formatos suportam a mesma estrutura de wrapper:

layout_schema: árvore canônica de layout de dashboard
_ascii_layout_preview: auxílio opcional de revisão para humanos/agentes

Galeria de Dashboards Explicáveis

O cwtwb inclui sete templates de Galeria empacotados para estruturas analíticas comuns. As recomendações usam requisitos explícitos e retornam suas pontuações, motivos de correspondência e penalidades; elas não inspecionam dados nem geram 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"),
    )
)

Após chamar list_worksheets, vincule nomes exatos de planilhas com materialize_gallery_layout(...) ou a ferramenta MCP generate_gallery_layout. O resultado gerado usa o mesmo DSL canônico aceito por add_dashboard.

Segurança de Cálculos

add_calculated_field verifica identificadores usados como chamadas de função em relação ao catálogo Tableau empacotado antes de editar o XML. Por exemplo, CHR(10) é rejeitado com uma sugestão de CHAR(). Esta é uma verificação leve de nomes de função, não um parser completo do Tableau nem um substituto para a validação semântica do Tableau Cloud.

Use validate_formula=False somente ao usar uma função Tableau mais recente que ainda não está no catálogo empacotado. Workbooks existentes podem ser revisados com audit_calculated_fields(). Os reparos são separados e usam dry_run=True por padrão.

Destaques

Área	O que você obtém
Criação de workbooks	Gere arquivos `.twb` / `.twbx` a partir de templates ou do zero; adicione hierarquias, conjuntos, títulos dinâmicos ricos e placeholders de parâmetros
Construção de gráficos	Crie workbooks de gráficos de barras, linhas, pizza, mapas, KPI, eixo duplo, em camadas e tabelas ordenadas de múltiplas colunas
Cálculos de tabela	Crie metadados de endereçamento de cálculos, conclusão de domínio, subtotais e dependências aninhadas de cálculos de tabela
Ações de dashboard	Adicione ações de filtro, destaque, URL, navegação, parâmetro e conjunto via Python ou MCP
Segurança	Valide nomes de funções e papéis de campos calculados, depois valide estrutura, XSD do Tableau (2026.1/2026.2) e semântica da API REST antes de publicar
Galeria de Dashboards	Classifique sete layouts explicáveis e vincule nomes exatos de planilhas ao DSL canônico
Validação em nuvem	Validação sintática/semântica da API REST + upload para Tableau Cloud/Server com captura de tela opcional
Migração	Redirecione workbooks existentes para novas fontes de dados com etapas explícitas
Suporte MCP	Conduza fluxos de trabalho de workbooks a partir de Claude, Cursor, VSCode ou outros clientes MCP

Veja em Ação

Este GIF mostra o fluxo de ferramentas MCP que constrói um dashboard passo a passo.

cwtwb demo GIF

Arquitetura

                            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     │
  └───────────────────────────────────────────────────────────────┘

Visualização 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

A camada de referência é empacotada com a biblioteca para que agentes e scripts possam começar a partir de assets de workbooks conhecidos e válidos, resolver a sintaxe de cálculos do Tableau, executar exemplos baseados em Hyper e validar contra esquemas XSD locais sem depender de um repositório clonado.

Arquitetura de Agentes

O cwtwb é projetado para agentes que usam ferramentas, não apenas para chamadas diretas em Python. O servidor MCP oferece aos agentes uma superfície pequena e com estado para edição de workbooks; os recursos de habilidades fornecem orientação específica do Tableau por fase antes de cada conjunto de chamadas de ferramentas.

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

Os prompts explicam o que construir. As habilidades explicam como construir bem. As ferramentas tornam as alterações no workbook inspecionáveis e repetíveis.

A arquitetura de habilidades empacotada está documentada em src/cwtwb/skills/README.md, incluindo seu diagrama de fluxo de trabalho e o limite entre orientação, mutações explícitas e evidências de validação.

Limite de Capacidades

O cwtwb mantém sua superfície pública intencionalmente pequena:

Nível	Significado
Núcleo	Primitivas estáveis para documentação normal do SDK, exemplos e fluxos de trabalho MCP
Avançado	Composições suportadas e padrões de interação com mais partes móveis
Receita	Padrões de demonstração expostos por meio de `configure_chart_recipe`, não uma ferramenta por gráfico

Use list_capabilities ou describe_capability quando um agente precisar verificar se um gráfico solicitado ou um recurso de workbook pertence à superfície estável.

Decisões de Design

O servidor MCP usa um modelo de sessão com estado: abra ou crie um workbook, altere-o por meio de ferramentas explícitas e depois chame save_workbook.
As habilidades são guias operacionais específicos por fase, não preenchimento genérico de prompts.
save_workbook, validate_workbook, validate_workbook_api e upload_workbook têm responsabilidades separadas para que os agentes não confundam escrita, verificações locais, validação semântica e publicação.
O registro de capacidades mantém o limite do produto explícito, em vez de permitir que exemplos de demonstração se tornem promessas acidentais de API.

Validação

O cwtwb oferece quatro níveis de validação de workbooks:

Nível	Descrição	Requer
1. XSD Local	Valida contra o esquema XSD oficial do Tableau TWB (ciente da versão: 2026.1 ou 2026.2)	Nenhum (integrado)
2. Sintático via API REST	Valida a sintaxe XML por meio da API REST do Tableau Cloud	Credenciais do Tableau + Tableau Cloud 2026.2+
3. Semântico via API REST	Validação semântica completa sem publicar — verificação padrão em nuvem para `.twb`	Credenciais do Tableau + Tableau Cloud 2026.2+
4. Upload + Captura de tela	Publica no Tableau Cloud/Server e captura uma imagem da visualização	Credenciais do 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

Perguntas Frequentes

Qual é a diferença entre `.twb` e `.twbx`?

.twb é o XML do workbook. .twbx é a versão empacotada que agrupa o workbook junto com extratos e imagens.

O `validate_workbook` salva arquivos?

Não. O validate_workbook() realiza validação XSD local no workbook ativo em memória ou em um arquivo .twb / .twbx existente. Ele não grava saída. save_workbook() é a ferramenta que grava arquivos.

Qual validação o `save()` realiza?

O save() executa validação XSD local automaticamente antes de substituir o arquivo de saída final. Para saída .twb, a validação semântica da API REST também é executada quando as credenciais do Tableau estão configuradas e o servidor a suporta. Use validate_workbook_api(..., validation_level="semantic") quando quiser solicitar a etapa de validação do Tableau Cloud/Server diretamente.

Para que serve o `upload_workbook`?

O upload_workbook publica um .twb ou .twbx no Tableau Cloud/Server. Use-o quando precisar explicitamente de evidência de publicação/abertura, de um ID de workbook para capturas de tela ou de validação de pacote .twbx. Para a verificação semântica padrão em nuvem do .twb, prefira validate_workbook_api porque ele não publica nem armazena o workbook. Requer pip install "cwtwb[validate]" e credenciais do Tableau a partir de variáveis de ambiente, um env_path explícito, TABLEAU_ENV_FILE ou um arquivo .env ao lado do workbook.

Como configuro a validação do Tableau Cloud/Server?

Instale: pip install "cwtwb[validate]"
Copie .env.example para .env
Preencha suas credenciais PAT do Tableau Cloud/Server
Chame save_workbook para gravar o .twb ou .twbx
Chame validate_workbook_api para a validação semântica padrão da API REST, ou upload_workbook somente quando também quiser evidência de publicação/abertura, capturas de tela ou validação de .twbx

A ordem de busca de credenciais é: env_path explícito primeiro, depois variáveis de ambiente, TABLEAU_ENV_FILE, o .env irmão do workbook, o .env do diretório de trabalho atual, o .env do projeto cwtwb e, por fim, o .env do diretório pessoal do usuário. Prefira env_path para chamadas MCP pontuais em vez de editar a configuração do servidor MCP e reiniciar o servidor.

Se a validação informar que tableauserverclient está ausente, chame get_mcp_status primeiro. Ela informa o executável Python do processo MCP, a versão do cwtwb e se o cliente Tableau pode ser importado sem expor credenciais. Uma alteração de env_path tem escopo de tempo de execução e não requer reinicialização do MCP; instalar dependências em um ambiente Python diferente não corrige o servidor em execução, então instale o extra de validação no interpretador informado por get_mcp_status e reconecte somente quando o tempo de execução ou o esquema da ferramenta mudar.

Quando devo usar `uvx cwtwb` em vez de `python -m cwtwb.mcp_server`?

Use uvx cwtwb para o fluxo de trabalho MCP normal. Use python -m cwtwb.mcp_server para testes locais sem uvx.

Para compatibilidade com versões anteriores, uvx --from cwtwb cwtwb-mcp, python -m cwtwb.server e python -m cwtwb.mcp continuam funcionando.

Onde está o guia completo?

Consulte o guia online.

cwtwb

Documentação

cwtwb

Referência de Fluxo de Trabalho de Design

Histórico de Estrelas

Início Rápido

Instalação

Executar Como Um Servidor MCP

Usar Como CLI

Estabilidade do Cliente MCP

Arquivos de Layout de Dashboard

Galeria de Dashboards Explicáveis

Segurança de Cálculos

Destaques

Veja em Ação

Arquitetura

Arquitetura de Agentes

Limite de Capacidades

Decisões de Design

Validação

Perguntas Frequentes

Qual é a diferença entre .twb e .twbx?

O validate_workbook salva arquivos?

Qual validação o save() realiza?

Para que serve o upload_workbook?

Como configuro a validação do Tableau Cloud/Server?

Quando devo usar uvx cwtwb em vez de python -m cwtwb.mcp_server?

Onde está o guia completo?

Documentação

Qual é a diferença entre `.twb` e `.twbx`?

O `validate_workbook` salva arquivos?

Qual validação o `save()` realiza?

Para que serve o `upload_workbook`?

Quando devo usar `uvx cwtwb` em vez de `python -m cwtwb.mcp_server`?