@adrata/adrata-mcp 1.0.3 → 1.0.7

package/analytics.js

@@ -119,7 +119,6 @@ function ensureDir() {
 }
 
 function readLocalAnalytics() {
-  ensureDir();
   if (!existsSync(ANALYTICS_FILE)) {
     return { events: [], sessions: [] };
   }
@@ -278,6 +277,69 @@ export function trackConversion(apiFn, auth, fromTier, toTier, trigger) {
 /** @type {{ startTime: number, toolsUsed: Set<string>, invocationCount: number } | null} */
 let currentSession = null;
 
+// ---------------------------------------------------------------------------
+// Analytics wrapper coverage
+// ---------------------------------------------------------------------------
+// The analytics counter is a monkey-patch on `server.tool`, so it can only see
+// tools registered AFTER it is installed. That makes its own coverage a fact
+// worth reporting: a zero from an instrumented surface and a zero from an
+// uninstrumented one are different answers, and until 2026-08-29 they were
+// rendered identically. `countedToolNames` is what the wrapper actually
+// wrapped; `get_mcp_analytics` compares it against what the server registered.
+
+/**
+ * Wrapper state belongs to one McpServer instance. Hosted HTTP creates a fresh
+ * server for every protocol session, so a module-global installed flag would
+ * wrap the first client and silently skip every client after it.
+ *
+ * @type {WeakMap<object, { countedToolNames: Set<string> }>}
+ */
+let analyticsWrapperStates = new WeakMap();
+
+/**
+ * How much of the registered tool surface the invocation counter can see.
+ *
+ * @param {object} [server] - McpServer instance, for the registered-tool total
+ * @returns {{installed: boolean, tools_counted: number, tools_registered: number|null, complete: boolean|null, uncounted_note: string|undefined}}
+ */
+export function getAnalyticsCoverage(server) {
+  const registered = registeredToolCount(server);
+  const wrapperState = server && typeof server === 'object'
+    ? analyticsWrapperStates.get(server)
+    : undefined;
+  const counted = wrapperState?.countedToolNames.size ?? 0;
+  const complete = registered === null ? null : counted >= registered;
+  return {
+    installed: wrapperState !== undefined,
+    tools_counted: counted,
+    tools_registered: registered,
+    complete,
+    uncounted_note:
+      complete === false
+        ? `${registered - counted} of ${registered} registered tools were registered before the `
+          + 'analytics wrapper was installed, so their invocations are NOT counted. '
+          + 'Treat tool_invocations as a lower bound, not a measurement.'
+        : undefined,
+  };
+}
+
+/** Best-effort read of the SDK's registered-tool map. Returns null if unavailable. */
+function registeredToolCount(server) {
+  try {
+    const registry = server?._registeredTools;
+    if (registry && typeof registry === 'object') return Object.keys(registry).length;
+  } catch {
+    // The SDK internal is not a contract. An unknown total is reported as
+    // null, never as a number we did not measure.
+  }
+  return null;
+}
+
+/** Test-only: forget that the wrapper was installed. */
+export function __resetAnalyticsWrapperForTests() {
+  analyticsWrapperStates = new WeakMap();
+}
+
 /**
  * Start a new analytics session.
  *
@@ -388,24 +450,43 @@ const SEARCH_TOOLS = {
  * invocation. This builds on top of the existing event logging in memory.js
  * by adding richer analytics (search classification, tier gates, sessions).
  *
- * Must be applied AFTER the event logging wrapper from memory.js.
+ * Must be applied AFTER the event logging wrapper from memory.js, and BEFORE
+ * the first `server.tool(...)` call. Monkey-patching `server.tool` can only
+ * ever reach FUTURE registrations, so installing it late does not degrade the
+ * count — it silently zeroes it. Measured 2026-08-29: installed from
+ * `registerAnalytics` ~1975 lines after the first registration, it covered 27
+ * of 254 tools and `get_mcp_analytics` reported `tool_invocations.total: 0`
+ * with no indication that 89% of the surface was never instrumented.
+ *
+ * Idempotent: calling it twice installs one wrapper, so `registerAnalytics`
+ * remains safe to call after server.js has already installed it early.
+ *
+ * `auth` may be an AUTH object or a zero-argument getter. Prefer the getter:
+ * server.js reassigns AUTH on `connect_workspace`, and an object captured at
+ * install time would report the pre-connection tier forever.
  *
  * @param {object} server - McpServer instance
  * @param {Function} apiFn - The api() helper
- * @param {object} auth - AUTH context
+ * @param {object|Function} auth - AUTH context, or a getter returning it
  * @param {Function} checkToolAccessFn - checkToolAccess from auth.js
  */
 export function wrapWithAnalytics(server, apiFn, auth, checkToolAccessFn) {
   if (!TELEMETRY_ENABLED) return;
+  if (analyticsWrapperStates.has(server)) return;
+  const wrapperState = { countedToolNames: new Set() };
+  analyticsWrapperStates.set(server, wrapperState);
 
+  const resolveAuth = () => (typeof auth === 'function' ? auth() : auth);
   const _analyticsWrappedTool = server.tool.bind(server);
 
   server.tool = function analyticsTool(name, ...rest) {
     const handler = rest[rest.length - 1];
+    wrapperState.countedToolNames.add(name);
     rest[rest.length - 1] = async function analyticsHandler(...handlerArgs) {
       const start = Date.now();
       let success = true;
       let errorMsg = null;
+      const auth = resolveAuth();
 
       // Track tier gate if access was denied (check without modifying flow)
       const access = checkToolAccessFn(name, auth);
@@ -574,16 +655,18 @@ function parsePeriod(period) {
  * @param {object} opts - { z, api, auth, ok, checkToolAccess }
  */
 export function registerAnalytics(server, { z, api, auth, ok, checkToolAccess }) {
+  const resolveAuth = () => (typeof auth === 'function' ? auth() : auth);
+
   // Wire up the analytics wrapper on all future tool registrations
   wrapWithAnalytics(server, api, auth, checkToolAccess);
 
   // Start a session
-  startSession(api, auth);
+  startSession(api, resolveAuth());
 
   // Graceful shutdown: end session on process exit
-  process.on('beforeExit', () => endSession(api, auth));
-  process.on('SIGINT', () => { endSession(api, auth); process.exit(0); });
-  process.on('SIGTERM', () => { endSession(api, auth); process.exit(0); });
+  process.on('beforeExit', () => endSession(api, resolveAuth()));
+  process.on('SIGINT', () => { endSession(api, resolveAuth()); process.exit(0); });
+  process.on('SIGTERM', () => { endSession(api, resolveAuth()); process.exit(0); });
 
   // ----- get_mcp_analytics -----
   server.tool('get_mcp_analytics',
@@ -594,27 +677,65 @@ export function registerAnalytics(server, { z, api, auth, ok, checkToolAccess })
     async (args) => {
       const period = args.period || '7d';
 
-      if (auth.authenticated) {
-        // The MCP surface exposes no dedicated analytics route. The
-        // subscription endpoint carries the server-side usage rollup
-        // (usage.tool_invocations_30d) alongside plan/trial state.
+      // Coverage travels with every answer. `tool_invocations.total: 0` from a
+      // fully instrumented surface means nobody called anything; the same zero
+      // from a surface the wrapper never reached means nothing was measured.
+      // Reporting the second as the first is how this counter read 0 for 227
+      // of 254 tools without anyone noticing.
+      const coverage = getAnalyticsCoverage(server);
+
+      if (resolveAuth().authenticated) {
+        // Authenticated hosted sessions persist invocation rows in the API,
+        // not ~/.adrata. Reading the local dashboard here used to both report
+        // zero and attempt to mkdir /home/adrata/.adrata in the read-only ECS
+        // image. The profile endpoint is the canonical named-tool rollup.
         try {
-          const data = await api('GET', '/api/v1/mcp/subscription');
-          const payload = data?.data || data || {};
+          const profileData = await api('GET', '/api/v1/mcp/profile');
+          const profile = profileData?.data || profileData || {};
+          const stats = profile.stats || {};
+          const topTools = Array.isArray(stats.top_tools)
+            ? stats.top_tools.map((entry) => ({
+                name: entry.name || entry.tool,
+                count: entry.count,
+              }))
+            : [];
+
+          let usage = null;
+          try {
+            const subscriptionData = await api('GET', '/api/v1/mcp/subscription');
+            const subscription = subscriptionData?.data || subscriptionData || {};
+            usage = subscription.usage || null;
+          } catch {
+            // Named invocation analytics remain valid when billing is absent.
+          }
+
           return ok({
             period,
-            server: payload,
-            usage: payload.usage || null,
-            local: getLocalDashboard(period),
+            coverage,
+            source: 'server',
+            server_scope: 'all_time',
+            period_note: 'The server profile currently reports all-time named invocation totals; period applies only to the local fallback.',
+            tool_invocations: {
+              total: Number(stats.total_queries || 0),
+              success: null,
+              errors: null,
+              avg_latency_ms: null,
+              top_tools: topTools,
+            },
+            server: profile,
+            usage,
+            server_events_30d: usage ? usage.tool_invocations_30d : null,
           });
         } catch {
-          // Fallback to local if server endpoint not available
-          return ok(getLocalDashboard(period));
+          // Offline-compatible fallback. readLocalAnalytics does not create a
+          // directory merely to answer an empty read, so this cannot break a
+          // read-only hosted container either.
+          return ok({ ...getLocalDashboard(period), coverage, source: 'local_fallback' });
         }
       }
 
       // Free tier: local analytics only
-      return ok(getLocalDashboard(period));
+      return ok({ ...getLocalDashboard(period), coverage });
     }
   );
 
@@ -627,7 +748,7 @@ export function registerAnalytics(server, { z, api, auth, ok, checkToolAccess })
       trigger: z.string().optional().describe('What triggered the conversion'),
     },
     async (args) => {
-      trackConversion(api, auth, args.from_tier, args.to_tier, args.trigger || 'manual');
+      trackConversion(api, resolveAuth(), args.from_tier, args.to_tier, args.trigger || 'manual');
       return ok({ tracked: true, from: args.from_tier, to: args.to_tier });
     }
   );

package/edge-block.js

@@ -0,0 +1,118 @@
+/**
+ * Tell an edge block apart from an authorization failure.
+ *
+ * The problem this exists for. api.adrata.com resolves to the ALB directly, and
+ * an AWS WAF web ACL sits on that ALB. When a managed rule matches a REQUEST
+ * BODY the request is refused at the edge and never reaches the Rust API, so
+ * the caller gets a bare HTML page:
+ *
+ *     <html>
+ *     <head><title>403 Forbidden</title></head>
+ *     <body>
+ *     <center><h1>403 Forbidden</h1></center>
+ *     </body>
+ *     </html>
+ *
+ * 403 is also what the API returns for a genuine `insufficient_scope`. Nothing
+ * in the old error message distinguished them, so the reasonable conclusion was
+ * "my token lost board write access" — and the reasonable next step was to ask
+ * the owner to reconnect the workspace. That reconnect loop has been run more
+ * than once for a cause that had nothing to do with credentials.
+ *
+ * The tell is decisive and needs no guessing. The Adrata API serialises EVERY
+ * error through one `IntoResponse` impl that always emits a JSON envelope
+ * (`code/api/crates/core/src/error.rs`), and its fallback route is JSON-only.
+ * An HTML body from this host is therefore structurally impossible to have come
+ * from the application. Something in front of it answered.
+ *
+ * Measured 2026-08-29 against production, same endpoint, same session, same
+ * everything but the body text:
+ *
+ *     plain prose ....................... 404 JSON  (reached the app)
+ *     markdown table, pipes only ........ 404 JSON  (reached the app)
+ *     fenced code block, backticks ...... 404 JSON  (reached the app)
+ *     JSX with angle brackets ........... 404 JSON  (reached the app)
+ *     "aaa ../ bbb" ..................... 403 HTML  (refused at the edge)
+ *     "link:../../packages/..." ......... 403 HTML  (refused at the edge)
+ *     "the file /etc/passwd is not read"  404 JSON  (reached the app)
+ *
+ * So the trigger is the path-traversal token `../`, not markdown structure —
+ * which matters, because "avoid tables and code fences" is the wrong lesson and
+ * would quietly strip evidence out of bug reports for no reason.
+ */
+
+/** Substrings measured to be refused at the edge, most specific first. */
+const MEASURED_TRIGGERS = [
+  { pattern: '../', label: 'a relative path segment (`../`)' },
+  { pattern: '..\\', label: 'a Windows relative path segment (`..\\`)' },
+  { pattern: '..%2f', label: 'a percent-encoded path segment (`..%2f`)' },
+  { pattern: '..%5c', label: 'a percent-encoded path segment (`..%5c`)' },
+];
+
+/**
+ * True when a response body cannot have come from the Adrata API.
+ *
+ * Deliberately narrow. It looks for an HTML document rather than for "not
+ * JSON": an empty body, a timeout, or a truncated read are different failures
+ * and must not be reported as an edge block.
+ */
+export function looksLikeEdgeHtml(text) {
+  if (typeof text !== 'string') return false;
+  const head = text.trimStart().slice(0, 400).toLowerCase();
+  if (!head.startsWith('<html') && !head.startsWith('<!doctype html')) return false;
+  return head.includes('<title>') || head.includes('<h1>');
+}
+
+/**
+ * Name the content the edge is most likely to have objected to.
+ *
+ * Returns every measured trigger present, because a body often carries more
+ * than one and fixing only the first sends the caller round again. Unknown is
+ * reported as unknown: a body with no measured trigger returns an empty list
+ * rather than a guess, so the caller is never told to edit the wrong sentence.
+ */
+export function offendingContent(requestBody) {
+  if (requestBody == null) return [];
+  let serialized;
+  try {
+    serialized = typeof requestBody === 'string' ? requestBody : JSON.stringify(requestBody);
+  } catch {
+    return [];
+  }
+  if (typeof serialized !== 'string') return [];
+  const haystack = serialized.toLowerCase();
+  return MEASURED_TRIGGERS.filter(({ pattern }) => haystack.includes(pattern)).map(
+    ({ label }) => label
+  );
+}
+
+/**
+ * Build the message for a request the edge refused, or return null when this
+ * was an ordinary API error and the caller should report it unchanged.
+ */
+export function describeEdgeBlock({ status, text, method, path, requestBody } = {}) {
+  if (!looksLikeEdgeHtml(text)) return null;
+  if (typeof status !== 'number' || status < 400 || status > 499) return null;
+
+  const found = offendingContent(requestBody);
+  const because = found.length
+    ? `The request body contains ${found.join(' and ')}, which the edge's path-traversal rule matches.`
+    : 'No known trigger was found in this request body, so the matching rule is not one already measured. Report the request id and the body, and check the WAF sampled requests.';
+
+  return [
+    `API ${method} ${path} → ${status}, refused at the network edge before it reached Adrata.`,
+    '',
+    'This is NOT an authentication or scope failure, and reconnecting the workspace will not',
+    'change it. The proof is the response body: the Adrata API serialises every error as JSON,',
+    'so an HTML error page from this host was produced by something in front of it (an AWS WAF',
+    'managed rule on the ALB). Your session is unaffected — do not call connect_workspace, and',
+    'do not ask the owner to reconnect.',
+    '',
+    because,
+    '',
+    'What to do: rewrite the offending text and resend. A relative path reads the same as',
+    '`code/desktop` or `<repo root>/packages/client-runtime`, and the record is no worse for it.',
+    'Do NOT strip out markdown tables or fenced code blocks — those were measured to pass, and',
+    'removing them only makes the record vaguer.',
+  ].join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrata/adrata-mcp",
-  "version": "1.0.3",
+  "version": "1.0.7",
   "description": "Adrata MCP Server \u2014 connect Claude Code, Codex, Gemini, Cursor, and other AI tools to your CRM. 80+ tools for companies, people, deals, actions, buyer groups, warm intros, webhooks, intelligence, and more.",
   "type": "module",
   "main": "server.js",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "start": "node server.js",
-    "test": "node --test server.test.js api-bridge.test.js audit-flush.test.js buyer-group-writes.test.js note-writes.test.js mcp-spec.test.js packaging.test.js product-profile.test.js security.test.js tool-annotations.test.js toolsets.test.js access/auth.test.js access/oauth-callback.test.js access/oauth-session.test.js access/oauth-capabilities.test.js scripts/local-dev-server.test.js tools/email-tools.test.js tools/scheduling.test.js tools/work-board-tools.test.js tools/work-hub/audit.test.js tools/roadmap-tools.test.js governance/money.test.js"
+    "test": "node --test analytics.test.js server.test.js api-bridge.test.js edge-block.test.js audit-flush.test.js buyer-group-writes.test.js note-writes.test.js mcp-spec.test.js packaging.test.js product-profile.test.js security.test.js tool-annotations.test.js toolsets.test.js access/auth.test.js access/oauth-callback.test.js access/oauth-session.test.js access/oauth-capabilities.test.js scripts/local-dev-server.test.js tools/competitive-coverage.test.js tools/email-tools.test.js tools/scheduling.test.js tools/work-board-tools.test.js tools/work-hub/audit.test.js tools/roadmap-tools.test.js tools/source-control/connection-tools.test.js governance/money.test.js"
   },
   "keywords": [
     "mcp",
@@ -44,6 +44,7 @@
     "api-bridge.js",
     "analytics.js",
     "security.js",
+    "edge-block.js",
     "transport-http.js",
     "resources.js",
     "tool-annotations.js",