v0.4.1

Umami Compass 0.4.1 — Trustworthy performance breakdowns

Umami Compass 0.4.1 is a focused patch release that prevents worst-page and environment rankings from being dominated by one-off Core Web Vital measurements. It adds a defensible sample guard, validates upstream percentile rows, and reports when Umami's own candidate limits make a filtered ranking incomplete.

Important

get_performance_breakdown now requires at least 20 samples per row by default for page, page-title, device, and browser rankings. Set minimumSampleCount explicitly to tighten the guard or use 1 to include every otherwise valid row. The tool surface and read-only security model are unchanged.

Fixes

• Exclude rows with fewer than 20 measurements from p75 rankings by default.
• Validate that row counts are positive integers and that p50 ≤ p75 ≤ p95 with nonnegative values.
• Reject missing names, missing counts, malformed percentiles, and impossible percentile ordering instead of silently ranking those rows.
• Distinguish genuinely empty ranges from insufficient_sample_size.
• Report the effective sample threshold and separate malformed-row and undersized-row counts.
• Apply the same quality policy consistently to page, page-title, device, and browser breakdowns.

Candidate coverage

Umami 3.2 sorts page-level performance candidates by p75 and caps page, page-title, and browser results at 500 before Compass receives them.

• Compass now reports the upstream candidate limit, how many candidates were evaluated, and whether coverage may be truncated.
• If all fully observed candidates are undersized, the result is empty with emptyReason: "insufficient_sample_size".
• If the 500-row cap prevents a complete conclusion, the result uses dataStatus: "unknown" instead of presenting the filtered ranking as exhaustive.
• Device results remain uncapped by this Umami route and report candidateItemLimit: null.

Why 20 samples?

The default is an exploratory p75 quality guard, not a claim of statistical significance. With 20 observations, the upper quartile represented by p75 contains at least five measurements, which prevents a single extreme visit from deciding the worst-page ranking. Callers with stricter evidence requirements can raise the threshold.

Safety and data quality

• All 37 tools remain read-only.
• The change adds no upstream requests and exposes no additional identifiers or event/session payloads.
• Invalid upstream aggregate rows are separated from valid but undersized rows.
• Result metadata preserves uncertainty when upstream candidate coverage is incomplete.
• Ranking remains deterministic: p75 descending, then sample count descending, then name.

Upgrade

npx --yes --prefer-online umami-compass@latest

Pin this exact patch when reproducibility matters:

npx --yes umami-compass@0.4.1

Restart the MCP process or client after upgrading so it discovers the updated tool schema.

Compatibility and verification

• Umami Cloud and self-hosted Umami 3.2+.
• Node.js 22 or newer.
• 109 automated tests plus lint, typecheck, build, package smoke testing, and CI on Node.js 22, 24, and 26.
• Packed-package verification covers CLI version, MCP initialization, and the 14-tool default surface.
• Official MCP Registry metadata validation completed before publication.
• npm publication includes SLSA provenance.

Release links

• npm package
• Official MCP Registry record
• Release PR #21
• Umami 3.2 performance aggregation
• Full changelog: v0.4.0...v0.4.1

v0.4.0

Umami Compass 0.4.0 — Release impact you can trust

Umami Compass 0.4.0 makes release analysis more honest and actionable: insufficient performance data now leads the verdict, traffic loss is separated from lower browsing depth, overlapping deployments are treated as confounders, and every low-data result explains when and how to recheck.

Important

analyze_release_impact now returns a compact executive summary by default. Use detailLevel: "full" when you need complete traffic breakdowns, traffic-quality evidence, and per-metric Core Web Vital changes. The tool surface and read-only security model are unchanged.

Highlights

Insufficient data comes first

• Return insufficient_data as the primary verdict when Core Web Vital samples do not meet the confidence threshold.
• Report the exact post-release and baseline sample deficits instead of only marking individual metrics inconclusive.
• Estimate recheckAt and a longer equal-window recommendation from the observed sample rate when a reliable estimate is possible.
• Avoid inventing a recheck date when the observed sample rate is zero or the required window would exceed the supported limit.

