Skip to main content
Glama

Zuar Portal — MCP Server

Let Claude operate your Zuar Portal (zPortal) for you — author HTML blocks, build pages, manage data sources, queries, themes and users, explore real data, and keep a git-versioned, revertible history of every change, all through natural language.

release MCP Zuar Portal node one-click install license


An MCP server that exposes a Zuar Portal's REST + auth APIs to any MCP client (Claude Desktop, Claude Code, …). It turns "build me a sales dashboard" into the right sequence of authenticated calls — discover data sources → write a saved query → author a validated HTML block → bind it → place it on a page — with bundled authoring guidance, layered write-safety, and a revertible history.

TIP

Install (Claude Code) — clone, build, register:

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

Then cd to a project folder and run /portal-setup to connect it to a portal. Details ↓

No terminal (Claude Desktop): download zuar-portal-mcp.mcpb from the latest release and double-click it. Details ↓

At a glance

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

Every write is tagged with a risk domain and passes the safety gates before anything reaches the portal; every successful content write is mirrored to a git repo so it can be reverted.

Related MCP server: LaunchNotes MCP Server

Contents

Working on the server rather than with it? See CONTRIBUTING.md.

NOTE

📚 Full documentation lives in docs/ — a 5-minute quickstart, install & config, a generated reference for all 40 tools, block authoring, the design system, version control, the in-block zPortal API, the agent ecosystem & model routing, tool gating, safety gates, and troubleshooting.

Highlights

🧰 One uniform surface (v3.0.0)

One model for everything — blocks are a validated registry kind, one declarative place_blocks, uniform dry_run on every write, paged lists, and new reads (find_resource, get_references, vc_diff). Breaking; PORTAL_COMPAT_TOOLS=1 bridges the old v2 names.

⌨️ Install once, use everywhere

Clone + build + claude mcp add … -- node …/dist/index.js, then /portal-setup per project. Or a one-click .mcpb for Claude Desktop — no terminal at all.

🧱 Validated authoring

HTML blocks go through rule-checked tools (create_block/update_block/validate_block) — and create_resource (block) passes the same per-kind validator at the registry chokepoint, so footguns are caught before the portal is touched.

🏢 Multi-portal, multi-repo (v2.4.0)

One install drives a different portal + git repo per folder via ./.zuar-portal/config.json.

🪄 Browser setup, no JSON, no key in the model

configure_project serves a local loopback web form — you type the API key in your browser, so it never passes through the model; it validates live and writes a 0600 config. Falls back to elicitation / arguments. The design_intake prompt walks theming and drives synthesize_theme.

🤝 A team of agents

In Claude Code, a gated build → style → responsive → debug → adversary → advisor pipeline of specialist subagents builds blocks for you — each on a right-sized model.

🔒 Enterprise safety (v2.5–2.6)

Risk-domain write gating, least-privilege tool scoping, structural + referential integrity gates, pre-delete impact analysis, and an opt-in audit log.

🕓 Revertible history (v2.2.0)

Every content write mirrors to a git repo — revert any change with restore_resource.


What Claude can do with it

40 tools — one uniform surface ("a resource is a resource") across 11 capability groups. The full per-tool reference is generated from the live server (npm run gen:docs, so it can't drift): docs/03 · Tools Reference.

IMPORTANT

Upgrading from 2.x? v3.0.0 is a breaking redesign (48 → 37 tools). Every removed v2 name maps to a v3 primitive — see CHANGELOG.md. Set PORTAL_COMPAT_TOOLS=1 to temporarily register the old names as deprecated aliases that forward to the same gated v3 handlers.

🧱 Block tools — typed + validated

Blocks are now a first-class registry kind: list, fetch, and delete them with the generic resource tools (resource: "block"), and the block-authoring rules run as a per-kind validator at the registry write chokepoint — create_resource (block) is validated exactly like create_block. The typed fronts remain for ergonomic authoring:

Tool

What it does

validate_block

Run the authoring rules against a block payload without writing — iterate until clean.

create_block

Create an HTML block (validated against authoring rules).

update_block

Update an HTML block — merged over the current block so untouched fields survive.

File input [4.2.0] — create_block, update_block, and validate_block take html_file and css_file. The server reads the bytes, so a model never carries them. Retyping a large block into a tool call is not a copy but a re-transcription: it burns tokens and silently normalizes characters (an em dash inside a regex character class arriving as a hyphen changes what the pattern matches — and passes review). Pass a path instead, edit the file in place, and only the delta is ever transcribed. Every gate runs identically either way. Reads are contained to the CWD, the VC dir, and any PORTAL_FILE_ROOTS entry. | bind_block_query | Bind a block to a datasource/query (auto-creates the query); sets ui_queries. | | place_blocks | One declarative placement primitive — add, update, hide, or remove blocks on a page grid in a single atomic write. mode: "merge" appends/updates (and honours remove: [...]); mode: "replace" + confirm: true makes the page exactly the given list while preserving survivors' customized grid.layouts and hidden flags. |

Pass resource plus a body/id. Call describe_resource to see each resource's fields, required-to-create fields, supported verbs, and risk domain.

Tool

What it does

describe_resource

List resources, or describe one (fields, verbs, domain).

list_resource

List records — always returns the paged envelope {total, offset, limit, returned, truncated, records} (default limit 100, max 500).

get_resource

Get one record by id — e.g. resource: "user", id: "me" for the current user's profile.

find_resource

Search by name (case-insensitive substring, or exact id) across kinds — optional kinds, tag, limit/offset; defaults to all non-admin kinds.

get_references

Read-only dependency query, both directions: dependents (who breaks if this is deleted — the same analysis the delete gate runs) and references (what this record points at, each flagged exists: false when dangling).

create_resource

Create a record (write-gated by domain; per-kind validators — blocks get the full authoring rules).

update_resource

Update a record (merged over current; write-gated).

delete_resource

Delete a record (write-gated; pre-delete impact analysis; confirm/force).

validate_portal

Read-only sweep for malformed records, dangling refs, and risky SQL.

Covered resources: block, layout (pages), datasource, query, db_modification, partial, theme, snippet, translation, dashboard, tag, user, group, permission, access_policy, api_key, credential, system.

Every write tool accepts dry_run: true — every gate runs (domain, structure, per-kind rules, references, impact), nothing is written, and the response carries applied: false plus what would have been written.

Tool

What it does

Domain

profile_datasource

Per-column stats (type, distinct values, min/max) plus raw sample rows (sample.columns / sample.rows; sample_rows default 10, max 50) to design filters + charts against real columns.

read

execute_query

Run a saved query by id and return results (optional row limit).

read

run_db_modification

Run a saved DB write by name. Needs confirm: true.

data

change_password

Change the current user's password.

admin

get_user_access

Read a user's group membership and permissions in one call.

read

set_user_access

Replace a user's groups and/or permissions — each provided list is a full replace; needs confirm: true, supports dry_run.

admin

get_config / update_config

Read / set portal config by path.

read / admin

get_version

Portal version + about (capability check).

read

get_rules

Show active block-authoring rules.

read

naming

The scope · kind · subject naming grammar — action: "suggest" proposes names, action: "parse" decomposes them.

read

check_connection

Start here — confirm the connection in one authenticated round-trip: portal, version, who you're signed in as, binding state and write posture, in ~160 chars. Bad credentials return the reason and the fix, not a false success (always available).

read

get_capabilities

Report the current posture — enabled/disabled tool groups, write-safety, VC + audit status, and the active config (portal / VC repo, secrets redacted) under its config key (always available).

read

get_metrics

Per-tool call count, error rate, latency, uptime, breaker state (always available).

read

configure_project

Connect this folder to a portal. By default it opens a local loopback setup page (API key typed in the browser, never through the model), validates live, writes a 0600 config; falls back to elicitation then arguments (pass ui:false, or portal_url + api_key + user_id). Also collects write-safety toggles + access scope + optional GitHub VC. Pins the folder to the portal so writes can't cross portals; writes ./.zuar-portal/config.json + design.md + a managed CLAUDE.md block.

setup

reload_config

Re-read config from disk (project/bundle/env) without a restart; resets the portal session.

setup

synthesize_theme

Pure theme synthesis — preferences (± an SSRF-guarded website color fetch) → a token map plus the exact create_resource call (create_with); creates nothing itself. Orchestrated by the design_intake prompt.

design

migration_preflight

Read-only migration audit — every block classified by function, all code-bearing fields scanned (comment/string-aware), placement via layouts/partials/snippets, hardcoded-origin sweep, bound-query preflight, browser-probe checklist.

migration

repair_query_metadata

Refresh a saved query's stored column metadata from a live execution — SQL untouched, dry-run by default, round-trip verified.

migration

The current user's profile is plain resource CRUD now: get_resource / update_resource with resource: "user", id: "me". Guided migration scoping is the migration_kickoff prompt (see Prompts below).

Tool

What it does

vc_status

Show whether VC is configured and the repo state.

snapshot_portal

Commit the full current portal state to the git repo — a durable checkpoint.

vc_log

Show the commit history of content changes.

vc_diff

Unified diff between two committed versions — record-scoped (resource + id) or repo-wide; defaults to the previous commit touching the record vs HEAD. Inspect before restore_resource — a revert is never blind.

restore_resource

Restore a resource to a previous committed version.

See docs/07 · Version Control.

Resources (zportal://guide/*) — authoring guidance Claude reads before building, so blocks follow zPortal conventions even on a fresh machine: block-structure, currentblock, zportal-api, charting, conventions, design-system, visual-verification, migration-1.18, loading-overlay, migration-playbook, and block-performance.

Prompts — guided workflows now live here rather than in the tool surface (9): zuar_portal_start (the cheapest session opener — confirm the connection in one call, report one line, ask what's next), zuar_portal_quickstart (orient → route), create_zportal_block (discover → build → create), setup_zuar_project (connect this folder, routes to configure_project), migrate_block_to_118 (one legacy block → the 1.18 lifecycle), add_loading_overlay (the sanctioned spinner + fade-out), block_perf_pass (the large-dataset perf audit: measure → trim SELECT * → chart-lib prefetch → 60 s honest timeouts), design_intake (guided theming — walks brand/website/density/radius, drives synthesize_theme, then creates the theme via create_resource), and migration_kickoff (guided migration scoping — batches the scope decisions, writes .zuar-portal/migration-scope.json, then runs migration_preflight).


The Claude Code agent ecosystem

When this repo is your Claude Code working directory, the MCP tools come with a team of specialists in .claude/. You don't drive create_block/bind_block_query by hand — you describe what you want, and a gated pipeline builds, styles, hardens, and reviews it. Full guide: docs/13 · Agents & Workflows.

The block pipeline

Blocks are never shipped raw. A spec flows through quality gates, each a focused subagent:

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

The adversary (gate) red-teams the block and proves each finding with evidence; while it returns blocking findings the pipeline loops back to the debugger. The visual gate (the adversary with browser eyes) then opens the rendered block in Claude for Chrome — screenshot, console, network — and a blank render, console error, sample-not-live data, or overflow loops back to the debugger too; it's best-effort and skips with a note when the extension isn't connected or the block isn't on a page. The advisor asks "is this the right block?" All gates are read-only — they carry no write tools and physically cannot mutate the portal (browsing/screenshotting is read-only). Beyond the six pipeline agents, four specialists handle broader jobs: portal-data-expert, portal-theme-designer, portal-bulk-operator (snapshot-first), and portal-onboarding.

Seeing the portal (Claude for Chrome)

Every gate above reasons about a block from its code and query rows — but a block can validate, bind, and still render blank, throw a runtime console error, overflow its grid cell, or silently show its hardcoded sample fallback instead of live data. With the Claude for Chrome extension connected, the agents can see the portal: open the page, screenshot the block, and read the browser console/network — for visual debugging and a final visual sign-off.

  • Recorded at setup. configure_project asks whether you use Claude for Chrome and stores browser.claudeInChrome in ./.zuar-portal/config.json; get_capabilities reports it.

  • Used where it pays. The debugger looks before it guesses; the adversary owns the visual gate; the stylist and responsive-specialist screenshot their work (the latter steps widths with resize_window); the advisor checks it reads at a glance.

  • Sign-in caveat. The MCP authenticates with an API key, but the browser needs a logged-in session — to view private pages you must be signed into your portal in Chrome. The MCP can't log you in.

  • Graceful by design. No extension, or the block isn't on a page? Every agent falls back to code-only review and says so. The doctrine lives in the zportal://guide/visual-verification resource.

Slash commands

Command

What it runs

/portal-setup

First-time per-folder setup + alignment Q&A → config + project brief.

/portal-build <spec>

The full build→style→responsive→debug→adversary→advisor pipeline for one block.

/portal-theme <goal>

Design or apply a portal-wide theme.

/portal-bulk <change>

A guarded bulk change across many blocks/pages (snapshot → dry-run → atomic apply).

/portal-audit [filter]

Read-only audit of existing blocks — bugs, a11y, responsiveness, design fit.

/portal-improve

One bounded improvement pass: score → fix worst blocks → verify → sweep → provable delta. Safe to schedule nightly.

/portal-align

Run the alignment Q&A on its own.

Model & effort routing

Each agent runs on the model and reasoning effort that fit its job — sharp where judgment matters, cheap where the work is mechanical. Three composing layers:

1 · Agent defaults (model:/effort: frontmatter) — for a direct call (a fast surgical edit, or one agent dispatched from a command):

Tier

Agents

Model · effort

🧠 Judgment / data

data-expert, adversary, advisor

opus · high

🛠️ Authoring

builder, stylist, debugger, bulk-operator, theme-designer, onboarding

sonnet · medium

⚡ Mechanical

responsive-specialist

haiku · low

2 · Workflow tier toggle — portal-block-pipeline.js and portal-audit.js take args:{ …, tier } and set each stage's model/effort explicitly:

tier

For…

Builders

Judgment gates

fast

cheap iteration, throwaway drafts, triage

sonnet/haiku · low

sonnet · medium

standard (default)

a normal build / audit

sonnet · medium

opus · high

max

production / executive build, pre-release audit

opus · high

opus · xhigh

3 · Commands pin to sonnet · medium — they only orchestrate (pre-flight → dispatch → synthesize); quality lives in the agents/workflow they call. /portal-build and /portal-audit infer the tier from your phrasing.

The MCP server never selects a model — only the agents, commands, and workflows that drive it do. Re-tier via agent frontmatter or a workflow's ROUTING table; see .claude/README.md.


Guided onboarding & theming

By default configure_project serves a tiny loopback web form (http://127.0.0.1:<random-port>) from the MCP process, best-effort opens your browser, and returns the link immediately — you type the URL, API key, write-safety toggles, access scope, and version control in the browser, so the API key never passes through the model. On Save it validates live, writes the gitignored 0600 config, and applies the change live. It falls back to MCP elicitation (field-by-field prompts) and then to arguments when a browser can't be used — pass ui:false, or pass portal_url + api_key + user_id as arguments. Guided theming is the design_intake MCP prompt, which orchestrates the pure synthesize_theme tool. See The browser setup form.

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 refuses to clobber an existing config, validates with a real login, and writes a gitignored ./.zuar-portal/. It also asks whether you use Claude for Chrome (stored as browser.claudeInChrome) so the build pipeline can see your blocks render — visual debugging + a final visual gate (see Seeing the portal). The setup_zuar_project prompt and /portal-setup route to it; pass interactive: false for the direct, no-prompt path. (Replaces v2's setup_portal and init_project_config.)

  • The design_intake prompt fetches the brand's website through synthesize_theme's SSRF-guarded fetch to suggest a palette, then walks density/radius/header/sidebar and, on your confirmation, creates a theme resource via create_resource. synthesize_theme itself is pure — it returns the token map and the exact create_with call, and never writes.


Requirements

  • A Zuar Portal reachable over HTTPS, with an account that can manage blocks (admin recommended).

  • Node.js 18+ — for Claude Code and any other MCP client. (Claude Desktop's one-click .mcpb bundles its own Node, so you need nothing.)

Getting your portal credentials

You need three values, entered once during install.

#

Value

Where

1

Portal URL

The base URL, no trailing path — e.g. https://your-portal.zuarbase.net.

2

Portal API Key

Admin → Auth → API Keys → create/copy a key. It inherits its user's permissions — that user must be able to create/edit/delete blocks.

3

Portal User ID

Admin → Users → your user → copy the UUID from the page URL.

IMPORTANT

Keep the API Key and User ID private. In the Claude Desktop bundle they're declaredsensitive (masked, stored securely) and never leave the machine running the server.


Install — Claude Desktop (one-click)

  1. Download zuar-portal-mcp.mcpb from the latest release.

  2. Double-click it, or drag it onto the Claude Desktop window. An install dialog appears.

  3. Fill in Portal URL, Portal API Key, Portal User ID (and optionally the write-safety toggles).

  4. Confirm. The tools, resources, and prompts are now available to Claude.

To update later, install a newer .mcpb over the old one.

Install — Claude Code & other MCP clients

This server speaks MCP over stdio, so any MCP-capable client can use it. Clone it, build it once, and register the built entry point — you need Node ≥ 18 and git.

Register it once, for every project:

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

Keep the clone where it is. claude mcp add records the absolute path to dist/index.js, so moving or deleting the folder breaks the server with a spawn ENOENT. Pick a permanent home for it — not /tmp, not ~/Downloads.

To update: pull and rebuild in place. The path doesn't change, so there's nothing to re-register — but restart your client, since the tool list is only fetched at handshake.

cd ~/zuar-portal-mcp && git pull && npm install && npm run build

Then, in each portal project folder, connect it to that portal:

mkdir ~/work/acme-portal && cd ~/work/acme-portal
claude
> /portal-setup

/portal-setup asks for your three values, checks them with a real login, and writes a gitignored ./.zuar-portal/config.json. Every folder can point at a different portal — see Per-project configuration ↓.

.mcp.json in the project (or claude_desktop_config.json) — point args at your clone's built entry point, as an absolute path (~ is not expanded here):

{
  "mcpServers": {
    "zuar-portal": {
      "command": "node",
      "args": ["/Users/you/zuar-portal-mcp/dist/index.js"]
    }
  }
}
IMPORTANT

Leave env empty. Don't put PORTAL_URL / PORTAL_API_KEY / PORTAL_USER_ID in your client config. Credentials in the client's env map create one global portal that every project silently inherits — so a folder you believe is pointed at staging quietly publishes to production. Let /portal-setup write credentials per project instead. Each project then carries a binding fingerprint, and the server refuses a write aimed at a portal the folder isn't bound to. Env vars still work (useful for CI, or a single-portal install), but the project file is the path that can't surprise you.


Per-project configuration (multiple portals)

One MCP install can drive a different portal — and a different git state-repo — in every folder. At startup the server resolves credentials in layers, highest priority first:

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

Most settings resolve per field, so a project file can set just vc.dir and inherit the rest. Empty values are ignored, so a blank Desktop field never shadows a project value.

WARNING

Portal credentials are the exception — they resolve all-or-nothing from ONE layer (v4.0.0). A layer naming any of url / apiKey / userId must supply all three, or startup fails with an explicit error. Per-field layering here was a cross-portal hazard: a project with a url but no apiKey silently borrowed PORTAL_API_KEY from the environment — one portal's address paired with another's key.

The file uses one schema for both the portal and its VC repo:

{
  "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": "…" }
}

Set it up without hand-editing JSON: ask Claude to run configure_project (see Guided onboarding ↑). get_capabilities shows which portal/repo is in effect under its config key (secrets redacted). ./.zuar-portal/ is gitignored, so credentials are never committed.


Getting started

New portal? Start here. From the folder you want to work in:

cd ~/work/acme-portal
claude
> /portal-setup

One command. It connects the folder to the portal (writing gitignored credentials + a binding fingerprint), profiles your datasources, interviews you about the business, and writes a project brief the other agents read. Everything below assumes it's done.

Then just talk to Claude:

  1. Confirm the connection — "List the datasources on my portal." → list_resource (datasource).

  2. Look at real data — "Show me a few sample rows from the Sales datasource." → profile_datasource (per-column stats + raw sample rows, so Claude sees the real column names first).

  3. Create a block — "Create a stat-card block 'Total Orders' showing the order count from Sales." → reads zportal://guide/*, builds the two-field block, create_block, reports the UUID.

  4. Iterate — "Make the number bigger and use the portal's primary color." / "Turn it into a bar chart of orders by state." → update_block.

TIP

InClaude Code, run /portal-build "a stat card of total orders from Sales" to push the spec through the whole gated pipeline, or invoke the create_zportal_block prompt for a structured discover → build → create flow.


Write safety & tool gating

Every write is tagged with a risk domain, gated independently:

Domain

Covers

Default

Enable with

content

blocks, layouts, partials, themes, queries, snippets, translations, dashboards, tags

on

(on unless read-only)

data

datasources, db_modifications, run_db_modification

off

PORTAL_ALLOW_DATA_WRITES=1

admin

users, groups, permissions, access policies, API keys, credentials, system, config, passwords

off

PORTAL_ALLOW_ADMIN_WRITES=1

  • PORTAL_READONLY=1 disables every write — reads and discovery still work.

  • A blocked write returns a clear message naming the flag to set; nothing reaches the portal.

  • run_db_modification additionally requires confirm: true on every call.

  • Deletes and user/password mutations are marked destructive to MCP clients.

  • Uniform dry_run: true (v3.0.0) on every write tool — all gates run (domain, structure, per-kind rules, references, impact) but nothing is written; the response reports applied: false and what would have changed. A dry run never bypasses a gate.

Least-privilege tool scoping (v2.5.0) — disable whole capability groups with PORTAL_DISABLE_TOOLS=users,config, or stand up a build-only allowlist with PORTAL_ENABLE_TOOLS=blocks,resources,data (deny wins).

Upgrading from 2.x — PORTAL_COMPAT_TOOLS=1 (off by default) registers the removed v2 tool names as deprecated aliases in a compat group; each alias forwards to the same gated v3 handler, so aliases confer no extra capability.

Integrity gates (v2.5–2.6, server-side, cannot be bypassed) — every content write is checked for portal-compatible structure (a page missing grid.layouts is repaired or rejected) and dangling references; deletes run pre-delete impact analysis and refuse to orphan dependents unless force=true; user deletes refuse to remove the last admin; unscoped mass SQL (a destructive verb without a real WHERE — 1=1 doesn't count — plus MERGE/TRUNCATE/DROP/ALTER…DROP/GRANT) needs allow_unfiltered=true, and the check fails closed when the SQL can't be inspected. Run the read-only validate_portal anytime to sweep for problems. Full guide: docs/16 · Safety & Integrity.

Unattended-loop safety (unreleased) — the guarantees that make parallel/overnight agent loops safe to leave alone:

  • No duplicate creates: a create that fails ambiguously (network died after the request may have landed) is verified by name and adopted if it already exists — never blindly resent. run_db_modification is never auto-retried at all.

  • No lost updates: pass expected_updated_at (from your read) to update_resource / update_block / place_blocks and a mid-flight change by anyone else refuses with a conflict instead of silently overwriting.

  • No stranded cruft: name loop temporaries TMP · <purpose> (or tag them scratch), then sweep with cleanup_scratch — dry-run by default, deletes only unreferenced non-recent candidates through the gated path, content stays VC-restorable.

  • Provable improvement: score_portal scores every block/page 0–100 on the mechanically checkable and diffs against a saved baseline — a loop's regression is a per-record delta, not an anecdote.

  • Admin can't self-destruct: stripping your own admin access needs allow_self_lockout=true; update_config and change_password require confirm (config edits return previous_at_path for one-call revert).

In the Claude Desktop bundle these are install-dialog toggles; for other clients set them as env vars. Deeper dive: docs/14 · Tool Gating & Guidance.


Resilience, observability & hardening

Production-grade behaviour for a local, single-user server — safe defaults, no configuration required.

Resilience (the portal HTTP client every tool calls through):

Behaviour

Default

Tune with

Per-attempt timeout

30 s

PORTAL_TIMEOUT_MS

Retries on transient failure (network, 408/425/429/5xx), exp. backoff + jitter, honouring Retry-After

2

PORTAL_MAX_RETRIES, PORTAL_BACKOFF_BASE_MS, PORTAL_BACKOFF_MAX_MS

Circuit breaker — fail fast while the upstream is down

opens after 5 failures, 15 s cooldown

PORTAL_BREAKER_THRESHOLD, PORTAL_BREAKER_COOLDOWN_MS

Max request body size

5 MB

PORTAL_MAX_BODY_BYTES

Max tool input size (rejected at the MCP boundary)

2 MB

PORTAL_MAX_INPUT_BYTES

execute_query returned-row cap

1,000 rows (limit:0 = all)

per-call limit

list_resource page byte cap (auto-projects to {id,name} + note)

60k chars

PORTAL_LIST_BYTE_CAP (0 disables)

Result serialization

compact JSON

PORTAL_PRETTY_JSON=1 for pretty

Binding re-verification cadence

10 min + on config reload

PORTAL_BINDING_REVERIFY_MS

Read cache (GETs; any write clears it; write-critical reads bypass it)

5 s TTL

PORTAL_READ_CACHE_MS (0 disables)

Retry safety: GET retries on any transient signal; writes retry only on explicit 429/503 back-pressure or a network failure that provably never connected — never on an ambiguous 502/504, and a create whose network error may have delivered the request is verified by name and adopted rather than resent (no silent duplicates).

Observability — every call gets a request id, latency, and an error tally. get_metrics (always-on) reports per-tool counts, error rate, latency, uptime, and the breaker state — metadata only, no payloads or secrets. Set PORTAL_LOG_FORMAT=json for structured stderr logs; PORTAL_AUDIT_LOG appends metadata-only JSONL for every content/data/admin write.

Output secret redaction — secret-bearing fields (password, secret, token, api_key, …) are masked as [redacted] on resource reads, so they never flow into the model's context, and secrets are also caught by shape inside any value or name — connection-string passwords (postgresql://user:[redacted]@host), JWTs, PEM private keys, AWS key ids — including in execute_query / profile_datasource results. Generic hex and key=value shapes are deliberately not masked (uuids, git shas and SQL params are legitimate content that round-trips back into writes). Identifier *_id fields are never masked; create/update responses are intact (so a freshly generated secret can be seen once). Disable with PORTAL_REDACT_SECRETS=0. Portal-authored content additionally returns inside an untrusted-data envelope, so a poisoned record name reads as data, not instructions.


Troubleshooting

Symptom

Likely cause / fix

"failed to connect" / spawn ENOENT

The client couldn't spawn the command. Either (a) the clone moved or was deleted — claude mcp add stored an absolute path to dist/index.js; re-check it with claude mcp list; (b) you registered it before running npm run build, so dist/index.js doesn't exist — build, then restart the client; or (c) node isn't on the PATH your client sees (common with nvm + Claude Desktop, which doesn't load your shell profile — use the .mcpb there, it bundles its own runtime).

An old guide says to run npx -y zuar-portal-mcp-server

That package is not on npm — the command can't work and fails as ENOENT. Install from a clone: Install — Claude Code ↓.

Reads work, but every write is refused as unbound

This folder isn't bound to a portal. Run /portal-setup (or configure_project) in it. Binding is what stops one project's block being published to another's portal, so it's deliberate — see Per-project configuration.

"Missing portal credentials: …"

One of PORTAL_URL / PORTAL_API_KEY / PORTAL_USER_ID is blank. Re-enter it.

"…must supply all three of url/apiKey/userId"

A config layer names some credentials but not all. That's refused on purpose — a url without an apiKey used to silently borrow the key from your environment, pairing one portal's address with another's key. Supply all three in one place.

"Portal login failed: HTTP 401/403"

Wrong API key or user ID, or the user lacks permission. Regenerate the key; confirm the user can manage blocks.

list_resource (query) says the endpoint isn't available

Your portal predates the saved-queries API (1.18+). Use resource: "datasource" — expected, not an error.

Tools don't appear in Claude

Restart the client — the tool list is fetched once at handshake, so a newly added server (or a new version) won't show up in a running session. For the .mcpb, reinstall it.

You upgraded but the new tools/rules aren't there

Same cause: the client is still running the old process. Restart it.

A v2 tool name is missing (list_blocks, setup_portal, …)

v3.0.0 removed/renamed it — see CHANGELOG.md for the replacement, or set PORTAL_COMPAT_TOOLS=1 for deprecated forwarding aliases.

Want to see what it's doing

Set PORTAL_DEBUG=1 (or PORTAL_LOG_FORMAT=json). Logs go to stderr only.

"circuit breaker is open"

The upstream failed repeatedly; it auto-recovers after a short cooldown. get_metrics shows breaker state.

A stored secret returns [redacted]

Read redaction is on. Set PORTAL_REDACT_SECRETS=0 for that session.

More: docs/12 · Troubleshooting.


Security

  • Credentials are never logged. Debug output (gated by PORTAL_DEBUG=1) goes to stderr only, so it never corrupts the MCP stdio stream.

  • The API Key and User ID are declared sensitive in the bundle manifest.

  • The server talks only to the Portal URL you configure; the base URL is validated as a well-formed http(s) origin at startup. synthesize_theme's website fetch (driven by the design_intake prompt) is SSRF-guarded.

  • create_block / update_block are restricted to type: "html" and reject other types before any portal call.

  • Secret-bearing fields are redacted from reads; tool inputs and request bodies are size-capped.

See SECURITY.md for the full posture: the per-tool-group data-touch matrix, credential handling, network egress, and data retention.

License

MIT.

Available Tools

40 tools
bind_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 passwordA
Destructive

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 connectionA
Read-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)A
DestructiveIdempotent

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 recordA
DestructiveIdempotent

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 resourceA
Read-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 queryA
Read-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 nameA
Read-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 configA
Read-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 configA
Read-only

Fetch the portal's configuration document.

Inputs: no named parameters.

get_metricsTool-call metricsA
Read-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?A
Read-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 recordA
Read-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 rulesA
Read-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)A
Read-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 / capabilitiesA
Read-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 collectionA
Read-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)A
Read-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)A
Read-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)A
Idempotent

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)A
Read-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 diskA
Idempotent

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 metadataA
Idempotent

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 modificationA
Destructive

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)A
Idempotent

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)A
DestructiveIdempotent

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 preferencesA
Read-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 blockA
Idempotent

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 configA
Idempotent

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 recordA
Idempotent

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)A
Read-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)A
Read-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 versionsA
Read-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 historyA
Read-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 statusA
Read-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

    A4.1/5.0

    Scored across 40 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      Not graded
      maintenance
      Enables 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.
      11
      123 npm
      1
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      22
      15 npm
      MIT
    • A
      license
      A
      quality
      Not graded
      maintenance
      AI-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.
      5
      24 npm
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language management of apps, services, resources, attributes, and data via the Dimetrics API with full CRUD operations and advanced filtering.
      -