@adrata/adrata-mcp 1.0.0

package/tool-annotations.js

@@ -0,0 +1,269 @@
+/**
+ * Honest MCP tool annotations + per-domain scoping for the Adrata MCP server.
+ *
+ * Two jobs:
+ *   1. Annotate every exposed tool with the MCP `ToolAnnotations` behaviour
+ *      hints (readOnlyHint / destructiveHint / idempotentHint / openWorldHint)
+ *      so a host (Claude, Cursor, ...) can truthfully decide what needs
+ *      confirmation. These hints are advisory per the MCP spec and MUST be
+ *      treated as untrusted by clients — we derive them from the tool's real
+ *      behaviour, never from a model-supplied description.
+ *   2. Tag each tool with a domain "pack" (crm, email, calendar, enrichment,
+ *      ...) so a client can request least-privilege scopes. When
+ *      ADRATA_MCP_ENABLED_DOMAINS is set, tools outside the enabled packs are
+ *      refused at dispatch — a lightweight scoped-tool-pack enforcement that
+ *      avoids shipping N separate servers.
+ *
+ * Pure/stateless so it is unit-testable.
+ */
+
+// ---------------------------------------------------------------------------
+// Domain packs
+// ---------------------------------------------------------------------------
+
+/**
+ * Explicit tool -> domain overrides. Anything not listed falls back to the
+ * keyword/prefix heuristic in getToolDomain().
+ */
+const DOMAIN_OVERRIDES = {
+  // Meta / workspace lifecycle — always available regardless of scope.
+  connect_workspace: 'workspace',
+  disconnect_workspace: 'workspace',
+  workspace_status: 'workspace',
+  list_workspaces: 'workspace',
+  switch_workspace: 'workspace',
+  get_workspace_settings: 'workspace',
+  list_toolsets: 'workspace',
+  enable_toolset: 'workspace',
+  who_am_i: 'workspace',
+  get_current_user: 'workspace',
+
+  // Governed API bridge.
+  adrata_api_catalog: 'bridge',
+  adrata_api_request: 'bridge',
+  adrata_ai_tool_catalog: 'bridge',
+  adrata_ai_tool_execute: 'bridge',
+
+  // Enrichment / external intelligence.
+  enrich_company: 'enrichment',
+  enrich_person: 'enrichment',
+  get_intent_signals: 'enrichment',
+  list_customer_signals: 'enrichment',
+  get_competitor_intel: 'enrichment',
+  get_company_firmographics: 'enrichment',
+  score_company_icp: 'intelligence',
+  list_icp_profiles: 'intelligence',
+  rank_companies_by_icp: 'intelligence',
+  rank_people_by_icp: 'intelligence',
+  get_icp_distribution: 'intelligence',
+  get_deal_authority: 'intelligence',
+  rank_paths_to_power: 'intelligence',
+  recommend_deal_move: 'intelligence',
+  get_account_read: 'intelligence',
+  build_pursuit_command_center: 'intelligence',
+  get_pipeline_metrics: 'intelligence',
+  get_forecast_data: 'intelligence',
+  get_speedrun_list: 'intelligence',
+  get_priority_pursuits: 'intelligence',
+  morning_brief: 'intelligence',
+
+  // Networking / warm intros.
+  find_intro_path: 'network',
+  get_network_stats: 'network',
+  create_intro_request: 'network',
+  update_intro_request: 'network',
+  list_intro_requests: 'network',
+  get_intro_pipeline: 'network',
+
+  // Meetings / calendar.
+  schedule_demo: 'calendar',
+  schedule_meeting: 'calendar',
+  get_demo_availability: 'calendar',
+  list_meetings: 'meetings',
+  get_meeting: 'meetings',
+  get_meeting_summary: 'meetings',
+  get_meeting_action_items: 'meetings',
+
+  // Memory.
+  save_memory: 'memory',
+  recall: 'memory',
+  forget: 'memory',
+
+  // Billing.
+  upgrade_account: 'billing',
+  check_subscription: 'billing',
+
+  // Analytics.
+  get_mcp_analytics: 'analytics',
+  track_conversion: 'analytics',
+
+  // Finance: the customer's own ERP invoices / installed base. Its own pack so
+  // a least-privilege scope can grant CRM reads without granting revenue data.
+  // get_company_invoices would otherwise fall through to the 'crm' keyword rule.
+  get_installed_base: 'finance',
+  get_company_invoices: 'finance',
+
+  // Adrata Cloud: the bitemporal record substrate read.
+  get_cloud_records: 'cloud',
+};
+
+const DOMAIN_PREFIX_RULES = [
+  [/^(create_email_account|list_email_accounts|warmup_email|get_email_health)/, 'infra'],
+  [/^(search_domains|purchase_domain|setup_domain|verify_domain|list_domains)/, 'infra'],
+  [/^(create_sequence|list_sequences|get_sequence|add_sequence_step|activate_sequence|pause_sequence|get_sequence_analytics|enroll_contacts|list_campaigns|get_campaign)/, 'sequences'],
+  [/^(search_emails|get_email|count_emails|check_inbox|log_interaction)/, 'email'],
+  [/webhook/, 'webhooks'],
+  [/(buyer_group)/, 'buyergroup'],
+  [/^(create_action|update_action|complete_action|delete_action|get_action|list_actions|list_overdue_actions|list_today_actions|get_activity_summary)/, 'actions'],
+  [/note/, 'notes'],
+  [/opportunit|move_pipeline_card/, 'pipeline'],
+  [/agent_task/, 'agent'],
+  [/(external_pipeline|external_companies|import_external|check_batch_import|bulk_import|export_data)/, 'admin'],
+  [/(custom_field|describe_fields|manage_data|manage_workspace)/, 'admin'],
+  [/(company|companies)/, 'crm'],
+  [/(person|people|lead|contact)/, 'crm'],
+  [/^search/, 'search'],
+  [/^find/, 'search'],
+];
+
+/** Domains that are always callable regardless of ADRATA_MCP_ENABLED_DOMAINS. */
+const ALWAYS_ENABLED_DOMAINS = new Set(['workspace', 'billing']);
+
+/** Resolve the domain pack for a tool. */
+export function getToolDomain(name) {
+  if (DOMAIN_OVERRIDES[name]) return DOMAIN_OVERRIDES[name];
+  for (const [re, domain] of DOMAIN_PREFIX_RULES) {
+    if (re.test(name)) return domain;
+  }
+  return 'general';
+}
+
+/**
+ * Enforce per-domain scoping. Returns { allowed } or { allowed:false, reason }.
+ * Enabled only when ADRATA_MCP_ENABLED_DOMAINS is set (comma list of packs).
+ */
+export function checkDomainScope(name) {
+  const raw = process.env.ADRATA_MCP_ENABLED_DOMAINS;
+  if (!raw) return { allowed: true };
+  const enabled = new Set(raw.split(',').map(s => s.trim()).filter(Boolean));
+  const domain = getToolDomain(name);
+  if (ALWAYS_ENABLED_DOMAINS.has(domain) || enabled.has(domain)) return { allowed: true };
+  return { allowed: false, reason: 'domain_not_in_scope', domain, enabled: [...enabled] };
+}
+
+// ---------------------------------------------------------------------------
+// Behaviour classification (readOnly / destructive / idempotent / openWorld)
+// ---------------------------------------------------------------------------
+
+// Tools that mutate but do not read (idempotent updates vs. creates vs. deletes).
+//
+// Destructive is derived from a PATTERN first, so every future `delete_*`,
+// `bulk_delete_*`, `purchase_*` (irreversible spend) or `*send_email`
+// (irreversible external effect) tool is destructive by construction. The
+// explicit set below covers names the pattern cannot see (mid-name deletes
+// like paper_delete_document, revokes, composite manage_* delete actions).
+const DESTRUCTIVE_PATTERN = /^(delete_|bulk_delete_|purchase_)|send_email$/;
+
+const DESTRUCTIVE = new Set([
+  'delete_company', 'delete_person', 'delete_opportunity', 'delete_action',
+  'delete_note', 'delete_webhook', 'disconnect_workspace', 'forget',
+  // Buyer rooms. delete_buyer_group cascades to the room's member seats, and
+  // bulk_delete_buyer_groups does that for up to 50 rooms in one call.
+  'delete_buyer_group', 'bulk_delete_buyer_groups', 'remove_buyer_group_member',
+  // Paper: mid-name delete + share revocation (cuts off external access).
+  'paper_delete_document', 'paper_revoke_share',
+  // The composite manage_* tools each expose a `delete` action. They were
+  // previously unclassified, so isReadOnly() fell through to a false
+  // destructiveHint — a host would not have confirmation-gated a delete.
+  'manage_company', 'manage_person', 'manage_opportunity', 'manage_activity',
+  'manage_buyer_group',
+]);
+
+/** True when a tool is destructive (irreversible delete, spend, or send). */
+export function isDestructive(name) {
+  return DESTRUCTIVE.has(name) || DESTRUCTIVE_PATTERN.test(name);
+}
+
+// Non-read tools that are safe to retry (PATCH/PUT semantics, toggles).
+const IDEMPOTENT_WRITES = new Set([
+  'update_company', 'update_person', 'update_opportunity', 'update_action',
+  'update_note', 'update_webhook', 'update_intro_request', 'complete_action',
+  'pause_sequence', 'activate_sequence', 'verify_domain', 'move_pipeline_card',
+  'add_to_company_list', 'find_or_create_person', 'find_or_create_company',
+  'save_memory', 'manage_custom_fields', 'build_pursuit_command_center',
+  'update_buyer_group', 'update_buyer_group_member',
+]);
+
+// Non-read tools that create new state / have side effects each call.
+const NON_IDEMPOTENT_WRITES = new Set([
+  'create_company', 'create_person', 'create_opportunity', 'create_action',
+  'create_note', 'create_webhook', 'create_buyer_group', 'add_buyer_group_member',
+  'create_company_list', 'create_intro_request', 'create_sequence',
+  'add_sequence_step', 'enroll_contacts', 'create_email_account',
+  'create_agent_task', 'cancel_agent_task', 'bulk_import', 'import_external_companies',
+  'import_external_pipeline_members', 'purchase_domain', 'setup_domain',
+  'warmup_email', 'schedule_demo', 'schedule_meeting', 'connect_workspace',
+  'enable_toolset', 'track_conversion', 'log_interaction', 'test_webhook',
+  'replay_webhook_delivery', 'upgrade_account',
+]);
+
+// Tools that reach beyond the workspace (external enrichment, web, providers).
+const OPEN_WORLD = new Set([
+  'enrich_company', 'enrich_person', 'get_intent_signals', 'get_competitor_intel',
+  'get_company_firmographics', 'search_domains', 'purchase_domain',
+  'find_intro_path', 'search_leads', 'get_demo_availability', 'schedule_demo',
+]);
+
+/** True when a tool only reads state. */
+function isReadOnly(name) {
+  if (isDestructive(name) || IDEMPOTENT_WRITES.has(name) || NON_IDEMPOTENT_WRITES.has(name)) {
+    return false;
+  }
+  return /^(get_|list_|search_|find_(?!or_create)|count_|describe_|check_|inspect_|rank_|score_|who_am_i|recall|workspace_status|morning_brief|export_data)/.test(name)
+    || name.endsWith('_catalog')
+    || name.endsWith('_analytics')
+    || name.endsWith('_status');
+}
+
+/**
+ * Build honest MCP annotations for a tool. Derived only from the tool's real
+ * behaviour class + domain — NEVER from an untrusted description string.
+ *
+ * @param {string} name
+ * @param {string} [description]
+ * @returns {{ title:string, readOnlyHint:boolean, destructiveHint:boolean,
+ *   idempotentHint:boolean, openWorldHint:boolean, domain:string,
+ *   requiresConfirmation:boolean }}
+ */
+export function buildToolAnnotations(name) {
+  const domain = getToolDomain(name);
+  const readOnly = isReadOnly(name);
+  const destructive = isDestructive(name);
+  // Deletes/revokes are retry-safe; purchases and email sends are destructive
+  // but NOT idempotent — retrying re-spends money or re-sends the email.
+  const nonRetryable = NON_IDEMPOTENT_WRITES.has(name) || /^purchase_|send_email$/.test(name);
+  const idempotent = readOnly
+    || IDEMPOTENT_WRITES.has(name)
+    || (destructive && !nonRetryable);
+  const openWorld = OPEN_WORLD.has(name);
+
+  return {
+    title: titleFor(name),
+    readOnlyHint: readOnly,
+    destructiveHint: destructive,
+    idempotentHint: idempotent,
+    openWorldHint: openWorld,
+    // Adrata extensions (allowed additional properties on ToolAnnotations).
+    domain,
+    // Write/destructive tools should be confirmation-gated by the host and are
+    // additionally tier-gated + audit-logged server-side.
+    requiresConfirmation: !readOnly,
+  };
+}
+
+function titleFor(name) {
+  return name
+    .split('_')
+    .map(w => (w ? w[0].toUpperCase() + w.slice(1) : w))
+    .join(' ');
+}