Better traffic interpretation

• Use visitors and visits to describe audience traffic instead of treating pageviews alone as traffic volume.
• Report pageviews per visit separately as browsing-depth evidence.
• Distinguish audience growth or decline from reduced or increased page depth and mixed audience signals.
• Treat zero baselines and weak audience samples as insufficient evidence rather than assigning a confident direction.

Competing releases and attribution

• Accept up to 20 neighboring deployments through otherReleases.
• Mark an observed change as confounded when another release overlaps the comparison windows.
• Keep evidenceVerdict available so clients can distinguish the observed signal from the attribution limit.
• Recommend supplying release history when competing-deployment context is unknown.

Compact by default, detailed on demand

• Return the verdict, confidence, traffic pattern, performance state, exact periods, sample readiness, attribution context, and recommended checks in the default response.
• Avoid page, referrer, device, channel, and event breakdown fan-out in summary mode.
• Preserve the complete evidence payload behind detailLevel: "full".
• Update the guided release-impact prompt to request summary mode first and drill down only when needed.

Safety and data quality

• All 37 tools remain read-only.
• Equal pre/post durations and explicit comparison periods remain part of every release analysis.
• Performance regressions and improvements still require material movement and sufficient samples.
• Human-traffic referrer exclusions remain aligned across traffic and performance where Umami supports the same scope.
• The result continues to describe before/after association rather than claiming causation.

Upgrade

npx --yes --prefer-online umami-compass@latest

Pin this exact release when reproducibility matters:

npx --yes umami-compass@0.4.0

Restart the MCP process or client after upgrading so it discovers the updated tool schema.

Compatibility and verification

• Umami Cloud and self-hosted Umami 3.2+.
• Node.js 22 or newer.
• 105 automated tests plus lint, typecheck, build, package smoke testing, and CI on Node.js 22, 24, and 26.
• Packed-package verification covers CLI version, MCP initialization, and the 14-tool default surface.
• Official MCP Registry metadata validation completed before publication.
• npm publication includes SLSA provenance.

Release links

• npm package
• Official MCP Registry record
• Release PR #20
• Full changelog: v0.3.1...v0.4.0

v0.3.1

Umami Compass 0.3.1 — Traffic analysis hardening

Umami Compass 0.3.1 is a focused patch release from an independent logic and code audit of the 0.3.0 traffic-analysis surface. It fixes unsafe filter composition, sparse/DST series alignment, evidence-scope mismatches, and silent upstream-data degradation without expanding the tool surface.

Important

Restart the MCP process or client after upgrading. The default and full tool counts are unchanged.

Fixes

• Fail closed when filters.match: "any" would weaken mandatory human-traffic exclusions or derived channel predicates.
• Fill sparse comparison series against real timezone buckets, handle DST spring-forward, and omit unsafe deltas when fall-back produces unequal local bucket counts.
• Keep release-impact traffic and Core Web Vitals in comparable scopes; channel-specific verdicts no longer mix filtered traffic with all-channel performance.
• Reject unsupported channel × event breakdowns and malformed expanded/breakdown rows instead of returning misleading empty results.
• Enforce field-specific structured-filter limits plus aggregate condition, value, and 16 KiB serialized-query budgets.
• Distinguish empty-referrer isolation from exact direct attribution and report capabilities from the actually enabled toolsets.

Safety and data quality

• All tools remain read-only.
• Ambiguous OR composition and malformed upstream evidence now fail closed.
• Sparse-series output exposes alignment quality; derived deltas are omitted when bucket counts are not safely comparable.
• Human-referrer exclusions are applied consistently to both traffic and performance evidence where Umami supports them.

Upgrade

npx --yes --prefer-online umami-compass@latest

Pin this exact patch when reproducibility matters:

npx --yes umami-compass@0.3.1

Compatibility and verification

