MCP Toolbox 实战：firestore-get-documents 工具批量读取 Firestore 文档

MCP Toolbox 实战firestore-get-documents 工具批量读取 Firestore 文档【免费下载链接】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 提供的firestore-get-documents工具展开讲解如何通过一条工具配置让 LLM Agent 依据文档路径一次性批量读取 Firestore 中的多个文档并获取文档数据与存在状态、创建/更新/读取时间等元数据。读完本文你将掌握该工具的 YAML 配置方法、documentPaths参数的使用规则、响应结构、路径校验约束与底层实现原理可直接在 MCP Toolbox 服务中落地使用。工具概览按路径批量获取 Firestore 文档firestore-get-documents是 MCP Toolbox for Databases 内置的 Firestore 集成工具之一其核心能力是通过文档路径数组一次读取多个 Firestore 文档并将每个文档的数据与元数据存在状态、创建时间、更新时间、读取时间一并返回给调用方LLM。该工具只接收一个输入参数documentPaths文档路径数组无需编写查询条件属于典型的按路径点查能力适合 Agent 在已知具体文档 ID 时快速拉取原始数据例如批量读取用户资料、订单记录或配置项。官方文档对该工具的定位见 firestore-get-documents.md其余 Firestore 工具增、删、改、查集合、查询规则等可参考 firestore 工具索引。输入参数与响应结构documentPaths 参数documentPaths是唯一的输入参数类型为字符串数组每一项是一个相对文档路径。从工具实现源码 firestoregetdocuments.go 可以看到参数定义documentPaths: Array of relative document paths to retrieve from Firestore (e.g., users/userId or users/userId/posts/postId). Note: These are relative paths, NOT absolute paths like projects/{project_id}/databases/{database_id}/documents/...要点路径必须是相对路径例如users/alice或嵌套子集合路径users/alice/posts/post-1严禁传入绝对路径形如projects/{project_id}/databases/{database_id}/documents/...校验阶段会直接报错数组不能为空也不能缺失该参数否则工具返回 Agent 错误见下文错误场景。返回值结构底层实现位于 firestore.go 的GetDocuments方法返回结果是一个数组数组元素与传入路径一一对应每个元素结构如下{ path: users/alice, exists: true, data: { name: Alice, age: 30 }, createTime: 2026-01-01T00:00:00Z, updateTime: 2026-01-02T00:00:00Z, readTime: 2026-01-03T00:00:00Z }字段说明字段类型说明pathstring本次请求传入的文档路径existsboolean文档是否存在不存在时为falsedatamap文档数据仅当文档存在时返回createTime/updateTime/readTimetimestamp文档创建、更新、读取时间仅当文档存在时返回特别值得注意当某个文档不存在时工具不会报错而是返回exists: false且不带data等字段。这一设计让 Agent 可以在一次调用中安全地批量探测多个路径无需逐个处理 404 异常。兼容的 Source 类型firestore-get-documents只能挂载在 Firestore 类型的 Source 上。工具源码通过compatibleSource接口做运行时类型校验见 firestoregetdocuments.go要求 Source 必须实现type compatibleSource interface { FirestoreClient() *firestoreapi.Client GetDocuments(context.Context, []string) ([]any, error) }若配置的source指向非 Firestore 类型例如 PostgreSQL 源工具初始化与调用时会抛出 invalid source / source used is not compatible with the tool 错误。Firestore Source 的完整能力说明见 firestore source 文档。Source 配置示例要使用该工具首先需要在配置文件中定义一个firestore类型的 Source见 source.mdkind: source name: my-firestore-source type: firestore project: my-project-id # database: my-database # 可选默认使用 (default)Source 参考字段字段类型必填说明typestringtrue必须为firestoreprojectstringtrue包含 Firestore 数据库的 GCP 项目 ID如my-project-iddatabasestringfalse要连接的 Firestore 数据库名不填时默认(default)数据库选择行为在源码 firestore.go 中有明确实现database为空时自动回退为(default)并通过firestore.NewClientWithDatabase建立连接。工具配置示例在my-firestore-sourceSource 之上声明firestore-get-documents工具官方示例见 firestore-get-documents.mdkind: tool name: get_user_documents type: firestore-get-documents source: my-firestore-source description: Use this tool to retrieve multiple documents from Firestore.配置字段参考字段类型必填说明typestringtrue必须为firestore-get-documentssourcestringtrue从中读取文档的 Firestore Source 名称descriptionstringtrue传递给 LLM 的工具描述用于触发正确的工具选择除上述字段外从源码 firestoregetdocuments.go 可知该工具的 Config 还内嵌了通用工具基类ConfigBase支持可选的authRequired与annotations字段。其中annotations若未显式配置会默认使用tools.NewReadOnlyAnnotations——即该工具被标记为只读操作不会产生数据写入。测试用例 firestoregetdocuments_test.go 验证了基础配置与带authRequired配置的 YAML 解析结果。使用预构建配置快速启用MCP Toolbox 提供了 Firestore 预构建配置见 firestore.yaml通过--prebuilt firestore即可一键启用包括get_documents在内的一组工具。预构建配置的要点见 prebuilt-configs/firestore.md启动参数--prebuilt firestore环境变量FIRESTORE_PROJECTGCP 项目 IDFIRESTORE_DATABASE可选Firestore 数据库 ID默认(default)工具清单预构建配置会注册get_documents、add_documents、update_document、list_collections、delete_documents、query_collection、get_rules、validate_rules共 8 个工具其中get_documents的说明即为Gets multiple documents from Firestore by their paths。底层实现原理1. 参数解析与校验链工具调用入口 Invoke 的执行链路从params中取出documentPaths并断言为[]any缺失或非数组时返回 Agent 错误空数组直接拒绝documentPaths parameter cannot be empty通过parameters.ConvertAnySliceToTyped转换为[]string对每个路径调用fsUtil.ValidateDocumentPath做合法性校验调用 Source 的GetDocuments执行实际读取GCP 错误经util.ProcessGcpError归一化后返回。2. 批量读取实现Source 层的GetDocuments见 firestore.go核心逻辑非常简洁docRefs : make([]*firestore.DocumentRef, len(documentPaths)) for i, path : range documentPaths { docRefs[i] s.FirestoreClient().Doc(path) } snapshots, err : s.FirestoreClient().GetAll(ctx, docRefs)它先用Doc(path)将每个相对路径转换为*firestore.DocumentRef再通过 Cloud Firestore Go 客户端的一次GetAll调用批量拉取快照最后逐条组装path/exists/data/createTime/updateTime/readTime响应。相比循环单次Get批量读取能显著减少往返请求次数。3. 路径校验规则路径校验由 validator.go 完成ValidateDocumentPath的规则包括文档路径必须为偶数段形如collection/doc或collection/doc/subcollection/doc奇数段如users会被判为非法因为那是集合路径拒绝绝对路径以^projects/[^/]/databases/[^/]/documents/开头的路径直接报错并提示使用相对路径写法拒绝空段与空白段路径中不能出现//、仅空格的段拒绝./..防止路径穿越类写法拒绝__前缀集合 ID 或文档 ID 不能以__开头该前缀被 Firestore 保留。IAM 权限要求访问 Firestore 时MCP Toolbox 使用 Application Default Credentials (ADC) 完成鉴权。对于只读的firestore-get-documentsIAM 身份至少需要详见 source.mdroles/datastore.userFirestore 的读写权限预构建配置默认授予roles/datastore.viewer只读访问权限足够支撑get_documents等只读操作。涉及安全规则管理的工具如get_rules、validate_rules还需要roles/firebaserules.admin或roles/firebaserules.viewer与本文工具的权限模型互相独立。错误场景与行为边界集成测试 firestore_integration_test.go 覆盖了该工具的主要调用场景可视为行为边界清单场景请求体预期结果读取单个文档{documentPaths: [users/alice]}返回文档数据如name:Alice读取多个文档{documentPaths: [users/alice, users/bob]}一次返回两条文档数据文档不存在{documentPaths: [non-existent-collection/non-existent-doc]}返回exists:false不报错缺少 documentPaths{}调用失败Agent 错误documentPaths 为空数组{documentPaths: []}调用失败Agent 错误实际使用中建议 Agent 遵循以下实践批量路径数量不宜过大避免单次GetAll响应过长先确认路径段数为偶数文档路径再发起调用对返回exists: false的结果做温和处理这通常是数据不存在而非系统故障只读类工具默认携带 read-only annotations可放心用于需要安全护栏的自动化流程。小结firestore-get-documents用最简洁的接口一个路径数组解决了 Agent 批量读取 Firestore 文档的刚需一条 YAML 工具声明、一次GetAll调用即可拿到多份文档的完整数据与时间元数据。结合相对路径校验、只读注解、预构建配置与完善的集成测试它是 MCP Toolbox Firestore 集成中开箱即用程度最高的工具之一。若需要进一步了解该工具在整体 Firestore 工具矩阵中的位置可查阅 Firestore 集成文档 与 预构建配置说明。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考