企业官网建设流程全解析

MCP Toolbox 中 looker-update-agent 工具实战：用 Looker Go SDK 更新 Conversation Analytics Agent

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

本文是 mcp-toolbox（MCP Toolbox for Databases）Looker 集成系列中关于looker-update-agent工具的技术指南。该工具为 LLM 提供更新已有 Looker Agent 的 MCP 能力，支持修改名称、描述、系统提示词（instructions）、数据源（sources）与代码解释器开关等核心配置。读完本文，你将掌握该工具的全部参数语义、server.yaml声明方法、底层 SDK 调用链与错误处理行为，并能在自己的 MCP Server 配置中直接落地使用。

工具概述：让 LLM 具备 Looker Agent 的"改写"能力

looker-update-agent是 mcp-toolbox 中面向 Looker Conversational Analytics（对话式数据分析）场景的管理类工具。它允许 LLM 通过一次 MCP 调用，对 Looker 实例中已存在的 Agent 进行更新。与只读查询工具不同，它是一个写操作工具：从源码来看，其ReadOnlyHint被显式设置为false（见 lookerupdateagent.go），MCP 客户端据此可将其标记为会产生副作用的调用，从而决定是否需要人工确认。

该工具与looker-create-agent、looker-get-agent、looker-list-agents、looker-delete-agent共同构成完整的 Agent 生命周期管理工具族（源码目录见 internal/tools/looker）。典型应用场景包括：

• 对话式分析 Agent 上线后，根据业务反馈迭代其 system prompt；
• 为 Agent 增删可查询的 model/explore 组合，控制其数据访问范围；
• 批量调整 Agent 的名称与描述，保持元数据可维护。

参数详解：六个参数的语义与源码校验逻辑

looker-update-agent共暴露 6 个 MCP 参数，全部由Initialize阶段通过参数构造器注册（见 lookerupdateagent.go），并在调用时以 JSON 形式传入：

典型调用载荷：

{ "name": "looker-update-agent", "parameters": { "agent_id": "123", "name": "Updated Agent Name" } }

从源码可以提炼出几个容易被忽视的实现细节：

1. agent_id是硬性必填：源码在构造v4.WriteAgent请求体之前，会先检查agentId == ""，一旦缺失立即返回400 Bad Request，错误信息为looker-update-agent operation: agent_id must be specified（见 lookerupdateagent.go）。这一点也被单元测试TestInvokeValidation的missing agent_id用例验证（见 lookerupdateagent_test.go）。
2. 其余参数均为增量更新语义：name、description、instructions只在非空时才写入请求体v4.WriteAgent；sources仅在长度大于 0 时赋值；code_interpreter只有在显式传入时才写入（见 lookerupdateagent.go）。这意味着更新操作是"补丁式"的——你只需传想修改的字段，未传入字段保持原样。
3. sources的严格结构校验：数组中的每个元素必须是包含model与explore两个字符串键的 JSON 对象，二者缺失或类型错误都会直接报错invalid source format: expected model of type string（见 lookerupdateagent.go），对应测试用例见 lookerupdateagent_test.go。
4. instructions映射到Context：Looker SDK 中 Agent 的系统提示词字段位于Context.Instructions，源码将其显式构造为v4.Context{Instructions: &instructions}（见 lookerupdateagent.go）。

server.yaml 配置：工具声明与 Looker Source 定义

使用该工具的第一步，是在 MCP Server 的server.yaml中声明工具。原始文档给出的最小声明如下：

kind: tool name: update_agent type: looker-update-agent source: my-looker-instance description: | Update a Looker agent. - `agent_id` (string): The ID of the agent. - `name` (string): The name of the agent. - `description` (string): The description of the agent. - `instructions` (string): The instructions (system prompt) for the agent. - `sources` (array): Optional. A list of JSON-encoded data sources for the agent (e.g., `[{"model": "my_model", "explore": "my_explore"}]`). - `code_interpreter` (boolean): Optional. Enables Code Interpreter for this Agent.

配置字段速查表：

其中的description不仅是文档，更是 LLM 的"使用说明书"——它会被完整注入 MCP 工具清单（manifest），指导模型正确填充参数，因此在编写时应像上面示例一样逐参数说明类型与取值方式。若description为空，工具初始化会直接失败并返回description is required for tool %q错误（见 lookerupdateagent.go）。

