mcp-toolbox bigtable-sql 工具详解用 GoogleSQL 参数化查询为 LLM 安全接入 Cloud Bigtable【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本文基于 bigtable-sql 工具文档 展开讲解如何为 Google Cloud Bigtable 实例定义bigtable-sql类型工具通过 GoogleSQLDML语句让 LLM 查询宽列 NoSQL 数据同时结合 工具实现源码 与 Bigtable 数据源实现剖析其参数绑定、模板注入防护与结果集组装的底层流程帮助你安全地把 Bigtable 接入 MCPModel Context Protocol生态。读完本文你可以正确配置bigtable-sql工具的 YAML 定义理解statement、parameters、templateParameters各字段的语义与差异掌握 GoogleSQL 中参数名占位符的编写方式以及 Bigtable 特有的cf[col]、TO_INT64、CAST等列访问写法从源码层面理解声明式参数防注入与模板参数可改标识符有注入风险在执行链中的不同处理路径。关于 bigtable-sql 工具bigtable-sql工具用于对 Bigtable 实例执行一条预定义的 SQL 语句。Bigtable 支持 GoogleSQL 查询Toolbox 的 Bigtable 集成使用的正是googlesql方言statement字段中指定的 SQL 会作为 DMLData Manipulation Language语句 执行声明的参数会按名称插入——例如name这样的占位符。需要注意Bigtable 的 GoogleSQL 对 DML 语句的支持可能仅限于特定查询类型官方文档列出了受支持的 DML 语句与用例。由于 Bigtable 是宽列存储SQL 中需要通过cf[column_name]形式引用列族column family下的列并经常配合TO_INT64(...)、CAST(... AS string)等显式转换函数把原始字节值转换为可用类型。兼容的数据源该工具仅接受bigtable类型数据源。数据源定义见 Bigtable Source 文档如下kind: source name: my-bigtable-source type: bigtable project: my-project-id instance: test-instance字段类型必填说明typestringtrue必须为 bigtable。projectstringtrue实例所在的 GCP 项目 ID如 my-project-id。instancestringtrueBigtable 实例名称。从 数据源源码 可以看到Config结构体把project与instance标记为validate:requiredInitialize阶段会同时创建三类客户端用于数据面 SQL 执行的bigtable.Client默认 10 个 gRPC 连接的连接池见 initBigtableClient、用于实例管理的InstanceAdminClient和用于表管理的AdminClient。后两者服务于bigtable-create-table等其他管理工具而bigtable-sql实际只用到的就是BigtableClient()与RunSQL。工具侧的兼容性校验在 compatibleSource 接口 中定义type compatibleSource interface { BigtableClient() *bigtable.Client RunSQL(context.Context, string, parameters.Parameters, parameters.ParamValues) (any, error) }ValidateSource 会在配置加载时做类型断言如果source字段指向的不是 Bigtable 数据源工具会直接报错“source is not a compatible type”在启动期就拦截错误配置。示例参数化查询推荐文档给出的核心示例是一个按 ID 或姓名搜索用户的工具。该工具使用参数化查询防止 SQL 注入查询参数可以替代任意表达式但不能替代标识符、列名、表名或其他查询结构部分。kind: tool name: search_user_by_id_or_name type: bigtable-sql source: my-bigtable-instance statement: | SELECT TO_INT64(cf[ id ]) as id, CAST(cf[ name ] AS string) as name, FROM mytable WHERE TO_INT64(cf[ id ]) id OR CAST(cf[ name ] AS string) name; description: | Use this tool to get information for a specific user. Takes an id number or a name and returns info on the user. Example: {{ id: 123, name: Alice, }} parameters: - name: id type: integer description: User ID - name: name type: string description: Name of the user这个示例包含几个值得展开的要点GoogleSQL 的列引用语法cf[id]表示列族cf下名为id的列。Bigtable 原始存储无类型所以WHERE子句里需要对id列做TO_INT64转换后与整数参数比较SELECT中的CAST(cf[name] AS string)则把字节值转成字符串输出。占位符id、name与parameters列表按名称一一对应。声明式参数最终会以 Bigtable 客户端的预编译语句prepared statement绑定参数形式执行参数值与 SQL 文本在物理上分离这正是防注入的关键。description 对 LLM 至关重要文档明确要求description是传递给 LLM 的工具描述示例中甚至嵌入了 JSON 调用样例帮助模型正确填充id/name参数。参数类型支持string、integer、float、boolean、array见 参数规范。在 Bigtable 侧这些类型会被映射为对应的 GoogleSQL 类型——getBigtableType 中的映射关系为boolean→BoolSQLType、string→StringSQLType、integer→Int64SQLType、float→Float64SQLType、array→ArraySQLType其元素类型由items.type决定见 getMapParamsType。示例模板参数谨慎使用当需要在查询中动态指定表名、列名等标识符时可以使用templateParameters。文档明确警告模板参数允许直接改写 SQL 语句包括标识符、列名、表名会使工具更容易遭受 SQL 注入。出于性能与安全考虑官方推荐使用普通参数kind: tool name: list_table type: bigtable-sql source: my-bigtable-instance statement: | SELECT * FROM {{.tableName}}; description: | Use this tool to list all information from a specific table. Example: {{ tableName: flights, }} templateParameters: - name: tableName type: string description: Table to select from注意 statement 中使用的是 Go template 语法{{.tableName}}而非 GoogleSQL 的参数占位符——两者作用于不同阶段模板参数在执行前对 SQL 文本做文本替换普通参数在执行时做值绑定。从源码执行链 Tool.Invoke 可以清晰看到这个两阶段顺序newStatement, err : parameters.ResolveTemplateParams(t.Cfg.TemplateParameters, t.Cfg.Statement, paramsMap) // ... newParams, err : parameters.GetParams(t.Cfg.Parameters, paramsMap) // ... resp, err : source.RunSQL(ctx, newStatement, t.Cfg.Parameters, newParams)ResolveTemplateParams先用模板参数渲染 statement得到最终 SQL 文本GetParams从入参中挑出声明过的普通参数RunSQL执行预编译绑定。单元测试 还验证了模板参数支持array类型如fieldArray指定返回哪些列说明模板替换同样可用于拼接列列表。字段参考字段类型必填说明typestringtrue必须为 bigtable-sql。sourcestringtrueSQL 执行所指向的数据源名称须为 bigtable 类型。descriptionstringtrue传递给 LLM 的工具描述。statementstringtrue要执行的 SQL 语句GoogleSQL 方言。parametersparametersfalse将插入 SQL 语句的参数列表按name绑定。templateParameterstemplateParametersfalse在执行预编译语句前插入 SQL 语句的模板参数列表文本替换有注入风险。补充说明两点源码层面的校验行为description在配置表中是必填的——Config.Initialize 会显式检查cfg.Description 并报错缺失描述的工具无法启动声明的parameters会被 ProcessParameters 统一处理后生成 MCP 工具 manifest 中的参数 schemaLLM 客户端据此生成结构化入参同时作为RunSQL预编译时的类型元数据来源。执行链深度剖析从 LLM 调用到结果集理解bigtable-sql的完整生命周期有助于排查问题。调用链如下工具注册init()中通过 tools.Register(bigtable-sql, newConfig) 注册类型名YAML 中的type: bigtable-sql据此路由到本工具的解析器配置解析newConfig用 YAML 解码器把配置块反序列化为Configstatement、source、parameters等字段的validate:required标签保证必填项完整执行与结果组装真正干活的是数据源侧的 Source.RunSQL。它的步骤是根据声明的参数构建map[string]bigtable.SQLType类型表PrepareStatement把 SQL 与类型表一起发给 Bigtable得到预编译语句句柄ps.Bind(params.AsMap())按名称绑定参数值——这里如果占位符与参数名不匹配如 SQL 写id但参数叫user_id绑定阶段即会失败bs.Execute逐行回调把每一行按列名读入map[string]any最终返回[]any即行列表这就是 MCP 工具返回给 LLM 的结构化结果。这个实现意味着SELECT的列别名会成为结果 map 的键所以在 statement 中给列起清晰的别名如示例中的as id、as name会显著提升 LLM 对返回结果的可读性。高级用法与实践建议先验证再上线Bigtable Studio 是探索与管理 Bigtable 数据的实用入口如果还不熟悉 GoogleSQL 语法可以先用 Query Builder 对目标表构建查询、在控制台验证结果再把确认无误的 SQL 搬进statement字段。下划线列名的处理部分 Python 生态库对_key这类下划线开头的保留列支持有限。文档给出的替代方案是利用 Bigtable Logical Views 重命名列绕过命名限制。权限要求Bigtable 通过 IAM 控制访问Toolbox 使用 Application Default CredentialsADC 进行认证见 source 文档的 IAM 章节。运行工具的 IAM 身份必须拥有所执行查询对应的 Bigtable 数据访问权限否则会收到权限错误。性能习惯Bigtable 的 SQL 查询与 NoSQL 请求同样由集群节点处理因此创建 SQL 查询时同样要遵循避免全表扫描、避免复杂过滤条件的最佳实践source.md中对此有明确提示。安全边界优先用parameters声明式参数覆盖所有值替换场景只有确需动态标识符时才启用templateParameters并且应尽可能在更上游对模板参数取值做约束例如 LLM 提示词层面限定合法表名集合。小结bigtable-sql是 mcp-toolbox 为 Cloud Bigtable 提供的核心查询工具一条statement、一组parameters即可把 GoogleSQL 查询暴露为 LLM 可调用的 MCP 工具。其实现上通过模板替换 → 预编译绑定两段式执行Invoke → RunSQL在保持声明式参数防注入语义的同时也为表名/列名级动态化提供了templateParameters逃生通道。配套的管理类工具建表、建 logical view 等见 tools 目录可与之组合形成完整的 Bigtable 数据接入与操作链路。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
