MCP Toolbox for Databases 实战:使用 looker-make-look 工具在 Looker 中创建保存型 Look 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 用户的个人文件夹中创建带可视化的保存型 LookSaved 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、urlrun_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 个参数#参数必填说明1model是包含 explore 的 LookML 模型名来自get_models2explore是要查询的 explore 名来自get_explores3fields是字段名列表dimension、measure、filter 或 parameter4filters否过滤器集合键为view.field全限定名5pivots否透视字段列表必须同时包含在fields中6sorts否排序列表如field.id desc 07limit否行数上限默认500-1表示不限制8tz否查询时区9vis_config否可视化配置 JSON 对象10title是Look 的标题在当前文件夹内必须唯一11description否Look 的描述12folder否目标文件夹 id不提供则使用用户默认个人文件夹其中第 18 项是标准的查询参数由 lookercommon.go 中的GetQueryParameters()统一生成与query工具共用同一套定义第 912 项是looker-make-look在Initialize()阶段追加的专属参数见 lookermakelook.gotitle字符串参数必填无默认值用作新建 Look 的名称description字符串参数默认空字符串folder字符串参数默认空字符串。传空时工具会自动解析当前用户通过MeAPI的personal_folder_idvis_configMap 参数默认{}结构与query_url工具的vis_config完全一致。查询参数细节fields字符串数组对应v4.WriteQuery.Fields可包含维度、度量、过滤器字段与参数。filtersMap 参数。键必须是view.field全限定名例如users.state值必须是 Looker 过滤器表达式。文档特别提醒值不要包额外引号对于 LookMLparameter字段应传原始 allowed_value如first_touch而非first_touch。若值含逗号需用单引号包裹如New York, NYnot 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_expressionLooker 表达式过滤器字符串支持${view.field}引用与AND/OR/matches_filter等函数与dynamic_fields表计算、自定义维度/度量的 JSON 数组两个可选参数它们同样会被looker-make-look继承到查询构建中。vis_config把可视化带进 Lookvis_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 users personal folder, and its name must be unique. Required Parameters: - title: A unique title for the new Look. - description: A brief description of the Looks 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 tools vis_config. Output: A JSON object containing a link (url) to the newly created Look, along with its id and slug.对应地YAML 顶层字段约束如下文档 Reference 表字段类型必填说明typestring是必须为looker-make-looksourcestring是该工具执行所依赖的 source 名称需为 Looker 类型descriptionstring是传递给 LLM 的工具描述用于让模型理解何时调用及如何传参工具配置的解析与校验从 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.ConfigTestFailParseFromYamlLookerMakeLook验证了在配置中混入method: GOT这类未知字段时会解析失败并报错unknown field method说明配置结构是严格白名单式的。此外looker-make-look的默认注解为写操作tools.NewWriteAnnotations与query等只读工具区分开便于权限模型按读写分离进行管控。底层执行流程一次 make_look 调用发生了什么looker-make-look的Invoke()实现lookermakelook.go把一次调用拆解为清晰的六步全部通过 Looker API v4 SDK 完成构建查询请求调用lookercommon.ProcessQueryArgs把model/explore/fields/filters/pivots/sorts/limit/tz等参数组装为v4.WriteQuery。若参数非法如字段类型错误会返回 Agent 错误error building query request。获取 SDK 会话通过 source 的GetLookerSDK(ctx, accessToken)获取与 Looker 实例的会话句柄见 looker.go。解析用户身份与目标文件夹调用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客户端错误。标题唯一性检查调用sdk.FolderLooks(folder, title, ...)拉取目标文件夹内全部 Look 的标题与传入的title比对。若已存在同名 Look返回错误并附上当前已使用的标题列表提示使用唯一标题重试。这正是文档中name must be unique约束的实现来源。先建查询、再建 Look先通过sdk.CreateQuery把含vis_config的WriteQuery落成一条持久化查询qrespFields仅请求id随后用sdk.CreateLook构造WriteLookWithQuery——把Title、UserId、Description、QueryId、FolderId绑定在一起创建 Look。这种查询 元数据的两段式写入保证了 Look 与底层查询严格一一对应。组装返回结果调用GetHostURL解析 Looker 实例的公网主机地址该地址来自versionsAPI 的web_server_url带 10 分钟缓存与失败回退逻辑见 looker.go将short_url拼接为完整链接。返回值成功时返回一个 JSON 对象包含id新建 Look 的唯一数字标识short_url可访问该 Look 的短链接能解析到主机地址时拼上 host否则返回 SDK 原始值。额外的查询健壮性处理在构建查询前工具还会调用lookercommon.EscapeUnquotedParameterFilterslookermakelook.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.Timeoutuse_client_oauth默认false此时必须提供client_id与client_secret工具会用服务账号/应用凭据建立 SDK 会话设为true时改为客户端 OAuth 模式每次请求由上层提供用户级AuthorizationtokenRequiresClientAuthorization会返回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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考