source指向的 Looker 实例需要在同一server.yaml中用kind: source定义。仓库预置配置 looker-conversational-analytics.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} project: ${LOOKER_PROJECT:} location: ${LOOKER_LOCATION:}

从 looker.go 的源码可以看到这些字段的默认值：verify_ssl默认true、timeout默认600s、use_client_oauth默认"false"、location默认"us"、会话长度默认1200秒。需要注意的认证前提是：当use_client_oauth为false（默认）时，必须同时提供client_id与client_secret，否则 Source 初始化会报错（见 looker.go）。环境变量形式${VAR:default}支持在未设置环境变量时优雅回退到默认值。

源码级原理：从 MCP 参数到 Looker SDK 的 UpdateAgent

理解该工具的调用链，有助于排查权限与错误问题。整体链路如下：

1. 注册与解析：工具类型"looker-update-agent"在包init()中通过tools.Register(resourceType, newConfig)注册（见 lookerupdateagent.go），server.yaml中kind: tool的配置块由newConfig用 YAML decoder 解析为Config结构体。
2. Source 兼容性校验：ValidateSource检查source指向的实例是否实现了compatibleSource接口（UseClientAuthorization、GetAuthTokenHeaderName、LookerApiSettings、GetLookerSDK四个方法，见 lookerupdateagent.go）。Looker 类型的 Source 天然满足该接口（见 looker.go），而其他数据库类型的 Source 则会被拒绝并提示"not a compatible type"。
3. SDK 获取与鉴权：Invoke中通过source.GetLookerSDK(ctx, string(accessToken))获取 Looker Go SDK 实例（v4 版本）。从 looker.go 可知，当启用客户端授权（use_client_oauth）时，传入的accessToken会通过自定义transportWithAuthHeader注入请求头；否则走 SDK 内置的 API Key 认证会话。
4. 构造请求体并调用：工具将参数组装为v4.WriteAgent后调用sdk.UpdateAgent(agentId, body, "", source.LookerApiSettings())（见 lookerupdateagent.go），成功后直接返回 Looker API 的响应体。
5. 错误处理：若 SDK 返回包含status=401的错误，工具统一转换为401 Unauthorized的 MCP 错误，方便客户端识别鉴权失败；其他错误则走util.ProcessGeneralError归一化处理（见 lookerupdateagent.go）。

测试验证：单元测试与集成测试如何保证行为

该工具的行为在仓库中有两层测试保障：

• 单元测试（lookerupdateagent_test.go）覆盖四个维度：
  • TestParseFromYaml：验证kind: tool+type: looker-update-agent的最小 YAML 能正确解析为Config（name、type、source、description）；
  • TestFailParseFromYaml：验证未知字段（如method）会导致解析失败，保证配置严格性；
  • TestInvokeValidation：通过 MockSource 验证agent_id缺失、sources元素格式错误时的报错信息；
  • TestManifest与TestAnnotations：验证工具清单中必须包含agent_id、name、instructions、sources、code_interpreter等参数，并确认ReadOnlyHint恒为false。
• 集成测试（tests/looker/looker_integration_test.go 与 L2515）：在真实 Looker 实例上注册update_agent工具，并通过tests.RunToolInvokeParametersTest传入{"agent_id": "<id>", "sources": [{"model": "system__activity", "explore": "history"}]}这样的真实参数，验证端到端调用成功。

实战建议与注意事项

• 获取agent_id的路径：先通过looker-list-agents枚举现有 Agent，或用looker-get-agent查询单个 Agent 的详细信息，再将其 ID 传给本工具，避免凭记忆硬编码数字 ID。
• sources的取值来源：可查询的 model/explore 组合可通过looker-get-models与looker-get-explores发现（见 looker-conversational-analytics.yaml 中ask_data_insights的用法说明），这与 Conversation Analytics 问答工具的数据源口径完全一致。
• 权限边界：更新 Agent 需要对应的 Looker API 权限，若使用客户端 OAuth 需保证传入的令牌具备写权限；遇到 401 时工具会明确返回未授权错误，便于快速定位。
• 增量更新语义：由于只有非空参数才会写入请求体，做"部分更新"时不要显式传空字符串，否则该字段会被忽略而不会清空——如需清空某字段，请检查 Looker API 对该字段的语义支持后再操作。

<输出文章>

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