Uptimizr

io.github.RaananW由 GitHub 帳號 RaananW 發布v1.2.3更新於 Nov 7, 2026

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

已驗證STDIO僅桌面安全與監控資料與分析媒體與設計

概覽

AI 產生的概覽

連接你自架的 Uptimizr 收集器，讓助理用自然語言查詢 3D 場景分析資料：熱圖、網格、工作階段與效能。

可以做什麼
  • 查詢工作階段與場景：列出近期工作階段、工作階段中繼資料、行走軌跡、場景表示與場景清單
  • 分析注意力與互動：指標、視線、世界空間、相機與位置熱圖，點擊射線、流向連線、熱門網格、停留、盲區、無效點擊與連續點擊
  • 檢視導覽與轉換：覆蓋率、彙總路徑、折返比例、轉換漏斗、留存、變體排行榜，以及基準、變化項目、異常與顯著性洞察
  • 檢查算繪效能與穩定性：FPS 分布、影格時間百分位、卡頓、著色器編譯停頓、GPU 與記憶體百分位、錯誤熱圖與診斷
  • 稽核 XR 與 AR：頭部旋轉、移動方式、追蹤品質、邊界接觸、工作階段放棄與 AR 放置指標
  • 讀取能力與技能資源，並執行內建方法論提示，例如注意力熱點、轉換排查與每週場景健康檢查
適用情境
適用於團隊已為 3D、WebGL 或 XR 產品部署 Uptimizr 收集器，並希望助理不必開啟儀表板就能回答互動、漏斗或影格率回退相關問題。
執行需求
透過 npx 以 stdio 在本機執行 npm 套件 @uptimizr/mcp，需要 Node.js。需設定 UPTIMIZR_COLLECTOR_URL（自架收集器的基礎網址）與 UPTIMIZR_API_KEY（以 x-api-key 標頭送出）。金鑰需具備 query 能力；加上 annotate 才會啟用中繼資料工具。需要能連線到你的收集器。
安裝前請注意
API 金鑰是專案憑證，需寫入用戶端設定，請勿放在共用檔案中。讀取類工具只發出 GET 請求，無法修改事件；但具備 annotate 能力的金鑰還會註冊寫入專案中繼資料的工具（註解、詞彙表、已儲存分析、釘選面板），這些寫入會記入專案的代理稽核記錄。資料只送往你自己的收集器，不會傳給第三方。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Uptimizr，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

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.

來源：oss/packages/mcp/README.md，提交 4e64022

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v1.2.3最新Nov 7, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分