package/tools/billing.js

@@ -0,0 +1,149 @@
+/**
+ * Billing tools for Adrata MCP Server.
+ *
+ * Provides two tools:
+ *   - upgrade_account: Opens browser to Adrata Edition signup page
+ *   - check_subscription: Returns current plan, usage, and trial status
+ */
+
+import { z } from 'zod';
+import { execFile } from 'node:child_process';
+
+const SIGNUP_URL = 'https://adrata.com/edition/signup';
+
+function openBrowser(url) {
+  if (process.platform === 'darwin') execFile('open', [url], () => {});
+  else if (process.platform === 'win32') {
+    execFile('rundll32.exe', ['url.dll,FileProtocolHandler', url], () => {});
+  } else execFile('xdg-open', [url], () => {});
+}
+
+/**
+ * Register billing tools on the MCP server instance.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {object} options
+ * @param {Function} options.api - HTTP helper for API calls
+ * @param {Function} options.ok - Response formatter
+ * @param {object} options.auth - Authentication context from authenticate()
+ */
+export function registerBillingTools(server, { api, ok, auth }) {
+  // --------------------------------------------------------------------------
+  // upgrade_account — opens browser to signup/upgrade page
+  // --------------------------------------------------------------------------
+  server.tool(
+    'upgrade_account',
+    'Open the Adrata Edition signup page in your browser to upgrade your account. ' +
+    'Free users get a 14-day Pro trial (no credit card required). ' +
+    'Pro users can manage their subscription. ' +
+    'Enterprise users are directed to schedule a demo.',
+    {
+      plan: z.enum(['pro', 'enterprise']).optional()
+        .describe('Target plan: "pro" for self-serve upgrade, "enterprise" for sales contact. Defaults to "pro".'),
+    },
+    async (args) => {
+      const targetPlan = args.plan || 'pro';
+
+      if (targetPlan === 'enterprise') {
+        return ok({
+          action: 'schedule_demo',
+          message: 'Enterprise plans require a conversation with our team. Schedule a demo to get started.',
+          url: 'https://adrata.com/demo',
+          calendar: 'https://cal.com/adrata/enterprise-demo',
+          next_steps: [
+            'Click the demo link above to schedule a call',
+            'Our team will customize a plan for your organization',
+            'Enterprise includes SSO, custom integrations, and dedicated support',
+          ],
+        });
+      }
+
+      // Pro upgrade / signup
+      const url = auth.authenticated
+        ? `${SIGNUP_URL}?upgrade=true`
+        : SIGNUP_URL;
+
+      // Attempt to open browser
+      let browserOpened = false;
+      try {
+        openBrowser(url);
+        browserOpened = true;
+      } catch {
+        browserOpened = false;
+      }
+
+      return ok({
+        action: 'upgrade_to_pro',
+        url,
+        browser_opened: browserOpened,
+        message: browserOpened
+          ? 'Opening signup page in your browser...'
+          : `Open this URL to sign up: ${url}`,
+        plan: {
+          name: 'Adrata Pro',
+          price: '$2,000/seat/year',
+          trial: '14-day free trial, no credit card required',
+          features: [
+            'Full company and contact intelligence',
+            'Buying intent signals and deal authority mapping',
+            'Pipeline analytics and revenue forecasting',
+            'Competitive intelligence briefs',
+            'Priority Pursuits ranked daily action lists',
+            'Meeting summaries and action items',
+            'AI-powered enrichment and scoring',
+          ],
+        },
+      });
+    }
+  );
+
+  // --------------------------------------------------------------------------
+  // check_subscription — returns current plan, usage, and trial status
+  // --------------------------------------------------------------------------
+  server.tool(
+    'check_subscription',
+    'Check your current Adrata subscription plan, usage limits, trial status, and billing details. ' +
+    'Works at all tiers: free users see upgrade options, pro users see usage and trial countdown, ' +
+    'enterprise users see full workspace subscription details.',
+    {},
+    async () => {
+      // Free tier — no API call possible
+      if (!auth.authenticated) {
+        return ok({
+          plan: 'free',
+          status: 'active',
+          usage: {
+            tools_available: 'Search and email tools only',
+            tools_used_today: 'N/A (no tracking in free tier)',
+          },
+          upgrade: {
+            message: 'Upgrade to Pro for full intelligence and analytics.',
+            url: SIGNUP_URL,
+            trial: '14-day free trial, no credit card required',
+          },
+        });
+      }
+
+      // Pro or Enterprise — fetch subscription from API
+      try {
+        const data = await api('GET', '/api/v1/mcp/subscription');
+        return ok({
+          plan: data.plan || auth.tier,
+          status: data.status || 'active',
+          trial: data.trial || null,
+          usage: data.usage || null,
+          billing: data.billing || null,
+          manage_url: data.manage_url || null,
+        });
+      } catch (err) {
+        // Fallback if endpoint not available yet
+        return ok({
+          plan: auth.tier,
+          status: 'active',
+          message: 'Subscription details are available in your Adrata dashboard.',
+          dashboard_url: 'https://app.adrata.com/settings/billing',
+        });
+      }
+    }
+  );
+}