zuar-portal-mcp: Skill for Claude Code

Zuar Portal db_modifications Service

The db_modifications service is how browser-based code inside a Zuar Portal writes data back to a database — Portal's local Postgres or any external database reachable via Portal credentials. Every write is pre-defined by a Portal admin as a named SQL template, so client code can only execute approved statements. SQL injection is impossible because the client never sends SQL.

Use this skill whenever the user needs to save, insert, update, delete, or upsert data from a portal page, whether they're building the block itself or setting up the underlying modification.

---

Mental Model — How It Works

Two sides to every db_modifications task:

1. Admin side (one-time setup). A Portal admin creates a row in the db_modifications table via the Portal's Swagger UI (/docs/). The row defines a name, optional credentials_id, a sql template with :named_params, and optional default_params. This is the only way to register executable SQL.
2. Client side (runtime). Browser code in an HTML block POSTs to /api/db_modifications/run with the modification's name and the parameter values. Authentication is automatic via the user's JWT cookie — do not send an Authorization header.

If the user asks "how do I insert from a block?" they need both sides. Always confirm the modification exists (or needs to be created) before writing client code.

---

The db_modifications Table

create table public.db_modifications (
  id              uuid         not null primary key,
  name            varchar(256) not null unique,
  credentials_id  varchar(256),
  sql             text,
  default_params  text,
  updated_at      timestamp with time zone not null,
  created_at      timestamp with time zone not null
);

Column	Purpose
id	UUID. Either this or name identifies a modification in API calls.
name	Unique human-readable identifier. Preferred in client code — more readable than a UUID.
credentials_id	ID or name of a Portal credential for the target database. null → Portal's local Postgres.
sql	One or more SQL statements, each ending in ;. Named parameters use :name syntax. Must be in the target DB's dialect.
default_params	JSON object of default values. Used when the client POST omits a parameter.