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 分