Cwtwb

cwtwb

再現可能な .twb / .twbx の生成、検証、移行を実現する Tableau ワークブックエンジニアリング。

cwtwb は、コードやエージェントのツール呼び出しから Tableau Desktop ワークブックを構築するための Python ツールキット兼 Model Context Protocol（MCP）サーバーです。

これは会話型分析エージェントではなく、ワークブックエンジニアリング層を目指しています。ローカルのワークフロー、スクリプト、CI における再現性、検査可能性、安全な自動化に重点を置いています。

デザインワークフローの参考資料

エージェント設計ワークフローと design_advisor スキルは、Adam Mico 氏の adammico-lab Tableau workflow skills、特に Tableau Dashboard Blueprint のデザイン仕様から構築する手法を参考にしています。 cwtwb はこれらのアイデアを独自に応用し、再現可能な .twb / .twbx の作成を実現しています。adammico-lab のコードやスキルの内容には依存せず、同梱もコピーもしていません。cwtwb は Adam Mico 氏、Salesforce、Tableau とは無関係です。

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

作者： Cooper Wenhua <[email protected]>

Web サイト · ソース · 変更履歴

スター履歴

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

クイックスタート

インストール

pip install cwtwb

Hyper を利用するサンプルも同梱版で実行する場合：

pip install "cwtwb[examples]"

クラウド検証（Tableau Cloud／Server へのアップロード）を利用する場合：

pip install "cwtwb[validate]"

MCP サーバーとして実行

uvx cwtwb

上記の短い形式が引き続き最も簡単な方法で、このリポジトリで既定の設定として示されています。cwtwb は状況に応じて動作するエントリーポイントです。対話型ターミナルで引数なしで実行すると CLI ヘルプを表示し、MCP クライアントから stdio 経由で起動されるとサーバーを開始します。

同じコマンドで、MCP クライアントにサーバーを追加できます。例：

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

Claude Code の場合：

claude mcp add cwtwb -- uvx cwtwb

VSCode では、ワークスペースまたはユーザーの mcp.json に cwtwb を追加し、コマンドとして uvx cwtwb を使用します。

スクリプト名を明示したい場合は、次の同等の起動方法も使用できます：

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

CLI として使用

同じパッケージでは、人間、スクリプト、CI、MCP ツール呼び出しではなくファイルを直接操作する必要があるエージェント向けに、フル機能のコマンドラインワークフローも提供しています。

cwtwb --help
cwtwb doctor
cwtwb status --json
cwtwb inspect workbook.twb --json
cwtwb validate workbook.twb
cwtwb analyze workbook.twb --json
cwtwb run examples/specs/basic_cli.yaml

一般的な書き込みコマンドでは、既定で出力パスの指定が必要です：

cwtwb create --out output/base.twb
cwtwb chart add output/base.twb --worksheet "Sales by Category" --mark Bar --rows Category --columns "SUM(Sales)" --out output/chart.twb
cwtwb dashboard add output/chart.twb --name Overview --worksheets "Sales by Category" --out output/dashboard.twb

入力ワークブックを意図的に上書きする場合にのみ --in-place を使用し、既存の出力ファイルを置き換える場合にのみ --force を使用してください。

ワークブックを形式間で変換する

convert はファイル拡張子から TWB、TWBX、YAML、JSON を判別します。Gallery、テンプレート、アクティブなエディターセッションは必要ありません。

cwtwb convert input.twbx --out workbook.yaml
cwtwb convert workbook.yaml --out workbook.json
cwtwb convert workbook.json --out rebuilt.twbx
cwtwb convert input.twbx --out unpacked.twb

cwtwb export input.twb --out workbook.yaml はエイリアスです。ネイティブ定義は cwtwb run workbook.yaml --out rebuilt.twb でも使用できます。既存の自動化仕様の動作は従来どおりです。--force を指定しない限り出力は上書きされません。また、変換によって入力が上書きされることはありません。

