cwprep

cwprep

Engenharia de fluxos Tableau Prep para geração, validação e tradução SQL reproduzíveis de .tfl / .tflx.

cwprep é um kit de ferramentas Python e um servidor Model Context Protocol (MCP) para construir fluxos Tableau Prep a partir de código ou chamadas de ferramentas de agentes.

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

O cw em cwprep vem de Cooper Wenhua.

Autor: Cooper Wenhua <imgwho@gmail.com>

Website · Código-fonte · Changelog

Experimente o fluxo de trabalho de exemplo · Leia o guia

Início Rápido

Instalação

pip install cwprep

Executar como Servidor MCP

uvx cwprep

A forma abreviada acima continua sendo a opção mais simples de cliente MCP e é a configuração padrão mostrada neste repositório. Quando um humano executa cwprep diretamente em um terminal interativo, ele imprime a ajuda da CLI em vez de iniciar o MCP stdio.

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

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

Para Claude Code:

claude mcp add cwprep -- uvx cwprep

Para VSCode, adicione cwprep ao seu espaço de trabalho ou mcp.json de usuário e use uvx cwprep como comando.

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

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

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

Usar a CLI

cwprep --help
cwprep doctor
cwprep status
cwprep capabilities
cwprep validate examples/basic_flow.yaml
cwprep run examples/basic_flow.yaml --out demo_output/cli_basic_flow.tfl
cwprep translate examples/basic_flow.yaml --out demo_output/cli_basic_flow.sql

cwprep run usa a mesma forma declarativa de fluxo que as ferramentas MCP, então as especificações podem ser movidas entre terminais locais, jobs de CI e agentes sem tradução.

Destaques

Área	O que você obtém
Criação de fluxos	Gerar fluxos Tableau Prep .tfl / .tflx a partir de definições MCP declarativas ou Python
Entradas de dados	Conectar a MySQL, PostgreSQL, SQL Server, Alibaba AnalyticDB for MySQL, CSV, Excel, SQL personalizado e entradas de tabela
Operações de preparação	Construir junções, uniões, filtros, filtros de valor, manter/remover colunas, renomeações, cálculos, etapas de limpeza rápida, alterações de tipo, agregações, pivôs e despivotamentos
Empacotamento	Salvar arquivos finais .tfl ou arquivos .tflx empacotados com arquivos de dados incorporados
Tradução SQL	Traduzir fluxos .tfl gerados ou existentes em CTEs SQL ANSI legíveis
Fluxo de trabalho CLI	Validar especificações, gerar fluxos, inspecionar capacidades e traduzir SQL a partir do terminal ou CI
Suporte MCP	Conduzir a geração de fluxos a partir de Claude, Cursor, VSCode, Gemini CLI, Continue ou outros clientes MCP

Veja em Ação

Este GIF mostra o fluxo de ferramentas MCP que projeta e gera um fluxo Tableau Prep.

Arquitetura

                            Interfaces
  +---------------------------------------------------------------+
  |  +--------------------------+  +---------------------------+  |
  |  |        MCP Server        |  |      Python Library       |  |
  |  |  generate_tfl            |  |  from cwprep import       |  |
  |  |  validate_flow_definition|  |  TFLBuilder, TFLPackager |  |
  |  |  translate_to_sql        |  |                           |  |
  |  |                          |  |  builder.add_...()       |  |
  |  |                          |  |  builder.build()         |  |
  |  |  (Claude / Cursor /      |  |  TFLPackager.save_tfl()  |  |
  |  |   VSCode / Gemini)       |  |                           |  |
  |  +------------+-------------+  +-------------+-------------+  |
  |               +-----------------------------+                 |
  +---------------------------------------------|-----------------+
                                                v
  +---------------------------------------------------------------+
  |                    Packaged References                        |
  |    api_reference.md  calculation_syntax.md  best_practices.md |
  |    served as cwprep://docs/... MCP resources                  |
  +----------------------------+----------------------------------+
                               v
  +---------------------------------------------------------------+
  |                         TFLBuilder                            |
  |       connections  inputs  joins  unions  cleaning            |
  |       calculations  aggregates  pivots  outputs               |
  +-------------+-------------------+-----------------------------+
                |                   |
                v                   v
  +--------------------------+  +-------------------------------+
  |       TFLPackager        |  |        SQLTranslator          |
  |  flow/display/meta JSON  |  |  .tfl or flow JSON -> SQL    |
  |  archive/tflx packaging  |  |  CTEs + step comments        |
  +------------+-------------+  +---------------+---------------+
               |                                |
               v                                v
       output.tfl / output.tflx          translated.sql
               |
               v
  +---------------------------------------------------------------+
  |                      Tableau Prep Builder                     |
  |          Open, inspect, run, publish, or continue editing      |
  +---------------------------------------------------------------+

Visualização Mermaid:

