@uptimizr/mcp 0.1.0

package/AGENTS.md

@@ -0,0 +1,43 @@
+# AGENTS.md — @uptimizr/mcp
+
+> Packaged agent guide. For the human reference see [README.md](./README.md); for design
+> rationale see the project ADRs at https://github.com/RaananW/Uptimizr/tree/main/docs/adr.
+
+## What this package is
+
+A **read-only** Model Context Protocol (MCP) server over an Uptimizr collector's query API. It
+lets an agent query a consumer's **own** 3D analytics in natural language. Each tool maps to one
+documented collector read endpoint; the server is a thin wrapper that holds no business logic and
+performs `GET` requests only (ADR 0005, ADR 0017).
+
+## Run
+
+```bash
+UPTIMIZR_COLLECTOR_URL="https://collect.example.com" UPTIMIZR_API_KEY="utk_…" npx @uptimizr/mcp
+```
+
+## Tools (read-only)
+
+`list_sessions`, `pointer_heatmap`, `world_heatmap`, `camera_heatmap`, `click_rays`, `flow_links`,
+`top_meshes`, `perf_summary`, `list_scenes`, `timeseries`, `event_counts`, `session_meta`,
+`scene_representation`. Most accept `since`/`until` (epoch ms) plus endpoint-specific filters
+(`scene`, `session`, `source`, `bins`, `cellSize`, `limit`).
+
+## Rules for agents
+
+- **Read-only and privacy-preserving.** Never add ingestion, mutation, or raw per-session event
+  tools here. No data leaves the consumer's infrastructure (ADR 0003).
+- The server talks only to the configured collector with the consumer's `x-api-key`; never hardcode
+  or log credentials.
+- Keep it a thin wrapper: a new tool = a new entry in the `readTools` registry mapping to a
+  documented query endpoint. Do not add aggregation/business logic — that lives in the collector.
+- Tool definitions are pure (`buildRequest`) and must stay unit-testable without a live collector.
+
+## Programmatic API
+
+`readMcpConfig()`, `createCollectorClient(config)`, `createMcpServer(client)`, `readTools`.
+
+## More
+
+- Package reference: [README.md](./README.md)
+- Integration guide: https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions for
+      use, reproduction, or distribution of Your modifications, or for any
+      such Derivative Works as a whole, provided Your use, reproduction,
+      and distribution of the Work otherwise complies with the conditions
+      stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Uptimizr Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,86 @@
+# @uptimizr/mcp
+
+A **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server over an
+Uptimizr collector's query 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 tool maps one-to-one to a documented collector query endpoint
+(see [integration docs](https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md)). It
+performs `GET` requests only — there are **no ingestion, mutation, or raw per-session event
+tools**.
+
+## Run
+
+```bash
+UPTIMIZR_COLLECTOR_URL="https://collect.example.com" \
+UPTIMIZR_API_KEY="utk_…" \
+npx @uptimizr/mcp
+```
+
+| Environment variable     | Required | Notes                                              |
+| ------------------------ | -------- | -------------------------------------------------- |
+| `UPTIMIZR_COLLECTOR_URL` | yes      | Base URL of **your** collector.                    |
+| `UPTIMIZR_API_KEY`       | yes      | Your project API key (`x-api-key`), read-only use. |
+
+### 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_…"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+All tools accept an optional time range (`since` / `until`, epoch ms) and the filters the
+underlying endpoint supports (`scene`, `session`, `source`, `bins`, `cellSize`, `limit`, …).
+
+| Tool                   | Endpoint                            | Returns                                          |
+| ---------------------- | ----------------------------------- | ------------------------------------------------ |
+| `list_sessions`        | `/api/v1/sessions`                  | Recent sessions.                                 |
+| `pointer_heatmap`      | `/api/v1/heatmaps/pointer`          | 2D pointer heatmap bins.                         |
+| `world_heatmap`        | `/api/v1/heatmaps/world`            | 3D world-space pointer voxels.                   |
+| `camera_heatmap`       | `/api/v1/heatmaps/camera`           | View-direction (spherical) bins.                 |
+| `click_rays`           | `/api/v1/heatmaps/click-rays`       | View-gated click rays.                           |
+| `flow_links`           | `/api/v1/heatmaps/flow`             | Gaze→mesh flow links.                            |
+| `top_meshes`           | `/api/v1/meshes/top`                | Most-interacted meshes.                          |
+| `perf_summary`         | `/api/v1/perf`                      | FPS summary (avg/min/p50).                       |
+| `list_scenes`          | `/api/v1/scenes`                    | Active scenes.                                   |
+| `timeseries`           | `/api/v1/timeseries`                | Event-volume buckets over time.                  |
+| `event_counts`         | `/api/v1/event-counts`              | Per-event-type counts.                           |
+| `session_meta`         | `/api/v1/sessions/:id/meta`         | Coarse session descriptor (no raw event stream). |
+| `scene_representation` | `/api/v1/scenes/:id/representation` | Registered proxy geometry, if any.               |
+
+## 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());
+```
+
+## Develop
+
+```bash
+pnpm --filter @uptimizr/mcp build
+pnpm --filter @uptimizr/mcp typecheck
+pnpm --filter @uptimizr/mcp test
+```
+
+Licensed under [Apache-2.0](./LICENSE).

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createCollectorClient } from "./client.js";
+import { readMcpConfig } from "./config.js";
+import { createMcpServer } from "./server.js";
+/**
+ * Entry point: read configuration from the environment, build a read-only
+ * collector client and MCP server, and serve over stdio (the transport MCP
+ * clients such as Claude Desktop / VS Code launch).
+ */
+async function main() {
+    const config = readMcpConfig();
+    const client = createCollectorClient(config);
+    const server = createMcpServer(client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`uptimizr-mcp failed to start: ${message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;GAIG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,OAAO,IAAI,CAAC,CAAC;IACnE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+import type { McpConfig } from "./config.js";
+/** A query-string parameter map. `undefined` values are omitted from the request. */
+export type QueryParams = Record<string, string | number | undefined>;
+/**
+ * A minimal **read-only** HTTP client over the collector query API. It performs
+ * `GET` requests only and holds no business logic — it is a thin transport that
+ * mirrors the dashboard's `CollectorApi` so an agent reads the same aggregated
+ * results a human would (ADR 0005 / ADR 0017).
+ */
+export interface CollectorClient {
+    get(path: string, params?: QueryParams): Promise<unknown>;
+}
+/** Thrown when the collector responds with a non-2xx status. */
+export declare class CollectorError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Build a read-only collector client bound to one `(collectorUrl, apiKey)` pair.
+ * `fetchImpl` is injectable for testing; it defaults to the global `fetch`.
+ */
+export declare function createCollectorClient(config: McpConfig, fetchImpl?: typeof fetch): CollectorClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,qFAAqF;AACrF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAED,gEAAgE;AAChE,qBAAa,cAAe,SAAQ,KAAK;IAGrC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM;CAK1B;AAMD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,SAAS,GAAE,OAAO,KAAa,GAC9B,eAAe,CAmBjB"}

package/dist/client.js

@@ -0,0 +1,38 @@
+/** Thrown when the collector responds with a non-2xx status. */
+export class CollectorError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "CollectorError";
+    }
+}
+function ensureTrailingSlash(url) {
+    return url.endsWith("/") ? url : `${url}/`;
+}
+/**
+ * Build a read-only collector client bound to one `(collectorUrl, apiKey)` pair.
+ * `fetchImpl` is injectable for testing; it defaults to the global `fetch`.
+ */
+export function createCollectorClient(config, fetchImpl = fetch) {
+    const base = ensureTrailingSlash(config.collectorUrl);
+    return {
+        async get(path, params = {}) {
+            const url = new URL(path.replace(/^\//, ""), base);
+            for (const [key, value] of Object.entries(params)) {
+                if (value != null)
+                    url.searchParams.set(key, String(value));
+            }
+            const res = await fetchImpl(url, {
+                method: "GET",
+                headers: { "x-api-key": config.apiKey },
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                throw new CollectorError(body || res.statusText, res.status);
+            }
+            return res.json();
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAeA,gEAAgE;AAChE,MAAM,OAAO,cAAe,SAAQ,KAAK;IAG5B;IAFX,YACE,OAAe,EACN,MAAc;QAEvB,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,SAAS,mBAAmB,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAiB,EACjB,YAA0B,KAAK;IAE/B,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACtD,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,IAAY,EAAE,SAAsB,EAAE;YAC9C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;YACnD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAClD,IAAI,KAAK,IAAI,IAAI;oBAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAC9D,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;gBAC/B,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE;aACxC,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;gBAC9C,MAAM,IAAI,cAAc,CAAC,IAAI,IAAI,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAC/D,CAAC;YACD,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Runtime configuration for the MCP server. The server only ever talks to the
+ * consumer's **own** collector, authenticated with the consumer's project API
+ * key — nothing is sent to any third party (ADR 0003 / ADR 0017).
+ */
+export interface McpConfig {
+    /** Base URL of the consumer's Uptimizr collector (e.g. https://collect.example.com). */
+    collectorUrl: string;
+    /** Project API key (`x-api-key`) used for read requests. */
+    apiKey: string;
+}
+/**
+ * Read and validate configuration from the environment. Throws a clear error if
+ * the collector URL or API key is missing or malformed.
+ */
+export declare function readMcpConfig(env?: NodeJS.ProcessEnv): McpConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,wFAAwF;IACxF,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AAOD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,SAAS,CAY7E"}

package/dist/config.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+const envSchema = z.object({
+    UPTIMIZR_COLLECTOR_URL: z.string().url("UPTIMIZR_COLLECTOR_URL must be a valid URL"),
+    UPTIMIZR_API_KEY: z.string().min(1, "UPTIMIZR_API_KEY must not be empty"),
+});
+/**
+ * Read and validate configuration from the environment. Throws a clear error if
+ * the collector URL or API key is missing or malformed.
+ */
+export function readMcpConfig(env = process.env) {
+    const parsed = envSchema.safeParse(env);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("; ");
+        throw new Error(`Invalid Uptimizr MCP configuration: ${issues}`);
+    }
+    return {
+        collectorUrl: parsed.data.UPTIMIZR_COLLECTOR_URL,
+        apiKey: parsed.data.UPTIMIZR_API_KEY,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IACzB,sBAAsB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,4CAA4C,CAAC;IACpF,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,oCAAoC,CAAC;CAC1E,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IAChE,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aAC3D,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,uCAAuC,MAAM,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,OAAO;QACL,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,sBAAsB;QAChD,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,gBAAgB;KACrC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { readMcpConfig, type McpConfig } from "./config.js";
+export { createCollectorClient, CollectorError, type CollectorClient, type QueryParams, } from "./client.js";
+export { readTools, type ReadTool, type ReadToolRequest } from "./tools.js";
+export { createMcpServer } from "./server.js";
+export { version } from "./version.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { readMcpConfig } from "./config.js";
+export { createCollectorClient, CollectorError, } from "./client.js";
+export { readTools } from "./tools.js";
+export { createMcpServer } from "./server.js";
+export { version } from "./version.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,qBAAqB,EACrB,cAAc,GAGf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAuC,MAAM,YAAY,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CollectorClient } from "./client.js";
+/**
+ * Build the Uptimizr MCP server: a read-only `McpServer` whose tools each wrap
+ * one collector query endpoint via the injected `CollectorClient`. The server
+ * holds no business logic — it forwards validated arguments and returns the
+ * collector's JSON (ADR 0005 / ADR 0017).
+ */
+export declare function createMcpServer(client: CollectorClient): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAyBlE"}

package/dist/server.js

@@ -0,0 +1,31 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { readTools } from "./tools.js";
+import { version } from "./version.js";
+/**
+ * Build the Uptimizr MCP server: a read-only `McpServer` whose tools each wrap
+ * one collector query endpoint via the injected `CollectorClient`. The server
+ * holds no business logic — it forwards validated arguments and returns the
+ * collector's JSON (ADR 0005 / ADR 0017).
+ */
+export function createMcpServer(client) {
+    const server = new McpServer({ name: "uptimizr-mcp", version });
+    for (const tool of readTools) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, async (args) => {
+            try {
+                const { path, params } = tool.buildRequest(args);
+                const data = await client.get(path, params);
+                return { content: [{ type: "text", text: JSON.stringify(data) }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+            }
+        });
+    }
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,MAAuB;IACrD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC,CAAC;IAEhE,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;YACE,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,IAAI,CAAC;gBACH,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,IAA+B,CAAC,CAAC;gBAC5E,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBAC5C,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YACrE,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YACnF,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { QueryParams } from "./client.js";
+/** A resolved read request: the collector path and its query parameters. */
+export interface ReadToolRequest {
+    path: string;
+    params: QueryParams;
+}
+/**
+ * A read-only tool definition. `inputSchema` is a Zod raw shape the MCP runtime
+ * uses to validate arguments; `buildRequest` maps validated arguments to a
+ * `GET` against the collector. Definitions are pure and unit-testable without a
+ * live collector.
+ */
+export interface ReadTool {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    buildRequest: (args: Record<string, unknown>) => ReadToolRequest;
+}
+/**
+ * The catalog of read-only tools. Each wraps one documented collector query
+ * endpoint (docs/integration.md §Query). There are intentionally **no**
+ * ingestion, mutation, or raw per-session event tools — the surface is
+ * aggregate, read-only, and privacy-preserving (ADR 0003 / ADR 0017).
+ */
+export declare const readTools: readonly ReadTool[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,eAAe,CAAC;CAClE;AAiCD;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,QAAQ,EAsKxC,CAAC"}

package/dist/tools.js

@@ -0,0 +1,203 @@
+import { z } from "zod";
+const num = (v) => (typeof v === "number" ? v : undefined);
+const str = (v) => (typeof v === "string" ? v : undefined);
+// Shared, reusable input fields (all optional unless a tool needs otherwise).
+const since = z.number().int().optional().describe("Start of the time range, epoch milliseconds.");
+const until = z.number().int().optional().describe("End of the time range, epoch milliseconds.");
+const bins = z.number().int().positive().max(500).optional().describe("Grid resolution per axis.");
+const limit = z.number().int().positive().max(1000).optional().describe("Maximum rows to return.");
+const scene = z.string().optional().describe("Restrict to one developer-assigned scene id.");
+const session = z.string().optional().describe("Scope the aggregate to a single session id.");
+const cellSize = z.number().positive().max(1000).optional().describe("Voxel size in world units.");
+const interval = z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Time-series bucket width, seconds.");
+const eventType = z
+    .string()
+    .optional()
+    .describe("Restrict to a single event type, e.g. pointer_click.");
+const source = z
+    .enum(["mouse", "touch", "stylus", "pen", "xr-controller", "hand", "gaze", "transient", "other"])
+    .optional()
+    .describe("Restrict a pointer/world heatmap to one input source.");
+/** Build the common `{ since, until }` range params from validated args. */
+function range(args) {
+    return { since: num(args.since), until: num(args.until) };
+}
+/**
+ * The catalog of read-only tools. Each wraps one documented collector query
+ * endpoint (docs/integration.md §Query). There are intentionally **no**
+ * ingestion, mutation, or raw per-session event tools — the surface is
+ * aggregate, read-only, and privacy-preserving (ADR 0003 / ADR 0017).
+ */
+export const readTools = [
+    {
+        name: "list_sessions",
+        title: "List recent sessions",
+        description: "Recent sessions with id, visitor, event count, and start/end times.",
+        inputSchema: { since, until, limit },
+        buildRequest: (args) => ({
+            path: "api/v1/sessions",
+            params: { ...range(args), limit: num(args.limit) },
+        }),
+    },
+    {
+        name: "pointer_heatmap",
+        title: "2D pointer heatmap",
+        description: "Binned 2D pointer-position heatmap (screen-normalized).",
+        inputSchema: { since, until, bins, scene, source, session },
+        buildRequest: (args) => ({
+            path: "api/v1/heatmaps/pointer",
+            params: {
+                ...range(args),
+                bins: num(args.bins),
+                scene: str(args.scene),
+                source: str(args.source),
+                session: str(args.session),
+            },
+        }),
+    },
+    {
+        name: "world_heatmap",
+        title: "3D world-space pointer heatmap",
+        description: "Voxelized world-space pointer heatmap.",
+        inputSchema: { since, until, cellSize, limit, scene, source },
+        buildRequest: (args) => ({
+            path: "api/v1/heatmaps/world",
+            params: {
+                ...range(args),
+                cellSize: num(args.cellSize),
+                limit: num(args.limit),
+                scene: str(args.scene),
+                source: str(args.source),
+            },
+        }),
+    },
+    {
+        name: "camera_heatmap",
+        title: "View-direction heatmap",
+        description: "Camera view-direction distribution as spherical bins.",
+        inputSchema: { since, until, bins, scene, session },
+        buildRequest: (args) => ({
+            path: "api/v1/heatmaps/camera",
+            params: {
+                ...range(args),
+                bins: num(args.bins),
+                scene: str(args.scene),
+                session: str(args.session),
+            },
+        }),
+    },
+    {
+        name: "click_rays",
+        title: "View-gated click rays",
+        description: "Clicks ASOF-joined to their nearest camera sample, per voxel and clicked mesh.",
+        inputSchema: { since, until, cellSize, limit, scene, source, session },
+        buildRequest: (args) => ({
+            path: "api/v1/heatmaps/click-rays",
+            params: {
+                ...range(args),
+                cellSize: num(args.cellSize),
+                limit: num(args.limit),
+                scene: str(args.scene),
+                source: str(args.source),
+                session: str(args.session),
+            },
+        }),
+    },
+    {
+        name: "flow_links",
+        title: "Gaze→mesh flow links",
+        description: "Aggregate links from camera-direction bins to clicked meshes.",
+        inputSchema: { since, until, bins, limit, scene, session },
+        buildRequest: (args) => ({
+            path: "api/v1/heatmaps/flow",
+            params: {
+                ...range(args),
+                bins: num(args.bins),
+                limit: num(args.limit),
+                scene: str(args.scene),
+                session: str(args.session),
+            },
+        }),
+    },
+    {
+        name: "top_meshes",
+        title: "Most-interacted meshes",
+        description: "Meshes ranked by interaction count.",
+        inputSchema: { since, until, limit, session },
+        buildRequest: (args) => ({
+            path: "api/v1/meshes/top",
+            params: { ...range(args), limit: num(args.limit), session: str(args.session) },
+        }),
+    },
+    {
+        name: "perf_summary",
+        title: "Rendering performance summary",
+        description: "Sample count and avg/min/p50 FPS over the range.",
+        inputSchema: { since, until, session },
+        buildRequest: (args) => ({
+            path: "api/v1/perf",
+            params: { ...range(args), session: str(args.session) },
+        }),
+    },
+    {
+        name: "list_scenes",
+        title: "List active scenes",
+        description: "Distinct developer-assigned scenes with activity.",
+        inputSchema: { since, until, limit },
+        buildRequest: (args) => ({
+            path: "api/v1/scenes",
+            params: { ...range(args), limit: num(args.limit) },
+        }),
+    },
+    {
+        name: "timeseries",
+        title: "Event-volume time series",
+        description: "Event-volume buckets over time, with average FPS per bucket.",
+        inputSchema: { since, until, interval, scene, type: eventType },
+        buildRequest: (args) => ({
+            path: "api/v1/timeseries",
+            params: {
+                ...range(args),
+                interval: num(args.interval),
+                scene: str(args.scene),
+                type: str(args.type),
+            },
+        }),
+    },
+    {
+        name: "event_counts",
+        title: "Per-event-type counts",
+        description: "Counts per event type over the range (scene-health panel).",
+        inputSchema: { since, until, scene },
+        buildRequest: (args) => ({
+            path: "api/v1/event-counts",
+            params: { ...range(args), scene: str(args.scene) },
+        }),
+    },
+    {
+        name: "session_meta",
+        title: "Session descriptor",
+        description: "Coarse descriptor for one session (device/scene/user). No raw event stream.",
+        inputSchema: { sessionId: z.string().min(1).describe("The session id to describe.") },
+        buildRequest: (args) => ({
+            path: `api/v1/sessions/${encodeURIComponent(str(args.sessionId) ?? "")}/meta`,
+            params: {},
+        }),
+    },
+    {
+        name: "scene_representation",
+        title: "Scene representation",
+        description: "Registered proxy geometry (bounds/meshes) for one scene, if any.",
+        inputSchema: { sceneId: z.string().min(1).describe("The scene id to fetch.") },
+        buildRequest: (args) => ({
+            path: `api/v1/scenes/${encodeURIComponent(str(args.sceneId) ?? "")}/representation`,
+            params: {},
+        }),
+    },
+];
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+/** Package version, stamped into the MCP server identity. */
+export declare const version = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,3 @@
+/** Package version, stamped into the MCP server identity. */
+export const version = "0.1.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/llms.txt

@@ -0,0 +1,18 @@
+# @uptimizr/mcp
+
+> A read-only Model Context Protocol server over an Uptimizr collector's query API. Lets an agent
+> query a consumer's own 3D analytics; thin wrapper, GET-only, no data egress.
+
+## Docs
+
+- [Package reference](./README.md): run instructions, MCP client config, the full tool table, programmatic use.
+- [Agent guide](./AGENTS.md): rules and tool catalog for AI agents.
+- [Integration & API reference](https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md): the underlying query endpoints.
+- [Architecture Decision Records](https://github.com/RaananW/Uptimizr/tree/main/docs/adr): privacy model (0003), thin backends (0005), consumer-facing agents (0017).
+
+## Key exports
+
+- `createMcpServer(client)` — build the read-only MCP server.
+- `createCollectorClient(config)` — the thin GET-only collector client.
+- `readMcpConfig()` — read `UPTIMIZR_COLLECTOR_URL` + `UPTIMIZR_API_KEY` from the environment.
+- `readTools` — the read-only tool catalog (one entry per query endpoint).

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@uptimizr/mcp",
+  "version": "0.1.0",
+  "description": "Read-only Model Context Protocol (MCP) server over an Uptimizr collector's query API — let an agent ask questions of your own 3D analytics, on your own infrastructure.",
+  "keywords": [
+    "uptimizr",
+    "analytics",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agent",
+    "3d"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RaananW/Uptimizr.git",
+    "directory": "oss/packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/RaananW/Uptimizr/issues"
+  },
+  "homepage": "https://github.com/RaananW/Uptimizr/tree/main/oss/packages/mcp#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "uptimizr-mcp": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "AGENTS.md",
+    "llms.txt"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.21",
+    "tsx": "^4.22.4",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "serve": "tsx src/bin.ts",
+    "start": "node dist/bin.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}