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.gotype 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.该声明的三个顶层字段语义如下字段类型必填说明typestringtrue必须为looker-get-filters用于注册与分发到对应工具实现。sourcestringtrue工具执行所依赖的数据源名称Looker source。descriptionstringtrue传递给 LLM 的工具说明文本描述工具能力与参数用法。从源码看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 验证了两点合法的 YAMLtypesourcedescription能被正确解析为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.gofunc 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 工具 manifestlookergetfilters.go 第 76-85 行。调用时若model或explore不是字符串类型ProcessFieldArgslookercommon.go 第 171-182 行会返回形如model must be a string, got ...的 Agent 错误。底层实现与 Looker API 调用链整个执行流程可以在 lookergetfilters.go 的Invoke方法 中完整看到校验数据源兼容性将sources.Source断言为compatibleSource失败则返回 500 客户端错误。解析参数通过lookercommon.ProcessFieldArgs提取model与explore。声明所需字段使用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))调用 SDK通过source.GetLookerSDK获取 Looker SDK v4 实例然后请求sdk.LookmlModelExplore(...)即 Looker API 的lookml_model_explore端点按名称获取模型与 explore 的元数据。错误分类若错误信息包含status401返回 401 Unauthorized其余错误统一交给util.ProcessGeneralError处理。空值防护lookercommon.CheckLookerExploreFields检查响应及其Fields对象是否为 nil避免后续解引用 paniclookercommon.go 第 102-108 行。字段提取调用lookercommon.ExtractLookerFieldProperties将 SDK 响应转换为统一的 JSON 结构并返回。字段提取规则源码级ExtractLookerFieldPropertieslookercommon.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 }各字段语义对照源码序列化逻辑字段来源LookML 属性说明namename字段全限定名如view.field可原样用作查询过滤器的键。typetype字段类型如string、date等 Looker 类型。labellabel完整显示标签。label_shortlabel_short短标签。descriptiondescription字段描述。tagstags标签数组仅在非空时输出。synonymssynonyms同义词数组仅在非空时输出。suggestablesuggestable布尔值表示该字段是否支持值建议源码中始终输出。suggestionssuggestions预定义建议值列表仅当suggestable为 true 且非空时输出。suggest_explore/suggest_dimensionsuggest_explore / suggest_dimension建议值来源的 explore 与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考