@adrata/adrata-mcp 1.0.0

package/toolsets/infrastructure.js

@@ -0,0 +1,757 @@
+/**
+ * Infrastructure Toolset (9 tools, Enterprise tier)
+ *
+ * manage_domains, manage_mailboxes, get_deliverability,
+ * list_provider_catalog, get_provider_connect_plan, list_provider_endpoints,
+ * connect_provider, manage_workspace, manage_data
+ */
+
+import { z } from 'zod';
+import { md, mdError, table, formatDeliverability, formatDate, progressBar } from '../output-formatter.js';
+
+export function register(server, api, AUTH) {
+
+  const DOMAINS_BASE = '/api/v1/email-provisioning/domains';
+  const MAILBOXES_BASE = '/api/v1/email-provisioning/mailboxes';
+
+  /** Resolve a domain id or name to its workspace email-domain record. */
+  async function findDomainRecord(domainOrId) {
+    const result = await api('GET', DOMAINS_BASE, { params: { limit: 200, page: 1 } });
+    const items = result?.data || [];
+    const needle = String(domainOrId || '').trim().toLowerCase();
+    return items.find(d =>
+      d.id === domainOrId || (d.domain && String(d.domain).toLowerCase() === needle)
+    ) || null;
+  }
+
+  // -----------------------------------------------------------------------
+  // manage_domains
+  // -----------------------------------------------------------------------
+  server.tool(
+    'manage_domains',
+    'Add, verify, and configure domains for email sending. Returns SPF/DKIM/DMARC setup instructions and verification status.',
+    {
+      action: z.enum(['add', 'verify', 'get', 'list', 'delete']).describe('Operation'),
+      domain: z.string().optional().describe('Domain name (e.g. outreach.acme.com)'),
+      id: z.string().optional().describe('Domain ID (for verify/get/delete)'),
+    },
+    async (args) => {
+      try {
+        switch (args.action) {
+          case 'add': {
+            const result = await api('POST', DOMAINS_BASE, { body: { domain: args.domain } });
+            const d = result?.data || result || {};
+            let text = `## Domain Added: ${args.domain}\n\n`;
+            text += `- **ID:** ${d.id || '\u2014'}\n`;
+            text += `- **Status:** ${d.status || 'pending'}\n\n`;
+            const records = Array.isArray(d.dnsRecords) ? d.dnsRecords : (d.dnsRecords?.records || []);
+            if (records.length > 0) {
+              text += '### DNS Records to Add\n\n';
+              text += '| Type | Name | Value |\n|------|------|-------|\n';
+              for (const r of records) {
+                text += `| ${r.type || r.recordType || '\u2014'} | ${r.name || r.host || '\u2014'} | ${r.value || r.record || '\u2014'} |\n`;
+              }
+            }
+            text += '\nAfter adding DNS records, run `manage_domains` with action: "verify".\n';
+            return md(text);
+          }
+          case 'verify': {
+            const record = await findDomainRecord(args.id || args.domain);
+            if (!record) return mdError(`Domain ${args.domain || args.id} not found in this workspace. Add it with action: "add".`);
+            const result = await api('POST', `${DOMAINS_BASE}/${encodeURIComponent(record.id)}/verify`);
+            const d = result?.data || result || {};
+            const v = d.verification || {};
+            const pass = (s) => s === 'verified';
+            let text = `## Domain Verification: ${d.domain || args.domain || args.id}\n\n`;
+            text += `- **SPF:** ${pass(v.spf?.status) ? '\u2705 Verified' : '\u274C Not verified'}\n`;
+            text += `- **DKIM:** ${pass(v.dkim?.status) ? '\u2705 Verified' : '\u274C Not verified'}\n`;
+            text += `- **DMARC:** ${pass(v.dmarc?.status) ? '\u2705 Verified' : '\u274C Not verified'}\n`;
+            text += `- **Overall:** ${d.isReady ? '\u2705 Ready to send' : '\u26A0\uFE0F Incomplete'}\n`;
+            return md(text);
+          }
+          case 'get': {
+            // No GET-by-id route exists; resolve from the workspace list.
+            const d = await findDomainRecord(args.id || args.domain);
+            if (!d) return mdError(`Domain ${args.id || args.domain} not found in this workspace.`);
+            let text = `## Domain: ${d.domain || args.id}\n\n`;
+            text += `- **ID:** ${d.id || '\u2014'}\n`;
+            text += `- **Status:** ${d.status || '\u2014'}\n`;
+            text += `- **Verified:** ${d.verified || d.status === 'verified' ? 'Yes' : 'No'}\n`;
+            text += `- **Health:** ${d.health || d.healthScore || '\u2014'}\n`;
+            return md(text);
+          }
+          case 'list': {
+            const result = await api('GET', DOMAINS_BASE, { params: { limit: 25, page: 1 } });
+            const items = result?.data || [];
+            if (items.length === 0) return md('## Domains\n\nNo domains configured. Add one with action: "add".\n');
+            let text = `## ${items.length} Domains\n\n`;
+            const rows = items.map(d => [
+              d.domain || '\u2014',
+              (d.verified || d.status === 'verified') ? '\u2705' : '\u274C',
+              d.health || d.healthScore || '\u2014',
+              d.mailboxCount != null ? String(d.mailboxCount) : '\u2014',
+            ]);
+            text += table(['Domain', 'Verified', 'Health', 'Mailboxes'], rows);
+            return md(text);
+          }
+          case 'delete': {
+            await api('DELETE', `${DOMAINS_BASE}/${encodeURIComponent(args.id)}`);
+            return md(`## Domain Deleted\n\nID: ${args.id}\n`);
+          }
+          default:
+            return mdError(`Unknown action: ${args.action}`);
+        }
+      } catch (err) {
+        return mdError('Domain operation failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // manage_mailboxes
+  // -----------------------------------------------------------------------
+  server.tool(
+    'manage_mailboxes',
+    'Create, configure, and manage sending mailboxes. Toggle warmup, check health, and set sending limits.',
+    {
+      action: z.enum(['create', 'get', 'list', 'update', 'warmup_start', 'warmup_stop', 'delete']).describe('Operation'),
+      id: z.string().optional().describe('Mailbox ID'),
+      email: z.string().optional().describe('Email address for the mailbox'),
+      domainId: z.string().optional().describe('Domain ID'),
+      displayName: z.string().optional().describe('Sender display name'),
+      dailyLimit: z.number().optional().describe('Max emails per day'),
+    },
+    async (args) => {
+      try {
+        switch (args.action) {
+          case 'create': {
+            const result = await api('POST', MAILBOXES_BASE, {
+              body: {
+                email: args.email,
+                domainId: args.domainId,
+                displayName: args.displayName,
+                dailySendLimit: args.dailyLimit || 50,
+              },
+            });
+            const m = result?.data || result || {};
+            let text = `## Mailbox Created\n\n`;
+            text += `- **Email:** ${args.email}\n`;
+            text += `- **ID:** ${m.id || '\u2014'}\n`;
+            text += `- **Daily Limit:** ${args.dailyLimit || 50}\n`;
+            text += `- **Warmup:** Not started\n\n`;
+            text += 'Run with action: "warmup_start" to begin warming up this mailbox.\n';
+            return md(text);
+          }
+          case 'get': {
+            const result = await api('GET', `${MAILBOXES_BASE}/${encodeURIComponent(args.id)}`);
+            const m = result?.data || result || {};
+            let text = `## Mailbox: ${m.email || args.id}\n\n`;
+            text += `- **Status:** ${m.status || '\u2014'}\n`;
+            text += `- **Health:** ${m.health || '\u2014'}\n`;
+            text += `- **Warmup:** ${m.warmupStatus || '\u2014'}\n`;
+            text += `- **Daily Limit:** ${m.dailyLimit || '\u2014'}\n`;
+            text += `- **Sent Today:** ${m.sentToday || 0}\n`;
+            return md(text);
+          }
+          case 'list': {
+            const result = await api('GET', MAILBOXES_BASE, { params: { limit: 25, page: 1 } });
+            const items = result?.data || [];
+            if (items.length === 0) return md('## Mailboxes\n\nNo mailboxes configured.\n');
+            let text = `## ${items.length} Mailboxes\n\n`;
+            const rows = items.map(m => [
+              m.email || '\u2014',
+              m.status || '\u2014',
+              m.warmupStatus || '\u2014',
+              `${m.sentToday || 0}/${m.dailyLimit || '\u2014'}`,
+              m.health || '\u2014',
+            ]);
+            text += table(['Email', 'Status', 'Warmup', 'Sent/Limit', 'Health'], rows);
+            return md(text);
+          }
+          case 'update': {
+            const body = {};
+            if (args.displayName) body.displayName = args.displayName;
+            if (args.dailyLimit) body.dailySendLimit = args.dailyLimit;
+            await api('PATCH', `${MAILBOXES_BASE}/${encodeURIComponent(args.id)}`, { body });
+            return md(`## Mailbox Updated\n\nID: ${args.id}\n`);
+          }
+          case 'warmup_start': {
+            await api('POST', `${MAILBOXES_BASE}/${encodeURIComponent(args.id)}/warmup`, { body: { enable: true } });
+            return md(`## Warmup Started\n\nMailbox: ${args.id}\nWarmup gradually increases send volume over 2-4 weeks to build sender reputation.\n`);
+          }
+          case 'warmup_stop': {
+            await api('POST', `${MAILBOXES_BASE}/${encodeURIComponent(args.id)}/warmup`, { body: { enable: false } });
+            return md(`## Warmup Stopped\n\nMailbox: ${args.id}\n`);
+          }
+          case 'delete': {
+            await api('DELETE', `${MAILBOXES_BASE}/${encodeURIComponent(args.id)}`);
+            return md(`## Mailbox Deleted\n\nID: ${args.id}\n`);
+          }
+          default:
+            return mdError(`Unknown action: ${args.action}`);
+        }
+      } catch (err) {
+        return mdError('Mailbox operation failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // get_deliverability
+  // -----------------------------------------------------------------------
+  server.tool(
+    'get_deliverability',
+    'Domain health check: SPF/DKIM/DMARC status, blacklist check, inbox placement prediction, and sender reputation score.',
+    {
+      domainId: z.string().optional().describe('Domain ID'),
+      domain: z.string().optional().describe('Domain name'),
+    },
+    async (args) => {
+      try {
+        // The deliverability API keys on the domain name; resolve an id first.
+        let domainName = args.domain;
+        if (!domainName && args.domainId) {
+          const record = await findDomainRecord(args.domainId);
+          domainName = record?.domain;
+        }
+        if (!domainName) {
+          return mdError('Deliverability check failed', 'Provide a domain name, or a domainId that exists in this workspace.');
+        }
+        const result = await api('GET', '/api/v1/email-deliverability/check-domain', {
+          params: {
+            domain: domainName,
+            // Required by the route signature but derived server-side from auth.
+            workspaceId: AUTH.workspaceId || 'current',
+          },
+        });
+        const d = result?.data || result || {};
+        let text = formatDeliverability({
+          domainHealth: d.healthScore,
+          spf: d.spf?.status,
+          dkim: d.dkim?.status,
+          dmarc: d.dmarc?.status,
+        });
+        if (Array.isArray(d.recommendations) && d.recommendations.length > 0) {
+          text += '\n### Recommendations\n';
+          for (const r of d.recommendations) text += `- ${typeof r === 'string' ? r : JSON.stringify(r)}\n`;
+        }
+        return md(text);
+      } catch (err) {
+        return mdError('Deliverability check failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // list_provider_catalog
+  // -----------------------------------------------------------------------
+  server.tool(
+    'list_provider_catalog',
+    'List Adrata integration providers with category, auth model, runtime status, headless support, and connect path.',
+    {
+      category: z.string().optional().describe('Optional category filter, e.g. Outbound, Sourcing, CRM'),
+      status: z.string().optional().describe('Optional status filter, e.g. customer_connectable, credential_only, registry_only, planned'),
+    },
+    async (args) => {
+      try {
+        const result = await api('GET', '/api/v1/providers/catalog', {
+          params: Object.fromEntries(Object.entries(args || {}).filter(([, v]) => v != null && v !== '')),
+        });
+        const data = result?.data || result || {};
+        const providers = data.providers || [];
+        if (providers.length === 0) return md('## Provider Catalog\n\nNo providers matched.\n');
+        let text = `## Provider Catalog — ${providers.length} providers\n\n`;
+        text += table(
+          ['Provider', 'Category', 'Status', 'Runtime', 'Auth', 'Headless'],
+          providers.map((p) => [
+            p.name || p.id,
+            p.category || '\u2014',
+            p.status || '\u2014',
+            p.runtime || '\u2014',
+            p.auth || '\u2014',
+            p.headless ? 'yes' : 'no',
+          ])
+        );
+        text += '\nUse `get_provider_connect_plan` or `list_provider_endpoints` for a provider before connecting it.\n';
+        return md(text);
+      } catch (err) {
+        return mdError('Provider catalog failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // get_provider_connect_plan
+  // -----------------------------------------------------------------------
+  server.tool(
+    'get_provider_connect_plan',
+    'Get the exact app/API/MCP/CLI connection plan for an integration provider.',
+    {
+      provider: z.string().describe('Provider id, e.g. gmail, salesforce, heyreach'),
+    },
+    async (args) => {
+      try {
+        const result = await api('GET', `/api/v1/providers/catalog/${encodeURIComponent(args.provider)}/connect`);
+        const data = result?.data || result || {};
+        const provider = data.provider || {};
+        const connect = data.connect || {};
+        let text = `## Connect Plan: ${provider.name || args.provider}\n\n`;
+        text += `- **Status:** ${provider.status || '\u2014'}\n`;
+        text += `- **Runtime:** ${provider.runtime || '\u2014'}\n`;
+        text += `- **Auth:** ${provider.auth || '\u2014'}\n`;
+        text += `- **Headless:** ${data.headless ? 'yes' : 'no'}\n`;
+        if (connect.path) {
+          text += `- **Method:** ${connect.method || '\u2014'}\n`;
+          text += `- **Path:** \`${connect.path}\`\n`;
+          if (connect.body) text += `- **Body:** \`${JSON.stringify(connect.body)}\`\n`;
+        }
+        if (data.warning) text += `\n> ${data.warning}\n`;
+        return md(text);
+      } catch (err) {
+        return mdError('Connect plan failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // list_provider_endpoints
+  // -----------------------------------------------------------------------
+  server.tool(
+    'list_provider_endpoints',
+    'List documented endpoint/actions for an integration provider, including scopes, latency, tags, and billing behavior.',
+    {
+      provider: z.string().describe('Provider id, e.g. heyreach'),
+      search: z.string().optional().describe('Optional endpoint search string'),
+    },
+    async (args) => {
+      try {
+        const result = await api('GET', `/api/v1/providers/catalog/${encodeURIComponent(args.provider)}/endpoints`);
+        const data = result?.data || result || {};
+        const needle = (args.search || '').toLowerCase();
+        const endpoints = (data.endpoints || []).filter((e) => {
+          if (!needle) return true;
+          return [e.method, e.path, e.slug, e.requiredScope, e.description, ...(e.tags || [])].join(' ').toLowerCase().includes(needle);
+        });
+        let text = `## ${data.provider?.name || args.provider} Endpoints — ${endpoints.length}/${data.total || 0}\n\n`;
+        if (endpoints.length === 0) {
+          text += data.coverage === 'connect_contract_only'
+            ? 'No endpoint catalog is published yet. This provider currently exposes only the connect contract.\n'
+            : 'No endpoints matched.\n';
+          return md(text);
+        }
+        text += table(
+          ['Method', 'Path', 'Slug', 'Scope', 'Latency', 'Billing'],
+          endpoints.map((e) => [e.method, e.path, e.slug, e.requiredScope || e.required_scope || '\u2014', e.latency, e.billing])
+        );
+        return md(text);
+      } catch (err) {
+        return mdError('Provider endpoints failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // connect_provider
+  // -----------------------------------------------------------------------
+  server.tool(
+    'connect_provider',
+    'Connect a provider using the backend provider catalog. Supports hosted OAuth providers and generic credential/BYOK providers.',
+    {
+      provider: z.string().describe('Provider id, e.g. gmail, salesforce, heyreach'),
+      scopes: z.array(z.string()).optional().describe('Additional OAuth scopes (advanced)'),
+      workspaceId: z.string().optional().describe('Workspace id required by some OAuth launch routes'),
+      credentials: z.record(z.unknown()).optional().describe('Credential payload for API-key/BYOK providers'),
+      returnUrl: z.string().optional().describe('Optional return URL for OAuth flows'),
+    },
+    async (args) => {
+      try {
+        const planResult = await api('GET', `/api/v1/providers/catalog/${encodeURIComponent(args.provider)}/connect`);
+        const plan = planResult?.data || planResult || {};
+        const provider = plan.provider || {};
+        const connect = plan.connect || {};
+        if (!plan.canConnect) {
+          return mdError('Connection failed', `${args.provider} is not connectable yet. ${plan.warning || ''}`);
+        }
+        if (!connect.path) {
+          return mdError('Connection failed', `${args.provider} is not connectable yet. ${plan.warning || ''}`);
+        }
+
+        let method = connect.method === 'POST' ? 'POST' : undefined;
+        let path = connect.path;
+        let body = connect.body || undefined;
+        const params = {};
+
+        if (args.returnUrl) params.returnUrl = args.returnUrl;
+        if (args.workspaceId && (args.provider === 'salesforce' || args.provider === 'hubspot' || args.provider === 'slack')) {
+          params.workspace_id = args.workspaceId;
+        }
+
+        if (args.provider === 'gmail' || args.provider === 'google_calendar' || args.provider === 'google_meet') {
+          method = 'POST';
+          body = { provider: 'google', scopes: args.scopes };
+        } else if (args.provider === 'outlook') {
+          method = 'POST';
+          body = { provider: 'microsoft', scopes: args.scopes };
+        } else if (path === '/api/v1/integrations') {
+          method = 'POST';
+          body = {
+            provider: args.provider,
+            type: 'grand_central',
+            credentials: args.credentials,
+            config: { source: 'mcp', runtime: provider.runtime, status: provider.status },
+          };
+        } else if (!method) {
+          method = 'GET';
+        }
+
+        const result = await api(method, path, { params, body });
+
+        const r = result?.data || result || {};
+        let text = `## Connect ${args.provider}\n\n`;
+
+        if (r.authUrl) {
+          text += `Authorization URL:\n${r.authUrl}\n\n`;
+          text += 'Open this URL in your browser to complete the connection.\n';
+        } else {
+          text += `- **Status:** ${r.status || 'Initiated'}\n`;
+          text += `- **Provider:** ${args.provider}\n`;
+          text += `- **Runtime:** ${provider.runtime || '\u2014'}\n`;
+          text += `- **Runtime actions:** ${plan.runtimeActions ? 'available' : 'not yet available'}\n`;
+          if (r.message) text += `\n${r.message}\n`;
+          if (plan.warning) text += `\n> ${plan.warning}\n`;
+        }
+
+        return md(text);
+      } catch (err) {
+        return mdError('Connection failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // add_provider_action_column
+  // -----------------------------------------------------------------------
+  server.tool(
+    'add_provider_action_column',
+    'Add a provider action column to a GTM table. Mirrors `adrata action-column add-provider --provider <slug> --table <table_id>` with dry-run policy metadata by default.',
+    {
+      provider: z.string().describe('Provider id, e.g. heyreach, apollo, gmail'),
+      tableId: z.string().describe('Adrata table id'),
+      columnName: z.string().optional().describe('Optional action-column name'),
+      endpoint: z.string().optional().describe('Optional endpoint/tool slug to bind first'),
+      scopes: z.array(z.string()).optional().describe('Scopes required by the provider action'),
+      credentialRef: z.string().optional().describe('Stored credential reference. Required for live requests.'),
+      idempotencyKey: z.string().optional().describe('Stable idempotency key for live requests. Generated when omitted.'),
+      billingClassification: z.string().optional().describe('Billing class for live execution review. Required for live requests.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to submit a live request.'),
+    },
+    async (args) => {
+      const payload = {
+        provider: args.provider,
+        tableId: args.tableId,
+        columnName: args.columnName || `${args.provider}_actions`,
+        endpoint: args.endpoint || null,
+        credentialRef: args.credentialRef || null,
+        idempotencyKey: args.idempotencyKey || null,
+        billingClassification: args.billingClassification || null,
+        scopes: args.scopes || [],
+        dryRun: args.dryRun !== false,
+        policy: {
+          operation: 'action_column.add_provider',
+          permission: 'tables.action_columns.write',
+          auditEvent: 'action_column.provider.add_requested',
+          dryRunRequired: args.dryRun !== false,
+          approvalRequired: true,
+        },
+      };
+      try {
+        const command = await api('POST', '/api/v1/commands', {
+          body: {
+            commandType: 'action_column.add_provider',
+            target: {
+              provider: payload.provider,
+              tableId: payload.tableId,
+              endpoint: payload.endpoint,
+              source: 'mcp',
+            },
+            parameters: payload,
+            dryRun: payload.dryRun,
+            idempotencyKey: payload.dryRun
+              ? null
+              : payload.idempotencyKey || actionColumnIdempotencyKey(payload),
+            reason: `Add ${payload.provider} action column to ${payload.tableId}`,
+          },
+        });
+        if (payload.dryRun) {
+          return md(`## Action Column Dry Run\n\n\`\`\`json\n${JSON.stringify({ command, payload }, null, 2)}\n\`\`\`\n`);
+        }
+        const result = await api('POST', '/api/v1/action-columns/providers', { body: payload });
+        return md(`## Action Column Requested\n\n\`\`\`json\n${JSON.stringify({ command, result }, null, 2)}\n\`\`\`\n`);
+      } catch (err) {
+        return mdError('Action column request failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // manage_workspace
+  // -----------------------------------------------------------------------
+  server.tool(
+    'manage_workspace',
+    'View and update workspace settings, features, team members, and integrations. The admin control panel.',
+    {
+      action: z.enum(['get', 'update', 'list_users', 'list_integrations']).describe('Operation'),
+      settings: z.record(z.unknown()).optional().describe('Settings to update (for update action)'),
+    },
+    async (args) => {
+      try {
+        switch (args.action) {
+          case 'get': {
+            // Parallel: user + counts
+            const [user, counts] = await Promise.all([
+              api('GET', '/api/v1/users/me').catch(() => ({})),
+              api('GET', '/api/v1/data/counts').catch(() => ({})),
+            ]);
+
+            const u = user?.data || user || {};
+            const c = counts?.data || counts || {};
+            let text = `## Workspace\n\n`;
+            text += `- **User:** ${u.name || u.email || '\u2014'}\n`;
+            text += `- **Tier:** ${AUTH.tier}\n`;
+            text += `- **Companies:** ${c.companies || 0}\n`;
+            text += `- **People:** ${c.people || 0}\n`;
+            text += `- **Opportunities:** ${c.opportunities || 0}\n`;
+            return md(text);
+          }
+          case 'update': {
+            // Workspace settings are written one key at a time:
+            // PUT /api/v1/workspace-settings/{setting_key} with { value }.
+            const entries = Object.entries(args.settings || {});
+            if (entries.length === 0) {
+              return mdError('Workspace update failed', 'Provide a settings object, e.g. { "timezone": "America/Los_Angeles" }.');
+            }
+            const updated = [];
+            const failed = [];
+            for (const [key, value] of entries) {
+              try {
+                await api('PUT', `/api/v1/workspace-settings/${encodeURIComponent(key)}`, { body: { value } });
+                updated.push(key);
+              } catch (err) {
+                failed.push(`${key}: ${err.message}`);
+              }
+            }
+            let text = `## Workspace Updated\n\n`;
+            text += `- **Updated:** ${updated.join(', ') || '—'}\n`;
+            if (failed.length > 0) {
+              text += `- **Failed:**\n`;
+              for (const f of failed) text += `  - ${f}\n`;
+            }
+            return md(text);
+          }
+          case 'list_users': {
+            const result = await api('GET', '/api/v1/users', { params: { limit: 50, page: 1 } });
+            const users = result?.data || [];
+            if (users.length === 0) return md('## Team\n\nNo team members found.\n');
+            let text = `## Team \u2014 ${users.length} Members\n\n`;
+            const rows = users.map(u => [u.name || '\u2014', u.email || '\u2014', u.role || '\u2014']);
+            text += table(['Name', 'Email', 'Role'], rows);
+            return md(text);
+          }
+          case 'list_integrations': {
+            const status = await api('GET', '/api/v1/providers/status').catch(() => ({ data: [] }));
+            const integrations = status?.data || [];
+            if (integrations.length === 0) return md('## Integrations\n\nNo integrations connected. Use `connect_provider` to add one.\n');
+            let text = `## ${integrations.length} Integrations\n\n`;
+            const rows = integrations.map(i => [
+              i.provider || i.id || '\u2014',
+              i.status === 'active' || i.status === 'connected' ? '\u2705 Active' : (i.status || '\u274C Inactive'),
+              formatDate(i.connectedAt || i.lastTestedAt || i.updatedAt),
+            ]);
+            text += table(['Provider', 'Status', 'Connected'], rows);
+            return md(text);
+          }
+          default:
+            return mdError(`Unknown action: ${args.action}`);
+        }
+      } catch (err) {
+        return mdError('Workspace operation failed', err.message);
+      }
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // manage_data
+  // -----------------------------------------------------------------------
+  server.tool(
+    'manage_data',
+    'Import CSV data, run bulk operations, check data quality, or export records. The data management swiss army knife.',
+    {
+      action: z.enum(['import', 'export', 'quality_check', 'bulk_update', 'bulk_delete']).describe('Operation'),
+      entityType: z.enum(['companies', 'people', 'opportunities']).optional().describe('Entity type'),
+      csvData: z.string().optional().describe('CSV content for import'),
+      filters: z.record(z.unknown()).optional().describe('Filters for export/bulk operations'),
+      updates: z.record(z.unknown()).optional().describe('Fields to update (for bulk_update)'),
+    },
+    async (args) => {
+      try {
+        switch (args.action) {
+          case 'import': {
+            // The live importer is POST /api/v1/bulk/import. It takes parsed
+            // records, not a raw CSV string. The older data-import route is a
+            // 501 stub and never wrote anything.
+            const records = parseCsvRecords(args.csvData || '');
+            if (records.length === 0) {
+              return mdError('Import failed', 'No data rows found. Provide CSV with a header row and at least one data row.');
+            }
+            const result = await api('POST', '/api/v1/bulk/import', {
+              body: {
+                entityType: args.entityType,
+                records,
+              },
+            });
+            const r = result?.data || result || {};
+            let text = `## Import Complete\n\n`;
+            text += `- **Type:** ${args.entityType}\n`;
+            text += `- **Job:** ${r.jobId || '—'}\n`;
+            text += `- **Records imported:** ${r.processedRecords || 0}\n`;
+            text += `- **Records failed:** ${r.failedRecords || 0}\n`;
+            text += `- **Companies created / updated:** ${r.createdCompanies || 0} / ${r.updatedCompanies || 0}\n`;
+            text += `- **People created / updated:** ${r.createdPeople || 0} / ${r.updatedPeople || 0}\n`;
+            if (Array.isArray(r.errors) && r.errors.length > 0) {
+              text += '\n### Errors\n';
+              r.errors.slice(0, 5).forEach(e => {
+                text += `- ${typeof e === 'string' ? e : `Row ${e.row ?? '—'}: ${e.message || JSON.stringify(e)}`}\n`;
+              });
+            }
+            return md(text);
+          }
+          case 'export': {
+            const result = await api('POST', '/api/v1/bulk/export', {
+              body: {
+                entityType: args.entityType,
+                filters: args.filters,
+              },
+            });
+            const r = result?.data || result || {};
+            let text = `## Export Ready\n\n`;
+            text += `- **Type:** ${args.entityType}\n`;
+            text += `- **Records:** ${r.count || 0}\n`;
+            if (r.downloadUrl) text += `- **Download:** ${r.downloadUrl}\n`;
+            return md(text);
+          }
+          case 'quality_check': {
+            // Real data quality lives under /api/v1/data-quality. The hygiene
+            // rollup covers people records (score, freshness, worst offenders).
+            const result = await api('GET', '/api/v1/data-quality/hygiene');
+            const q = result?.data || result || {};
+            const summary = q.summary || {};
+            let text = `## Data Quality \u2014 People\n\n`;
+            if (args.entityType && args.entityType !== 'people') {
+              text += `> Note: the data-quality API currently reports on people records; "${args.entityType}" is not scoped separately.\n\n`;
+            }
+            if (summary.averageScore != null) {
+              text += `**Average Health Score:** ${summary.averageScore}/100\n`;
+              text += progressBar(summary.averageScore) + '\n\n';
+            }
+            if (summary.total != null) text += `- **Records scored:** ${summary.total}\n`;
+            const dist = summary.distribution || {};
+            for (const [bucket, info] of Object.entries(dist)) {
+              if (info?.count != null) text += `- **${bucket}** (${info.range}): ${info.count} (${info.coverage})\n`;
+            }
+            const fresh = summary.freshness || {};
+            if (fresh.stale != null) text += `- **Stale records (>${fresh.staleThresholdDays || 90}d):** ${fresh.stale}\n`;
+            if (fresh.neverEnriched != null) text += `- **Never enriched:** ${fresh.neverEnriched}\n`;
+            if (Array.isArray(q.worstOffenders) && q.worstOffenders.length > 0) {
+              text += `\n### Worst Offenders (lowest scores)\n`;
+              q.worstOffenders.slice(0, 5).forEach(w => {
+                text += `- ${w.name || `${w.firstName || ''} ${w.lastName || ''}`.trim() || w.id}: ${w.score}/100 (missing: ${(w.missingFields || []).join(', ') || '\u2014'})\n`;
+              });
+            }
+            return md(text);
+          }
+          case 'bulk_update': {
+            return mdError(
+              'bulk_update is not supported',
+              'The Adrata API has no filtered bulk-update endpoint yet. Update records individually (update_company, update_person, update_opportunity) or use export + import.'
+            );
+          }
+          case 'bulk_delete': {
+            return mdError(
+              'bulk_delete is not supported',
+              'The Adrata API has no filtered bulk-delete endpoint yet. Delete records individually (delete_company, delete_person, delete_opportunity).'
+            );
+          }
+          default:
+            return mdError(`Unknown action: ${args.action}`);
+        }
+      } catch (err) {
+        return mdError('Data operation failed', err.message);
+      }
+    }
+  );
+}
+
+/**
+ * Parse a CSV string into an array of row objects keyed by the header row.
+ * Handles quoted fields and escaped double-quotes.
+ */
+function parseCsvRecords(csvString) {
+  const lines = String(csvString).trim().split(/\r?\n/);
+  if (lines.length < 2) return [];
+  const headers = parseCsvLine(lines[0]).map(h => h.trim());
+  const records = [];
+  for (let i = 1; i < lines.length; i += 1) {
+    if (!lines[i].trim()) continue;
+    const values = parseCsvLine(lines[i]);
+    const record = {};
+    headers.forEach((h, idx) => {
+      const val = values[idx];
+      if (h && val !== undefined && val !== '') record[h] = val;
+    });
+    if (Object.keys(record).length > 0) records.push(record);
+  }
+  return records;
+}
+
+function parseCsvLine(line) {
+  const fields = [];
+  let current = '';
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i];
+    if (ch === '"') {
+      if (inQuotes && line[i + 1] === '"') {
+        current += '"';
+        i += 1;
+      } else {
+        inQuotes = !inQuotes;
+      }
+    } else if (ch === ',' && !inQuotes) {
+      fields.push(current);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  fields.push(current);
+  return fields.map(f => f.trim());
+}
+
+function actionColumnIdempotencyKey(payload) {
+  return [
+    'mcp-action-column',
+    stableToken(payload.provider),
+    stableToken(payload.tableId),
+    stableToken(payload.endpoint || 'default'),
+    stableToken(payload.columnName || ''),
+  ].join('-');
+}
+
+function stableToken(value) {
+  const input = String(value || '');
+  let hash = 0;
+  for (let i = 0; i < input.length; i += 1) {
+    hash = (hash * 31 + input.charCodeAt(i)) >>> 0;
+  }
+  return hash.toString(36);
+}