twilize

Toolkit zur Generierung von Tableau-Arbeitsmappen (.twb/.twbx) für reproduzierbare Dashboards und Arbeitsmappen-Engineering Erstellen Sie programmgesteuert Tableau-Arbeitsmappen mit stabilen analytischen Primitiven, Dashboard-Komposition und integrierter struktureller Validierung.

Übersicht

twilize ist ein Model Context Protocol (MCP) Server und ein Python-Toolkit zum Generieren von Tableau Desktop Arbeitsmappendateien (.twb / .twbx) aus Code oder KI-gesteuerten Tool-Aufrufen.

Es ist als Arbeitsmappen-Engineering-Ebene konzipiert, nicht als konversationsbasierter Datenexplorations-Agent. Das Ziel ist es, die Generierung von Arbeitsmappen reproduzierbar, überprüfbar und sicher für die Automatisierung in lokalen Workflows, Skripten und CI-Umgebungen zu machen.

Der Standard-Workflow ist:

1. Starten Sie mit einer bekannten Vorlage (.twb oder .twbx) oder der integrierten Zero-Config-Vorlage

2. Fügen Sie berechnete Felder und Parameter hinzu

3. Erstellen Sie Arbeitsblätter aus stabilen Diagramm-Primitiven

4. Stellen Sie Dashboards und Interaktionen zusammen

5. Speichern und validieren Sie eine .twb oder .twbx, die sich in Tableau Desktop öffnen lässt

                            Interfaces
  ┌───────────────────────────────────────────────────────────────┐
  │  ┌──────────────────────────┐  ┌───────────────────────────┐  │
  │  │        MCP Server        │  │      Python Library       │  │
  │  │  tools_workbook          │  │  from twilize.twb_editor    │  │
  │  │  tools_layout            │  │  import TWBEditor         │  │
  │  │  tools_migration         │  │                           │  │
  │  │  tools_support           │  │  editor.add_...()         │  │
  │  │                          │  │  editor.configure_...()   │  │
  │  │  (Claude / Cursor /      │  │  editor.save(...)         │  │
  │  │   VSCode / Claude Code)  │  │                           │  │
  │  └─────────────┬────────────┘  └──────────────┬────────────┘  │
  │                └──────────────┬────────────────┘               │
  └─────────────────────────────  ┼  ─────────────────────────────┘
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                          TWBEditor                            │
  │       ParametersMixin  ·  ConnectionsMixin                    │
  │       ChartsMixin      ·  DashboardsMixin                     │
  └──────────┬──────────────────┬──────────────────┬─────────────┘
             ▼                  ▼                  ▼
  ┌──────────────────┐  ┌──────────────┐  ┌──────────────────────┐
  │  Chart Builders  │  │  Dashboard   │  │  Analysis &          │
  │                  │  │  System      │  │  Migration           │
  │  Basic  DualAxis │  │              │  │                      │
  │  Pie    Text     │  │  layouts     │  │  migration.py        │
  │  Map    Recipes  │  │  actions     │  │  twb_analyzer.py     │
  │                  │  │  dependencies│  │  capability_registry │
  └────────┬─────────┘  └──────┬───────┘  └──────────┬───────────┘
           └───────────────────┼──────────────────────┘
                               ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                     XML Engine  (lxml)                        │
  │    template.twb/.twbx  →  patch  →  validate  →  save        │
  └───────────────────────────────┬───────────────────────────────┘
                                  ▼
                      output.twb  /  output.twbx

Installation

pip install twilize

Um das mitgelieferte Hyper-basierte Beispiel auszuführen, das .hyper-Dateien untersucht und die physische Orders_*-Tabelle automatisch auflöst, installieren Sie zusätzlich die optionale Beispiel-Abhängigkeit:

pip install "twilize[examples]"

Anforderungen

• Python >= 3.10

• lxml >= 5.0

• uv

• mcp >= 1.0

Schnellstart

Als MCP-Server

Um einem MCP-Client das automatische Erstellen von Tableau-Arbeitsmappen zu ermöglichen, fügen Sie twilize zur MCP-Konfiguration des Clients hinzu.

Der Startbefehl ist bei allen Clients gleich:

uvx twilize

Jeder Client speichert diesen Befehl in einem anderen Konfigurationsformat. Verwenden Sie das passende Beispiel unten.

Claude Desktop

Öffnen Sie ~/Library/Application Support/Claude/claude_desktop_config.json unter macOS oder %APPDATA%\Claude\claude_desktop_config.json unter Windows und fügen Sie Folgendes hinzu:

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

Cursor IDE