• Umami Cloud and self-hosted Umami 3.2+.
• Node.js 22 or newer.
• 100 automated tests plus lint, typecheck, build, package smoke testing, and CI on Node.js 22, 24, and 26.
• Independently reviewed before and after the fixes; final verdict found no remaining P0–P2 issues.
• npm publication includes SLSA provenance.

Release links

• npm package
• Official MCP Registry record
• Release PR #19
• Full changelog: v0.3.0...v0.3.1

v0.3.0

Umami Compass 0.3.0 — Traffic you can trust

Umami Compass 0.3.0 makes traffic investigations actionable: isolate direct visits, filter by channel, exclude known noise, and surface conservative referral-spam evidence without leaving the read-only analytics contract.

Important

The default read-only surface expands from 12 to 14 tools and the complete opt-in surface from 35 to 37. Restart the MCP process or client after upgrading so it can discover the new tools and capabilities.

Highlights

Channel-aware traffic analysis

• Filter explain_traffic_change and analyze_release_impact by channel, including direct.
• Isolate direct traffic with either referrer: "" or the structured is_empty operator.
• Build bounded channel × dimension breakdowns such as channel by device in run_breakdown_report.
• Include channel evidence automatically in traffic-change and release-impact explanations.

Human traffic and referral-spam signals

• Detect suspicious referral domains conservatively from generated-looking hostnames, at least 90% bounce rate, at most two seconds average visit duration, and a minimum of three visits.
• Return the evidence, thresholds, and confidence behind every referral-spam signal.
• Apply the opt-in trafficSegment: "human" preset to exclude detected domains through native negative filters.
• Connect referral-spam evidence to explain_traffic_change and tracking_health_check instead of returning only a generic causation caveat.

Note

Referral-spam detection is deliberately conservative and evidence-based. The human-traffic preset fails closed when traffic quality cannot be assessed for every required comparison period.

More expressive filters

• Add equals, not_equals, contains, not_contains, regex, and not_regex operators.
• Add is_empty and is_not_empty for direct and missing-value scenarios.
• Accept arrays for native IN and NOT IN behavior, including path and referrer exclusions.

Faster investigations and capability discovery

• Add compare_traffic_series for aligned current/baseline buckets, making the exact date of a traffic break visible.
• Add get_server_info for local version, enabled toolsets, safety limits, and supported capabilities.
• Preserve explicit truncation and incomplete-coverage metadata for bounded derived breakdowns.

Safety and data quality

• All 37 tools remain read-only.
• Human-traffic cleanup uses upstream negative referrer-domain filters; it does not mutate Umami data.
• Derived channel cross-tabs are bounded to 50 candidate rows with four concurrent workers.
• Incomplete candidate coverage and unavailable spam assessment are reported explicitly instead of being treated as complete data.

Upgrade

npx --yes --prefer-online umami-compass@latest

Pin this exact release when reproducibility matters:

npx --yes umami-compass@0.3.0

Restart the MCP process or client after upgrading.

Compatibility and verification

• Umami Cloud and self-hosted Umami 3.2+.
• Node.js 22 or newer.
• 87 automated tests plus lint, typecheck, build, package smoke testing, and CI on Node.js 22, 24, and 26.
• Packed-package verification covers CLI version, MCP initialization, and the 14-tool default surface.
• npm publication includes SLSA provenance.

Release links

• npm package
• Official MCP Registry record
• Release PR #18
• Full changelog: v0.2.0...v0.3.0

v0.2.0

Umami Compass 0.2.0 — Decision-ready analytics

Umami Compass 0.2.0 moves beyond low-level API wrappers with bounded workflows that answer portfolio, traffic, release-impact, and tracking-health questions directly while preserving the read-only security model.

Important

The default toolsets change from core to core,insights, expanding the default surface from 7 to 12 aggregate tools. Set UMAMI_TOOLSETS=core to retain the previous default surface. All 35 available tools remain read-only.

Highlights

Five decision-ready workflows

