企业官网建设流程全解析

MCP Toolbox 的 looker-health-vacuum 工具：基于系统活动数据分析并清理未使用的 LookML 对象

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

本指南系统讲解 MCP Toolbox 中looker-health-vacuum工具的功能定位、参数语义、配置方法及其底层实现原理。该工具面向 Looker 实例的"健康治理"场景，通过查询 Looker 系统活动数据（system__activity）识别长期未被查询使用的模型（models）、探索（explores）、连接（joins）与字段（fields），为语义层瘦身、LookML 重构和权限清理提供数据依据。读完本文，你将能够独立完成该工具的参数调优、YAML 配置接入，并理解其判定"未使用"的完整算法。

工具概览：从"体检"到"清理建议"

在 MCP Toolbox 的 Looker 集成体系中，looker-health-vacuum与looker-health-analyze构成一对互补工具：looker-health-analyze 负责统计项目、模型、探索的使用情况（相当于"体检报告"），而looker-health-vacuum则进一步输出可直接移除的低活跃度对象候选清单（相当于"清理建议"），帮助团队在语义层规模膨胀前主动治理。

根据工具说明（looker-health-vacuum.md），该工具通过action参数选择执行的清理分析类型：

• models：识别一个模型（model）内部未被使用的 explores；
• explores：识别一个探索（explore）内部未被使用的 joins 和 fields。

从源码结构看，两种 action 的输出对象不同：models模式的返回值聚焦"模型 → 未使用探索列表"的映射，而explores模式则细化到"探索 → 未使用连接 / 未使用字段"两个维度，详见 lookerhealthvacuum.go。

参数详解：六个参数控制整个判定逻辑

工具的运行时参数定义于 lookerhealthvacuum.go 的 Initialize 方法，与文档参数表完全对应：

各参数要点说明：

• action（必填）：合法值仅为models与explores。源码中switch action对未知值返回unknown action: %s的 Agent 错误（Invoke 方法），因此调用时务必使用文档规定的两种取值。
• project / model / explore（可选，逐级收窄）：用于将分析范围限定到指定对象。从源码实现看，过滤条件为空字符串时视为"不过滤"：models模式同时支持project与model两个过滤维度（models 方法）；explores模式则用model过滤模型、用explore过滤探索（explores 方法）。不指定任何范围参数时，将扫描实例内全部 LookML 模型。
• timeframe（默认 90）：回溯分析的使用时间窗口（天）。该值会拼入系统活动查询的时间过滤条件，例如"history.created_date": "90 days"。
• min_queries（默认 1）：判定"被使用"的查询次数下限。默认值 1 意味着"至少被查询过 1 次"即视为已使用；将值调大（如 5、10）可以更严格地筛选出真正的低频对象。

注意：源码中默认值的生效逻辑为"参数为 0 时回退到默认值"（Invoke 方法），即显式传入timeframe: 0或min_queries: 0与不传效果相同，会分别被重置为 90 与 1。

配置接入：完整的 YAML 工具定义

在 MCP Toolbox 中，工具通过 YAML 声明式配置注册。文档给出了一个识别thelook模型中order_items探索内低活跃字段与连接的示例（这里min_queries判定阈值下，20 天内查询次数少于 1 的字段被标记为未使用）：

kind: tool name: health_vacuum type: looker-health-vacuum source: looker-source description: | This tool identifies and suggests LookML models or explores that can be safely removed due to inactivity or low usage. Parameters: - action (required): The type of resource to analyze for removal candidates. Can be `"models"` or `"explores"`. - project (optional): The specific project ID to consider. - model (optional): The specific model name to consider. Requires `project` if used without `explore`. - explore (optional): The specific explore name to consider. Requires `model` if used. - timeframe (optional): The lookback period in days to assess usage. Defaults to `90` days. - min_queries (optional): The minimum number of queries for a resource to be considered active. Defaults to `1`. Output: A JSON array of objects, each representing a model or explore that is a candidate for deletion due to low usage.

配置块中的三个顶层字段含义如下：

其中description会被直接传递给 LLM 作为工具说明（Manifest 定义），是模型理解工具用途与参数语义的关键文本，务必写清 action 取值、可选参数依赖关系与输出格式。

该工具的预置配置已随项目提供：在 looker-dev.yaml 中可以看到名为health_vacuum的完整工具条目，且它被列入该预置配置的工具清单（looker-dev.yaml 工具列表）。因此，直接加载looker-dev预置配置即可快速获得该工具，无需手工编写。

配置解析的严格性

工具的配置解析由 newConfig 与Config结构体（type、source均为validate:"required"）承载。对应的单元测试 lookerhealthvacuum_test.go 验证了两类行为：

• 合法配置可正常解析：最小化配置（仅kind、name、type、source、description）能正确反序列化为Config对象；
• 未知字段会直接报错：若在配置中混入未定义的字段（如invalid_field: true），解析将失败并返回unknown field "invalid_field"错误，防止拼写错误悄悄生效。