Python では、from cwtwb import convert_workbook に続けて convert_workbook("input.twbx", "workbook.yaml") を実行します。MCP では、同じステートレスな convert_workbook(input_path, output_path, force=False) ツールを公開しています。

バージョン管理された cwtwb-native 形式では、現在 ネイティブの XML ツリー を表現します。document.root には、tag、attributes、text、順序を保持した children、tail が含まれます。コメント、処理命令、名前空間、サムネイル、未知の要素も保持されます。数式は calculation.attributes.formula で、レイアウトのジオメトリは zone 属性で編集します。XML 属性値は文字列のままです。これは詳細な構造形式であり、簡略化されたセマンティックなワークブック DSL ではまだありません。すべての Tableau 機能が理解され、安全に編集できるとは限りません。変換では TWBEditor によるクリーンアップを迂回し、自動生成コメントも挿入しません。XML 宣言の表記、CDATA の表記、名前空間プレフィックス、ZIP メタデータがバイト単位で保持される保証はありません。未知のノードは保持されますが、解釈はされません。

バイナリリソースは <output-name>.assets/ にコピーされ、定義には相対パスと SHA-256 ハッシュが記録されます。定義とこのディレクトリは一緒に保管してください。展開された TWB には、後で再パッケージ化する際に未参照のパッケージアセットを保持するための <output-name>.resources.json コンパニオンファイルも作成されます。必要に応じてファイル参照は再配置されますが、リモートデータベース接続はリモートのままです。スタンドアロン TWB の検出対象は現在、Hyper／CSV／Excel 接続とビットマップゾーンです。カスタム拡張機能が参照する任意の外部ファイルは自動的には検出されません。TWBX の変換では、未知の拡張子を含め、バンドルされたすべてのリソースファイルが保持されます。

既知の外部リソースが見つからない場合、テキスト出力では警告が表示され、TWBX のパッケージ化は中止されます。重複キー、未知のドキュメントプロパティ／バージョン、存在しない、または変更されたリソースファイル、安全でないアーカイブパス、TWB が複数含まれるアーカイブ、DTD を含む XML は、明示的にエラーになります。アセットを意図的に変更した後は、記録されているハッシュを更新してください。出力を置き換えても、リソースディレクトリはガベージコレクションされません。

変換で検証されるのは XML 構文とリソースの整合性であり、Tableau の計算、フィールド参照のセマンティクス、Desktop での読み込み、レンダリング、インタラクションではありません。既存の検証コマンドと Tableau ランタイムでのチェックは、別途実行してください。変換中にそのようなチェックが実行されたと誤解されないよう、ネイティブ定義では run --validate は意図的に拒否されます。

MCP クライアントの安定性

cwtwb が MCP サーバーとして接続されている場合、エージェントはクライアントを通じて公開された MCP ツールを直接呼び出す必要があります。mcp call cwtwb ...、mcp list-tools cwtwb、gh api .../mcp/... などのシェルコマンドを実行してはいけません。これらのコマンドは cwtwb の一部ではなく、通常の Claude、Codex、Cursor、VSCode 環境では一般に利用できません。

エージェントが create_workbook、add_worksheet、save_workbook などのツールを認識できない場合は、MCP クライアントを再起動または再接続し、サーバー設定を確認してください。uv キャッシュをクリアするとインストール済みパッケージは更新されますが、古いクライアントのツール一覧は修正されません。

既存の .twb をビジュアル参照として使用する場合、エージェントは Tableau XML の列インスタンストークンをチャート入力にコピーしてはいけません。[sum:Sales:qk]、[none:Category:nk]、[mn:Order Date:ok]、[federated.xxx].[sum:Profit:qk] などの値は、生成された内部表現です。代わりに、Sales、SUM(Sales)、Category、MONTH(Order Date) など、ユーザー向けの式を渡してください。

エージェント向けの便利なリソース：

cwtwb://tool-surface
cwtwb://skills/index
cwtwb://skills/data_quality
cwtwb://skills/design_advisor
cwtwb://skills/metric_blueprint
cwtwb://skills/dashboard_designer
cwtwb://skills/quality_review
cwtwb://skills/documentation
file://docs/tableau_all_functions.json

