@adrata/adrata-mcp 1.0.0

package/tools/enterprise-tools.js

@@ -0,0 +1,651 @@
+/**
+ * Enterprise-only tools for Adrata MCP Server.
+ *
+ * These tools require an OAuth-connected workspace (enterprise tier) and provide:
+ *   - bulk_import: CSV data -> create records in bulk
+ *   - export_data: filtered export of records as JSON or CSV
+ *   - custom_field_management: list, create, update custom fields
+ *   - workspace_settings: view workspace configuration
+ *
+ * All tools check workspace capabilities before executing and respect
+ * rate limits per workspace tier.
+ */
+
+import { getWorkspaceCapabilities, hasCapability, fetchWorkspaceCapabilities } from '../access/oauth.js';
+
+// ---------------------------------------------------------------------------
+// Capability checking
+// ---------------------------------------------------------------------------
+
+/**
+ * Module name -> capability flag mapping.
+ * Tools check their module is enabled before executing.
+ */
+const MODULE_CAPABILITIES = {
+  bulk_import: 'bulk_operations',
+  export_data: 'data_export',
+  manage_custom_fields: 'custom_fields',
+  get_workspace_settings: 'workspace_admin',
+};
+
+/**
+ * Check if a module is enabled for the current workspace.
+ * Returns { enabled: true } or { enabled: false, response } with a helpful message.
+ */
+function checkCapability(toolName, ok) {
+  const requiredCap = MODULE_CAPABILITIES[toolName];
+  if (!requiredCap) return { enabled: true };
+
+  const caps = getWorkspaceCapabilities();
+
+  // If capabilities haven't been fetched yet, allow the call
+  // (the API will enforce server-side anyway)
+  if (!caps) return { enabled: true };
+
+  if (hasCapability(requiredCap)) return { enabled: true };
+
+  return {
+    enabled: false,
+    response: ok({
+      error: 'module_not_enabled',
+      tool: toolName,
+      requiredCapability: requiredCap,
+      message: `The "${toolName}" tool requires the "${requiredCap}" module, which is not enabled for your workspace. Contact your Adrata administrator to enable this module.`,
+      currentCapabilities: caps.features || Object.keys(caps).filter(k => caps[k] === true),
+      help: 'Use workspace_settings to view your current workspace configuration and enabled modules.',
+    }),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Rate limiting
+// ---------------------------------------------------------------------------
+
+/** Per-workspace rate limit state */
+const _rateLimitState = {
+  windowStart: Date.now(),
+  requestCount: 0,
+};
+
+/**
+ * Get the rate limit for the current workspace tier.
+ * Enterprise workspaces get higher limits based on capabilities.
+ */
+function getRateLimit() {
+  const caps = getWorkspaceCapabilities();
+  if (caps && caps.rateLimits) {
+    return {
+      maxRequests: caps.rateLimits.maxRequestsPerMinute || 120,
+      windowMs: 60000,
+    };
+  }
+  // Default enterprise rate limit
+  return { maxRequests: 120, windowMs: 60000 };
+}
+
+/**
+ * Check and increment rate limit counter.
+ * Returns { allowed: true } or { allowed: false, response }.
+ */
+function checkRateLimit(toolName, ok) {
+  const limit = getRateLimit();
+  const now = Date.now();
+
+  // Reset window if expired
+  if (now - _rateLimitState.windowStart > limit.windowMs) {
+    _rateLimitState.windowStart = now;
+    _rateLimitState.requestCount = 0;
+  }
+
+  _rateLimitState.requestCount++;
+
+  if (_rateLimitState.requestCount > limit.maxRequests) {
+    const retryAfterMs = limit.windowMs - (now - _rateLimitState.windowStart);
+    return {
+      allowed: false,
+      response: ok({
+        error: 'rate_limit_exceeded',
+        tool: toolName,
+        message: `Rate limit exceeded (${limit.maxRequests} requests per minute). Please wait ${Math.ceil(retryAfterMs / 1000)} seconds before retrying.`,
+        retryAfterSeconds: Math.ceil(retryAfterMs / 1000),
+        limit: limit.maxRequests,
+      }),
+    };
+  }
+
+  return { allowed: true };
+}
+
+// ---------------------------------------------------------------------------
+// CSV parsing helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse CSV string into array of objects.
+ * Handles quoted fields, commas within quotes, and newlines.
+ */
+function parseCSV(csvString) {
+  const lines = csvString.trim().split('\n');
+  if (lines.length < 2) return [];
+
+  // Parse header row
+  const headers = parseLine(lines[0]);
+  const records = [];
+
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    const values = parseLine(line);
+    const record = {};
+    headers.forEach((h, idx) => {
+      const val = values[idx];
+      if (val !== undefined && val !== '') {
+        record[h.trim()] = val;
+      }
+    });
+    if (Object.keys(record).length > 0) records.push(record);
+  }
+
+  return records;
+}
+
+function parseLine(line) {
+  const fields = [];
+  let current = '';
+  let inQuotes = false;
+
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '"') {
+      if (inQuotes && line[i + 1] === '"') {
+        current += '"';
+        i++;
+      } else {
+        inQuotes = !inQuotes;
+      }
+    } else if (ch === ',' && !inQuotes) {
+      fields.push(current.trim());
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  fields.push(current.trim());
+  return fields;
+}
+
+// ---------------------------------------------------------------------------
+// CSV serialization helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert an array of objects to CSV string.
+ */
+function toCSV(records) {
+  if (!records || records.length === 0) return '';
+
+  const headers = [...new Set(records.flatMap(r => Object.keys(r)))];
+  const csvLines = [headers.join(',')];
+
+  for (const record of records) {
+    const values = headers.map(h => {
+      const val = record[h];
+      if (val == null) return '';
+      const str = typeof val === 'object' ? JSON.stringify(val) : String(val);
+      // Escape quotes and wrap in quotes if contains comma, quote, or newline
+      if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+        return `"${str.replace(/"/g, '""')}"`;
+      }
+      return str;
+    });
+    csvLines.push(values.join(','));
+  }
+
+  return csvLines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Register all enterprise-only tools on the MCP server.
+ *
+ * @param {McpServer} server - The MCP server instance (already tier-gated)
+ * @param {object} deps - Dependencies: { z, api, AUTH, ok, API_BASE }
+ */
+export function registerEnterpriseTools(server, { z, api, AUTH, ok, API_BASE }) {
+
+  // ===== BULK IMPORT =====
+
+  server.tool('bulk_import',
+    'Import records in bulk from CSV data. Creates companies, people, or opportunities from structured CSV input. Each row becomes a record. Custom fields are supported via column names prefixed with "cf_" (e.g., cf_industry_segment). Returns created record IDs and any errors. Enterprise only.',
+    {
+      entity: z.enum(['company', 'person', 'opportunity']).describe('Record type to import'),
+      csvData: z.string().describe('CSV string with headers in first row. Standard columns map to entity fields, cf_* columns map to customFields.'),
+      dryRun: z.boolean().optional().describe('If true, validate data without creating records (default: false)'),
+      skipDuplicates: z.boolean().optional().describe('If true, skip records that match existing records by email/domain (default: true)'),
+    },
+    async (args) => {
+      // Check capability
+      const capCheck = checkCapability('bulk_import', ok);
+      if (!capCheck.enabled) return capCheck.response;
+
+      // Check rate limit
+      const rateCheck = checkRateLimit('bulk_import', ok);
+      if (!rateCheck.allowed) return rateCheck.response;
+
+      const records = parseCSV(args.csvData);
+      if (records.length === 0) {
+        return ok({ error: 'empty_csv', message: 'No data rows found in CSV. Ensure the first row contains headers and subsequent rows contain data.' });
+      }
+
+      if (records.length > 500) {
+        return ok({ error: 'too_many_records', message: `CSV contains ${records.length} rows. Maximum is 500 per import. Split your data into smaller batches.` });
+      }
+
+      const endpoint = args.entity === 'company' ? 'companies'
+        : args.entity === 'person' ? 'people'
+        : 'opportunities';
+
+      const skipDuplicates = args.skipDuplicates !== false;
+
+      // Transform records: extract cf_* columns into customFields
+      const transformed = records.map(record => {
+        const base = {};
+        const customFields = {};
+
+        for (const [key, value] of Object.entries(record)) {
+          if (key.startsWith('cf_')) {
+            customFields[key.slice(3)] = value;
+          } else {
+            base[key] = value;
+          }
+        }
+
+        if (Object.keys(customFields).length > 0) {
+          base.customFields = customFields;
+        }
+
+        // Coerce numeric fields
+        if (base.amount) base.amount = parseFloat(base.amount) || 0;
+        if (base.probability) base.probability = parseFloat(base.probability) || 0;
+        if (base.employeeCount) base.employeeCount = parseInt(base.employeeCount, 10) || 0;
+
+        return base;
+      });
+
+      if (args.dryRun) {
+        return ok({
+          dryRun: true,
+          entity: args.entity,
+          recordCount: transformed.length,
+          sampleRecord: transformed[0],
+          columns: Object.keys(records[0]),
+          customFieldColumns: Object.keys(records[0]).filter(k => k.startsWith('cf_')),
+          message: `Dry run: ${transformed.length} ${args.entity} records parsed and ready to import.`,
+        });
+      }
+
+      // Execute import
+      const results = { created: [], skipped: [], errors: [] };
+
+      for (let i = 0; i < transformed.length; i++) {
+        const record = transformed[i];
+        try {
+          // Duplicate check
+          if (skipDuplicates) {
+            const searchKey = args.entity === 'person' ? record.email
+              : args.entity === 'company' ? (record.domain || record.name)
+              : null;
+
+            if (searchKey) {
+              const existing = await api('GET', `/api/v1/${endpoint}`, {
+                params: { search: searchKey, limit: 1, page: 1 },
+              });
+              const matches = existing?.data || [];
+              if (matches.length > 0) {
+                results.skipped.push({ row: i + 2, reason: 'duplicate', key: searchKey });
+                continue;
+              }
+            }
+          }
+
+          const created = await api('POST', `/api/v1/${endpoint}`, { body: record });
+          results.created.push({
+            row: i + 2,
+            id: created?.data?.id || created?.id,
+          });
+        } catch (err) {
+          results.errors.push({
+            row: i + 2,
+            error: err.message.slice(0, 200),
+          });
+        }
+      }
+
+      return ok({
+        entity: args.entity,
+        totalRows: transformed.length,
+        created: results.created.length,
+        skipped: results.skipped.length,
+        errors: results.errors.length,
+        createdIds: results.created.map(r => r.id),
+        skippedDetails: results.skipped.length > 0 ? results.skipped : undefined,
+        errorDetails: results.errors.length > 0 ? results.errors : undefined,
+      });
+    }
+  );
+
+  // ===== EXPORT DATA =====
+
+  server.tool('export_data',
+    'Export records as JSON or CSV with filters. Supports companies, people, opportunities, actions, and notes. Includes custom fields. Enterprise only.',
+    {
+      entity: z.enum(['company', 'person', 'opportunity', 'action', 'note']).describe('Record type to export'),
+      format: z.enum(['json', 'csv']).optional().describe('Output format (default: json)'),
+      filters: z.object({
+        search: z.string().optional(),
+        status: z.string().optional(),
+        companyId: z.string().optional(),
+        stage: z.string().optional(),
+        type: z.string().optional(),
+        ownerId: z.string().optional(),
+      }).optional().describe('Optional filters to narrow the export'),
+      limit: z.number().optional().describe('Max records to export (default 100, max 1000)'),
+      fields: z.array(z.string()).optional().describe('Specific fields to include (default: all)'),
+    },
+    async (args) => {
+      // Check capability
+      const capCheck = checkCapability('export_data', ok);
+      if (!capCheck.enabled) return capCheck.response;
+
+      // Check rate limit
+      const rateCheck = checkRateLimit('export_data', ok);
+      if (!rateCheck.allowed) return rateCheck.response;
+
+      const endpoint = {
+        company: 'companies',
+        person: 'people',
+        opportunity: 'opportunities',
+        action: 'actions',
+        note: 'notes',
+      }[args.entity];
+
+      const exportLimit = Math.min(args.limit || 100, 1000);
+      const format = args.format || 'json';
+
+      // Fetch records (paginate if needed)
+      const allRecords = [];
+      let page = 1;
+      const perPage = Math.min(exportLimit, 100);
+
+      while (allRecords.length < exportLimit) {
+        const params = {
+          ...(args.filters || {}),
+          limit: perPage,
+          page,
+        };
+
+        const data = await api('GET', `/api/v1/${endpoint}`, { params });
+        const records = data?.data || [];
+        if (records.length === 0) break;
+
+        allRecords.push(...records);
+        if (records.length < perPage) break;
+        page++;
+      }
+
+      // Trim to requested limit
+      const exported = allRecords.slice(0, exportLimit);
+
+      // Filter fields if specified
+      let output = exported;
+      if (args.fields && args.fields.length > 0) {
+        output = exported.map(record => {
+          const filtered = {};
+          for (const field of args.fields) {
+            if (record[field] !== undefined) filtered[field] = record[field];
+          }
+          return filtered;
+        });
+      }
+
+      if (format === 'csv') {
+        return ok({
+          entity: args.entity,
+          format: 'csv',
+          recordCount: output.length,
+          csv: toCSV(output),
+        });
+      }
+
+      return ok({
+        entity: args.entity,
+        format: 'json',
+        recordCount: output.length,
+        records: output,
+      });
+    }
+  );
+
+  // ===== CUSTOM FIELD MANAGEMENT =====
+
+  server.tool('manage_custom_fields',
+    'List, create, or update custom fields for an entity type. Custom fields in Adrata are JSONB-merged, so this tool helps discover existing fields, define conventions, and bulk-update field values. Enterprise only.',
+    {
+      action: z.enum(['list', 'create', 'update']).describe('list: discover fields, create: add a new field to records, update: modify field values across records'),
+      entity: z.enum(['company', 'person', 'opportunity']).describe('Entity type'),
+      fieldName: z.string().optional().describe('Field name (required for create/update)'),
+      fieldValue: z.unknown().optional().describe('Default value for create, or new value for update'),
+      targetIds: z.array(z.string()).optional().describe('Record IDs to update (for update action)'),
+      description: z.string().optional().describe('Field description/documentation (stored as cf_meta)'),
+    },
+    async (args) => {
+      // Check capability
+      const capCheck = checkCapability('manage_custom_fields', ok);
+      if (!capCheck.enabled) return capCheck.response;
+
+      // Check rate limit
+      const rateCheck = checkRateLimit('manage_custom_fields', ok);
+      if (!rateCheck.allowed) return rateCheck.response;
+
+      const endpoint = args.entity === 'company' ? 'companies'
+        : args.entity === 'person' ? 'people'
+        : 'opportunities';
+
+      // LIST: discover custom fields across records
+      if (args.action === 'list') {
+        const data = await api('GET', `/api/v1/${endpoint}`, { params: { limit: 100, page: 1 } });
+        const records = data?.data || [];
+        const fieldMap = {};
+
+        for (const record of records) {
+          const cf = record.customFields;
+          if (cf && typeof cf === 'object') {
+            for (const [key, value] of Object.entries(cf)) {
+              if (!fieldMap[key]) {
+                fieldMap[key] = {
+                  name: key,
+                  type: typeof value,
+                  sampleValues: [],
+                  recordCount: 0,
+                };
+              }
+              fieldMap[key].recordCount++;
+              if (fieldMap[key].sampleValues.length < 5) {
+                const sample = typeof value === 'object' ? JSON.stringify(value) : String(value);
+                if (!fieldMap[key].sampleValues.includes(sample)) {
+                  fieldMap[key].sampleValues.push(sample);
+                }
+              }
+            }
+          }
+        }
+
+        return ok({
+          entity: args.entity,
+          recordsSampled: records.length,
+          customFields: Object.values(fieldMap).sort((a, b) => b.recordCount - a.recordCount),
+          note: 'Custom fields are JSONB. Add any field by including it in the customFields object when creating/updating records.',
+        });
+      }
+
+      // CREATE: add a new custom field to specified records (or all)
+      if (args.action === 'create') {
+        if (!args.fieldName) {
+          return ok({ error: 'missing_field_name', message: 'fieldName is required for create action.' });
+        }
+
+        const targets = args.targetIds || [];
+
+        if (targets.length === 0) {
+          // Just document the field convention (no records to update)
+          return ok({
+            entity: args.entity,
+            fieldCreated: args.fieldName,
+            defaultValue: args.fieldValue ?? null,
+            description: args.description || null,
+            message: `Custom field "${args.fieldName}" is now documented. To populate it, update records with customFields: { "${args.fieldName}": value } or specify targetIds to set it on specific records.`,
+          });
+        }
+
+        // Apply to target records
+        const results = { updated: [], errors: [] };
+        for (const id of targets.slice(0, 100)) {
+          try {
+            await api('PATCH', `/api/v1/${endpoint}/${id}`, {
+              body: { customFields: { [args.fieldName]: args.fieldValue ?? null } },
+            });
+            results.updated.push(id);
+          } catch (err) {
+            results.errors.push({ id, error: err.message.slice(0, 100) });
+          }
+        }
+
+        return ok({
+          entity: args.entity,
+          fieldName: args.fieldName,
+          updated: results.updated.length,
+          errors: results.errors.length,
+          errorDetails: results.errors.length > 0 ? results.errors : undefined,
+        });
+      }
+
+      // UPDATE: change a custom field value across records
+      if (args.action === 'update') {
+        if (!args.fieldName) {
+          return ok({ error: 'missing_field_name', message: 'fieldName is required for update action.' });
+        }
+        if (!args.targetIds || args.targetIds.length === 0) {
+          return ok({ error: 'missing_target_ids', message: 'targetIds is required for update action. Provide record IDs to update.' });
+        }
+
+        const results = { updated: [], errors: [] };
+        for (const id of args.targetIds.slice(0, 100)) {
+          try {
+            await api('PATCH', `/api/v1/${endpoint}/${id}`, {
+              body: { customFields: { [args.fieldName]: args.fieldValue } },
+            });
+            results.updated.push(id);
+          } catch (err) {
+            results.errors.push({ id, error: err.message.slice(0, 100) });
+          }
+        }
+
+        return ok({
+          entity: args.entity,
+          fieldName: args.fieldName,
+          newValue: args.fieldValue,
+          updated: results.updated.length,
+          errors: results.errors.length,
+          errorDetails: results.errors.length > 0 ? results.errors : undefined,
+        });
+      }
+    }
+  );
+
+  // ===== WORKSPACE SETTINGS =====
+
+  server.tool('get_workspace_settings',
+    'View your workspace configuration, enabled modules, rate limits, user count, and subscription details. Use this to understand what features are available. Enterprise only.',
+    {},
+    async () => {
+      // Check capability
+      const capCheck = checkCapability('get_workspace_settings', ok);
+      if (!capCheck.enabled) return capCheck.response;
+
+      // Check rate limit
+      const rateCheck = checkRateLimit('get_workspace_settings', ok);
+      if (!rateCheck.allowed) return rateCheck.response;
+
+      // Refresh capabilities from server
+      let caps = getWorkspaceCapabilities();
+      if (!caps && AUTH.token) {
+        caps = await fetchWorkspaceCapabilities(API_BASE, AUTH.token);
+      }
+
+      // Also fetch current user and basic workspace info
+      let currentUser = null;
+      try {
+        currentUser = await api('GET', '/api/v1/users/me');
+      } catch { /* non-critical */ }
+
+      let userCount = null;
+      try {
+        const users = await api('GET', '/api/v1/users', { params: { limit: 1, page: 1 } });
+        userCount = users?.total || users?.meta?.total || null;
+      } catch { /* non-critical */ }
+
+      let recordCounts = null;
+      try {
+        recordCounts = await api('GET', '/api/v1/data/counts');
+      } catch { /* non-critical */ }
+
+      // Report a failed lookup as structured degradation, not English prose in
+      // a data field. This previously returned success with
+      // capabilities:"Unable to fetch workspace capabilities" and
+      // enabledModules:"Unknown", so a caller could not distinguish "this
+      // workspace has no modules" from "the lookup failed" without
+      // string-matching a sentence.
+      return ok({
+        workspace: {
+          capabilitiesAvailable: caps != null,
+          capabilities: caps ?? null,
+          enabledModules: caps?.features ?? null,
+          rateLimits: caps?.rateLimits || { maxRequestsPerMinute: 120 },
+          ...(caps == null
+            ? { degraded: 'capabilities lookup failed; fields are null rather than empty' }
+            : {}),
+        },
+        currentUser: currentUser?.data || currentUser,
+        teamSize: userCount,
+        recordCounts: recordCounts?.data || recordCounts,
+        auth: {
+          tier: AUTH.tier,
+          source: AUTH.source,
+          apiBase: API_BASE,
+        },
+      });
+    }
+  );
+}
+
+/**
+ * Wrap an existing tool handler with capability checking.
+ * Used to add capability checks to the existing 67 tools.
+ *
+ * @param {string} toolName - Tool name
+ * @param {string} capabilityName - Required capability
+ * @param {function} ok - The ok() helper
+ * @returns {function} Wrapper that checks capability before delegating
+ */
+export function withCapabilityCheck(toolName, capabilityName, ok) {
+  return (originalHandler) => {
+    return async (...args) => {
+      const capCheck = checkCapability(toolName, ok);
+      if (!capCheck.enabled) return capCheck.response;
+      return originalHandler(...args);
+    };
+  };
+}