RationalBloks

RationalBloks MCP 服务

几分钟内即可部署生产级 API。 提供项目、架构、部署、模块、对象存储和图数据工具，并运行在您自己的基础设施上（自托管或使用您自己的 BYOC 集群）。

这是什么？

RationalBloks MCP 让 AI Agent（Claude Code、Claude Desktop、Cursor、VS Code 等）能够根据 JSON 架构部署生产级 API，并部署和运行基于这些 API 构建的前端和后端。无需编写后端代码，无需管理基础设施。

"Create a task management API with tasks, projects, and users"
→ 2 minutes later: Production API running on Kubernetes

安装

# recommended — no install step; @latest checks for a new release at every start
uvx rationalbloks-mcp@latest

# or install into an environment
pip install rationalbloks-mcp

快速开始

1. 获取 API 密钥

访问 rationalbloks.com/settings 并创建 API 密钥。密钥包含作用域：只读密钥只能使用读取工具，读写密钥可以使用所有工具。服务只会列出您的密钥可以调用的工具。

2. 配置您的 AI Agent

Claude Code — 远程服务（无需安装）：

claude mcp add --transport http rationalbloks https://mcp.rationalbloks.com/mcp \
  --header "Authorization: Bearer rb_sk_your_key_here"

或使用本地服务：

claude mcp add --env RATIONALBLOKS_API_KEY=rb_sk_your_key_here rationalbloks \
  -- uvx rationalbloks-mcp@latest

--scope project 会将服务写入仓库的 .mcp.json，以便团队共享。使用 "Authorization": "Bearer ${RATIONALBLOKS_API_KEY}" 将密钥保留在文件之外：Claude Code 会从每位开发者的环境中展开该变量。

VS Code — 添加到 .vscode/mcp.json（Cursor：使用 mcpServers 键添加到 .cursor/mcp.json）：

{
  "servers": {
    "rationalbloks": {
      "command": "uvx",
      "args": ["rationalbloks-mcp@latest"],
      "env": {
        "RATIONALBLOKS_API_KEY": "rb_sk_your_key_here"
      }
    }
  }
}

Claude Desktop — 添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "rationalbloks": {
      "command": "uvx",
      "args": ["rationalbloks-mcp@latest"],
      "env": {
        "RATIONALBLOKS_API_KEY": "rb_sk_your_key_here"
      }
    }
  }
}

**其他客户端：**将其指向 https://mcp.rationalbloks.com/mcp（Streamable HTTP），并设置 Authorization: Bearer rb_sk_...。

3. Claude Code 权限

每个可能导致数据丢失的工具都带有 destructiveHint: true，其他工具则不会导致数据丢失。一条允许规则即可覆盖此服务，并通过询问规则让可能导致数据丢失的工具在执行前提示确认。Claude Code 会先评估询问规则，再评估允许规则，因此即使服务已获允许，这些工具仍会提示确认；在自动模式下也仍会提示，因为询问规则会在分类器之前运行。将以下内容添加到 .claude/settings.json（项目级）或 ~/.claude/settings.json（适用于每个项目）：

{
  "permissions": {
    "allow": ["mcp__rationalbloks"],
    "ask": [
      "mcp__rationalbloks__update_schema",
      "mcp__rationalbloks__drop_schema_items",
      "mcp__rationalbloks__deploy_destructive",
      "mcp__rationalbloks__rollback_project",
      "mcp__rationalbloks__delete_project",
      "mcp__rationalbloks__update_graph_schema",
      "mcp__rationalbloks__rollback_graph_project",
      "mcp__rationalbloks__delete_graph_project",
      "mcp__rationalbloks__delete_graph_node",
      "mcp__rationalbloks__delete_graph_relationship",
      "mcp__rationalbloks__set_module_env",
      "mcp__rationalbloks__delete_module"
    ]
  }
}

将 "mcp__rationalbloks__deploy_production" 添加到 ask，即可在每次生产发布前自行批准。

**每次更改前都询问：**改为只允许读取工具。这些规则匹配所有读取工具，不匹配其他工具：

{
  "permissions": {
    "allow": [
      "mcp__rationalbloks__get_*",
      "mcp__rationalbloks__list_*",
      "mcp__rationalbloks__search_graph_nodes",
      "mcp__rationalbloks__fulltext_search_graph",
      "mcp__rationalbloks__traverse_graph",
      "mcp__rationalbloks__preview_schema_change"
    ]
  }
}

**只读服务：**使用只读密钥注册第二个服务。它只会列出读取工具，且平台会拒绝所有其他调用，因此一条规则即可允许所有读取工具：

