zuar-portal-mcp: Skill for Claude Code

Portal block performance playbook

Distilled from a production incident on a customer portal (2026-07-08): a block took 17–19 s to load on a fast connection and never loaded on slow ones. Root causes, in order of impact: a SELECT * query shipping 46.8 MB of uncompressed JSON, a chart library loaded serially after the data arrived, and a 15 s load timeout that turned "slow" into "permanently blank". Every pattern below was verified in production.

The performance model

A block's wall-clock load = DB query → server JSON serialization → network transfer → JS parse → chart-lib load → render.

For large datasets the DB is usually the SMALLEST slice (3 s of an 18 s load). Payload size drives serialization + transfer + parse, so bytes are the enemy, not the index. Diagnose with real numbers before touching anything:

# Login (host/creds in .zuar-portal/config.json)
curl -s -c cookies.txt "$HOST/auth/login?api_key=$KEY&user_id=$UID"

# Replay the block's exact execute call with timing
curl -s -b cookies.txt -H "X-Api-Key: $KEY" -H "Content-Type: application/json" --compressed \
  -d '{"query_id":"<QID>","dsl":{"where":[]},"params":[],"datasource_filters":[{"datasource_id":"<DSID>","where":[]}],"response_control":{"include_count":true,"include_params_details":true,"include_columns":false}}' \
  -o resp.json -w "ttfb=%{time_starttransfer}s total=%{time_total}s bytes=%{size_download}\n" \
  "$HOST/api/queries/<QID>/execute"
jq '{count, rows: (.data|length), db_time: .timings.main_query}' resp.json

timings.main_query = DB time. ttfb − db_time = server serialization. total − ttfb = transfer. Multi-second serialization or multi-MB payloads → trim the query.

1. Query audit: trim SELECT * to referenced columns

A granular table × 39 columns × 120k rows ≈ 47 MB. Blocks typically read fewer than half the columns. Trimming is free — no block-code changes — IF done safely:

1. Find every column the block reads. Blocks access columns by NAME through accessor helpers. Grep the block HTML for ALL of these patterns per column:
   • quoted refs: 'col_name' / "col_name" (accessors like str(r,'x'), num(r,'x'), getVal(row,'x'), getColVal(...))
   • dot lookups on a column map: colMap.col_name
   • plain word-boundary greps LIE (title matches HTML attributes; period matches variable names) — count quoted+dot matches only.
2. Names referenced in JS but absent from the query are usually guarded fallbacks (if (colMap.x !== undefined)) — dropping nothing they need. Verify the guard exists.
3. Check the query isn't shared: get_references resource="query" id=<QID> — the dependents list shows every block bound to it. Trim only if this block is the sole binder (or audit all binders).
4. Update sql_form.columns from ["*"] to the explicit list via update_resource resource="query". Keep where/order_by verbatim.
5. Datasource filters are unaffected — datasource_filters apply inside the datasource CTE which still has all columns; the query projection only shapes the SELECT.
6. Re-measure with the curl above. Expect roughly (kept/total columns) × old size.