Uptimizr

io.github.RaananWPublished by GitHub account RaananWv1.2.3Updated Nov 7, 2026

Ask an AI agent about your self-hosted 3D scene analytics: heatmaps, meshes, performance, sessions.

VerifiedSTDIODesktop onlySecurity & MonitoringData & AnalyticsMedia & Design

Overview

AI-generated overview

Queries your own self-hosted Uptimizr collector so an assistant can answer questions about 3D scene analytics: heatmaps, meshes, sessions and performance.

What you can do
  • Query sessions and scenes: list recent sessions, session metadata, walked paths, scene representations and scene lists
  • Analyze attention and interaction: pointer, gaze, world, camera and position heatmaps, click rays, flow links, top meshes, dwell, blind spots, dead and rage clicks
  • Review navigation and funnels: coverage, aggregate paths, backtracking, conversion funnels, retention, variant leaderboards and insight baselines, movers, anomalies and significance
  • Inspect rendering performance and stability: FPS distributions, frame-time percentiles, jank, compile stalls, GPU and memory percentiles, error heatmaps and diagnostics
  • Audit XR and AR: head rotation, locomotion, tracking quality…
When to use it
Use it when your team already runs an Uptimizr collector for a 3D, WebGL or XR product and you want an assistant to answer natural-language questions about engagement, funnels or frame-rate regressions without opening a dashboard.
Requirements
Runs locally over stdio via npx from the npm package @uptimizr/mcp, so Node.js is needed. Requires UPTIMIZR_COLLECTOR_URL (base URL of your own collector) and UPTIMIZR_API_KEY, sent as the x-api-key header. The key needs the query capability; add annotate to enable metadata tools. Network access to your collector is required.
Before you install
The API key is a project credential passed in the client config; keep it out of shared files. Read tools are GET-only and cannot alter events, but a key with the annotate capability also registers tools that write project metadata (annotations, glossary terms, saved analyses, pinned panels), recorded in the project's agent audit log. Data goes only to your own collector, not to third parties.

Installation

In SourceWeft

  1. Open Uptimizr in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@uptimizr/mcp

A Model Context Protocol server over an Uptimizr collector's API. It lets an AI agent ask natural-language questions about your 3D analytics ("what was the most-clicked mesh this week?") and have them answered by querying your own collector — nothing is sent to any third party.

The server is a thin wrapper: each analytics tool maps one-to-one to a documented collector query endpoint (see integration docs) and performs GET requests only. There is no ingestion tool, and nothing here can write, alter or delete an analytics event — events are read-only. A key holding query:raw additionally gets session_narrative, the compacted account of one session, on a collector running with ENABLE_RAW_SESSION_RETENTION.

The one exception is gated: when the configured key holds the annotate capability the server also registers the project-metadata tools annotate, define_term, save_analysis, pin_panel and unpin_panel (plus list_annotations, list_glossary, list_analyses, list_panels), which leave notes, definitions, saved analyses and pinned panels behind. The server asks GET /api/v1/whoami once at start-up, so a read-only key yields a read-only server, and every metadata write is recorded in the project's agent audit log.

How it connects

The server talks only to your collector's HTTP query API — it never opens the database (DuckDB/ClickHouse/Postgres) directly. The collector stays the single gateway to your data, so an agent gets exactly the auth, project-scoping, and privacy guarantees a dashboard user does:

text
AI agent ──stdio──▶ @uptimizr/mcp ──HTTPS GET + x-api-key──▶ collector ──▶ store

Run

bash
UPTIMIZR_COLLECTOR_URL="https://collect.example.com" \UPTIMIZR_API_KEY="utk_…" \npx @uptimizr/mcp
Environment variableRequiredNotes
UPTIMIZR_COLLECTOR_URLyesBase URL of your collector.
UPTIMIZR_API_KEYyesYour project API key (x-api-key). query reads; add annotate to enable the metadata tools.

Configure an MCP client

Most MCP clients (Claude Desktop, VS Code, etc.) launch the server over stdio. Example client config:

json
{  "mcpServers": {    "uptimizr": {      "command": "npx",      "args": ["-y", "@uptimizr/mcp"],      "env": {        "UPTIMIZR_COLLECTOR_URL": "https://collect.example.com",        "UPTIMIZR_API_KEY": "utk_…"      }    }  }}

