Analytics (BI) module — JetSetGo MCP reference

The bi module is the JetSetGo MCP server's facade over the analytics stack. It lets an assistant answer operator business questions with real, tenant-scoped numbers by querying the warehouse through its semantic layer — never raw SQL — and lets the assistant save charts and dashboards into a public workspace on the operator's behalf as human-approved writes.

What the operator uses it for

An operator asks questions in plain language — revenue totals over a period, capacity versus bookings per service, utilisation percentages, journey or sector counts — and the assistant translates the question into a governed query against pre-defined metrics and dimensions. The assistant first discovers what data exists (bi_list_explores, bi_find_fields), optionally searches the allowed values of a name field to build filters, then runs the query and reports the rows.

The operator can also ask what charts or dashboards already exist (bi_find_content), have new ones saved into their public assistant-authored workspace (bi_save_chart, bi_save_dashboard), and set which period a dashboard opens on by default (bi_get_date_filter_options, bi_get_dashboard_date_defaults, bi_set_dashboard_date_defaults).

Where it sits

This module is a facade, not a data store. Read calls pass through the analytics stack's bundled tool interface and are parsed into canonical row/field shapes; content saves go through its content-as-code write API. The MCP server is the tenant-pinning enforcement point: every call runs against the pinned tenant's own project, preventing cross-tenant leakage.

Upstream, the warehouse is populated from JetSetGo operational data on a scheduled sync. Downstream, the module produces no booking data — its only writes are charts, dashboards, and dashboard date defaults inside the BI product itself.

The module is provision-gated: on a deployment without its BI configuration present, it ships disabled and its tools are simply not registered; it never crashes the shared server.

Key concepts

Explore — a semantic-layer dataset (e.g. accounting entries, service availability). Queries are expressed against an explore, not tables.
Metric / dimension — metrics are aggregatable measures (totals, averages, percentage ratios); dimensions are grouping and filter fields (names, statuses, dates).
FieldId — the exact identifier of a metric or dimension. Metric ids carry a doubled table prefix; dimension ids a single prefix. Ids are discovered at runtime and used verbatim.
Date scoping — an active_date range filter scopes a metric to a period; without one, results are all-time and stamped as such.
as_of / freshness note — every result states when it was produced and that the warehouse syncs on a schedule rather than live.
Assistant workspace — a public space where saved charts/dashboards live; same-slug saves replace existing content.
Guarded write — saves and date-default changes follow a preview → operator confirmation handshake before anything is applied.

Tools

Tool	Class	Purpose
`bi_list_explores`	Read	List the explores available to query.
`bi_find_fields`	Read	Find metrics/dimensions in an explore by label; returns exact fieldIds and types.
`bi_search_field_values`	Read	Search unique values of an allowlisted name-type dimension for building filters.
`bi_run_query`	Read	Run a governed metric/dimension query and return canonical rows with metadata.
`bi_find_content`	Read	Find existing saved charts/dashboards by name/description across spaces.
`bi_get_date_filter_options`	Read	List valid quick-dates, saved quick-dates, and date-basis options for defaults.
`bi_get_dashboard_date_defaults`	Read	Read a dashboard's current default date-filter configuration.
`bi_set_dashboard_date_defaults`	Guarded write	Set or reset a dashboard's default opening period/comparison/date basis.
`bi_save_chart`	Guarded write	Save a chart from a simplified chart spec plus metric query into the workspace.
`bi_save_dashboard`	Guarded write	Save or edit a dashboard composed of chart tiles referencing saved charts.

Rules worth knowing

Semantic layer only. Queries use discovered fieldIds verbatim; raw SQL is not available. A curated set of starter explores covers accounting/revenue lines, per-service availability and utilisation, and journey counts.
Comparison-period metrics are refused. Only base (current-period) metrics may be queried through this path.
No date filter means all-time. Unscoped results are explicitly stamped all-time and flagged so the assistant relays the scope.
Percentage metrics are ratios, meaningful only at the grain they are computed (e.g. per track); they must not be summed.
Row caps apply — queries default to 100 rows with a hard cap of 500 per query.
Value search is default-deny to a small allowlist of name-type dimensions; email- and phone-shaped values are redacted from results.
Same-slug saves replace. Chart and dashboard saves overwrite existing content with the same slug; the preview states this before confirmation.
Dashboard edits merge, not wipe. Editing preserves non-chart tiles and dashboard filters automatically; tabbed dashboards and dashboards containing SQL-chart tiles are refused for editing.

Tracks — service availability and utilisation reporting aggregates track-level operations.
Resources — resource usage feeds the operational data the warehouse syncs.
Revenue management — financial performance questions surface through accounting-entry metrics.