1. Öffnen Sie Cursor Settings -> Features -> MCP

2. Klicken Sie auf Add New MCP Server

3. Setzen Sie Type auf command

4. Setzen Sie Name auf twilize

5. Setzen Sie Command auf uvx twilize

Claude Code

claude mcp add twilize -- uvx twilize

VSCode

Öffnen Sie die Arbeitsbereichsdatei .vscode/mcp.json oder Ihre Benutzerprofil-Datei mcp.json und fügen Sie Folgendes hinzu:

{
  "servers": {
    "twilize": {
      "command": "uvx",
      "args": ["twilize"]
    }
  }
}

In VSCode können Sie diese Dateien über die Befehlspalette mit MCP: Open Workspace Folder Configuration oder MCP: Open User Configuration öffnen. Sie können auch MCP: Add Server verwenden und denselben uvx twilize-Befehl über den geführten Ablauf eingeben.

Als Python-Bibliothek

Verwenden Sie TWBEditor(...), um mit einer Vorlage zu beginnen und den Inhalt der Arbeitsmappe neu aufzubauen. Verwenden Sie TWBEditor.open_existing(...), wenn Sie bestehende Arbeitsblätter und Dashboards beibehalten und ein Blatt direkt bearbeiten möchten.

from twilize.twb_editor import TWBEditor

editor = TWBEditor("")  # "" uses the built-in Superstore template
editor.clear_worksheets()
editor.add_calculated_field("Profit Ratio", "SUM([Profit])/SUM([Sales])")

editor.add_worksheet("Sales by Category")
editor.configure_chart(
    worksheet_name="Sales by Category",
    mark_type="Bar",
    rows=["Category"],
    columns=["SUM(Sales)"],
)

editor.add_worksheet("Segment Pie")
editor.configure_chart(
    worksheet_name="Segment Pie",
    mark_type="Pie",
    color="Segment",
    wedge_size="SUM(Sales)",
)

editor.add_dashboard(
    dashboard_name="Overview",
    worksheet_names=["Sales by Category", "Segment Pie"],
    layout="horizontal",
)

editor.save("output/my_workbook.twb")

Arbeiten mit gepackten Arbeitsmappen (.twbx)

.twbx-Dateien sind ZIP-Archive, die die Arbeitsmappen-XML zusammen mit Datenextrakten (.hyper) und Bild-Assets bündeln. twilize liest und schreibt diese transparent:

from twilize.twb_editor import TWBEditor

# Open a packaged workbook — extracts and images are preserved automatically
editor = TWBEditor.open_existing("templates/dashboard/MyDashboard.twbx")

# Make changes as usual
editor.add_calculated_field("Profit Ratio", "SUM([Profit])/SUM([Sales])")

# Save as .twbx — re-bundles the updated .twb with the original extracts/images
editor.save("output/MyDashboard_v2.twbx")

# Or extract just the XML when the packaged format isn't needed
editor.save("output/MyDashboard_v2.twb")

Eine einfache .twb kann ebenfalls gepackt werden:

editor = TWBEditor("templates/twb/superstore.twb")
# ...
editor.save("output/superstore.twbx")  # produces a single-entry ZIP with the .twb inside

MCP-Tools

Fähigkeitsmodell

Kern-Primitive

Dies sind die stabilen Bausteine, die das Projekt weiterhin garantieren sollte:

• Balken

• Linie

• Fläche

• Kreis

• Karte

• Text / KPI-Karten

• Parameter und berechnete Felder

• Grundlegende Dashboard-Komposition

Fortgeschrittene Muster

Diese werden unterstützt, sind jedoch eher höherwertige Kompositionen oder Interaktionsfunktionen als die Standardoberfläche:

• Streudiagramm

• Heatmap

• Treemap

• Blasendiagramm

• Dual-Achse — mark_color_1/2, color_map_1, reverse_axis_1, hide_zeroline, synchronized

• Tabellenberechnungen — RANK_DENSE, RUNNING_SUM, WINDOW_SUM via add_calculated_field(table_calc="Rows")

• KPI-Differenz-Badges — MIN(1) Dummy-Achse + axis_fixed_range + color_map + customized_label

• Donut (via extra_axes) — Multi-Pane-Kreisdiagramm + weißer Kreis unter Verwendung von configure_dual_axis(extra_axes=[...]); unterstützt color_map für :Measure Names Palette

• Rich-Text-Beschriftungen — configure_chart(label_runs=[...]) für Multi-Style-KPI-Karten und dynamische Titel mit Inline-Feldwerten

