rhombus-node-mcp 0.1.46 → 0.1.47

package/dist/analytics/amplitude.js

@@ -0,0 +1,74 @@
+import { flush, init, track } from "@amplitude/analytics-node";
+import { logger } from "../logger.js";
+/**
+ * Amplitude analytics for the Rhombus MCP server.
+ *
+ * Analytics are **opt-in**: nothing is sent unless `AMPLITUDE_API_KEY` is set.
+ * This keeps the published npm package / self-hosted deployments silent by
+ * default and confines telemetry to Rhombus-operated deployments that supply
+ * the key. Every function here is defensive — analytics must never throw into,
+ * slow down, or otherwise affect the request path.
+ */
+let enabled = false;
+/**
+ * Initialize the Amplitude client once at process start. No-op (and leaves
+ * analytics disabled) when `AMPLITUDE_API_KEY` is unset or init fails.
+ */
+export function initAnalytics() {
+    const apiKey = process.env.AMPLITUDE_API_KEY;
+    if (!apiKey) {
+        logger.info("📊 Amplitude analytics disabled (AMPLITUDE_API_KEY not set)");
+        return;
+    }
+    const serverZone = (process.env.AMPLITUDE_SERVER_ZONE ?? "US").toUpperCase() === "EU" ? "EU" : "US";
+    try {
+        init(apiKey, {
+            serverZone,
+            // Batch in the background; the request path never waits on Amplitude.
+            flushIntervalMillis: 10_000,
+            flushQueueSize: 50,
+        });
+        enabled = true;
+        logger.info(`📊 Amplitude analytics enabled (zone=${serverZone})`);
+    }
+    catch (error) {
+        logger.warn(`📊 Failed to initialize Amplitude analytics: ${String(error)}`);
+    }
+}
+/** Whether analytics are active (key present and init succeeded). */
+export function analyticsEnabled() {
+    return enabled;
+}
+/**
+ * Record an analytics event. Fire-and-forget and fully guarded — callers do
+ * not await this and a failure here is logged at debug level only.
+ */
+export function trackEvent(eventType, eventProperties, identity = {}) {
+    if (!enabled)
+        return;
+    try {
+        const { userId, orgUuid, deviceId } = identity;
+        track(eventType, eventProperties, {
+            // Amplitude requires a user_id or a device_id. Prefer the stable user id;
+            // fall back to a device id (session id) and finally a constant so the
+            // event is still accepted for stateless (api-key / oauth) callers.
+            user_id: userId,
+            ...(userId ? {} : { device_id: deviceId || "mcp-stateless" }),
+            ...(orgUuid ? { groups: { org: orgUuid } } : {}),
+        });
+    }
+    catch (error) {
+        logger.debug(`📊 trackEvent("${eventType}") failed: ${String(error)}`);
+    }
+}
+/** Flush any buffered events. Call on graceful shutdown. */
+export async function flushAnalytics() {
+    if (!enabled)
+        return;
+    try {
+        await flush().promise;
+    }
+    catch (error) {
+        logger.debug(`📊 flushAnalytics failed: ${String(error)}`);
+    }
+}

package/dist/analytics/analyticsProxy.js