cwtwb://docs/manual-editing など、よく推測される URI の互換エイリアスも利用できますが、新しいプロンプトでは cwtwb://tool-surface と cwtwb://skills/index を優先してください。

クライアント固有の詳細と完全なリファレンスについては、https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md を参照してください。

ダッシュボードレイアウトファイル

カスタムダッシュボードレイアウトを、同じ宣言型 DSL を使って JSON または YAML で作成できるようになりました。エージェントのワークフローでは、まずレイアウトファイルを生成し、そのファイルパスを add_dashboard(layout=...) に渡してください。

generate_layout_json("output/layout.json", layout_tree, ascii_preview)
generate_layout_yaml("output/layout.yaml", layout_tree, ascii_preview)

どちらの形式も、同じラッパー構造に対応しています。

• layout_schema：正規のダッシュボードレイアウトツリー
• _ascii_layout_preview：任意の人間／エージェントによるレビュー用補助情報

説明可能なダッシュボードギャラリー

cwtwb には、一般的な分析構造向けのパッケージ済みギャラリーテンプレートが 7 種類含まれています。推奨は明示的な要件を使用し、スコア、一致理由、ペナルティを返します。データを調査したり、暗黙にチャートを生成したりすることはありません。

from cwtwb import DashboardRequirements, recommend_gallery_templates

recommendations = recommend_gallery_templates(
    DashboardRequirements(
        primary_intent="trend",
        has_temporal_data=True,
        kpi_count=2,
        chart_count=3,
        chart_types=("Line", "Bar"),
    )
)

list_worksheets の呼び出し後、materialize_gallery_layout(...) または MCP の generate_gallery_layout ツールを使って、正確なワークシート名を割り当ててください。生成結果では、add_dashboard が受け付けるものと同じ正規 DSL が使用されます。

計算フィールドの安全性

add_calculated_field は、XML を編集する前に、関数呼び出しとして使われている識別子をパッケージ済み Tableau カタログと照合します。たとえば、CHR(10) は CHAR() の提案とともに拒否されます。これは軽量な関数名チェックであり、完全な Tableau パーサーや Tableau Cloud のセマンティック検証の代替ではありません。

パッケージ済みカタログにまだ含まれていない新しい Tableau 関数を対象にする場合に限り、validate_formula=False を使用してください。既存のワークブックは audit_calculated_fields() で確認できます。修復は別途実行され、デフォルトでは dry_run=True です。

主な特徴

領域	内容
ワークブックの作成	テンプレートまたは一から .twb / .twbx ファイルを生成し、階層、セット、動的なタイトル、パラメーターのプレースホルダーを追加できます
チャートの作成	棒、折れ線、円、マップ、KPI、二重軸、レイヤー、列数の多い順序付きテーブルのワークブックを作成できます
テーブル計算	計算のアドレス指定メタデータ、ドメイン補完、小計、ネストされたテーブル計算の依存関係を作成できます
ダッシュボードアクション	Python または MCP を通じて、フィルター、ハイライト、URL、ナビゲーション、パラメーター、セットのアクションを追加できます
安全性	関数名と計算フィールドの役割を検証した後、公開前に構造、Tableau XSD（2026.1/2026.2）、REST API のセマンティクスを検証します
ダッシュボードギャラリー	説明可能な 7 つのレイアウトを順位付けし、正確なワークシート名を標準 DSL に割り当てます
クラウド検証	REST API による構文／セマンティクスの検証と、オプションのスクリーンショット付きで Tableau Cloud/Server にアップロードできます
移行	明示的な手順で既存のワークブックのデータソースを新しいものに切り替えます
MCP 対応	Claude、Cursor、VSCode などの MCP クライアントからワークブックのワークフローを実行できます

動作を見る

この GIF では、MCP ツールのフローでダッシュボードを段階的に作成する様子を示します。