• Fortgeschrittenes Arbeitsblatt-Styling — configure_worksheet_style unterstützt Zell-/Datenbeschriftungs-/Markierungsstile auf Pane-Ebene, Formate für Beschriftungen/Zellen/Kopfzeilen pro Feld, Achsen-Tick-Steuerung, Deaktivierung von Tooltips und Unterdrückung von visuellem Rauschen in Tableau

• Unterdrückung von Zeilendimension-Kopfzeilen — configure_worksheet_style(hide_row_label="FieldName")

• Filterzonen, Parametersteuerungen, Farblegenden

• Dashboard-Filter- und Hervorhebungsaktionen

• Deklarative JSON-Layout-Workflows

• Steuerung von Dashboard-Zonentiteln via show_title: false in Layout-Dicts

Rezepte und Showcase-Muster

Diese können heute generiert werden, sollten jedoch eher als Rezepte oder Beispiele betrachtet werden, nicht als erstklassige Versprechen:

• Donut

• Lollipop

• Bullet

• Bump

• Butterfly

• Kalender

Rezept-Diagramme werden absichtlich über ein einziges configure_chart_recipe-Tool bereitgestellt, damit die öffentliche MCP-Oberfläche nicht für jedes Showcase-Muster um ein neues Tool wächst.

Diese Unterscheidung ist wichtig, da twilize nicht versucht, ein Diagramm-Zoo zu werden oder mit Tableaus eigenen konversationsbasierten Analysetools zu konkurrieren. Das Projekt ist am stärksten, wenn es eine zuverlässige, automatisierbare Ebene zur Generierung von Arbeitsmappen bereitstellt.

Fähigkeitsorientierter Workflow

Wenn Sie sich nicht sicher sind, ob etwas zur stabilen SDK-Oberfläche gehört:

1. Verwenden Sie list_capabilities, um die deklarierte Grenze zu überprüfen

2. Verwenden Sie describe_capability, um ein bestimmtes Diagramm, eine Kodierung oder eine Funktion zu prüfen

3. Verwenden Sie analyze_twb oder diff_template_gap, bevor Sie eine Showcase-Vorlage verfolgen

Dies hält die Arbeit an neuen Funktionen an der tatsächlichen Produktgrenze des Projekts ausgerichtet, anstatt an dem, was zufällig in einer Beispiel-Arbeitsmappe erscheint.

Integrierte Validierung

Strukturelle Validierung

save() validiert automatisch die TWB-XML-Struktur vor dem Schreiben:

• Fatale Fehler wie fehlende <workbook> oder <datasources> lösen TWBValidationError aus

• Warnungen wie fehlende <view> oder <panes> werden protokolliert, blockieren aber nicht das Speichern

• Die Validierung kann mit editor.save("output.twb", validate=False) oder editor.save("output.twbx", validate=False) deaktiviert werden

XSD-Schema-Validierung

TWBEditor.validate_schema() prüft die Arbeitsmappe anhand des offiziellen Tableau TWB XSD-Schemas (2026.1), das unter vendor/tableau-document-schemas/ bereitgestellt wird:

result = editor.validate_schema()
print(result.to_text())
# PASS  Workbook is valid against Tableau TWB XSD schema (2026.1)
# — or —
# FAIL  Schema validation failed (2 error(s)):
#   * Element 'workbook': Missing child element(s)...

result.valid          # bool
result.errors         # list[str] — lxml error messages
result.schema_available  # False if the vendor submodule is not checked out

Die gleiche Prüfung ist als MCP-Tool verfügbar:

validate_workbook()                       # validate current open workbook in memory
validate_workbook(file_path="out.twb")    # validate a file on disk (.twb or .twbx)

XSD-Fehler sind informativ — Tableau selbst generiert Arbeitsmappen, die gelegentlich vom Schema abweichen — aber wiederkehrende Fehler signalisieren strukturelle Probleme, die behoben werden sollten.

Dashboard-Layouts

Benutzerdefinierte Layouts können programmgesteuert mithilfe eines verschachtelten layout-Wörterbuchs oder über generate_layout_json für MCP-Workflows erstellt werden.

Hyper-basiertes Beispiel

Das Beispiel examples/hyper_and_new_charts.py verwendet den Sample - EU Superstore.hyper-Extrakt, der direkt im Paket (src/twilize/references/) gebündelt ist, und löst die physische Orders_*-Tabelle über die Tableau Hyper API auf, bevor die Arbeitsmappenverbindung gewechselt wird. Es ist kein Repository-Klon erforderlich — installieren Sie es mit pip install "twilize[examples]" und führen Sie es direkt aus.

