cwprep

generar archivo de preparación de Tableau con IA

GitHub
5
Prueba este MCPPatrocinado

Documentación

cwprep

Datacooper logo

Ingeniería de flujos de Tableau Prep para generación, validación y traducción SQL reproducibles de .tfl / .tflx.

cwprep hero image

cwprep es un kit de herramientas de Python y un servidor de Protocolo de Contexto de Modelo (MCP) para construir flujos de Tableau Prep desde código o llamadas de herramientas de agentes.

Está pensado para ser una capa de ingeniería de PrepFlow, no un agente analítico conversacional genérico. El enfoque está en la reproducibilidad, la inspeccionabilidad y la automatización segura en flujos de trabajo locales, scripts y clientes de IA.

El cw en cwprep proviene de Cooper Wenhua.

Autor: Cooper Wenhua <imgwho@gmail.com>

Sitio web · Código fuente · Registro de cambios

PyPI Downloads Website Source License Python

Star History Chart

Prueba el flujo de ejemplo · Lee la guía

Inicio rápido

Instalación

pip install cwprep

Ejecutar como servidor MCP

uvx cwprep

La forma corta anterior sigue siendo la opción más simple de cliente MCP y es la configuración predeterminada que se muestra en este repositorio. Cuando un humano ejecuta cwprep directamente en una terminal interactiva, imprime la ayuda de CLI en lugar de iniciar stdio MCP.

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

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

Para Claude Code:

claude mcp add cwprep -- uvx cwprep

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

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

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

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

Usar la 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 la misma forma de flujo declarativo que las herramientas MCP, por lo que las especificaciones pueden moverse entre terminales locales, trabajos de CI y agentes sin traducción.

Aspectos destacados

ÁreaLo que obtienes
Autoría de flujosGenera flujos de Tableau Prep .tfl / .tflx desde Python o definiciones MCP declarativas
Entradas de datosConéctate a MySQL, PostgreSQL, SQL Server, Alibaba AnalyticDB para MySQL, CSV, Excel, SQL personalizado y entradas de tabla
Operaciones de PrepConstruye uniones, uniones de conjuntos, filtros, filtros de valor, mantener/eliminar columnas, renombrados, cálculos, pasos de limpieza rápida, cambios de tipo, agregados, pivotes y despivotes
EmpaquetadoGuarda archivos finales .tfl o archivos empaquetados .tflx con archivos de datos incrustados
Traducción SQLTraduce flujos .tfl generados o existentes a CTEs SQL ANSI legibles
Flujo de trabajo CLIValida especificaciones, genera flujos, inspecciona capacidades y traduce SQL desde terminal o CI
Soporte MCPImpulsa la generación de flujos desde Claude, Cursor, VSCode, Gemini CLI, Continue u otros clientes MCP

Verlo en acción

Este GIF muestra el flujo de herramientas MCP que diseña y genera un flujo de Tableau Prep.

cwprep demo GIF

Arquitectura

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

Vista 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

La capa de referencia se empaqueta con la biblioteca para que los agentes y scripts puedan partir de una guía de API conocida, resolver la sintaxis de cálculo de Tableau Prep y evitar errores comunes de diseño de flujos sin depender de un repositorio clonado.

Arquitectura de agentes

cwprep está diseñado para agentes que usan herramientas, no solo para llamadas directas a Python. El servidor MCP ofrece a los agentes una superficie compacta de generación de flujos; los documentos de recursos brindan guía específica de Tableau Prep por fase antes de la generación.

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

Los prompts explican qué construir. Los recursos explican cómo construirlo correctamente. Las herramientas hacen que el flujo generado sea inspeccionable y repetible.

Límite de capacidades

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

NivelSignificado
NúcleoPrimitivas estables para documentación normal del SDK, ejemplos y flujos de trabajo MCP
AvanzadoComposiciones compatibles como .tflx empaquetado, uniones de archivos, uniones de múltiples columnas y traducción SQL
InspeccionableLas carpetas de flujo expandidas y el JSON interno están disponibles para depuración, pero los archivos finales son la salida predeterminada

Usa list_supported_operations cuando un agente necesite verificar si una operación de Prep solicitada pertenece a la superficie estable.

Decisiones de diseño

  • El flujo de trabajo MCP es primero la definición: diseña el flujo, valida el contrato JSON y luego genera el archivo.
  • Los documentos de recursos son guías operativas específicas por fase, no relleno genérico de prompts.
  • El SDK y MCP generan solo el archivo final .tfl / .tflx por defecto. Usa save_to_folder() solo cuando quieras explícitamente la carpeta expandida para inspección.
  • La sintaxis de cálculo de Tableau Prep no es sintaxis SQL. Los agentes deben leer cwprep://docs/calculation-syntax antes de crear fórmulas.
  • La traducción SQL es una ayuda de legibilidad y migración, no un reemplazo para la ejecución de Tableau Prep.
  • El reemplazo de archivos se maneja de forma defensiva: la generación escribe artefactos temporales primero y respalda las salidas existentes antes del reemplazo.

Validación

cwprep proporciona cuatro niveles de validación y revisión de flujos:

NivelDescripciónRequiere
1. Validación de definiciónValida la definición de flujo MCP declarativa antes de generar archivosNinguno
2. Seguridad de generación de archivosEscribe artefactos temporales, respalda las salidas existentes y emite archivos finales .tfl / .tflxNinguno
3. Revisión de traducción SQLTraduce la lógica de flujo compatible a CTEs SQL ANSI para inspección y planificación de migraciónNinguno
4. Apertura en Tableau PrepAbre el archivo generado en Tableau Prep Builder para verificación final del productoTableau 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")

Preguntas frecuentes

¿Cuál es la diferencia entre .tfl y .tflx?

.tfl es el archivo de flujo de Tableau Prep. .tflx es la versión empaquetada que puede incluir archivos de datos locales utilizados por el flujo.

¿cwprep abre o ejecuta Tableau Prep Builder?

No. cwprep genera archivos que Tableau Prep Builder puede abrir. No automatiza la GUI de escritorio de Tableau Prep.

¿validate_flow_definition guarda archivos?

No. validate_flow_definition verifica la definición de flujo solicitada antes de la generación. generate_tfl es la herramienta MCP que escribe el archivo final .tfl o .tflx.

¿Puede cwprep traducir flujos a SQL?

Sí. SQLTranslator y la herramienta MCP translate_to_sql pueden traducir la lógica de flujo .tfl compatible a CTEs estilo SQL ANSI.

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

Usa uvx cwprep para el flujo de trabajo MCP normal. Usa cwprep mcp o python -m cwprep.mcp_server para pruebas MCP locales explícitas sin depender de la detección inteligente de puntos de entrada.

Para compatibilidad hacia atrás, uvx --from cwprep cwprep-mcp y cwprep-mcp siguen funcionando.

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

Consulta la guía en línea.

Documentación