使用 MCP Toolbox 的 looker-create-dashboard-layout 工具为 Looker 仪表盘创建多 Tab 布局
【免费下载链接】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-create-dashboard-layout工具为主线，系统讲解如何通过声明式 YAML 配置与 MCP 调用，在 Looker 仪表盘中创建新的 dashboard layout（即现代 Looker 仪表盘中的 Tab 页签）。读完本文，你将掌握该工具的全部参数语义、底层 Looker SDK 调用链、兼容的 Looker Source 配置方式，以及它与make_dashboard、update_dashboard_layout_component等工具协作构建多页签仪表盘的完整工作流。
工具概述：什么是 dashboard layout
在现代 Looker 仪表盘中，一个 dashboard 可以包含多个 layout，每个 layout 通常对应界面上的一个Tab（页签）。looker-create-dashboard-layout工具的作用就是在指定仪表盘下创建一个新的 layout，从而以编程方式实现"一个仪表盘、多个页签"的结构。该能力对应的官方文档位于 docs/en/integrations/looker/tools/looker-create-dashboard-layout.md，它属于 Looker 集成工具集（toolset）中的仪表盘构建类工具。
从源码结构看，该工具被注册为资源类型looker-create-dashboard-layout，在 internal/tools/looker/lookercreatedashboardlayout/lookercreatedashboardlayout.go 中实现。它通过 Looker 官方 SDK（github.com/looker-open-source/sdk-codegen/go/sdk/v4）调用CreateDashboardLayoutAPI，将工具的语义化参数映射为 Looker API v4 的WriteDashboardLayout请求对象。
工作原理：从 YAML 配置到 Looker API 的调用链
该工具遵循 MCP Toolbox 统一的"工具注册 → 配置解析 → 参数清单（Manifest） → 调用执行"生命周期：
- 注册：包内
init()通过tools.Register("looker-create-dashboard-layout", newConfig)完成注册，若类型重复注册会直接 panic（见 lookercreatedashboardlayout.go）。 - 配置解析：
newConfig使用goccy/go-yaml将 YAML 解码为Config结构体，其中type与source字段带validate:"required"约束（同文件 L40-L60）。 - 初始化与参数清单：
Initialize中通过parameters.NewStringParameter/NewBooleanParameter声明四个参数（含默认值），并生成 MCP Manifest，向 LLM 暴露工具描述与参数模式；同时校验description字段必须非空，否则报错description is required for tool %q（同文件 L69-L94）。 - 执行调用：
Invoke从参数 Map 中取出dashboard_id、label、type、active，组装成 v4 的WriteDashboardLayout{ DashboardId, Label, Type, Active }，然后通过source.GetLookerSDK(ctx, accessToken)获取 SDK 实例并调用sdk.CreateDashboardLayout(wdl, "", source.LookerApiSettings())（同文件 L119-L175）。
// 核心调用（源码简化示意，完整实现见 internal/tools/looker/lookercreatedashboardlayout/lookercreatedashboardlayout.go） wdl := v4.WriteDashboardLayout{ DashboardId: &dashboardId, Label: &label, Type: &layoutType, Active: &active, } sdk, err := source.GetLookerSDK(ctx, string(accessToken)) resp, err := sdk.CreateDashboardLayout(wdl, "", source.LookerApiSettings())需要说明的是，该工具是写操作（创建资源），其默认注解通过tools.NewWriteAnnotations生成（同文件 L89），测试TestAnnotations也验证了ReadOnlyHint为false。
配置示例：完整 YAML 声明
原文档给出了最小可用示例，结合 internal/prebuiltconfigs/tools/looker.yaml 中实际预置的create_dashboard_layout配置，以下是可直接复制使用的完整 YAML：
kind: tool name: create_dashboard_layout type: looker-create-dashboard-layout source: looker-source description: | This tool creates a new dashboard layout, which typically represents a tab in modern Looker dashboards. Parameters: - dashboard_id (required): The ID of the dashboard. - label (required): The label (title) of the new tab. - type (optional): The type of layout (defaults to 'newspaper'). - active (optional): Whether to make this layout active.其中description会被原样传递到 LLM 的工具清单中，作为模型决定是否调用以及如何填参的依据，因此建议在描述中把参数语义写清楚。
顶层配置字段参考
| field | type | required | description |
|---|---|---|---|
| kind | string | true | 固定为tool。 |
| name | string | true | 工具实例名，即 MCP 暴露的工具名（如create_dashboard_layout）。 |
| type | string | true | 必须为looker-create-dashboard-layout。 |
| source | string | true | Looker source 的名称（须与 source 配置的name一致）。 |
| description | string | true | 传递给 LLM 的工具描述；源码中校验其为必填（否则初始化失败）。 |
对应测试用例 lookercreatedashboardlayout_test.go 中的TestParseFromYaml验证了上述最小 YAML 能被正确解析为Config{Type: "looker-create-dashboard-layout", Source: "my-instance"}，而TestFailParseFromYaml验证了未知字段（如method）会导致解析失败。
调用参数详解
该工具在调用（MCP invoke）阶段接收四个参数，前两个必填、后两个可选：
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
dashboard_id | string | 是 | 无 | 目标仪表盘的 ID，通常来自get_dashboards或make_dashboard的返回结果。 |
label | string | 是 | 无 | 新页签（layout）的标签/标题，会显示在仪表盘 Tab 上。 |
type | string | 否 | newspaper | 布局类型，例如newspaper、grid。源码中默认值由parameters.WithStringDefault("newspaper")声明（见 lookercreatedashboardlayout.go）。 |
active | boolean | 否 | false | 是否将该 layout 设为当前激活页签，默认false（同文件 L77）。 |
TestManifest测试逐一断言了这四个参数（dashboard_id、label、type、active）都会出现在 MCP Manifest 的参数清单中，确保 LLM 能感知到它们的 schema。
返回值
调用成功后，工具返回一个 JSON 对象：
result：形如Dashboard layout (tab) "<label>" created的确认消息；id：当 Looker API 响应包含 layout ID 时返回，供后续update_dashboard_layout_component等操作引用（见 lookercreatedashboardlayout.go）。
错误处理
- 参数缺失或类型错误（如
dashboard_id不是字符串）时返回 Agent 错误； - Looker 返回 401 时被识别为未授权错误，转为
util.NewClientServerError； - 其余错误统一走
util.ProcessGeneralError处理（同文件 L162-L167）。
Compatible Sources：Looker Source 的配置要求
原文档中的{{< compatible-sources >}}表明该工具只适用于 Looker 类型的数据源。源码中通过compatibleSource接口（UseClientAuthorization、GetAuthTokenHeaderName、LookerApiSettings、GetLookerSDK）约束了这一点（见 lookercreatedashboardlayout.go），ValidateSource会对不兼容的 source 报错。
因此使用前需要先声明一个type: looker的 source，参考 internal/prebuiltconfigs/tools/looker.yaml 顶部的标准配置：
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}在 internal/sources/looker/looker.go 的源码中可以看到这些配置项的默认值：SslVerification默认true、Timeout默认600s、UseClientOAuth默认"false"、ShowHiddenModels/Explores/Fields默认true。SDK 初始化时将ApiVersion固定为"4.0"，并把verify_ssl、timeout、client_id、client_secret等映射到rtl.ApiSettings。工具调用所需的鉴权 token 由调用方注入，通过GetLookerSDK与 source 建立连接。
典型工作流：构建多页签仪表盘
looker-create-dashboard-layout通常不是单独使用的，而是嵌入到"创建仪表盘 → 添加内容"的流水线中。综合 internal/prebuiltconfigs/tools/looker.yaml 中相关工具的描述，推荐的调用顺序是：
- 用
make_dashboard创建空仪表盘，拿到dashboard_id； - 用
add_dashboard_filter添加仪表盘级筛选器； - 用
add_dashboard_element添加内容瓦片（tile）； - 用本工具
create_dashboard_layout创建新页签（layout）； - 用
looker-update-dashboard-layout-component（文档见 docs/en/integrations/looker/tools/looker-update-dashboard-layout-component.md）将已有瓦片移动到新页签并调整行列、宽高。
其中第 5 步工具的调用参数为：dashboard_layout_component_id（必填）定位瓦片组件，dashboard_layout_id指定目标页签，row/column/width/height控制位置与尺寸。通过create_dashboard_layout+update_dashboard_layout_component的组合，Agent 可以完全程序化地把一个仪表盘组织成多个 Tab 的结构，而无需人工在 Looker UI 中拖拽。
一个完整的 LLM 调用示例（MCP invoke 阶段）：
{ "name": "create_dashboard_layout", "arguments": { "dashboard_id": "123", "label": "Revenue Overview", "type": "newspaper", "active": true } }测试与可靠性保障
该工具附带了完整的单元测试，位于 internal/tools/looker/lookercreatedashboardlayout/lookercreatedashboardlayout_test.go，覆盖四个维度：
- 配置解析（
TestParseFromYaml/TestFailParseFromYaml）：验证合法 YAML 可正确反序列化、未知字段会报错； - 参数清单（
TestManifest）：验证四个参数全部暴露在 Manifest 中； - 注解语义（
TestAnnotations）：验证工具为写操作（ReadOnlyHint=false）。
这些测试从侧面印证了本文所述的行为：只要按表格字段配置 YAML，工具就能稳定注册、初始化并被 LLM 正确调用。
小结
looker-create-dashboard-layout是 MCP Toolbox Looker 集成中用于构建多页签仪表盘的写操作工具。它通过dashboard_id+label两个必填参数与type（默认newspaper）、active（默认false）两个可选参数，经 Looker SDK v4 的CreateDashboardLayoutAPI 完成页签创建，并返回新建 layout 的id供后续编排。与make_dashboard、add_dashboard_element、update_dashboard_layout_component搭配使用，即可让 Agent 端到端地完成"创建仪表盘并组织为多 Tab 布局"的自动化流程。相关实现与测试可直接在仓库的 internal/tools/looker/lookercreatedashboardlayout/ 目录中查阅，预置配置可参考 internal/prebuiltconfigs/tools/looker.yaml。
【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
