MCP Toolbox 数据库集成指南Firestore Source 配置与实战【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本篇技术指南以 MCP Toolbox 仓库中的 Firestore Source 文档 为核心主体系统讲解如何将 NoSQL 文档数据库 Firestore 接入 MCP Toolbox从 Source 配置语法、IAM 权限与身份认证、多数据库选择到预构建配置、可用工具集与源码级实现原理。读完本篇你将能够独立编写一份可运行的 Firestore Source 配置并将其与 CRUD、查询、安全规则等工具组合成完整的 MCP 服务。Firestore Source 是什么Firestore 是一款为自动扩展、高性能和易开发而设计的 NoSQL 文档数据库属于全托管的 Serverless 数据库同时支持移动端、Web 端和服务端开发。虽然 Firestore 的接口与许多传统数据库拥有相似的能力但作为 NoSQL 数据库它在“如何描述数据对象之间的关系”上与传统关系型数据库存在本质差异没有表连接JOIN与强约束的模式数据以文档Document和集合Collection的层级结构组织。在 MCP Toolbox 中Source是数据连接层的入口概念。一个 Firestore Source 封装了目标项目与数据库的连接信息是所有 Firestore 工具的公共依赖——每个 Firestore 工具都通过source字段绑定到具体的 Source 实例从而获得 Firestore 客户端与 Firebase Rules 客户端的访问能力。如果你对 Firestore 还不熟悉可以先创建一个数据库并学习基础知识参考 Firestore 官方快速入门。Source 的注册机制与配置结构从源码结构看MCP Toolbox 通过注册表机制管理各种数据库 Source 类型。在 internal/sources/sources.go 中Register(sourceType string, factory SourceConfigFactory)将每种 source 类型的工厂函数登记到全局注册表解析配置文件时DecodeConfig依据type字段找到对应的工厂完成解码。Firestore 在 internal/sources/firestore/firestore.go 中注册了SourceType firestore其配置结构体定义了四个字段type Config struct { // Firestore configs Name string yaml:name validate:required Type string yaml:type validate:required Project string yaml:project validate:required Database string yaml:database // Optional, defaults to (default) }其中name、type、project三个字段带有validate:required校验标签缺失时配置解析会直接报错database字段可选留空时在运行时回落为默认数据库(default)。最小配置示例原文档给出的示例配置如下它定义了一个名为my-firestore-source、指向 GCP 项目my-project-id的 Firestore Sourcekind: source name: my-firestore-source type: firestore project: my-project-id # database: my-database # Optional, defaults to (default)配置字段参考原文档的 Reference 表格完整定义了三个核心字段fieldtyperequireddescriptiontypestringtrueMust be firestore。projectstringtrueId of the GCP project that contains the Firestore database例如 my-project-id。databasestringfalseName of the Firestore database to connect to。未指定时默认使用 (default)。结合源码可以补充一点实际配置还包含必填的name字段它作为该 Source 在配置中的唯一标识供后续工具通过source: name引用。配置解析的行为验证internal/sources/firestore/firestore_test.go 中的单元测试印证了上述解析行为TestParseFromYamlFirestore验证“未指定 database 时解析为空字符串”运行时回落为(default)以及“显式指定自定义 database”两种场景都能正确解析TestFailParseFromYaml验证两个失败场景——配置中出现未知字段如foo: bar会报unknown field foo错误缺少必填的project字段会报Field validation for Project failed on the required tag错误。这提醒我们在编写配置时要严格遵循字段定义既不要拼错字段名也不要遗漏必填项。数据库选择单项目多数据库支持Firestore 允许在同一个 GCP 项目下创建多个数据库每个数据库相互隔离拥有自己独立的文档与集合。如果你的配置中没有显式指定database工具将使用名为(default)的默认数据库。这一行为在源码中有明确实现。firestore.go 中的GetDatabaseId()方法在Database字段为空时返回(default)func (s *Source) GetDatabaseId() string { if s.Database { return (default) } return s.Database }连接初始化时initFirestoreConnection同样先做默认值填充再通过firestore.NewClientWithDatabase(ctx, project, database, ...)创建指定数据库的客户端见 firestore.go。换言之database字段最终决定工具读写的是哪个隔离的数据实例——多环境隔离如 dev / staging / prod 各建一个数据库可以通过配置不同 Source 轻松实现。TestGetDatabaseId测试firestore_test.go对“空值回落默认库”和“自定义库”两种分支均有覆盖。IAM 权限与身份认证Firestore 使用 Identity and Access Management (IAM) 控制用户与用户组对 Firestore 资源的访问。MCP Toolbox 将使用你的 Application Default Credentials (ADC) 在与 Firestore 交互时完成授权与身份认证。除了为服务器设置 ADC 之外你还必须确保该 IAM 身份被授予正确的 Firestore 访问权限。原文档列出的常用角色包括IAM 角色作用roles/datastore.user对 Firestore 的读写访问roles/datastore.viewer对 Firestore 的只读访问roles/firebaserules.adminFirestore 的 Firebase Security Rules 全面管理。涉及创建、更新或管理 Firestore 安全规则的操作参见 Firebase Security Rules 角色必须拥有该角色关于如何为某个身份应用 IAM 权限与角色可参考 Firestore 访问控制文档。从源码实现看Firestore Source 在初始化时会同时创建两类客户端firestore.goFirestore 客户端initFirestoreConnection基于 ADC 与datastore、cloud-platform等 OAuth scope 建立文档数据连接Firebase Rules 客户端initFirebaseRulesConnection通过firebaserules.NewService创建用于安全规则的读取与校验firestore.go。这也解释了为什么“获取/校验安全规则”类工具需要额外的 Firebase Rules 相关权限预构建配置文档中对应的是roles/firebaserules.viewer详见下文预构建配置一节。预构建配置与可用工具原文档的 “Available Tools” 章节通过短代码动态列出 Firestore 集成下的全部工具。仓库中以两种方式固化这份工具清单预构建配置文件 internal/prebuiltconfigs/tools/firestore.yaml 与对应的文档说明 docs/en/integrations/firestore/prebuilt-configs/firestore.md。使用预构建配置的方式是启动时指定--prebuilt参数--prebuilt firestore环境变量环境变量说明FIRESTORE_PROJECTGCP 项目 ID必填FIRESTORE_DATABASEFirestore 数据库 ID可选默认(default)预构建配置将环境变量映射到 Source 字段见 firestore.yamlkind: source name: firestore-source type: firestore project: ${FIRESTORE_PROJECT} database: ${FIRESTORE_DATABASE:}推荐的权限组合Cloud Datastore Userroles/datastore.user用于获取文档、列出集合与查询集合Firebase Rules Viewerroles/firebaserules.viewer用于获取与校验 Firestore 安全规则。预构建工具清单每个工具的完整参数说明见对应文档工具名类型功能get_documentsfirestore-get-documents按路径批量获取多个 Firestore 文档参见 文档add_documentsfirestore-add-documents向 Firestore 集合新增文档参见 文档update_documentfirestore-update-document更新 Firestore 中已有文档支持 updateMask 局部更新参见 文档list_collectionsfirestore-list-collections列出指定父路径下的 Firestore 集合参见 文档delete_documentsfirestore-delete-documents批量删除 Firestore 文档参见 文档query_collectionfirestore-query-collection按完整文档路径与过滤条件查询集合中的文档参见 文档get_rulesfirestore-get-rules获取当前项目生效的 Firestore 安全规则参见 文档validate_rulesfirestore-validate-rules校验提供的 Firestore Rules 源码是否存在语法与校验错误参见 文档预构建配置还将这些工具组织成了分组与工具集firestore.yamlgroupdata负责 NoSQL 文档操作与集合层级探索包含get_documents、add_documents、update_document、delete_documents、query_collection、list_collections适用于 CRUD 任务与数据检索toolsetsecurity包含get_rules与validate_rules集中管理安全规则相关能力。此外集成目录中还包含两个基于 Firestore 的扩展型工具firestore-mongodb-execute-mql执行 MQL 查询参见 文档与firestore-mongodb-get-schema获取集合模式参见 文档。从参数化查询看工具能力以firestore-query工具文档为例它支持 Go 模板语法的参数化查询collectionPath、filters、select、orderBy、limit均可使用{{.param}}占位符在运行时替换并支持 AND/OR 嵌套过滤逻辑与 Firestore 原生 JSON 类型值stringValue、integerValue、doubleValue、booleanValue、timestampValue、geoPointValue、arrayValue、mapValue等还可通过analyzeQuery: true返回 explain 指标计划摘要与执行统计用于索引调优。这份工具文档为自定义 Firestore 工具提供了可复用的查询模板基础。源码级实现纵深Source 如何驱动 Firestore 操作Firestore Source 的运行时实现集中在 internal/sources/firestore/firestore.go它在Source结构体中同时持有 Firestore 客户端与 Firebase Rules 客户端firestore.gotype Source struct { Config Client *firestore.Client RulesClient *firebaserules.Service }其核心操作能力包括查询构建与执行BuildQuery依次应用过滤器WhereEntity、字段投影Select、排序OrderBy与行数限制Limit并在analyzeQuery开启时附加ExplainOptions{Analyze: true}ExecuteQuery将文档迭代器结果转换为包含id、path、data、createTime、updateTime、readTime的结构化结果并通过getExplainMetrics提取planSummary使用的索引与executionStats返回行数、读操作数、执行耗时等指标firestore.go文档 CRUDGetDocuments基于文档引用批量GetAllAddDocuments通过collection.Add写入并可选返回写入后的文档数据UpdateDocument在有updates时走docRef.Update否则走Set(..., firestore.MergeAll)实现合并写入DeleteDocuments使用BulkWriter高效批量删除firestore.go集合探索ListCollections支持列出根集合或指定文档下的子集合并返回父路径信息firestore.go安全规则管理GetRules通过 release 名称projects/{project}/releases/cloud.firestore/{database}拉取当前生效规则集ValidateRules调用 Firebase Rules 的 test API返回valid、issueCount与带行号/列号定位的精美格式错误输出firestore.goMQL 与模式推断ExecuteMQL将 MQL 语句包装进executePipelineAPI 的iql阶段执行GetSchema优先调用get_schemapipeline 阶段不可用时回退为采样最多 50 篇文档推断字段类型firestore.go。值得注意的一个细节是FirestoreValueToJSONfirestore.go它将 Firestore 特有的类型time.Time→ RFC3339 字符串、LatLng→{latitude, longitude}、[]byte→ base64、DocumentRef→ 路径转换为简化 JSON使返回给 LLM/Agent 的数据更易读。IsReadOnly()返回false表明该 Source 同时暴露读写能力。集成测试验证仓库在 tests/firestore/firestore_integration_test.go 中提供了端到端集成测试其环境变量约定与预构建配置保持一致通过FIRESTORE_PROJECT指定项目FIRESTORE_DATABASE可选指定数据库。TestFirestoreToolEndpoints会真实启动 Toolbox 服务依次验证REST 工具端点/api/tool/{name}/invoke上的获取、新增、更新、删除、集合列出、查询、规则获取与规则校验MCPtools/call方法的 JSON-RPC 调用含参数缺失报错、无效工具名报错、文档不存在时exists:false等边界场景。这为读者提供了一套可对照的验收清单配置好FIRESTORE_PROJECT后运行该测试即可验证自己的 Firestore Source 与工具配置是否端到端可用。实践建议结合预构建配置中内嵌的最佳实践说明firestore.yaml使用 Firestore Source 时建议遵循始终使用类型化值写入documentData时每个字段都要用类型指示符包裹如{stringValue: text}这与 Firestore 原生 JSON 格式一致大整数用字符串表示integerValue接受字符串形式如{integerValue: 1500}避免大整数精度丢失慎用returnData仅当需要核对实际写入/更新结果时再置为true减少额外读取时间戳用 RFC3339、二进制用 base64timestampValue必须符合 RFC3339 格式字节数据必须 base64 编码后放入bytesValue更新时优先使用 updateMask只更新目标字段避免误改其他字段要从文档中删除字段可在 updateMask 中列出该字段但不在 documentData 中提供关注安全规则确保目标集合的 Firestore Security Rules 允许相应的创建、更新操作权限最小化只读场景使用roles/datastore.viewer读写场景使用roles/datastore.user仅当需要规则管理能力时才授予roles/firebaserules.admin或roles/firebaserules.viewer。小结Firestore Source 是 MCP Toolbox 接入 NoSQL 文档数据库的标准化入口配置上仅需type、project与可选的database三个核心字段配合 ADC 与 IAM 角色即可打通认证链路结合预构建配置可快速获得覆盖 CRUD、查询、集合探索与安全规则管理的完整工具集。其底层实现通过 Firestore 官方 Go 客户端与 Firebase Rules API 双通道驱动既保证了文档操作的高效BulkWriter 批量删除、Explain 查询分析也为 LLM/Agent 提供了类型友好、结构统一的响应格式——这使其成为构建数据库类 MCP 服务时值得优先采用的集成方案。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考