twilize

Набор инструментов для создания книг Tableau (.twb/.twbx) для воспроизводимых дашбордов и проектирования книг Программное создание книг Tableau со стабильными аналитическими примитивами, композицией дашбордов и встроенной структурной проверкой.

Обзор

twilize — это сервер протокола контекста модели (MCP) и набор инструментов Python для создания файлов книг Tableau Desktop (.twb / .twbx) с помощью кода или вызовов инструментов на базе ИИ.

Он разработан как уровень проектирования книг, а не как агент для разговорного исследования данных. Цель состоит в том, чтобы сделать создание книг воспроизводимым, проверяемым и безопасным для автоматизации в локальных рабочих процессах, скриптах и CI.

Стандартный рабочий процесс:

1. Начните с известного шаблона (.twb или .twbx) или встроенного шаблона с нулевой конфигурацией.

2. Добавьте вычисляемые поля и параметры.

3. Создайте рабочие листы из стабильных примитивов диаграмм.

4. Соберите дашборды и взаимодействия.

5. Сохраните и проверьте файл .twb или .twbx, который открывается в Tableau Desktop.

                            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

Установка

pip install twilize

Чтобы запустить прилагаемый пример на базе Hyper, который проверяет файлы .hyper и автоматически разрешает физическую таблицу Orders_*, установите также дополнительную зависимость для примеров:

pip install "twilize[examples]"

Требования

• Python >= 3.10

• lxml >= 5.0

• uv

• mcp >= 1.0

Быстрый старт

Как сервер MCP

Чтобы позволить клиенту MCP автоматически создавать книги Tableau, добавьте twilize в конфигурацию MCP этого клиента.

Команда запуска одинакова для всех клиентов:

uvx twilize

Каждый клиент хранит эту команду в своем формате конфигурации. Используйте соответствующий пример ниже.

Claude Desktop

Откройте ~/Library/Application Support/Claude/claude_desktop_config.json в macOS или %APPDATA%\Claude\claude_desktop_config.json в Windows и добавьте:

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

Cursor IDE

1. Откройте Cursor Settings -> Features -> MCP

2. Нажмите Add New MCP Server

3. Установите Type в значение command

4. Установите Name в значение twilize

5. Установите Command в значение uvx twilize

Claude Code

claude mcp add twilize -- uvx twilize

VSCode

Откройте файл .vscode/mcp.json в рабочей области или файл mcp.json в профиле пользователя и добавьте:

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

В VSCode вы можете открыть эти файлы из палитры команд с помощью MCP: Open Workspace Folder Configuration или MCP: Open User Configuration. Вы также можете использовать MCP: Add Server и ввести ту же команду uvx twilize через мастер настройки.

Как библиотека Python

Используйте TWBEditor(...), чтобы начать с шаблона и перестроить содержимое книги. Используйте TWBEditor.open_existing(...), если хотите сохранить существующие рабочие листы и дашборды и перенастроить лист на месте.

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")

Работа с упакованными книгами (.twbx)

Файлы .twbx — это ZIP-архивы, которые объединяют XML книги с извлеченными данными (.hyper) и графическими ресурсами. twilize читает и записывает их прозрачно:

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")

Обычный файл .twb также можно упаковать:

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

Инструменты MCP

Модель возможностей

Базовые примитивы

Это стабильные строительные блоки, которые проект должен продолжать поддерживать:

• Столбчатая диаграмма

• Линейная диаграмма

• Диаграмма с областями

• Круговая диаграмма

• Карта

• Текст / KPI-карточки

• Параметры и вычисляемые поля

• Базовая композиция дашбордов

Расширенные шаблоны

Они поддерживаются, но представляют собой композиции более высокого уровня или функции взаимодействия, а не стандартную область применения:

• Точечная диаграмма

• Тепловая карта

• Древовидная карта

• Пузырьковая диаграмма

• Двойная ось — mark_color_1/2, color_map_1, reverse_axis_1, hide_zeroline, synchronized

• Табличные вычисления — RANK_DENSE, RUNNING_SUM, WINDOW_SUM через add_calculated_field(table_calc="Rows")

• Бейджи разницы KPI — фиктивная ось MIN(1) + axis_fixed_range + color_map + customized_label

• Кольцевая диаграмма (через extra_axes) — многопанельная круговая диаграмма + белый круг с использованием configure_dual_axis(extra_axes=[...]); поддерживает color_map для палитры :Measure Names

• Метки с форматированным текстом — configure_chart(label_runs=[...]) для многостилевых KPI-карточек и динамических заголовков со встроенными значениями полей

