@adrata/adrata-mcp 1.0.0

package/analytics.js

@@ -0,0 +1,634 @@
+/**
+ * Analytics and telemetry for Adrata MCP Server.
+ *
+ * Tracks:
+ *   - Tool invocations (tool name, tier, latency, success/error)
+ *   - Search queries with classification (industry/role/location)
+ *   - Tier gate impressions (upgrade CTA shown)
+ *   - Conversion events (free->signup, signup->pro, pro->enterprise)
+ *   - Session lifecycle (start, end, tools used, duration)
+ *
+ * Privacy:
+ *   - All PII is hashed (SHA-256) before storage
+ *   - Only metadata is tracked, never tool result content
+ *   - ADRATA_TELEMETRY=off disables all tracking
+ *   - Aggregation by default for dashboard queries
+ *
+ * Builds on top of the existing event logging in memory.js.
+ * All analytics calls are non-blocking (fire-and-forget).
+ */
+
+import crypto from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const TELEMETRY_ENABLED = process.env.ADRATA_TELEMETRY !== 'off';
+const ADRATA_DIR = join(homedir(), '.adrata');
+const ANALYTICS_FILE = join(ADRATA_DIR, 'analytics.json');
+
+// ---------------------------------------------------------------------------
+// PII hashing
+// ---------------------------------------------------------------------------
+
+/**
+ * Hash PII values with SHA-256. Returns a hex digest prefix (16 chars)
+ * so values can be grouped/counted without storing raw PII.
+ *
+ * @param {string} value - Raw PII value (email, name, etc.)
+ * @returns {string} Hashed value prefix
+ */
+export function hashPII(value) {
+  if (!value || typeof value !== 'string') return '';
+  return crypto.createHash('sha256').update(value.toLowerCase().trim()).digest('hex').slice(0, 16);
+}
+
+/**
+ * Sanitize an args object by hashing any PII fields.
+ * Recognized PII fields: email, name, firstName, lastName, personName, personEmail
+ *
+ * @param {object} args - Tool arguments
+ * @returns {object} Sanitized copy with PII hashed
+ */
+function sanitizeArgs(args) {
+  if (!args || typeof args !== 'object') return {};
+  const PII_FIELDS = ['email', 'name', 'firstName', 'lastName', 'personName', 'personEmail', 'phone'];
+  const sanitized = {};
+  for (const [k, v] of Object.entries(args)) {
+    if (v === undefined || v === null) continue;
+    if (PII_FIELDS.includes(k) && typeof v === 'string') {
+      sanitized[k] = hashPII(v);
+    } else {
+      sanitized[k] = v;
+    }
+  }
+  return sanitized;
+}
+
+// ---------------------------------------------------------------------------
+// Search query classification
+// ---------------------------------------------------------------------------
+
+const INDUSTRY_KEYWORDS = [
+  'fintech', 'healthcare', 'saas', 'ecommerce', 'banking', 'insurance',
+  'manufacturing', 'retail', 'technology', 'energy', 'telecom', 'media',
+  'pharma', 'biotech', 'logistics', 'real estate', 'education', 'automotive',
+];
+
+const ROLE_KEYWORDS = [
+  'ceo', 'cto', 'cfo', 'coo', 'vp', 'director', 'manager', 'head of',
+  'engineer', 'developer', 'sales', 'marketing', 'product', 'design',
+  'founder', 'president', 'chief', 'executive', 'analyst', 'consultant',
+];
+
+const LOCATION_KEYWORDS = [
+  'new york', 'san francisco', 'london', 'berlin', 'tokyo', 'singapore',
+  'seattle', 'austin', 'boston', 'chicago', 'los angeles', 'toronto',
+  'us', 'uk', 'eu', 'apac', 'emea', 'remote', 'california', 'texas',
+];
+
+/**
+ * Classify a search query into categories.
+ *
+ * @param {string} query - The search query text
+ * @returns {{ industry: string|null, role: string|null, location: string|null }}
+ */
+export function classifyQuery(query) {
+  if (!query || typeof query !== 'string') return { industry: null, role: null, location: null };
+  const lower = query.toLowerCase();
+
+  const industry = INDUSTRY_KEYWORDS.find(kw => lower.includes(kw)) || null;
+  const role = ROLE_KEYWORDS.find(kw => lower.includes(kw)) || null;
+  const location = LOCATION_KEYWORDS.find(kw => lower.includes(kw)) || null;
+
+  return { industry, role, location };
+}
+
+// ---------------------------------------------------------------------------
+// Local analytics storage (fallback for free tier / offline)
+// ---------------------------------------------------------------------------
+
+function ensureDir() {
+  if (!existsSync(ADRATA_DIR)) {
+    mkdirSync(ADRATA_DIR, { recursive: true });
+  }
+}
+
+function readLocalAnalytics() {
+  ensureDir();
+  if (!existsSync(ANALYTICS_FILE)) {
+    return { events: [], sessions: [] };
+  }
+  try {
+    return JSON.parse(readFileSync(ANALYTICS_FILE, 'utf-8'));
+  } catch {
+    return { events: [], sessions: [] };
+  }
+}
+
+function writeLocalAnalytics(data) {
+  ensureDir();
+  // Keep only last 10,000 events to prevent unbounded growth
+  if (data.events && data.events.length > 10000) {
+    data.events = data.events.slice(-10000);
+  }
+  writeFileSync(ANALYTICS_FILE, JSON.stringify(data, null, 2));
+}
+
+function appendLocalEvent(event) {
+  try {
+    const data = readLocalAnalytics();
+    data.events.push(event);
+    writeLocalAnalytics(data);
+  } catch {
+    // Swallow errors — analytics must never break the tool
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Event tracking (fire-and-forget)
+// ---------------------------------------------------------------------------
+
+/**
+ * Track a tool invocation event.
+ *
+ * @param {Function} apiFn - The api() helper
+ * @param {object} auth - AUTH context
+ * @param {string} toolName
+ * @param {string} tier - Tool's required tier
+ * @param {object} args - Tool arguments (will be sanitized)
+ * @param {number} latencyMs
+ * @param {boolean} success
+ * @param {string|null} error - Error message if failed
+ */
+export function trackToolInvocation(apiFn, auth, toolName, tier, args, latencyMs, success, error) {
+  if (!TELEMETRY_ENABLED) return;
+
+  const event = {
+    event_type: 'tool_invocation',
+    tool_name: toolName,
+    tier,
+    args_summary: summarizeForAnalytics(sanitizeArgs(args)),
+    latency_ms: latencyMs,
+    success,
+    error: error ? error.slice(0, 200) : undefined,
+    timestamp: new Date().toISOString(),
+  };
+
+  if (auth.authenticated) {
+    apiFn('POST', '/api/v1/mcp/events', { body: event }).catch(() => {});
+  } else {
+    appendLocalEvent(event);
+  }
+}
+
+/**
+ * Track a search query with classification.
+ *
+ * @param {Function} apiFn
+ * @param {object} auth
+ * @param {string} query - The search text
+ * @param {string} entityType - 'company', 'person', 'lead', etc.
+ * @param {number} resultsCount
+ * @param {string} tier
+ */
+export function trackSearchQuery(apiFn, auth, query, entityType, resultsCount, tier) {
+  if (!TELEMETRY_ENABLED) return;
+
+  const classification = classifyQuery(query);
+  const event = {
+    event_type: 'search_query',
+    query_hash: hashPII(query),
+    entity_type: entityType,
+    results_count: resultsCount,
+    tier,
+    classification,
+    timestamp: new Date().toISOString(),
+  };
+
+  if (auth.authenticated) {
+    apiFn('POST', '/api/v1/mcp/events', { body: event }).catch(() => {});
+  } else {
+    appendLocalEvent(event);
+  }
+}
+
+/**
+ * Track a tier gate impression (when user hits an upgrade wall).
+ *
+ * @param {Function} apiFn
+ * @param {object} auth
+ * @param {string} toolAttempted
+ * @param {string} currentTier
+ * @param {boolean} upgradeShown
+ */
+export function trackTierGate(apiFn, auth, toolAttempted, currentTier, upgradeShown) {
+  if (!TELEMETRY_ENABLED) return;
+
+  const event = {
+    event_type: 'tier_gate',
+    tool_attempted: toolAttempted,
+    current_tier: currentTier,
+    upgrade_shown: upgradeShown,
+    timestamp: new Date().toISOString(),
+  };
+
+  if (auth.authenticated) {
+    apiFn('POST', '/api/v1/mcp/events', { body: event }).catch(() => {});
+  } else {
+    appendLocalEvent(event);
+  }
+}
+
+/**
+ * Track a conversion event (tier upgrade).
+ *
+ * @param {Function} apiFn
+ * @param {object} auth
+ * @param {string} fromTier
+ * @param {string} toTier
+ * @param {string} trigger - What caused the conversion (e.g., 'connect_workspace', 'upgrade_account')
+ */
+export function trackConversion(apiFn, auth, fromTier, toTier, trigger) {
+  if (!TELEMETRY_ENABLED) return;
+
+  const event = {
+    event_type: 'conversion',
+    from_tier: fromTier,
+    to_tier: toTier,
+    trigger,
+    timestamp: new Date().toISOString(),
+  };
+
+  if (auth.authenticated) {
+    apiFn('POST', '/api/v1/mcp/events', { body: event }).catch(() => {});
+  } else {
+    appendLocalEvent(event);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Session tracking
+// ---------------------------------------------------------------------------
+
+/** @type {{ startTime: number, toolsUsed: Set<string>, invocationCount: number } | null} */
+let currentSession = null;
+
+/**
+ * Start a new analytics session.
+ *
+ * @param {Function} apiFn
+ * @param {object} auth
+ */
+export function startSession(apiFn, auth) {
+  if (!TELEMETRY_ENABLED) return;
+
+  currentSession = {
+    startTime: Date.now(),
+    toolsUsed: new Set(),
+    invocationCount: 0,
+  };
+
+  const event = {
+    event_type: 'session',
+    action: 'start',
+    tier: auth.tier,
+    timestamp: new Date().toISOString(),
+  };
+
+  if (auth.authenticated) {
+    apiFn('POST', '/api/v1/mcp/events', { body: event }).catch(() => {});
+  } else {
+    appendLocalEvent(event);
+  }
+}
+
+/**
+ * End the current analytics session.
+ *
+ * @param {Function} apiFn
+ * @param {object} auth
+ */
+export function endSession(apiFn, auth) {
+  if (!TELEMETRY_ENABLED || !currentSession) return;
+
+  const event = {
+    event_type: 'session',
+    action: 'end',
+    tier: auth.tier,
+    duration_ms: Date.now() - currentSession.startTime,
+    tools_used_count: currentSession.toolsUsed.size,
+    invocation_count: currentSession.invocationCount,
+    timestamp: new Date().toISOString(),
+  };
+
+  if (auth.authenticated) {
+    apiFn('POST', '/api/v1/mcp/events', { body: event }).catch(() => {});
+  } else {
+    appendLocalEvent(event);
+  }
+
+  currentSession = null;
+}
+
+/**
+ * Record that a tool was used in the current session.
+ *
+ * @param {string} toolName
+ */
+function recordSessionTool(toolName) {
+  if (currentSession) {
+    currentSession.toolsUsed.add(toolName);
+    currentSession.invocationCount++;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Analytics summary helpers
+// ---------------------------------------------------------------------------
+
+function summarizeForAnalytics(args) {
+  if (!args || typeof args !== 'object') return undefined;
+  const parts = [];
+  for (const [k, v] of Object.entries(args)) {
+    if (v === undefined || v === null) continue;
+    const str = typeof v === 'string' ? v : JSON.stringify(v);
+    parts.push(`${k}=${str.length > 40 ? str.slice(0, 37) + '...' : str}`);
+  }
+  const summary = parts.join(', ');
+  return summary.length > 150 ? summary.slice(0, 147) + '...' : summary;
+}
+
+// ---------------------------------------------------------------------------
+// Search tools that need query tracking
+// ---------------------------------------------------------------------------
+
+const SEARCH_TOOLS = {
+  search_companies: 'company',
+  search_people: 'person',
+  search_leads: 'lead',
+  search_emails: 'email',
+  search_opportunities: 'opportunity',
+  find_company: 'company',
+  find_person: 'person',
+  find_or_create_person: 'person',
+  find_or_create_company: 'company',
+};
+
+// ---------------------------------------------------------------------------
+// Analytics wrapper for server.tool
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap the MCP server's tool method to add analytics tracking on every
+ * 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.
+ *
+ * @param {object} server - McpServer instance
+ * @param {Function} apiFn - The api() helper
+ * @param {object} auth - AUTH context
+ * @param {Function} checkToolAccessFn - checkToolAccess from auth.js
+ */
+export function wrapWithAnalytics(server, apiFn, auth, checkToolAccessFn) {
+  if (!TELEMETRY_ENABLED) return;
+
+  const _analyticsWrappedTool = server.tool.bind(server);
+
+  server.tool = function analyticsTool(name, ...rest) {
+    const handler = rest[rest.length - 1];
+    rest[rest.length - 1] = async function analyticsHandler(...handlerArgs) {
+      const start = Date.now();
+      let success = true;
+      let errorMsg = null;
+
+      // Track tier gate if access was denied (check without modifying flow)
+      const access = checkToolAccessFn(name, auth);
+      if (!access.allowed) {
+        trackTierGate(apiFn, auth, name, auth.tier, true);
+      }
+
+      try {
+        const result = await handler(...handlerArgs);
+
+        // Track search queries for search tools
+        const args = handlerArgs[0] || {};
+        const entityType = SEARCH_TOOLS[name];
+        if (entityType) {
+          const query = args.query || args.name || args.search || '';
+          if (query) {
+            trackSearchQuery(apiFn, auth, query, entityType, 0, auth.tier);
+          }
+        }
+
+        return result;
+      } catch (err) {
+        success = false;
+        errorMsg = err?.message || String(err);
+        throw err;
+      } finally {
+        const latency = Date.now() - start;
+        const args = handlerArgs[0] || {};
+        trackToolInvocation(apiFn, auth, name, auth.tier, args, latency, success, errorMsg);
+        recordSessionTool(name);
+      }
+    };
+    return _analyticsWrappedTool(name, ...rest);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dashboard data aggregation (local analytics)
+// ---------------------------------------------------------------------------
+
+/**
+ * Aggregate local analytics into dashboard-ready data.
+ * Used when the Rust API endpoint is not available (free tier).
+ *
+ * @param {string} period - '1d', '7d', '30d', '90d'
+ * @returns {object} Dashboard data
+ */
+export function getLocalDashboard(period = '7d') {
+  const data = readLocalAnalytics();
+  const events = data.events || [];
+
+  // Parse period into milliseconds
+  const periodMs = parsePeriod(period);
+  const cutoff = new Date(Date.now() - periodMs).toISOString();
+  const filtered = events.filter(e => e.timestamp >= cutoff);
+
+  // Tool invocation stats
+  const toolEvents = filtered.filter(e => e.event_type === 'tool_invocation');
+  const toolCounts = {};
+  let totalLatency = 0;
+  let successCount = 0;
+  let errorCount = 0;
+
+  for (const e of toolEvents) {
+    toolCounts[e.tool_name] = (toolCounts[e.tool_name] || 0) + 1;
+    totalLatency += e.latency_ms || 0;
+    if (e.success) successCount++;
+    else errorCount++;
+  }
+
+  const topTools = Object.entries(toolCounts)
+    .sort(([, a], [, b]) => b - a)
+    .slice(0, 10)
+    .map(([name, count]) => ({ name, count }));
+
+  // Search query stats
+  const searchEvents = filtered.filter(e => e.event_type === 'search_query');
+  const queryCounts = {};
+  const classificationCounts = { industry: {}, role: {}, location: {} };
+
+  for (const e of searchEvents) {
+    const key = e.query_hash || 'unknown';
+    queryCounts[key] = (queryCounts[key] || 0) + 1;
+    if (e.classification) {
+      for (const dim of ['industry', 'role', 'location']) {
+        const val = e.classification[dim];
+        if (val) classificationCounts[dim][val] = (classificationCounts[dim][val] || 0) + 1;
+      }
+    }
+  }
+
+  const topQueries = Object.entries(queryCounts)
+    .sort(([, a], [, b]) => b - a)
+    .slice(0, 10)
+    .map(([hash, count]) => ({ query_hash: hash, count }));
+
+  // Tier gate stats
+  const tierGateEvents = filtered.filter(e => e.event_type === 'tier_gate');
+  const tierGateCounts = {};
+  for (const e of tierGateEvents) {
+    tierGateCounts[e.tool_attempted] = (tierGateCounts[e.tool_attempted] || 0) + 1;
+  }
+
+  // Conversion funnel
+  const conversionEvents = filtered.filter(e => e.event_type === 'conversion');
+  const conversions = {};
+  for (const e of conversionEvents) {
+    const key = `${e.from_tier}->${e.to_tier}`;
+    conversions[key] = (conversions[key] || 0) + 1;
+  }
+
+  // Session stats
+  const sessionEnds = filtered.filter(e => e.event_type === 'session' && e.action === 'end');
+  const avgDuration = sessionEnds.length > 0
+    ? sessionEnds.reduce((sum, e) => sum + (e.duration_ms || 0), 0) / sessionEnds.length
+    : 0;
+
+  return {
+    period,
+    total_events: filtered.length,
+    tool_invocations: {
+      total: toolEvents.length,
+      success: successCount,
+      errors: errorCount,
+      avg_latency_ms: toolEvents.length > 0 ? Math.round(totalLatency / toolEvents.length) : 0,
+      top_tools: topTools,
+    },
+    search_queries: {
+      total: searchEvents.length,
+      top_queries: topQueries,
+      classification_distribution: classificationCounts,
+    },
+    tier_gates: {
+      total: tierGateEvents.length,
+      by_tool: tierGateCounts,
+    },
+    conversion_funnel: conversions,
+    sessions: {
+      total: sessionEnds.length,
+      avg_duration_ms: Math.round(avgDuration),
+    },
+  };
+}
+
+function parsePeriod(period) {
+  const match = period.match(/^(\d+)(d|h|m)$/);
+  if (!match) return 7 * 24 * 60 * 60 * 1000; // default 7d
+  const [, num, unit] = match;
+  const n = parseInt(num, 10);
+  switch (unit) {
+    case 'd': return n * 24 * 60 * 60 * 1000;
+    case 'h': return n * 60 * 60 * 1000;
+    case 'm': return n * 60 * 1000;
+    default: return 7 * 24 * 60 * 60 * 1000;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Register analytics tools on the MCP server
+// ---------------------------------------------------------------------------
+
+/**
+ * Register the analytics dashboard tool and wire up the analytics wrapper.
+ *
+ * @param {object} server - McpServer instance
+ * @param {object} opts - { z, api, auth, ok, checkToolAccess }
+ */
+export function registerAnalytics(server, { z, api, auth, ok, checkToolAccess }) {
+  // Wire up the analytics wrapper on all future tool registrations
+  wrapWithAnalytics(server, api, auth, checkToolAccess);
+
+  // Start a session
+  startSession(api, auth);
+
+  // 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); });
+
+  // ----- get_mcp_analytics -----
+  server.tool('get_mcp_analytics',
+    'Get MCP usage analytics dashboard: top tools, search queries, conversion funnel, tier distribution. Admin only for server-side data; free tier shows local analytics.',
+    {
+      period: z.string().optional().describe('Time period: 1d, 7d, 30d, 90d (default: 7d)'),
+    },
+    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.
+        try {
+          const data = await api('GET', '/api/v1/mcp/subscription');
+          const payload = data?.data || data || {};
+          return ok({
+            period,
+            server: payload,
+            usage: payload.usage || null,
+            local: getLocalDashboard(period),
+          });
+        } catch {
+          // Fallback to local if server endpoint not available
+          return ok(getLocalDashboard(period));
+        }
+      }
+
+      // Free tier: local analytics only
+      return ok(getLocalDashboard(period));
+    }
+  );
+
+  // ----- track_conversion (internal use, exposed for billing integration) -----
+  server.tool('track_conversion',
+    'Track a tier conversion event (internal). Used by billing to record upgrades: free->pro, pro->enterprise.',
+    {
+      from_tier: z.enum(['free', 'pro', 'enterprise']).describe('Previous tier'),
+      to_tier: z.enum(['free', 'pro', 'enterprise']).describe('New tier'),
+      trigger: z.string().optional().describe('What triggered the conversion'),
+    },
+    async (args) => {
+      trackConversion(api, auth, args.from_tier, args.to_tier, args.trigger || 'manual');
+      return ok({ tracked: true, from: args.from_tier, to: args.to_tier });
+    }
+  );
+}