@adrata/adrata-mcp 1.0.0

package/tools/free-search.js

@@ -0,0 +1,160 @@
+/**
+ * Free Tier Claude-Powered Search
+ *
+ * These tools return structured prompts that guide Claude (the LLM running the
+ * MCP client) to search its own training data for company and person profiles.
+ *
+ * Cost to Adrata: $0 — Claude's own knowledge does the work.
+ * No API key needed, no account needed, unlimited usage.
+ */
+
+// ---------------------------------------------------------------------------
+// In-memory LRU cache (max 500 entries)
+// ---------------------------------------------------------------------------
+
+const CACHE_MAX = 500;
+const cache = new Map();
+
+function cacheGet(key) {
+  if (!cache.has(key)) return undefined;
+  const value = cache.get(key);
+  // Move to end (most recently used)
+  cache.delete(key);
+  cache.set(key, value);
+  return value;
+}
+
+function cacheSet(key, value) {
+  if (cache.has(key)) cache.delete(key);
+  cache.set(key, value);
+  // Evict oldest if over limit
+  if (cache.size > CACHE_MAX) {
+    const oldest = cache.keys().next().value;
+    cache.delete(oldest);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Company search prompt
+// ---------------------------------------------------------------------------
+
+const COMPANY_SYSTEM_PROMPT = `You are a business intelligence assistant integrated into the Adrata sales platform.
+The user asked about a company. Search your training data and return a comprehensive, sales-relevant profile.
+
+IMPORTANT: Respond with ONLY a valid JSON object matching this exact schema. No markdown, no explanation, no code fences.
+
+{
+  "name": "Official Company Name",
+  "industry": "Primary industry classification",
+  "description": "2-3 sentence company overview focusing on what they do, their market position, and value proposition",
+  "headquarters": "City, State/Country",
+  "founded": "Year or approximate",
+  "key_people": ["Name (Title)", "Name (Title)"],
+  "estimated_size": "Employee count range (e.g. 1,000-5,000 employees)",
+  "estimated_revenue": "Revenue range if known (e.g. $100M-$500M ARR)",
+  "products_services": ["Core product/service 1", "Core product/service 2"],
+  "competitors": ["Competitor 1", "Competitor 2", "Competitor 3"],
+  "recent_highlights": "Notable recent developments, funding, acquisitions, or strategic moves from training data",
+  "ideal_sales_angles": "2-3 sentence suggestion for how a seller might approach this company",
+  "data_freshness": "Based on training data through early 2025. Some details may have changed.",
+  "upgrade_prompt": "Want verified contacts, real-time headcount, funding rounds, hiring signals, and intent data? Upgrade to Adrata Pro for enriched intelligence."
+}
+
+Rules:
+- Include up to 5 key people (C-suite and VPs preferred)
+- Include up to 5 competitors
+- Include up to 5 products/services
+- If you are unsure about a field, provide your best estimate with a qualifier like "approximately" or "estimated"
+- Never fabricate specific numbers — use ranges when uncertain
+- Focus on information useful to a B2B sales professional`;
+
+const PERSON_SYSTEM_PROMPT = `You are a business intelligence assistant integrated into the Adrata sales platform.
+The user asked about a professional. Search your training data and return a comprehensive, sales-relevant profile.
+
+IMPORTANT: Respond with ONLY a valid JSON object matching this exact schema. No markdown, no explanation, no code fences.
+
+{
+  "name": "Full Name",
+  "title": "Current or most recent title",
+  "company": "Current or most recent company",
+  "summary": "2-3 sentence professional summary — who they are and why they matter in their industry",
+  "background": "Career trajectory highlights: previous notable roles, companies, achievements",
+  "education": "University and degree if known, otherwise omit",
+  "expertise": ["Domain expertise 1", "Domain expertise 2", "Domain expertise 3"],
+  "notable_achievements": "Key accomplishments, board seats, speaking engagements, publications",
+  "linkedin_likely": "Likely LinkedIn URL pattern (e.g. linkedin.com/in/firstname-lastname) — note: unverified",
+  "sales_context": "2-3 sentence suggestion for how a seller might approach this person — what they likely care about",
+  "data_freshness": "Based on training data through early 2025. Current role may have changed.",
+  "upgrade_prompt": "Want verified email, phone, social profiles, recent activity, and buyer signals? Upgrade to Adrata Pro for enriched contact intelligence."
+}
+
+Rules:
+- Focus on publicly known professionals (executives, founders, industry leaders)
+- If the person is not well-known, provide what you can and note the limitation
+- Never fabricate contact information (email, phone)
+- The linkedin_likely field is a guess based on common URL patterns — always mark as unverified
+- Focus on information useful to a B2B sales professional approaching this person`;
+
+// ---------------------------------------------------------------------------
+// Tool implementations
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a structured company profile prompt for Claude to fill from its
+ * training data. Returns a text response that Claude will process inline.
+ */
+export function findCompany(name) {
+  const normalizedName = name.trim().toLowerCase();
+  const cacheKey = `company:${normalizedName}`;
+
+  const cached = cacheGet(cacheKey);
+  if (cached) return cached;
+
+  const result = {
+    content: [
+      {
+        type: 'text',
+        text: [
+          COMPANY_SYSTEM_PROMPT,
+          '',
+          `Company to research: "${name}"`,
+          '',
+          'Respond with the JSON object now.',
+        ].join('\n'),
+      },
+    ],
+  };
+
+  cacheSet(cacheKey, result);
+  return result;
+}
+
+/**
+ * Generate a structured person profile prompt for Claude to fill from its
+ * training data. Returns a text response that Claude will process inline.
+ */
+export function findPerson(name) {
+  const normalizedName = name.trim().toLowerCase();
+  const cacheKey = `person:${normalizedName}`;
+
+  const cached = cacheGet(cacheKey);
+  if (cached) return cached;
+
+  const result = {
+    content: [
+      {
+        type: 'text',
+        text: [
+          PERSON_SYSTEM_PROMPT,
+          '',
+          `Person to research: "${name}"`,
+          '',
+          'Respond with the JSON object now.',
+        ].join('\n'),
+      },
+    ],
+  };
+
+  cacheSet(cacheKey, result);
+  return result;
+}

package/tools/memory.js

@@ -0,0 +1,440 @@
+/**
+ * Memory tools for Adrata MCP Server.
+ *
+ * Tier behavior:
+ *   - Free tier: memories stored locally in ~/.adrata/memories.json
+ *   - Pro+ tier: memories stored in the Adrata Cloud via the API
+ *
+ * Tools:
+ *   - save_memory  — store a fact or insight
+ *   - recall       — search memories by text query
+ *   - who_am_i     — user profile with usage stats
+ *   - forget       — soft-delete a memory by ID
+ *
+ * Also provides:
+ *   - logEvent()           — silent background event logging
+ *   - wrapWithEventLogging — wraps the server.tool method to auto-log every invocation
+ *   - registerProfileResource — registers the adrata://profile MCP resource
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Local storage (free tier)
+// ---------------------------------------------------------------------------
+
+const ADRATA_DIR = join(homedir(), '.adrata');
+const MEMORIES_FILE = join(ADRATA_DIR, 'memories.json');
+
+function ensureLocalDir() {
+  if (!existsSync(ADRATA_DIR)) {
+    mkdirSync(ADRATA_DIR, { recursive: true });
+  }
+}
+
+function readLocalMemories() {
+  ensureLocalDir();
+  if (!existsSync(MEMORIES_FILE)) return [];
+  try {
+    return JSON.parse(readFileSync(MEMORIES_FILE, 'utf-8'));
+  } catch {
+    return [];
+  }
+}
+
+function writeLocalMemories(memories) {
+  ensureLocalDir();
+  writeFileSync(MEMORIES_FILE, JSON.stringify(memories, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// Event logging (fires in background, never blocks)
+// ---------------------------------------------------------------------------
+
+/**
+ * Silently log a tool invocation event. Fire-and-forget: errors are swallowed.
+ *
+ * @param {Function} apiFn  - The api() helper from server.js
+ * @param {object}   auth   - The AUTH context { tier, token, apiKey, authenticated }
+ * @param {string}   toolName
+ * @param {string}   [argsSummary]
+ * @param {string}   [resultType]  - 'success' | 'error' | 'teaser'
+ * @param {number}   [latencyMs]
+ */
+export function logEvent(apiFn, auth, toolName, argsSummary, resultType, latencyMs) {
+  // Only log to server for authenticated (pro+) users
+  if (!auth.authenticated) return;
+
+  const body = {
+    tool_name: toolName,
+    args_summary: argsSummary || undefined,
+    result_type: resultType || 'success',
+    latency_ms: latencyMs || undefined,
+  };
+
+  // Fire and forget — do not await, swallow errors
+  apiFn('POST', '/api/v1/mcp/events', { body }).catch(() => {});
+}
+
+/**
+ * Summarize tool arguments into a short string for analytics.
+ * Strips large values and keeps only keys + short values.
+ */
+function summarizeArgs(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 > 60 ? str.slice(0, 57) + '...' : str}`);
+  }
+  const summary = parts.join(', ');
+  return summary.length > 200 ? summary.slice(0, 197) + '...' : summary;
+}
+
+/**
+ * Wrap the MCP server's tool method so that every invocation is automatically
+ * logged via logEvent(). This should be called AFTER the tier-gating wrapper
+ * has already been applied.
+ *
+ * @param {object} server  - The McpServer instance
+ * @param {Function} apiFn - The api() helper
+ * @param {object} auth    - The AUTH context
+ * @returns {Function} restore - Call to remove the wrapper (for testing)
+ */
+export function wrapWithEventLogging(server, apiFn, auth) {
+  const _wrappedTool = server.tool.bind(server);
+
+  server.tool = function loggedTool(name, ...rest) {
+    const handler = rest[rest.length - 1];
+    rest[rest.length - 1] = async function loggedHandler(...handlerArgs) {
+      const start = Date.now();
+      let resultType = 'success';
+      try {
+        const result = await handler(...handlerArgs);
+        return result;
+      } catch (err) {
+        resultType = 'error';
+        throw err;
+      } finally {
+        const latency = Date.now() - start;
+        // handlerArgs[0] is the args object from MCP
+        const argsSummary = summarizeArgs(handlerArgs[0]);
+        logEvent(apiFn, auth, name, argsSummary, resultType, latency);
+      }
+    };
+    return _wrappedTool(name, ...rest);
+  };
+
+  return function restore() {
+    server.tool = _wrappedTool;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Memory tools
+// ---------------------------------------------------------------------------
+
+/**
+ * Register all memory tools on the MCP server.
+ *
+ * @param {object}   server - McpServer instance (already has tier gating)
+ * @param {object}   z      - Zod instance from MCP SDK
+ * @param {Function} apiFn  - The api() helper for server calls
+ * @param {object}   auth   - AUTH context { tier, token, apiKey, authenticated }
+ * @param {Function} okFn   - The ok() response helper from server.js
+ */
+export function registerMemoryTools(server, z, apiFn, auth, okFn) {
+  const isServerSide = auth.authenticated; // pro+ uses server, free uses local
+
+  // ----- save_memory -----
+  server.tool('save_memory',
+    'Store a fact, insight, preference, or deal context. Memories persist across conversations so Claude remembers important information. Free tier stores locally; Pro+ stores server-side with vector search.',
+    {
+      content: z.string().describe('The fact or insight to remember (e.g. "Stripe is our top competitor in payments")'),
+      tags: z.array(z.string()).optional().describe('Optional tags for categorization (e.g. ["competitor", "payments"])'),
+      memory_type: z.enum(['fact', 'preference', 'deal_context', 'pattern']).optional().describe('Type of memory (default: fact)'),
+    },
+    async (args) => {
+      if (isServerSide) {
+        const data = await apiFn('POST', '/api/v1/mcp/memories', {
+          body: {
+            content: args.content,
+            tags: args.tags || [],
+            memory_type: args.memory_type || 'fact',
+          },
+        });
+        return okFn(data);
+      }
+
+      // Free tier: store locally
+      const memories = readLocalMemories();
+      const memory = {
+        id: randomUUID(),
+        content: args.content,
+        memory_type: args.memory_type || 'fact',
+        tags: args.tags || [],
+        confidence: 1.0,
+        is_latest: true,
+        forgotten_at: null,
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+      };
+      memories.push(memory);
+      writeLocalMemories(memories);
+
+      return okFn({
+        success: true,
+        data: {
+          id: memory.id,
+          memory_type: memory.memory_type,
+          is_latest: true,
+        },
+      });
+    }
+  );
+
+  // ----- recall -----
+  server.tool('recall',
+    'Search saved memories by text query. Returns memories ranked by relevance. Use this to recall facts, preferences, deal context, or patterns from previous conversations.',
+    {
+      query: z.string().describe('Search query (e.g. "competitors in payments", "user preferences")'),
+      memory_type: z.enum(['fact', 'preference', 'deal_context', 'pattern']).optional().describe('Filter by memory type'),
+      limit: z.number().optional().describe('Max results (default 10, max 50)'),
+    },
+    async (args) => {
+      if (isServerSide) {
+        const params = {
+          query: args.query,
+          memory_type: args.memory_type,
+          limit: args.limit || 10,
+        };
+        const data = await apiFn('GET', '/api/v1/mcp/memories', { params });
+        return okFn(data);
+      }
+
+      // Free tier: local text search
+      const memories = readLocalMemories();
+      const queryLower = args.query.toLowerCase();
+      const limit = Math.min(args.limit || 10, 50);
+
+      const scored = memories
+        .filter(m => m.is_latest && !m.forgotten_at)
+        .filter(m => !args.memory_type || m.memory_type === args.memory_type)
+        .map(m => {
+          // Simple text similarity: count query word matches
+          const words = queryLower.split(/\s+/);
+          const contentLower = m.content.toLowerCase();
+          const tagsLower = (m.tags || []).join(' ').toLowerCase();
+          let score = 0;
+          for (const word of words) {
+            if (contentLower.includes(word)) score += 2;
+            if (tagsLower.includes(word)) score += 1;
+          }
+          return { ...m, similarity: score / (words.length * 3) };
+        })
+        .filter(m => m.similarity > 0)
+        .sort((a, b) => b.similarity - a.similarity)
+        .slice(0, limit);
+
+      return okFn({
+        success: true,
+        data: scored,
+        meta: { count: scored.length, search_type: 'local_text' },
+      });
+    }
+  );
+
+  // ----- who_am_i -----
+  server.tool('who_am_i',
+    'Get your user profile with usage statistics — tier, top tools used, recent activity, saved memories count, and industries researched. Useful for understanding your Adrata context.',
+    {},
+    async () => {
+      if (isServerSide) {
+        const data = await apiFn('GET', '/api/v1/mcp/profile');
+
+        // /api/v1/mcp/profile describes the OAuth *client*, not the human it
+        // acts for: it returns name:"OAuth client", email:"", role:null,
+        // tier:"free" even for an enterprise seat. That directly contradicts
+        // get_current_user and makes who_am_i — the first tool an agent
+        // reaches for — untrustworthy. Overlay the authenticated user so both
+        // tools agree on identity.
+        try {
+          const me = await apiFn('GET', '/api/v1/users/me');
+          const u = me?.data || me;
+          if (u?.id) {
+            const profile = data?.data ? { ...data.data } : {};
+            profile.user = {
+              ...(profile.user || {}),
+              id: u.id,
+              name: u.name || [u.firstName, u.lastName].filter(Boolean).join(' ') || null,
+              email: u.email || null,
+              role: u.role ?? (profile.user || {}).role ?? null,
+              title: u.title || null,
+              workspaceId: u.activeWorkspaceId || u.workspaceId || null,
+              // Keep whatever tier the profile endpoint reported, but never let
+              // a null/absent value silently read as "free".
+              tier: (profile.user || {}).tier || null,
+            };
+            return okFn({ ...data, data: profile });
+          }
+        } catch {
+          // Fall through to the raw profile rather than failing the tool.
+        }
+        return okFn(data);
+      }
+
+      // Free tier: build profile from local data
+      const memories = readLocalMemories();
+      const activeMemories = memories.filter(m => m.is_latest && !m.forgotten_at);
+
+      // Collect tags as a proxy for "industries"
+      const tagCounts = {};
+      for (const m of activeMemories) {
+        for (const tag of (m.tags || [])) {
+          tagCounts[tag] = (tagCounts[tag] || 0) + 1;
+        }
+      }
+
+      const topTags = Object.entries(tagCounts)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .map(([tag, count]) => ({ tag, count }));
+
+      return okFn({
+        success: true,
+        data: {
+          user: {
+            tier: 'free',
+            role: null,
+            preferences: {},
+          },
+          stats: {
+            total_queries: 0,
+            top_tools: [],
+            recent_conversations_30d: 0,
+            active_memories: activeMemories.length,
+            top_tags: topTags,
+            industries_searched: [],
+          },
+        },
+      });
+    }
+  );
+
+  // ----- forget -----
+  server.tool('forget',
+    'Soft-delete a specific memory by ID. The memory will no longer appear in recall results.',
+    {
+      memory_id: z.string().describe('The ID of the memory to forget'),
+    },
+    async (args) => {
+      if (isServerSide) {
+        // DELETE /api/v1/mcp/memories/{id} hard-deletes from the unified
+        // ai_memories store. (The old fallback of saving a "[FORGOTTEN]"
+        // tombstone memory polluted recall — never do that; surface the
+        // error instead.)
+        try {
+          await apiFn('DELETE', `/api/v1/mcp/memories/${args.memory_id}`);
+          return okFn({ success: true, forgotten: args.memory_id });
+        } catch (err) {
+          return okFn({
+            success: false,
+            error: `Failed to forget memory ${args.memory_id}: ${err?.message || err}`,
+          });
+        }
+      }
+
+      // Free tier: mark as forgotten locally
+      const memories = readLocalMemories();
+      let found = false;
+      for (const m of memories) {
+        if (m.id === args.memory_id && !m.forgotten_at) {
+          m.forgotten_at = new Date().toISOString();
+          m.is_latest = false;
+          found = true;
+          break;
+        }
+      }
+
+      if (!found) {
+        return okFn({ success: false, error: `Memory ${args.memory_id} not found or already forgotten` });
+      }
+
+      writeLocalMemories(memories);
+      return okFn({ success: true, forgotten: args.memory_id });
+    }
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MCP Resource: adrata://profile
+// ---------------------------------------------------------------------------
+
+/**
+ * Register the adrata://profile resource that Claude reads at session start
+ * for context injection.
+ *
+ * @param {object}   server - McpServer instance
+ * @param {Function} apiFn  - The api() helper
+ * @param {object}   auth   - AUTH context
+ */
+export function registerProfileResource(server, apiFn, auth) {
+  server.resource('user-profile', 'adrata://profile', async () => {
+    let profileText;
+
+    if (auth.authenticated) {
+      try {
+        const data = await apiFn('GET', '/api/v1/mcp/profile');
+        const profile = data?.data || data;
+        profileText = `Adrata User Profile
+Tier: ${profile.user?.tier || auth.tier}
+Email: ${profile.user?.email || 'unknown'}
+Role: ${profile.user?.role || 'not set'}
+Member since: ${profile.user?.member_since || 'unknown'}
+
+Usage Statistics:
+- Total queries: ${profile.stats?.total_queries || 0}
+- Active memories: ${profile.stats?.active_memories || 0}
+- Recent conversations (30d): ${profile.stats?.recent_conversations_30d || 0}
+
+Top tools: ${(profile.stats?.top_tools || []).map(t => `${t.tool} (${t.count})`).join(', ') || 'none yet'}
+Industries searched: ${(profile.stats?.industries_searched || []).join(', ') || 'none yet'}`;
+      } catch {
+        profileText = `Adrata User Profile
+Tier: ${auth.tier}
+Status: Profile data unavailable (API error). User is authenticated.`;
+      }
+    } else {
+      // Free tier: build from local data
+      const memories = readLocalMemories();
+      const activeMemories = memories.filter(m => m.is_latest && !m.forgotten_at);
+      const tags = {};
+      for (const m of activeMemories) {
+        for (const tag of (m.tags || [])) {
+          tags[tag] = (tags[tag] || 0) + 1;
+        }
+      }
+      const topTags = Object.entries(tags).sort((a, b) => b[1] - a[1]).slice(0, 5);
+
+      profileText = `Adrata User Profile
+Tier: free
+Active memories: ${activeMemories.length}
+Top tags: ${topTags.map(([t, c]) => `${t} (${c})`).join(', ') || 'none yet'}
+
+Note: Upgrade to Pro for server-side memory with vector search, usage analytics, and full profile data.
+Set the ADRATA_API_KEY environment variable to activate.`;
+    }
+
+    return {
+      contents: [{
+        uri: 'adrata://profile',
+        mimeType: 'text/plain',
+        text: profileText,
+      }],
+    };
+  });
+}