cwprep

★ 4

from imgwho

ai generate tableau prep file

🔥🔥🔥✓ VerifiedFreeQuick setup

#email #automation #analytics #database #documents #git #translation

cwprep

Tableau Prep flow engineering for reproducible .tfl / .tflx generation, validation, and SQL translation.

cwprep hero image

cwprep is a Python toolkit and Model Context Protocol (MCP) server for building Tableau Prep flows from code or agent tool calls.

It is meant to be a PrepFlow engineering layer, not a generic conversational analytics agent. The focus is reproducibility, inspectability, and safe automation in local workflows, scripts, and AI clients.

The cw in cwprep comes from Cooper Wenhua.

Author: Cooper Wenhua <imgwho@gmail.com>

Website · Source · Changelog

Try the example workflow · Read the guide

Highlights

Area	What you get
Flow authoring	Generate Tableau Prep `.tfl` / `.tflx` flows from Python or declarative MCP definitions
Data inputs	Connect to MySQL, PostgreSQL, SQL Server, Alibaba AnalyticDB for MySQL, CSV, Excel, custom SQL, and table inputs
Prep operations	Build joins, unions, filters, value filters, keep/remove columns, renames, calculations, quick clean steps, type changes, aggregates, pivots, and unpivots
Packaging	Save final `.tfl` archives or packaged `.tflx` files with embedded data files
SQL translation	Translate generated or existing `.tfl` flows into readable ANSI SQL CTEs
MCP support	Drive flow generation from Claude, Cursor, VSCode, Gemini CLI, Continue, or other MCP clients

See It In Action

This GIF shows the MCP tool flow that designs and generates a Tableau Prep flow.

cwprep demo GIF

Architecture

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

Mermaid view:

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

The reference layer is packaged with the library so agents and scripts can start from known-good API guidance, resolve Tableau Prep calculation syntax, and avoid common flow-design pitfalls without relying on a checked-out repository.

Agent Architecture

cwprep is designed for tool-using agents, not just direct Python calls. The MCP server gives agents a compact flow-generation surface; resource documents give phase-specific Tableau Prep guidance before generation.

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 explain what to build. Resources explain how to build it correctly. Tools make the generated flow inspectable and repeatable.

Capability Boundary

cwprep keeps its public surface intentionally small:

Level	Meaning
Core	Stable primitives for normal SDK docs, examples, and MCP workflows
Advanced	Supported compositions such as packaged `.tflx`, file unions, multi-column joins, and SQL translation
Inspectable	Exploded flow folders and internal JSON are available for debugging, but final archives are the default output

Use list_supported_operations when an agent needs to check whether a requested Prep operation belongs in the stable surface.

Design Decisions

The MCP workflow is definition-first: design the flow, validate the JSON contract, then generate the archive.
Resource documents are phase-specific operating guides, not generic prompt stuffing.
The SDK and MCP output only the final .tfl / .tflx archive by default. Use save_to_folder() only when you explicitly want the exploded folder for inspection.
Tableau Prep calculation syntax is not SQL syntax. Agents should read cwprep://docs/calculation-syntax before creating formulas.
SQL translation is a readability and migration aid, not a replacement for Tableau Prep execution.
File replacement is handled defensively: generation writes temporary artifacts first and backs up existing outputs before replacement.

Validation

cwprep provides four levels of flow validation and review:

Level	Description	Requires
1. Definition validation	Validate the declarative MCP flow definition before generating files	None
2. Archive generation safety	Write temporary artifacts, back up existing outputs, and emit final `.tfl` / `.tflx` archives	None
3. SQL translation review	Translate supported flow logic into ANSI SQL CTEs for inspection and migration planning	None
4. Tableau Prep openability	Open the generated archive in Tableau Prep Builder for final product verification	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")

Documentation

Copy & paste — that's it

pip install cwprep

Quick Start

Install

pip install cwprep

Run As An MCP Server

uvx cwprep

The short form above remains the simplest option and is the default config shown in this repository.

Add the server to your MCP client with the same command. For example:

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

For Claude Code:

claude mcp add cwprep -- uvx cwprep

For VSCode, add cwprep to your workspace or user mcp.json and use uvx cwprep as the command.

If you prefer an explicit script name, these equivalent launch styles also work:

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

For client-specific details and the full reference, see https://github.com/imgwho/cwprep/blob/main/docs/guide.md.

cwprep

cwprep

Highlights

See It In Action

Architecture

Agent Architecture

Capability Boundary

Design Decisions

Validation

Documentation

Quick Start

Install

Run As An MCP Server

FAQ

What is the difference between `.tfl` and `.tflx`?

Does cwprep open or run Tableau Prep Builder?

Does `validate_flow_definition` save files?

Can cwprep translate flows to SQL?

When should I use `uvx cwprep` versus `python -m cwprep.mcp_server`?

Where is the full guide?

cwprep

Highlights

See It In Action

Architecture

Agent Architecture

Capability Boundary

Design Decisions

Validation

Documentation

Quick Start

Install

Run As An MCP Server

FAQ

What is the difference between .tfl and .tflx?

Does cwprep open or run Tableau Prep Builder?

Does validate_flow_definition save files?

Can cwprep translate flows to SQL?

When should I use uvx cwprep versus python -m cwprep.mcp_server?

Where is the full guide?

What is the difference between `.tfl` and `.tflx`?

Does `validate_flow_definition` save files?

When should I use `uvx cwprep` versus `python -m cwprep.mcp_server`?