claude mcp add --transport http rationalbloks-read https://mcp.rationalbloks.com/mcp \
  --header "Authorization: Bearer rb_sk_your_read_key"

{ "permissions": { "allow": ["mcp__rationalbloks-read"] } }

自动模式只会从 ~/.claude/settings.json、托管设置或 --settings 读取 autoMode，不会从项目的 .claude/settings.json 读取。如果其分类器阻止了常规的 RationalBloks 调用，请在此处描述您的项目，并保留 $defaults（将 MyProject 和 apps.yourdomain.com 替换为您的项目名称和集群域名）：

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Key internal services: RationalBloks (MCP server rationalbloks, https://mcp.rationalbloks.com), where our project MyProject runs; its staging environment is for development",
      "Trusted internal domains: rationalbloks.com and *.rationalbloks.com; *.apps.yourdomain.com, where MyProject's APIs and modules are served",
      "Sensitive remote targets: MyProject's production environment"
    ]
  }
}

运行 claude auto-mode config 查看生效的规则，或在 /permissions 中编辑规则（Auto mode 标签页）。

---

工具

读取工具只负责读取。写入工具会修改内容，但不会丢失数据。破坏性工具可能导致数据丢失，并带有 destructiveHint: true：它们会替换整个架构（update_schema、update_graph_schema）、删除、回滚、部署会删除数据的计划（deploy_destructive），或覆盖模块的环境（set_module_env）。

如果计划会删除表或字段，或更改字段类型导致其存储值被舍入或截断（例如，缩小小数位数或将小数改为整数、将日期时间改为日期），则该计划会删除数据。部署工具会拒绝此类计划并列出每项删除操作；deploy_destructive 会应用该计划。

长时间运行的操作（创建、部署、回滚、删除、模块操作）会作为作业运行：工具会返回一个 job_id，然后可通过 get_job_status 查询作业结果。

关系型项目

工具	类型	描述
list_projects	读取	列出你的所有项目
get_project	读取	获取项目详情
get_schema	读取	获取当前 JSON 架构（可选择仅查看部分表或字段）
get_user_info	读取	获取已验证用户的信息
list_clusters	读取	列出你的 BYOC 资源池（客户端自有集群）
get_job_status	读取	查询作业（创建、部署、晋级、回滚、删除、模块操作）的结果
list_project_jobs	读取	列出项目的作业，按时间从新到旧排序，并显示每项作业的结果
get_project_info	读取	获取包含 K8s 状态的详细项目信息
get_version_history	读取	获取 Git 提交历史
get_template_schemas	读取	获取预构建的架构模板
get_schema_reference	读取	获取高级架构功能参考（__policy__、computed、__constraints__、__audit__）
get_subscription_status	读取	获取套餐和用量限制
get_project_usage	读取	获取 CPU／内存指标
get_project_storage_usage	读取	获取对象存储的文件数和已用字节数，以及对应限额
list_project_files	读取	列出已上传的文件（元数据和公开 URL）
get_schema_at_version	读取	获取指定提交中的架构
preview_schema_change	读取	预览更改（补丁操作或完整架构）：迁移计划及所有删除操作，不保存任何内容
create_project	写入	根据架构创建项目（cluster_id 为你的某个 BYOC 资源池；backend_type 为 python 或 rust）
patch_schema	写入	修改部分架构：添加、重命名和设置表及字段。不会删除任何内容
deploy_staging	写入	将已保存的架构部署到预发布环境。若计划会删除数据，则拒绝部署
deploy_production	写入	将预发布环境晋级到生产环境。若计划会删除数据，则拒绝部署
redeploy_project	写入	根据项目正在运行的架构重建并推出预发布环境，不更改架构
rename_project	写入	重命名项目
update_schema	破坏性	替换整个架构：未保留的表或字段会在下次部署时被删除
drop_schema_items	破坏性	从已保存的架构中删除表或字段
deploy_destructive	破坏性	将会删除数据的计划部署到预发布或生产环境（关系型或图）
rollback_project	破坏性	将架构和代码回滚到先前版本
delete_project	破坏性	永久删除项目

图谱项目

工具	类型	描述
get_graph_schema	读取	获取图谱项目的架构
get_graph_template_schemas	读取	预置的图谱架构模板
get_graph_version_history	读取	图谱架构版本历史
get_graph_schema_at_version	读取	获取特定版本的架构
get_graph_project_info	读取	获取包含 K8s/Neo4j 状态的图谱项目信息
create_graph_project	写入	创建 Neo4j 图谱项目
deploy_graph_staging	写入	将已保存的图谱架构部署到预发布环境。若部署计划会删除数据，则拒绝执行
deploy_graph_production	写入	将图谱预发布环境提升至生产环境。若部署计划会删除数据，则拒绝执行
update_graph_schema	破坏性操作	替换整个图谱架构：未包含的内容会在下次部署时被删除
rollback_graph_project	破坏性操作	将图谱项目回滚到先前版本
delete_graph_project	破坏性操作	删除图谱项目

图谱数据

工具	类型	描述
get_graph_node	读取	按 ID 获取节点
list_graph_nodes	读取	按实体类型列出节点
get_node_relationships	读取	获取节点的关系
search_graph_nodes	读取	按属性筛选条件搜索节点
fulltext_search_graph	读取	跨所有字段进行全文搜索
traverse_graph	读取	从某个节点遍历图谱
get_graph_statistics	读取	图谱统计信息（计数）
get_graph_data_schema	读取	已部署的数据架构
create_graph_node	写入	创建节点
update_graph_node	写入	更新节点属性
create_graph_relationship	写入	创建关系
bulk_create_graph_nodes	写入	创建最多 500 个节点
bulk_create_graph_relationships	写入	创建最多 500 个关系
delete_graph_node	破坏性操作	删除节点及其关系
delete_graph_relationship	破坏性操作	删除关系

模块

模块是项目自有的前端（frontblok）或后端（logicblok），基于 GitHub 仓库构建，并与项目一同运行。

工具	类型	描述
list_modules	读取	项目的模块：ID、类型、仓库、URL、状态、Pod、资源以及最近构建的镜像
deploy_module	写入	从 GitHub 仓库部署新模块
redeploy_module	写入	根据模块仓库默认分支的最新提交重新构建模块并发布
update_module	写入	重命名模块或将其指向其他仓库
freeze_module	写入	停止模块的 Pod，并记录其运行数量
unfreeze_module	写入	重新启动已冻结模块的 Pod
scale_module	写入	运行 1 或 2 个模块 Pod
set_module_resources	写入	设置模块的 CPU 和内存，并重新构建
set_module_env	破坏性操作	设置或移除环境变量（合并操作：未指定的变量会保留）；变量值不会被读回
delete_module	破坏性操作	移除模块

---

架构格式

架构必须采用 FLAT 格式：

{
  "tasks": {
    "title": {"type": "string", "max_length": 200, "required": true},
    "status": {"type": "string", "max_length": 50, "enum": ["pending", "done"]},
    "due_date": {"type": "date", "required": false}
  },
  "projects": {
    "name": {"type": "string", "max_length": 100, "required": true}
  }
}

字段类型

类型	必需属性
string	max_length
text	无
integer	无
decimal	precision、scale
boolean	无
uuid	无
date	无
datetime	无
json	无

自动生成的字段

以下字段会自动生成，请勿定义：

• id（UUID 主键）
• created_at（datetime）
• updated_at（datetime）
• row_version（integer：行的版本号，插入时为 1，每次更新时递增 1）

用户身份验证

使用内置的 app_users 表：

{
  "employee_profiles": {
    "user_id": {"type": "uuid", "foreign_key": "app_users.id", "required": true},
    "department": {"type": "string", "max_length": 100}
  }
}

get_schema_reference 涵盖高级功能：行策略、计算字段、唯一组（对包含可空列的组使用 nulls_not_distinct，对在提交时检查的组使用 deferrable）、审计跟踪、生成的 API 的范围限定删除，以及声明所读取 row_version 的写入（If-Match、if_version）。

---

前端

进行前端开发时，请使用我们的 NPM 包：

npm install @rationalbloks/frontblok-auth @rationalbloks/frontblok-crud

这些包提供：

• frontblok-auth：身份验证、登录、令牌、用户上下文
• frontblok-crud：通过 getApi().getAll()、getApi().create() 等执行通用 CRUD 操作

---

环境变量

变量	说明	默认值
RATIONALBLOKS_API_KEY	您的 API 密钥（stdio；HTTP 客户端会在每个请求中将其作为 Bearer 令牌发送）。如果未设置，服务会列出其工具，并在每次调用时说明如何设置该密钥	-
TRANSPORT	stdio 或 http	stdio
HOST / PORT	TRANSPORT=http 时的绑定地址	0.0.0.0 / 8000
LOGICBLOK_URL	LogicBlok 网关基础 URL	https://logicblok.rationalbloks.com
RATIONALBLOKS_DEBUG	在启动错误时输出完整回溯信息	未设置

---

支持

• 文档： rationalbloks.com/documentation
• 电子邮件： [email protected]

许可证

专有 - 版权所有 2026 RationalBloks。保留所有权利。