biztory-tableau-knowledge-mcp

biztory-tableau-knowledge-mcp

让任何 AI 助手都能利用你的 Tableau 知识图谱。
按含义搜索、追踪数据沿袭和影响，并补充业务背景。

biztory-tableau-knowledge-mcp 将你站点的 Tableau Knowledge Graph API 转换为 23 个 MCP 工具，让 AI 助手（Claude、Cursor、VS Code、Cline 等）可以用自然语言操作图谱：

• “哪些字段表示收入？它们来自哪里？”
• “如果 Superstore 数据源发生变化，会影响哪些工作簿和仪表板？”
• “Profit 关联了哪些业务背景？添加：“Profit 扣除退货后计算，单位为 EUR。””
• “我们的图谱健康状况如何？影响最大的五项修复措施是什么？”
• “将 Superstore 导出为 Apache Ossie，以便我们将其迁移到 Snowflake。”
• “为 P&L 仪表板编写 Business Preferences。”
• “将此站点上的所有 Superstore 数据源添加到 Sales 图谱。”
• “询问 Tableau 的 Agent 图谱中有多少个数据源，并核实它的回答。”

它提供 九个读取工具（语义搜索、节点查询、边查询、血缘关系、影响分析、数据源、语义上下文、图谱健康状况和连接探测），以及 四个用于语义上下文的写入工具。语义上下文是让人和 AI 都能有效使用图谱的业务陈述（其中一个工具可将文档转换为上下文）。还有五个工具用于管理图谱本身：添加和移除数据源与工作簿、创建和更新图谱，以及向 Tableau 自带的 Agent 提问来测试它的回答。这些工具通过 Tableau Knowledge Web 应用背后的 API 调用，而 Tableau 并未公开其文档。另外还有四个工具通过 Apache Ossie 迁移语义层（该标准前身为 Open Semantic Interchange，简称 OSI），Snowflake、dbt、Power BI、Databricks、Tableau Next 等产品都可与之进行格式转换。还有一个工具可逐行检查 Business Preferences 文件，对照 Agent 实际会看到的字段进行核验。

实际演示

_{来自测试站点的真实工具结果回放，已移除站点专属名称。使用 docs/images/render_demo_gifs.py 重新生成。}

与众不同之处

• 按含义查询，而不是按 ID 查询。 每个读取工具都接受节点 ID 或 描述（“净销售额字段”）。描述通过图谱自身的语义搜索进行解析，回答会说明选中了哪个节点、匹配分数以及其他候选项，因此错误猜测会显现出来，而不会悄无声息地发生。
• 提供答案，而不是载荷。 impact_analysis 按类型汇总并统计所有下游内容；lineage 会补充节点和边的计数；graph_health 会将数百条建议缩减至最重要的几条，同时保留所有总数。
• 错误会告诉模型下一步该怎么做。 Tableau 的错误代码会转化为具体步骤（site_not_entitled → 管理员必须启用 Knowledge；no_active_graph → 传入 graph_id；没有嵌入器 → 使用精确 ID），并保留 trace_id 以便寻求支持。遇到速率限制时会根据 Retry-After 重试。
• 值得信赖的写入。 只有语义上下文和图谱的数据源可以写入（后者通过 Tableau Knowledge 未公开的 Web 应用 API 实现，该 API 可能随时变更）。写入工具要求提供精确 ID（模糊匹配绝不会决定写入目标），会在发送前进行验证，并提供诚实的 MCP 注释，让客户端先征求确认；delete_semantic_context 会返回已删除的内容。
• 迁移语义层。 export_to_ossie 会将已发布的数据源转换为经过验证的 Ossie 模型；对于可以精确转换的 Tableau 计算，会将其转换为可移植的 SQL，并提供其余内容的损失报告。import_from_ossie 会将任意 Ossie 模型中的描述、同义词和定义导入 Tableau Knowledge，并先提供可供审核的计划。
• 轻量且安全可靠。 仅使用 Stdio（无入站端口），密钥仅从环境变量读取，强制使用 HTTPS，拒绝重定向，对 ID 进行编码，使其绝不可能到达其他端点，并对解析器进行模糊测试；运行时依赖仅有两项：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，一行命令：

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 的转换器；本服务基于 Knowledge 图谱构建了一个转换器，因此业务上下文也能一并迁移。

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> 上下文。匹配时优先使用上次导出中的 ID，然后再使用名称。对于 API 仅接受图谱级上下文的网站，相同语句会合并为一个全局 ossie:<model> 上下文，并为每条语句添加描述对象前缀（Superstore / Sales: Also known as: revenue.）；scope 可强制指定为 node 或 global。首次调用会返回计划（创建／更新／不变，以及所有未匹配项），只有设置 apply=true 后才会写入任何内容。Tableau 中已有的语句会被跳过，因此重新导入未编辑过的导出内容不会写入任何内容。

