v0.5.1

Umami Compass 0.5.1 — Compact portfolio answers you can trust

Umami Compass 0.5.1 is a focused follow-up to the portfolio performance release. It keeps every analyzed site and the evidence needed for decisions while cutting the default response dramatically, selecting drill-downs from the correct metric, removing low-sample noise from aligned rows, and making truncation and collection semantics precise.

Important

analyze_performance_portfolio now defaults to verbosity: "compact". Use standard for richer per-site rows and metric-specific page/device drill-downs, or full for the complete normalized evidence shape introduced in 0.5.0. The aggregate meta.truncated field remains, but new clients should use meta.responseTruncated and meta.sectionsTruncated.

Fixes

Portfolio responses fit the client

• Add verbosity: "compact" | "standard" | "full".
• Keep every analyzed website, selected-metric p75/change values, current and comparison event counts, confidence, event/pageview ratios, and decision leaders in compact mode.
• Omit drill-downs and repeated normalized percentile structures from the default response.
• Keep a representative 23-site compact response below 24 KB in integration tests; the reported 0.5.0 full response was approximately 114 KB.
• Preserve the complete 0.5.0 evidence payload behind explicit verbosity: "full".

Drill-downs follow detailMetric

• Select detail websites only from regressions and worst-site rankings for the requested detailMetric.
• Stop selecting a site because of TTFB or INP and then returning unrelated LCP pages.
• Continue prioritizing regressions for the detail metric before its worst current values.
• Allow detailMetric to drive drill-down selection even when it is not included in the compact metrics list.

Useful aligned rows come first

• Add includeInsufficient to compare_performance_breakdown and portfolio drill-downs.
• Default includeInsufficient to false.
• Exclude rows below minimumSampleCount before applying the returned-row limit.
• Return comparable rows first, followed by sufficiently sampled one-sided rows.
• When explicitly requested, append undersized inconclusive rows after the useful comparisons.
• Report both the detected and excluded undersized-row counts under dataQuality.

Truncation is no longer ambiguous

• Add meta.responseTruncated for an incomplete primary result.
• Add meta.sectionsTruncated with exact paths such as details.pages, leaders.worst, or candidateItems.
• Keep meta.truncated as a backward-compatible aggregate of the two precise states.
• Report a fully analyzed portfolio as responseTruncated: false even when a nested detail list is bounded.
• Preserve upstream candidate uncertainty as a section state instead of claiming the whole response was cut.

Events per pageview are not coverage

• Replace the misleading *PerformanceEventsPerPageviewPercent fields with performanceEventsPerPageviewRatio.
• Allow the ratio to exceed 1; Umami can report more than one performance event per pageview.
• Return true collection coverage as unknown_upstream instead of presenting an events/pageviews ratio as a covered-pageview percentage.
• Keep current and comparison ratios separate.

Note

Umami 3.2 still does not expose metric-specific counts in time buckets, queryable likely-human/likely-bot performance segmentation, LCP decomposition, LCP element/resource attribution, cache status, or edge region. Compass continues to report these limitations explicitly rather than manufacturing missing evidence.

Safety and compatibility

• All 42 tools remain read-only.
• Compact output reduces analytics data entering model context.
• No new identifiers or row-level events are exposed.
• meta.truncated remains available for existing clients.
• Callers that require the full 0.5.0 portfolio shape must now pass verbosity: "full".
• The old misleading event/pageview percentage fields are replaced rather than retained as aliases.

Upgrade

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

Pin this exact patch when reproducibility matters:

npx --yes umami-compass@0.5.1

Restart the MCP process or client after upgrading so it discovers the new portfolio and comparison inputs.

Compatibility and verification

• Umami Cloud and self-hosted Umami 3.2+.
• Node.js 22 or newer.
• 122 automated tests plus lint, typecheck, build, package smoke testing, and CI on Node.js 22, 24, and 26.
• A 23-site integration fixture enforces a compact structured response below 24 KB.
• Packed-package verification covers CLI version, MCP initialization, and the 15-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 #25
• Full changelog: v0.5.0...v0.5.1