MCP Toolbox 中的 cloud-sql-get-instance 工具通过 Cloud SQL Admin API 获取实例资源的配置与源码解析【免费下载链接】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 中的cloud-sql-get-instance工具展开说明如何通过 YAML 配置定义该工具、如何声明cloud-sql-admin数据源并选择认证方式并结合仓库源码讲解工具在运行时如何解析参数、调用 Cloud SQL Admin API以及集成测试如何验证其真实行为。读完后你将能够独立配置出可用的实例查询工具并理解其参数注入、错误处理与 OAuth 模式下的鉴权链路。工具简介cloud-sql-get-instance 是什么cloud-sql-get-instance是 MCP Toolbox 提供的一款只读管理工具它通过 Cloud SQL Admin API 获取一个 Cloud SQL 实例资源DatabaseInstance的完整信息。典型使用场景包括Agent 在创建、克隆或备份实例后确认实例的最终状态state、ipAddresses、settings等运维排查时快速拉取实例的规格、区域、数据库版本等元数据作为cloud-sql-list-instances列出实例的下钻动作先列表、再按instanceId精确获取。从源码结构看该工具在 internal/tools/cloudsql/cloudsqlgetinstances/cloudsqlgetinstances.go 中注册const resourceType string cloud-sql-get-instance func init() { if !tools.Register(resourceType, newConfig) { panic(fmt.Sprintf(tool type %q already registered, resourceType)) } }即 YAML 配置中type: cloud-sql-get-instance会经由全局注册表被映射到这个Config解析器。工具在Initialize中默认使用描述Gets a particular cloud sql instance.并通过tools.NewReadOnlyAnnotations为其打上只读注解供支持注解的 MCP 客户端识别这是一个不会修改基础设施的操作。前置声明 cloud-sql-admin 数据源cloud-sql-get-instance工具必须绑定一个cloud-sql-admin类型的 source。该 source 负责持有 Cloud SQL Admin API 客户端支持两种认证方式见 docs/en/integrations/cloud-sql-admin/source.mdApplication Default CredentialsADC默认行为服务端本地读取 ADC 完成鉴权客户端 OAuthuseClientOAuth: true时每个请求由客户端如浏览器提供 OAuth 2.0 access token。source 配置示例kind: source name: my-cloud-sql-admin-source type: cloud-sql-admin defaultProject: my-gcp-project --- kind: source name: my-oauth-cloud-sql-admin-source type: cloud-sql-admin useClientOAuth: true各字段说明与 source 文档保持一致字段类型必填说明typestringtrue必须为cloud-sql-admindefaultProjectstringfalse用于 Cloud SQL 基础设施工具的 Google Cloud 项目 IDuseClientOAuthbooleanfalse为true时使用客户端 OAuth 鉴权否则使用 ADC。默认falsereadOnlybooleanfalse为true时抑制具有写能力的管理工具。默认false对应源码见 internal/sources/cloudsqladmin/cloud_sql_admin.goConfig.Initialize中若UseClientOAuth为true则只创建携带 User-Agent 的普通http.Clienttoken 由每次请求注入否则调用google.FindDefaultCredentials(ctx, sqladmin.SqlserviceAdminScope)以 ADC 构建 oauth2 客户端最终封装为sqladmin.Service并指向https://sqladmin.googleapis.com。工具配置完整字段与示例基础配置示例kind: tool name: get-sql-instance type: cloud-sql-get-instance source: my-cloud-sql-admin-source description: Gets a particular cloud sql instance.字段参考字段类型必填说明typestringtrue必须为cloud-sql-get-instancesourcestringtrue要使用的cloud-sql-adminsource 名称descriptionstringfalse工具描述缺省时源码会回填默认描述 Gets a particular cloud sql instance.其中name与description来自内联的tools.ConfigBase见工具源码中的Config结构体cloudsqlgetinstances.gotype与source均带有validate:required标签配置缺失时会在启动阶段报解析/校验错误这一点由单测 internal/tools/cloudsql/cloudsqlgetinstances/cloudsqlgetinstances_test.go 中的 YAML 反序列化用例覆盖kind: tool name: get-instances type: cloud-sql-get-instance description: A tool to get cloud sql instances source: my-gcp-source运行时参数工具暴露两个调用参数均在buildParams中定义cloudsqlgetinstances.go#L85-L94参数类型必填说明projectIdstring是Google Cloud 项目 IDinstanceIdstring是Cloud SQL 实例 ID一个重要的设计细节是defaultProject的预置机制当 source 配置了defaultProject时GetParameters会调用buildParams(s.GetDefaultProject())此时projectId参数会带上默认值并且描述被改写为The GCP project ID. This is pre-configured; do not ask for it unless the user explicitly provides a different one.也就是说Agent 侧的 MCP 客户端看到的工具 schema 会直接携带项目默认值减少 Agent 反复追问项目 ID 的情况未配置defaultProject时projectId则是纯必填参数。调用链路与源码解析工具的实际执行逻辑在Invoke方法中cloudsqlgetinstances.go#L141-L161完整调用链如下兼容性检查将传入的 source 断言为compatibleSource接口要求实现GetDefaultProject、UseClientAuthorization、GetInstance三个方法不匹配则返回 500 类错误说明source 与工具不兼容参数校验从params.AsMap()中取出projectId与instanceId缺失时返回AgentErrormissing projectId parameter / missing instanceId parameter。这类错误在 MCP 语义上会被标记为可由 Agent 自行修正从而提示调用方补齐参数而不是直接失败API 调用委托给 source 的GetInstance方法cloud_sql_admin.go#L228-L239func (s *Source) GetInstance(ctx context.Context, projectId, instanceId, accessToken string) (any, error) { service, err : s.GetService(ctx, accessToken) if err ! nil { return nil, err } resp, err : service.Instances.Get(projectId, instanceId).Do() if err ! nil { return nil, fmt.Errorf(error getting instance: %w, err) } return resp, nil }即最终发起的是GET /v1/projects/{projectId}/instances/{instanceId}请求返回完整的sqladmin.DatabaseInstance资源 4.错误转译工具层通过util.ProcessGcpError(err)将 GCP API 错误转译为 Toolbox 的标准错误类型保留 HTTP 语义如 404 对应实例不存在。OAuth 模式下的服务实例重建也值得注意GetService中若 source 启用了UseClientOAuth每次请求都会用当前调用携带的accessToken构造oauth2.StaticTokenSource并新建一个sqladmin.ServiceADC 模式则直接复用初始化时创建的 service 实例。这保证了多用户/多会话场景下每个请求使用各自的令牌。与相邻工具的区分Cloud SQL Admin 集成下另有cloud-sql-list-instances列出项目内实例返回精简的name/instanceType列表和各类写操作工具创建实例、克隆、备份等见 docs/en/integrations/cloud-sql-admin/tools/_index.md 所在目录。cloud-sql-get-instance的定位是按 ID 精确获取单个实例的完整资源是列表工具之后的细节查询入口。仓库内的预置配置参考在预置工具集 internal/prebuiltconfigs/tools/cloud-sql-postgres-admin.yaml 中可以看到该工具的标准姿势kind: source name: cloud-sql-admin-source type: cloud-sql-admin defaultProject: ${CLOUD_SQL_POSTGRES_PROJECT:} readOnly: ${CLOUD_SQL_POSTGRES_READONLY:false} --- kind: tool name: get_instance type: cloud-sql-get-instance source: cloud-sql-admin-source --- kind: tool name: list_instances type: cloud-sql-list-instances source: cloud-sql-admin-source其中defaultProject与readOnly均通过环境变量CLOUD_SQL_POSTGRES_PROJECT、CLOUD_SQL_POSTGRES_READONLY注入并带默认空值适合容器化部署。同样的cloud-sql-get-instance也出现在 cloud-sql-mysql-admin.yaml、cloud-sql-mssql-admin.yaml、cloud-sql-postgres.yaml 等预置配置中说明它是各数据库引擎管理工具集的通用成员。集成测试如何验证该工具tests/cloudsql/cloud_sql_get_instances_test.go 提供了端到端验证方式使用httptest搭建一个假的 Admin API 服务并通过自定义RoundTripper把发往https://sqladmin.googleapis.com的请求重定向到本地测试服务测试 handler 会校验请求头中携带genai-toolbox/前缀的 User-Agent并断言请求路径符合/v1/projects/{project}/instances/{instance}格式——这与GetInstance源码中的service.Instances.Get(projectId, instanceId).Do()相互印证两个用例分别覆盖成功与失败路径查询存在的instance-1返回{name:instance-1,kind:sql#instance}查询不存在的instance-2则预期非 200 状态。测试中的工具配置也展示了最小可用组合sources: my-cloud-sql-source: type: cloud-sql-admin tools: get-instance-1: type: cloud-sql-get-instance description: get instance 1 source: my-cloud-sql-source小结与实践要点配置三步走声明cloud-sql-adminsource确定 ADC 还是useClientOAuth→ 声明cloud-sql-get-instance工具并绑定 source → 启动后 Agent 以projectIdinstanceId调用若部署环境项目固定建议给 source 配置defaultProject源码会自动为该参数注入默认值并调整描述降低 Agent 交互成本该工具是只读的源码中默认使用NewReadOnlyAnnotations配合 source 的readOnly: true可以进一步收敛整个管理工具集的行为排障时可关注三类错误参数缺失AgentError提示补齐projectId/instanceId、source 类型不兼容配置了非cloud-sql-admin的 source、GCP API 错误经ProcessGcpError转译404 通常意味着实例不存在或项目 ID 有误。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考