アーキテクチャ

                            Interfaces
  ┌───────────────────────────────────────────────────────────────┐
  │  ┌──────────────────────────┐  ┌───────────────────────────┐  │
  │  │        MCP Server        │  │      Python Library       │  │
  │  │  tools_workbook          │  │  from cwtwb.twb_editor    │  │
  │  │  tools_validate          │  │  import TWBEditor         │  │
  │  │                          │  │                           │  │
  │  │                          │  │  editor.add_...()         │  │
  │  │                          │  │  editor.configure_...()   │  │
  │  │                          │  │  editor.validate_schema() │  │
  │  │  (Claude / Cursor /      │  │  editor.save(...)         │  │
  │  │   VSCode / Claude Code)  │  │                           │  │
  │  └─────────────┬────────────┘  └──────────────┬────────────┘  │
  │                └──────────────┬────────────────┘               │
  └─────────────────────────────  ┼  ─────────────────────────────┘
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                          TWBEditor                            │
  │       ParametersMixin  ·  ConnectionsMixin                    │
  │       ChartsMixin      ·  DashboardsMixin                     │
  │       validate_schema()  ·  save()                            │
  └──────────┬──────────────────┬──────────────────┬─────────────┘
             ▼                  ▼                  ▼
  ┌──────────────────┐  ┌──────────────┐  ┌──────────────────────┐
  │  Chart Builders  │  │  Dashboard   │  │  Analysis &          │
  │                  │  │  System      │  │  Migration           │
  │  Basic  DualAxis │  │              │  │                      │
  │  Pie    Text     │  │  layouts     │  │  migration.py        │
  │  Map    Recipes  │  │  actions     │  │  twb_analyzer.py     │
  │                  │  │  dependencies│  │  capability_registry │
  └────────┬─────────┘  └──────┬───────┘  └──────────┬───────────┘
           └───────────────────┼──────────────────────┘
                               ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                    Packaged References                        │
  │    empty_template.twb  ·  Superstore XLS/Hyper                │
  │    tableau_all_functions.json  ·  dataset profiles            │
  │    vendored Tableau TWB XSD schemas (2026.1 / 2026.2)         │
  └───────────────────────────────┬───────────────────────────────┘
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                     XML Engine  (lxml)                        │
  │    template.twb/.twbx  →  patch  →  validate  →  save        │
  └───────────────────────────────┬───────────────────────────────┘
                                  ▼
                      output.twb  /  output.twbx
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │               Cloud Validation (optional)                    │
  │    validate_workbook_api → REST API semantic validation      │
  │    upload_workbook       → Tableau Cloud/Server publish      │
  │    screenshot_workbook   → capture view for visual check     │
  └───────────────────────────────────────────────────────────────┘

Mermaid ビュー：

flowchart TD
    subgraph Interfaces
        MCP["MCP Server<br/>tools_workbook<br/>tools_validate"]
        PY["Python Library<br/>TWBEditor API"]
    end

    subgraph Editor["Core Editor"]
        TWB["TWBEditor<br/>parameters · connections<br/>charts · dashboards<br/>validate_schema · save"]
    end

    subgraph Builders["Workbook Systems"]
        CHARTS["Chart Builders<br/>basic · dual-axis<br/>pie · text · map · recipes"]
        DASH["Dashboard System<br/>layouts · actions<br/>dependencies"]
        ANALYSIS["Analysis & Migration<br/>migration.py<br/>twb_analyzer.py<br/>capability_registry"]
    end

    subgraph References["Packaged References"]
        REFS["empty_template.twb<br/>Superstore XLS/Hyper<br/>Tableau functions<br/>TWB XSD schemas"]
    end

    subgraph Engine["XML Engine"]
        XML["lxml patch pipeline<br/>template.twb/.twbx → patch → validate → save"]
    end

    subgraph Outputs
        OUT["output.twb / output.twbx"]
        CLOUD["Cloud Validation<br/>REST semantic validation<br/>upload · screenshot"]
    end

    MCP --> TWB
    PY --> TWB
    TWB --> CHARTS
    TWB --> DASH
    TWB --> ANALYSIS
    CHARTS --> XML
    DASH --> XML
    ANALYSIS --> XML
    REFS --> TWB
    REFS --> XML
    XML --> OUT
    OUT --> CLOUD