• resolve_website — resolve a UUID from a URL, domain, or name without guessing on ambiguous fuzzy matches.
• get_portfolio_overview — summarize visible websites, growth and decline leaders, stale data, failures, and anomalies.
• explain_traffic_change — compare equal periods and surface observed page, referrer, country, device, channel, and event changes without claiming causation.
• analyze_release_impact — assess equal pre/post windows across traffic and Core Web Vitals with explicit confidence and caveats.
• tracking_health_check — audit freshness, traffic drops, domains, expected events, recorder features, and permission failures.

Safer interpretation

• Add a common meta envelope with dataStatus, empty reason, website, requested range, timezone, and truncation state.
• Use explicit equal-length baseline requests for portfolio and tracking comparisons.
• Treat missing rows outside a truncated top-N as unknown instead of inventing zero values.
• Require material Web Vital movement and sufficient samples before assigning a release-impact direction.
• Register guided prompts only when their required toolsets are enabled.

Stronger authorization

• Add UMAMI_TEAM_IDS as a strict boundary for discovery and direct website/report access.
• Exclude user-owned websites while a team allowlist is active unless they belong to an allowed team.
• Intersect UMAMI_TEAM_IDS and UMAMI_WEBSITE_IDS when both are configured.
• Enforce the boundary before direct website routes, typed reports, and saved-report execution.

Additional MCP improvements

• Add the sanitized umami://capabilities resource for enabled toolsets, auth type, scope, and safety limits.
• Add guided workflows for weekly portfolio briefings, traffic investigation, release impact, tracking health, and conversion audits.
• Expand the complete opt-in surface from 30 to 35 tools.

Upgrade

npx --yes --prefer-online umami-compass@latest

Pin this exact release when reproducibility matters:

npx --yes umami-compass@0.2.0

Restart the MCP process or client after upgrading so it can discover the new tools and prompts.

Compatibility and verification

• Umami Cloud and self-hosted Umami 3.2+.
• Node.js 22 or newer.
• 79 automated tests plus lint, typecheck, build, package smoke testing, and CI on Node.js 22, 24, and 26.
• Independently reviewed twice; all identified P1/P2 code and logic findings were resolved before release.
• npm publication includes SLSA provenance.

Release links

• npm package
• Official MCP Registry record
• Release PR #15
• Full changelog: v0.1.3...v0.2.0

v0.1.3

Umami Compass 0.1.3 — Reliable team discovery

This patch completes reliable website discovery for Umami team members and view-only accounts, including deployments where includeTeams=true does not return team-owned websites from the primary endpoint.

Fixed

• Traverse each visible team through the dedicated Umami team-websites endpoint.
• Include websites available through member and view-only team roles without requiring a UUID workaround.
• Deduplicate websites returned through both direct and team discovery before applying pagination and the optional website allowlist.

Security and reliability

• Bound team traversal and upstream website pages.
• Fail explicitly when discovery exceeds the configured safety budget instead of returning a silently partial portfolio.
• Preserve global pagination and allowlist behavior after combining discovery sources.
• No write capabilities are introduced.

Who should upgrade

Upgrade if list_websites is empty or incomplete for a team member/view-only Umami identity, or if the same website appears through multiple discovery paths.

npx --yes --prefer-online umami-compass@latest

Reproduce this exact version:

npx --yes umami-compass@0.1.3

Restart the MCP process after changing versions.

Verification

• 57 automated tests, lint, typecheck, and build.
• npm 12 dry-run pack and clean-consumer package smoke test.
• Official MCP Registry publisher validation against synchronized release metadata.

Release links

• npm package
• Official MCP Registry record
• Release PR #14
• Full changelog: v0.1.2...v0.1.3

v0.1.2

Umami Compass 0.1.2 — Automatic client updates

This release makes stable client updates explicit and unifies the release pipeline so npm, the official MCP Registry, and GitHub Releases cannot silently drift to different versions.

Note

This is primarily a distribution and operations release. It does not expand the analytics tool surface.

Highlights

• Update documented stdio configurations to run umami-compass@latest with --prefer-online, allowing npm to check the stable channel whenever the MCP process starts.
• Document stable, preview, and exact-version channels, including the MCP restart required to load a newly installed version.
• Publish npm, exact MCP Registry metadata, and the GitHub Release from one tag-triggered workflow.
• Verify immutable package version, npm release channel, Registry propagation, and release metadata before completion.
• Make the workflow retry-safe: already-published artifacts are accepted only when they match the tagged commit.

Upgrade

Use the stable channel:

npx --yes --prefer-online umami-compass@latest

Reproduce this exact version:

npx --yes umami-compass@0.1.2

MCP processes do not hot-swap their executable. Restart the process or client after an upgrade.

Verification

• 55 automated tests, lint, typecheck, build, and packed-package smoke testing.
• Release metadata checked against the exact v0.1.2 tag.
• npm and MCP Registry publication verified by the release workflow.

Release links

• npm package
• Official MCP Registry record
• Release PR #13
• Full changelog: v0.1.1...v0.1.2

v0.1.1

Umami Compass 0.1.1 — Live-run reliability fixes

This patch release addresses defects found during the first live third-party run. It improves onboarding, report compatibility, performance ranking, recorder diagnostics, and numeric consistency without adding write capabilities.

Note

Team-inclusive discovery in this version relies on the primary Umami website endpoint. Reliable discovery for team member and view-only roles is completed in v0.1.3. New installations should use the current stable release.

Fixed

• Request team-inclusive website discovery where supported by the Umami 3.2 website endpoint.
• Parse segments and cohorts as paged Umami responses instead of rejecting them as arrays.
• Exclude performance rows with missing percentiles and rank valid rows by p75.
• Distinguish an authorized empty replay or heatmap result from a permission failure, including recorder state where available.
• Normalize safe numeric SQL aggregates such as views, visits, and total time without coercing identifiers or arbitrary values.

Why this matters

Agents now receive more dependable website discovery, compatible segment/cohort data, trustworthy performance ordering, actionable empty-state explanations, and stable numeric analytics fields.

Upgrade

Current stable release:

npx --yes --prefer-online umami-compass@latest

Reproduce this exact version:

npx --yes umami-compass@0.1.1

Restart the MCP process after changing versions.

Verification

• 53 automated tests, lint, typecheck, and build.
• npm 12 pack verification and packed-package MCP initialize/list-tools smoke test.
• Official MCP Registry publisher validation.

Release links

• npm package
• Official MCP Registry record
• Release PR #12
• Full changelog: v0.1.0...v0.1.1

v0.1.0

Umami Compass 0.1.0 — Initial public release

Umami Compass reaches its first public release: a secure, read-only Model Context Protocol server for Umami Analytics 3.2+, supporting both Umami Cloud and self-hosted deployments.

Note

This is a historical release. New installations should use the current stable version; exact-version instructions below are provided for reproducibility.

Highlights

• 30 read-only MCP tools across core analytics, events, sessions, Core Web Vitals, reports, revenue, replay metadata, and heatmaps.
• Least-privilege defaults with only the aggregate core toolset enabled initially.
• Three authentication modes: Umami Cloud API key, self-hosted Bearer token, or cached username/password login.
• Decision support: funnels, goals, journeys, retention, attribution, UTM analysis, revenue, bounded heatmaps, and replay metadata.
• MCP-native integration: structured tool output, resources, guided prompts, runtime schemas, and read-only annotations.

Security and reliability

• Fixed-origin upstream networking and HTTPS enforcement.
• Optional website UUID allowlist.
• Bounded date ranges, pages, response sizes, and high-cardinality results.
• Request timeouts, cancellation propagation, generation-safe login refresh, and redacted upstream errors.
• No tool in this release changes Umami state.

Install

Current stable release:

npx --yes --prefer-online umami-compass@latest

Reproduce this exact version:

npx --yes umami-compass@0.1.0

Requires Node.js 22 or newer. Restart the MCP process after changing versions.

Verification

• CI on Node.js 22, 24, and 26.
• 45 automated tests plus TypeScript build and packed-package MCP smoke testing.
• Published from commit d59b92a.

Distribution

• npm package
• Official MCP Registry record
• Source at v0.1.0

License: MIT.