FireCMS Cloud

@firecms/mcp-server

适用于 FireCMS Cloud 的 MCP 服务。让 AI 助手将 Firebase 项目连接到 FireCMS，根据 Firestore 中已有的数据推断集合，然后管理 CMS — 浏览和编辑数据、定义集合架构和属性、配置项目以及管理用户。

仅限管理员：所有写入操作都要求经过身份验证的用户在目标项目中拥有 admin 角色。任何经过身份验证的项目成员都可以执行读取操作。引导工具在项目创建前运行，因此改由 Google Cloud 访问权限控制。

同一服务可在两个位置运行：

• 托管版，地址为 https://api.firecms.co/mcp，面向所有人。客户端在浏览器中通过 OAuth 登录；无需安装任何内容。它不持有 Google Cloud 凭据，因此连接新的 Firebase 项目需要交由 Web 应用处理。FireCMS 后端通过 @firecms/mcp-server/hosted 入口挂载它。
• 本地版，通过 stdio 运行（npx @firecms/mcp-server）。它使用你的 Google 账号登录（firecms_login），因此也可以启用 API、创建 Firestore 数据库，并端到端地连接项目。

托管服务

在 Claude（claude.ai 或 Claude Desktop）中：依次打开 Settings → Connectors → Add custom connector，然后粘贴 https://api.firecms.co/mcp。

在 Claude Code 中：

claude mcp add --transport http firecms https://api.firecms.co/mcp

其他任何支持通过 URL 添加远程服务的客户端：

{
  "mcpServers": {
    "firecms": { "url": "https://api.firecms.co/mcp" }
  }
}

本地服务

设置

cd packages/mcp_server && npm install && npm run build

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "firecms": {
      "command": "node",
      "args": ["/path/to/packages/mcp_server/dist/cli.js"]
    }
  }
}

或者使用 npx（无需构建）：

{
  "mcpServers": {
    "firecms": {
      "command": "npx",
      "args": ["@firecms/mcp-server"]
    }
  }
}

出现提示时，使用 firecms_login 登录。令牌与 FireCMS CLI 共用（~/.firecms/tokens.json）。

连接现有 Firebase 项目

这是典型的首次会话。此处的所有操作都由你登录时使用的 Google 账号驱动。

1. list_firebase_projects        → see which projects you can connect, and what they still need
2. get_project_setup_status      → check one project in detail (optional)
3. enable_project_apis           → only if apisEnabled is false
4. enable_firestore              → only if firestoreEnabled is false (location is permanent)
5. connect_project_to_firecms    → service account, admin user, and the security rules
6. setup_all_collections         → infer every root collection from the existing data

在第 5 步之前，必须先在项目上启用 Firebase Authentication — 这是唯一不涉及 API 的前置条件，因此请在 Firebase 控制台中将其启用。第 5 步会将 FireCMS 的访问规则添加到项目的 Firestore 和 Storage 规则中；如果没有这些规则，CMS 会报告“缺少 Firestore 安全规则”并且无法打开任何内容。此处的工具都不会发现这一问题，因为它们均通过后端的服务账号读取数据，而该账号会绕过安全规则。

第 6 步将现有项目转变为可用的 CMS：FireCMS 会对每个根集合中的文档进行采样，推断属性类型，并使用大模型选择显示名称、单数名称、图标和导航分组。

根据现有数据创建集合

工具	说明
get_root_collections	列出项目的 Firestore 根集合（实时读取）
list_subcollections	列出文档的子集合，用于探索嵌套数据
list_databases	列出 Firestore 数据库（仅在需要访问 (default) 以外的数据库时使用）
preview_inferred_schema	根据采样文档推断架构，但不保存
infer_collections_from_data 🔒	为选定路径推断并保存集合
setup_all_collections 🔒	推断并保存所有尚未映射的根集合

preview_inferred_schema 是一种非破坏性选项：它最多对 200 个文档进行采样，在本地推断类型、枚举和验证规则，并返回一份草稿供你编辑，然后通过 save_collection_schema 保存。它也适用于子集合以及批量工具会跳过的任何路径。

infer_collections_from_data 和 setup_all_collections 会通过后端执行操作，后端会添加大模型处理环节，并将结果直接写入项目。两者都会跳过已映射到集合的路径，因此随着数据库增长，可以安全地重复运行。

