GuanMCP 使用指南
产品概述
GuanMCP 是连接企业 AI 助手和观远 BI 的服务。
接入后，员工可以在飞书 Aily、观远 DecideX、企业自研 AI 助手等入口中，用自然语言查询 BI 数据、查看指标口径、分析看板内容，或发起 ChatBI 问数和洞察分析。
例如：
员工在飞书 Aily 中问：" 昨天华东区销售额是多少？"
AI 助手会通过 GuanMCP 调用观远 BI 的查询能力。观远 BI 按这个员工自己的权限返回结果，AI 助手再把答案展示给员工。
员工不需要知道数据集 ID、卡片 ID，也不需要会写 SQL。AI 助手会根据问题选择并调用 GuanMCP 工具，GuanMCP 再执行对应的 BI 查询。
适用范围
典型业务问题
| 业务问题 | GuanMCP 可以让 AI 助手做什么 |
|---|---|
| " 这个指标是什么意思？" | 搜索指标，查看指标口径、负责人、可用维度和更新时间。 |
| " 昨天销售额是多少？" | 调用 ChatBI 或指标查询能力，返回当前用户有权限看到的数据。 |
| " 销售经营看板里用了哪些数据？" | 搜索页面和卡片，读取卡片配置、数据集来源和页面结构。 |
| " 这个数为什么下降？" | 调用 ChatBI 洞察或指标归因能力，分析变化原因。 |
| " 这个数据集有哪些字段？" | 查看数据集字段、字段类型、维度、度量和计算字段。 |
| " 我找不到某张报表。" | 在 BI 中搜索页面、卡片、数据集、ETL 等资源。 |
适用场景
- 企业已经有 AI 助手，希望员工在原有入口直接问 BI 数据。
- 业务人员不熟悉 BI 操作，但需要查指标、找看板、看洞察。
- 企业希望统一权限，员工在 AI 助手里能看到什么数据仍由 BI 控制。
- 需要把观远 BI 的只读查询、指标、ChatBI 能力接入企业 AI 平台。
不适用场景
- 需要 AI 创建、修改、发布 BI 资源。请参考 GuanVis 使用指南 或 GuanCLI 使用指南。
- 需要 AI 修改 ETL。请参考 GuanETL 使用指南。
- 只是个人电脑上试用 BI 查询能力，还没有企业 AI 助手。建议先参考 GuanCLI 使用指南。
业务查询示例
业务用户提问：
帮我看一下本周华东区销售额为什么比上周下降。
AI 助手可能会通过 GuanMCP 完成这些动作：
- 搜索和「销售额」相关的指标或 ChatBI 主题。
- 确认当前用户有权限查看该指标或主题。
- 查询本周和上周华东区销售额。
- 按城市、门店、渠道或商品类目拆解变化。
- 汇总下降最明显的因素，并给出可追溯的数据来源。
用户看到的是一段业务解释；背后由 GuanMCP 负责调用观远 BI。
产品能力
与 GuanCLI 工具套件的区别
| 对比项 | GuanMCP | GuanCLI 工具套件 |
|---|---|---|
| 面向对象 | 企业 AI 助手和业务用户 | 本地 Agent、数据分析师、实施和开发人员 |
| 使用入口 | 飞书 Aily、DecideX、自研 AI 助手等 | 命令行或本地 Agent |
| 主要能力 | 让 AI 助手安全查询 BI 数据和指标 | 查询、分析、创建或修改 BI 资源 |
| 典型场景 | 员工在 AI 助手里问数 | Agent 在本地排查数据集、改卡片、改 ETL |
| 权限方式 | 每次请求识别真实用户，由 BI 判断权限 | 通常使用当前登录用户或本地配置用户 |
简单理解：GuanMCP 是给企业 AI 助手接入 BI 能力的；GuanCLI 工具套件是给本地 Agent 直接操作 BI 能力的。
支持的 BI 能力
| 内容 | 用户能问什么 |
|---|---|
| BI 能力探测 | 当前 BI 版本、运行模式、可用能力有哪些。 |
| 全局搜索 | 搜索卡片、仪表板、数据集、ETL 等 BI 资源。 |
| 数据集 | 查看字段结构、字段类型、维度、度量和计算字段。 |
| 页面和卡片 | 查看页面里有哪些卡片、卡片来自哪些数据集、图表配置是什么。 |
| 卡片数据 | 读取已保存卡片的只读数据结果。 |
| 轻量 SQL 查询 | 面向数据集执行只读查询。 |
| 指标平台 | 搜索指标、查看口径、查询指标数据。 |
| 指标树归因 | 查看指标树，做单维拆解或全维扫描。 |
| ChatBI | 列主题、问数、发起洞察分析、查看洞察报告。 |
GuanMCP 默认聚焦只读查询。它不创建、编辑、保存或发布 BI 资源。
接入说明
权限与安全边界
GuanMCP 不绕过观远 BI 权限。
- AI 助手能看到 GuanMCP 工具，不代表用户能看到所有 BI 数据。
- 每次查询都需要识别当前真实用户。
- 观远 BI 会根据该用户在 BI 中的权限返回数据。
- 正式接入时，不建议用一个固定账号代替所有员工查询。
- 用户在 AI 助手中能看到的数据，与其在观远 BI 中有权限查看的数据保持一致。
如果同一个问题由不同用户发起，返回结果可能不同。
接入准备
接入前建议先确认：
- 希望在哪个 AI 助手中使用，例如飞书 Aily、DecideX 或企业自研助手。
- 员工主要会问哪些问题，例如查指标、找看板、看数据集字段或做洞察。
- 哪些 BI 资源要开放给 AI 助手查询。
- 低权限用户、高权限用户分别应该看到什么数据。
- 是否需要先选一个部门或一个主题做试点。
- 是否已指定负责接入的管理员或运维同学。
接入完成后，建议用不同权限的测试账号分别提问，确认返回结果符合 BI 权限预期。
常见接入入口
| 文档或入口 | 适合对象 | 说明 |
|---|---|---|
| 飞书 Aily 对接 | Aily 管理员 | 在飞书 Aily 中配置自定义 MCP，让员工用自然语言查询观远 BI 数据。 |
| GuanMCP 部署指南 | 运维和平台管理员 | 部署 GuanMCP 服务，配置入口鉴权、用户身份传递、环境变量和 HTTP 验证。 |
| 观远 DecideX | 观远 AI 助手场景 | 员工在 DecideX 中调用观远 BI 的查询、指标和洞察能力。 |
| 企业自研 AI 助手 | 企业统一 AI 入口 | 企业将 GuanMCP 接入自研助手，让员工在统一入口访问 BI 能力。 |
常见问题
AI 助手能看到工具，但查不到数据
工具可见不等于用户有资源权限。请先确认该用户在观远 BI 中能否直接查看对应页面、卡片、数据集或指标。如果 BI 中也无法访问，需要由 BI 管理员补充权限。
SQL 查询报错
- 确认当前 BI 版本支持高级 SQL 功能。
- 确认数据集显示名称与 SQL 中使用的表名一致。
- 如果业务用户无法判断原因，请联系管理员查看对应查询限制和错误信息。
不同用户看到的结果不一致
GuanMCP 会按当前用户在观远 BI 中的权限返回数据。不同用户的数据权限、组织范围或行列权限不同，返回结果也可能不同。
飞书 Aily 中无法正常查询
请先确认 Aily 端已完成自定义 MCP 配置，并且当前用户的身份信息可以传递给观远 BI。具体配置可参考 对接飞书 Aily 使用指南。