@adrata/adrata-mcp 1.0.0 → 1.0.2

package/governance/governed-args.js

@@ -0,0 +1,261 @@
+/**
+ * Shared governed-write plumbing for the toolset packs.
+ *
+ * # Why this file exists
+ *
+ * `governedWrite` (api-bridge.js) is the enforcement point: a write previews by
+ * default and only executes with `dryRun:false` + `approved:true` + a non-empty
+ * `reason` + a non-empty `idempotencyKey`. server.js wired 18 tools to it, but
+ * it did so with two private helpers — `governedWriteArgs` (the zod fields) and
+ * `governedWriteNote` (the description sentence) — that live inside server.js
+ * and cannot be imported. Every other pack (`toolsets/*.js`, `tools/*.js`) was
+ * therefore left calling `api()` raw, which is exactly the asymmetry
+ * `governedWrite` was written to end: the purpose-built tool was strictly less
+ * safe than the generic `adrata_api_request` fallback it exists to replace.
+ *
+ * Copying the schema into five files is how a governance contract drifts — one
+ * file gains a field, another keeps the old wording, and the gate silently
+ * differs by tool. So the schema, the description sentence, the refusal text
+ * and the preview renderer live here once, and the packs import them.
+ *
+ * This governs the *client*. It does not replace the server-side scope check:
+ * the API still rejects a token without the matching `write:*` scope with 403
+ * insufficient_scope.
+ *
+ * It lives in `governance/` rather than at the package root next to
+ * `governed-args`-style helpers because `package.json`'s `files:` array names
+ * root modules one by one and whole directories wholesale — `governance/` is
+ * already shipped, a new root file would not be, and packaging.test.js's "ships
+ * every source file" check would fail on a module that exists in the checkout
+ * and is missing from the tarball. `governance/money.js` is the same idea for
+ * money writes, so this is where a governance envelope belongs anyway.
+ */
+
+import { z as defaultZod } from 'zod';
+
+import { governedWrite } from '../api-bridge.js';
+import { md, mdError } from '../output-formatter.js';
+
+/**
+ * Coresignal charges 20 credits for a `collect/{employee_id}` — one person.
+ * See CLAUDE.md ("Coresignal credits are the other real bill") and
+ * `code/api/crates/integrations/src/coresignal/company_multi_source.rs`, whose
+ * `COMPANY_MULTI_SOURCE_CREDITS_PER_CALL` is likewise 20.
+ *
+ * This number is stated in the tool description AND repeated in the preview on
+ * purpose: a caller who only ever reads the preview must still see the bill
+ * before approving it.
+ */
+export const CORESIGNAL_CREDITS_PER_PERSON = 20;
+export const CORESIGNAL_CREDITS_PER_COMPANY = 20;
+
+export const PERSON_ENRICH_COST_SENTENCE =
+  ` SPENDS VENDOR CREDITS: a Coresignal collect is ${CORESIGNAL_CREDITS_PER_PERSON} credits per person, charged to the workspace's shared credit pool.`;
+
+export const COMPANY_ENRICH_COST_SENTENCE =
+  ` SPENDS VENDOR CREDITS: a Coresignal company multi-source call is ${CORESIGNAL_CREDITS_PER_COMPANY} credits per company, charged to the workspace's shared credit pool.`;
+
+/** The cost line rendered inside an enrich preview. */
+export function enrichCostLine(kind) {
+  return kind === 'company'
+    ? `${CORESIGNAL_CREDITS_PER_COMPANY} Coresignal credits per company (vendor spend, not refundable)`
+    : `${CORESIGNAL_CREDITS_PER_PERSON} Coresignal credits per person (vendor spend, not refundable)`;
+}
+
+/**
+ * Governance fields every governed write tool accepts.
+ *
+ * Takes the caller's `zod` so a pack that receives `z` through its dependency
+ * object (tools/email-tools.js) builds its schema with the same instance the
+ * rest of that tool's schema uses.
+ */
+export function governedWriteArgs(zod = defaultZod) {
+  return {
+    dryRun: zod
+      .boolean()
+      .optional()
+      .describe('Defaults to true. Returns a preview of the exact call instead of performing it. Set false to execute.'),
+    approved: zod
+      .boolean()
+      .optional()
+      .describe('Required (true) for a live write. Records that the caller confirmed the mutation; it does not by itself grant scope.'),
+    reason: zod
+      .string()
+      .optional()
+      .describe('Required for a live write. Recorded as the audit reason (X-Adrata-Reason).'),
+    idempotencyKey: zod
+      .string()
+      .optional()
+      .describe('Required for a live write. Sent as Idempotency-Key so a retry cannot double-apply.'),
+  };
+}
+
+/**
+ * The sentence appended to a governed tool's description.
+ *
+ * It names the scope because that is the one thing the caller cannot guess and
+ * the API will reject them for: a 403 `insufficient_scope` on `write:people`
+ * reads like a bug unless the tool already said which scope it needed. Pass
+ * `null` when the route genuinely requires no OAuth write scope.
+ */
+export function governedWriteNote(scope) {
+  const base =
+    ' Governed write: previews by default. A live write requires dryRun:false plus approved:true, a reason, and an idempotencyKey';
+  return scope
+    ? `${base}, and the connection must hold ${scope} (connect_workspace with writeAccess:true).`
+    : `${base}. This route currently requires no OAuth write scope, so approval and audit are the only gate.`;
+}
+
+/** True when the caller has explicitly asked for a live write. */
+export function isLiveWrite(args = {}) {
+  return args?.dryRun === false;
+}
+
+/**
+ * Which authorization fields a live write is still missing.
+ *
+ * `validateApiBridgeRequest` throws on the first one it finds, which tells a
+ * caller to add a reason and then, one round trip later, to add an idempotency
+ * key. Listing them together is the same gate, said once.
+ */
+export function missingLiveWriteFields(args = {}) {
+  const missing = [];
+  if (args.approved !== true) missing.push('approved:true');
+  if (!args.reason || !String(args.reason).trim()) missing.push('reason');
+  if (!args.idempotencyKey || !String(args.idempotencyKey).trim()) missing.push('idempotencyKey');
+  return missing;
+}
+
+/** The refusal payload for a live write that is missing authorization fields. */
+export function liveWriteRefusal(args = {}, request = {}) {
+  const missing = missingLiveWriteFields(args);
+  return {
+    error: true,
+    refused: true,
+    missing,
+    message:
+      `live write refused: missing ${missing.join(', ')}. ` +
+      `Nothing was sent to ${request.method || 'the API'} ${request.path || ''}`.trimEnd() + '.',
+    wouldHaveCalled: { method: request.method, path: request.path },
+  };
+}
+
+const PREVIEW_LABELS = {
+  method: 'Method',
+  path: 'Path',
+  wouldSend: 'Would send',
+  requiredScope: 'Required scope',
+  scopeHeld: 'Scope held',
+  entity: 'Entity',
+  entityId: 'Entity ID',
+  operation: 'Operation',
+  cost: 'Cost if executed',
+  affects: 'Would affect',
+  cascade: 'Cascades to',
+};
+
+/**
+ * Render a governed-write preview as Markdown.
+ *
+ * The preview is not a courtesy — it IS the refusal, rendered as the exact call
+ * that was withheld plus what is missing to authorize it. So it always prints
+ * the method and path, never a bare "ok".
+ */
+export function previewMarkdown(heading, preview = {}) {
+  const {
+    method,
+    path,
+    wouldSend,
+    requiredScope,
+    scopeHeld,
+    requiredForLiveWrite,
+    note,
+    body,
+    blocked,
+    fix,
+    reason,
+    ...extra
+  } = preview;
+
+  let text = `## ${heading} — Preview Only (nothing was written)\n\n`;
+  text += `- **Method:** ${method}\n`;
+  text += `- **Path:** ${path}\n`;
+  text += `- **Required scope:** ${requiredScope}\n`;
+  text += `- **Scope held:** ${scopeHeld}\n`;
+
+  for (const [key, value] of Object.entries(extra)) {
+    if (value === undefined || value === null) continue;
+    const label = PREVIEW_LABELS[key] || key;
+    const rendered =
+      typeof value === 'object' ? JSON.stringify(value) : String(value);
+    text += `- **${label}:** ${rendered}\n`;
+  }
+
+  if (blocked) {
+    text += `\n> **Blocked:** ${reason}\n>\n> Fix: ${fix}\n`;
+  }
+
+  if (body && Object.keys(body).length > 0) {
+    text += `\n### Body that would be sent\n\n\`\`\`json\n${JSON.stringify(body, null, 2)}\n\`\`\`\n`;
+  }
+
+  text += `\n### To execute\n\nRe-call with \`dryRun:false\`, \`approved:true\`, a \`reason\`, and an \`idempotencyKey\`.\n`;
+  if (note) text += `\n${note}\n`;
+  return text;
+}
+
+/**
+ * Run a Markdown-returning tool's write through the governed contract.
+ *
+ * @param api       the pack's `api(method, path, opts)` callable
+ * @param args      tool arguments carrying dryRun/approved/reason/idempotencyKey
+ * @param request   {method, path, body, preview, heading}
+ * @param onSuccess (result) => Markdown string, rendered only on a live write
+ */
+export async function runGovernedMarkdownWrite(api, args, request, onSuccess) {
+  const { heading = 'Governed write', ...call } = request;
+
+  if (isLiveWrite(args)) {
+    const missing = missingLiveWriteFields(args);
+    if (missing.length > 0) {
+      return mdError(
+        `Live write refused — missing ${missing.join(', ')}`,
+        `Nothing was sent to ${call.method} ${call.path}. Re-call with dryRun:false plus ${missing.join(', ')}.`,
+      );
+    }
+  }
+
+  try {
+    const outcome = await governedWrite(api, args, call);
+    if (outcome.dryRun) return md(previewMarkdown(heading, outcome.preview));
+    return md(onSuccess(outcome.result));
+  } catch (err) {
+    return mdError(`${heading} failed`, err.message);
+  }
+}
+
+/**
+ * Run a JSON-returning tool's write through the governed contract.
+ *
+ * @param api       the pack's `api(method, path, opts)` callable
+ * @param args      tool arguments carrying dryRun/approved/reason/idempotencyKey
+ * @param request   {method, path, body, preview}
+ * @param ok        the pack's `ok(data)` envelope helper
+ * @param onSuccess (result) => object, merged into the live-write envelope
+ */
+export async function runGovernedJsonWrite(api, args, request, ok, onSuccess = (r) => ({ result: r })) {
+  if (isLiveWrite(args)) {
+    const missing = missingLiveWriteFields(args);
+    if (missing.length > 0) return ok(liveWriteRefusal(args, request));
+  }
+
+  try {
+    const outcome = await governedWrite(api, args, request);
+    if (outcome.dryRun) {
+      return ok({ dryRun: true, executed: false, preview: outcome.preview });
+    }
+    return ok({ dryRun: false, executed: true, ...onSuccess(outcome.result) });
+  } catch (err) {
+    return ok({ error: true, executed: false, message: err.message });
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adrata/adrata-mcp",
-  "version": "1.0.0",
-  "description": "Adrata MCP Server — connect Claude Code, Codex, Gemini, Cursor, and other AI tools to your CRM. 80+ tools for companies, people, deals, actions, buyer groups, warm intros, webhooks, intelligence, and more.",
+  "version": "1.0.2",
+  "description": "Adrata MCP Server \u2014 connect Claude Code, Codex, Gemini, Cursor, and other AI tools to your CRM. 80+ tools for companies, people, deals, actions, buyer groups, warm intros, webhooks, intelligence, and more.",
   "type": "module",
   "main": "server.js",
   "bin": {
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "start": "node server.js",
-    "test": "node --test server.test.js api-bridge.test.js buyer-group-writes.test.js note-writes.test.js mcp-spec.test.js packaging.test.js security.test.js toolsets.test.js access/auth.test.js access/oauth-callback.test.js access/oauth-session.test.js access/oauth-capabilities.test.js tools/email-tools.test.js tools/scheduling.test.js tools/work-board-tools.test.js governance/money.test.js"
+    "test": "node --test server.test.js api-bridge.test.js audit-flush.test.js buyer-group-writes.test.js note-writes.test.js mcp-spec.test.js packaging.test.js product-profile.test.js security.test.js tool-annotations.test.js toolsets.test.js access/auth.test.js access/oauth-callback.test.js access/oauth-session.test.js access/oauth-capabilities.test.js scripts/local-dev-server.test.js tools/email-tools.test.js tools/scheduling.test.js tools/work-board-tools.test.js tools/work-hub/audit.test.js tools/roadmap-tools.test.js governance/money.test.js"
   },
   "keywords": [
     "mcp",
@@ -32,7 +32,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://gitlab.com/adratagit/speedrun"
+    "url": "https://github.com/adrata/adrata",
+    "directory": "code/mcp"
   },
   "homepage": "https://adrata.com",
   "engines": {
@@ -46,6 +47,7 @@
     "transport-http.js",
     "resources.js",
     "tool-annotations.js",
+    "product-profile.js",
     "output-formatter.js",
     "access/",
     "tools/",
@@ -62,7 +64,10 @@
   },
   "overrides": {
     "@hono/node-server": "2.0.12",
-    "fast-uri": "3.1.4",
-    "hono": "4.12.27"
+    "fast-uri": "3.1.5",
+    "hono": "4.12.34"
+  },
+  "bugs": {
+    "url": "https://github.com/adrata/adrata/issues"
   }
 }

package/product-profile.js

@@ -0,0 +1,43 @@
+/** Branded MCP launch profiles over one shared server implementation. */
+export const PRODUCT_PROFILES = Object.freeze({
+  adrata: Object.freeze({ displayName: 'Adrata', domains: null }),
+  bounce: Object.freeze({
+    displayName: 'Bounce',
+    domains: Object.freeze([
+      'actions', 'agent', 'bridge', 'calendar', 'email', 'infra',
+      'meetings', 'sequences', 'webhooks',
+    ]),
+  }),
+  starfield: Object.freeze({
+    displayName: 'Starfield',
+    domains: Object.freeze([
+      'agent', 'board', 'bridge', 'forms', 'surveys', 'webhooks', 'workflows',
+    ]),
+  }),
+});
+
+export function applyProductProfile(env = process.env) {
+  const product = env.ADRATA_MCP_PRODUCT?.trim().toLowerCase();
+  if (!product) return null;
+  const profile = PRODUCT_PROFILES[product];
+  if (!profile) {
+    throw new Error(
+      `Unknown ADRATA_MCP_PRODUCT "${product}". Expected ${Object.keys(PRODUCT_PROFILES).join(', ')}.`,
+    );
+  }
+  if (!env.ADRATA_MCP_SERVER_NAME?.trim()) env.ADRATA_MCP_SERVER_NAME = profile.displayName;
+  // Explicit operator policy wins. A profile only supplies a least-privilege default.
+  if (!env.ADRATA_MCP_ENABLED_DOMAINS?.trim() && profile.domains) {
+    env.ADRATA_MCP_ENABLED_DOMAINS = profile.domains.join(',');
+  }
+  return profile;
+}
+
+export function assertProductCapabilityRef(ref, product) {
+  const normalizedProduct = String(product ?? '').trim().toLowerCase();
+  if (!normalizedProduct) return ref;
+  if (typeof ref !== 'string' || !ref.startsWith(`/${normalizedProduct}/`)) {
+    throw new Error(`Capability ${String(ref)} is outside the /${normalizedProduct}/ product scope.`);
+  }
+  return ref;
+}

package/resources.js

@@ -225,18 +225,30 @@ Use connect_workspace to get started.`;
  * @param {Function} apiFn  - The api() helper for server calls
  * @param {object}   auth   - AUTH context { tier, token, apiKey, authenticated }
  */
+export function resourceNamesForProduct(product = process.env.ADRATA_MCP_PRODUCT) {
+  const normalized = String(product ?? '').trim().toLowerCase();
+  return !normalized || normalized === 'adrata'
+    ? ['recent-research', 'sales-playbook', 'workspace-summary']
+    : ['workspace-summary'];
+}
+
 export function registerResources(server, apiFn, auth) {
-  server.resource(
-    'recent-research',
-    'adrata://recent-research',
-    buildRecentResearchHandler(apiFn, auth)
-  );
+  const enabled = new Set(resourceNamesForProduct());
+  if (enabled.has('recent-research')) {
+    server.resource(
+      'recent-research',
+      'adrata://recent-research',
+      buildRecentResearchHandler(apiFn, auth)
+    );
+  }
 
-  server.resource(
-    'sales-playbook',
-    'adrata://guide/sales-playbook',
-    buildSalesPlaybookHandler()
-  );
+  if (enabled.has('sales-playbook')) {
+    server.resource(
+      'sales-playbook',
+      'adrata://guide/sales-playbook',
+      buildSalesPlaybookHandler()
+    );
+  }
 
   server.resource(
     'workspace-summary',

package/security.js

@@ -300,6 +300,16 @@ class AuditLogger {
     this.maxBufferedEntries = 1000;
     this.flushIntervalMs = 30_000;
     this.flushing = false;
+    // Consecutive failed flushes. Telemetry is best-effort, so a server that is
+    // permanently unable to accept it must not produce an unbounded stream of
+    // stderr on somebody's terminal: the MCP's own audit endpoint answered 500
+    // to every batch for the whole life of the 1.0.x line, and the visible
+    // result was "[audit] Failed to flush N audit entries" every 30 seconds,
+    // forever, in a client the user is trying to work in. After
+    // `maxConsecutiveFailures` the logger says so ONCE and stands down.
+    this.consecutiveFailures = 0;
+    this.maxConsecutiveFailures = 3;
+    this.disabled = false;
     this.flushTimer = setInterval(() => this.flush(), this.flushIntervalMs);
     if (this.flushTimer.unref) this.flushTimer.unref();
   }
@@ -309,7 +319,7 @@ class AuditLogger {
    * @param {{ tool: string, tier: string, action: string, args: object, userId: string|null, sessionKey: string, timestamp: string }} entry
    */
   log(entry) {
-    if (!TELEMETRY_ENABLED) return;
+    if (!TELEMETRY_ENABLED || this.disabled) return;
 
     this.buffer.push({
       tool: entry.tool,
@@ -332,18 +342,36 @@ class AuditLogger {
    * Silently drops entries if the API is unavailable (non-blocking).
    */
   async flush() {
-    if (this.buffer.length === 0 || this.flushing) return;
+    if (this.buffer.length === 0 || this.flushing || this.disabled) return;
     this.flushing = true;
     const entries = this.buffer.splice(0, this.buffer.length);
 
     if (this.apiFn) {
       try {
         await this.apiFn('POST', '/api/v1/mcp/audit', { body: { entries } });
+        // A success clears the streak; an intermittent outage must not count
+        // toward standing down.
+        this.consecutiveFailures = 0;
       } catch {
-        // Retain a bounded retry buffer. Never retain arbitrary arguments: log()
-        // already redacts and truncates them before they enter this buffer.
-        this.buffer = [...entries, ...this.buffer].slice(-this.maxBufferedEntries);
-        console.error(`[audit] Failed to flush ${entries.length} audit entries; retained for retry`);
+        this.consecutiveFailures += 1;
+        if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
+          // Give up for the life of the process, and drop what we were holding
+          // rather than carrying a doomed batch forever. Telemetry is not worth
+          // a permanent retry loop or a growing buffer in someone's editor.
+          this.disabled = true;
+          this.buffer = [];
+          clearInterval(this.flushTimer);
+          console.error(
+            `[audit] Audit telemetry disabled after ${this.consecutiveFailures} consecutive flush failures. `
+            + 'Tool calls still work; only local usage analytics stop. '
+            + 'Set ADRATA_TELEMETRY=off to disable this at startup.',
+          );
+        } else {
+          // Retain a bounded retry buffer. Never retain arbitrary arguments: log()
+          // already redacts and truncates them before they enter this buffer.
+          this.buffer = [...entries, ...this.buffer].slice(-this.maxBufferedEntries);
+          console.error(`[audit] Failed to flush ${entries.length} audit entries; retained for retry`);
+        }
       } finally {
         this.flushing = false;
       }