此外，工具初始化时若description为空会直接返回错误（Initialize 方法），这是配置被拒绝的最常见原因。

前置条件：Looker 源与认证

looker-health-vacuum属于 Looker 集成，必须挂载在合法的 Looker source 上运行。源码通过compatibleSource接口约束来源类型（接口定义），要求来源具备GetLookerSDK能力；若 source 不兼容，ValidateSource会返回类型错误。

在认证方面，Looker source 仅使用 API 认证：需要先在 Looker 中创建 API 用户以登录，并确保运行 MCP Toolbox 的服务身份具备相应的 GCP IAM 权限（如roles/looker.instanceUser等），详见 Looker Source 说明。调用工具时 SDK 的获取基于访问令牌，源码对 401 未授权错误有专门处理（Invoke 方法），认证失效时会返回 401 状态以便上层重试或刷新凭据。

实现原理：如何判定"未使用"

这是本文的核心部分。工具的判定逻辑全部建立在Looker 系统活动数据（system__activity中的history视图）之上——即"查询历史记录"。整体分为三层查询：

1. 模型使用度：getUsedModels

getUsedModels 通过内联查询（inline query）汇总最近timeframe天内每个模型被查询的次数，其过滤条件相当精细：

• 按history.created_date限定时间窗口（如"90 days"）；
• 排除系统模型自身：-system__activity, -i__looker；
• 仅统计达到活跃阈值的记录：history.query_run_count > min_queries-1；
• 排除开发分支上的查询：user.dev_branch_name: "NULL"，即只统计生产环境的真实使用。

查询结果以{"模型名": 查询次数}的映射形式返回，供后续匹配。

2. 未使用探索：getUnusedExplores

getUnusedExplores 针对单个模型内的每个探索，构造以query.model与query.view（即探索名）为过滤条件的计数查询；若结果集为空（该探索在时间窗口内一条生产查询都没有），则将其标记为未使用。注意该函数对查询失败的处理是"记录错误并继续"，单个探索查询失败不会中断整体分析。

3. 未使用字段与连接：getUsedExploreFields

getUsedExploreFields 是整个工具最核心的细节所在，它决定了一个字段是否"被使用"：

• 查询query.formatted_fields与query.filters两个字段（即"被选中展示的字段"与"被用作筛选条件的字段"），并限制在production工作区（history.workspace_id: "production"）；
• 用正则(\w+\.\w+)从这两类文本中提取视图名.字段名形式的字段标识；
• 将每次命中的history.query_run_count累加到对应字段上，得到每个字段的总查询次数。

随后 explores 方法 组装判定结果：

• 未使用字段：从LookmlModelExplore拉取该探索全部未隐藏的 dimension 与 measure，凡是不在"已使用字段"映射中的，即判定为未使用；
• 未使用连接：按字段名首段（.前的 join 名）聚合各 join 的查询次数，再与该探索的 join 列表比对，计数为 0 的 join 即为未使用。

输出格式

工具最终返回一个 JSON 数组。models模式的每个元素形如{"Model": ..., "Unused Explores": [...], "Model Query Count": N}；explores模式的每个元素形如{"Model": ..., "Explore": ..., "Unused Joins": [...], "Unused Fields": [...]}。Agent 可据此直接生成"建议移除对象"清单，交人工复核后执行删除。

使用建议与注意事项

• 先 analyze 后 vacuum：建议先运行looker-health-analyze获取使用统计概览，再运行looker-health-vacuum获取可移除对象清单，两步数据相互印证，避免误删。
• 生产数据为基准：判定仅统计生产环境（排除开发分支）的查询，符合"线上真实使用"的清理语义；如果团队存在大量未上线的预研模型，它们会自然进入候选清单，这是预期行为而非缺陷。
• 合理设置时间窗口：默认 90 天适合大多数季度节奏；对快速迭代的团队可缩短（如 30 天），对数据仓库类低频业务可拉长（如 180 天），以平衡"清理收益"与"误伤风险"。
• 字段级清理需人工复核：字段与连接的判定依赖系统活动数据的字段名文本解析，若 Looker 中存在自定义字段命名或异常查询日志，建议将min_queries保持默认值并结合人工抽查确认后再删除对象。

小结

looker-health-vacuum是 MCP Toolbox Looker 集成中面向语义层治理的实用工具：它以 Looker 系统活动数据为唯一事实来源，通过models与explores两种模式分别输出未使用的探索、连接与字段候选清单，并以"时间窗口 + 最小查询次数"两个可调阈值控制清理灵敏度。配合本文所述的源码级判定逻辑（lookerhealthvacuum.go）、配置规范（looker-dev.yaml）与测试保障（lookerhealthvacuum_test.go），开发者可以安全地将该工具接入日常的 Looker 健康巡检流程，持续控制语义层规模与维护成本。

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