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 &amp; design</b><br/>configure_project · synthesize_theme"]
        G{{"🛡️ <b>Safety &amp; 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 代理生态系统 — 流水线、代理、模型/算力路由

• 引导式入门与主题化

• 要求与凭据

• 🖱️ 安装 — Claude Desktop（一键）

• ⌨️ 安装 — Claude Code 与其他客户端

• 按项目配置（多门户）

• 入门

• 写入安全与工具门控

• 韧性、可观测性与加固

• 故障排除 · 安全 · 许可证

正在开发这个服务器而不是使用它？参见 CONTRIBUTING.md。

[!NOTE] 📚 完整文档位于 docs/ — 5 分钟快速入门、安装与配置、全部 40 个工具的生成参考、块编写、设计系统、版本控制、块内 zPortal API、代理生态系统与模型路由、工具门控、安全门 以及故障排除。

亮点

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 完全相同。类型化前端仍然存在，以便于编写：

文件输入 [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 查看每种资源的字段、创建所需的字段、支持的动词和风险域。

覆盖的资源： 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 以及本将写入的内容。

当前用户的个人资料现在是普通的资源 CRUD：get_resource / update_resource，使用 resource: "user", id: "me"。引导式迁移范围界定是 migration_kickoff 提示词（见下方提示词）。

参见 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）——用于直接调用（快速的外科手术式编辑，或从命令中派发一个代理）：

2 · 工作流 tier 开关——portal-block-pipeline.js 和 portal-audit.js 接受 args:{ …, tier } 并显式设置每个阶段的模型/推理强度：

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)"]]
    end

• configure_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，因此你无需安装任何东西。）

获取你的门户凭据

你需要三个值，在安装期间输入一次。

[!IMPORTANT] 请保管好 API 密钥和用户 ID。在 Claude Desktop 安装包中，它们被标记为 敏感（掩码显示、安全存储），绝不会离开运行服务器的机器。

安装 — Claude Desktop（一键安装）

1. 从最新版本下载 zuar-portal-mcp.mcpb。

2. 双击它，或将其拖放到 Claude Desktop 窗口中，会出现安装对话框。

3. 填写 门户 URL、门户 API 密钥、门户用户 ID（并可选择设置写入安全开关）。

4. 确认。工具、资源和提示词现在可供 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 对话：

1. 确认连接 — 例如 “列出我门户上的数据源” → 使用 list_resource (datasource)。

2. 查看真实数据 — 例如 “为我显示 Sales 数据源中的一些示例行” → 使用 profile_datasource（每列统计 + 原始示例行，让 Claude 先看到真实列名）。

3. 创建区块 — 例如 “创建一个名为“Total Orders”的 stat-card 区块，显示 Sales 数据源中的订单数” → 它会读取 zportal://guide/*，构建双字段的区块，调用 create_block，然后报告 UUID。

4. 迭代调整 — 例如 “把数字变大一些，并使用门户的主色调” 或 “把它改成按州计的订单柱状图” → 使用 update_block。

[!TIP] 在 Claude Code 中，运行 /portal-build "a stat card of total orders from Sales" 可将该规格推送到完整的受控门控流水线上；也可以调用 create_zportal_block 提示词，开始面向结构化“发现 → 构建 → 创建”流程。

写入安全与工具门控

每次写入都会标记一个风险域，并且独立门控：

{{ (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客户端）：

重试安全：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 创作的内容还会在不可信数据信封内返回，因此被污染的记录名称会被读取为数据，而不是指令。

故障排除

更多：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。