MCP Toolbox 中looker-run-look工具完全指南运行已保存 Look 的查询【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxlooker-run-look是 MCP Toolbox for Databases 提供的 Looker 集成工具之一用于直接执行与某个已保存 LookLooker 中预定义并保存的查询/可视化关联的查询并以 JSON 结构返回结果数据。本指南围绕该工具的配置方式、参数语义与底层实现展开读者将掌握如何在 MCP Toolbox 的 YAML 配置中声明该工具、如何通过look_id触发一次 Look 查询以及该工具从 Looker REST API 取数到返回 JSON 的完整执行链路。工具概述looker-run-look的核心能力非常聚焦给定一个 Looker Look 的唯一标识look_id它会读取该 Look 保存的查询定义重新向 Looker 发起内联查询inline query请求并把查询结果作为 JSON 数组返回给调用方LLM 或 Agent。该工具只接收一个必需参数参数类型必需说明look_idstring是要运行的 Look 的唯一标识通常由get_looks工具搜索得到在 looker-run-look.go 的实现中可以看到该工具实际上声明了两个运行时参数look_id必需字符串与limit整型默认值 500用于控制返回行数上限lookidParameter : parameters.NewStringParameter(look_id, The id of the look to run.) limitParameter : parameters.NewIntParameter(limit, The row limit. Default 500, parameters.WithIntDefault(500))这意味着即使在原文档中只强调了look_id通过源码可以看出调用方还可以通过limit约束结果规模默认取 500 行。配置参考在 MCP Toolbox 中所有工具都是通过 YAML 配置文件声明注册的。一个完整的looker-run-look工具声明如下出自 原文档kind: tool name: run_look type: looker-run-look source: looker-source description: | This tool executes the query associated with a saved Look and returns the resulting data in a JSON structure. Parameters: - look_id (required): The unique identifier of the Look to run, typically obtained from the get_looks tool. Output: The query results are returned as a JSON object.该配置项字段说明如下继承自原文档 Reference 表格字段类型必需说明typestring是必须为looker-run-look声明本工具的类型sourcestring是查询所执行的 Looker source 名称descriptionstring是传递给 LLM 的工具描述description字段并非摆设从源码 lookerrunlook.go 可见Initialize阶段会强制校验description非空否则直接返回错误description is required for tool %q。该描述会被写入工具的 MCP manifest作为 LLM 理解工具用途、生成正确参数的关键输入因此应写清楚参数语义、获取方式与输出格式。与 Looker source 的配合示例中的source: looker-source必须指向一个type: looker的 source 定义。完整 Looker source 配置可参考 source.md 与仓库预构建配置 looker.yamlkind: source name: looker-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} show_hidden_models: ${LOOKER_SHOW_HIDDEN_MODELS:true} show_hidden_explores: ${LOOKER_SHOW_HIDDEN_EXPLORES:true} show_hidden_fields: ${LOOKER_SHOW_HIDDEN_FIELDS:true}关键注意点base_url形如https://looker.example.com不要带尾部/自建部署on-premises场景通常还需追加 API 端口如https://looker.example.com:19999。client_id/client_secret由 Looker 服务器分配若使用 Looker OAuth 则无需填写。verify_ssl除true小写外的任何取值都会按 false 处理除非使用自签名证书否则应保持true。建议一律使用${ENV_NAME}环境变量替换格式避免把密钥明文写进配置文件。源码级执行原理理解该工具的运行机制需要沿着 lookerrunlook.go 的Invoke方法走一遍完整链路第一步获取 Looker SDK。工具先从 source 拿到配置好的 Looker SDKsource.GetLookerSDK(ctx, accessToken)用于后续所有 API 调用。若 SDK 获取失败返回 HTTP 500 错误。第二步读取 Look 定义。调用sdk.Look(look_id, , source.LookerApiSettings())获取 Look 的元数据其中最关键的是look.Query——它包含了该 Look 保存时的完整查询定义。这里对 401 状态做了专门识别返回 HTTP 401 Unauthorized 错误便于调用方感知鉴权问题。第三步重建查询。把look.Query中的Model、View、Fields、Pivots、Filters、Sorts、QueryTimezone逐一拷贝到新的v4.WriteQuery并把limit参数转换为字符串后写入Limit字段。这意味着run_look本质上不是调用运行已保存查询的 API而是把已保存查询的配置翻译成一次全新的内联查询请求因此limit得以动态生效。第四步内联执行。通过 lookercommon.go 中的RunInlineQuery以json格式执行查询。值得注意的实现细节是它优先使用带query_api_client_context标识为MCP Toolbox的新版/queries/run_inline端点若该端点失败再回退到sdk.RunInlineQuery旧接口兼顾了兼容性与可观测性。第五步JSON 反序列化。将查询响应的 JSON 字符串json.Unmarshal到[]any即 JSON 数组作为any类型返回给调用方。任何反序列化失败都会以 HTTP 500 客户端错误返回。从整体流程看该工具是一个只读查询工具源码中通过tools.NewReadOnlyAnnotations为它声明了只读注解LLM 可以据此判断调用该工具不会产生副作用。与 get_looks 工具的协同使用look_id从哪里来原文档明确指出它通常从get_looks工具获取。Looker 集成中配套提供了 looker-get-looks 搜索工具支持按title通配符、folder_id、user_id、description、id等条件检索已保存的 Look并支持limit/offset分页。典型的 Agent 工作流是调用get_looks按标题或描述找到目标 Look取其id调用run_look传入该id作为look_id拿到 JSON 结果后交由 LLM 进行解读、汇总或进一步追问。兼容性与源码验证从源码结构看looker-run-look通过compatibleSource接口lookerrunlook.go约束其兼容的 source 类型source 必须实现UseClientAuthorization、GetAuthTokenHeaderName、LookerApiSettings与GetLookerSDK四个方法。ValidateSource会在配置校验期拒绝不兼容的 source提前暴露配置错误而非等到运行时才失败。仓库还提供了对应的配置解析测试 lookerrunlook_test.go其中TestParseFromYamlLookerRunLook验证了最小 YAML 配置kind: tool、name、type: looker-run-look、source、description能够被正确解析为Config结构体TestFailParseFromYamlLookerRunLook验证了未知字段如method会被严格拒绝并报错说明该工具的配置解析是白名单式的——多余的字段不会静默忽略。另外仓库预构建的 Looker 工具集 looker.yaml 中已包含一份开箱即用的run_look声明并将其纳入了looker_tools工具组使用官方预构建配置时无需再手动编写该工具定义。小结looker-run-look用极简的配置接口一个look_id参数 三个声明字段封装了运行已保存 Look 查询这一常见 BI 场景它复用了 Look 中固化好的字段、筛选、排序与时区设置避免 Agent 重新拼装复杂查询同时通过limit保持了对结果规模的控制。配合get_looks搜索工具它能够成为 LLM 对话式数据分析链路中直接复用既有报表查询的高效一环。配置时只需确保type、source、description三要素齐全并让source指向配置正确的 Looker source 即可。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