参照レイヤーはライブラリにパッケージ化されているため、エージェントやスクリプトは、チェックアウト済みのリポジトリに依存せず、検証済みのワークブックアセットを起点として、Tableau の計算構文を解決し、Hyper を使用した例を実行し、ローカルの XSD スキーマで検証できます。

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

cwtwb は、Python を直接呼び出すだけでなく、ツールを使用するエージェント向けに設計されています。MCP サーバーは、状態を保持する小規模なワークブック編集インターフェースをエージェントに提供し、スキルのリソースはツールを呼び出す各段階の前に、Tableau に関するガイダンスを提供します。

Human or agent prompt
        |
        v
MCP server instructions
        |
        v
Skill resources
data_quality -> governance -> synthetic_data -> design_advisor -> metric_blueprint
-> calculation_builder -> chart_builder -> dashboard_designer -> formatting
-> validation -> quality_review -> documentation
        |
        v
Workbook tools
create/open -> list_fields -> add/configure -> layout -> save -> validate/upload
        |
        v
TWB/TWBX artifact + validation evidence

プロンプトは何を作成するかを説明します。スキルは適切な作成方法を説明します。ツールを使えば、ワークブックの変更を確認可能かつ再現可能な形で行えます。

パッケージ化されたスキルアーキテクチャについては、 src/cwtwb/skills/README.md に、ワークフロー図と、ガイダンス、明示的な変更、検証の証拠の境界を含めて記載しています。

機能の範囲

cwtwb の公開インターフェースは意図的に小さく保たれています。

レベル	意味
コア	通常の SDK ドキュメント、例、MCP ワークフローで使用する安定したプリミティブ
高度	構成要素が多い、サポート対象の組み合わせとインタラクションパターン
レシピ	configure_chart_recipe で公開されるショーケースパターン。チャートごとにツールがあるわけではありません

エージェントが、要求されたチャートまたはワークブック機能が安定した公開インターフェースに含まれるか確認する必要がある場合は、list_capabilities または describe_capability を使用してください。

設計上の判断

• MCP サーバーは状態を保持するセッションモデルを使用します。ワークブックを開くか作成し、明示的なツールで変更を加えた後、save_workbook を呼び出します。
• スキルは段階ごとの操作ガイドであり、汎用的なプロンプトの詰め込みではありません。
• save_workbook、validate_workbook、validate_workbook_api、upload_workbook はそれぞれ役割が異なるため、エージェントが書き込み、ローカルチェック、セマンティクス検証、公開を混同しません。
• 機能レジストリによって製品の範囲を明確に保ち、ショーケースの例が意図せず API の保証となるのを防ぎます。

検証

cwtwb では、ワークブックを 4 段階で検証できます。

レベル	説明	必要なもの
1. ローカル XSD	公式の Tableau TWB XSD スキーマに照らして検証します（バージョン対応：2026.1 または 2026.2）	なし（組み込み）
2. REST API 構文検証	Tableau Cloud REST API を使用して XML 構文を検証します	Tableau の認証情報 + Tableau Cloud 2026.2 以降
3. REST API セマンティック検証	公開せずに完全なセマンティック検証を行います。.twb に対するデフォルトのクラウドチェックです	Tableau の認証情報 + Tableau Cloud 2026.2 以降
4. アップロード + スクリーンショット	Tableau Cloud/Server に公開し、ビュー画像をキャプチャします	Tableau の認証情報 + pip install "cwtwb[validate]"

# Level 1 — Local XSD (in-memory, no save required)
result = editor.validate_schema()
print(result.to_text())

# Level 3 — REST API semantic validation
from cwtwb.validate.uploader import TableauUploader
uploader = TableauUploader(env_path="project/.env")
result = uploader.validate("output.twb", validation_level="semantic")

# Save with local XSD validation; REST API semantic validation also runs when .env is configured
editor.save("output.twb")

# MCP tools
validate_workbook(file_path="output.twb")                                       # Local XSD validation
validate_workbook_api(twb_path="output.twb", validation_level="semantic")        # Default cloud semantic validation, no publish
validate_workbook_api(twb_path="output.twb", env_path="project/.env")            # Runtime credentials
upload_workbook(twb_path="output.twb")                                          # Publish/openability evidence or TWBX validation
screenshot_workbook(workbook_id="...", view_name="Sheet 1")                     # Visual check after upload_workbook

よくある質問

.twb と .twbx の違いは何ですか？

.twb はワークブックの XML です。.twbx は、ワークブックと抽出データや画像をまとめたパッケージ版です。

validate_workbook はファイルを保存しますか？

いいえ。validate_workbook() は、アクティブなメモリ内ワークブック、または既存の .twb / .twbx ファイルに対してローカル XSD 検証を実行します。出力は書き込みません。ファイルを書き込むツールは save_workbook() です。

save() ではどのような検証が行われますか？

save() は、最終出力ファイルを置き換える前にローカル XSD 検証を自動で実行します。.twb を出力する場合、Tableau の認証情報が設定されており、サーバーが対応していれば、REST API セマンティック検証も実行されます。Tableau Cloud/Server の検証ステップを直接リクエストする場合は、validate_workbook_api(..., validation_level="semantic") を使用してください。

upload_workbook は何に使いますか？

upload_workbook は .twb または .twbx を Tableau Cloud/Server に公開します。公開やオープン可能であることの証拠、スクリーンショット用のワークブック ID、または .twbx パッケージの検証が明示的に必要な場合に使用してください。デフォルトの .twb クラウドセマンティックチェックには、ワークブックを公開したり保存したりしない validate_workbook_api を推奨します。pip install "cwtwb[validate]" と、環境変数、明示的な env_path、TABLEAU_ENV_FILE、またはワークブックと同じ場所にある .env ファイルから取得する Tableau の認証情報が必要です。

Tableau Cloud/Server の検証を設定するにはどうすればよいですか？

1. インストールします：pip install "cwtwb[validate]"
2. .env.example を .env にコピーします
3. Tableau Cloud/Server の PAT 認証情報を入力します
4. save_workbook を呼び出して .twb または .twbx を書き込みます
5. デフォルトの REST API セマンティック検証には validate_workbook_api を呼び出します。公開やオープン可能であることの証拠、スクリーンショット、または .twbx の検証も必要な場合に限り、upload_workbook を呼び出します

認証情報の検索順序は、明示的な env_path、環境変数、TABLEAU_ENV_FILE、ワークブックと同じ場所にある .env、現在の作業ディレクトリの .env、cwtwb プロジェクトの .env、最後にユーザーのホームディレクトリの .env です。MCP サーバーの設定を編集してサーバーを再起動する代わりに、単発の MCP 呼び出しでは env_path を使用してください。

検証で tableauserverclient が見つからないと報告された場合は、まず get_mcp_status を呼び出してください。認証情報を公開せずに、MCP プロセスの Python 実行ファイル、cwtwb のバージョン、Tableau クライアントをインポートできるかどうかを報告します。env_path の変更は実行時にのみ適用されるため、MCP の再起動は不要です。別の Python 環境に依存関係をインストールしても実行中のサーバーは修正されないため、get_mcp_status で報告されたインタープリターに検証用エクストラをインストールしてください。実行環境またはツールスキーマを変更した場合にのみ、再接続してください。

uvx cwtwb と python -m cwtwb.mcp_server は、どのように使い分ければよいですか？

通常の MCP ワークフローには uvx cwtwb を使用してください。uvx を使わずにローカルテストする場合は、python -m cwtwb.mcp_server を使用してください。

後方互換性のため、uvx --from cwtwb cwtwb-mcp、python -m cwtwb.server、python -m cwtwb.mcp も引き続き動作します。

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

オンラインガイドを参照してください。

ドキュメント

• ガイド
• 変更履歴