R1 Dash Master

An MCP server that builds importable Data Studio dashboards for RUCKUS One and RUCKUS Analytics from a simple declarative spec. Output is a .zip you import via Data Studio → Settings → Import Dashboard. Pure offline generation — no API credentials needed.

📺 Setup & usage in Claude Desktop: https://youtu.be/-gU7yu6liOw

Data Studio is Apache Superset on an Apache Druid backend. This tool encodes the dataset catalogs and the chart/query grammar so you (or an agent) can build valid dashboards without learning Superset internals or guessing field names.

Targets: RUCKUS One vs RUCKUS Analytics

Every spec says which product it is for with "target":

target	product	catalog	bundle deployment
r1	RUCKUS One	catalog.json (18 datasets)	ALTO
analytics	RUCKUS Analytics	catalog_analytics.json (19 datasets)	MLISA

There is no default, on purpose. Both products run the same Data Studio and the same chart grammar, and metric/dimension names mostly match — but every dataset has a different UUID and usually a different numeric id in each (R1 id 10 is wifiCalling; Analytics id 10 is binnedSessions). A bundle built for the wrong product is rejected on import. For a single-product setup, set R1DM_TARGET=r1 (or analytics) in the MCP server's environment instead of repeating it.

Name differences that do exist: Analytics adds controller dimensions (ctrlName, ctrlMac, ctrlModel, …); R1 has tag/tagList; binnedApTraffic latency metrics say AP-to-SZ in Analytics vs AP-to-RUCKUS One in R1. apAlarms and controllerInventory exist only in Analytics. validate_spec checks names against the chosen target.

Tools