工具

身份验证

工具	说明
firecms_login 💻	通过浏览器登录（Google OAuth）
firecms_logout 💻	退出登录
firecms_get_current_user	显示当前用户

入门

工具	描述
list_firebase_projects 💻	可访问的 Google Cloud 项目，以及 FireCMS 就绪状态标记
get_project_setup_status 💻	某个项目的详细就绪状态
list_firestore_locations 💻	新建 Firestore 数据库时可用的位置
enable_project_apis 💻	启用 FireCMS 所需的 Google Cloud API
enable_firestore 💻	创建默认 Firestore 数据库（位置不可更改）
connect_project_to_firecms	连接现有 Firebase 项目，并应用所需的安全规则。托管版：返回在 Web 应用中连接项目的链接
apply_firestore_security_rules 🔒	将 FireCMS 的访问规则添加到 Firestore 和 Storage（幂等）
create_firecms_webapp 🔒	如果 Web 应用创建失败，可重试创建

项目与根集合

工具	描述
list_projects	列出 FireCMS Cloud 项目
get_root_collections	列出 Firestore 根集合
list_subcollections	列出文档的子集合

项目配置 🔒

工具	描述
get_project_config	获取完整的项目配置（名称、颜色、计划、功能）
update_project_name	重命名项目
update_project_colors	更新品牌主色和辅助色
update_default_locale	更改默认区域设置
toggle_text_search	启用/停用本地文本搜索
toggle_entity_history	启用/停用实体历史记录

用户 🔒

工具	描述
list_users	列出项目用户及其角色
add_user	邀请用户
update_user_roles	更改用户角色
remove_user	移除用户

集合架构 🔒

工具	描述
list_collection_schemas	列出所有已保存的集合架构
get_collection_schema	获取集合的完整架构
save_collection_schema	创建或替换集合架构
update_collection_schema	部分更新集合架构
delete_collection_schema	删除集合架构（不影响数据）
save_property	在集合中添加或更新单个属性
delete_property	从集合架构中移除属性

AI 架构生成

工具	描述
generate_collection	根据提示词使用 AI 生成集合架构
modify_collection	根据提示词使用 AI 修改现有架构

文档（Firestore CRUD）

工具	描述
list_documents	查询文档（筛选、排序、分页）
get_document	按路径获取文档
create_document	创建新文档
update_document	部分更新文档
delete_document	删除文档
count_documents	统计集合中的文档数量

数据导入与导出

工具	描述
export_collection	将集合数据导出为 JSON
import_documents 🔒	批量导入文档（每次最多 500 个）

🔒 = 仅限管理员的操作 · 💻 = 仅限本地服务

每个工具都声明了 title 和 readOnlyHint，并且在写入数据时声明 destructiveHint：对于只会新增内容的工具（创建文档、邀请用户），值为 false；对于任何可能覆盖或删除内容的工具，值为 true。

资源

URI	描述
firecms://projects/{id}/collections	Firestore 根级集合
firecms://projects/{id}/users	项目用户及其角色
firecms://projects/{id}/schemas	所有集合架构（完整配置树）
firecms://projects/{id}/config	项目配置快照

示例工作流

将现有 Firebase 项目接入 FireCMS

1. list_firebase_projects        → pick a project that is not yet connected
2. connect_project_to_firecms    → provision it
3. setup_all_collections         → infer collections from the data already there

从头创建集合

1. firecms_login          → authenticate
2. list_projects          → pick your project
3. save_collection_schema → define the schema
4. import_documents       → seed with initial data

在提交架构前调整其形态

1. preview_inferred_schema  → draft a schema from real documents, nothing saved
2. save_property            → adjust individual fields
3. save_collection_schema   → persist the result

AI 辅助创建架构

1. generate_collection    → describe what you want in natural language
2. save_collection_schema → persist the generated schema

架构

会话：本地和托管

没有任何代码会从进程级状态读取凭据。每次 API 调用都会通过一个 FireCMSSession（session.ts）——其中包含用户的电子邮件地址、firecms-backend 上的 Firebase ID 令牌，以及可用时的 Google 访问令牌——并传递给 createFireCMSMcpServer()：