斜杠命令。 此服务附带 MCP 提示词，可引导完成每个工作流：将数据源导出到 Ossie、将 Ossie 模型导入 Tableau Knowledge 和 编写业务偏好设置。在 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）会提供精确命令，并固定到经过审核的提交。待这些转换器发布后，此服务会将它们封装为工具。

编写可行的 Business Preferences

Business Preferences 文件是一组 # rule 行，Tableau 的 Agent 会在回答前读取这些规则：Tableau Cloud 上每个仪表板对应一个文件（50 条规则，8,000 个字符），Tableau Next 上每个语义模型对应一个文件（30,000 个字符）。它会影响 Agent 如何规划答案，因此每一行都必须是它能遵循的规则。check_business_preferences 汇集了实测经验，内容来自 Business Preferences in Tableau Cloud: What We Learned（Celia Fryar，XeoMatrix，2026 年 9 月）：

• Tableau 会静默忽略的格式错误：# 前有空格，或其后没有空格。
• 限制：预留余量；不要添加标题、空行或重复规则，也不要出现矛盾。
• 会误导 Agent 的措辞：没有“仅使用此值”字样的阈值、渗入查询的格式规则、对话式语句、可能被过度解读的缺失项、含糊的排序和平均值。缺少两条基准规则时，它还会建议补上（保持查询为数值型，如实报告失败）。
• 实时检查字段名称：提供仪表板后，每个 [Field] 都必须是 Agent 能看到的可见标题，并附上“你是否想找”的建议。它还会标记工作簿问题：重复字段（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。

提示词示例

• "Use server_info：此站点有哪些图表，哪个是主图？"
• "找到表示收入的字段，然后展示最佳匹配项的沿袭关系。"
• "对 Superstore 数据源运行 impact_analysis：哪些工作簿和仪表板依赖它？"
• "Profit 字段附带了哪些语义上下文？"
• "显示图表的健康评分和五条高严重性建议，以及它们针对的节点。"
• "向 Profit 字段添加一条说明：'Profit is calculated after returns and reported in EUR.'"

架构

此服务通过 stdio 使用 MCP 与客户端通信，并通过 HTTPS 连接 Tableau：它使用你的 PAT 登录以获取 X-Tableau-Auth 会话（过期时会刷新），然后调用 /api/v1/knowledge。不会存储任何内容；每个回答都是实时获取的。

你应该了解的 API 特性

• 搜索按含义进行。 分数是相对值；最高分约为 0.4-0.5 时，仍可能对应正确节点，因此请检查其他候选项。
• 沿袭关系反映依赖，而非包含关系。 单个字段的沿袭关系通常只有它自身；list_edges 会显示它所属的表。
• 上下文搜索目前不会按文本筛选。 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；此服务会采用退避策略重试，但建议优先使用 lineage 和 impact_analysis，而不是大量调用 get_node。

安全性

• 写入仅限语义上下文，使用精确 ID，发送前会进行验证，并附加标注，以便客户端先行询问。Viewer 或 Explorer PAT 实际上会使服务处于只读状态。
• 仅限本地和 stdio。 不会开放入站网络端口。
• 密钥仅从环境变量读取。 绝不通过工具参数传递、绝不记录日志、绝不返回。
• 凭据只会发送到你的 Tableau 主机。 必须使用 HTTPS，证书会经过验证，并且会拒绝重定向。
• 无法通过 ID 注入内容。 节点和上下文 ID 会编码为单个路径段；发送前会根据 Tableau 的模式检查 graph_id。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.4.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 会额外运行一轮测试，创建、更新并删除一个临时上下文。

CI 中也会运行相同的检查（Linux/macOS/Windows，Python 3.10 至 3.13）：ruff check、ruff format --check、mypy --strict，以及设有覆盖率下限的 pytest。CodeQL 会扫描每次推送，OpenSSF Scorecard 每周运行一次，模糊测试任务（fuzz/）会攻击不可信输入解析器。此软件包包含 PEP 561 py.typed 标记文件。

欢迎贡献：请参阅 CONTRIBUTING.md 和 行为准则。

路线图

• 导出到 Apache Ossie，并从 Apache Ossie 导入（原名 OSI）
• 将 Ossie 转换器（Snowflake、dbt、Power BI、Databricks）封装为工具，待其发布到 PyPI 后实现
• Knowledge API 开放相关信息后，根据 Tableau 联接键生成 Ossie 关系
• 在本 README 中添加演示录制
• 可选地按会话缓存 server_info 和已解析节点

欢迎在 Discussions 中提出想法并投票。

许可证

MIT © Biztory。姊妹项目：tableau-graphql-mcp，用于通过 Tableau Metadata API 获取数据沿袭。