MCP Toolbox 的 alloydb-ai-nl 工具让 Agent 用自然语言直连 AlloyDB 查询数据库【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox导读alloydb-ai-nl是 MCP Toolbox for Databases 提供的专用工具类型它接入 AlloyDB AI 的新一代自然语言Natural Language能力允许 AI Agent 直接用自然语言向 AlloyDB 集群提问由数据库自身负责把问题转换为 SQL 并执行。本文以 alloydb-ai-nl 工具文档 为主线完整讲解该工具的适用前提、nl_config配置方法、参数化安全视图PSV参数绑定、YAML 配置示例与字段参考并结合 源码实现 与 测试用例 说明其底层原理。读完本文你将掌握如何在自己的 MCP Toolbox 配置中落地一个安全、可复用的自然语言查询工具。About什么是 alloydb-ai-nlalloydb-ai-nl工具让 Agent 直接以自然语言查询数据库。它的核心价值在于把“自然语言转 SQL”的复杂度从应用层下沉到数据库层从而显著简化生成式 AI 应用的开发流程。其工作方式可以概括为Agent 收到用户提问后调用alloydb-ai-nl工具工具携带问题文本与一个预先配置好的nl_config自然语言配置AlloyDB 端通过alloydb_ai_nl.execute_nl_query函数完成「自然语言 → SQL 生成 → 执行」的完整闭环最后把查询结果返回给 Agent。AlloyDB AI 自然语言能力为应用终端用户的自然语言提问提供安全、准确的回答。从源码角度看该工具类型在 internal/tools/alloydbainl/alloydbainl.go 中注册resourceType为alloydb-ai-nl并在init()中通过tools.Register(resourceType, newConfig)完成类型注册因此可以在 YAML 配置中直接以type: alloydb-ai-nl声明。兼容的 Source数据源alloydb-ai-nl必须在 AlloyDB 数据源之上运行。源码中定义了一个compatibleSource接口type compatibleSource interface { PostgresPool() *pgxpool.Pool RunSQL(context.Context, string, []any) (any, error) }凡是实现该接口的 Source 均可与alloydb-ai-nl组合使用。在 internal/sources/alloydbpg/alloydb_pg.go 中alloydb-postgres类型的 Source 同时实现了PostgresPool()与RunSQL()因此它是该工具最直接、也是最主要的兼容数据源。工具初始化阶段会对 Source 做类型校验见 alloydbainl.go 的 ValidateSource如果配置中指定的source不是兼容类型会返回类似source %q is not a compatible type的报错调用阶段Invoke也会再次断言不兼容则返回 500 错误。也就是说在配置alloydb-ai-nl工具前请先参照 AlloyDB Source 文档 配置一个type: alloydb-postgres的 source。前置条件Requirements使用该工具需要满足两类前置条件1. 在 AlloyDB 侧启用自然语言能力AlloyDB AI 自然语言目前处于受限公开预览gated public preview阶段可用性与限制请以 AlloyDB 官方文档为准。要在集群上启用该能力需要按照 AlloyDB 官方“使用自然语言生成 SQL 查询”的步骤操作主要包括启用扩展与**为应用配置上下文context**两部分。扩展名称为alloydb_ai_nl启用后才能调用其提供的execute_nl_query函数。2. 版本兼容性v1.0.3 与 Toolbox v0.19.0文档中特别强调了一个版本注意事项自AlloyDB AI NL v1.0.3起execute_nl_query的函数签名发生了更新Toolbox v0.19.0要求集群上的 AlloyDB AI NL 扩展版本v1.0.3 及以上如果你此前使用create_configuration操作配置过自然语言配置升级到 Toolbox v0.19.0 后必须删除旧配置并按照新签名重新创建。可以使用下面这条 SQL 检查实例当前的扩展版本SELECT extversion FROM pg_extension WHERE extname alloydb_ai_nl;这一约束也体现在源码中当RunSQL执行失败时错误信息会提示 “Toolbox v0.19.0 is only compatible with AlloyDB AI NL v1.0.3. Please ensure that you are using the latest AlloyDB AI NL extension”见 alloydbainl.go帮助用户快速定位版本不匹配问题。配置详解指定 nl_config把应用与上下文关联起来nl_config是一种把应用与数据库 schema 对象、示例及其他可被使用的上下文关联起来的配置。对于大型应用还可以为不同模块配置不同的nl_config只要在对应模块发起提问时指定正确的配置即可。一旦你在 AlloyDB 侧完成了上下文配置就可以在 Toolbox 的工具配置中使用nlConfig字段引用它。当alloydb-ai-nl工具被调用时Toolbox 会把该配置作为nl_config_id传给execute_nl_querySQL 的生成与执行都会基于这份上下文进行。对应源码见 alloydbainl.go 的 Config 结构体其中NLConfig字段标注为validate:required即该字段为必填。为参数化安全视图PSV指定参数Parameterized Secure Views参数化安全视图PSV是 AlloyDB 独有的特性它要求查询该视图时必须传入一个或多个命名参数值类似于普通 SQL 查询中的绑定变量bind variables从而在行级或字段级实现更精细的访问控制。在alloydb-ai-nl中通过nlConfigParameters列出nl_config所需的参数你必须为上下文中所有 PSV 用到的参数提供值由于这些参数对 LLM 不可见强烈建议配合Authenticated Parameters认证参数或Bound Parameters绑定参数使用为自然语言生成的查询提供安全访问通道防止 LLM 自行编造参数值。提示要使用 PSV 特性即nlConfigParameters请先在 AlloyDB Studio 中启用parameterized_views扩展CREATE EXTENSION IF NOT EXISTS parameterized_views;关于 Authenticated 与 Bound 参数的详细说明可参见 工具配置文档 中的对应章节Authenticated Parameters 会自动从请求头中携带的 ID token 解码出用户信息来填充参数值通过authServices把认证服务映射到 OIDC token 中的特定 claim如sub、email而 Secure/Bound Parameters 则让参数值在客户端绑定、与 LLM 上下文隔离。完整配置示例以下是一个把alloydb-ai-nl用于航班信息查询的完整示例kind: tool name: ask_questions type: alloydb-ai-nl source: my-alloydb-source description: Ask questions to check information about flights nlConfig: cymbal_air_nl_config nlConfigParameters: - name: user_email type: string description: User ID of the logged in user. # note: we strongly recommend using features like Authenticated or # Bound parameters to prevent the LLM from seeing these params and # specifying values it shouldnt in the tool input authServices: - name: my_google_service field: email该示例中user_email参数对应cymbal_air_nl_config上下文中某个 PSV 所需的参数。由于配置了authServices这个参数不会出现在 LLM 可见的 tool input 中而是由 Toolbox 在调用时从用户 ID token 的emailclaim 自动填充从而保证“每个用户只能通过自然语言查询到自己权限范围内的数据”。在 alloydbainl_test.go 的 TestParseFromYamlAlloyDBNLA 中可以看到对上述配置结构的解析测试支持单个参数、多个参数、authRequired、authServices等多种组合验证了 YAML 配置能被正确解析为alloydbainl.Config。底层实现工具调用时发生了什么当工具被调用时Tool.Invoke 会执行以下步骤校验source是否实现compatibleSource接口将参数按顺序组装$1是自然语言问题question$2是nlConfig其后的$3、$4…依次对应nlConfigParameters中声明的 PSV 参数值调用source.RunSQL执行构造好的 SQL并返回结果。初始化阶段Initialize会根据是否声明了nlConfigParameters构造不同的 SQL 模板无参数时SELECT alloydb_ai_nl.execute_nl_query(nl_question $1, nl_config_id $2);有参数时参数名与占位符会分别组装为ARRAYSELECT alloydb_ai_nl.execute_nl_query(nl_question $1, nl_config_id $2, param_names ARRAY[user_email], param_values $3);例如文档示例的 SQL 形态见 alloydbainl.go 源码注释SELECT alloydb_ai_nl.execute_nl_query(nl_question How many tickets do I have?, nl_config_id cymbal_air_nl_config, param_names ARRAY [user_email], param_values ARRAY [hailongligoogle.com]);同时question参数会被自动插入到工具参数清单的最前面描述为 “The natural language question to ask.”作为该工具暴露给 LLM 的唯一输入。工具默认采用只读注解tools.NewReadOnlyAnnotations见 alloydbainl.go并支持通过annotations字段覆盖authRequired可用于强制要求调用方携带认证信息。集成测试验证仓库提供了针对该工具端到端的集成测试见 tests/alloydbainl/alloydb_ai_nl_integration_test.goHTTP API 层面通过GET /api/tool/my-simple-tool/验证工具元信息仅暴露question参数通过POST /api/tool/name/invoke验证自然语言问题的实际执行结果认证参数层面测试了携带有效 Google ID token 时my-auth-tool返回用户信息{name:Alice}而携带无效 token 或不带 token 时调用失败验证了authServices参数注入与鉴权链路MCP 协议层面通过tools/call方法JSON-RPC 2.0调用工具并校验返回的content[0].text同时验证了缺少question参数时返回parameter question is required的错误。这些测试从实际行为上印证了文档中描述的配置语义nlConfig决定执行上下文nlConfigParameters通过认证服务注入用户相关参数最终调用execute_nl_query完成自然语言查询。字段参考ReferencefieldtyperequireddescriptiontypestringtrueMust be alloydb-ai-nl.sourcestringtrueName of the AlloyDB source the natural language query should execute on.descriptionstringtrueDescription of the tool that is passed to the LLM.nlConfigstringtrueThe name of thenl_configin AlloyDBnlConfigParametersparameterstrueList of PSV parameters defined in thenl_config各字段要点type必须为alloydb-ai-nlsource必须是兼容的 AlloyDB 数据源名称即alloydb-postgres类型工具会校验其兼容性description会作为工具描述传递给 LLM用于帮助模型判断何时调用该工具nlConfig对应 AlloyDB 中已配置好的自然语言配置名称必填nlConfigParameters列出nl_config上下文里所有 PSV 所需参数支持authServices等安全注入方式工具初始化时若发现声明了参数会自动为其构造param_names/param_values的调用形式。小结与使用建议先在 AlloyDB 集群上启用alloydb_ai_nl扩展、完成上下文nl_config配置并确认扩展版本不低于 v1.0.3Toolbox 版本不低于 v0.19.0在 Toolbox 中先配置type: alloydb-postgres的 source再配置type: alloydb-ai-nl的工具只要nl_config中涉及 PSV就务必通过nlConfigParameters声明全部参数并优先使用 Authenticated / Bound 参数等安全机制让参数对 LLM 不可见、由系统在服务端或客户端侧注入需要为同一应用的不同模块提供不同语义上下文时可以配置多个nl_config并分别为它们创建alloydb-ai-nl工具。通过alloydb-ai-nlAgent 可以跳过手写 SQL 的环节直接面向业务问题提问同时借助 AlloyDB 侧的权限模型与 Toolbox 侧的参数安全机制兼顾开发效率与数据安全。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考