企业官网建设流程全解析

MCP Toolbox for Databases 的 looker-get-filters 工具：从 Looker Explore 提取 Filter-Only 字段的完整指南

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

导读

looker-get-filters是 MCP Toolbox for Databases（开源数据库 MCP Server）内置的 Looker 集成工具之一，用于返回指定 LookML 模型中某个 Explore 的全部 filter-only 字段（在 LookML 中以filter:显式声明的特殊字段）。本文以官方文档为主体，结合仓库源码、预置配置与集成测试，系统讲解该工具的参数、YAML 声明方式、响应结构、底层 Looker API 调用链与字段提取规则，帮助你直接在 MCP 场景下让 LLM 借助该工具动态发现可用的过滤控件，为构建动态查询铺路。

工具概述

looker-get-filters的核心职责是：返回给定model中指定explore的所有过滤器字段（filters）。它只接受两个参数——model和explore，二者均为必填。

需要特别强调的是，这里的"过滤器字段"专指 LookML 中显式定义为filter:类型的字段（filter-only fields）。这类字段在 Looker 中用于创建面向用户的过滤控件，其特殊之处在于：它们不会直接参与 SQL 查询的GROUP BY子句，通常与 liquid 模板（liquid templating）配合使用来生成动态查询。文档明确指出，常规的维度（dimensions）和度量（measures）也可以在查询中充当过滤器，但本工具只返回在 LookML 中显式声明为filter:的字段。

兼容数据源

该工具运行在 Looker 数据源之上。在源码中，工具通过类型断言检查运行它的数据源是否实现了compatibleSource接口（internal/tools/looker/lookergetfilters/lookergetfilters.go）：

type compatibleSource interface { UseClientAuthorization() bool GetAuthTokenHeaderName() string LookerApiSettings() *rtl.ApiSettings GetLookerSDK(context.Context, string) (*v4.LookerSDK, error) LookerShowHiddenFields() bool }

如果配置中的source不是兼容类型，ValidateSource会直接报错："invalid source for ... tool: source ... is not a compatible type"。也就是说，使用前需要先配置好 Looker 数据源（source），并且该数据源需支持通过 Looker SDK v4 访问 API。

在配置文件中声明工具

looker-get-filters通过 YAML 配置文件以kind: tool的方式声明。以下是官方文档给出的完整示例（与仓库预置配置 internal/prebuiltconfigs/tools/looker.yaml 中的get_filters一致）：

kind: tool name: get_filters type: looker-get-filters source: looker-source description: | This tool retrieves a list of "filter-only fields" defined within a specific Looker explore. These are special fields defined in LookML specifically to create user-facing filter controls that do not directly affect the `GROUP BY` clause of the SQL query. They are often used in conjunction with liquid templating to create dynamic queries. Note: Regular dimensions and measures can also be used as filters in a query. This tool *only* returns fields explicitly defined as `filter:` in LookML. 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`.

该声明的三个顶层字段语义如下：

从源码看，Config结构体还支持可选的annotations字段（internal/tools/looker/lookergetfilters/lookergetfilters.go）。若未显式声明 annotations，工具初始化时默认套用tools.NewReadOnlyAnnotations（同文件第 82 行），即默认视为只读工具；description为空时初始化会直接失败并返回错误 "description is required for tool ..."。

单元测试 internal/tools/looker/lookergetfilters/lookergetfilters_test.go 验证了两点：合法的 YAML（type+source+description）能被正确解析为Config；而出现未知字段（如示例中的method: GOT）时解析会失败并给出明确的错误信息，说明配置结构是严格校验的。

调用参数

该工具只暴露两个运行时参数，均由 Looker 侧元数据派生而来：

• model（必填）：LookML 模型的名称。参数描述为 "The model containing the explore."，通常可先调用配套的get_models工具获取候选模型列表。
• explore（必填）：模型内部的 explore 名称。参数描述为 "The explore containing the fields."，通常可先调用配套的get_explores工具获取候选 explore 列表。

这两个参数的定义集中在 internal/tools/looker/lookercommon/lookercommon.go：

func GetFieldParameters() parameters.Parameters { modelParameter := parameters.NewStringParameter("model", "The model containing the explore.") exploreParameter := parameters.NewStringParameter("explore", "The explore containing the fields.") return parameters.Parameters{modelParameter, exploreParameter} }

工具初始化时正是通过lookercommon.GetFieldParameters()构造参数清单并生成对应的 MCP 工具 manifest（lookergetfilters.go 第 76-85 行）。调用时若model或explore不是字符串类型，ProcessFieldArgs（lookercommon.go 第 171-182 行）会返回形如'model' must be a string, got ...的 Agent 错误。

底层实现与 Looker API 调用链

整个执行流程可以在 lookergetfilters.go 的Invoke方法 中完整看到：

1. 校验数据源兼容性：将sources.Source断言为compatibleSource，失败则返回 500 客户端错误。
2. 解析参数：通过lookercommon.ProcessFieldArgs提取model与explore。
3. 声明所需字段：使用lookercommon.FiltersFields常量（lookercommon.go 第 32 行）向 Looker API 声明只需要 filters 相关的字段子集：

   FiltersFields = "fields(filters(name,type,label,label_short,description,synonyms,tags,hidden,suggestable,suggestions,suggest_dimension,suggest_explore))"

4. 调用 SDK：通过source.GetLookerSDK获取 Looker SDK v4 实例，然后请求sdk.LookmlModelExplore(...)，即 Looker API 的lookml_model_explore端点，按名称获取模型与 explore 的元数据。
5. 错误分类：若错误信息包含status=401，返回 401 Unauthorized；其余错误统一交给util.ProcessGeneralError处理。
6. 空值防护：lookercommon.CheckLookerExploreFields检查响应及其Fields对象是否为 nil，避免后续解引用 panic（lookercommon.go 第 102-108 行）。
7. 字段提取：调用lookercommon.ExtractLookerFieldProperties将 SDK 响应转换为统一的 JSON 结构并返回。

字段提取规则（源码级）

ExtractLookerFieldProperties（lookercommon.go 第 37-100 行）对每个 filter 字段依次应用以下规则：

• 跳过_raw后缀字段：名称以_raw结尾的字段被直接跳过（strings.HasSuffix(*v.Name, "_raw")）。
• 隐藏字段：当数据源配置LookerShowHiddenFields()返回 false（默认）时，hidden为 true 的字段会被过滤掉，不返回给 LLM。
• nil 安全序列化：只有字段值非 nil 时才写入结果 map，保证 JSON 中不出现null噪音。
• suggest 信息条件化：只有suggestable为 true、且同时存在suggest_explore与suggest_dimension时，才输出suggestions、suggest_explore、suggest_dimension三个字段——这与预置配置中"当提供suggest_explore和suggest_dimension时，可查询该 explore 与 dimension 以获取合法过滤值列表"的说明完全吻合。

响应格式

调用成功后返回的是一个 JSON 数组，每个元素对应一个 filter 字段，包含以下字段：

{ "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" }

各字段语义对照源码序列化逻辑：

集成测试 tests/looker/looker_integration_test.go 中可以看到该工具在真实 Looker 实例上的行为：对system__activity模型、content_usageexplore 调用get_filters返回空数组[]（该 explore 没有显式filter:字段），而get_measures能返回含name、label、type、suggestable等键的对象——这与文档"只返回显式filter:声明字段"的语义一致。

与配套工具的协作

looker-get-filters不是孤立存在的，它在 Looker 工具集中与字段发现与查询链路配合使用：

• 向上溯源：先用get_models获取模型列表，再用get_explores获取某模型下的 explore 列表，然后调用本工具获取该 explore 的 filter-only 字段。
• 向下延伸：预置配置 internal/prebuiltconfigs/tools/looker.yaml 中，query工具的filters参数说明明确要求"每个 key 必须是完整的view_name.field_name，原样复制自get_dimensions、get_measures、get_filters或get_parameters"，且前缀与点号必须保留；而get_field_value_suggestions工具则用于在suggestable字段上检索合法过滤值。也就是说，looker-get-filters的返回结果是构造合法query过滤条件的字段来源之一。

使用限制与注意事项

• 只读工具：默认 annotations 为 ReadOnly，适合安全地暴露给 LLM 做元数据探索，不会修改 Looker 端任何资源。
• 结果取决于 Looker 元数据：返回内容直接来源于lookml_model_explore端点，因此模型/explore 名称必须与 Looker 侧完全一致；名称错误时 SDK 调用会返回错误并被分类处理。
• 隐藏字段受数据源配置控制：是否返回隐藏字段由 Looker source 的show_hidden_fields类配置决定（接口方法LookerShowHiddenFields()），这是工具级别无法覆盖的。
• 建议信息为可选：suggestions、suggest_explore、suggest_dimension只有在字段可建议且元数据完整时才会出现，LLM 使用时应将其视为可选增强信息。

综上，looker-get-filters是 Looker 动态查询链路中负责"过滤器字段发现"的关键一环：它以极小的参数面（仅model、explore）把 Looker 的 filter-only 字段元数据以结构化 JSON 暴露给 LLM，配合get_models、get_explores、get_field_value_suggestions与query等工具，即可在 MCP 场景下构建"发现字段 → 校验取值 → 组装查询"的完整自动化闭环。

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