• list_datasets(target) — every dataset for that product (internal name, cube name, id, counts).
• describe_dataset(name, target) — exact metric + dimension names (Analytics also shows each metric's SQL).
• validate_spec(spec) — check a spec against its target's catalog before building.
• build_dashboard(spec, filename?) — emit an importable .zip (written to out/, named <title>_<target>_IMPORT.zip).

Spec format

{
  "target": "r1",                        // REQUIRED: "r1" (RUCKUS One) or "analytics" (RUCKUS Analytics)
  "title": "Network Intelligence",      // generic — NEVER tenant-specific (bundles are portable across ECs)
  // tenant_id: OPTIONAL — omit it. Import auto-rescopes to the target EC (tenant). Only include to hard-pin a tenant.
  "time_range": "Last week",            // default for all charts (Last day/week/month/quarter, previous calendar week/month, or explicit range)
  "grain": "day",                       // OPTIONAL trend time grain: 30 second/minute/3·5·10·15·30 minute/hour/day/week/month/quarter (default hour); charts can override
  "rows": [                              // each row = list of charts; widths in a row sum to <= 12
    [ {chart}, {chart} ]
  ]
}

Chart:

{
  "type": "bignum" | "bignum_trend" | "line" | "bar" | "area" | "scatter" | "pie" | "table"
         | "gauge" | "heatmap" | "funnel" | "pivot" | "mixed" | "tree" | "bubble",
  "stacked": true,                       // bar/area only: stack the series
  "x": "apMac",                          // line/bar/area/scatter: optional DIMENSION x-axis (default __time)
  // pivot:  "rows": ["zoneName"], "columns": ["radio"], "metrics": [...]
  // mixed:  "metrics": [...] (bars) + "metrics_b": [...] (line) + optional "groupby"/"groupby_b","format_b"
  // tree:   "id": "apName", "parent": "apModel", "name": "apName", "metric": "..."
  // bubble: "entity": "apName", "x": <metric>, "y": <metric>, "size": <metric>  (x/y/size are METRICS here)
  // funnel/gauge/heatmap: "metric" (singular) + "groupby" ([dim]; heatmap uses first dim as Y)
  "dataset": "binnedSessions",          // internal name from list_datasets
  "title": "...", "width": 1-12,
  "metric":  "User Traffic (Total)"     // bignum/pie; string = saved metric
           | {"sql": "1.0*SUM(a)/SUM(b)", "label": "Rate"},  // or custom-SQL (ratios/%)
  "metrics": [ ... ],                    // line/table (list of the same forms)
  "groupby": ["radio"],
  "filter":  ["radio","5"]  | [["radio","5"],["zoneName","X"]],
  "time_range": "Last day",              // optional per-chart override
  "format": ".1%",                       // d3 number format (rates -> ".1%")
  "percent_of_total": ["Traffic (Total)"], // table: share-of-column-total column
  "row_limit": 25
}

Layout & cross-filtering (design convention)

Data Studio dashboards are cross-filterable: clicking a value in any chart (e.g. a venue in a venue table) filters the entire dashboard to that value; clearing it up top removes the filter. So put venue and AP tables/charts near the TOP — they double as interactive filter controls. Recommended order: KPI row → venue (and AP) table → detail charts below. The builder preserves row order from the spec, so order your rows that way.

Grammar notes baked in (gotchas)

• Field names are exact & dataset-specific. radio not Radio; Unique Client MAC Count not "Unique Client Count"; User Traffic(Total) (no space) in sessionsSummary vs User Traffic (Total) (space) in binnedSessions. validate_spec catches saved-metric/dim typos.
• Custom-SQL metrics reference RAW columns (e.g. successCount), not display metric names, and integer division floors — always 1.0 * (or 100.0 *). See raw_columns in the catalog.
• Rate vs share: a true rate = SQL metric + .1% format. percent_of_total (table percent_metrics) means "% of the column total" (contribution), not "format as %".
• Band values are tri-band: the radio/band dimensions take "2.4", "5", and "6(5)" — the 6 GHz band's literal value is the string "6(5)", NOT "6" (confirmed from the per-band metric SQL). Per-band metrics label it 6(5) GHz. Don't hardcode just 2.4/5.
• Dashboards are transmutable across ECs — keep titles generic, swap tenant_id.

Why a panel imports empty (troubleshooting)

Bundles are tenant-less: there is no datasets/ folder. Charts bind to a dataset by UUID and reference metrics by name string, and both must already exist in the target EC. (Multi-dataset dashboards are fully supported — see examples/network_intelligence.json; if a board looks limited to one dataset, that's not a tool limitation.) A panel that imports but renders empty almost always traces to one of:

1. Saved-metric name not present on the target cube. A metric like "Client Throughput" only resolves if that EC's cube defines it. Fix: use a self-contained custom-SQL metric ({"sql": "...", "label": "..."}) instead of a saved-metric name — it carries its own definition and doesn't depend on the target.
2. Dataset not provisioned in that EC. The UUID resolves to nothing. Confirm the dataset exists in the target Data Studio before importing.
3. Overwrite-orphaning on re-import. Re-importing over an existing published dashboard can orphan charts whose position or title changed (chart identity is keyed on title + row/col). Fix: import to a fresh dashboard title rather than overwriting.

Re-importing while you iterate on the same dashboard

This is the most common self-inflicted cause of the empty/duplicate panels above, and it bites hardest mid-session when you're iterating on one idea — adding, removing, renaming, or reordering charts on the same board and re-importing after each change. Chart identity is derived from (dashboard title, row, column, chart title), and the dashboard from its title alone, so:

• Re-import is idempotent only when the spec is unchanged (same titles, same layout) — it cleanly overwrites the same objects in place.
• The moment a chart is added, removed, renamed, or moved, its identity changes: Superset creates the new version and leaves the old one behind as an orphan (on no dashboard). Enough churn accumulates a pile of stale, sometimes-empty tiles that look like a data problem.

Pick one discipline and stick to it for the session:

• Overwrite in place — keep the dashboard title, chart titles, and layout stable across imports so every re-import updates the same board.
• Fresh each pass — bump the dashboard title each iteration and delete the previous board, so every import is a clean set with nothing orphaned.

Avoid the middle ground: repeatedly reshaping a same-named board and re-importing. If you've already accumulated orphans, clean them in the UI — delete charts that belong to no dashboard, remove duplicate boards, then re-import your current spec once.

CLI (without MCP)

python3 builder.py examples/network_intelligence.json out/network_intelligence_IMPORT.zip
# build the same spec for the other product:
python3 builder.py examples/network_intelligence.json out/ni_analytics.zip --target analytics

Tests

python3 -m unittest discover -s tests

tests/test_gallery.py fails when a committed gallery zip no longer matches its spec. Run ./build_gallery.sh and commit the result. Builds are byte-reproducible, so a rebuild only shows a diff when a bundle's content actually changed.

Run as MCP

Needs Python 3.10+ and the MCP Python SDK 2.x (mcp>=2.0,<3). SDK 2.0 renamed FastMCP to MCPServer, so this server does not run on 1.x.

Install it into its own virtualenv. Other MCP servers on the same Python may still be on SDK 1.x, and installing 2.x globally breaks them at startup:

python3 -m venv ~/.venvs/r1-dash-master
~/.venvs/r1-dash-master/bin/pip install -r requirements.txt
~/.venvs/r1-dash-master/bin/python server.py

Easiest: just ask Claude to set it up — point it at this repo and it'll wire the MCP server into your client for you (that's what the video shows).

Manual: register it yourself. For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "r1-dash-master": {
      "command": "/home/you/.venvs/r1-dash-master/bin/python",
      "args": ["/path/to/r1_dash_master/server.py"],
      "env": { "R1DM_TARGET": "r1" }
    }
  }
}

R1DM_TARGET is optional. Set it (r1 or analytics) if you only ever build for one product. Leave it out and every spec must carry its own "target".

Examples vs. Gallery

• examples/*.json — source specs, for driving the MCP/builder and learning the spec format.
• gallery/*.zip — prebuilt, ready-to-import RUCKUS One dashboards; gallery/analytics/*.zip — the same boards for RUCKUS Analytics. Since bundles are tenant-less, they auto-rescope to whatever EC you import them into. Grab one → Data Studio → Settings → Import Dashboard. Current set: executive_overview, capacity_rf, connection_health, network_intelligence, switch_health, chart_gallery, delivered_throughput.
• Regenerate the gallery from specs anytime: ./build_gallery.sh (keeps zips in sync).

Status

Catalogs: RUCKUS One 18 datasets (AP Alarms & Controller Inventory are SmartZone-only, N/A in R1); RUCKUS Analytics 19/19, every UUID verified by import on a live tenant (2026-09-22). Viz (15): bignum, bignum_trend, line, bar, area, scatter, pie, table, gauge, heatmap, funnel, pivot, mixed, tree, bubble. Query grammar: saved + custom-SQL metrics, percent-of-total, dimension + time filters, d3 formats. Cross-filtering is built in (click a chart value to filter the dashboard). Not yet: explicit dashboard-level native filter bar; remaining viz (treemap, sunburst, box plot, radar, waterfall, graph, histogram, calendar heatmap, sankey, smooth/stepped line); auto-import (needs an analytics-backend API — import the zip via UI).