MCP Toolbox 实战：looker-get-projects 工具详解——列出 Looker 实例的全部 LookML 项目

MCP Toolbox 实战looker-get-projects 工具详解——列出 Looker 实例的全部 LookML 项目【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxlooker-get-projects是 MCP Toolbox for Databases 中 Looker 集成套件的核心工具之一用于一次性获取指定 Looker 实例上所有 LookML 项目的清单。本文以该工具的官方文档为主体结合仓库内 Go 源码、单元测试与预置配置完整讲解其 YAML 配置方式、底层调用链、鉴权机制与输出格式帮助你将其正确接入自己的 MCP 服务配置并在 Agent 工作流中利用项目清单驱动后续的 LookML 文件读取与修改操作。工具定位与适用场景在 MCP Toolbox 的 Looker 工具集中looker-get-projects负责回答一个基础但关键的问题当前 Looker 实例上有哪些 LookML 项目LookML 项目Project是 Looker 中承载模型定义、视图定义与探索Explore配置的代码单元。无论是检索项目文件、还是对项目进行修改通常都需要先知道目标项目的唯一标识。从官方文档的描述看该工具正是服务于先识别项目、再执行后续动作这一前置环节It is useful for identifying projects before performing actions like retrieving project files or making modifications.从仓库源码结构观察Looker 工具集中与项目相关的下游工具还有looker-get-project-files列出项目内 LookML 文件、looker-get-project-file读取单个文件、looker-create-project-file、looker-update-project-file等它们都以project_id作为必填参数而该参数正是来自get_projects的输出因此它在整个工具链中承担着入口导航的角色。配置方法YAML 声明一个零参数工具looker-get-projects最大的特点是不接受任何参数——调用时无需传入任何请求参数直接返回结果。官方文档给出的标准配置示例如下kind: tool name: get_projects type: looker-get-projects source: looker-source description: | This tool retrieves a list of all LookML projects available on the Looker instance. It is useful for identifying projects before performing actions like retrieving project files or making modifications. Parameters: This tool takes no parameters. Output: A JSON array of objects, each containing the project_id and project_name for a LookML project.其中各字段的含义与要求见官方文档的 Reference 表fieldtyperequireddescriptiontypestringtrueMust be looker-get-projects.sourcestringtrueName of the source Looker instance.descriptionstringtrueDescription of the tool that is passed to the LLM.使用要点type必须严格等于looker-get-projects它是工具在注册表中的唯一资源类型标识source指向一个已定义的looker类型 source例如名为looker-source的实例配置工具运行时将从该 source 获取 Looker SDKdescription是必填项其内容会原样传递给 LLM作为 MCP 工具描述官方建议在其中同时说明无参数和返回 project_id / project_name 数组这两个关键信息以便模型正确决定何时调用该工具该配置不包含annotations字段时会由框架自动套用只读注解见下文源码分析。结合预置配置使用仓库中 internal/prebuiltconfigs/tools/looker-dev.yaml 的 Looker 开发工具集预置配置也包含了完全一致的get_projects声明同文件的 100115 行并且随后声明的get_project_files、get_project_file等工具均以project_id (required): The unique ID of the LookML project, obtained from get_projects的方式引用其输出印证了它作为项目操作前置入口的定位。可以直接复用该预置配置或将其中的工具段复制到自己的配置文件中。底层实现从配置解析到 SDK 调用的完整链路该工具的 Go 实现位于 internal/tools/looker/lookergetprojects/lookergetprojects.go整个调用链可以分为三个环节。1. 配置结构与校验工具的配置结构体Config内联了tools.ConfigBase并声明了三个字段type Config struct { tools.ConfigBase yaml:,inline Type string yaml:type validate:required Source string yaml:source validate:required Annotations *tools.ToolAnnotations yaml:annotations,omitempty }其中Type与Source都带validate:required与文档 Reference 表中必填的约束一一对应。Annotations可选在Initialize中若未显式提供注解框架会调用tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewReadOnlyAnnotations)自动套用只读工具注解——这与工具只读语义仅查询项目列表是一致的。2. 初始化阶段无参数声明Initialize方法构建了一个空的parameters.Parameters{}实例并通过allParameters.Manifest()生成工具的参数清单。由于集合为空最终暴露给 LLM 的工具签名就是零参数这与官方文档accepts no parameters的表述完全吻合。Initialize还强制要求Description非空否则返回description is required for tool错误。3. 调用阶段AllProjects API 与输出映射工具被调用时Invoke方法按以下步骤执行从sources.Source断言出兼容的 Looker source需实现compatibleSource接口包含LookerApiSettings()与GetLookerSDK()等方法不兼容时报 500 错误通过source.GetLookerSDK(ctx, accessToken)获取 Looker SDK v4 客户端调用sdk.AllProjects(id,name, source.LookerApiSettings())拉取全部项目——注意这里显式指定了fieldsid,name只请求最少量的字段以降低响应开销遍历响应将每个项目映射为{project_id: id, project_name: name}形式的 JSON 对象并聚合成数组返回。其中鉴权相关的两个接口RequiresClientAuthorization与GetAuthTokenHeaderName均委托给 source 实现意味着该工具天然支持 Looker 的两种接入模式见下文。此外如果 Looker API 返回 401源码会将错误归一化为http.StatusUnauthorized的unauthorized error便于上层统一处理。测试验证仓库中的 internal/tools/looker/lookergetprojects/lookergetprojects_test.go 提供了两组单元测试TestParseFromYamlLookerGetProjects验证一份合法的 YAML含name、type: looker-get-projects、source、description能够被正确解析为lkr.Config包括AuthRequired: []string{}的空鉴权声明TestFailParseFromYamlLookerGetProjecProjects验证当 YAML 中出现未知字段如method: GOT时解析会失败并报告unknown field method错误说明该工具的配置模式是严格受控的不允许额外字段。这两组测试可作为你验证自建配置格式是否合法时的参考。兼容的 Source 与鉴权模式工具的compatibleSource接口要求 source 至少提供UseClientAuthorization() boolGetAuthTokenHeaderName() stringLookerApiSettings() *rtl.ApiSettingsGetLookerSDK(context.Context, string) (*v4.LookerSDK, error)对应到 internal/sources/looker/looker.go 中的 Looker source 实现它支持两种鉴权模式由 source 配置项use_client_oauth决定服务账号模式默认use_client_oauth: falsesource 初始化时必须提供client_id与client_secretSDK 通过rtl.NewAuthSession自动完成 OAuth 登录GetLookerSDK直接返回复用的s.LookerClient()客户端授权模式use_client_oauth: true每次请求由 MCP 客户端携带访问令牌GetLookerSDK会基于当前请求的 token 动态构造 SDK通过transportWithAuthHeader注入Authorization头并在缺少 token 时返回 no access token supplied with request。一个典型的 Looker source 配置形如 internal/prebuiltconfigs/tools/looker.yamlkind: 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-get-projects工具段的source: looker-source指向该 source 即可完成对接base_url、client_id、client_secret等敏感项建议通过环境变量注入。输出格式与 LLM 工作流中的典型用法looker-get-projects的输出为JSON 数组数组元素为包含两个键的对象[ { project_id: ecommerce, project_name: ecommerce }, { project_id: jaffle_shop, project_name: jaffle_shop } ]project_id项目的唯一标识后续调用get_project_files、get_project_file、create_project_file、update_project_file等工具时作为必填参数使用project_name项目名称通常与project_id相同。在 Agent 工作流中典型调用序列是get_projects先枚举可用项目 → 选定project_id后调用get_project_files查看项目内文件 → 再通过get_project_file读取具体文件内容。官方文档中工具描述也明确建议在获取项目文件或进行修改之前先调用本工具完成项目识别这正是 LLM 判断调用时机的重要语义线索。小结looker-get-projects是 MCP Toolbox Looker 集成中一个小而专的导航型工具零参数、只读、输出结构简单却是整个 LookML 项目操作链路的起点。通过本文的 YAML 配置示例、Reference 字段约束、Go 源码调用链AllProjects(id,name)到project_id/project_name映射以及预置配置与单元测试的佐证你可以快速将其纳入自己的 MCP 配置并让 Agent 在需要操作 LookML 项目文件时拥有可靠的项目清单来源。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考