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.