Cwprep

cwprep

再現可能な .tfl / .tflx の生成、検証、SQL 変換を実現する Tableau Prep フローエンジニアリングツールキットです。

cwprep は、コードまたはエージェントのツール呼び出しによって Tableau Prep フローを構築するための Python ツールキット兼 Model Context Protocol（MCP）サーバーです。

これは汎用的な会話型分析エージェントではなく、PrepFlow エンジニアリングレイヤーとして設計されています。ローカルのワークフロー、スクリプト、AI クライアントにおける再現性、検査可能性、安全な自動化を重視しています。

cwprep の cw は Cooper Wenhua に由来します。

作成者： Cooper Wenhua <[email protected]>

ウェブサイト · ソース · 変更履歴

サンプルのワークフローを試す · ガイドを読む

クイックスタート

インストール

pip install cwprep

MCP サーバーとして実行する

uvx cwprep

上記の短縮形式は、最もシンプルな MCP クライアントの設定であり、このリポジトリに掲載されているデフォルト設定です。対話型ターミナルで人が cwprep を直接実行すると、stdio MCP を起動する代わりに CLI のヘルプが表示されます。

同じコマンドを使って、MCP クライアントにサーバーを追加してください。例：

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

Claude Code の場合：

claude mcp add cwprep -- uvx cwprep

VSCode の場合は、ワークスペースまたはユーザーの mcp.json に cwprep を追加し、コマンドとして 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 ジョブ、エージェント間で共有できます。

主な特長

領域	内容
フローの作成	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

参照レイヤーはライブラリに同梱されているため、エージェントやスクリプトは、チェックアウトしたリポジトリに依存せず、実績のある API ガイダンスをもとに開始し、Tableau Prep の計算構文を解決して、よくあるフロー設計上の落とし穴を回避できます。

エージェントのアーキテクチャ

cwprep は、Python を直接呼び出すだけでなく、ツールを使用するエージェント向けに設計されています。MCP サーバーは、エージェントに簡潔なフロー生成機能を提供し、リソースドキュメントは生成前にフェーズごとの 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 はデバッグに利用できますが、デフォルトの出力は最終アーカイブです

エージェントが要求された Prep 操作が安定したインターフェースの対象かどうかを確認する必要がある場合は、list_supported_operations を使用してください。

設計上の決定事項

• MCP ワークフローは定義を先に作成します。フローを設計し、JSON コントラクトを検証してから、アーカイブを生成します。
• リソースドキュメントはフェーズごとの運用ガイドであり、汎用的なプロンプトへの情報の詰め込みではありません。
• SDK と MCP のデフォルトの出力は、最終的な .tfl / .tflx アーカイブのみです。検査用に展開したフォルダーが明示的に必要な場合にのみ、save_to_folder() を使用してください。
• Tableau Prep の計算構文は SQL 構文ではありません。数式を作成する前に、エージェントは cwprep://docs/calculation-syntax を読む必要があります。
• SQL 変換は可読性の向上と移行の補助を目的としており、Tableau Prep による実行の代わりではありません。
• ファイルの置き換えは安全性を考慮して処理されます。生成時にはまず一時ファイルを作成し、既存の出力をバックアップしてから置き換えます。

検証

cwprep は、フローの検証とレビューを 4 つのレベルで提供します。

レベル	説明	必要なもの
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")

FAQ

.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 と translate_to_sql MCP ツールを使うと、サポート対象の .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 も引き続き動作します。

ガイド全文はどこにありますか？

オンラインガイドをご覧ください。

ドキュメント

• ガイド
• 例
• 変更履歴