Arbeitsmappen-Migration

twilize enthält ein Migrations-Subsystem zum Wechseln einer bestehenden .twb auf eine neue Datenquelle — zum Beispiel, um eine Arbeitsmappe, die auf einer Excel-Datei basiert, auf eine andere Excel-Datei mit einem anderen Schema umzustellen oder zwischen Sprachvarianten desselben Datensatzes zu migrieren.

Funktionsweise

Die Migration ist ein mehrstufiger Workflow. Jeder Schritt ist sowohl als MCP-Tool als auch als Python-Funktion verfügbar:

1. inspect_target_schema   →  Scan the target Excel and list its columns
2. profile_twb_for_migration  →  Inventory which fields the workbook uses
3. propose_field_mapping   →  Match source fields to target columns (fuzzy)
4. preview_twb_migration   →  Dry-run: show what would change, blockers/warnings
5. apply_twb_migration     →  Write the migrated .twb + JSON reports

migrate_twb_guided ist ein Komfort-Wrapper, der die Schritte 2–5 nacheinander ausführt und automatisch pausiert, wenn nur noch Feldübereinstimmungen mit geringer Konfidenz vorhanden sind, und ein warning_review_bundle zur menschlichen Überprüfung zurückgibt, bevor fortgefahren wird.

Python-Beispiel

from twilize.migration import migrate_twb_guided_json
import json

# One-call guided migration
result = migrate_twb_guided_json(
    file_path="templates/SalesDashboard.twb",
    target_source="data/new_data_source.xlsx",
    output_path="output/SalesDashboard_migrated.twb",
)
bundle = json.loads(result)

if bundle["status"] == "warning_review_required":
    # Inspect low-confidence matches and confirm or override them
    print(bundle["warning_review_bundle"])
    # Re-run with confirmed mappings
    result = migrate_twb_guided_json(
        file_path="templates/SalesDashboard.twb",
        target_source="data/new_data_source.xlsx",
        output_path="output/SalesDashboard_migrated.twb",
        mapping_overrides={"Old Field Name": "New Column Name"},
    )

MCP-Tool-Beispiel

Wenn Sie twilize als MCP-Server verwenden, kann ein KI-Agent den vollständigen Workflow ausführen:

inspect_target_schema(target_source="data/new_data_source.xlsx")
→ returns column list and data types

migrate_twb_guided(
    file_path="templates/SalesDashboard.twb",
    target_source="data/new_data_source.xlsx",
    output_path="output/SalesDashboard_migrated.twb"
)
→ returns status: "applied" or "warning_review_required"

Ausgabedateien

Eine abgeschlossene Migration schreibt drei Dateien:

Scope-Parameter

scope="workbook" migriert alle Arbeitsblätter. Übergeben Sie einen Arbeitsblattnamen, um die Migration auf ein einzelnes Blatt zu beschränken.

Eigenständiges Beispiel

examples/migrate_workflow/ enthält eine Vorlagen-.twb, die ursprüngliche Superstore-Excel, eine Ziel-Superstore-Excel mit chinesischem Gebietsschema und ein ausführbares Skript:

python examples/migrate_workflow/test_migration_workflow.py

Projektstruktur

twilize/
|-- src/twilize/
|   |-- __init__.py
|   |-- capability_registry.py
|   |-- config.py
|   |-- charts/
|   |-- connections.py
|   |-- dashboard_actions.py
|   |-- dashboard_dependencies.py
|   |-- dashboard_layouts.py
|   |-- dashboards.py
|   |-- field_registry.py
|   |-- layout.py
|   |-- layout_model.py
|   |-- layout_rendering.py
|   |-- mcp/
|   |-- parameters.py
|   |-- twb_analyzer.py
|   |-- twb_editor.py
|   |-- validator.py
|   `-- server.py
|-- tests/
|-- examples/
|-- docs/
|-- pyproject.toml
`-- README.md

Entwicklung

# Install in editable mode
pip install -e .

# Run test suite
pytest --basetemp=output/pytest_tmp

# Run the mixed showcase example
python examples/scripts/demo_all_supported_charts.py

# Run the advanced Hyper-backed example
python examples/scripts/demo_hyper_and_new_charts.py

# Run the guided migration example
python examples/migrate_workflow/test_migration_workflow.py

# Start MCP server
twilize

MCP-Server-Manifest

twilize wird mit einem vollständigen MCP-Server-Manifest (mcp-server.json) ausgeliefert — dem MCP-Äquivalent einer Tableau-Erweiterungsdatei .trex. Es deklariert: