企业官网建设流程全解析

MCP Toolbox 的 looker-get-models 工具：从 Looker 实例获取全部 LookML 模型清单

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

导读

looker-get-models是 MCP Toolbox for Databases 中面向 Looker 集成的一组只读工具之一，它的职责非常聚焦：返回 Looker 源（source）中的全部 LookML 模型。本文将基于官方工具文档（docs/en/integrations/looker/tools/looker-get-models.md），结合仓库内该工具的 Go 源码实现与单元测试，完整讲解其 YAML 配置方式、底层 Looker API 调用逻辑、返回数据格式，以及它在"模型 → Explore → 查询"这条 LLM 工作流中的定位。读完本文，你将能够在自己的 MCP Toolbox 配置中正确声明并使用该工具，理解其输出字段的语义来源。

工具概述：无参数、只读的模型列举

looker-get-models是一个无参数工具，调用时不接受任何参数，直接返回当前 Looker 源中定义的所有 LookML 模型（models）。在 MCP 会话中，它通常扮演"能力发现"角色：LLM 先通过它获知实例上有哪些模型，再据此决定后续该调用哪个 Explore、执行哪条查询。

从源码结构看，该工具属于 Looker 工具族中的只读类别：在初始化时会自动应用只读注解（tools.NewReadOnlyAnnotations），并在配置清单中暴露一个空的参数列表（internal/tools/looker/lookergetmodels/lookergetmodels.go）：

allParameters := parameters.Parameters{} return Tool{ BaseTool: tools.NewBaseTool( cfg, tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewReadOnlyAnnotations), tools.Manifest{Description: cfg.Description, Parameters: allParameters.Manifest(), AuthRequired: cfg.AuthRequired}, allParameters, ), }, nil

这也与官方文档中"looker-get-modelsaccepts no parameters"的描述完全一致：它不接收任何运行时参数，所需的一切上下文（连接哪个 Looker 实例、是否显示隐藏模型）都来自工具所绑定的 source 配置。

兼容的 Source 类型

该工具只能挂载在类型为looker的源上。源码通过一个compatibleSource接口对源做了编译期约束（internal/tools/looker/lookergetmodels/lookergetmodels.go），要求源必须实现以下能力：

• UseClientAuthorization()：是否转发客户端 OAuth 授权
• GetAuthTokenHeaderName()：授权令牌所在的请求头名称
• LookerApiSettings()：返回 Looker API 调用所需的rtl.ApiSettings
• GetLookerSDK(context.Context, string)：获取 Looker SDK v4 实例
• LookerShowHiddenModels()：是否显示隐藏模型

如果在 YAML 中把该工具绑定到非looker类型的源，ValidateSource会直接报错："invalid source for 'looker-get-models' tool"。

Looker 源本身在 internal/sources/looker/looker.go 中注册，源码配置的完整字段说明见 Looker Source 文档。

底层实现：一次 LookML 模型的全量拉取

当工具被调用时，Invoke方法会通过 Looker SDK 调用AllLookmlModels接口（对应 Looker API 4.0 的/lookml_models端点），并传入三个控制参数（internal/tools/looker/lookergetmodels/lookergetmodels.go）：

excludeEmpty := false excludeHidden := !source.LookerShowHiddenModels() includeInternal := true req := v4.RequestAllLookmlModels{ ExcludeEmpty: &excludeEmpty, ExcludeHidden: &excludeHidden, IncludeInternal: &includeInternal, } resp, err := sdk.AllLookmlModels(req, source.LookerApiSettings())

三个参数的语义如下：

也就是说，是否展示隐藏模型不是由工具本身决定的，而是由它绑定的 Looker 源配置中的show_hidden_models开关决定的——这一点与文档中"工具不接受参数"的设计相辅相成：行为偏好被收敛到了源配置层，工具调用保持极简。

错误处理与鉴权

• 若 Looker 返回 401，工具会将其转换为unauthorized error返回；
• 其他错误统一交由util.ProcessGeneralError处理；
• 工具是否要求客户端授权（RequiresClientAuthorization）以及使用哪个头传递令牌（GetAuthTokenHeaderName），均委托给所绑定源的配置判断。

返回数据格式

AllLookmlModels的原始响应经过处理后，被归一化为元素为 map 的数组，每个模型输出四个字段（internal/tools/looker/lookergetmodels/lookergetmodels.go）：

vMap["label"] = *v.Label vMap["name"] = *v.Name vMap["project_name"] = *v.ProjectName vMap["connections"] = *v.AllowedDbConnectionNames

对应的一次典型返回大致如下：

[ { "label": "E-Commerce Model", "name": "ecommerce", "project_name": "my_project", "connections": ["my_connection"] }, { "label": "Marketing Model", "name": "marketing", "project_name": "marketing_project", "connections": ["marketing_conn"] } ]

字段语义：

name字段是整个 Looker 工具链协作的关键：官方文档在 looker-get-explores 工具文档 中明确指出，get_explores的必需参数model_name正是"从get_models获得"。

配置示例

声明工具

官方文档给出的工具声明示例如下，字段含义见文末 Reference 表格：

kind: tool name: get_models type: looker-get-models source: looker-source description: | This tool retrieves a list of available LookML models in the Looker instance. LookML models define the data structure and relationships that users can query. The output includes details like the model's `name` and `label`, which are essential for subsequent calls to tools like `get_explores` or `query`. This tool takes no parameters.

注意description字段会被直接传递给 LLM，作为工具清单（manifest）中的说明文本，因此建议像示例一样写清楚"输出里有哪些字段"以及"这些字段在后续流程中如何使用"，帮助模型正确编排调用链。

绑定 Looker 源

source字段必须指向一个已声明的looker类型源。一个最小可用的源配置（详见 Looker Source 文档）如下：

kind: 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 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，不要带尾部斜杠；自托管部署可能需要附加 API 端口，如https://looker.example.com:19999；
• verify_ssl几乎总是应为true，除非 Looker 服务器使用自签名证书；
• show_hidden_models默认值为true，即默认返回隐藏模型；设为false可在拉取模型清单时过滤掉隐藏模型；
• 建议用${ENV_NAME}环境变量替换的方式注入密钥，避免在配置文件中硬编码。

参数 Reference（官方字段表）

looker-get-models的 YAML 声明仅支持以下三个字段：

三个字段均为必填。type固定为looker-get-models，source指向 Looker 源名称，description描述工具用途（会透传给 LLM）。若配置中出现未知字段（例如误写method: GOT），YAML 解析将直接失败，这一行为有对应的单元测试覆盖（见下文）。

测试与配置校验

仓库为该工具提供了两个方向的单元测试（internal/tools/looker/lookergetmodels/lookergetmodels_test.go）：

• 正向解析测试TestParseFromYamlLookerGetModels：验证形如下面的合法配置能被正确反序列化为工具配置对象：

  kind: tool name: example_tool type: looker-get-models source: my-instance description: some description

• 失败解析测试TestFailParseFromYamlLookerGetModels：验证包含未知字段method: GOT的配置会抛出unknown field "method"的解析错误，确保配置校验的严格性。

这些测试印证了：工具声明是"白名单"式的——除name、type、source、description之外不接受其他字段，任何多余字段都会在加载配置阶段被拒绝，而不是静默忽略。

在 LLM 工作流中的典型用法

looker-get-models是 Looker 工具链的入口工具。一个典型的"从自然语言到数据结果"的调用链是：

1. get_models：列举实例上的全部 LookML 模型，得到模型的name/label；
2. get_explores：基于上一步选定的model_name，列出该模型内的 Explore；
3. get_dimensions/get_measures/get_parameters/get_filters：进一步了解 Explore 内的字段能力；
4. query/query_sql：最终构造并执行查询。

整个 Looker 工具家族在 docs/en/integrations/looker/tools/_index.md 中有完整索引；looker-get-models与其余 50 余个 Looker 工具一样，通过 internal/tools/looker/ 目录下的独立包注册到 MCP Toolbox 的工具注册表（tools.Register("looker-get-models", newConfig)），可与其他数据库类工具（PostgreSQL、BigQuery、Spanner 等）在同一服务器配置中混合编排。

小结

looker-get-models以"零参数 + 只读"的极简设计，承担了 Looker 语义层探索的第一步：通过一次AllLookmlModelsAPI 调用，把实例上所有 LookML 模型归一化为name、label、project_name、connections四个字段的数组，供 LLM 规划后续查询。它的行为偏好（如是否包含隐藏模型）由绑定的 Looker 源配置控制，声明格式严格限定为type、source、description三个必填字段，且受单元测试约束——这使它既易于接入，又行为可预期，非常适合作为 Looker 数据问答 Agent 的起点工具。

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