Cwprep

cwprep

Tableau Prep 流程工程，用于以可复现的方式生成和验证 .tfl / .tflx，以及将其转换为 SQL。

cwprep 是一款 Python 工具包和模型上下文协议（MCP）服务，可通过代码或 Agent 工具调用来构建 Tableau Prep 流程。

它旨在充当 PrepFlow 工程层，而非通用对话式分析 Agent。其重点是在本地工作流、脚本和 AI 客户端中实现可复现、可检查和安全的自动化。

cwprep 中的 cw 源自 Cooper Wenhua。

作者： Cooper Wenhua <[email protected]>

网站 · 源码 · 更新日志

试用示例工作流 · 阅读指南

快速开始

安装

pip install cwprep

作为 MCP 服务运行

uvx cwprep

上面的简写仍是最简单的 MCP 客户端选项，也是本仓库中展示的默认配置。用户在交互式终端中直接运行 cwprep 时，它会打印 CLI 帮助信息，而不会启动 stdio MCP。

使用相同的命令将服务添加到 MCP 客户端。例如：

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

对于 Claude Code：

claude mcp add cwprep -- uvx cwprep

对于 VSCode，将 cwprep 添加到工作区或用户的 mcp.json，并将 uvx cwprep 用作命令。

如果你更喜欢显式指定脚本名称，也可以使用以下等效的启动方式：

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

有关特定客户端的详细信息和完整参考，请参阅 https://github.com/aidatacooper/cwprep/blob/main/docs/guide.md。

使用 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 使用与 MCP 工具相同的声明式流程结构，因此无需转换即可在本地终端、CI 作业和 Agent 之间迁移规范。

亮点

领域	功能
流程编写	通过 Python 或声明式 MCP 定义生成 Tableau Prep .tfl / .tflx 流程
数据输入	连接 MySQL、PostgreSQL、SQL Server、Alibaba AnalyticDB for MySQL、CSV、Excel、自定义 SQL 和表输入
Prep 操作	构建联接、联合、筛选、值筛选、保留/移除列、重命名、计算、快速清理步骤、类型更改、聚合、透视和逆透视
打包	保存最终的 .tfl 存档或内嵌数据文件的打包 .tflx 文件
SQL 转换	将生成的或现有的 .tfl 流程转换为易读的 ANSI SQL CTE
CLI 工作流	在终端或 CI 中验证规范、生成流程、检查功能并转换 SQL
MCP 支持	通过 Claude、Cursor、VSCode、Gemini CLI、Continue 或其他 MCP 客户端驱动流程生成

实际演示

此 GIF 展示了设计并生成 Tableau Prep 流的 MCP 工具工作流。

架构

                            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 视图：

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

参考层与库打包在一起，因此 Agent 和脚本可以依据经过验证的 API 指南开始操作，解析 Tableau Prep 计算语法，并避免常见的流程设计问题，而无需依赖已检出的代码仓库。

Agent 架构

cwprep 专为使用工具的 Agent 设计，而不仅仅是直接调用 Python。MCP 服务为 Agent 提供精简的流程生成接口；资源文档则在生成前提供针对各阶段的 Tableau Prep 指南。

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

提示词说明要构建什么。资源说明如何正确构建。工具让生成的流程可检查且可重复。

能力边界

cwprep 有意将其公共接口保持精简：

级别	含义
Core	用于常规 SDK 文档、示例和 MCP 工作流的稳定原语
Advanced	受支持的组合形式，例如打包的 .tflx、文件联合、多列联接和 SQL 转换
Inspectable	可使用展开的流程文件夹和内部 JSON 进行调试，但默认输出为最终存档

当 Agent 需要确认某项请求的 Prep 操作是否属于稳定接口时，请使用 list_supported_operations。

设计决策

• MCP 工作流以定义为先：设计流程、验证 JSON 合约，然后生成存档。
• 资源文档是针对各阶段的操作指南，而非通用的提示词填充内容。
• SDK 和 MCP 默认只输出最终的 .tfl / .tflx 存档。仅当你明确需要展开的文件夹以供检查时，才使用 save_to_folder()。
• Tableau Prep 计算语法不是 SQL 语法。创建公式前，Agent 应先阅读 cwprep://docs/calculation-syntax。
• SQL 转换用于提升可读性和辅助迁移，并非 Tableau Prep 执行的替代方案。
• 文件替换采用防护措施：生成过程会先写入临时文件，再备份现有输出，然后进行替换。

验证

cwprep 提供四个级别的流程验证和审查：

级别	描述	要求
1. 定义验证	生成文件前验证声明式 MCP 流程定义	无
2. 存档生成安全性	写入临时文件、备份现有输出，并生成最终 .tfl / .tflx 存档	无
3. SQL 转换审查	将受支持的流程逻辑转换为 ANSI SQL CTE，以供检查和制定迁移计划	无
4. Tableau Prep 可打开性	在 Tableau Prep Builder 中打开生成的存档，以进行最终产品验证	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")

常见问题

.tfl 和 .tflx 有什么区别？

.tfl 是 Tableau Prep 流存档。.tflx 是打包版本，可包含流程使用的本地数据文件。

cwprep 会打开或运行 Tableau Prep Builder 吗？

不会。cwprep 会生成可由 Tableau Prep Builder 打开的文件，但不会自动操作 Tableau Prep 桌面 GUI。

validate_flow_definition 会保存文件吗？

不会。validate_flow_definition 会在生成前检查请求的流程定义。generate_tfl 是用于写入最终 .tfl 或 .tflx 存档的 MCP 工具。

cwprep 可以将流程转换为 SQL 吗？

可以。SQLTranslator 和 MCP 工具 translate_to_sql 可以将受支持的 .tfl 流程逻辑转换为 ANSI SQL 风格的 CTE。

什么时候应该使用 uvx cwprep，什么时候应该使用 python -m cwprep.mcp_server？

常规 MCP 工作流请使用 uvx cwprep。如需在本地明确测试 MCP，而不依赖智能入口点检测，请使用 cwprep mcp 或 python -m cwprep.mcp_server。

为保持向后兼容，uvx --from cwprep cwprep-mcp 和 cwprep-mcp 仍可使用。

完整指南在哪里？

请参阅在线指南。

文档

• 指南
• 示例
• 更新日志