04 | cwprep and cwtwb Basic Cases: Python First, Then MCP

What You Will Learn

• Why Python interfaces should come first
• How to run one minimal cwprep Python case
• How to run one minimal cwtwb Python case
• Why MCP is an AI calling layer built on top of the same interfaces

Prerequisites

• You completed previous guides (Python/uv/IDE/Agent + basic MCP setup)
• You can access these online example folders:

- cwprep examples: https://github.com/imgwho/cwprep/tree/main/examples - cwtwb examples: https://github.com/imgwho/cwtwb/tree/master/examples

Why Python Interfaces Are Necessary First

Starting with Python interfaces gives you:

• Stability: if scripts run, core capabilities are available
• Control: precise input, parameters, and output paths
• Easier debugging: faster isolation of data/parameter/environment issues
• Reusability: script templates for automation and team standards

In one line: MCP is not a different capability stack. It calls the same core interfaces.

Python Case A: cwprep (Data Flow First)

Start with this minimal pattern (aligned with cwprep/examples/quick_start.py):

from cwprep import TFLBuilder, TFLPackager

builder = TFLBuilder(flow_name="quick_start_demo")
conn = builder.add_connection(host="localhost", username="root", dbname="demo")
orders = builder.add_input_table("orders", "orders", conn)
builder.add_output_server("output", orders, "orders_datasource")

flow, display, meta = builder.build()
TFLPackager.save_tfl("./quick_start_demo.tfl", flow, display, meta)

If you want slightly richer cleaning examples, check cwprep examples:

• demo_basic.py
• demo_cleaning.py

Expected result:

• A .tfl or .tflx file is generated
• The file opens in Tableau Prep

Python Case B: cwtwb (Workbook Second)

Start with a minimal workbook pattern (aligned with cwtwb/examples/scripts/demo_connections.py):

from cwtwb import create_workbook, set_excel_connection, add_worksheet, configure_chart, save_workbook

create_workbook()
set_excel_connection(filepath="Sample - Superstore.xls", sheet_name="Orders")
add_worksheet(worksheet_name="Sales by Category")
configure_chart(
    worksheet_name="Sales by Category",
    mark_type="bar",
    rows=["Category"],
    columns=["SUM(Sales)"],
)
save_workbook(output_path="sales_by_category.twb")

If you want slightly richer layout examples, check cwtwb examples/scripts:

• demo_declarative_layout.py
• demo_auto_layout4.py

Expected result:

• A .twb or .twbx file is generated
• The file opens in Tableau Desktop

Then MCP: Built on the Same Interfaces

Once Python cases are working, MCP becomes much easier:

• Better for non-developers: natural language workflow
• Better for collaboration: agents can call tools directly
• Better troubleshooting: if MCP fails, validate the same action in Python first

MCP Cases: Mirror the Python Cases

Use cwprep first, then cwtwb:

• cwprep prompts: https://github.com/imgwho/cwprep/blob/main/examples/prompts.md
• cwtwb prompts: https://github.com/imgwho/cwtwb/tree/master/examples/prompts

Recommended execution order:

1. Pick one minimal prompt from cwprep prompts
2. Confirm output file is generated
3. Pick one minimal prompt from cwtwb prompts
4. Confirm workbook output is generated

Validation Checklist

• Python path generated .tfl/.tflx
• Python path generated .twb/.twbx
• MCP path triggered real tool calls (not text-only suggestions)
• You can explain: Python interfaces are the foundation, MCP is the calling layer

Common Beginner Issues

• Python works but MCP fails: usually MCP config/client restart issue
• MCP returns output but files are wrong: verify parameters/data in Python case first
• Still blocked: paste error + config into AI agent and ask for smallest next fix

Next Step

You now have a full loop: validate in scripts first, then scale with MCP collaboration. Next you can move to templates, batching, and migration workflows.