@adrata/adrata-mcp 1.0.1 → 1.0.2

package/toolsets/crm.js

@@ -9,6 +9,23 @@ import { z } from 'zod';
 import {
   md, mdError, table, formatEntityTimeline, formatDate,
 } from '../output-formatter.js';
+import {
+  governedWriteArgs, governedWriteNote, isLiveWrite, runGovernedMarkdownWrite,
+  enrichCostLine, COMPANY_ENRICH_COST_SENTENCE, PERSON_ENRICH_COST_SENTENCE,
+} from '../governance/governed-args.js';
+
+/**
+ * The `manage_*` tools are composites: one tool, one `action` argument, reads
+ * and writes side by side. Only the write actions are governed — a `get`,
+ * `list`, `search` or `timeline` must keep working exactly as before, with no
+ * new required arguments and no preview step.
+ *
+ * This is the list of actions that mutate. Everything not in it is a read.
+ */
+const WRITE_ACTIONS = new Set([
+  'create', 'update', 'delete', 'enrich', 'complete',
+  'bulk_delete', 'add_member', 'update_member', 'remove_member',
+]);
 
 export function register(server, api, AUTH) {
 
@@ -17,7 +34,10 @@ export function register(server, api, AUTH) {
   // -----------------------------------------------------------------------
   server.tool(
     'manage_company',
-    'Full CRUD for companies: create, read, update, delete, enrich, and view activity timeline. One tool for all company operations.',
+    'Full CRUD for companies: create, read, update, delete, enrich, and view activity timeline. One tool for all company operations.'
+    + ' Reads (get/search/timeline) run directly. create/update/delete/enrich are governed writes.'
+    + COMPANY_ENRICH_COST_SENTENCE
+    + governedWriteNote('write:companies'),
     {
       action: z.enum(['create', 'get', 'update', 'delete', 'enrich', 'timeline', 'search']).describe('Operation'),
       id: z.string().optional().describe('Company ID (for get/update/delete/enrich/timeline)'),
@@ -28,6 +48,7 @@ export function register(server, api, AUTH) {
       status: z.string().optional().describe('ACTIVE, PROSPECT, CUSTOMER, CHURNED'),
       customFields: z.record(z.unknown()).optional().describe('Custom fields (JSONB merged)'),
       query: z.string().optional().describe('Search query (for search action)'),
+      ...governedWriteArgs(z),
     },
     async (args) => {
       try {
@@ -40,9 +61,20 @@ export function register(server, api, AUTH) {
             if (args.website) body.website = args.website;
             if (args.status) body.status = args.status;
             if (args.customFields) body.customFields = args.customFields;
-            const result = await api('POST', '/api/v1/companies', { body });
-            const c = result?.data || result;
-            return md(`## Company Created\n\n- **Name:** ${c.name || args.name}\n- **ID:** ${c.id || '\u2014'}\n- **Status:** ${c.status || 'PROSPECT'}\n`);
+            return runGovernedMarkdownWrite(
+              api, args,
+              {
+                method: 'POST',
+                path: '/api/v1/companies',
+                body,
+                heading: 'Create Company',
+                preview: { entity: 'company', operation: 'create', fields: Object.keys(body) },
+              },
+              (result) => {
+                const c = result?.data || result || {};
+                return `## Company Created\n\n- **Name:** ${c.name || args.name}\n- **ID:** ${c.id || '\u2014'}\n- **Status:** ${c.status || 'PROSPECT'}\n`;
+              },
+            );
           }
           case 'get': {
             const c = await api('GET', `/api/v1/companies/${args.id}`);
@@ -64,16 +96,46 @@ export function register(server, api, AUTH) {
             if (args.website) body.website = args.website;
             if (args.status) body.status = args.status;
             if (args.customFields) body.customFields = args.customFields;
-            await api('PATCH', `/api/v1/companies/${args.id}`, { body });
-            return md(`## Company Updated\n\nID: ${args.id}\nFields updated: ${Object.keys(body).join(', ')}\n`);
+            return runGovernedMarkdownWrite(
+              api, args,
+              {
+                method: 'PATCH',
+                path: `/api/v1/companies/${args.id}`,
+                body,
+                heading: 'Update Company',
+                preview: { entity: 'company', entityId: args.id, operation: 'update', fields: Object.keys(body) },
+              },
+              () => `## Company Updated\n\nID: ${args.id}\nFields updated: ${Object.keys(body).join(', ')}\n`,
+            );
           }
           case 'delete': {
-            await api('DELETE', `/api/v1/companies/${args.id}`);
-            return md(`## Company Deleted\n\nID: ${args.id}\n`);
+            return runGovernedMarkdownWrite(
+              api, args,
+              {
+                method: 'DELETE',
+                path: `/api/v1/companies/${args.id}`,
+                heading: 'Delete Company',
+                preview: { entity: 'company', entityId: args.id, operation: 'soft-delete' },
+              },
+              () => `## Company Deleted\n\nID: ${args.id}\n`,
+            );
           }
           case 'enrich': {
-            await api('POST', `/api/v1/companies/${args.id}/enrich`);
-            return md(`## Enrichment Triggered\n\nCompany ID: ${args.id}\nData will be available shortly.\n`);
+            return runGovernedMarkdownWrite(
+              api, args,
+              {
+                method: 'POST',
+                path: `/api/v1/companies/${args.id}/enrich`,
+                heading: 'Enrich Company',
+                preview: {
+                  entity: 'company',
+                  entityId: args.id,
+                  operation: 'enrich',
+                  cost: enrichCostLine('company'),
+                },
+              },
+              () => `## Enrichment Triggered\n\nCompany ID: ${args.id}\nCost: ${enrichCostLine('company')}\nData will be available shortly.\n`,
+            );
           }
           case 'timeline': {
             const [company, actions] = await Promise.all([

package/toolsets/prospecting.js

@@ -12,6 +12,89 @@ import {
   formatQualification, formatCompanyResearch, formatPersonResearch,
   formatSpeedrunList, formatNextContacts, table, signalEmoji, formatDate, daysSince,
 } from '../output-formatter.js';
+import {
+  governedWriteArgs, governedWriteNote, isLiveWrite, missingLiveWriteFields,
+  previewMarkdown, enrichCostLine,
+  COMPANY_ENRICH_COST_SENTENCE, PERSON_ENRICH_COST_SENTENCE,
+} from '../governance/governed-args.js';
+import { governedWrite } from '../api-bridge.js';
+
+/**
+ * Run the enrichment leg of a research tool through the governed-write
+ * contract and render the outcome as a Markdown section.
+ *
+ * `research_company` / `research_person` are read tools with one write inside
+ * them: a POST to `/enrich`, which spends real Coresignal credits. They used to
+ * fire that POST on every call with no preview, no audit reason and no
+ * idempotency key — while the IDENTICAL endpoint reached through
+ * `enrich_company` / `enrich_person` in server.js previewed and refused.
+ *
+ * So the reads still run and still produce the report. The enrich is withheld
+ * by default and reported as withheld, with the credit cost named, rather than
+ * being silently skipped — a research report that quietly lost its enrichment
+ * would be worse than one that spent the credits.
+ *
+ * @returns `{ enrichment, section }` — `enrichment` is the live result (or an
+ *          empty object when nothing was executed) so the report renders
+ *          identically either way.
+ */
+async function governedEnrich(api, args, { method, path, kind, subjectId }) {
+  if (isLiveWrite(args)) {
+    const missing = missingLiveWriteFields(args);
+    if (missing.length > 0) {
+      return {
+        enrichment: {},
+        section:
+          `\n---\n\n## Enrichment refused — nothing was spent\n\n` +
+          `A live enrichment write is missing: ${missing.join(', ')}.\n\n` +
+          `- **Would have called:** ${method} ${path}\n` +
+          `- **Cost if executed:** ${enrichCostLine(kind)}\n\n` +
+          `Re-call with \`dryRun:false\` plus ${missing.join(', ')}.\n`,
+      };
+    }
+  }
+
+  try {
+    const outcome = await governedWrite(api, args, {
+      method,
+      path,
+      preview: {
+        entity: kind,
+        entityId: subjectId,
+        operation: 'enrich',
+        cost: enrichCostLine(kind),
+      },
+    });
+
+    if (outcome.dryRun) {
+      return {
+        enrichment: {},
+        section:
+          `\n---\n\n${previewMarkdown('Enrichment', outcome.preview)}` +
+          `\nThe research above was assembled from reads only. No vendor credits were spent.\n`,
+      };
+    }
+
+    return {
+      enrichment: outcome.result || {},
+      section:
+        `\n---\n\n## Enrichment executed\n\n` +
+        `- **Call:** ${method} ${path}\n` +
+        `- **Cost:** ${enrichCostLine(kind)}\n` +
+        `- **Reason:** ${args.reason}\n` +
+        `- **Idempotency key:** ${args.idempotencyKey}\n`,
+    };
+  } catch (err) {
+    return {
+      enrichment: {},
+      section:
+        `\n---\n\n## Enrichment not performed\n\n` +
+        `- **Attempted:** ${method} ${path}\n` +
+        `- **Error:** ${err.message}\n` +
+        `\nThe research above was assembled from reads only.\n`,
+    };
+  }
+}
 
 export function register(server, api, AUTH) {
 
@@ -63,10 +146,14 @@ export function register(server, api, AUTH) {
   // -----------------------------------------------------------------------
   server.tool(
     'research_company',
-    'Deep research report on a company: firmographics, tech stack, funding, news, competitors, intent signals. Orchestrates 5+ API calls into a structured report.',
+    'Deep research report on a company: firmographics, tech stack, funding, news, competitors, intent signals. Orchestrates 5+ API calls into a structured report.'
+    + ' The reads always run. The enrichment leg is a governed write:'
+    + COMPANY_ENRICH_COST_SENTENCE
+    + governedWriteNote('write:companies'),
     {
       companyId: z.string().optional().describe('Company ID'),
       name: z.string().optional().describe('Company name to search'),
+      ...governedWriteArgs(z),
     },
     async (args) => {
       try {
@@ -86,14 +173,22 @@ export function register(server, api, AUTH) {
           return mdError('Provide companyId or name');
         }
 
-        // Parallel enrichment
-        const [enrichment, signals, competitors] = await Promise.all([
-          api('POST', `/api/v1/companies/${companyId}/enrich`).catch(() => ({})),
+        // Reads run unconditionally. The enrich POST is a governed write and
+        // previews by default, so a research call costs zero vendor credits
+        // unless the caller explicitly authorised the spend.
+        const [signals, competitors] = await Promise.all([
           api('GET', '/api/v1/intent-signals', { params: { companyId } }).catch(() => ({ data: [] })),
           api('GET', '/api/v1/competitors', { params: { companyId } }).catch(() => ({ data: [] })),
         ]);
 
-        return md(formatCompanyResearch(company, enrichment, signals, competitors));
+        const { enrichment, section } = await governedEnrich(api, args, {
+          method: 'POST',
+          path: `/api/v1/companies/${companyId}/enrich`,
+          kind: 'company',
+          subjectId: companyId,
+        });
+
+        return md(formatCompanyResearch(company, enrichment, signals, competitors) + section);
       } catch (err) {
         return mdError('Research failed', err.message);
       }
@@ -105,11 +200,15 @@ export function register(server, api, AUTH) {
   // -----------------------------------------------------------------------
   server.tool(
     'research_person',
-    'Deep research on a person: professional profile, communication preferences, intro paths, recent activity. Orchestrates 3+ API calls.',
+    'Deep research on a person: professional profile, communication preferences, intro paths, recent activity. Orchestrates 3+ API calls.'
+    + ' The reads always run. The enrichment leg is a governed write:'
+    + PERSON_ENRICH_COST_SENTENCE
+    + governedWriteNote('write:people'),
     {
       personId: z.string().optional().describe('Person ID'),
       name: z.string().optional().describe('Person name to search'),
       email: z.string().optional().describe('Email to search by'),
+      ...governedWriteArgs(z),
     },
     async (args) => {
       try {
@@ -132,13 +231,20 @@ export function register(server, api, AUTH) {
           return mdError('Provide personId, name, or email');
         }
 
-        // Parallel: enrichment + actions
-        const [enrichment, actions] = await Promise.all([
-          api('POST', `/api/v1/people/${personId}/enrich`).catch(() => ({})),
-          api('GET', '/api/v1/actions', { params: { personId, limit: 10, page: 1 } }).catch(() => ({ data: [] })),
-        ]);
+        // Reads run unconditionally; the enrich POST is governed and previews
+        // by default. A Coresignal collect is 20 credits per person, so an
+        // ungoverned research call was a per-invocation vendor charge.
+        const actions = await api('GET', '/api/v1/actions', { params: { personId, limit: 10, page: 1 } })
+          .catch(() => ({ data: [] }));
+
+        const { enrichment, section } = await governedEnrich(api, args, {
+          method: 'POST',
+          path: `/api/v1/people/${personId}/enrich`,
+          kind: 'person',
+          subjectId: personId,
+        });
 
-        return md(formatPersonResearch(person, enrichment, actions));
+        return md(formatPersonResearch(person, enrichment, actions) + section);
       } catch (err) {
         return mdError('Research failed', err.message);
       }