• Расширенное стилизование рабочих листов — configure_worksheet_style поддерживает стили ячеек/меток данных/меток на уровне панели, форматы меток/ячеек/заголовков для каждого поля, управление делениями осей, отключение подсказок и подавление всех визуальных шумов Tableau

• Подавление заголовка измерения строки — configure_worksheet_style(hide_row_label="FieldName")

• Зоны фильтров, элементы управления параметрами, цветовые легенды

• Действия фильтрации и выделения на дашборде

• Декларативные рабочие процессы макета JSON

• Управление заголовком зоны дашборда через show_title: false в словарях макета

Рецепты и демонстрационные шаблоны

Их можно создать сегодня, но их следует рассматривать как рецепты или примеры, а не как первоклассные обязательства:

• Кольцевая диаграмма

• Леденцовая диаграмма (Lollipop)

• Пулевая диаграмма (Bullet)

• Bump-диаграмма

• Диаграмма «бабочка»

• Календарь

Рецептурные диаграммы намеренно представлены через единый инструмент configure_chart_recipe, чтобы публичная поверхность MCP не разрасталась по одному инструменту для каждого демонстрационного шаблона.

Это различие важно, потому что twilize не пытается стать зоопарком диаграмм или конкурировать с собственными инструментами разговорного анализа Tableau. Проект наиболее силен, когда он предоставляет надежный, автоматизируемый уровень создания книг.

Рабочий процесс, ориентированный на возможности

Если вы не уверены, относится ли что-то к стабильной поверхности SDK:

1. Используйте list_capabilities, чтобы проверить заявленную границу.

2. Используйте describe_capability, чтобы проверить конкретную диаграмму, кодировку или функцию.

3. Используйте analyze_twb или diff_template_gap перед тем, как пытаться реализовать демонстрационный шаблон.

Это позволяет согласовывать работу над новыми функциями с реальными границами продукта, а не с тем, что случайно появилось в примере книги.

Встроенная проверка

Структурная проверка

save() автоматически проверяет структуру TWB XML перед записью:

• Фатальные ошибки, такие как отсутствие <workbook> или <datasources>, вызывают TWBValidationError.

• Предупреждения, такие как отсутствие <view> или <panes>, записываются в журнал, но не блокируют сохранение.

• Проверку можно отключить с помощью editor.save("output.twb", validate=False) или editor.save("output.twbx", validate=False).

Проверка по схеме XSD

TWBEditor.validate_schema() проверяет книгу на соответствие официальной схеме Tableau TWB XSD (2026.1), размещенной в vendor/tableau-document-schemas/:

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

Та же проверка доступна как инструмент MCP:

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

Ошибки XSD носят информационный характер — сама Tableau создает книги, которые иногда отклоняются от схемы, — но повторяющиеся ошибки сигнализируют о структурных проблемах, которые стоит исправить.

Макеты дашбордов

Пользовательские макеты можно создавать программно с помощью вложенного словаря layout или через generate_layout_json для рабочих процессов MCP.

Пример на базе Hyper

Пример examples/hyper_and_new_charts.py использует извлечение Sample - EU Superstore.hyper, упакованное непосредственно в пакет (src/twilize/references/), и разрешает физическую таблицу Orders_* через Tableau Hyper API перед переключением подключения книги. Клонирование репозитория не требуется — установите с помощью pip install "twilize[examples]" и запустите напрямую.

Миграция книг

twilize включает подсистему миграции для переключения существующего .twb на новый источник данных — например, перенаправление книги, созданной на основе одного файла Excel, на другой Excel с другой схемой или миграция между языковыми вариантами одного и того же набора данных.

Как это работает

Миграция — это многошаговый рабочий процесс. Каждый шаг доступен как инструмент MCP и как функция Python:

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 — это удобная обертка, которая выполняет шаги 2–5 последовательно и автоматически приостанавливается, когда остаются только сопоставления полей с низкой степенью уверенности, возвращая warning_review_bundle для проверки человеком перед продолжением.

Пример на Python

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

При использовании twilize в качестве сервера MCP агент ИИ может запустить полный рабочий процесс:

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"

Выходные файлы

Завершенная миграция записывает три файла:

Параметр области действия (scope)

scope="workbook" мигрирует все рабочие листы. Передайте имя рабочего листа, чтобы ограничить миграцию одним листом.

Автономный пример

examples/migrate_workflow/ содержит шаблон .twb, оригинальный Excel Superstore, целевой Excel Superstore с китайской локалью и запускаемый скрипт:

python examples/migrate_workflow/test_migration_workflow.py

Структура проекта

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

Разработка

# 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

twilize поставляется с полным манифестом сервера MCP (mcp-server.json) — эквивалентом файла .trex расширения Tableau. Он объявляет: