企业官网建设流程全解析

MCP Toolbox 实战：looker-get-measures 工具详解——从 Looker Explore 拉取全部度量（Measures）字段

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

looker-get-measures是 MCP Toolbox（面向数据库的开源 MCP Server）为 Looker 集成提供的一款元数据探测工具：给定 LookML 模型与 Explore 名称，即可一次性返回该 Explore 内定义的全部度量（measure）字段及其元数据，为 LLM 理解"哪些指标可以聚合、如何用于过滤"提供结构化依据。读完本文，你将掌握该工具的参数契约、YAML 配置方法、JSON 返回结构、源码调用链，以及它与get_models、get_explores、get_dimensions、get_field_value_suggestions等兄弟工具协作完成"模型 → Explore → 字段 → 过滤值"完整链路的方式。

工具定位：度量字段的语义目录

在 Looker 的语义层中，字段分为两类：

• 维度（dimension）：不可聚合的属性，用于分组、过滤、切分（如订单日期、客户城市）；
• 度量（measure）：可聚合的指标，用于计算与定量分析（如总销售额、平均价格、用户数）。

looker-get-measures的作用正是把后者的"目录"完整暴露给 LLM。根据 工具官方文档 的定义：

Alooker-get-measurestool returns all the measures from a given explore in a given model in the source.

它只接受两个必填参数：model与explore。这与looker-get-dimensions（返回维度）是同一族工具，二者共享几乎完全相同的参数与输出契约，只是字段来源不同——维度来自dimensions，度量来自measures（参见 looker-get-dimensions 文档）。

在 Looker 源（source）文档 中，该工具被列为 Looker 源可用工具之一；Looker 源本身是一套基于 Web 的商业智能与语义层工具，可部署在云端、GCP 或本地。

配置示例：YAML 声明一个度量探测工具

在 MCP Toolbox 中，所有工具都通过 YAML 配置文件声明。下面是looker-get-measures的标准配置（节选自 官方文档 示例）：

kind: tool name: get_measures type: looker-get-measures source: looker-source description: | This tool retrieves a list of measures defined within a specific Looker explore. Measures are aggregatable metrics (e.g., total sales, average price, count of users) that are used for calculations and quantitative analysis in your queries. Parameters: - model_name (required): The name of the LookML model, obtained from `get_models`. - explore_name (required): The name of the explore within the model, obtained from `get_explores`. Output Details: - If a measure includes a `suggestions` field, its contents are valid values that can be used directly as filters for that measure. - If a `suggest_explore` and `suggest_dimension` are provided, you can query that specified explore and dimension to retrieve a list of valid filter values.

各字段的契约如下表（Reference 部分）：

其中description并非可有可无：该字符串会作为工具清单（Manifest）中的描述直接暴露给 LLM（见下文源码分析），是引导模型正确调用工具的关键。上例中的description明确告知模型：model_name、explore_name为必填，且二者的取值应分别来自get_models与get_explores的返回结果——这正是 MCP Toolbox 让多个工具"接力协作"的典型写法。

在 内置预配置 中，同样存在一个开箱即用的get_measures工具定义，其 description 还额外补充了一条：若度量带有"suggestable": true，可再调用get_field_value_suggestions工具（传入该度量的name作为field参数）获取其合法的过滤取值。

输出结构：度量字段的 JSON 元数据数组

调用成功后，工具返回一个 JSON 数组，每个元素描述一个度量字段，结构如下（见 官方文档）：

{ "name": "field name", "description": "field description", "type": "field type", "label": "field label", "label_short": "field short label", "tags": ["tags", ...], "synonyms": ["synonyms", ...], "suggestions": ["suggestion", ...], "suggest_explore": "explore", "suggest_dimension": "dimension" }

字段含义与使用要点：

• name/description/type：字段唯一名、描述与类型，是后续构造查询与过滤器的基础；
• label/label_short：面向用户的完整标签与短标签；
• tags/synonyms：LookML 中定义的标签与同义词，便于 LLM 理解业务语义；
• suggestions：预定义的合法取值列表，可直接用作该字段的过滤值；
• suggest_explore/suggest_dimension：当两者同时出现时，可通过查询其指定的 Explore 与 Dimension 来获取合法的过滤值集合。

文档特别强调后两类字段的用法：命中suggestions时直接使用；命中suggest_explore+suggest_dimension时，则需要"按图索骥"去对应 Explore 中查询。而在 looker-get-field-value-suggestions 文档 中可以看到，该工具正是用来对suggestable字段获取去重取值建议（如{"suggestions": ["CA", "NY", "TX", "WA"]}）的补充能力，二者搭配即可把"合法过滤值"这条信息链补完整。

源码实现：一次 Looker API 调用 + 字段属性抽取

在仓库中，looker-get-measures的实现位于 internal/tools/looker/lookergetmeasures/lookergetmeasures.go。

注册与配置解析

工具类型字符串looker-get-measures通过init()中的tools.Register(resourceType, newConfig)注册到全局工具注册表（第 33-39 行）；newConfig用 YAML 解码器把配置段解析为Config结构体，其中Type与Source均带validate:"required"标签，与文档的 Reference 表完全对应。

Config还嵌入了tools.ConfigBase并提供可选的annotations字段。在Initialize中，若Description为空会直接报错"description is required for tool"（第 71-87 行）——这印证了文档中description必须为true的原因：它是构造工具 Manifest（对 LLM 可见的描述与参数声明）的必要输入。同时，该工具默认使用tools.NewReadOnlyAnnotations（只读注解），表明它属于只读探测类工具。

