MCP Toolbox 中 Looker Conversational Analytics 工具实战指南:让 Agent 用自然语言直接提问 Looker 数据

MCP Toolbox 中 Looker Conversational Analytics 工具实战指南:让 Agent 用自然语言直接提问 Looker 数据 MCP Toolbox 中 Looker Conversational Analytics 工具实战指南让 Agent 用自然语言直接提问 Looker 数据【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox导读looker-conversational-analytics是 MCP Toolbox for Databases 中面向 Looker 的专用工具它允许 LLM Agent 以自然语言向 Looker 数据提问由 Looker 的 Conversational Analytics会话式分析API 负责语义解析、查询生成与数据检索。本指南以 官方工具文档 为主体结合 预置配置、Looker Source 文档 与 源码实现 展开读完你将掌握该工具的两个核心参数及其数据形态、在 MCP Toolbox 中的完整配置步骤、GCP 侧的前置条件API 开通与 IAM 权限以及底层调用链与流式响应结构。工具概览一句话读懂它做什么looker-conversational-analytics的核心能力是让 LLM 直接向 Looker 数据提问。与传统先由 Agent 探索 schema、再拼装 LookML 查询的路径不同该工具把问题交给 Conversational Analytics 系统由它自行理解语义、选择合适的 explore、执行查询并返回结果。从源码看它在 MCP Toolbox 中注册的资源类型为const resourceType string looker-conversational-analytics参见 lookerconversationalanalytics.go。该工具本身不直接连接数据库而是充当 MCP Toolbox 与 Looker Conversational Analytics API 之间的桥接层它接收用户问题与 explore 引用构造 GDAGemini Data Analytics会话请求再将流式响应整理成结构化的多段结果返回给 Agent。参数详解工具接受的两个入参根据 官方工具文档该工具接受两个参数user_query_with_context向 Conversational Analytics 系统提出的问题。这是一个字符串参数可携带对话历史与系统指令上下文。源码中的定义为userQueryParameter : parameters.NewStringParameter(user_query_with_context, The users question, potentially including conversation history and system instructions for context.)explore_references用于回答问题的 explore 列表数量限制为 1 到 5 个每个元素的形式为[{model: model name, explore: explore name}, ...]。这是一个数组参数元素是自由形式的 map源码中定义如下exploreRefsParameter : parameters.NewArrayParameter( explore_references, An Array of at least one and up to 5 explore references like [{model: MODEL_NAME, explore: EXPLORE_NAME}], parameters.NewMapParameter( explore_reference, An explore reference like {model: MODEL_NAME, explore: EXPLORE_NAME}, , ), )两处定义见 lookerconversationalanalytics.go。explore_references 的解析与校验由于explore_references被声明为自由形式 map 数组LLM 生成的元素结构并不会被 schema 严格校验因此源码在解析时对每个元素逐一做防御性检查元素必须是对象、model与explore必须是字符串任何形状异常都会返回明确的 Agent 错误而不是触发 panic。核心逻辑位于 parseExploreReferencesfunc parseExploreReferences(raw []any, lookerInstanceURI string) ([]LookerExploreReference, util.ToolboxError) { refs : make([]LookerExploreReference, 0, len(raw)) for i, er : range raw { m, ok : er.(map[string]any) if !ok { return nil, util.NewAgentError(fmt.Sprintf(invalid explore reference at index %d in explore_references: expected object, got %T, i, er), nil) } model, ok : m[model].(string) ... } return refs, nil }对应的单元测试 lookerconversationalanalytics_internal_test.go 覆盖了五类异常输入——元素不是对象、缺少model、model非字符串、缺少explore、explore非字符串——以及空输入返回空切片不报错的正常路径。同时每个被解析出的引用都会被附上 Looker 实例 URIlookerInstanceUri用于在请求中标识数据来源。完整配置示例工具级配置以下 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.工具字段参考表fieldtyperequireddescriptiontypestringtrueMust be looker-conversational-analytics.sourcestringtrueName of the source the SQL should execute on.descriptionstringtrueDescription of the tool that is passed to the LLM.需要说明的是原文档参考表中 type 写作 lookerca-conversational-analytics从源码注册的resourceType见上文可确认实际合法值应为looker-conversational-analytics文档表格存在笔误配置时请以源码为准。此外源码要求description字段必填——Initialize 中会在描述为空时直接返回错误description is required for tool %q。该描述会被透传给 LLM用于让模型判断何时调用此工具因此建议写得具体说明适用场景、两个参数的形式1~5 个 model/explore 组合并提示配合get_models、get_explores发现可用模型与 explore。工具默认行为只读标注与系统指令从源码可见该工具在未显式配置annotations时会套用tools.NewReadOnlyAnnotations即默认标记为只读工具见 lookerconversationalanalytics.go。同时每次请求都会携带一段固定系统指令要求回答先呈现支撑数据、再给出结论且输出必须为纯文本、禁止生成任何图表或可视化const instructions **INSTRUCTIONS - FOLLOW THESE RULES:** 1. **CONTENT:** Your answer should present the supporting data and then provide a conclusion based on that data. 2. **OUTPUT FORMAT:** Your entire response MUST be in plain text format ONLY. 3. **NO CHARTS:** You are STRICTLY FORBIDDEN from generating any charts, graphs, images, or any other form of visualization.见 lookerconversationalanalytics.go。前置条件Looker 源与 GCP 权限该工具的兼容数据源是type: looker的源源码中的 compatibleSource 接口 定义了它要求的源能力Looker SDK、GCP 项目与区域、令牌来源等。使用前需要完成 Looker 源配置、GCP API 开通与 IAM 授权三层准备详见 Looker Source 文档。1. 配置 looker 源含 Conversational Analytics 字段普通 Looker 工具源只需要 API 地址与凭据而 Conversational Analytics 额外依赖project与location两个字段仅在使用该工具时被用到kind: source name: my-looker-conversational-source type: looker base_url: ${LOOKER_BASE_URL} client_id: ${LOOKER_CLIENT_ID:} client_secret: ${LOOKER_CLIENT_SECRET:} verify_ssl: ${LOOKER_VERIFY_SSL:true} timeout: 600s use_client_oauth: ${LOOKER_USE_CLIENT_OAUTH:false} project: ${LOOKER_PROJECT:} location: ${LOOKER_LOCATION:}几点实操注意来自源文档base_url形如https://looker.example.com不要带结尾斜杠本地/自建部署的 Looker 可能需要追加 API 端口如https://looker.example.com:19999。verify_ssl几乎总是应设为小写true仅在使用自签名证书时才改为 false任何非true的值都会被解释为 false。client_id/client_secret是 Looker 服务器分配的一串随机字符如果使用 Looker OAuth 则无需配置。location默认值为us源字段参考表。强烈建议用${ENV_NAME}环境变量替换方式注入敏感信息避免把密钥硬编码进配置文件。2. 开通 GCP API在目标 Google Cloud 项目中启用以下两个 API源自 Looker Source 文档gcloud services enable geminidataanalytics.googleapis.com --project$PROJECT_ID gcloud services enable cloudaicompanion.googleapis.com --project$PROJECT_ID3. IAM 权限除按 ADC 官方指南 配置应用默认凭据外运行身份需要具备以下 IAM 角色或其对应权限角色用途roles/looker.instanceUser访问 Looker 实例roles/cloudaicompanion.user访问 Conversational AnalyticsGemini for Google Cloud 用户roles/geminidataanalytics.dataAgentStatelessUser访问 Conversational AnalyticsGemini Data Analytics 无状态聊天用户Beta启动 MCP Toolbox 前先在本机执行gcloud auth login --update-adc初始化应用默认凭据。此外Looker 侧账号本身也必须有权限访问目标模型、explore 与数据见 预置配置文档。源码在 Invoke 时还会强制校验源的project非空否则直接报错lookerconversationalanalytics.go。预置配置一条命令拉起完整会话分析工具集为了免去手工拼装仓库内置了完整的预置配置 internal/prebuiltconfigs/tools/looker-conversational-analytics.yaml通过--prebuilt looker-conversational-analytics即可启用。它包含一个 looker 源与三个工具组成的工具集looker_conversational_analytics_toolsask_data_insights类型looker-conversational-analytics向数据提问get_models类型looker-get-models列出 Looker 实例中可用的 LookML 模型无参数get_explores类型looker-get-explores列出指定模型下的 explore必填参数model_name。其中get_models/get_explores是ask_data_insights的侦察前置工具——Agent 先枚举模型与 explore再把选定的 1~5 个组合作为explore_references传入提问工具形成发现 → 引用 → 提问的完整链路。对应工具文档可参见 looker-get-models 与 looker-get-explores。预置配置依赖的环境变量环境变量说明LOOKER_BASE_URLLooker 实例地址LOOKER_CLIENT_IDLooker API 客户端 IDLOOKER_CLIENT_SECRETLooker API 客户端密钥LOOKER_VERIFY_SSL是否校验 SSL 证书默认 trueLOOKER_USE_CLIENT_OAUTH是否使用客户端 OAuth默认 falseLOOKER_PROJECT用于 Conversational Analytics 的 GCP 项目LOOKER_LOCATION用于 Conversational Analytics 的 GCP 区域底层原理一次提问在源码中的完整调用链从源码层面拆解一次looker-conversational-analytics调用Invoke 实现可以看到清晰的五步流程校验源断言源实现了compatibleSource接口并校验project已定义。获取凭据通过源的GoogleCloudTokenSourceWithScope申请https://www.googleapis.com/auth/cloud-platform范围令牌用于调用 Gemini Data Analytics APILooker 侧的认证则视源配置二选一——若启用客户端授权use_client_oauth透传 MCP 客户端的 OAuth access token否则使用源的 Looker APIclient_id/client_secret。解析 explore 引用调用parseExploreReferences将原始参数转换为带lookerInstanceUri的强类型引用。构造并发送请求向 GDA 端点发起流式chat请求caURL : fmt.Sprintf(%s/v1/projects/%s/locations/%s:chat, util.GetGDAEndpoint(), url.PathEscape(projectID), url.PathEscape(location))请求体CAPayload包含用户消息、系统指令、数据源引用datasourceReferences.looker.exploreReferences、凭据与clientIdEnum见 lookerconversationalanalytics.go。HTTP 客户端超时被设置为330 秒以容纳长查询与流式返回。解析流式响应getStream读取 JSON 数组形式的流按systemMessage类型分发到五个处理函数lookerconversationalanalytics.go流消息类型处理函数返回给 Agent 的键texthandleTextResponseAnswer最终答案文本schemahandleSchemaResponseQuestion/Schema Resolvedschema 确认过程datahandleDataResponseRetrieval Query生成的 Looker 查询/Data Retrieved查询结果行analysishandleAnalysisResponseAnalysisJSON 化的分析事件含计划推理、代码、执行输出等errorhandleErrorError错误信息appendMessage还会对连续数据消息去重若上一条是Data Retrieved则先移除再追加新消息避免返回重复数据块lookerconversationalanalytics.go。这套结构意味着 Agent 拿到的是一组过程 结果的多段消息既能看到系统确认了哪个 explore 的 schema、生成了什么样的 LookML 查询也能拿到最终答案与检索到的原始数据行便于在回答中先呈现支撑数据、再给出结论。典型使用流程总结结合上文一个完整的落地流程是开通 GCP 的两个 API配置 ADC 与三项 IAM 角色配置带project/location的type: looker源或直接使用--prebuilt looker-conversational-analytics在工具配置中声明looker-conversational-analytics工具description 建议写明参数约束与配合工具Agent 运行时先调用get_models→get_explores发现数据再以user_query_with_context 1~5 个explore_references调用本工具从返回的Answer/Data Retrieved/Analysis等段落中提取支撑数据与结论以纯文本形式呈现给用户。限制与注意事项explore 数量上限explore_references一次最多 5 个超出会违反工具参数约束输出纯文本系统指令强制禁止图表输出不要期望该工具返回可视化仅支持 Looker 源ValidateSource会拒绝非兼容类型源lookerconversationalanalytics.goBeta 能力roles/geminidataanalytics.dataAgentStatelessUser为 Beta 角色生产环境使用前需评估其成熟度认证模式二选一客户端 OAuth 透传与 Looker API 密钥认证互斥由源的use_client_oauth决定。更多上下文可继续阅读 Looker 集成文档 与 预置配置列表并结合 源码 与 单元测试 验证本文所述行为。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考