企业官网建设流程全解析

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 Source：

kind: source name: my-firestore-source type: "firestore" project: "my-project-id" # database: "my-database" # Optional, defaults to "(default)"

配置字段参考

原文档的 Reference 表格完整定义了三个核心字段：

结合源码可以补充一点：实际配置还包含必填的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 权限与角色，可参考 Firestore 访问控制文档。

从源码实现看，Firestore Source 在初始化时会同时创建两类客户端（firestore.go）：

1. Firestore 客户端（initFirestoreConnection）：基于 ADC 与datastore、cloud-platform等 OAuth scope 建立文档数据连接；
2. 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

环境变量：

预构建配置将环境变量映射到 Source 字段（见 firestore.yaml）：

kind: source name: firestore-source type: firestore project: ${FIRESTORE_PROJECT} database: ${FIRESTORE_DATABASE:}

推荐的权限组合：

• Cloud Datastore User（roles/datastore.user）：用于获取文档、列出集合与查询集合；
• Firebase Rules Viewer（roles/firebaserules.viewer）：用于获取与校验 Firestore 安全规则。

预构建工具清单（每个工具的完整参数说明见对应文档）：

预构建配置还将这些工具组织成了分组与工具集（firestore.yaml）：

• groupdata：负责 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.go）：

type 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）；
• 文档 CRUD：GetDocuments基于文档引用批量GetAll；AddDocuments通过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.go）；
• MQL 与模式推断：ExecuteMQL将 MQL 语句包装进executePipelineAPI 的iql阶段执行；GetSchema优先调用get_schemapipeline 阶段，不可用时回退为采样最多 50 篇文档推断字段类型（firestore.go）。

值得注意的一个细节是FirestoreValueToJSON（firestore.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 时建议遵循：

1. 始终使用类型化值：写入documentData时每个字段都要用类型指示符包裹（如{"stringValue": "text"}），这与 Firestore 原生 JSON 格式一致；
2. 大整数用字符串表示：integerValue接受字符串形式（如{"integerValue": "1500"}），避免大整数精度丢失；
3. 慎用returnData：仅当需要核对实际写入/更新结果时再置为true，减少额外读取；
4. 时间戳用 RFC3339、二进制用 base64：timestampValue必须符合 RFC3339 格式，字节数据必须 base64 编码后放入bytesValue；
5. 更新时优先使用 updateMask：只更新目标字段，避免误改其他字段；要从文档中删除字段，可在 updateMask 中列出该字段但不在 documentData 中提供；
6. 关注安全规则：确保目标集合的 Firestore Security Rules 允许相应的创建、更新操作；
7. 权限最小化：只读场景使用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