@@ -0,0 +1,97 @@
+import { resolveSessionIdentity } from "../api/get-accessible-apps.js";
+import { logger } from "../logger.js";
+import { extractFromToolExtra } from "../util.js";
+import { analyticsEnabled, trackEvent } from "./amplitude.js";
+const TOOL_CALLED_EVENT = "MCP Tool Called";
+/**
+ * Resolve identity (cached `getCurrentUser` — no extra API call for session
+ * callers) and emit the tool-call event. Fire-and-forget: never awaited by the
+ * handler and fully guarded so analytics cannot affect the response.
+ */
+async function emitToolCall(toolName, 
+// biome-ignore lint/suspicious/noExplicitAny: dynamic tool args
+args, extra, success, durationMs, errorMessage) {
+    try {
+        const { sessionId } = extractFromToolExtra(extra);
+        const identity = sessionId ? await resolveSessionIdentity(sessionId) : null;
+        trackEvent(TOOL_CALLED_EVENT, {
+            tool_name: toolName,
+            success,
+            duration_ms: durationMs,
+            // Record which arguments were supplied, never their values (avoid PII).
+            arg_keys: args && typeof args === "object" ? Object.keys(args) : [],
+            transport: process.env.TRANSPORT_TYPE ?? "stdio",
+            ...(errorMessage ? { error_message: errorMessage } : {}),
+        }, {
+            userId: identity?.userId,
+            orgUuid: identity?.orgUuid,
+            deviceId: sessionId,
+        });
+    }
+    catch (error) {
+        logger.debug(`📊 emitToolCall("${toolName}") failed: ${String(error)}`);
+    }
+}
+/** Wrap a tool handler so each invocation is timed and tracked. */
+function wrapHandler(toolName, handler) {
+    return async (args, extra) => {
+        const start = Date.now();
+        let success = true;
+        let errorMessage;
+        try {
+            const result = await handler(args, extra);
+            // A tool can signal failure via `isError` rather than throwing.
+            if (result && typeof result === "object" && result.isError) {
+                success = false;
+            }
+            return result;
+        }
+        catch (error) {
+            success = false;
+            errorMessage = error instanceof Error ? error.message : String(error);
+            throw error;
+        }
+        finally {
+            void emitToolCall(toolName, args, extra, success, Date.now() - start, errorMessage);
+        }
+    };
+}
+/**
+ * Returns a Proxy over an `McpServer` that wraps every tool handler to emit a
+ * `"${TOOL_CALLED_EVENT}"` analytics event. Both registration methods are
+ * intercepted: `registerTool` (most tools) and the legacy `tool` (a handful,
+ * including the filtering-blacklisted ones), so coverage is complete.
+ *
+ * When analytics are disabled the proxy returns the server untouched, so there
+ * is zero overhead on deployments without `AMPLITUDE_API_KEY`.
+ *
+ * Compose it *inside* the filtering proxy — `createFilteringProxy(createAnalyticsProxy(server))`
+ * — so handlers are timed after filtering strips `includeFields`/`filterBy`,
+ * keeping those synthetic args out of `arg_keys`.
+ */
+export function createAnalyticsProxy(server) {
+    if (!analyticsEnabled())
+        return server;
+    return new Proxy(server, {
+        get(target, prop, receiver) {
+            if (prop === "registerTool") {
+                // biome-ignore lint/suspicious/noExplicitAny: proxy intercept
+                return (name, config, handler) => target.registerTool(name, config, wrapHandler(name, handler));
+            }
+            if (prop === "tool") {
+                // Legacy signature: tool(name, [description], [paramsSchema], [annotations], handler).
+                // The handler is always the final argument.
+                // biome-ignore lint/suspicious/noExplicitAny: proxy intercept
+                return (...toolArgs) => {
+                    const name = toolArgs[0];
+                    const lastIdx = toolArgs.length - 1;
+                    if (typeof toolArgs[lastIdx] === "function") {
+                        toolArgs[lastIdx] = wrapHandler(name, toolArgs[lastIdx]);
+                    }
+                    return target.tool(...toolArgs);
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}

package/dist/api/get-accessible-apps.js

@@ -1,16 +1,13 @@
 import { logger } from "../logger.js";
 import { postApi } from "../network/network.js";
 /**
- * Fetches `user.accessibleRhombusApps` from getCurrentUser for the given session.
- * Successful results are cached in-memory for the lifetime of the session;
- * failures are NOT cached so transient errors don't poison the session.
- * Returns null on error or missing session; callers should fall back to a
- * permissive default.
+ * Single cached `getCurrentUser` fetch per session. Both `resolveAccessibleApps`
+ * and `resolveSessionIdentity` read from this cache, so identity for analytics
+ * costs no extra API call. Successful results are cached for the lifetime of
+ * the session; failures are NOT cached so transient errors don't poison it.
  */
 const cache = new Map();
-export async function resolveAccessibleApps(sessionId) {
-    if (!sessionId)
-        return null;
+async function fetchSession(sessionId) {
     const cached = cache.get(sessionId);
     if (cached !== undefined)
         return cached;
@@ -24,16 +21,43 @@ export async function resolveAccessibleApps(sessionId) {
             logger.warn(`resolveAccessibleApps: getCurrentUser failed for session ${sessionId}`);
             return null;
         }
-        const apps = (res.user?.accessibleRhombusApps ?? []).filter((a) => a !== null && a !== undefined);
-        cache.set(sessionId, apps);
+        const user = res.user;
+        const apps = (user?.accessibleRhombusApps ?? []).filter((a) => a !== null && a !== undefined);
+        const identity = {
+            userId: user?.uuid ?? user?.rhombusUserUuid ?? undefined,
+            orgUuid: user?.orgUuid ?? undefined,
+            email: user?.email ?? undefined,
+        };
+        const entry = { apps, identity };
+        cache.set(sessionId, entry);
         logger.info(`resolveAccessibleApps: session ${sessionId} -> [${apps.join(", ")}]`);
-        return apps;
+        return entry;
     }
     catch (e) {
         logger.warn(`resolveAccessibleApps: error for session ${sessionId}: ${String(e)}`);
         return null;
     }
 }
+/**
+ * Fetches `user.accessibleRhombusApps` from getCurrentUser for the given session.
+ * Returns null on error or missing session; callers should fall back to a
+ * permissive default.
+ */
+export async function resolveAccessibleApps(sessionId) {
+    if (!sessionId)
+        return null;
+    return (await fetchSession(sessionId))?.apps ?? null;
+}
+/**
+ * Fetches identity (user uuid, org uuid, email) from getCurrentUser for the
+ * given session, reusing the same cached response as `resolveAccessibleApps`.
+ * Returns null on error or missing session.
+ */
+export async function resolveSessionIdentity(sessionId) {
+    if (!sessionId)
+        return null;
+    return (await fetchSession(sessionId))?.identity ?? null;
+}
 /** Drop the cached entry — call when a session ends. */
 export function clearAccessibleAppsCache(sessionId) {
     cache.delete(sessionId);

package/dist/createServer.js

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import path from "path";
+import { createAnalyticsProxy } from "./analytics/analyticsProxy.js";
 import { resolveAccessibleApps } from "./api/get-accessible-apps.js";
 import { logger } from "./logger.js";
 import { createFilteringProxy } from "./util.js";
@@ -105,7 +106,10 @@ export default async function createServer({ sessionId } = {}) {
     const toolsToRegister = pickToolsForSession(apps);
     logDevToolRegistration(sessionId, apps, toolsToRegister);
     logger.info(`🔒 Session ${sessionId ?? "(none)"}: apps=[${apps?.join(", ") ?? "unknown"}] — registering ${toolsToRegister.length} tools`);
-    const filteredServer = createFilteringProxy(server, new Set(["time-tool", "count-tool", "time-conversion-tool"]));
+    // Analytics wraps every tool handler; filtering wraps on top so handlers are
+    // timed after includeFields/filterBy are stripped (keeping them out of
+    // arg_keys). Both are no-ops when their respective features are disabled.
+    const filteredServer = createFilteringProxy(createAnalyticsProxy(server), new Set(["time-tool", "count-tool", "time-conversion-tool"]));
     for (const tool of toolsToRegister) {
         try {
             await tool.create(filteredServer);

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import "dotenv/config";
+import { flushAnalytics, initAnalytics } from "./analytics/amplitude.js";
 import { serverInit } from "./createServer.js";
 import { logger } from "./logger.js";
 import stdioTransport from "./transports/stdio.js";
@@ -12,6 +13,7 @@ async function main() {
         logger.info(`🔑 Using API_KEY: ${RHOMBUS_API_KEY}`);
     }
     logger.info("🌐 Using server url", serverUrl);
+    initAnalytics();
     await serverInit();
     if (TRANSPORT_TYPE === "stdio") {
         await stdioTransport();
@@ -23,6 +25,13 @@ async function main() {
         throw new Error(`Invalid transport type: ${TRANSPORT_TYPE}`);
     }
 }
+// Flush buffered analytics on graceful shutdown so in-flight events aren't lost.
+for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, async () => {
+        await flushAnalytics();
+        process.exit(0);
+    });
+}
 main().catch(error => {
     console.error("Fatal error in main():", error);
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rhombus-node-mcp",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "description": "MCP server for Rhombus API",
   "keywords": [
     "ai",
@@ -49,6 +49,7 @@
     "dist"
   ],
   "dependencies": {
+    "@amplitude/analytics-node": "^1.5.60",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "axios": "^1.11.0",
     "cheerio": "^1.1.2",