flowchart TD
    subgraph Interfaces
        MCP["MCP Server<br/>generate_tfl<br/>validate_flow_definition<br/>translate_to_sql"]
        PY["Python Library<br/>TFLBuilder · TFLPackager<br/>SQLTranslator"]
    end

    subgraph References["Packaged References"]
        REFS["api_reference.md<br/>calculation_syntax.md<br/>best_practices.md<br/>served as cwprep://docs/..."]
    end

    subgraph Engine["Flow Engine"]
        BUILDER["TFLBuilder<br/>connections · inputs · joins · unions<br/>cleaning · calculations · pivots · outputs"]
    end

    subgraph Artifacts["Packaging & Translation"]
        PACKAGER["TFLPackager<br/>flow/display/meta JSON<br/>archive/tflx packaging"]
        SQL["SQLTranslator<br/>.tfl or flow JSON → SQL<br/>CTEs + step comments"]
    end

    subgraph Outputs
        TFL["output.tfl / output.tflx"]
        SQL_OUT["translated.sql"]
        PREP["Tableau Prep Builder<br/>open · inspect · run · publish"]
    end

    MCP --> BUILDER
    PY --> BUILDER
    REFS --> MCP
    REFS --> BUILDER
    REFS --> SQL
    BUILDER --> PACKAGER
    BUILDER --> SQL
    PACKAGER --> TFL
    SQL --> SQL_OUT
    TFL --> PREP

A camada de referência é empacotada com a biblioteca para que agentes e scripts possam começar a partir de orientações de API conhecidas e boas, resolver a sintaxe de cálculo do Tableau Prep e evitar armadilhas comuns de design de fluxo sem depender de um repositório clonado.

Arquitetura de Agentes

cwprep é projetado para agentes que usam ferramentas, não apenas para chamadas Python diretas. O servidor MCP dá aos agentes uma superfície compacta de geração de fluxos; documentos de recursos fornecem orientação específica por fase do Tableau Prep antes da geração.

Human or agent prompt
        |
        v
MCP server instructions
        |
        v
Resource documents
api-reference -> calculation-syntax -> best-practices
        |
        v
Flow tools
validate_flow_definition -> generate_tfl / translate_to_sql
        |
        v
.tfl / .tflx artifact + optional SQL representation

Prompts explicam o que construir. Recursos explicam como construir corretamente. Ferramentas tornam o fluxo gerado inspecionável e repetível.

Limite de Capacidade

cwprep 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, como .tflx empacotados, uniões de arquivos, junções de múltiplas colunas e tradução SQL
Inspecionável	Pastas de fluxo expandidas e JSON interno estão disponíveis para depuração, mas arquivos finais são a saída padrão

Use list_supported_operations quando um agente precisar verificar se uma operação Prep solicitada pertence à superfície estável.

Decisões de Design

• O fluxo de trabalho MCP é primeiro a definição: projete o fluxo, valide o contrato JSON e depois gere o arquivo.
• Documentos de recursos são guias operacionais específicos por fase, não preenchimento genérico de prompts.
• O SDK e o MCP geram apenas o arquivo final .tfl / .tflx por padrão. Use save_to_folder() somente quando você quiser explicitamente a pasta expandida para inspeção.
• A sintaxe de cálculo do Tableau Prep não é sintaxe SQL. Agentes devem ler cwprep://docs/calculation-syntax antes de criar fórmulas.
• A tradução SQL é um auxílio de legibilidade e migração, não um substituto para a execução do Tableau Prep.
• A substituição de arquivos é tratada defensivamente: a geração escreve artefatos temporários primeiro e faz backup das saídas existentes antes da substituição.

Validação

cwprep fornece quatro níveis de validação e revisão de fluxo:

Nível	Descrição	Requer
1. Validação de definição	Validar a definição declarativa do fluxo MCP antes de gerar arquivos	Nenhum
2. Segurança da geração de arquivos	Escrever artefatos temporários, fazer backup das saídas existentes e emitir arquivos finais .tfl / .tflx	Nenhum
3. Revisão da tradução SQL	Traduzir a lógica de fluxo suportada em CTEs SQL ANSI para inspeção e planejamento de migração	Nenhum
4. Abertura no Tableau Prep	Abrir o arquivo gerado no Tableau Prep Builder para verificação final do produto	Tableau Prep Builder

from cwprep import TFLBuilder, TFLPackager

builder = TFLBuilder(flow_name="Customer Orders")
# ... add connections, inputs, transforms, and outputs ...
flow, display, meta = builder.build()
TFLPackager.save_tfl("./customer_orders.tfl", flow, display, meta)

# MCP tools
validate_flow_definition(flow_definition={...})
generate_tfl(flow_definition={...}, output_path="customer_orders.tfl")
translate_to_sql(tfl_path="customer_orders.tfl")

FAQ

Qual é a diferença entre .tfl e .tflx?

.tfl é o arquivo de fluxo Tableau Prep. .tflx é a versão empacotada que pode incluir arquivos de dados locais usados pelo fluxo.

O cwprep abre ou executa o Tableau Prep Builder?

Não. O cwprep gera arquivos que o Tableau Prep Builder pode abrir. Ele não automatiza a GUI desktop do Tableau Prep.

O validate_flow_definition salva arquivos?

Não. O validate_flow_definition verifica a definição de fluxo solicitada antes da geração. O generate_tfl é a ferramenta MCP que grava o arquivo final .tfl ou .tflx.

O cwprep pode traduzir fluxos para SQL?

Sim. O SQLTranslator e a ferramenta MCP translate_to_sql podem traduzir a lógica de fluxo .tfl suportada em CTEs no estilo SQL ANSI.

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

Use uvx cwprep para o fluxo de trabalho MCP normal. Use cwprep mcp ou python -m cwprep.mcp_server para testes MCP locais explícitos sem depender da detecção inteligente de ponto de entrada.

Para compatibilidade retroativa, uvx --from cwprep cwprep-mcp e cwprep-mcp continuam funcionando.

Onde está o guia completo?

Consulte o guia online.

Documentação

• Guia
• Exemplos
• Changelog