cwprep 0.5.7

Tableau Prep Flow SDK - Programmatically generate .tfl files

cwprep - Text-to-PrepFlow Engine

cwprep is a Python-based engine that enables Text-to-PrepFlow generation.

By reverse-engineering the .tfl JSON structure and providing a built-in MCP (Model Context Protocol) server, cwprep acts as a bridge between LLMs (like Claude, Gemini) and Tableau Prep. You can now generate, modify, and build data cleaning flows simply through natural language conversations or Python scripts, without ever opening the GUI!

Author: Cooper Wenhua <[e-mail]>

Installation

pip install cwprep

Quick Start

from cwprep import TFLBuilder, TFLPackager

# Create builder
builder = TFLBuilder(flow_name="My Flow")

# Add database connection
conn_id = builder.add_connection(
    host="localhost",
    username="root",
    dbname="mydb"
)

# Add input tables
orders = builder.add_input_table("orders", "orders", conn_id)
customers = builder.add_input_table("customers", "customers", conn_id)

# Join tables
joined = builder.add_join(
    name="Orders + Customers",
    left_id=orders,
    right_id=customers,
    left_col="customer_id",
    right_col="customer_id",
    join_type="left"
)

# Add output
builder.add_output_server("Output", joined, "My_Datasource")

# Build and save
flow, display, meta = builder.build()
TFLPackager.save_tfl("./my_flow.tfl", flow, display, meta)

By default, both the SDK and MCP output only the final .tfl/.tflx archive. Use save_to_folder() only when you explicitly want the exploded folder for inspection.

Features

Feature	Method	Description
Database Connection	add_connection()	Connect to MySQL/PostgreSQL/SQL Server
File Connection	add_file_connection()	Connect to Excel (.xlsx/.xls) or CSV files
SQL Input	add_input_sql()	Custom SQL query input
Table Input	add_input_table()	Direct table connection
Excel Input	add_input_excel()	Read from Excel worksheet
CSV Input	add_input_csv()	Read from CSV file
CSV Union	add_input_csv_union()	Merge multiple CSV files
Join	add_join()	left/right/inner/full joins (single or multi-column)
Union	add_union()	Merge multiple tables
Filter	add_filter()	Expression-based filter
Value Filter	add_value_filter()	Keep/exclude by values
Keep Only	add_keep_only()	Select columns
Remove Columns	add_remove_columns()	Drop columns
Rename	add_rename()	Rename columns
Calculation	add_calculation()	Tableau formula fields
Quick Calc	add_quick_calc()	Quick clean (lowercase/uppercase/trim/remove)
Change Type	add_change_type()	Change column data types
Duplicate Column	add_duplicate_column()	Duplicate (copy) a column
Aggregate	add_aggregate()	GROUP BY with SUM/AVG/COUNT
Pivot	add_pivot()	Rows to columns
Unpivot	add_unpivot()	Columns to rows
Output	add_output_server()	Publish to Tableau Server
TFLX Packaging	build(is_packaged=True)	Generate .tflx with embedded data files
SQL Translation	SQLTranslator	Translate TFL flows to equivalent ANSI SQL

Examples

See the examples/ directory for complete demos:

• demo_basic.py - Input, Join, Output
• demo_cleaning.py - Filter, Calculate, Rename
• demo_field_operations.py - Quick Calc, Change Type, Duplicate Column
• demo_aggregation.py - Union, Aggregate, Pivot
• demo_comprehensive.py - All features combined
• prompts.md - 8 ready-to-use MCP prompt templates for AI-driven flow generation

MCP Server

cwprep includes a built-in Model Context Protocol server, enabling AI clients (Claude Desktop, Cursor, Gemini CLI, etc.) to generate TFL files directly.

Prerequisites

Method	Requirement
uvx (recommended)	Install uv — it auto-downloads cwprep in an isolated env
pip install	Python ≥ 3.8 + pip install cwprep

Quick Start

# Local (stdio)
cwprep-mcp

# Remote (Streamable HTTP)
cwprep-mcp --transport streamable-http --port 8000

[!TIP] Upgrading? If you previously used uvx with an older version, clear the cache to pick up the latest release:

uv cache clean cwprep

Client Configuration

All clients below use the uvx method (recommended). Replace uvx with cwprep-mcp if you prefer a local pip install.

Claude Desktop

Edit config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

Cursor

Settings → MCP → Add new MCP server, or edit ~/.cursor/mcp.json:

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

VS Code (Copilot)

Create .vscode/mcp.json in project root:

{
  "servers": {
    "cwprep": {
      "command": "uvx",
      "args": ["--from", "cwprep", "cwprep-mcp"]
    }
  }
}

Windsurf (Codeium)

Edit ~/.codeium/windsurf/mcp_config.json:

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

Claude Code (CLI)

claude mcp add cwprep -- uvx --from "cwprep" cwprep-mcp

Gemini CLI

Edit ~/.gemini/settings.json:

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

Continue (VS Code / JetBrains)

Edit ~/.continue/config.yaml:

mcpServers:
  - name: cwprep
    command: uvx
    args:
      - --from
      - cwprep
      - cwprep-mcp

Remote HTTP Mode (any client)

Start the server:

cwprep-mcp --transport streamable-http --port 8000

Then configure your client with the endpoint: http://your-server-ip:8000/mcp

Available MCP Capabilities

Type	Name	Description
🔧 Tool	generate_tfl	Generate .tfl/.tflx file from flow definition
🔧 Tool	translate_to_sql	Translate flow definition or .tfl file to ANSI SQL
🔧 Tool	list_supported_operations	List all supported node types
🔧 Tool	validate_flow_definition	Validate flow definition before generating
📖 Resource	cwprep://docs/api-reference	SDK API reference
📖 Resource	cwprep://docs/calculation-syntax	Tableau Prep calculation syntax
📖 Resource	cwprep://docs/best-practices	Common pitfalls and flow design rules
💬 Prompt	design_data_flow	Interactive flow design assistant
💬 Prompt	explain_tfl_structure	TFL file structure explanation

AI Skill Support

This project includes a specialized AI Skill for assistants like Claude or Gemini to help you build flows.

• Location: .agents/skills/tfl-generator/
• Features: MCP server index with fallback SDK usage guide. Detailed API and syntax references are served via MCP Resources from src/cwprep/references/.

Directory Structure

cwprep/
├── .agents/skills/      # AI Agent skills (MCP index)
├── src/cwprep/          # SDK source code
│   ├── builder.py       # TFLBuilder class
│   ├── packager.py      # TFLPackager class
│   ├── translator.py    # SQLTranslator class
│   ├── expression_translator.py  # ExpressionTranslator class
│   ├── config.py        # Configuration utilities
│   ├── mcp_server.py    # MCP Server (Tools, Resources, Prompts)
│   └── references/      # MCP Resource documents (.md)
├── examples/            # Demo scripts
├── docs/                # Documentation
└── tests/               # Unit tests

Configuration

Create config.yaml for default settings:

# MySQL (default)
database:
  host: localhost
  port: 3306
  dbname: mydb
  type: mysql

# SQL Server (Windows Authentication)
# database:
#   host: localhost
#   type: sqlserver
#   authentication: sspi
#   schema: dbo

# PostgreSQL
# database:
#   host: localhost
#   port: 5432
#   dbname: mydb
#   type: postgres

tableau_server:
  url: http://your-server
  default_project: Default

Changelog

See changelog.md for version history.

License

AGPL-3.0 License