参数与调用链

工具执行入口Invoke（第 112-155 行）的逻辑非常清晰：

1. 将运行时参数交给lookercommon.ProcessFieldArgs解析出model与explore两个字符串（定义见 internal/tools/looker/lookercommon/lookercommon.go，GetFieldParameters将二者声明为必填字符串参数）；
2. 通过source.GetLookerSDK(ctx, accessToken)获取 Looker SDK v4 客户端；
3. 构造v4.RequestLookmlModelExplore请求，其中Fields固定为MeasuresFields：

   fields(measures(name,type,label,label_short,description,synonyms,tags,hidden,suggestable,suggestions,suggest_dimension,suggest_explore))

   该常量定义于 lookercommon.go 第 30-35 行——注意它只请求measures子集，因此响应体远小于一次全量 explore 元数据拉取；

4. 调用sdk.LookmlModelExplore，并针对 HTTP 401 返回未授权错误；
5. 用lookercommon.CheckLookerExploreFields校验响应中的Fields不为空；
6. 用lookercommon.ExtractLookerFieldProperties（第 38-100 行）把 SDK 字段对象转换成文档所示的 JSON map 数组后返回。

抽取逻辑的细节：隐藏字段与建议字段

ExtractLookerFieldProperties有两个值得注意的行为，与文档中"输出结构"一节严格对应：

• 跳过_raw字段：字段名以_raw结尾时被直接跳过（第 55-57 行），避免把 Looker 生成的原始字段混入结果；
• 隐藏字段控制：当且仅当 source 配置了show_hidden_fields为 false 时，隐藏字段（hidden: true）才会被过滤（第 58-60 行），该开关与 Looker 源配置中的show_hidden_fields参数一一对应；
• 建议类字段的条件输出：suggestions仅在字段suggestable为 true 且存在非空建议时才输出；suggest_explore与suggest_dimension仅在suggestable为 true 且二者同时非空时才成对输出（第 83-94 行）。这与文档 Output Details 中的说明完全吻合，也解释了为什么返回元素的这些键是"可能缺失"的。

与 Looker 源的契约

工具通过compatibleSource接口与 Looker 源解耦（第 49-55 行），运行时强校验源是否实现了LookerApiSettings、GetLookerSDK、LookerShowHiddenFields等方法；若配置的 source 类型不兼容，ValidateSource与Invoke都会明确报错。也就是说，looker-get-measures只能挂在 Looker 类型的 source 上使用。Looker 源的完整配置可参考 Looker 源文档 或 内置预配置，其中show_hidden_fields: ${LOOKER_SHOW_HIDDEN_FIELDS:true}直接决定上文第 2 条隐藏字段过滤行为。

测试验证：配置解析与端到端调用

仓库为looker-get-measures提供了三层测试证据：

1. 配置解析单测：在 lookergetmeasures_test.go 中，TestParseFromYamlLookerGetMeasures验证 YAML 配置能被正确解析为Config（name、description、type、source 一一对应）；TestFailParseFromYamlLookerGetMeasures则验证未知字段（如method: GOT）会触发严格的解析错误——说明该工具对配置文件是白名单严格校验的，拼写错误会被直接拒绝；
2. 端到端集成测试：在 tests/looker/looker_integration_test.go 中，get_measures出现在工具的测试注册表里（第 116 行），并通过RunToolGetTestByName（第 485 行）与RunToolInvokeParametersTest（第 2396 行）验证了真实调用，后者使用{"model": "system__activity", "explore": "content_usage"}作为参数——这也可以作为你调试时的参考样例：Looker 自带的system__activity模型无需额外建数即可用于验证。

实战链路：从模型到可用的过滤值

结合 内置预配置 中的工具编排，looker-get-measures在完整链路中的位置如下：

1. get_models→ 获取全部 LookML 模型列表；
2. get_explores（传model_name）→ 获取模型内全部 Explore；
3. get_measures（传model_name+explore_name）→ 获取 Explore 内全部度量字段及其元数据；
4. 若度量带suggestions→ 直接作为过滤值使用；
5. 若度量带suggest_explore/suggest_dimension→ 查询对应 Explore/Dimension 获取过滤值；
6. 若度量带"suggestable": true→ 调用get_field_value_suggestions获取去重建议值（参考 工具文档 中的term与filters参数用法）；
7. 最终由query或looker-query-sql等查询类工具携带上述字段与过滤值执行分析。

配置好 Looker 源（参考 Looker 源文档 中的base_url、client_id、client_secret、verify_ssl等参数，以及为源配置项使用${ENV_NAME}环境变量替换的实践）与上述工具后，即可启动 MCP Toolbox，让 LLM 借助get_measures的元数据自主完成"选指标 → 定过滤 → 写查询"的分析闭环。

小结

looker-get-measures是一个设计精巧的只读元数据工具：对外，它把 Looker 语义层中"可聚合度量"的目录以结构化 JSON 呈现给 LLM；对内，它通过一次字段裁剪过的LookmlModelExploreAPI 调用加上统一的字段属性抽取逻辑，做到了轻量、可控且与维度工具完全对称。无论是为 LLM 提供指标语义，还是为下游查询准备合法的过滤取值，它都是 Looker 集成中不可或缺的一环。更多 Looker 工具（looker-get-dimensions、looker-get-parameters、looker-get-filters、looker-query等）可参阅 Looker 集成文档目录 继续深入。

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox