@practicemakes/mcp 26.710.3 → 26.823.1

package/README.md

@@ -44,7 +44,7 @@ yarn workspace @practicemakes/mcp smoke        # end-to-end check against prod
 ```sh
 claude mcp add practicemakes \
   --env FIREBASE_REFRESH_TOKEN=... \
-  -- node /Users/johnfonte/IdeaProjects/common-frontend/packages/mcp/dist/index.js
+  -- node "$(pwd)/packages/mcp/dist/index.js"
 ```
 
 ## Publish
@@ -70,6 +70,24 @@ yarn workspace @practicemakes/mcp publish   # runs prepublishOnly (clean + build
 | `list_workflows` | Your Planner workflows |
 | `get_workflow` | One workflow, hydrated with run state |
 | `get_billing_config` | Billing/entitlement config for your org |
+| `list_servers` | Monitored servers + both identifiers the tools below need |
+| `get_server` | One server's config, including its maintenance windows |
+| `list_server_statuses` | Live status of **all** your servers (is anything down now) |
+| `get_server_uptime` | Uptime % over the last 1–168 hours, from raw heartbeats |
+| `get_server_uptime_daily` | Per-day uptime history beyond heartbeat retention |
+| `list_server_incidents` | Outage history for one server, planned vs unplanned |
+
+### Server identifiers
+
+The monitoring tools take **two different, non-interchangeable identifiers**, and passing the wrong
+one returns a 404 that reads like a missing server. `list_servers` returns both:
+
+| Identifier | Used by | Route family |
+|---|---|---|
+| `serverShortLink` | `get_server_uptime`, `get_server_uptime_daily` | `/api/public/...` (unauthenticated) |
+| `serverId` | `get_server`, `list_server_incidents` | `/api/server/...` (authenticated, org-scoped) |
+
+Neither is a UUID — `serverId` is the operator-assigned id (e.g. `web-01`).
 
 ## Roadmap
 

package/dist/index.js

@@ -8,6 +8,7 @@ import { registerOrganizationTools } from "./tools/organizations.js";
 import { registerProfileTools } from "./tools/profiles.js";
 import { registerPlannerTools } from "./tools/planner.js";
 import { registerBillingTools } from "./tools/billing.js";
+import { registerMonitorTools } from "./tools/monitor.js";
 async function main() {
     const config = loadConfig();
     const tokens = new TokenManager(config);
@@ -20,6 +21,7 @@ async function main() {
     registerProfileTools(server, client);
     registerPlannerTools(server, client);
     registerBillingTools(server, client);
+    registerMonitorTools(server, client);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // stdout is the MCP transport; log to stderr only.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAEvD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,yBAAyB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,mDAAmD;IACnD,OAAO,CAAC,KAAK,CAAC,qCAAqC,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC;AAC3E,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAClE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAEvD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,yBAAyB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,mDAAmD;IACnD,OAAO,CAAC,KAAK,CAAC,qCAAqC,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC;AAC3E,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAClE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools/monitor.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { PmClient } from "../pmClient.js";
+export declare function registerMonitorTools(server: McpServer, client: PmClient): void;

package/dist/tools/monitor.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { runTool } from "./shared.js";
+/**
+ * Server-monitoring tools.
+ *
+ * Two identifiers are in play and they are NOT interchangeable — passing one where the other
+ * belongs yields a 404 that looks like a missing server:
+ *
+ *   - `serverShortLink` keys the unauthenticated `/api/public/...` uptime routes.
+ *   - `serverId` keys the authenticated, org-scoped `/api/server/...` routes. It is the
+ *     operator-assigned identifier (e.g. "web-01"), not the row's UUID.
+ *
+ * `list_servers` returns both fields, so it is the way to resolve either one.
+ */
+/** The backend caps a daily-uptime range at 366 days; 30 is the useful default window. */
+const DEFAULT_DAILY_DAYS = 30;
+/** Mirrors ServerController.MAX_INCIDENT_PAGE_SIZE — the backend silently caps above this. */
+const MAX_INCIDENT_PAGE_SIZE = 100;
+function isoDate(date) {
+    return date.toISOString().slice(0, 10);
+}
+export function registerMonitorTools(server, client) {
+    server.registerTool("list_servers", {
+        title: "List monitored servers",
+        description: "Every server your organization monitors, with its configuration. Start here: the response carries both identifiers the other monitoring tools need — `serverId` (the operator-assigned id used by get_server and list_server_incidents) and `serverShortLink` (used by the uptime tools).",
+        inputSchema: {},
+    }, async () => runTool(() => client.get("/api/server")));
+    server.registerTool("get_server", {
+        title: "Get server",
+        description: "One monitored server's full configuration, including its heartbeat interval and maintenance-window schedule (which determines whether an outage is recorded as planned). Keyed by `serverId` — the operator-assigned identifier from list_servers, NOT a UUID and NOT the serverShortLink.",
+        inputSchema: {
+            serverId: z.string().describe("Operator-assigned server id from list_servers, e.g. 'web-01'."),
+        },
+    }, async ({ serverId }) => runTool(() => client.get(`/api/server/${encodeURIComponent(serverId)}`)));
+    server.registerTool("list_server_statuses", {
+        title: "List server statuses",
+        description: "Current live status (online/offline, last heartbeat, last speedtest) for ALL servers in your organization — this returns a list, it does not take a server identifier. Use it to answer 'is anything down right now'.",
+        inputSchema: {},
+    }, async () => runTool(() => client.get("/api/server/status")));
+    server.registerTool("get_server_uptime", {
+        title: "Get server uptime",
+        description: "Uptime percentage over a recent window, computed from raw heartbeats (retained ~31 days). Keyed by `serverShortLink` from list_servers — NOT the serverId the /api/server tools take. For history older than the heartbeat retention, use get_server_uptime_daily.",
+        inputSchema: {
+            serverShortLink: z.string().describe("Server short link from list_servers (public uptime identifier)."),
+            hours: z
+                .number()
+                .int()
+                .min(1)
+                .max(168)
+                .default(24)
+                .describe("Window in hours. Values outside 1-168 are rejected before the request is sent."),
+        },
+    }, async ({ serverShortLink, hours }) => runTool(() => client.get(`/api/public/server/${encodeURIComponent(serverShortLink)}/uptime?hours=${hours}`)));
+    server.registerTool("get_server_uptime_daily", {
+        title: "Get daily uptime history",
+        description: "Per-day uptime rollups: uptime percent, online/downtime/planned-downtime seconds and incident count for each day. This is the long-term history — it survives past the ~31-day raw heartbeat retention that get_server_uptime is limited to. Keyed by `serverShortLink`, NOT serverId. Defaults to the last 30 days; the backend rejects ranges wider than 366 days.",
+        inputSchema: {
+            serverShortLink: z.string().describe("Server short link from list_servers (public uptime identifier)."),
+            from: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .optional()
+                .describe("Start date, ISO YYYY-MM-DD. Defaults to 30 days ago."),
+            to: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .optional()
+                .describe("End date, ISO YYYY-MM-DD. Defaults to today."),
+        },
+    }, async ({ serverShortLink, from, to }) => runTool(() => {
+        const today = new Date();
+        const resolvedTo = to ?? isoDate(today);
+        const resolvedFrom = from ?? isoDate(new Date(today.getTime() - DEFAULT_DAILY_DAYS * 24 * 60 * 60 * 1000));
+        const query = new URLSearchParams({ from: resolvedFrom, to: resolvedTo });
+        return client.get(`/api/public/server/${encodeURIComponent(serverShortLink)}/uptime/daily?${query}`);
+    }));
+    server.registerTool("list_server_incidents", {
+        title: "List server incidents",
+        description: "Outage history for one server, newest first: when each outage started and ended, how long it lasted, and whether it was `planned` (started inside a configured maintenance window) or unplanned. An incident with `ongoing: true` has no end yet — the server is down right now. Keyed by `serverId` from list_servers, NOT the serverShortLink.",
+        inputSchema: {
+            serverId: z.string().describe("Operator-assigned server id from list_servers, e.g. 'web-01'."),
+            page: z.number().int().min(0).default(0).describe("Zero-based page number."),
+            size: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_INCIDENT_PAGE_SIZE)
+                .default(50)
+                .describe(`Incidents per page, max ${MAX_INCIDENT_PAGE_SIZE}.`),
+        },
+    }, async ({ serverId, page, size }) => runTool(() => {
+        const query = new URLSearchParams({ page: String(page), size: String(size) });
+        return client.get(`/api/server/${encodeURIComponent(serverId)}/incidents?${query}`);
+    }));
+}
+//# sourceMappingURL=monitor.js.map

package/dist/tools/monitor.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@practicemakes/mcp",
-  "version": "26.710.3",
+  "version": "26.823.1",
   "description": "MCP server exposing PracticeMakes prod data (read-only) to Claude, authenticated as the calling user's own Firebase identity.",
   "license": "UNLICENSED",
   "type": "module",
@@ -23,16 +23,20 @@
     "start": "node dist/index.js",
     "smoke": "node --env-file=.env dist/smoke.js",
     "login": "node --env-file=.env dist/login.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ci": "vitest run",
     "prepublishOnly": "yarn clean && yarn build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",
     "rimraf": "4.1.2",
-    "typescript": "6.0.3"
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
   },
   "engines": {
     "node": ">=20.6.0"