biztory-tableau-knowledge-mcp

biztory-tableau-knowledge-mcp

Tableau のナレッジグラフを、あらゆる AI アシスタントで活用できます。
意味で検索し、リネージと影響をたどり、ビジネスコンテキストを追加できます。

biztory-tableau-knowledge-mcp は、サイトの Tableau Knowledge Graph API を17個の MCP ツールに変換します。これにより、AI アシスタント（Claude、Cursor、VS Code、Cline など）が自然な言葉でグラフを操作できます。

• 「売上を意味するフィールドはどれで、それらの由来は何ですか？」
• 「Superstore データソースが変更された場合、影響を受けるワークブックやダッシュボードはどれですか？」
• 「Profit に関連付けられているビジネスコンテキストは何ですか？『Profit は返品を差し引いた後の金額で、通貨は EUR です』を追加してください。」
• 「グラフの健全性はどの程度ですか？影響の大きい修正を5つ教えてください。」
• 「Superstore を Apache Ossie にエクスポートして、Snowflake に移行できるようにしてください。」
• 「P&L ダッシュボードの Business Preferences を記述してください。」 9 つの読み取りツール（セマンティック検索、ノード検索、エッジ、リネージュ、影響分析、ソース、セマンティックコンテキスト、グラフの健全性、接続プローブ）と、グラフを人や AI にとって有用にするビジネス上の記述であるセマンティックコンテキストだけを扱う3 つの書き込みツールを提供します。さらに、Snowflake、dbt、Power BI、Databricks、Tableau Next などが相互変換に使用するオープン標準、Apache Ossie（旧 Open Semantic Interchange、OSI）を介してセマンティックレイヤーを移行する 4 つのツールがあります。また、エージェントが実際に参照するフィールドと照らし合わせて、Business Preferences ファイルを行ごとに検証するツールもあります。

他とは異なる点

• ID ではなく意味で検索できます。 すべての読み取りツールには、ノード ID または説明（「純売上フィールド」など）を指定できます。説明はグラフ独自のセマンティック検索で解決され、選択されたノード、マッチスコア、次点候補が回答に示されるため、誤った推測があれば隠れずに分かります。
• ペイロードではなく、回答を返します。 impact_analysis は下流のすべての情報をタイプ別にグループ化して件数を集計し、lineage はノード数とエッジ数を追加します。graph_health は候補を上位のものに絞りながら、合計数をすべて保持します。
• エラーから、モデルが次にすべきことが分かります。 Tableau のエラーコードは具体的な手順に変換されます（site_not_entitled → 管理者が Knowledge を有効にする必要があります。no_active_graph → graph_id を渡します。埋め込みモデルがない場合 → 正確な ID を使います）。サポート用の trace_id も保持されます。レート制限が発生した場合は、Retry-After に従って再試行します。
• 信頼できる書き込み。 書き込み可能なのはセマンティックコンテキストだけです。書き込みツールには正確な ID が必要です（あいまい一致によって書き込み先が決まることはありません）。送信前に検証を行い、クライアントが事前に確認できるよう、適切な MCP アノテーションを付与します。また、delete_semantic_context は削除した内容を返します。
• セマンティックレイヤーを移行できます。 export_to_ossie は公開済みデータソースを検証済みの Ossie モデルに変換します。正確に変換できる Tableau の計算式は移植可能な SQL に変換し、それ以外はすべて損失レポートに記録します。import_from_ossie は、任意の Ossie モデルから説明、同義語、定義を Tableau Knowledge に取り込みます。取り込み前にレビュー可能なプランを提示します。
• 軽量かつ堅牢です。 Stdio のみ（受信ポートなし）、シークレットは環境変数からのみ取得、HTTPS を強制、リダイレクトを拒否、ID をエンコードして別のエンドポイントに届かないようにし、パーサーをファジングで検証しています。実行時の依存関係は 2 つだけです。MCP SDK と PyYAML（HTTP には標準ライブラリの urllib を使用）。

要件

Tableau Knowledge は Tableau Cloud の機能です（2026 年 9 月以降、Tableau+ ライセンスが必要）。Tableau Server では利用できません。ユーザーは誰でも、コンテンツ権限でフィルタリングされたグラフを読み取れます。セマンティックコンテキストの書き込みには Creator ロールが必要です。

クイックスタート

uv（curl -LsSf https://astral.sh/uv/install.sh | sh）と Tableau の個人用アクセストークンが必要です。

Claude Code、1 行で設定：

claude mcp add tableau-knowledge \
  -e TABLEAU_SERVER=https://10ax.online.tableau.com \
  -e TABLEAU_SITE_CONTENT_URL=YourSite \
  -e TABLEAU_PAT_NAME=my-token \
  -e TABLEAU_PAT_SECRET=the-full-secret \
  -- uvx biztory-tableau-knowledge-mcp

これで完了です。uvx が PyPI からパッケージを取得し、分離された環境で実行するため、クローンもインストールも不要です。続けて、次のように尋ねてください。「server_info を使って、自分のサイトにあるグラフを教えてください。」

設定

すべての設定は環境変数で行います（クライアントの env ブロックに設定し、コマンドラインには設定しないでください）。

¹ PAT（TABLEAU_PAT_NAME ＋ TABLEAU_PAT_SECRET）または TABLEAU_AUTH_TOKEN を指定してください。

{
  "mcpServers": {
    "tableau-knowledge": {
      "command": "uvx",
      "args": ["biztory-tableau-knowledge-mcp"],
      "env": {
        "TABLEAU_SERVER": "https://10ax.online.tableau.com",
        "TABLEAU_SITE_CONTENT_URL": "YourSite",
        "TABLEAU_PAT_NAME": "my-token",
        "TABLEAU_PAT_SECRET": "the-full-secret"
      }
    }
  }
}

node 引数には、ノード ID または平易な言葉による説明を指定できます。グラフを対象とするすべてのツールでは、省略可能な graph_id も指定できます。

書き込みツールには readOnlyHint: false が付記されています（更新、削除、インポートには destructiveHint: true も付記されています）。そのため、クライアントは各ツールの実行前に確認を求めることができます。Tableau が管理する（SEMANTIC_CONTEXT_EXTERNAL）コンテキストは読み取り専用です。

Apache Ossie でセマンティックレイヤーを移行する

Apache Ossie（インキュベーション中。旧称 Open Semantic Interchange）は、セマンティックモデル向けのベンダー中立な YAML 標準です。従来の Tableau 用コンバーターは存在しませんでした。このサーバーはナレッジグラフを基盤として構築されたコンバーターで、ビジネスコンテキストも引き継ぎます。

Tableau → Ossie（export_to_ossie）：

エクスポートでは出力を検証し、losses リストを返します。Knowledge には物理テーブルのパスや結合キーがないため、source と relationships を補う必要があります。INCLUDE/EXCLUDE LOD、テーブル計算、パラメーター、一部の関数は Tableau 専用のまま残り、それぞれレポートに記載されます。

Ossie → Tableau Knowledge（import_from_ossie）：Knowledge API はセマンティックコンテキストを書き込めるため、Ossie モデルはその形で取り込まれます。説明、ai_context の指示、同義語（「別名…」）、質問例、メトリック定義は、対応するノードに書き込まれます。各ノードには ossie:<model> コンテキストが 1 つずつ作成されます。対応付けには、まず以前のエクスポートで使用した ID を使い、次に名前を使います。API 経由ではグラフ全体のコンテキストしか受け付けないサイトでは、同じ記述が 1 つのグローバルな ossie:<model> コンテキストになり、それぞれに説明対象が前置されます（Superstore / Sales: またの名を revenue。）。scope を指定すると node または global を強制できます。最初の呼び出しでは、計画（作成／更新／変更なし、および対応付けできなかった項目）が返され、apply=true にするまで何も書き込まれません。Tableau にすでに存在する記述はスキップされるため、編集していないエクスポートを再インポートしても、何も書き込まれません。

スラッシュコマンド。 サーバーには、各ワークフローを案内する MCP プロンプトが付属しています。データソースを Ossie にエクスポート、Ossie モデルを Tableau Knowledge にインポート、ビジネス設定を書き込む の 3 つです。Claude Code では、/mcp__tableau-knowledge__export_datasource_to_ossie と /mcp__tableau-knowledge__import_ossie_into_tableau_knowledge として表示されます（サーバー名には選択した名前が使われます）。

他のプラットフォームへの展開。 Snowflake、dbt、Power BI、Databricks、Tableau Next、Cube、ThoughtSpot、Omni、Sigma などに対応するコンバーターがあります。まだ PyPI には公開されていないため、ossie_guide（トピック converters）で、レビュー済みのコミットに固定された正確なコマンドを確認できます。公開後、サーバーはそれらをツールとしてラップします。

効果的なビジネス設定の作成

ビジネス設定ファイルは、Tableau のエージェントが回答前に読み込む # rule 行のリストです。Tableau Cloud ではダッシュボードごとに 1 ファイル（50 ルール、8,000 文字）、Tableau Next ではセマンティックモデルごとに 1 ファイル（30,000 文字）を使用します。エージェントが回答を 計画する 方法を形作るため、各行はエージェントが実行できる内容でなければなりません。check_business_preferences には、Business Preferences in Tableau Cloud: What We Learned（Celia Fryar、XeoMatrix、2026 年 9 月）で得られた、実地検証済みの教訓が組み込まれています。

• Tableau が黙って無視する書式の誤り：# の前にスペースがある、# の後にスペースがない。
• 余裕を持たせた上限：見出し、空行、重複、矛盾は避けます。
• エージェントを誤解させる表現：「この値のみを使用」と書かれていないしきい値、クエリに漏れ込む書式ルール、会話調の行、過剰に解釈される可能性のある不在の記述、曖昧な並べ替えや平均値などです。また、欠けている場合は、基本となる 2 つのルール（クエリを数値のまま保つ、正直に失敗する）も提案します。
• ライブで確認するフィールド名：ダッシュボードを指定すると、すべての [Field] がエージェントに表示されるキャプションであることを確認し、「もしかして」の候補を提示します。ワークブックの問題（重複した Account ID (Account)、汎用的な Amount、ヘルパーフィールド）にもフラグを立てます。

write_business_preferences プロンプトは、プロセス全体を実行します。実際のキャプションを収集し、用語、しきい値、ポリシーについて質問したうえで、問題がなくなるまで草案の作成と確認を繰り返し、アップロード後に公開する手順とテストのアドバイスを含む v1 を返します。ルールブック全体を表示するには、テキストを指定せずに check_business_preferences を呼び出してください。

説明がノードになる仕組み

# illustrative
"the net sales field"
   │  1. exact lookup: GET /nodes/{id}           → found? use it, no guessing
   │  2. not an id: semantic search (top 4)      → best match + runners-up
   ▼
{ "id": "field:…:Net Sales", …,
  "resolution": { "match": {"name": "Net Sales", "type": "FIELD", "score": 0.82},
                  "alternatives": [ … ],
                  "note": "Not an exact id: resolved by semantic search …" } }

モデルにはスコアと代替候補が表示されるため、あなたに確認するか、代替候補の ID を指定して再試行できます。書き込みツールではこの手順全体を省略し、正確な ID が必要です。

プロンプトの例

• 「server_info を使ってください。このサイトにはどのグラフがあり、プライマリはどれですか？」
• 「収益を意味するフィールドを見つけて、最適な候補のリネージを表示してください。」
• 「Superstore データソースで impact_analysis を実行してください。これに依存するワークブックとダッシュボードはどれですか？」
• 「Profit フィールドには、どのようなセマンティックコンテキストが付与されていますか？」
• 「グラフの健全性スコアと、重要度の高い 5 件の提案を、対象ノードとともに表示してください。」
• 「Profit フィールドに次のステートメントを追加してください：『Profit は返品後に計算され、EUR で報告されます。』」

アーキテクチャ

サーバーはクライアントとは stdio 経由で、Tableau とは HTTPS 経由で MCP を介して通信します。PAT でサインインして X-Tableau-Auth セッションを取得し（期限切れ時に更新）、その後 /api/v1/knowledge を呼び出します。データは保存されず、回答はすべてライブデータに基づきます。

API について知っておくべきこと

• 検索は意味に基づきます。 スコアは相対値です。上位スコアが 0.4～0.5 程度でも正しいノードである可能性があるため、代替候補も確認してください。
• リネージは包含関係ではなく依存関係をたどります。 単一フィールドのリネージは、多くの場合そのフィールドだけです。list_edges を使うと、そのフィールドを HAS しているテーブルを確認できます。
• コンテキスト検索では、まだテキストによる絞り込みはできません。 search_semantic_contexts ではノードまたは is_global で絞り込みます。ステートメントを意味で検索するには search_nodes を使ってください。
• 不明な ID に対する動作はエンドポイントによって異なります。 API のリネージは不明な ID に対して空のグラフを返しますが、このサーバーは先にノードを解決するため、常に明確なエラーが返されます。
• 削除は冪等です。 不明な ID を削除しても、何も起きずに成功します。
• サイトによっては、グラフ全体に適用されるコンテキストのみを受け付けます。 ノードに関連付けられたコンテキストの作成は、node_semantic_context_disabled（「ノードスコープのコンテキストは Tableau によって管理され、取り込みを通じて反映されます」）で失敗することがあります。BiztoryPulse はこの動作をします。is_global=true を使い、ステートメント内でフィールド名を指定してください。import_from_ossie は自動的にこの方法にフォールバックします。
• API にはレート制限があります。 大規模なグラフをノードごとにクロールすると HTTP 429 が発生します。サーバーはバックオフして再試行しますが、多数の get_node 呼び出しよりも lineage と impact_analysis を優先してください。