For GitHub Copilot CLI, put the same entry in ~/.copilot/mcp-config.json with "type": "local" and "tools": ["*"], then restart the CLI so it loads the tools:

json
{  "mcpServers": {    "uptimizr": {      "type": "local",      "command": "npx",      "args": ["-y", "@uptimizr/mcp"],      "env": {        "UPTIMIZR_COLLECTOR_URL": "http://localhost:4318",        "UPTIMIZR_API_KEY": "utk_…"      },      "tools": ["*"]    }  }}

Tools

The catalog is generated from the semantic metric registry in @uptimizr/metrics (ADR 0051 §1): every metric the collector serves on a read endpoint is a tool — 76 of them, one table row each, of which a plain query key sees 75 (session_narrative needs query:raw). Each tool's description carries the metric's interpretation notes and caveats, and each declares an MCP outputSchema covering every format envelope it can answer with — the rows, the table envelope around them (the tools' default), or a summary digest. Results come back as both content text and structuredContent. Read uptimizr://capabilities for each tool's result grain, column units, row schema and caveats; the same registry drives the collector's GET /api/v1/openapi.json.

Most tools accept an optional time range (since / until, epoch ms) and the filters the underlying endpoint supports (scene, session, source, bins, cellSize, interval, type, limit, cameraMode, region, …). session_meta, session_trajectory and scene_representation take a required id.

ToolEndpointReturnsParameters
list_sessions/api/v1/sessionsRecent sessionssince, until, bins, limit, cameraMode, format
session_meta/api/v1/sessions/:id/metaSession descriptorsession
session_narrative/api/v1/sessions/:id/narrativeSession narrativesession, minDwellMs, fpsThreshold, maxEntries, format
scene_representation/api/v1/scenes/:sceneId/representationScene representationscene
list_scenes/api/v1/scenesActive scenessince, until, limit, format
timeseries/api/v1/timeseriesEvent volume over timesince, until, interval, scene, type, format
event_counts/api/v1/event-countsCounts per event typesince, until, scene, format
pointer_heatmap/api/v1/heatmaps/pointer2D pointer heatmapsince, until, bins, limit, scene, session, source, cameraMode, format
mesh_uv_heatmap/api/v1/heatmaps/mesh-uvPer-mesh UV (texture-space) heatmapsince, until, bins, limit, scene, session, source, mesh, format
world_heatmap/api/v1/heatmaps/world3D world-space pointer heatmapsince, until, cellSize, limit, scene, source, cameraMode, region, format
world_heatmap_stats/api/v1/heatmaps/world/statsWorld heatmap totalssince, until, cellSize, scene, source, cameraMode, region, format
gaze_heatmap/api/v1/heatmaps/gazeWorld-space gaze heatmapsince, until, cellSize, limit, scene, session, cameraMode, region, format
gaze_heatmap_stats/api/v1/heatmaps/gaze/statsGaze heatmap totalssince, until, cellSize, scene, session, cameraMode, region, format
camera_heatmap/api/v1/heatmaps/cameraView-direction heatmapsince, until, bins, limit, scene, session, cameraMode, format
view_coverage_histogram/api/v1/coverage/view-histogram360° view-coverage histogramsince, until, bins, limit, scene, session, cameraMode, format
position_heatmap/api/v1/heatmaps/positionFloor-plan camera-position heatmapsince, until, cellSize, limit, scene, session, cameraMode, region, format
session_trajectory/api/v1/sessions/:sessionId/trajectorySession walked pathsession, since, until, limit, scene, format
aggregate_paths/api/v1/pathsAggregate desire-line pathssince, until, cellSize, limit, scene, cameraMode, format
scene_coverage/api/v1/coverageScene coverage / dead zonessince, until, cellSize, limit, scene, session, format
camera_distance/api/v1/camera/distanceCamera distance / zoom distributionsince, until, centerX, centerY, centerZ, bucketSize, limit, scene, session, format
click_rays/api/v1/heatmaps/click-raysView-gated click rayssince, until, cellSize, limit, scene, source, session, format
flow_links/api/v1/heatmaps/flowGaze → mesh flow linkssince, until, bins, limit, scene, session, cameraMode, cellSize, groupByOrigin, originVoxel, format
top_meshes/api/v1/meshes/topMost-interacted meshessince, until, bins, limit, session, format
mesh_sources/api/v1/meshes/sourcesMesh interactions by input sourcesince, until, bins, limit, scene, session, source, cameraMode, format
mesh_trend/api/v1/meshes/trendPer-mesh interaction trendsince, until, bins, limit, scene, session, source, cameraMode, interval, format
mesh_dwell/api/v1/meshes/dwellPer-object dwell / attentionsince, until, bins, limit, scene, session, format
mesh_blind_spots/api/v1/meshes/blind-spotsBlind spots / never-noticed meshessince, until, bins, limit, scene, session, format
mesh_interaction_kinds/api/v1/meshes/kindsInteraction kinds per meshsince, until, bins, limit, scene, session, source, cameraMode, format
mesh_reachability/api/v1/meshes/reachabilityMesh reachability by distancesince, until, bins, limit, scene, session, source, cameraMode, bucketSize, format
dead_clicks/api/v1/clicks/deadDead-click ratesince, until, bins, limit, scene, session, source, cameraMode, format
rage_clicks/api/v1/clicks/rageRage-click clusterssince, until, bins, limit, scene, session, source, cameraMode, interval, minRepeats, format
hover_dwell/api/v1/hover/dwellHover hesitation per objectsince, until, bins, limit, scene, session, source, cameraMode, format
interaction_sources/api/v1/interactions/sourcesInteractions by input sourcesince, until, bins, limit, scene, session, source, cameraMode, format
top_input_actions/api/v1/input-actions/topMost-used shortcuts and actionssince, until, bins, limit, scene, session, source, cameraMode, format
custom_event_vocabulary/api/v1/vocabulary/custom-eventsDiscovered custom-event vocabularysince, until, scene, limit, format
camera_gestures/api/v1/camera-gesturesCamera navigation gesturessince, until, bins, limit, scene, session, source, cameraMode, format
navigation_stats/api/v1/navigationNavigation effort per sessionsince, until, moveThreshold, limit, scene, session, format
backtrack_ratio/api/v1/backtrackPath retrace / backtrackingsince, until, cellSize, limit, scene, session, format
perf_summary/api/v1/perfRendering performance summarysince, until, bins, limit, session, format
render_scale_truth/api/v1/perf/render-scaleRender-scale truthsince, until, bins, limit, session, format
perf_distribution/api/v1/perf/distributionFPS distribution (per-session)since, until, bins, limit, scene, session, format
fps_histogram/api/v1/perf/fps-histogramPer-session median-FPS histogramsince, until, bins, limit, scene, session, bucket, format
frame_time_percentiles/api/v1/perf/frame-timeFrame-time percentilessince, until, bins, limit, scene, session, format
jank_rate/api/v1/perf/jankJank ratesince, until, bins, limit, scene, session, format
perf_churn/api/v1/perf/churnPerf-correlated churnsince, until, bins, limit, scene, session, windowMs, fpsThreshold, stallMs, format
perf_by_device/api/v1/perf/by-deviceFPS by device classsince, until, bins, limit, scene, session, format
perf_by_scene/api/v1/perf/by-sceneFPS by scenesince, until, bins, limit, scene, session, format
perf_heatmap/api/v1/heatmaps/perfSpatial FPS heatmapsince, until, cellSize, limit, scene, session, format
compile_stalls/api/v1/perf/compile-stallsShader / pipeline compile stallssince, until, bins, limit, scene, session, format
resource_summary/api/v1/perf/resourcesGPU / memory footprint summarysince, until, bins, limit, session, format
resource_percentiles/api/v1/perf/resource-percentilesGPU / memory footprint percentilessince, until, bins, limit, scene, session, format
stability_counts/api/v1/perf/stabilityStability incidentssince, until, bins, limit, scene, session, format
graphics_diagnostics/api/v1/graphics-diagnosticsEngine diagnostic countssince, until, bins, limit, scene, session, format
error_heatmap/api/v1/heatmaps/errorsSpatial error heatmapsince, until, cellSize, limit, scene, session, region, severity, category, errorKind, format
rendering_technology/api/v1/rendering-technologyRendering-technology mixsince, until, bins, limit, scene, session, format
capability_changes/api/v1/capabilitiesCapability / fidelity transitionssince, until, bins, limit, scene, session, format
xr_rotation/api/v1/xr/rotationXR head-rotation ratesince, until, rapidTurn, limit, scene, session, format
xr_sources/api/v1/xr/sourcesXR input-source usagesince, until, bins, limit, scene, session, format
xr_abandonment/api/v1/xr/abandonmentXR session abandonmentsince, until, bins, limit, scene, session, format
xr_locomotion/api/v1/xr/locomotionXR locomotion & comfortsince, until, bins, limit, scene, session, format
xr_tracking_quality/api/v1/xr/trackingXR tracking qualitysince, until, bins, limit, scene, session, format
boundary_heatmap/api/v1/heatmaps/boundaryGuardian / boundary-touch heatmapsince, until, cellSize, limit, scene, session, region, format
boundary_heatmap_stats/api/v1/heatmaps/boundary/statsBoundary heatmap totalssince, until, cellSize, scene, session, region, format
xr_boundary_contacts/api/v1/xr/boundary-contactsBoundary contacts per sessionsince, until, bins, limit, scene, session, format
ar_placement_time_to_place/api/v1/ar/placement/time-to-placeAR time-to-place distributionsince, until, bins, limit, scene, session, bucketMs, format
ar_placement_attempts/api/v1/ar/placement/attemptsAR re-placement distributionsince, until, bins, limit, scene, session, format
ar_placement_surfaces/api/v1/ar/placement/surfacesAR placement surfacessince, until, bins, limit, scene, session, format
funnel/api/v1/funnelConversion funnelsince, until, scene, cameraMode, steps, format
scene_retention/api/v1/scene-retentionScene-to-scene retentionsince, until, limit, format
load_bounce_funnel/api/v1/load-bounceLoad → bounce funnelsince, until, scene, bands, format
variant_leaderboard/api/v1/variant-leaderboardVariant → conversion leaderboardsince, until, scene, cameraMode, variant, conversion, limit, format
insight_baseline/api/v1/insights/baselineMetric baselinemetric, scene, window, bucket, since, until, format
insight_movers/api/v1/insights/moversWhat changedscene, metrics, bucket, limit, since, until, refSince, refUntil, format
insight_anomalies/api/v1/insights/anomaliesAnomalous bucketsmetric, scene, window, bucket, sensitivity, since, until, format
insight_significance/api/v1/insights/significanceStatistical significancemetric, scene, bucket, since, until, refSince, refUntil, format
insight_scene_health/api/v1/insights/scene-healthScene health scorescene, window, since, until, bucket, limit, weights, format

Resources & prompts

The server also exposes read-only resources for self-discovery — uptimizr://capabilities (a machine-readable descriptor of event types, the tool catalog, parameter semantics, and metrics: the collector's whole semantic metric registry, with each metric's result grain, column units, row JSON Schema, row limits, interpretation and caveats — ADR 0051) and uptimizr://context (the live project context document), uptimizr://scenes (live scene ids) and uptimizr://skills (the methodology catalog below) — plus one curated prompt per packaged skill, listed in the table below, that drives the tools above. See the MCP guide for details.

Methodology skills

Each prompt template is a packaged skill — an Agent Skills file, skills/<name>/SKILL.md, shipped in this package — so the method an agent follows is readable, forkable and identical to the one uptimizr agent report --skill runs on your collector. The catalog is also served as the uptimizr://skills resource. * marks a required argument.

SkillArgumentsWhat it produces, and when to use itTools its method names
attention_hotspotsscene*, range?Find where visitors look and click in a scene: view-direction concentration, gaze→mesh flow, the objects that draw the most interaction, and the ones nobody ever notices. USE FOR: deciding where to put a call to action, finding ignored or invisible content, explaining why an object gets no clicks, laying out a scene around what people actually look at.camera_heatmap, flow_links, click_rays, top_meshes, mesh_dwell, mesh_blind_spots, query
conversion_investigationscene?, range?Find out where a funnel loses people and whether the loss is real: step-by-step drop-off, the bounce that happens before the funnel even starts, scene-to-scene retention, variant performance, and the interaction failures (dead clicks, rage clicks, unreachable meshes) that explain a stalled step. USE FOR: a funnel that converts worse than expected, an A/B variant comparison, "where do people drop off", diagnosing a step nobody completes.funnel, load_bounce_funnel, scene_retention, variant_leaderboard, dead_clicks, rage_clicks, mesh_reachability, flow_links, insight_significance, insight_movers, query
performance_regression_triagescene?, range?Triage a frame-rate or stability regression: confirm it moved, date it, locate it (which scene, device class, place in the scene), and name the mechanism — jank, shader compile stalls, memory pressure, a render-scale change or a rendering-technology shift. USE FOR: "the app got slower", a FPS drop after a release, stutter reports, deciding whether a regression is real or noise.insight_movers, insight_anomalies, insight_significance, insight_baseline, perf_summary, perf_distribution, frame_time_percentiles, jank_rate, perf_by_device, perf_by_scene, perf_heatmap, compile_stalls, resource_percentiles, render_scale_truth, rendering_technology, query
weekly_scene_healthscene?, range?A weekly health check for a scene (or the whole project): a weighted health score with every factor traced back to the metric behind it, what changed against last week, traffic, event mix, performance, and the most-interacted meshes. USE FOR: the recurring "how is the scene doing?" review, a scheduled weekly or monthly report, a first look at a project you do not know yet, deciding which scene to investigate next.insight_scene_health, insight_movers, insight_baseline, insight_significance, insight_anomalies, event_counts, timeseries, perf_summary, top_meshes, list_sessions, query
xr_comfort_auditscene?, range?Audit VR/AR comfort for a scene (or the whole project): rapid head rotation, locomotion style, tracking quality, guardian/boundary contacts, input-source mix, and the short sessions that mean someone took the headset off. USE FOR: motion-sickness complaints, immersive sessions that end early, choosing a locomotion scheme, checking whether a play space is big enough.xr_rotation, xr_locomotion, xr_abandonment, xr_sources, xr_tracking_quality, xr_boundary_contacts, boundary_heatmap_stats, insight_scene_health, insight_movers, query
bash
cat node_modules/@uptimizr/mcp/skills/weekly-scene-health/SKILL.md

Hosted transport (Streamable HTTP)

The collector can serve this same server itself, over MCP's Streamable HTTP transport, so a remote agent connects with a URL and a key instead of launching this package locally (ADR 0051 §7). Start the collector with COLLECTOR_MCP_HTTP=1 and point a client at /mcp:

jsonc
{  "mcpServers": {    "uptimizr": {      "type": "http",      "url": "https://collect.example.com/mcp",      "headers": { "Authorization": "Bearer utk_…" },    },  },}

x-api-key works in place of the bearer header, the key still needs only query, and the tools, resources and prompts are identical — both transports are built by the same createMcpServer() below. Tool calls made that way are recorded in the collector's audit log with surface: "mcp-http"; calls from this package over stdio are ordinary HTTP reads, recorded as http. See the hosted transport guide.

Programmatic use

ts
import { createCollectorClient, createMcpServer, readMcpConfig } from "@uptimizr/mcp";import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const client = createCollectorClient(readMcpConfig());const server = createMcpServer(client);await server.connect(new StdioServerTransport());

createMcpServer(client, options?) takes an optional options.capabilities — the capability set of the API key the server instance is bound to. The collector-hosted transport passes the key it resolved, so a session's surface can only narrow to what its key may do; omitting it (as the stdio entry point does) registers the whole read catalog and leaves enforcement to the collector.

The package also exports readTools, rawTools, writeTools, CollectorError, version, and the related public types. The read-only analytics catalog (readTools), the annotate-gated writeTools, and the collector client are defined in the framework-agnostic @uptimizr/agent-core package and re-exported here, so the agent tool surface is defined once and shared across the MCP server, the dashboard assistant, and the demo assistant (ADR 0050). Building a non-MCP agent? Depend on @uptimizr/agent-core directly — it also ships a headless provider-adapter interface and tool-calling loop.

Develop

bash
pnpm --filter @uptimizr/mcp buildpnpm --filter @uptimizr/mcp typecheckpnpm --filter @uptimizr/mcp test

Licensed under Apache-2.0.

Source: oss/packages/mcp/README.md at commit 4e64022

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.2.3LatestNov 7, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts