MCP Toolbox 的 looker-get-explores 工具：基于 LookML 模型发现 Explore 元数据的完整指南

导读

looker-get-explores 是 MCP Toolbox for Databases 中 Looker 集成系列的核心元数据发现工具之一。它以 LookML 模型名为入参，向 LLM/Agent 返回该模型下全部 Explore 的名称、描述、标签与分组标签，是后续调用 looker-get-dimensions、looker-get-measures、looker-query 等工具前必须执行的第一环。阅读本文后，你将掌握该工具的参数约定、YAML 配置方式、返回数据格式，并能从源码层面理解其调用 Looker API 与过滤隐藏 Explore 的完整实现链路。

功能概述：从模型名到 Explore 清单

在 Looker 中，Explore 是对数据的一种策划视图（curated view），通常将多张表 JOIN 在一起，为某个特定主题域提供聚焦分析入口。looker-get-explores 的作用就是"给定一个 LookML 模型，返回该模型下定义的所有 Explore"。

该工具只接受一个参数：model（LookML 模型的 ID/名称）。调用后返回一个由 map 组成的数组，每个 map 的格式如下：

{
    "name": "explore name",
    "description": "explore description",
    "label": "explore label",
    "group_label": "group label"
}

四个字段的含义：

字段	含义
name	Explore 在 LookML 中的唯一标识名，后续调用 looker-get-dimensions、looker-get-measures、looker-query 时通过 explore_name 引用它
description	该 Explore 的说明文字，帮助 LLM 判断此 Explore 是否适合当前分析主题
label	面向用户展示的显示名
group_label	该 Explore 所属的分组标签，用于在 UI 中归类

需要留意的是：在 源码实现 中，工具参数名被定义为 model（描述为 "The model containing the explores."），这与 Looker 系列其他工具在配置文档中惯用的 model_name 命名不同；集成测试 中也以 {"model": "system__activity"} 作为调用载荷进行验证。

配置示例：在 MCP Toolbox 中注册该工具

looker-get-explores 遵循 MCP Toolbox 统一的 kind: tool 声明式配置方式。下面是一个可直接复制使用的完整配置（与 预置配置 中的 get_explores 定义一致）：

kind: tool
name: get_explores
type: looker-get-explores
source: looker-source
description: |
  This tool retrieves a list of explores defined within a specific LookML model.
  Explores represent a curated view of your data, typically joining several
  tables together to allow for focused analysis on a particular subject area.
  The output provides details like the explore's `name` and `label`.

  Parameters:
  - model (required): The name of the LookML model, obtained from `get_models`.

source 字段必须指向一个已声明的 type: looker 源。Looker 源的典型配置如下（完整字段见 Looker Source 文档）：

kind: source
name: my-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}

其中 show_hidden_explores 字段（默认 true）直接决定了本工具是否会把标记为 hidden 的 Explore 一并返回，其底层逻辑见下文"隐藏 Explore 的过滤"一节。

配置字段参考

工具自身的可配置字段如下表（与 原文档 Reference 表格 一致）：

field	type	required	description
type	string	true	Must be "looker-get-explores".
source	string	true	Name of the source the SQL should execute on.
description	string	true	Description of the tool that is passed to the LLM.

除上表三个必填字段外，源码的 Config 结构 还内嵌了 tools.ConfigBase（包含 name、authRequired 等通用字段），并支持可选的 annotations 字段。其中 description 会被原样传递给 LLM 作为工具说明，因此务必在描述中写清参数含义与使用前置条件。

源码实现解析：一次调用的完整链路

理解底层实现有助于排查问题与评估该工具的能力边界。核心实现位于 lookergetexplores.go，可以拆分为四个环节：

1. 工具注册与 YAML 解析

模块在 init() 中通过 tools.Register("looker-get-explores", newConfig) 完成注册（注册代码）。newConfig 使用 goccy/go-yaml 将 YAML 内容解码到 Config 结构体，并通过 validate:"required" 标签约束 type 与 source 必填。YAML 解析行为有对应的单元测试覆盖：

• TestParseFromYamlLookerGetExplores：验证最小配置 type/source/description 能正确解析为 Config；
• TestFailParseFromYamlLookerGetFilters：验证配置中出现未知字段（如 method）时解析直接失败，返回包含字段位置的报错信息。

2. 参数声明与只读语义

Initialize 阶段通过 parameters.NewStringParameter("model", ...) 声明唯一的字符串参数 model，并调用 tools.NewReadOnlyAnnotations 为该工具打上"只读"注解（初始化代码），表示该工具不会对数据产生写操作。集成测试 RunToolGetTestByName 验证了对外暴露的参数清单：model 为必填、类型为 string。

3. 源兼容性校验

ValidateSource 与 Invoke 都要求传入的 source 实现 compatibleSource 接口（接口定义），该接口包含：

• UseClientAuthorization()：判断是否使用客户端（终端用户）授权；
• GetAuthTokenHeaderName()：返回访问令牌所在的 HTTP 头名称；
• LookerApiSettings()：返回 Looker API 设置；
• GetLookerSDK(ctx, accessToken)：返回 Looker SDK 实例；
• LookerShowHiddenExplores()：返回是否展示隐藏 Explore。

internal/sources/looker/looker.go 中的 Source 类型完整实现了该接口。从源码结构看，这保证了本工具既能与 Looker 服务端账号认证（client_id/client_secret）配合，也能与 use_client_oauth: true 时的终端用户令牌转发模式配合——RequiresClientAuthorization 与 GetAuthTokenHeaderName 会透传给 source 决定。

4. 调用 Looker API 与结果组装

Invoke 的执行流程（核心调用）：

1. 从参数表中取出 model，非字符串类型直接返回 Agent 错误；
2. 调用 source.GetLookerSDK(ctx, accessToken) 获取 SDK 实例；
3. 调用 sdk.LookmlModel(model, "explores(name,description,label,group_label,hidden)")，通过 Looker API v4 按字段子集拉取模型下的 Explore 信息；
4. 错误处理：若响应包含 status=401，转换为 HTTP 401 的未授权错误；其他错误走 util.ProcessGeneralError 统一处理；
5. 遍历响应中的每个 Explore，仅当字段非空（如 v.Name != nil）时才写入返回 map，从而保证返回 JSON 中只出现实际存在的键。

隐藏 Explore 的过滤

在第 5 步遍历时，代码会检查隐藏标记（过滤逻辑）：

if !source.LookerShowHiddenExplores() && v.Hidden != nil && *v.Hidden {
    continue
}

即：当 source 配置中 show_hidden_explores 为 false 时，hidden 属性为 true 的 Explore 会被跳过；默认值为 true，此时隐藏 Explore 也会出现在结果中。这是该工具与 Looker 源配置联动最直接的一个行为点。

在完整工作流中的位置

looker-get-explores 不是孤立工具，它与 Looker 工具族构成一条典型的"发现—查询"链路（工具清单见 Looker 源文档 及 预置配置）：

1. looker-get-models：获取全部 LookML 模型；
2. looker-get-explores（本文）：给定模型，获取其下所有 Explore；
3. looker-get-dimensions / looker-get-measures / looker-get-filters / looker-get-parameters：获取 Explore 内的字段细节；
4. looker-query / looker-query-sql / looker-query-url：基于上述元数据执行实际查询。

因此，在配置多个工具时，通常会在各工具的 description 中交叉引用上游输出（如 get_explores 的 model 来自 get_models，而 get_dimensions 的 explore_name 来自 get_explores），帮助 LLM 正确编排调用顺序。

总结

• looker-get-explores 是只读元数据工具，接受唯一参数 model，返回 Explore 的 name/description/label/group_label 数组；
• 配置只需声明 type: looker-get-explores、source 与面向 LLM 的 description 三个必填字段；
• 底层通过 Looker SDK 的 LookmlModel 接口拉取数据，并对 401 未授权、隐藏 Explore 等场景做了显式处理；
• 与 looker-get-models（上游）和 looker-get-dimensions、looker-query（下游）配合，构成完整的元数据驱动查询链路；
• 相关实现与验证可继续查阅：工具源码、单元测试、Looker 源实现、预置配置 与 集成测试。