セキュリティ

• 書き込みはセマンティックコンテキストに限定されます。 正確な ID を指定し、送信前に検証され、クライアントが確認を求められるよう注釈が付けられています。Viewer または Explorer の PAT を使用すると、実質的にサーバーは読み取り専用になります。
• ローカル環境および stdio のみです。 外部から接続可能なネットワークポートは開きません。
• シークレットは環境変数からのみ取得します。 ツール引数には含めず、ログにも記録せず、返却もしません。
• 認証情報の送信先は Tableau ホストのみです。 HTTPS を必須とし、証明書を検証し、リダイレクトは拒否します。
• ID を介したインジェクションは発生しません。 Node ID と context ID はそれぞれ 1 つのパスセグメントとしてエンコードされます。graph_id は送信前に Tableau のパターンに照らして検査されます。信頼できない入力を扱う両方のパーサーは CI でファジングされています。
• YAML は安全に解析されます。 Ossie ドキュメントは yaml.safe_load（タグやコードなし）で処理され、サイズ上限は 5 MB です。validate_ossie と ossie_guide は Tableau に接続しません。
• 検証可能なリリースです。 すべての GitHub リリースに Sigstore 署名と CycloneDX SBOM が付属し、PyPI へのアップロードには Trusted Publishing を使用します。
• 本番環境ではバージョンを固定してください：uvx biztory-tableau-knowledge-mcp==0.3.0。

脅威モデル、データの取り扱い、脆弱性の開示ポリシー、リリースの検証方法については、SECURITY.md を参照してください。

トラブルシューティング

MCP Inspector でサーバーを直接検査できます：

npx @modelcontextprotocol/inspector uvx biztory-tableau-knowledge-mcp

開発

git clone https://github.com/biztory/biztory-tableau-knowledge-mcp && cd biztory-tableau-knowledge-mcp
uv sync --all-extras
uv run biztory-tableau-knowledge-mcp                   # run from source (needs the env vars above)
uv run pytest --cov=biztory_tableau_knowledge_mcp      # tests + coverage (offline; no Tableau needed)
uv run ruff check . && uv run ruff format --check . && uv run mypy

ツールのテストは、インプロセスの Knowledge API のフェイク（tests/conftest.py）に対して実際のクライアントを通じて実行されるため、URL の組み立て、ID のエンコード、エラーのマッピングがすべて検証されます。ライブテストはオプトイン方式です。TABLEAU_LIVE=1 で読み取り専用テストを実行し、TABLEAU_LIVE_WRITE=1 を指定すると、自ら作成した一時的なコンテキスト 1 件を作成、更新、削除する一連のテストも追加されます。

同じチェックを CI でも実行します（Linux/macOS/Windows、Python 3.10 から 3.13）：ruff check、ruff format --check、mypy --strict、およびカバレッジ下限を設定した pytest です。CodeQL はすべての push をスキャンし、OpenSSF Scorecard は毎週実行され、ファジングジョブ（fuzz/）は信頼できない入力を扱うパーサーを検証します。このパッケージには PEP 561 の py.typed マーカーが含まれています。

コントリビューションを歓迎します：CONTRIBUTING.md と Code of Conduct をご覧ください。

ロードマップ

• Apache Ossie（旧 OSI）へのエクスポートと Apache Ossie からのインポート
• Ossie コンバーター（Snowflake、dbt、Power BI、Databricks）が PyPI で公開されたら、ツールとしてラップする
• Knowledge API で公開されたら、Tableau の結合キーから Ossie のリレーションシップを作成する
• この README にデモ動画を追加する
• server_info と解決済みノードのセッションごとの任意のキャッシュ

アイデアや投票を Discussions で歓迎します。

ライセンス

MIT © Biztory。関連プロジェクト：tableau-graphql-mcp（Tableau Metadata API を利用したリネージュ管理）。