/maple-dashboard-widgets

name: maple-dashboard-widgets
description: "Build, repair, or review Maple dashboard widgets via the MCP. Triggers on phrases like 'create_dashboard', 'add_dashboard_widget', 'update_dashboard_widget', 'dashboard widget JSON', 'panel_type', 'QueryDraft', or any session that submits widget JSON to the maple MCP. Covers the panel-type table, the kind-discriminated data source, the percent vs percent_100 unit rule, valid aggregations and group-by tokens per source, the custom whereClause grammar, the scalar reduceToValue transform, and the verification step (MCP success != chart correctness)."

Maple dashboard widgets via MCP

Everything below is generated from the live widget schema by `bun run --cwd apps/ai mcp:docs`. **Do not edit this file by hand.** Edit `apps/ai/src/mcp/lib/dashboard-schema-doc.ts` and regenerate. The same module backs the `describe_dashboard_schema` MCP tool, so an agent at runtime and a reader here see one truth.

When to use this skill

When constructing widget JSON for `mcp__maple__create_dashboard`, `mcp__maple__add_dashboard_widget`, `mcp__maple__update_dashboard_widget` or `mcp__maple__replace_dashboard_widgets`.

For a brand-new dashboard, prefer the simplified `widgets` array on `create_dashboard` (`{ title, source, metric, group_by?, service_name?, unit? }`). It fills in the traps below. Reach for raw JSON when the simplified spec can't express what you need: multi-query charts, formulas, hidden series, non-default transforms.

The three silent failures

1. **A data source is a `kind`-discriminated union.** `{ "endpoint": …, "params": … }` is the retired v2 shape and will not decode. 2. **`percent` means a 0–1 fraction; `percent_100` means 0–100.** Inverted from Grafana. 3. **`groupBy` is ignored unless `addOns.groupBy` is `true`.** No error, just an ungrouped total.

Verification

MCP success is not chart correctness. The mutation tools reject queries the engine can't honor and widgets that cannot render, and return an automatic `inspect_chart_data` summary for everything else. Read the verdict: `suspicious` or `broken` means fix and resubmit.

Panel types

`panel_type` is the whole answer to “what kind of widget is this”. Pass it and the persisted `visualization`, the `display.chartId` and the raw-SQL display type are all derived for you. The legacy `visualization` parameter is still accepted, but it collapses line/bar/area into `chart` and then needs a `display.chartId` to tell them apart. The two columns below are what `panel_type` resolves to, and are what you write directly when authoring an assembled widget rather than calling `add_dashboard_widget`. A panel whose `chartId` is `-` takes none: the `visualization` alone identifies it.

| panel_type | Label | `visualization` | `display.chartId` | Raw-SQL type | Default w×h | Requirements | |---|---|---|---|---|---|---| | `line` | Line | `chart` | `query-builder-line` | `line` | 4×6 | - | | `bar` | Bar | `chart` | `query-builder-bar` | `bar` | 4×6 | - | | `hbar` | Horizontal Bar | `hbar` | `query-builder-hbar` | `hbar` | 4×6 | needs a group-by | | `area` | Area | `chart` | `query-builder-area` | `area` | 4×6 | - | | `pie` | Pie | `pie` | `query-builder-pie` | `pie` | 4×6 | needs a group-by | | `stat` | Stat | `stat` | - | `stat` | 3×4 | needs `transform.reduceToValue` | | `gauge` | Gauge | `gauge` | - | `stat` | 4×6 | needs `transform.reduceToValue` | | `table` | Table | `table` | - | `table` | 6×5 | - | | `list` | List | `list` | - | - | 6×5 | **no raw-SQL support** | | `histogram` | Histogram | `histogram` | `query-builder-histogram` | `histogram` | 4×6 | - | | `heatmap` | Heatmap | `heatmap` | `query-builder-heatmap` | `heatmap` | 4×6 | needs a group-by | | `funnel` | Funnel | `funnel` | `query-builder-funnel` | `funnel` | 4×6 | needs a group-by | | `paths` | Paths | `paths` | `query-builder-paths` | - | 6×5 | **no raw-SQL support** | | `markdown` | Note | `markdown` | - | - | 4×5 | **no raw-SQL support** |

Choosing one

• **line / area / bar**: a value over time. `area` and `bar` accept `display.stacked`; `line` does not.
• **hbar**: a ranked “top N by volume”. Each row is labelled with its share of the **total**.
• **funnel**: sequential stages with a drop-off. Labels each bar as a share of the *largest*,

so an unranked breakdown of four equal things reads “100%” four times. Use `hbar` for that. `display.funnel.variant: "dropoff"` draws the same funnel as one column per step with the loss between steps, the median time between them, and where the leavers went.

• **paths**: what people do in the steps after (or before) one event or page, as a flow.

Defined by `display.paths` alone; no query set.

• **pie**: composition, few slices. Collapses a long tail into “Other”.
• **stat / gauge**: one number. A gauge adds an arc; set `display.gauge.min`/`max` to match the unit.
• **table**: rows and columns; set `display.columns` for headers and per-column units.
• **list**: recent traces/logs. Configured by `display.listDataSource`, never by SQL.
• **heatmap / histogram**: a distribution. A histogram over traces can bucket raw values client-side.
• **markdown**: a static note. Takes no query at all.

Data sources

A widget's `dataSource` is a discriminated union over `kind`: `query`, `raw_sql`, `route`, `static`. Every arm requires its `kind`.

> **If you have seen `{ "endpoint": …, "params": … }` anywhere, that is the retired v2 shape > and it will not decode.** A `query` source spreads `queries`/`formulas` at the TOP LEVEL, > not under `params`, and requires `resultShape`.

`kind: "query"`: the query builder

`resultShape` is required and is one of `timeseries` (a value over time), `breakdown` (one row per group) or `list` (raw rows). Optional: `formulas`, `comparison`, `limit`, `defaultLimit`, `columns`, `transform`.

{
  "kind": "query",
  "resultShape": "timeseries",
  "queries": [
    {
      "id": "q1",
      "name": "A",
      "enabled": true,
      "