• 本地（cli.ts）：localSession 会读取 CLI 的令牌文件，并将 Google ID 令牌兑换为后端令牌（见下文）。登录/注销工具仅由 CLI 注册。
• 托管（hosted.ts）：后端会将每个请求的 OAuth bearer 令牌解析为对应用户，并传递一个可为该用户生成后端 ID 令牌的会话。这里没有 Google 令牌，因此 Google Cloud 工具会替换为一个链接到 Web 应用的 connect_project_to_firecms。每个请求都有独立的服务和传输（无状态 Streamable HTTP），因此任何用户的会话都不会在其请求结束后继续存在。hosted.ts 从不导入 CLI 的登录流程；有一项测试会遍历其导入关系图，确保这一点。

身份验证

FireCMS Cloud API 需要两种不同的令牌，服务会同时发送这两种令牌——与 Web 应用发送的令牌相同：

标头	令牌	用途
Authorization	由 firecms-backend 签发的 Firebase ID 令牌	由 firebaseAuthorization() 保护的端点——大多数 API
x-admin-authorization	Google OAuth 访问令牌（cloud-platform 作用域）	由 googleCloudAuthentication() 保护的端点——GCP 资源配置。仅限本地会话

firecms login 只会生成 Google 凭据。Google ID 令牌不是 Firebase ID 令牌——它由 accounts.google.com 为 Google OAuth 客户端签发，因此 verifyIdToken() 会拒绝它。因此，backend-auth.ts 会通过 Identity Toolkit signInWithIdp 将其兑换为真正的 firecms-backend 令牌，这相当于 Web 应用的无头版本 signInWithPopup(auth, GoogleAuthProvider)。兑换后的令牌会缓存在内存中，直到即将过期时为止。

集合配置的存储位置

FireCMS Cloud 会从后端 Firestore 的 projects/{projectId}/collections/{collectionId} 路径读取集合配置——参见 FireCMSCloudApp.tsx 中的 useFirestoreCollectionsConfigController。这并非客户端项目的 __FIRECMS/config/collections，后者是可自托管部署所用的布局，Cloud 从不读取它。

后端没有为该存储提供 REST 端点——Web 应用会直接通过 Firebase SDK 写入——因此 backend-firestore.ts 会使用兑换后的 Firebase 令牌调用 Firestore REST API。后端的安全规则保持不变。

文档的 CRUD 操作则不同：后端会通过项目委派的服务账号，将其代理到客户端的 Firestore 中。

感知缓存的集合发现

后端的 firestore_root_collections 端点会按项目缓存结果 5 分钟，因此会漏掉上次查询后创建的集合——包括刚刚连接的项目中的所有集合。因此，发现操作会使用未缓存的 admin/collections/list 端点；setup_all_collections 会自行解析路径，而不是委托给 initial_setup，因为后者会通过同一个缓存来解析路径。

infer_collections_from_data 也会拒绝没有文档的路径。后端无论如何都会运行 LLM 推理；如果没有可供抽样的数据，模型就会仅根据路径名称臆造架构——一个空的 articles 路径会生成看似合理的 title/slug/status/author 字段，但这些字段在数据中根本不存在。

stdout 专用于协议

在 stdio 传输中，stdout 承载 JSON-RPC 流，因此 cli.ts 会在启动前将所有 console 输出通道重定向到 stderr。依赖项确实会输出日志——@firecms/schema_inference 在推断属性时会记录日志——而一条意外的 console.log 就会破坏协议流。

安全性

• 托管式身份验证：通过 OAuth 2.1 和 PKCE 对接 FireCMS 后端；用户在 Web 应用中批准每个客户端。后端仅以哈希形式存储令牌，会轮换刷新令牌，且不会持有 Google Cloud 凭据
• 本地身份验证：通过浏览器使用 Google OAuth，与 firecms login CLI 相同
• 授权：写入操作会针对每个项目检查管理员角色
• 令牌存储：~/.firecms/tokens.json（与 CLI 共用）；交换得到的后端令牌仅保存在内存中，并会在退出登录时清除
• 管理员缓存：每个项目的角色检查会缓存 5 分钟
• 凭据安全：list_projects 会从输出中移除每个项目的服务账号，因此凭据绝不会被序列化到模型的上下文中