企业官网建设流程全解析

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-toolbox

looker-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 表：

使用要点：

• type必须严格等于looker-get-projects，它是工具在注册表中的唯一资源类型标识；
• source指向一个已定义的looker类型 source（例如名为looker-source的实例配置），工具运行时将从该 source 获取 Looker SDK；
• description是必填项，其内容会原样传递给 LLM（作为 MCP 工具描述），官方建议在其中同时说明"无参数"和"返回 project_id / project_name 数组"这两个关键信息，以便模型正确决定何时调用该工具；
• 该配置不包含annotations字段时，会由框架自动套用只读注解（见下文源码分析）。

结合预置配置使用

仓库中 internal/prebuiltconfigs/tools/looker-dev.yaml 的 Looker 开发工具集预置配置也包含了完全一致的get_projects声明（同文件的 100～115 行），并且随后声明的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方法按以下步骤执行：

1. 从sources.Source断言出兼容的 Looker source（需实现compatibleSource接口，包含LookerApiSettings()与GetLookerSDK()等方法），不兼容时报 500 错误；
2. 通过source.GetLookerSDK(ctx, accessToken)获取 Looker SDK v4 客户端；
3. 调用sdk.AllProjects("id,name", source.LookerApiSettings())拉取全部项目——注意这里显式指定了fields="id,name"，只请求最少量的字段以降低响应开销；
4. 遍历响应，将每个项目映射为{"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() bool
• GetAuthTokenHeaderName() string
• LookerApiSettings() *rtl.ApiSettings
• GetLookerSDK(context.Context, string) (*v4.LookerSDK, error)

对应到 internal/sources/looker/looker.go 中的 Looker source 实现，它支持两种鉴权模式，由 source 配置项use_client_oauth决定：

• 服务账号模式（默认，use_client_oauth: false）：source 初始化时必须提供client_id与client_secret，SDK 通过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.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}

将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