企业官网建设流程全解析

MCP Toolbox for Databases 实战：使用 looker-make-look 工具在 Looker 中创建保存型 Look

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

本篇技术指南围绕 MCP Toolbox for Databases 中 Looker 集成模块的looker-make-look工具展开，讲解如何通过 MCP 协议让 LLM 在 Looker 用户的个人文件夹中创建带可视化的保存型 Look（Saved Look），涵盖完整的参数语义、YAML 工具配置、底层调用链与错误处理行为。读完本文，你将掌握在 MCP Toolbox 配置中接入该工具、向其正确传参、理解其返回值与约束，并能结合get_models、get_explores等工具编排"数据探索 → 建 Look"的完整 Agent 工作流。

工具定位：从"查询"到"沉淀"

在 Looker 集成 的 MCP 工具集中，looker-make-look是一个写操作型工具，它与只读的query、query_url、run_look形成互补：

• query：执行查询并直接返回结果数据；
• query_url：生成可分享的查询 URL，返回id、slug、url；
• run_look：执行一个已存在Look 的查询并返回数据；
• looker-make-look：创建一个新的保存型 Look（查询 + 可视化），保存在用户个人文件夹中，并返回访问链接。

从源码结构看，该工具的实现位于 lookermakelook.go，注册的资源类型名为looker-make-look（见resourceType常量）。工具在init()阶段通过tools.Register(resourceType, newConfig)完成注册，因此它可以像其他内置工具一样被 prebuiltconfigs/tools/looker.yaml 中的预置配置直接引用。

一个典型的 Agent 编排流程是：先用get_models获取 LookML 模型，再用get_explores获取 explore，接着用get_dimensions/get_measures确认可用字段，最后调用make_look把分析结果沉淀为团队或个人可复用的 Look。

十二个参数完整解析

根据 looker-make-look 官方文档，该工具共接收12 个参数：

其中第 1～8 项是标准的查询参数，由 lookercommon.go 中的GetQueryParameters()统一生成，与query工具共用同一套定义；第 9～12 项是looker-make-look在Initialize()阶段追加的专属参数（见 lookermakelook.go）：

• title：字符串参数，必填，无默认值，用作新建 Look 的名称；
• description：字符串参数，默认空字符串；
• folder：字符串参数，默认空字符串。传空时工具会自动解析当前用户（通过MeAPI）的personal_folder_id；
• vis_config：Map 参数，默认{}，结构与query_url工具的vis_config完全一致。

查询参数细节

• fields：字符串数组，对应v4.WriteQuery.Fields，可包含维度、度量、过滤器字段与参数。
• filters：Map 参数。键必须是view.field全限定名（例如users.state），值必须是 Looker 过滤器表达式。文档特别提醒：值不要包额外引号；对于 LookMLparameter字段，应传原始 allowed_value（如first_touch）而非"first_touch"。若值含逗号需用单引号包裹（如'New York, NY'）；not null取代-NULL。需要合法取值时，可先用get_field_value_suggestions工具查询。
• pivots：字符串数组，透视字段必须同时出现在fields中。
• sorts：字符串数组，格式如["view.field desc"]。
• limit：整数，默认500，-1表示不限行数。
• tz：时区字符串；若未提供，ProcessQueryArgs会通过tzlocal.RuntimeTZ()探测本地时区，探测失败时回退到Etc/UTC（见 lookercommon.go）。
• 此外，GetQueryParameters()还提供了filter_expression（Looker 表达式过滤器字符串，支持${view.field}引用与AND/OR/matches_filter等函数）与dynamic_fields（表计算、自定义维度/度量的 JSON 数组）两个可选参数，它们同样会被looker-make-look继承到查询构建中。

vis_config：把可视化带进 Look

vis_config决定了新建 Look 打开时的默认图表形态。它在调用CreateQuery时被写入WriteQuery.VisConfig（见 lookermakelook.go）。它支持looker_bar、looker_column、looker_line、looker_area、looker_scatter、looker_pie、looker_funnel、looker_boxplot、looker_waterfall、looker_wordcloud、single_value、looker_single_record等图表类型，通用配置项包括：

• 常规：type、series_types、show_view_names、series_labels；
• 样式与颜色：colors、series_colors、color_application、font_size；
• 图例：hide_legend、legend_position；
• 坐标轴：swap_axes、x_axis_scale、x_axis_reversed、y_axis_reversed、x_axis_gridlines、y_axis_gridlines、x_axis_label_rotation、x_axis_zoom、y_axis_zoom、y_axes多轴数组；
• 数据与序列：stacking（''/normal/percent）、ordering、limit_displayed_rows、limit_displayed_rows_values、discontinuous_nulls、point_style、interpolation、show_value_labels、label_value_format、show_totals_labels、hidden_series；
• 散点/气泡专属：size_by_field、color_by_field、quadrants_enabled、quadrant_properties、cluster_points；
• 其他：reference_lines、trend_lines、trellis、crossfilters、advanced_vis_config（内嵌 Highcharts JSON 字符串）。

一个最简的柱状图示例：

{ "type": "looker_bar", "stacking": "normal", "legend_position": "center", "show_x_axis_label": true, "show_y_axis_labels": true, "x_axis_gridlines": false, "y_axis_gridlines": true }

完整可复制的各图表类型配置样例可参考 looker.yaml 预置配置 中query_url工具的描述部分（make_look的vis_config与其完全同构）。

在 YAML 中配置 make_look 工具

looker-make-look作为 MCP Toolbox 的一种 tool 类型，通过 YAML 声明接入。下面是文档提供的完整配置示例（在预置配置文件 looker.yaml 中即为make_look条目）：

kind: tool name: make_look type: looker-make-look source: looker-source description: | This tool creates a new Look (saved query with visualization) in Looker. The Look will be saved in the user's personal folder, and its name must be unique. Required Parameters: - title: A unique title for the new Look. - description: A brief description of the Look's purpose. - model_name: The name of the LookML model (from `get_models`). - explore_name: The name of the explore (from `get_explores`). - fields: A list of field names (dimensions, measures, filters, or parameters) to include in the query. Optional Parameters: - pivots, filters, sorts, limit, query_timezone: These parameters are identical to those described for the `query` tool. - vis_config: A JSON object defining the visualization settings for the Look. The structure and options are the same as for the `query_url` tool's `vis_config`. Output: A JSON object containing a link (`url`) to the newly created Look, along with its `id` and `slug`.

对应地，YAML 顶层字段约束如下（文档 Reference 表）：

工具配置的解析与校验

从 Config 结构体 可以看到，Type与Source都带有validate:"required"约束，description同样不可为空——若Initialize()时Description == ""，会直接返回错误description is required for tool %q（见 lookermakelook.go）。

单元测试 lookermakelook_test.go 对该配置的解析行为给出了明确印证：

• TestParseFromYamlLookerMakeLook：验证了最小合法配置kind/name/type/source/description可被正确解析为lookermakelook.Config；
• TestFailParseFromYamlLookerMakeLook：验证了在配置中混入method: GOT这类未知字段时会解析失败并报错unknown field "method"，说明配置结构是严格白名单式的。

此外，looker-make-look的默认注解为写操作（tools.NewWriteAnnotations），与query等只读工具区分开，便于权限模型按读写分离进行管控。

底层执行流程：一次 make_look 调用发生了什么

looker-make-look的Invoke()实现（lookermakelook.go）把一次调用拆解为清晰的六步，全部通过 Looker API v4 SDK 完成：

1. 构建查询请求：调用lookercommon.ProcessQueryArgs把model/explore/fields/filters/pivots/sorts/limit/tz等参数组装为v4.WriteQuery。若参数非法（如字段类型错误）会返回 Agent 错误error building query request。
2. 获取 SDK 会话：通过 source 的GetLookerSDK(ctx, accessToken)获取与 Looker 实例的会话句柄（见 looker.go）。
3. 解析用户身份与目标文件夹：调用sdk.Me()（请求字段id,personal_folder_id）获取当前用户。若调用方未传folder参数，则取用户的personal_folder_id；若用户没有个人文件夹且未指定folder，工具直接报错user does not have a personal folder. A folder must be specified。若Me返回 401，则转为unauthorized error客户端错误。
4. 标题唯一性检查：调用sdk.FolderLooks(folder, "title", ...)拉取目标文件夹内全部 Look 的标题，与传入的title比对。若已存在同名 Look，返回错误并附上当前已使用的标题列表，提示"使用唯一标题重试"。这正是文档中"name must be unique"约束的实现来源。
5. 先建查询、再建 Look：先通过sdk.CreateQuery把（含vis_config的）WriteQuery落成一条持久化查询（qrespFields仅请求id），随后用sdk.CreateLook构造WriteLookWithQuery——把Title、UserId、Description、QueryId、FolderId绑定在一起创建 Look。这种"查询 + 元数据"的两段式写入保证了 Look 与底层查询严格一一对应。
6. 组装返回结果：调用GetHostURL解析 Looker 实例的公网主机地址（该地址来自versionsAPI 的web_server_url，带 10 分钟缓存与失败回退逻辑，见 looker.go），将short_url拼接为完整链接。

返回值

成功时返回一个 JSON 对象，包含：

• id：新建 Look 的唯一数字标识；
• short_url：可访问该 Look 的短链接（能解析到主机地址时拼上 host，否则返回 SDK 原始值）。

额外的查询健壮性处理

在构建查询前，工具还会调用lookercommon.EscapeUnquotedParameterFilters（lookermakelook.go）：它会查询 explore 的 parameter 元数据，将过滤器中指向type: unquoted参数的_、%、,、^等 Looker 过滤表达式元字符按规则转义（如first_touch→first^_touch），避免查询以 400 失败。元数据查询失败时仅记录告警并继续（保证无参数场景可用），相关实现见 lookercommon.go。

前置条件：Looker Source 配置

looker-make-look只能运行在类型为looker的 source 之上。预置配置 looker.yaml 给出了标准 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 use_client_oauth: ${LOOKER_USE_CLIENT_OAUTH:false} show_hidden_models: ${LOOKER_SHOW_HIDDEN_MODELS:true} show_hidden_explores: ${LOOKER_SHOW_HIDDEN_EXPLORES:true} show_hidden_fields: ${LOOKER_SHOW_HIDDEN_FIELDS:true}

从 looker.go 源码 可以确认其默认值与行为：

• verify_ssl默认true；设为false时跳过 TLS 校验并输出安全告警日志；
• timeout默认600s，会被解析为time.Duration后传给 SDK 的ApiSettings.Timeout；
• use_client_oauth默认false，此时必须提供client_id与client_secret，工具会用服务账号/应用凭据建立 SDK 会话；设为true时改为客户端 OAuth 模式，每次请求由上层提供用户级Authorizationtoken（RequiresClientAuthorization会返回UseClientAuthorization()的结果，见 lookermakelook.go）；
• 兼容性校验：looker-make-look要求 source 实现compatibleSource接口（UseClientAuthorization、GetAuthTokenHeaderName、LookerApiSettings、GetLookerSDK、GetHostURL），若把 source 配成其他类型会报错invalid source for "looker-make-look" tool（见 lookermakelook.go）。

使用建议与注意事项

• 写操作权限：looker-make-look被标记为写注解工具，Agent 调用前应确认所用凭据具备创建 Look、查询元数据（LookmlModelExplore）与写入个人文件夹的权限。
• 标题唯一性：Look 标题在同一目标文件夹内必须唯一；重复创建同标题 Look 会得到错误响应（附当前已用标题列表），Agent 应据此改名后重试。
• 个人文件夹依赖：不指定folder时依赖用户拥有个人文件夹；若用户无个人文件夹，必须显式传入folderid。
• 与get_looks协同：创建后可借助get_looks（支持按title、folder_id、user_id等搜索）验证或定位已创建的 Look，再用run_look取数。
• 时区语义：tz不传时按运行环境本地时区（探测失败回退Etc/UTC）计算，跨时区团队建议显式指定。

小结

looker-make-look是 MCP Toolbox Looker 集成中"从查询到沉淀"的关键写工具：它复用query的全部查询参数，追加title、description、folder、vis_config四类专属参数，并在服务端完成"查用户 → 查文件夹 → 校验标题唯一 → 建查询 → 建 Look → 拼链接"的完整调用链。理解其参数语义、YAML 配置格式与底层实现，你就能让 LLM 稳定地把分析结果固化为团队可复用的 Look 资产。

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