zuar-portal-mcp
Zuar Portal — MCP Server
让 Claude 替你操作你的 Zuar Portal(zPortal) — 编写 HTML 块、构建页面、管理数据源、查询、主题和用户,探索真实数据,并通过自然语言保留每次更改的 git 版本化、可回滚历史。
一个 MCP 服务器,将 Zuar Portal 的 REST + auth API 暴露给任何 MCP 客户端(Claude Desktop、Claude Code 等)。它把 "给我建一个销售仪表盘" 变成正确的认证调用序列 — 发现数据源 → 编写保存的查询 → 编写一个经过验证的 HTML 块 → 绑定它 → 将其放置在页面上 — 并附带内置的编写指南、分层写入安全和可回滚的历史记录。
[!TIP] 安装(Claude Code) — 克隆、构建、注册:
git clone https://github.com/zuarbase/Zuar-Portal-MCP-Public.git ~/zuar-portal-mcp cd ~/zuar-portal-mcp && npm install && npm run build claude mcp add zuar-portal --scope user -- node ~/zuar-portal-mcp/dist/index.js然后
cd到项目文件夹并运行/portal-setup将其连接到门户。详情 ↓无需终端(Claude Desktop): 从最新版本下载
zuar-portal-mcp.mcpb并双击它。详情 ↓
概览
flowchart TB
CD["<b>MCP Client</b><br/>Claude Desktop · Claude Code · any MCP client"]
CD -- "JSON-RPC / stdio" --> S
subgraph server["zuar-portal-mcp server"]
direction TB
S["index.ts → buildServer()"]
S --> BT["🧱 <b>Block tools</b><br/>typed authoring + place_blocks"]
S --> RT["📦 <b>Resource tools</b><br/>generic CRUD · 18 kinds (blocks included)"]
S --> AT["⚡ <b>Action tools</b><br/>query · profile · users · config"]
S --> VC["🕓 <b>Version-control tools</b><br/>snapshot · history · diff · restore"]
S --> EL["🪄 <b>Setup & design</b><br/>configure_project · synthesize_theme"]
G{{"🛡️ <b>Safety & integrity gates</b><br/>write-domain · structure · refs · impact · SQL"}}
BT & RT & AT & VC & EL --> G
end
G --> HTTP["portalClient.ts<br/>login · X-Api-Key · retry · circuit breaker"]
HTTP -- "/api + /auth · HTTPS" --> P[("Zuar Portal")]
BT -. "mirrors every content write" .-> GIT[("git VC repo<br/>revertible")]
classDef gate fill:#fde68a,stroke:#b45309,color:#000;
class G gate每次写入都带有风险域标签,并在任何内容到达门户之前通过安全门;每次成功的内容写入都会镜像到 git 仓库,以便可以回滚。
Related MCP server: LaunchNotes MCP Server
目录
Claude 可以用它做什么 — 38 个工具目录
Claude Code 代理生态系统 — 流水线、代理、模型/算力路由
正在开发这个服务器而不是使用它?参见
CONTRIBUTING.md。
[!NOTE] 📚 完整文档位于
docs/— 5 分钟快速入门、安装与配置、全部 40 个工具的生成参考、块编写、设计系统、版本控制、块内zPortalAPI、代理生态系统与模型路由、工具门控、安全门 以及故障排除。
亮点
🧰 统一表面 (v3.0.0) | 万物一模型 — 块是经过验证的注册表种类,一个声明式 |
⌨️ 一次安装,随处使用 | 克隆 + 构建 + |
🧱 验证式编写 | HTML 块通过规则检查的工具( |
🏢 多门户、多仓库 (v2.4.0) | 一次安装通过 |
🪄 浏览器设置,无需 JSON,模型不接触密钥 |
|
🤝 代理团队 | 在 Claude Code 中,一个受门控的 构建 → 样式 → 响应式 → 调试 → 对抗 → 顾问 专业子代理流水线为你构建块 — 每个都在合适规模的模型上。 |
🔒 企业级安全 (v2.5–2.6) | 风险域写入门控、最小权限工具范围、结构 + 引用完整性门、删除前影响分析,以及可选的审计日志。 |
🕓 可回滚历史 (v2.2.0) | 每次内容写入都镜像到 git 仓库 — 用 |
Claude 可以用它做什么
40 个工具 — 跨 11 个能力组的统一表面("资源就是资源")。完整的按工具参考是从实时服务器生成的(npm run gen:docs,因此不会漂移):docs/03 · 工具参考。
[!IMPORTANT] 从 2.x 升级? v3.0.0 是一次破坏性重新设计(48 → 37 个工具)。每个移除的 v2 名称都映射到 v3 原语 — 参见
CHANGELOG.md。设置PORTAL_COMPAT_TOOLS=1以临时将旧名称注册为转发到相同受门控 v3 处理器的弃用别名。
🧱 块工具 — 类型化 + 验证
块现在是一等注册表种类:使用通用资源工具(resource: "block")列出、获取和删除它们,块编写规则作为按种类验证器在注册表写入检查点运行 — create_resource (block) 的验证方式与 create_block 完全相同。类型化前端仍然存在,以便于编写:
工具 | 功能 |
| 对块负载运行编写规则而不写入 — 迭代直到干净。 |
| 创建 HTML 块(根据编写规则验证)。 |
| 更新 HTML 块 — 与当前块合并,因此未触及的字段得以保留。 |
文件输入
[4.2.0]—create_block、update_block和validate_block接受html_file和css_file。服务器读取字节,因此模型永远不会携带它们。将大块重新输入到工具调用中不是复制,而是重新转录:它会消耗 token 并静默地规范化字符(正则表达式字符类中的破折号以连字符形式出现会改变模式匹配的内容 — 并通过审查)。改为传递路径,就地编辑文件,只有增量会被转录。无论哪种方式,每个门都以相同方式运行。读取仅限于 CWD、VC 目录和任何PORTAL_FILE_ROOTS条目。 |bind_block_query| 将块绑定到数据源/查询(自动创建查询);设置ui_queries。 | |place_blocks| 一个声明式放置原语 — 在单个原子写入中在页面网格上添加、更新、隐藏或移除块。mode: "merge"追加/更新(并尊重remove: [...]);mode: "replace"+confirm: true使页面完全成为给定列表,同时保留幸存者自定义的grid.layouts和隐藏标志。 |
传递 resource 加上 body/id。调用 describe_resource 查看每种资源的字段、创建所需的字段、支持的动词和风险域。
工具 | 功能说明 |
| 列出资源,或描述某个资源(字段、操作、域)。 |
| 列出记录 — 始终返回分页信封 |
| 按 id 获取单条记录 — 例如 |
| 按名称搜索(不区分大小写的子串,或精确 id)跨类型 — 可选 |
| 只读依赖查询,双向: |
| 创建记录(按域进行写入门禁;按类型校验器 — 块(block)会获得完整的编写规则)。 |
| 更新记录(与当前记录合并;写入门禁)。 |
| 删除记录(写入门禁;删除前影响分析; |
| 只读扫描,检查格式错误的记录、悬空引用和风险 SQL。 |
覆盖的资源: block、layout(页面)、datasource、query、db_modification、partial、theme、snippet、translation、dashboard、tag、user、group、permission、access_policy、api_key、credential、system。
每个写入工具都接受
dry_run: true— 所有门禁都会运行(域、结构、按类型规则、引用、影响),不会写入任何内容,响应会携带applied: false以及本将写入的内容。
工具 | 功能 | 领域 |
| 每列统计信息(类型、不同值、最小值/最大值)以及原始样本行( | 读取 |
| 按 id 运行已保存的查询并返回结果(可选行数 | 读取 |
| 按名称运行已保存的数据库写入操作。需要 | 数据 |
| 更改当前用户的密码。 | 管理 |
| 一次调用即可读取用户的组成员身份和权限。 | 读取 |
| 替换用户的组和/或权限——每个提供的列表都是完整替换;需要 | 管理 |
| 按路径读取/设置门户配置。 | 读取 / 管理 |
| 门户版本 + 关于信息(能力检查)。 | 读取 |
| 显示当前生效的块编写规则。 | 读取 |
|
| 读取 |
| 从这里开始——通过一次经过身份验证的往返确认连接:门户、版本、当前登录身份、绑定状态和写入姿态,约 ~160 个字符。凭据错误时返回原因和修复方法,而不是虚假的成功 (始终可用)。 | 读取 |
| 报告当前姿态——启用/禁用的工具组、写入安全性、VC + 审计状态,以及其 | 读取 |
| 每个工具的调用次数、错误率、延迟、运行时间、熔断器状态 (始终可用)。 | 读取 |
| 将此文件夹连接到门户。默认情况下,它会打开一个本地回环设置页面(API 密钥在浏览器中输入,绝不通过模型),实时验证,写入 | 设置 |
| 无需重启即可从磁盘重新读取配置(项目/包/环境);重置门户会话。 | 设置 |
| 纯主题合成——偏好(± 一个受 SSRF 防护的网站颜色获取)→ 一个令牌映射,加上精确的 | 设计 |
| 只读迁移审计——每个块按功能分类,所有包含代码的字段都被扫描(识别注释/字符串),通过布局/局部模板/片段确定位置,硬编码来源扫描,绑定查询预检,浏览器探测检查清单。 | 迁移 |
| 从一次实时执行刷新已保存查询的存储列元数据——SQL 不变,默认试运行,往返已验证。 | 迁移 |
当前用户的个人资料现在是普通的资源 CRUD:
get_resource/update_resource,使用resource: "user", id: "me"。引导式迁移范围界定是migration_kickoff提示词(见下方提示词)。
工具 | 功能 |
| 显示 VC 是否已配置以及仓库状态。 |
| 将当前完整的门户状态提交到 git 仓库——一个持久的检查点。 |
| 显示内容变更的提交历史。 |
| 两个已提交版本之间的统一差异——按记录范围( |
| 将资源恢复到之前的已提交版本。 |
参见 docs/07 · 版本控制。
资源(zportal://guide/*)——Claude 在构建之前阅读的编写指南,因此即使在新机器上,区块也遵循 zPortal 约定:block-structure、currentblock、zportal-api、charting、conventions、design-system、visual-verification、migration-1.18、loading-overlay、migration-playbook 和 block-performance。
提示词——引导式工作流现在位于此处,而不是工具界面中(共 9 个):zuar_portal_start(最便宜的会话开启方式——一次调用确认连接,报告一行内容,询问下一步)、zuar_portal_quickstart(定位 → 路由)、create_zportal_block(发现 → 构建 → 创建)、setup_zuar_project(连接此文件夹,路由到 configure_project)、migrate_block_to_118(一个旧版区块 → 1.18 生命周期)、add_loading_overlay(官方认可的加载动画 + 淡出效果)、block_perf_pass(大数据集性能审计:测量 → 精简 SELECT * → 图表库预取 → 60 秒诚实的超时)、design_intake(引导式主题设计——逐步处理品牌/网站/密度/圆角,驱动 synthesize_theme,然后通过 create_resource 创建主题),以及 migration_kickoff(引导式迁移范围界定——批量处理范围决策,写入 .zuar-portal/migration-scope.json,然后运行 migration_preflight)。
Claude Code 代理生态系统
当此仓库作为你的 Claude Code 工作目录时,MCP 工具附带一个位于 .claude/ 中的专家团队。你不需要手动驱动 create_block/bind_block_query——你只需描述你想要的内容,一个带门禁的流水线就会构建、美化、加固并审查它。完整指南:docs/13 · 代理与工作流。
区块流水线
区块绝不会原样发布。一个规格说明会流经质量门禁,每个门禁都是一个专注的子代理:
flowchart LR
spec([spec]) --> B["🏗️ builder"] --> St["🎨 stylist"] --> R["📱 responsive"] --> D["🔧 debugger"]
D --> A{"🚨 adversary<br/><b>CODE GATE</b>"}
A -- "blocking (≤2 rounds)" --> D
A -- "clean" --> V{"👁️ visual<br/><b>GATE</b>"}
V -- "blocking (≤2 rounds)" --> D
V -- "clean / skipped" --> Ad["🧭 advisor"] --> ship([ship ✅])
classDef gate fill:#fde68a,stroke:#b45309,color:#000;
classDef ro fill:#dbeafe,stroke:#1d4ed8,color:#000;
class A,V gate
class Ad ro对抗者(门禁)对区块进行红队测试,并用证据证明每个发现;当它返回阻塞性发现时,流水线会循环回调试器。视觉门禁(拥有浏览器之眼的对抗者)随后在 Claude for Chrome 中打开渲染后的区块——截图、控制台、网络——空白渲染、控制台错误、非实时示例数据或溢出也会循环回调试器;它是尽力而为的,当扩展未连接或区块不在页面上时会跳过并附注说明。顾问会问"这是正确的区块吗?"所有门禁都是只读的——它们不携带任何写入工具,物理上无法修改门户(浏览/截图是只读的)。除了六个流水线代理之外,还有四个专家处理更广泛的任务:portal-data-expert、portal-theme-designer、portal-bulk-operator(快照优先)和 portal-onboarding。
查看门户(Claude for Chrome)
上述每个门禁都根据区块的代码和查询行进行推理——但一个区块可能通过验证、绑定,却仍然渲染为空白、抛出运行时控制台错误、溢出其网格单元格,或静默显示硬编码的示例回退而不是实时数据。连接 Claude for Chrome 扩展后,代理可以看到门户:打开页面、截取区块截图、读取浏览器控制台/网络——用于视觉调试和最终的视觉签核。
在设置时记录。
configure_project会询问你是否使用 Claude for Chrome,并将browser.claudeInChrome存储在./.zuar-portal/config.json中;get_capabilities会报告它。在值得的地方使用。 调试器在猜测之前先查看;对抗者负责视觉门禁;样式师和响应式专家会截取他们的工作截图(后者使用
resize_window逐步调整宽度);顾问会检查它是否一目了然。登录注意事项。 MCP 使用 API 密钥进行身份验证,但浏览器需要已登录的会话——要查看私有页面,你必须在 Chrome 中登录你的门户。MCP 无法为你登录。
设计上优雅降级。 没有扩展,或者区块不在页面上?每个代理都会回退到仅代码审查并明确说明。该原则记录在
zportal://guide/visual-verification资源中。
斜杠命令
命令 | 运行内容 |
| 首次按文件夹设置 + 对齐问答 → 配置 + 项目简报。 |
| 单个区块的完整 构建→样式→响应式→调试→对抗→顾问 流水线。 |
| 设计或应用门户级主题。 |
| 跨多个区块/页面的受保护批量变更(快照 → 预演 → 原子应用)。 |
| 对现有区块的只读审计——错误、无障碍性、响应式、设计契合度。 |
| 一次有边界的改进:评分 → 修复最差的区块 → 验证 → 全面检查 → 可证明的改进。可安全地安排为夜间任务。 |
| 单独运行对齐问答。 |
模型与推理强度路由
每个代理都运行在适合其工作的模型和推理强度上——在需要判断力的地方使用强模型,在机械性工作的地方使用廉价模型。三个组合层:
1 · 代理默认值(model:/effort: frontmatter)——用于直接调用(快速的外科手术式编辑,或从命令中派发一个代理):
层级 | 代理 | 模型 · 推理强度 |
🧠 判断 / 数据 | data-expert、adversary、advisor |
|
🛠️ 编写 | builder、stylist、debugger、bulk-operator、theme-designer、onboarding |
|
⚡ 机械性 | responsive-specialist |
|
2 · 工作流 tier 开关——portal-block-pipeline.js 和 portal-audit.js 接受 args:{ …, tier } 并显式设置每个阶段的模型/推理强度:
| 适用于… | 构建者 | 判断门禁 |
| 廉价迭代、一次性草稿、分诊 | sonnet/haiku · low | sonnet · medium |
| 正常的构建 / 审计 | sonnet · medium | opus · high |
| 生产 / 高管构建、发布前审计 | opus · high | opus · xhigh |
3 · 命令固定为 sonnet · medium——它们只负责编排(预检 → 派发 → 综合);质量存在于它们调用的代理/工作流中。/portal-build 和 /portal-audit 会根据你的措辞推断 tier。
MCP 服务器从不选择模型——只有驱动它的代理、命令和工作流才会选择。通过代理 frontmatter 或工作流的
ROUTING表重新分层;参见.claude/README.md。
引导式入门与主题设计
默认情况下,configure_project 从 MCP 进程提供一个极简的回环 Web 表单(http://127.0.0.1:<random-port>),
尽力打开你的浏览器,并立即返回链接——你在浏览器中输入
URL、API 密钥、写入安全开关、访问范围和版本控制,因此 API
密钥永远不会经过模型。保存时它会实时验证,写入被 gitignore 的 0600 配置,
并实时应用更改。当无法使用浏览器时,它会回退到 MCP 引导式询问(逐字段提示),
然后再回退到参数——传递 ui:false,或传递 portal_url + api_key +
user_id 作为参数。引导式主题设计是 design_intake MCP 提示词,它编排纯
synthesize_theme 工具。参见 浏览器设置表单。
flowchart TB
subgraph setup["🔌 configure_project — connect a portal"]
direction TB
s1["Portal URL"] --> s2["API key 🔒"] --> s3["User ID"] --> s4{"add GitHub VC?<br/>(optional)"}
s4 --> s4b{"use Claude for Chrome?<br/>👁️ visual checks"}
s4b --> s5["✓ live portal login<br/>✓ GitHub token + repo (API)"] --> s6[["writes .zuar-portal/config.json<br/>+ .gitignore"]]
end
subgraph intake["🎨 design_intake prompt — theme the portal"]
direction TB
d1["brand + website"] --> d2["fetch site 🛡️ SSRF-guarded<br/>→ suggest brand colors"] --> d3["palette · density · radius"]
d3 --> d4["header + sidebar style"] --> d5{"confirm?"} --> d6[["synthesize_theme →<br/>create_resource (theme)"]]
endconfigure_project拒绝覆盖现有配置,通过真实登录进行验证,并写入被 gitignore 的./.zuar-portal/。它还会询问你是否使用 Claude for Chrome(存储为browser.claudeInChrome),以便构建流水线可以看到你的区块渲染——视觉调试 + 最终的视觉门禁(参见 查看门户)。setup_zuar_project提示词和/portal-setup会路由到它;传递interactive: false以使用直接、无提示的路径。(取代 v2 的setup_portal和init_project_config。)design_intake提示词通过synthesize_theme的受 SSRF 保护的抓取获取品牌网站以建议调色板,然后逐步处理密度/圆角/页眉/侧边栏,并在你确认后通过create_resource创建theme资源。synthesize_theme本身是纯函数——它返回令牌映射和精确的create_with调用,并且从不写入。
要求
一个可通过 HTTPS 访问的 Zuar Portal,具有可以管理区块的账户(建议管理员)。
Node.js 18+——用于 Claude Code 和任何其他 MCP 客户端。(Claude Desktop 的一键式
.mcpb捆绑了自己的 Node,因此你无需安装任何东西。)
获取你的门户凭据
你需要三个值,在安装期间输入一次。
# | 值 | 位置 |
1 | 门户 URL | 基础 URL,不带尾部路径 — 例如 |
2 | 门户 API 密钥 | 管理 → 认证 → API 密钥 → 创建/复制一个密钥。该密钥继承其用户的权限 — 该用户必须拥有创建/编辑/删除区块的权限。 |
3 | 门户用户 ID | 管理 → 用户 → 你的用户 → 从页面 URL 中复制 UUID。 |
[!IMPORTANT] 请保管好 API 密钥和用户 ID。在 Claude Desktop 安装包中,它们被标记为 敏感(掩码显示、安全存储),绝不会离开运行服务器的机器。
安装 — Claude Desktop(一键安装)
从最新版本下载
zuar-portal-mcp.mcpb。双击它,或将其拖放到 Claude Desktop 窗口中,会出现安装对话框。
填写 门户 URL、门户 API 密钥、门户用户 ID(并可选择设置写入安全开关)。
确认。工具、资源和提示词现在可供 Claude 使用。
如需日后更新,在新的 .mcpb 上直接覆盖安装旧版本即可。
安装 — Claude Code 及其他 MCP 客户端
此服务器通过 stdio 使用 MCP 协议,因此任何支持 MCP 的客户端都可以使用它。先克隆仓库,构建一次,然后注册构建好的入口点 — 你需要 Node ≥ 18 和 git。
只需为任意项目注册一次:
git clone https://github.com/zuarbase/Zuar-Portal-MCP-Public.git ~/zuar-portal-mcp
cd ~/zuar-portal-mcp
npm install
npm run build
claude mcp add zuar-portal --scope user -- node ~/zuar-portal-mcp/dist/index.js[!IMPORTANT] 请将克隆下来的仓库放在原处。
claude mcp add会记录到dist/index.js的绝对路径,因此移动或删除该目录会导致服务器以spawn ENOENT报错。请为它选择一个长久稳定的位置 — 不要在/tmp,也不要在~/Downloads。
更新: 在原位置 pull 并重新构建。路径不会变化,所以无需重新注册 — 但请重启你的客户端,因为工具只在握手时获取。
cd ~/zuar-portal-mcp && git pull && npm install && npm run build然后,在每个门户项目文件夹中,将其连接到对应的门户:
mkdir ~/work/acme-portal && cd ~/work/acme-portal
claude
> /portal-setup/portal-setup 会询问你的三个值,用真实登录验证它们,并写入一个已被 gitignore 的 ./.zuar-portal/config.json。每个文件夹都可以指向不同的门户 — 参见按项目配置 ↓。
在项目中使用 .mcp.json(或 claude_desktop_config.json)— 将 args 指向你本地仓库构建好的入口点,必须是绝对路径(此处不会展开 ~):
{
"mcpServers": {
"zuar-portal": {
"command": "node",
"args": ["/Users/you/zuar-portal-mcp/dist/index.js"]
}
}
}[!IMPORTANT] 请让
env保持为空。不要把PORTAL_URL/PORTAL_API_KEY/PORTAL_USER_ID放在客户端配置中。 客户端env中的凭据会形成一个每个项目都会静默共享的全局门户 — 所以一个在你看来指向 staging 的文件夹,可能会悄然在 anonymize/test 环境,甚至在远程环境中将数据发布出去。请改用/portal-setup编写来写每个项目的凭据。这样每个项目都会带有一个绑定指纹,而且服务器会拒绝向任何不属于该文件夹所绑定门户的写入请求。环境变量仍然可以使用(很适合 CI,或者单门户安装),但只有项目文件这种方式能保证你不会被意想不到的事情分心。
按项目配置(多门户)
一个 MCP 安装可以在每个文件夹中驱动不同门户 — 以及不同 git 状态存储库。启动时,服务器按优先级从高到低逐层解析配置:
flowchart LR
A["1 · Project config<br/><code>./.zuar-portal/config.json</code><br/>(walks up from cwd)"] --> R{{"resolved<br/>credentials"}}
B["2 · Environment<br/><code>PORTAL_*</code> env vars<br/>(Desktop / MCPB)"] --> R
C["3 · Bundle config<br/><code>config.json</code> beside bundle"] --> R大多数配置都是按字段各自解析的,因此项目文件可以只包含 vc.dir 字段,并继承其他配置。空值会被忽略,所以 Desktop 中的空字段不会掩盖项目文件中的值。
[!WARNING] 门户凭据属于例外 — 它们必须来自同一层、且同时齐全 (v4.0.0)。只要某一层出现了
url/apiKey/userId中的任意一个,就同时提供全部三个,否则启动会失败且报错。 这里的按字段分层方式存在跨门户风险:一个项目如果只设置了url,但没有apiKey,会悄悄从环境中借用PORTAL_API_KEY— 一个门户地址配上另一个门户的密钥。
该文件对每个门户及其版本控制仓库使用同一套 schema:
{
"portal": { "url": "https://team-a.zuarbase.net", "apiKey": "…", "userId": "…" },
"vc": { "dir": "/path/to/team-a-state", "push": true,
"remote_url": "https://github.com/you/team-a-portal-state.git", "token": "…" }
}无需手工编辑 JSON,直接配置: 让 Claude 执行 configure_project(参见可引导上手 ↑)。get_capabilities 会在其 config 键下显示当前生效的门户/仓库(机密信息会隐藏)。./.zuar-portal/ 已被 gitignore,因此凭据绝不会被提交。
快速开始
新门户?从这一步开始。 在你要工作的文件夹中:
cd ~/work/acme-portal
claude
> /portal-setup一行命令。它会让文件夹与门户连接(写入 gitignore 凭据和绑定指纹)、分析数据源、询问业务情况,并生成其他 agent 会读取的项目简报。下面的所有内容都默认它已经执行完毕。
然后直接与 Claude 对话:
确认连接 — 例如 “列出我门户上的数据源” → 使用
list_resource (datasource)。查看真实数据 — 例如 “为我显示 Sales 数据源中的一些示例行” → 使用
profile_datasource(每列统计 + 原始示例行,让 Claude 先看到真实列名)。创建区块 — 例如 “创建一个名为“Total Orders”的 stat-card 区块,显示 Sales 数据源中的订单数” → 它会读取
zportal://guide/*,构建双字段的区块,调用create_block,然后报告 UUID。迭代调整 — 例如 “把数字变大一些,并使用门户的主色调” 或 “把它改成按州计的订单柱状图” → 使用
update_block。
[!TIP] 在 Claude Code 中,运行
/portal-build "a stat card of total orders from Sales"可将该规格推送到完整的受控门控流水线上;也可以调用create_zportal_block提示词,开始面向结构化“发现 → 构建 → 创建”流程。
写入安全与工具门控
每次写入都会标记一个风险域,并且独立门控:
域 | 覆盖范围 | 默认值 | 启用方式 |
| 区块、布局、局部视图、主题、查询、代码片段、翻译条目、仪表盘、标签 | 打开 | (除非只读,否则默认打开) |
| 数据源、db_modifications、 | 关闭 |
|
| 用户、用户组、权限、访问策略、API 密钥、凭据、系统、配置、密码 | 关闭 | 由 |
{{ (target: json_range(masToken)) }}
要完成每个写入工具,都统一设置 PORTAL_ALLOW_DATA_WRITES=1 是通过环境变量来开启的,而 PORTAL_ALLOW_ADMIN_WRITES=1 同理。
凡被拦截的写入,都会返回一条明确提示,说明应设置哪个环境变量;在该时刻,不会有任何请求送达门户。
run_db_modification 另要求每次调用都传递 confirm: true。
删除操作以及用户/密码变更都会向 MCP 客户端标记为破坏性操作。
统一 dry_run: true (v3.0.0) 适用于每个写入工具 — 所有门都会完整执行(域、结构、对象规则、引用、影响)但不会写入任何内容,响应会报告 applied: false,并说明本来会产生什么改动。Dry run 永远不能绕过门控。
最小权限工具权限控制 (v2.5.0) — 使用 PORTAL_DISABLE_TOOLS=users,config 可禁用整个能力组,或用 PORTAL_ENABLE_TOOLS=blocks,resources,data 配置成仅构建白名单(拒绝优先)。
从 2.x 升级 — PORTAL_COMPAT_TOOLS=1(默认关闭)将已移除的 v2 工具名注册为 compat 组中的已弃用别名;每个别名都会转发到相同受控的 v3 处理器,因此不会激发额外能力。
完整性门控 (v2.5–2.6,服务端强制,不能绕过) — 每次内容写入都会检查结构是否可兼容门户(缺 grid.layouts 的页面会被自动修复或拒绝)以及引用是否悬空;删除操作运行删除前影响分析,除非 force=true,否则拒绝将依赖者置为孤立;用户删除不允许删除最后一位管理员;未限定条件的批量 SQL(如使用破坏性动词,且没有真实 WHERE — 1=1 不算,还包括 MERGE/TRUNCATE/DROP/ALTER…DROP/GRANT)都需要 allow_unfiltered=true,另外当 SQL 不可检查时,安全检查默认失败(fail closed)。任何你在此时可以运行只读的 validate_portal 来做全量扫描。完整指南请参[JS→的信息] docs/16 · 安全与完整性。
无人值守循环安全性 (尚未发布) — 这些保证,让并行/通宵 agent循环可以放心无人值守:
不创建重复数据:如果创建过程中出现模棱两桥的失败(例如请求发出后网络断了),服务器会按名称去验证,且若已存在会复用;绝不再盲目重发。
run_db_modification则根本不会自动重试。不会丢失更新:把读取时拿到的
expected_updated_at传给update_resource/update_block/place_blocks,其他人若中途改动了,就会返回冲突错误而不是悄悄覆盖。不会遗留垃圾数据:把循环递归写的临时文件命名为
TMP · <用途>(或打上scratch标签),运行规则使用cleanup_scratch清理即可 — 默认是 dry-run,只删除未被引用且不是新近,并通过正常门控路径。可证明的改善:
score_portal会对每个区块/页面打分(0–100,考虑所有能机器检查的因子),并将当前分数与已保存的基线做比对,一条条的 delta 会清晰显示一个循环是否回退。管理员不能自锁:删除自己的管理员权限需要
allow_self_lockout=true;update_config和change_password必须使用confirm(配置文件还应返回previous_at_path,可一步还原)。
在 Claude Desktop 中,这些是安装弹窗的开关;在其他客户端中,作为环境变量设置。了解更多:docs/14 · 工具节流与指南(主页),或 docs/16 · 安全与完整性。
弹性、可观测性与加固
针对本地、单用户服务器,默认生产级行为 — 安全、零配置设计。
弹性(每个工具都通过它调用门户HTTP客户端):
行为 | 默认值 | 调整方式 |
单次尝试超时 | 30 秒 |
|
对瞬时故障(网络、408/425/429/5xx)的重试,指数退避 + 抖动,遵循 | 2 |
|
熔断器 — 上游宕机时快速失败 | 5 次失败后打开,冷却 15 秒 |
|
最大请求体大小 | 5 MB |
|
最大工具输入大小(在 MCP 边界拒绝) | 2 MB |
|
| 1,000 行( | 每次调用的 |
| 60k 字符 |
|
结果序列化 | 紧凑 JSON |
|
绑定重新验证频率 | 10 分钟 + 配置重载时 |
|
读缓存(GET;任何写入都会清除;写关键读绕过) | 5 秒 TTL |
|
重试安全:GET 对任何瞬时信号进行重试;写入仅在明确的 429/503 背压或可证明从未连接的网络故障时重试 — 绝不在模糊的 502/504 上重试,并且一个 create 如果其网络错误可能已经送达请求,则按名称验证并采用,而不是重新发送(不会静默重复)。
可观测性 — 每次调用都会获得请求 ID、延迟和错误计数。get_metrics(始终开启)报告每个工具的次数、错误率、延迟、运行时间和熔断器状态 — 仅元数据,不包含负载或机密。设置 PORTAL_LOG_FORMAT=json 以获取结构化 stderr 日志;PORTAL_AUDIT_LOG 为每次内容/数据/管理员写入追加仅元数据的 JSONL。
输出机密编辑 — 包含机密的字段(password、secret、token、api_key 等)在资源读取时被掩码为 [redacted],因此它们永远不会流入模型的上下文,并且机密也会按形状在任何值或名称中被捕获 — 连接字符串密码(postgresql://user:[redacted]@host)、JWT、PEM 私钥、AWS 密钥 ID — 包括在 execute_query / profile_datasource 结果中。通用十六进制和 key=value 形状故意不掩码(uuid、git SHA 和 SQL 参数是合法内容,会往返回写入)。标识符 *_id 字段永远不会被掩码;创建/更新响应保持完整(因此新生成的机密可以看到一次)。使用 PORTAL_REDACT_SECRETS=0 禁用。Portal 创作的内容还会在不可信数据信封内返回,因此被污染的记录名称会被读取为数据,而不是指令。
故障排除
症状 | 可能的原因 / 修复方法 |
"failed to connect" / | 客户端无法启动该命令。可能原因:(a) 克隆的仓库被移动或删除—— |
旧指南说要运行 | 该包不在 npm 上——该命令无法工作,会以 |
读取正常,但每次写入都被拒绝为 | 此文件夹未绑定到门户。在其中运行 |
"缺少门户凭据:…" |
|
"…必须同时提供 url/apiKey/userId 三项" | 某个配置层只指定了部分凭据而非全部。这是有意拒绝的——没有 |
"门户登录失败:HTTP 401/403" | API 密钥或用户 ID 错误,或用户缺少权限。请重新生成密钥;确认该用户可以管理块。 |
| 你的门户早于保存查询 API(1.18+)。请使用 |
工具没有出现在 Claude 中 | 重启客户端——工具列表只在握手时获取一次,因此新添加的服务器(或新版本)不会出现在正在运行的会话中。对于 |
你升级了,但新工具/规则没有出现 | 原因相同:客户端仍在运行旧进程。请重启它。 |
缺少 v2 工具名称( | v3.0.0 已移除/重命名它——请参阅 |
想查看它在做什么 | 设置 |
"熔断器已打开" | 上游反复失败;短暂冷却后会自动恢复。 |
存储的密钥返回 | 读取脱敏已开启。请为该会话设置 |
更多:docs/12 · 故障排查。
安全
凭据绝不会被记录。调试输出(由
PORTAL_DEBUG=1控制)仅进入 stderr,因此绝不会破坏 MCP stdio 流。API 密钥和用户 ID 在包清单中被声明为敏感。
服务器只与您配置的门户 URL 通信;启动时会验证基础 URL 是否为格式良好的
http(s)源。synthesize_theme的网站抓取(由design_intake提示驱动)受 SSRF 防护。create_block/update_block仅限于type: "html",并在任何门户调用之前拒绝其他类型。包含密钥的字段在读取时会被脱敏;工具输入和请求体有大小上限。
完整的安全态势请参阅 SECURITY.md:按工具组划分的数据接触矩阵、凭据处理、网络出口和数据保留。
许可证
MIT。
Available Tools
40 toolsbind_block_queryBind a block to a datasource/queryA
Give an existing block its data binding so currentBlock.queryResults[0] is populated. Pass an existing query_id, OR a datasource_id (a SELECT * query is auto-created against it and linked). Sets the block's ui_queries while preserving its html/css/name. The bound query must have a datasource (auto-created ones do) or the portal rejects it.
Inputs: block_id (required), sql, dry_run, query_id, +2 more.
change_passwordChange the current user's passwordADestructive
Change the authenticated user's password. Requires admin writes enabled (PORTAL_ALLOW_ADMIN_WRITES=1) and confirm=true — this rotates the credential the current session signs in with. Passwords are never logged or echoed back.
Inputs: new_password (required), old_password (required), confirm.
check_connectionConfirm the portal connectionARead-only
START HERE — confirm in ONE authenticated round-trip which Zuar Portal this folder is on, its version, who you're signed in as, what you may write, and whether browser assist is on. Proves the credentials actually work, and on failure reports the reason and the fix. Returns a few short fields rather than a JSON wall — call get_capabilities only if you then need the full tool/group, VC and audit posture.
Inputs: no named parameters.
cleanup_scratchSweep scratch leftovers (loop hygiene)ADestructiveIdempotent
Find records that scratch conventions mark as disposable — a name starting 'TMP ·', a 'scratch'/'tmp' tag, or '(delete me)' in the name; optionally '(diagnostic)' records and unnamed ones. DRY-RUN BY DEFAULT: reports every match, why it matched, and what (if anything) references it. confirm=true deletes only the safe candidates — unreferenced, not recently touched — through the same gated delete path as delete_resource. Content deletes are VC-recorded (restorable); db_modification deletes are NOT restorable and only ever match the explicit TMP/scratch markers.
Inputs: kinds, confirm, max_delete, include_unnamed, +2 more.
configure_projectConfigure this project's portal connectionA
Connect THIS folder to a Zuar Portal — one install can serve many portals, each folder gets its own ./.zuar-portal/config.json. By default this opens a tiny local setup page (http://127.0.0.1:, single-use token) served by this MCP process, best-effort opening your browser and returning the link immediately (non-blocking): you type the URL, API key, write-safety toggles, access scope, and version-control settings IN THE BROWSER, so the API key never passes through the model. On Save it validates the portal with a live login, writes the config + a .gitignore (0600, secrets never committed), then PINS the folder to the portal's live identity (later writes to a DIFFERENT portal are refused) — all applied live, no restart; the success page points you at design_intake to scaffold this project's design.md + CLAUDE.md. The write-safety toggles are set ONLY via this human form (no tool argument sets them), and WIDENING data/admin writes additionally needs the env opt-in PORTAL_ALLOW_OPERATOR_TOGGLES, so an agent can never widen its own permissions. Falls back to MCP elicitation, then headless arguments, when a browser can't be used: pass ui:false, or pass portal_url + api_key + user_id as arguments — that path also scaffolds a project design.md every block inherits and a managed CLAUDE.md block. Refuses to overwrite an existing config via the args path unless overwrite=true; the browser form prefills current values and Save is your consent. Secrets are stored locally and never echoed.
Inputs: ui, vc_dir, api_key, density, +18 more.
create_blockCreate an HTML blockA
Create a new HTML block. Accepts the full block payload (name, css, json_data, ui_queries, tags, access). Type is always html. Read the zportal://guide/* resources first to produce a correct two-field block. Equivalent to create_resource resource="block" with a typed schema; the authoring rules, structural and referential gates run either way. dry_run:true previews.
Inputs: name (required), css, data, tags, +7 more.
create_resourceCreate a resource recordA
Create a record. body carries the resource's fields (see describe_resource). Writes are gated by risk domain: content is on by default; data (datasources/db_modifications) needs PORTAL_ALLOW_DATA_WRITES; admin (users/groups/etc.) needs PORTAL_ALLOW_ADMIN_WRITES.
Inputs: body (required), resource (required), dry_run.
delete_resourceDelete a resource recordADestructiveIdempotent
Delete a record by id (or name, for tags). Requires confirm:true. Same write gating as create_resource — the record's risk domain must be enabled. Refuses if other records depend on the target (pass force=true to override) and refuses to remove the last admin / your own account. Content records can be reverted with restore_resource when version control is on.
Inputs: id (required), confirm (required), resource (required), force, +1 more.
describe_resourceDescribe a portal resourceARead-only
Show a resource's path, write fields, required-to-create fields, supported verbs, and risk domain. Omit resource to list every resource this server manages. Call this before create_resource/update_resource so the body matches the portal schema.
Inputs: resource.
execute_queryExecute a saved queryARead-only
Run a saved query by id and return its results. Pass params as a { name: value } map for parameterized queries. Rows RETURNED are capped at 1,000 by default (a SELECT * on a big table otherwise blows the context budget); the response notes when it truncated. Pass limit for a different cap, or limit:0 for ALL rows (know your table size first). Read-only.
Inputs: query_id (required), limit, params.
find_resourceFind resources by nameARead-only
Search records across resource kinds by name — "find the query named X" without listing whole collections client-side. Case-insensitive substring match on name/title, plus exact-id match. Defaults to every non-admin kind (block, layout, partial, theme, query, snippet, translation, dashboard, tag, datasource, db_modification); pass kinds to narrow or to include admin kinds. Optional tag filters to records carrying that tag.
Inputs: query (required), tag, kinds, limit, +1 more. Returns: query, errors, offset, results, +4 more
get_capabilitiesServer capabilities, posture & active configARead-only
Report what this server can currently do AND which portal it's pointed at: enabled/disabled tool groups and tools, the write-safety posture (read-only / data / admin), the resolved project config (portal URL + user, config file path), version-control status, browser-assist flag, and whether audit logging is on. THE orientation call — run it before acting; it stays available even when other tool groups are gated off. All secrets are redacted.
Inputs: no named parameters.
get_configGet portal configARead-only
Fetch the portal's configuration document.
Inputs: no named parameters.
get_metricsTool-call metricsARead-only
Report in-memory observability metrics for THIS server process: per-tool call count, error count/rate, and latency (avg/max/last ms), plus rolled-up totals, uptime, and the upstream circuit-breaker state. Metadata only — no payloads or secrets. Resets when the process restarts. Use it to spot a failing tool or a degraded portal upstream.
Inputs: no named parameters.
get_referencesWho references this record?ARead-only
Read-only dependency query for a record, both directions: dependents = records that would break if this one were deleted (the same analysis the delete gate runs — pages placing a block, queries reading a datasource, blocks bound to a query, system defaults), and references = records THIS one points at, each flagged exists:false when dangling. Use it before a delete/rename, or to trace where a datasource/query is used.
Inputs: id (required), resource (required). Returns: id, note, resource, dependents, +1 more
get_resourceGet one resource recordARead-only
Fetch a single record of a resource by its id (or name, for tags). Control the token cost: summary:true returns an overview (bulk fields become size stats — a block drops ~2,750 → ~150 tokens); fields:[…] returns just those top-level fields (+ id). Omit both for the full record.
Inputs: id (required), resource (required), fields, summary.
get_rulesGet active authoring rulesARead-only
Return the active block-authoring rules: per-rule enforcement severities and the conventions text. Read this to see what create_block/update_block will enforce.
Inputs: no named parameters.
get_user_accessGet a user's access (groups + permissions)ARead-only
Return the groups a user belongs to and the permissions granted to them, in one call. The user record itself is get_resource resource="user" (id "me" = the authenticated user).
Inputs: user_id (required).
get_versionGet portal version / capabilitiesARead-only
Fetch the portal version and about info — use it to gate version-specific endpoints (e.g. saved queries are 1.18+). To confirm the connection, call check_connection instead.
Inputs: no named parameters.
list_resourceList a resource collectionARead-only
List records of a resource (block, datasource, layout, query, theme, partial, user, group, db_modification, etc.). Use this for discovery — e.g. find a datasource UUID before authoring a block. Always returns the paged envelope { total, offset, limit, returned, truncated, records } (default page size 100, max 500) — check truncated and walk offset for the rest. Optional query adds URL query params. First pages (offset 0) fetch SERVER-SIDE when the portal honors ?limit — total is then null while truncated=true (walk until truncated=false; the portal didn't send a count). Pages are also BYTE-capped (PORTAL_LIST_BYTE_CAP, default 60k chars): an oversized page auto-projects to { id, name } and says so in note — prefer only_names/fields for discovery and get_resource (summary/fields) for detail.
Inputs: resource (required), limit, query, fields, +2 more. Returns: note, limit, total, offset, +5 more
migration_preflightMigration preflight probe (read-only)ARead-only
Empirical migration audit of the connected portal — run BEFORE writing any conversion pattern. Covers every block by FUNCTION, not just scripted ones: classifies each placed block (scripted/template/markup/native-widget), scans EVERY code- and config-bearing field (not just the html body) for legacy patterns — comment/string-aware so a commented-out call doesn't drive scope — flags hardcoded portal origins (environment portability), maps placement through layouts AND partials AND snippets (an 'orphan' is unreachable through all three), and preflights every bound query: does it execute, does it return column metadata, are numeric columns delivered as strings, is the STORED column metadata stale (repair_query_metadata fixes that). Also returns the browser-probe checklist for the runtime questions a server-side scan cannot answer. Read-only.
Inputs: limit, max_queries, execute_queries.
namingNaming convention (suggest / parse)ARead-only
The SCOPE · Kind Subject naming convention as a pure function. action=suggest generates a conforming display name, stable slug and facet tags from parts (kind required; scope accepts a code or facet tag: HC=healthcare, FIN=financial, SC=supply-chain, RT=retail, IOT=iot, CRM=crm, MKT=marketing, EXEC=executive, SYS=system, DW=data-warehouse, TMP=scratch; kind is one of: kpi, chart, table, filter, hero, navigation, map, text, page, partial, query, datasource, theme — resource kinds like datasource/query/page omit the kind word from the display name). action=parse decomposes an existing display name (name required) and grades conformance. Prefer suggest over hand-naming so names — and the slugs/tags derived from them — stay consistent.
Inputs: action (required), kind, name, scope, +3 more.
place_blocksPlace blocks on a page (declarative)AIdempotent
Declaratively manage which blocks a page (layout) shows, in ONE atomic read-modify-write. mode=merge (default): upsert the blocks entries (re-placing updates position) and remove any ids in remove; other blocks on the page are untouched. mode=replace: the page becomes EXACTLY the blocks list (requires confirm:true; customized grid.layouts, hidden flags and geometry of surviving blocks are preserved). Each entry: { block_id, position?, height?, hidden? }. An entry with NEITHER position NOR height keeps an already-placed block's current geometry (safe for hidden-only toggles); a NEW block with no position auto-stacks full-width below existing content in array order; pass position (or height) to re-place explicitly. Blocks are placed, not created (create_block first) and never deleted (delete_resource does that). dry_run:true previews the final grid without writing. GRID BUDGET: every box is a % of the page's grid.layouts.{bp}.height (default 100), and blocks stack by accumulating top — so Σ(heights) must stay <= the grid height or the page CLIPS silently. The auto-place default is 50%, so THREE defaulted blocks already overflow: pass an explicit height for each. Budget guide at 100: filter bar 8-10, KPI band 18-22, chart card 30-35, table 35-40. Pair blocks side by side (same top, width 50 each) to buy vertical room before making the page taller, and aim to land everything above the fold at lg (the portal's header/footer/sidebars already take their share). If it truly won't fit, raise the grid height in increments of 25 (100 -> 125 -> 150) via update_resource. The response reports overflow when content exceeds the grid.
Inputs: layout_id (required), mode, blocks, remove, +3 more.
profile_datasourceProfile a datasource (stats + sample rows)ARead-only
Sample a datasource and return per-column statistics — inferred type, non-null/empty counts, distinct value count, sample distinct values for categoricals, and min/max for numerics — PLUS raw sample rows (sample.columns + sample.rows) so you see real column names and literal values in the same call. Exactly what you need to design filters, choose chart dimensions, pick aggregations, and match a block's column constants to reality. Profiles over a sample (default 500 rows); sample_rows caps the raw rows returned (default 10, 0 for stats only).
Inputs: datasource_id (required), sample_rows, sample_size, distinct_cap.
reload_configReload configuration from diskAIdempotent
Drop every in-process config cache and re-read config from disk (project .zuar-portal/config.json, bundle config, env-derived settings), resetting the portal HTTP session. Use after MANUALLY editing a config file — edits to the already-loaded project file are also picked up automatically (mtime-aware), but a NEWLY CREATED config file or bundle/env change needs this. Note: tool-surface gating is registered at startup and still needs a server restart to change.
Inputs: no named parameters.
repair_query_metadataRepair a saved query's column metadataAIdempotent
Re-introspect and store a saved query's COLUMN METADATA without touching its SQL or datasource binding — safe by construction (name/datasources/raw_sql/sql_form are re-sent verbatim; only columns is refreshed from a live execution). Stale stored metadata makes bound blocks render blank/wrong after schema or version moves; migration_preflight flags it as stored_metadata_stale. Dry-run by default: reports the stored-vs-live diff; pass apply:true to write. Round-trip verifies the write and mirrors it to version control.
Inputs: query_id (required), apply, params.
restore_resourceRestore a record to a previous versionA
Revert a content record — or a datasource — to a prior committed version and write it back through the same gated write path as any other update (a DELETED block is recreated under its old id; a datasource restore needs data writes enabled). Omit ref to undo the most recent change, or pass a commit hash from vc_log; inspect it first with vc_diff. The restore is itself committed. Requires PORTAL_VC_DIR. NOT covered (never snapshotted): users, groups, permissions, credentials, api_keys, system records, db_modifications.
Inputs: id (required), resource (required), ref.
run_db_modificationRun a database modificationADestructive
Execute a saved db_modification (INSERT/UPDATE/DELETE) by name. This WRITES to a database — and database writes have NO snapshot/rollback, unlike portal content. Requires data writes enabled (PORTAL_ALLOW_DATA_WRITES=1) and confirm=true. Refuses an unscoped mass write (UPDATE/DELETE/MERGE without a real WHERE — 1=1 doesn't count — TRUNCATE, DROP, ALTER…DROP, GRANT/REVOKE) unless allow_unfiltered=true; the check is a best-effort classifier and fails closed if the SQL can't be inspected. Pass params as a { name: value } map, or params_list for bulk rows.
Inputs: name (required), confirm (required), params, autocommit, +3 more.
score_portalScore portal quality (blocks + pages, with baseline delta)AIdempotent
Score every block and page 0–100 on what is MECHANICALLY checkable — authoring-rule violations, dangling query bindings, orphaned blocks, naming-convention fit, SELECT * bindings, oversized HTML, unscoped CSS, page overflow and dangling placements. 100 means 'nothing mechanically wrong', NOT 'well designed' — visual/business judgment stays with review agents. Scratch-marked records are excluded (cleanup_scratch handles them). With version control on, compares against the last saved baseline (improved/regressed/added/removed per record) — the loop discipline: score, improve, re-score, and only update_baseline=true after a verified improvement.
Inputs: detail_below, update_baseline.
set_user_accessSet a user's access (groups and/or permissions)ADestructiveIdempotent
Replace a user's group membership and/or permission set — pass groups, permissions, or both; each provided list is a FULL REPLACE (not additive), an omitted one is untouched. Requires admin writes enabled (PORTAL_ALLOW_ADMIN_WRITES=1) and confirm:true. dry_run:true reports the current access next to the proposed lists without writing. Stripping YOUR OWN admin access is refused unless allow_self_lockout=true.
Inputs: confirm (required), user_id (required), groups, dry_run, +2 more.
snapshot_portalSnapshot portal content to gitA
Export every content resource (blocks + layouts/queries/themes/partials/snippets/translations/dashboards/tags) AND datasources to the version-control repo and commit. Run once to seed history, or anytime to capture a checkpoint. Verifies COVERAGE: staged counts are checked against live listings and any resource kind that failed to export is reported (a rollback snapshot that silently skipped saved queries is not a rollback). Requires PORTAL_VC_DIR.
Inputs: message.
synthesize_themeSynthesize a portal theme from brand preferencesARead-onlyIdempotent
Turn brand preferences into a portal theme spec — a customProperties token map + css — WITHOUT creating anything. Give a website_url and it fetches the homepage (SSRF-guarded) to suggest brand colors when primary_color is omitted. Create the returned theme with create_resource resource="theme" body={ name, json_data: { customProperties, css } } (a normal VC-tracked content write); the response includes that exact call as create_with. The design_intake PROMPT walks a user through these choices conversationally.
Inputs: font, mode, header, radius, +8 more.
update_blockUpdate an HTML blockAIdempotent
Update an existing HTML block by UUID. Only the fields you pass change — the server merges them over the current record, so an omitted ui_queries keeps the existing data binding. Authoring rules validate only your delta; violations the stored block already has are grandfathered to warnings, never blockers. dry_run:true previews the exact write.
Inputs: block_id (required), css, data, name, +10 more.
update_configUpdate portal configAIdempotent
Set a value at a config path. path is the key path (array of strings); value is the new value; merge merges into an existing object instead of replacing. Portal-wide setting: requires admin writes enabled (PORTAL_ALLOW_ADMIN_WRITES=1) AND confirm=true; dry_run=true previews the current value without writing. The response returns previous_at_path — pass it back to revert. Pointing default_dashboard/theme_id at a missing record is refused.
Inputs: path (required), merge, value, confirm, +1 more.
update_resourceUpdate a resource recordAIdempotent
Update a record by id. Only the fields in body change; the server merges them over the current record (portal PUT is full-replace) so untouched fields are preserved. Same write gating as create_resource. For loop/parallel safety, pass expected_updated_at (the updated_at you saw when reading) — the write is then refused with a conflict if anyone changed the record in between, instead of silently overwriting their work.
Inputs: id (required), body (required), resource (required), dry_run, +1 more.
validate_blockValidate a block (no write)ARead-only
Run the same authoring rules as create_block/update_block against a block payload WITHOUT writing it. Use it to iterate on HTML/JS/CSS until it's clean — it flags the footguns that only surface in a live browser (literal $ String.replace mangling, {{ }} interpolation, data polling, unscoped CSS, full docs, unsafe JS). Returns { valid, errors, warnings }. Pass against_block_id to preview GRANDFATHERING: errors the stored block already has are reported as pre_existing (update_block flags them as warnings instead of blocking).
Inputs: css, data, name, css_file, +4 more.
validate_portalValidate portal integrity (read-only)ARead-only
Sweep every page (layout), partial, theme, query, block, db_modification and system record and report anything that would break or render wrong: structurally malformed records (e.g. a page missing grid.layouts — the 'all pages vanished' bug), dangling references (a page/block pointing at a deleted block/query/datasource), unscoped mass-write SQL (UPDATE/DELETE with no WHERE, TRUNCATE, DROP), and datasource hygiene (a name that leaks a connection-string/password, or a datasource reporting a broken connection). Fixes nothing — run it after bulk changes or on a schedule to catch latent breakage before users do.
Inputs: limit.
vc_diffDiff two committed versionsARead-only
Unified diff between two committed versions — of one record (resource + id) or the whole repo. Defaults answer "what did the last change change?": ref_b = HEAD, ref_a = the previous commit touching the record (or HEAD's parent repo-wide). Pass hashes from vc_log for any pair. Inspect the diff BEFORE restore_resource so a revert is never blind. Requires PORTAL_VC_DIR.
Inputs: id, ref_a, ref_b, resource, +1 more. Returns: ok, diff, note, ref_a, +3 more
vc_logVersion-control historyARead-only
List recent commits, optionally scoped to one record. Use a returned hash with restore_resource to revert to that version. Requires PORTAL_VC_DIR.
Inputs: id, limit, resource.
vc_statusVersion-control statusARead-only
Report whether portal version control is enabled (set PORTAL_VC_DIR to a git repo path), the repo location, and push config (PORTAL_VC_PUSH / PORTAL_VC_REMOTE). When enabled, every content write (blocks, layouts, queries, themes, partials, snippets, translations, dashboards, tags) is auto-committed so it can be reverted with restore_resource.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 40 tools
Most tools have clear, distinct purposes targeting specific resources or actions. However, there is some overlap between generic resource CRUD (create_resource, update_resource) and typed block wrappers (create_block, update_block), and a cluster of status/config tools (get_rules, get_config, get_capabilities, get_version, check_connection) that could be confused at a glance.
The vast majority follow a consistent verb_noun snake_case pattern (get_, create_, update_, delete_, list_, validate_, execute_, etc.). Minor deviations exist: 'naming' is a bare gerund, 'migration_preflight' is noun_noun without a verb, and the 'vc_*' prefix (vc_status, vc_log, vc_diff) uses a shortened prefix instead of full verbs.
At 40 tools, this server is well beyond the 25-tool threshold where tool sets become heavy and hard for an agent to navigate. While each tool has a specific role, the surface bundles many subdomains (content, queries, users, config, version control, migration) into a single server, making selection more difficult.
The generic CRUD tools (create_resource, get_resource, update_resource, delete_resource, list_resource, describe_resource) cover every resource kind, while typed tools handle blocks, queries, datasources, users, config, version control, and auditing. This provides full lifecycle coverage with no obvious dead ends: missing specific operations (e.g., creating a query) can be achieved via the generic resource tools.
Maintenance
Related MCP Connectors
No-code databases, forms, portals and AI sites. Manage records and automation via natural language.
No-code databases, forms, portals and AI sites. Manage records and automation via natural language.
No-code databases, forms, portals and AI sites. Manage records and automation via natural language.
Query, explore, and manage your databases through natural conversation.
Related MCP Servers
- FlicenseAqualityNot gradedmaintenanceEnables comprehensive PostgreSQL database management through natural language including queries, schema operations, user management, and administrative tasks. Features enterprise-grade connection pooling, transaction support, and full database administration capabilities.11123 npm1-
- AlicenseAqualityCmaintenanceEnables management of LaunchNotes projects and announcements through natural language, including customization of themes, colors, content, and publishing announcements with full read/write access via the LaunchNotes GraphQL API.2217 npmMIT
- AlicenseAqualityNot gradedmaintenanceAI-powered WordPress management that enables creating and editing posts, pages, media, plugins, themes, and Gutenberg blocks through natural language with safe-by-default writes and full rollback support.524 npm-
- FlicenseNot gradedqualityDmaintenanceEnables natural language management of apps, services, resources, attributes, and data via the Dimetrics API with full CRUD operations and advanced filtering.-