Rebase

@rebasepro/mcp

Model Context Protocol（MCP）服务，可向 AI 助手公开 Rebase 架构、数据库、文档 CRUD、用户管理和开发服务工具。

安装

pnpm add -D @rebasepro/mcp

通过 rebase init 创建的项目已包含此服务，并固定为 CLI 的版本：该服务会调用项目自己的 CLI 和后端，因此版本应与两者保持一致。

仅支持 ESM：设有 "type": "module"，没有 CommonJS 构建版本，因此需通过 import 加载。它需要 Node >=22.22.0（这是其 engines 下限），在此版本中也可通过 require() 加载：Node 从 22.12 起便支持 require(esm)。

运行项目副本：

pnpm exec rebase-mcp

此软件包的功能

@rebasepro/mcp 通过 stdio 实现 Model Context Protocol，使 AI 助手（Gemini、Claude、Cursor 等）能够与 Rebase 项目交互。它提供工具，并将集合定义和生成的架构公开为 MCP 资源。它原生支持管理多个本地和远程项目。

多项目支持

MCP 服务支持同时管理多个 Rebase 项目。这非常适合在 IDE 中使用多个已打开的工作区，或同时与本地开发服务和远程预发布／生产环境交互。

• 注册表：项目配置存储在 ~/.rebase/projects.json 中。
• 自动发现：如果本地正在运行 rebase dev，MCP 服务会自动从项目目录中的 .rebase/state.json 发现当前开发端口和服务密钥，实现零配置本地开发。

运行时如何确定使用哪个项目

优先级顺序如下：

1. 环境变量配置块 — REBASE_PROJECT_DIR、REBASE_BASE_URL、REBASE_API_TOKEN。只要其中任意一项已设置，每次启动时都会据此重建 default 项目。重建整个条目：针对旧 projectDir 注册的令牌会被丢弃，不会带到它从未为之签发过的目录中。
2. 服务的工作目录，前提是其中包含 rebase.json。~/.rebase/projects.json 是整台机器共用的，而当前所在的项目优先于主目录缓存。
3. 已持久化的 default，仅当前两项都未提供信息时使用。

根据第 1 项或第 2 项生成的 default 永远不会写回注册表：每次启动时都会重新计算；如果将其持久化，就会把某个项目的目录、后端 URL 和开发服务密钥写入这台机器上所有其他项目都会读取的文件。

自动发现会在这三种情况下填补缺失值，且绝不会覆盖上述任一项提供的值——无论是令牌还是 baseUrl。发现过程会读取开发服务的服务密钥，这是一个不限定作用范围的管理员密钥，因此即使 rebase dev 正在运行，仍会使用你注册的范围较窄的 rk_live_* 密钥；同样，注册到 https://staging.example.com 的项目也会保留该地址，而不会被悄然重定向到本地开发端口。若两者的 baseUrl 不一致，会在 stderr 中报告。填补缺失值则不会：如果没有注册令牌，SDK 工具就会使用发现到的服务密钥——拥有完整管理员权限——但不会有任何提示。

rebase init 会在生成的 .mcp.json 中写入 "env": { "REBASE_PROJECT_DIR": "." }——该路径相对于客户端的工作目录；对于项目级配置文件来说，工作目录就是项目本身。

配置

服务从环境变量和 .env 文件中读取配置：

变量	默认值	说明
REBASE_PROJECT_DIR	process.cwd()	项目根目录（rebase.json 所在目录）
REBASE_BASE_URL	http://localhost:3001	Rebase 后端 URL；在发现不到开发服务时使用
REBASE_API_TOKEN	（空）	用于向应用发起 API 调用的身份验证令牌。REBASE_TOKEN（CLI 的控制平面令牌）绝不会发送给应用；云端工具只会将其传递给 CLI
REBASE_MCP_ALLOW_REMOTE_WRITES	false	允许破坏性工具对非本地目标运行（见下文）

服务会尝试从 $REBASE_PROJECT_DIR/.env 或 $REBASE_PROJECT_DIR/app/.env 加载 .env。这些值用于配置服务本身，不会传递给 CLI 或其启动的开发服务：它们会读取当前项目自身的 .env，而传入的变量会优先于该文件中的值和检出分支中的值，就如同你在 shell 中导出该变量一样。

破坏性工具安全门

rebase_project_add 接受任意 baseUrl，而 CLI 工具会连接到项目 .env 中声明的任意 DATABASE_URL。这意味着，同一组工具既可以编辑你笔记本电脑上的临时数据库，也可以删除生产环境中的行——两者之间没有任何防护，只有助手对当前活动项目的判断。

除非目标位于回环接口上，否则拒绝任何会更改目标环境的工具。 安全门采用的是一份不受限制的清单，因此新添加的工具默认会受到保护：

• 不受限制 — 读取操作： rebase_schema_plan、rebase_doctor、rebase_db_branch_list、rebase_db_branch_info、rebase_db_branch_diff、list_documents、get_document、list_users、list_roles、storage_list_objects、storage_get_download_url、cron_list_jobs、cron_get_job、cron_get_job_logs、rebase_dev_logs，以及 Rebase Cloud 的读取操作 rebase_cloud_status、rebase_cloud_logs、rebase_cloud_env_list、rebase_cloud_deployments_list。
• 不受限制 — Rebase Cloud 写入操作： rebase_cloud_provision、rebase_cloud_deploy、rebase_cloud_env_set、rebase_cloud_rollback。预配操作会创建项目并链接此目录；其他操作会更改已链接的云项目，但它们会启动 rebase cloud，该命令使用 CLI 自己的凭据和控制平面自身的权限检查，针对 .rebase/cloud.json 中链接的项目执行操作；它们绝不会使用 baseUrl 或 DATABASE_URL，而安全门只能检查这两个值。
• 不受限制 — 仅限本地： rebase_schema_introspect、rebase_db_branch_switch、rebase_schema_generate、rebase_db_generate、rebase_generate_sdk、开发服务器工具以及项目注册表工具。这些工具只会写入本地文件或本地状态，没有需要检查的远程目标。
• 针对 DATABASE_URL 进行限制： 其他所有 CLI 工具——rebase_db_push、rebase_db_migrate、rebase_db_branch_create、rebase_db_branch_delete。
• 针对项目 baseUrl 进行限制： 其他所有 SDK 工具——create_document、update_document、delete_document、create_user、update_user、delete_user、rebase_auth_reset_password、storage_delete_object、cron_trigger_job、cron_toggle_job、invoke_function。

这两个目标不能互换：CLI 工具看不到 baseUrl，因此，如果 localhost 后端旁边配置的是生产环境 DATABASE_URL，检查的对象是数据库，而不是后端。create_user 和 update_user 会设置 roles，因此可以创建管理员；invoke_function 可以使用任意 HTTP 方法调用任意函数；cron_toggle_job 可以在不发出提示的情况下禁用计划备份。这些操作都无法像“增量”一词所暗示的那样恢复，因此现在采用了相反的清单方式。

安全门检查的 DATABASE_URL 会按照已启动的 CLI 解析它的方式进行解析。如果启动服务的 shell 中导出了 DATABASE_URL，则会直接采用该值。否则，安全门会读取 <root>/.env、<root>/backend/.env、DOTENV_CONFIG_PATH 和父目录中的 .env 内所有的 DATABASE_URL 和 ADMIN_CONNECTION_STRING（分支命令接受的备用值），并像 CLI 一样使用 dotenv 解析每个文件；如果其中任何一个是远程地址，就会拒绝操作。如果完全无法解析出连接字符串，就会拒绝数据库工具：无法验证的目标并不安全，而且子进程会自行从本进程可能无法访问的文件中解析连接字符串。

只有回环地址（localhost 和 *.localhost、127.0.0.0/8、::1、0.0.0.0）才算本地——10.x 和 192.168.x 等私有网段不算，因为这些地址同样可能属于共享的预发布集群，而不是笔记本电脑。

设置 REBASE_MCP_ALLOW_REMOTE_WRITES=true 可选择退出此限制。

分支工具（rebase_db_branch_*）还需要管理员权限，并通过 GET /auth/me 进行检查——该接口只接受已登录用户的访问令牌，因此使用服务密钥（包括发现功能提供的密钥）或 rk_live_* API 密钥时，所有分支工具都会失败，并显示 "Admin authorization failed"。

不可信数据标记

行、用户记录、存储列表、cron 作业、函数响应和 CLI 输出都会包含在明确的 <<<UNTRUSTED_DATA …>>> 封套中。数据库中存储的任何内容都是由某人写入的，而且它与助手遵循的工具契约通过同一渠道传入；该封套会告知模型将其视为惰性内容，而非指令。这只是一个标记，并非沙箱——使用这些工具的助手是否安全，取决于你允许它读取的内容。

---

工具

共 51 个工具，分为 10 组。标记为 ⚠ 的工具针对非本地目标的操作会被拒绝，除非设置了 REBASE_MCP_ALLOW_REMOTE_WRITES=true——请参阅上方的限制说明。

架构与数据库（13）

在当前项目目录中运行 Rebase CLI。

工具	必填项	描述
rebase_schema_generate	—	根据 Rebase TypeScript 集合定义生成 Drizzle 架构
rebase_db_push ⚠	—	将当前 Drizzle 架构直接应用到数据库（开发快捷方式，会跳过迁移文件）
rebase_schema_introspect	—	检查实时数据库，并根据现有表生成 Rebase 集合定义
rebase_db_generate	—	根据架构更改生成 SQL 迁移文件（将当前 Drizzle 架构与上一个实体进行比较）
rebase_db_migrate ⚠	—	对数据库运行所有待处理的 SQL 迁移
rebase_generate_sdk	—	根据集合定义生成完全类型化的 JavaScript/TypeScript SDK
rebase_doctor	—	检测集合定义、生成的 Drizzle 架构与实时 PostgreSQL 数据库之间的架构漂移
rebase_db_branch_create ⚠	name	创建新的数据库分支（仅限管理员）
rebase_db_branch_list	—	列出所有数据库分支（仅限管理员）
rebase_db_branch_delete ⚠	name	删除现有数据库分支（仅限管理员）
rebase_db_branch_info	name	显示数据库分支的信息和状态（仅限管理员）
rebase_db_branch_diff	name	显示数据库分支相对于其源数据库所做的更改（仅限管理员）：以 SQL 形式列出新增、删除和修改的表、列、约束、索引、触发器、RLS 策略、枚举类型、视图和函数；对于每张表，还会按主键匹配并展示该分支插入、更新和删除的行，以及示例行
rebase_db_branch_switch	—	将此工作区指向某个数据库分支，或切回主数据库（仅限管理员）

架构规划（1）

询问后端更改会产生什么影响。不使用 CLI，也不写入文件。

工具	必填项	描述
rebase_schema_plan	collectionId、collection	显示集合更改将执行的 SQL，但不实际执行

文档（5）

通过 @rebasepro/client 对集合执行 CRUD 操作。

工具	必填项	描述
list_documents	collection	列出 Rebase 集合中的文档，可选过滤、排序和分页
get_document	collection、id	按 ID 获取 Rebase 集合中的单个文档
create_document ⚠	collection、data	在 Rebase 集合中创建新文档
update_document ⚠	collection、id、data	更新 Rebase 集合中的现有文档
delete_document ⚠	collection、id	删除 Rebase 集合中的文档

用户与角色（6）

工具	必填项	描述
list_users	—	列出 Rebase 后端中注册的所有用户，包括其角色
create_user ⚠	email	在 Rebase 后端中创建新用户
update_user ⚠	uid	更新现有用户（电子邮件、显示名称、角色）
delete_user ⚠	uid	从 Rebase 后端删除用户
list_roles	—	列出 Rebase 后端中定义的所有角色
rebase_auth_reset_password ⚠	email	通过管理 API 重置用户密码

开发服务器（3）

工具	必需参数	描述
rebase_dev_start	—	启动 Rebase 开发服务器（前端 + 后端）
rebase_dev_logs	—	读取正在运行的 Rebase 开发服务器的近期输出
rebase_dev_stop	—	停止正在运行的 Rebase 开发服务器

存储（3）

工具	必需参数	描述
storage_list_objects	—	列出存储在 Rebase 存储中的文件/对象
storage_delete_object ⚠	key	从 Rebase 存储中删除对象/文件
storage_get_download_url	key	为 Rebase 存储中的文件生成临时签名下载 URL

定时任务（5）

工具	必需参数	描述
cron_list_jobs	—	列出所有已安排的定时任务及其配置状态
cron_get_job	jobId	获取特定已安排定时任务的状态和详情
cron_trigger_job ⚠	jobId	立即手动触发一次定时任务运行
cron_get_job_logs	jobId	读取特定定时任务的执行日志
cron_toggle_job ⚠	jobId, enabled	启用或禁用已安排的定时任务

函数（1）

工具	必需参数	描述
invoke_function ⚠	name	调用自定义后端 Hono 函数（位于 api/functions/:name）

项目注册表（6）

工具	必需参数	描述
rebase_project_list	—	列出所有已注册的 Rebase 项目，并显示当前激活的项目
rebase_project_switch	name	按名称切换当前激活的 Rebase 项目
rebase_project_add	name	注册新的 Rebase 项目
rebase_project_remove	name	从项目注册表中移除已注册的项目
rebase_project_current	—	显示当前激活的 Rebase 项目详情，包括解析后的 URL 和认证状态
rebase_project_status	—	通过调用 GET /health 检查当前激活项目的后端健康状况

Rebase Cloud（8）

在当前激活项目目录中，对其关联的项目使用 CLI 自带的凭据运行 rebase cloud … --json。配置会创建项目；部署、设置环境变量和回滚会更改关联的项目。它们不受环回网关限制，因为它们从不使用 baseUrl 或 DATABASE_URL。

工具	必需参数	描述
rebase_cloud_provision	—	无需账户或注册，即可为当前激活项目启用 Rebase Cloud 实时后端：配置项目，在 .env 中设置 REBASE_BASE_URL，将目录关联到项目，并将本地 collections 部署到该项目（rebase cloud init --claim），然后在 .env 中设置 REBASE_API_TOKEN：应用部署后可接受的密钥，可通过行级安全策略读取和写入数据，并在认领期限结束时过期
rebase_cloud_status	—	显示此目录关联的 Rebase Cloud 项目（rebase cloud status）
rebase_cloud_deploy	—	将此目录部署到其关联的 Rebase Cloud 项目（rebase cloud deploy）
rebase_cloud_logs	—	读取关联的 Rebase Cloud 项目的日志；只读取一次，内容为正在运行的应用日志或最新构建日志（rebase cloud logs）
rebase_cloud_env_list	—	列出关联的 Rebase Cloud 项目的环境变量，但不显示其值（rebase cloud env list）
rebase_cloud_env_set	key, value	在关联的 Rebase Cloud 项目上设置一个环境变量（rebase cloud env set KEY --stdin）
rebase_cloud_deployments_list	—	列出关联的 Rebase Cloud 项目近期的部署，按时间从新到旧排列（rebase cloud deployments list）
rebase_cloud_rollback	—	恢复关联的 Rebase Cloud 项目之前一次成功的部署，使其重新投入使用（rebase cloud rollback）

---

资源

该服务会公开 MCP 资源，供 AI 提供上下文：

URI	描述
rebase://collections/{name}	集合定义的 TypeScript 源码
rebase://schema	生成的 Drizzle schema（schema.generated.ts）

集合文件会从当前项目目录下的 app/config/collections/、config/collections/ 或 collections/ 中发现。

快速开始

将其添加到 AI 助手的 MCP 配置中（例如 .gemini/settings.json）：

{
  "mcpServers": {
    "rebase": {
      "command": "pnpm",
      "args": ["--dir", "/path/to/your/project", "exec", "rebase-mcp"],
      "env": {
        "REBASE_PROJECT_DIR": "/path/to/your/project"
      }
    }
  }
}

MCP Registry

稳定版发布时，会将此服务发布到 MCP Registry，名称为 io.github.rebasepro/rebase——MCP 客户端在提供安装选项时会读取此条目。两个文件承载着这一身份信息，且必须一致：

package.json → mcpName	所有权证明，从已发布的 npm tarball中读取
server.json	清单：相同的名称、版本以及要安装的 npm 包

发布时不会手动编辑这两个文件。publishable-packages.mjs --set-version 会将版本写入 server.json 以及每个 package.json，而 pnpm check:publishable-set 会拒绝两者不一致的目录树——Registry 会通过下载清单中指定的 tarball 来验证发布，因此如果清单未同步更新，发布会在最后一步失败；此时 npm 发布内容已无法再修改。

稳定版发布工作流会在发布 npm、标签和 fleet 镜像之后，使用已有的 npm 来源证明 OIDC 令牌直接推送 Registry 条目。手动运行 release.sh 无法做到这一点——登录采用设备代码流程——因此它会打印完成发布所需的命令：

mcp-publisher login github && mcp-publisher publish

使用 brew install mcp-publisher 安装 mcp-publisher，并通过 mcp-publisher validate 检查清单，无需实际发布。

相关包

• @rebasepro/client — 在内部用于数据和管理 API 调用