MCP Toolbox 中的 Looker Conversational Analytics 预构建配置环境变量、权限与 ask_data_insights 工具全解析【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本篇技术指南聚焦开源项目 MCP Toolbox for Databases 中looker-conversational-analytics预构建配置Prebuilt Configuration说明如何通过--prebuilt参数一键装载 Looker 会话式数据分析能力详细讲解其环境变量、IAM 权限要求、三个内置工具的参数语义并结合仓库源码剖析ask_data_insights调用 Gemini Data Analytics API 的底层实现与流式响应处理机制。读完本文你将能独立配置、部署并理解该预构建工具集在 MCP 服务器中的完整工作方式。一、预构建配置是什么一条命令装载 Looker 会话式分析工具集MCP Toolbox 提供了一种名为Prebuilt Configuration预构建配置的启动方式将常用的「数据源配置 工具定义 工具集」预先打包为单个 YAML 文件并通过--prebuilt命令行参数在服务器启动时装载从而省去手工编写 config 文件的步骤。Looker Conversational Analytics 预构建配置的--prebuilt值为--prebuilt looker-conversational-analytics其对应的完整配置清单位于 internal/prebuiltconfigs/tools/looker-conversational-analytics.yaml文件由三段 YAML document 组成kind: source—— 定义一个名为looker-source、类型为looker的数据源kind: tool—— 定义三个工具ask_data_insights、get_models、get_exploreskind: toolset—— 定义一个名为looker_conversational_analytics_tools的工具集将上述三个工具聚合起来。从实现上看预构建机制通过go:embed将tools/*.yaml全部嵌入二进制并在启动时由 internal/prebuiltconfigs/prebuiltconfigs.go 读取见loadPrebuiltToolYAMLs文件名去掉.yaml后缀即为--prebuilt的取值键。这意味着looker-conversational-analytics这个名字并非硬编码而是由该 YAML 文件名自动派生。二、环境变量详解默认值与底层映射预构建配置中的 source 段使用${VAR}形式的环境变量引用支持${VAR:default}语法提供默认值。下表基于 looker-conversational-analytics.yaml 与 Looker 数据源实现 整理环境变量是否必需默认值说明LOOKER_BASE_URL是无Looker 实例的 URL对应base_url源码中标记为validate:requiredLOOKER_CLIENT_ID视认证模式空Looker API 的 Client ID当LOOKER_USE_CLIENT_OAUTHfalse时必填否则启动校验报错LOOKER_CLIENT_SECRET视认证模式空Looker API 的 Client Secret要求同上LOOKER_VERIFY_SSL否true是否校验 SSL 证书置为false时跳过 TLS 校验并输出安全警告日志LOOKER_USE_CLIENT_OAUTH否false是否使用 OAuth终端用户授权替代 client_id/client_secret 认证LOOKER_PROJECT是使用本工具时空用于 Conversational Analytics 的 GCP Project工具调用时若为空会直接报错LOOKER_LOCATION否us源码默认用于 Conversational Analytics 的 GCP Location需要特别说明的是YAML 配置中与工具运行相关的默认值大多定义在数据源初始化逻辑里。查看 looker.go 的newConfig可知当配置未显式给出时源码会填充以下默认值SslVerification: true对应verify_sslTimeout: 600sLooker API 请求超时预构建 YAML 中亦显式声明为600sUseClientOAuth: falseShowHiddenModels / ShowHiddenExplores / ShowHiddenFields: trueget_models、get_explores等元数据工具会包含隐藏模型/探索/字段Location: usSessionLength: 1200三、认证模式Client OAuth 与终端用户 OAuth 二选一Looker 数据源的认证行为由LOOKER_USE_CLIENT_OAUTH决定这一分支逻辑体现在 looker.go 的Initialize中false默认要求必须同时提供LOOKER_CLIENT_ID与LOOKER_CLIENT_SECRET缺失任一字段都会返回client_id and client_secret need to be specified错误。此时服务器用服务账号凭据换取 Looker 会话并调用Me()接口做连通性验证日志会打印登录用户信息。true走 Google Cloud 终端用户授权路径每个 MCP 请求携带用户 access token源码中UseClientAuthorization()返回true工具会把请求中的 Bearer Token 透传给 Conversational Analytics API。对于 Conversational Analytics 场景认证凭据最终会打包进 API 请求的credentials.oauth字段client OAuth 模式填入clientId/clientSecret终端用户 OAuth 模式填入access_token见工具实现的Invokelookerconversationalanalytics.go。四、权限要求Looker 账号与三项 IAM 角色预构建配置文档明确了使用 Conversational Analytics 所需的三层权限Looker 账号需要具备访问目标 LookML 模型models、探索explores与数据的权限Looker Instance Userroles/looker.instanceUser访问 Looker 实例的 IAM 角色Gemini for Google Cloud Userroles/cloudaicompanion.user访问 Conversational Analytics 的 IAM 角色Gemini Data Analytics Stateless Chat User (Beta)roles/geminidataanalytics.dataAgentStatelessUser访问 Conversational Analytics 的 IAM 角色。从源码角度可印证第 3、4 项与 API 调用的对应关系工具在调用前通过GoogleCloudTokenSourceWithScope申请https://www.googleapis.com/auth/cloud-platform作用域的令牌lookerconversationalanalytics.go随后向 Gemini Data Analytics 的 chat 端点发起请求数据源初始化时同样使用geminidataanalytics.DefaultAuthScopes()查找默认凭据looker.go。五、三个内置工具职责、参数与调用链预构建配置聚合了三个工具由工具集looker_conversational_analytics_tools统一暴露1.ask_data_insights—— 会话式数据问答核心工具类型为looker-conversational-analytics其实现位于 internal/tools/looker/lookerconversationalanalytics/lookerconversationalanalytics.go。该工具接受两个参数参数类型说明user_query_with_contextstring向 Conversational Analytics 提出的自然语言问题可包含对话历史与系统指令上下文explore_referencesarray15 个元素可被查询以回答问题的 explore 引用列表形如[{model: 模型名, explore: 探索名}, ...]工具描述中特别要求LLM 在使用前应先通过get_models与get_explores发现可用的模型与探索再将 15 个「model explore」组合作为explore_references传入。参数校验的健壮性由于explore_references声明为自由格式 map 数组模型可能提供结构异常的数据。源码中的parseExploreReferenceslookerconversationalanalytics.go对每个元素逐一校验非对象元素、缺失model/explore字段、字段非字符串等情况都会返回明确的 Agent 错误而非触发 panic。对应的单元测试 lookerconversationalanalytics_internal_test.go 覆盖了 5 类异常形状的输入。底层调用链Invokelookerconversationalanalytics.go校验 source 兼容性并确认LOOKER_PROJECT已配置为空则返回project must be defined for source to use with looker-conversational-analytics tool获取cloud-platform作用域的令牌源通过GetLookerSDK获得 Looker SDK并调用GetHostURL动态解析实例公共主机 URL——该函数优先通过 LookerversionsAPI 获取web_server_url并缓存 10 分钟失败时回退到base_urllooker.go组装 JSON payloadmessages用户问题、inlineContext系统指令与 datasource references、credentials认证凭据、clientIdEnum向{GDA-ENDPOINT}/v1/projects/{project}/locations/{location}:chat发起 POST 流式请求location来自LOOKER_LOCATION默认us超时设为 330 秒流式解析响应getStream按消息类型分派处理。输出约束工具内置instructions常量要求模型回答「先给支撑数据、再给结论」全文纯文本且严格禁止生成图表、图形、图片等任何可视化内容。流式响应处理API 返回 JSON 数组形式的流式消息每条消息按SystemMessage细分处理lookerconversationalanalytics.go消息类型处理结果Text汇总为Answer字段Schema输出Questionschema 查询或Schema Resolved已解析的 datasource 及其 model/explore/实例 URIData输出Retrieval Query生成的 Looker 查询model、explore、fields、filters、sorts、limit或Data Retrieved结果行Analysis输出Analysis含 planner reasoning、生成代码、执行输出、自然语言结论等Error输出Error.Message2.get_models—— 获取 LookML 模型列表类型为looker-get-models无需参数。返回 Looker 实例中可用的 LookML 模型及其name、label等元数据。LookML 模型定义了可查询的数据结构与关系其输出是后续调用get_explores、ask_data_insights的基础。3.get_explores—— 获取指定模型中的探索列表类型为looker-get-explores需要一个必填参数model_name来自get_models的模型名。探索Explore是对数据的精选视图通常关联多张表以支持某一主题域的聚焦分析返回结果包含探索的name与label。工具配置的可复制示例参考预构建 YAML 与工具参考文档一个独立的ask_data_insights工具声明如下kind: tool name: ask_data_insights type: looker-conversational-analytics source: looker-source description: | Use this tool to ask questions about your data using the Looker Conversational Analytics API. You must provide a natural language query and a list of 1 to 5 model and explore combinations (e.g. [{model: the_model, explore: the_explore}]). Use the get_models and get_explores tools to discover available models and explores.其中各字段含义type固定为looker-conversational-analytics注意工具参考文档字段表中写作lookerca-conversational-analytics但从预构建 YAML与源码常量resourceType looker-conversational-analytics看实际生效值应为looker-conversational-analytics参考时需以源码为准source为工具所依赖的数据源名称description是传给 LLM 的工具说明用于引导模型正确调用。六、测试验证配置解析与参数校验的守护仓库为该预构建配置提供了两层测试保障配置解析测试lookerconversationalanalytics_test.go通过TestParseFromYamlLookerConversationalAnalytics验证最小 YAML 声明kind/name/type/source/description能被正确反序列化为Config结构确认type与source字段为必填、description缺失会触发初始化错误参数校验测试lookerconversationalanalytics_internal_test.goTestParseExploreReferences验证合法引用被正确解析model/explore/lookerInstanceUri 字段完整、空输入返回空切片以及 5 类异常输入均返回错误而非 panic。七、小结与使用建议looker-conversational-analytics预构建配置以「一个 flag、七个环境变量、三项 IAM 角色」为最小落地单元将 Looker 元数据发现get_models/get_explores与 Gemini 驱动的会话式问答ask_data_insights封装为开箱即用的 MCP 工具集。部署时的关键检查点如下确认LOOKER_BASE_URL指向可访问的 Looker 实例并按认证模式配置LOOKER_CLIENT_ID/LOOKER_CLIENT_SECRET或开启LOOKER_USE_CLIENT_OAUTH为服务账号授予roles/looker.instanceUser、roles/cloudaicompanion.user、roles/geminidataanalytics.dataAgentStatelessUser并确保LOOKER_PROJECT指向正确的 GCP 项目LOOKER_LOCATION默认us使用--prebuilt looker-conversational-analytics启动后让 LLM 先调用get_models→get_explores完成发现再携带 15 个 model/explore 引用调用ask_data_insights。需要说明的是Conversational Analytics 依赖 Google Cloud 侧的 Gemini Data Analytics 能力与对应 Beta 角色实际可用性以你的 GCP 项目授权与区域支持情况为准本文所述命令、参数与默认值均以当前仓库版本预构建配置、Looker 数据源、工具实现为准。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考