@adrata/adrata-mcp 1.0.0

package/api-bridge.js

@@ -0,0 +1,499 @@
+const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const SAFE_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+
+const BLOCKED_PREFIXES = [
+  '/api/v1/auth',
+  '/api/v1/api-keys',
+  '/api/v1/billing',
+  '/api/v1/custom-integrations',
+  '/api/v1/integrations',
+  '/api/v1/observability',
+  '/api/v1/users',
+  '/api/v1/webhooks',
+  '/api/v1/webhooks/inbound',
+  '/api/v1/webhooks/stripe',
+  '/auth',
+];
+
+const BLOCKED_SURFACES = {
+  billing: ['/api/v1/billing'],
+  apiKeys: ['/api/v1/api-keys'],
+  observability: ['/api/v1/observability'],
+  users: ['/api/v1/users'],
+  integrations: ['/api/v1/integrations', '/api/v1/custom-integrations'],
+  webhooks: ['/api/v1/webhooks'],
+};
+
+const ALLOWED_PREFIXES = [
+  '/api/v1/actions',
+  '/api/v1/action-columns',
+  '/api/v1/agent-tasks',
+  '/api/v1/afternoon-brief',
+  '/api/v1/ai',
+  '/api/v1/ai-analytics-tools',
+  '/api/v1/ai-chat',
+  '/api/v1/ai-chat-debug',
+  '/api/v1/ai-chat-stream',
+  '/api/v1/ai-communication-tools',
+  '/api/v1/ai-context',
+  '/api/v1/ai-crm-tools',
+  '/api/v1/ai-evaluate',
+  '/api/v1/ai-executive-assistant',
+  '/api/v1/ai-features',
+  '/api/v1/ai-tools',
+  '/api/v1/analytics',
+  '/api/v1/api-keys',
+  '/api/v1/area',
+  '/api/v1/automations',
+  '/api/v1/billing',
+  '/api/v1/briefs',
+  '/api/v1/buyer-group',
+  '/api/v1/buyer-groups',
+  '/api/v1/calendar',
+  '/api/v1/calls',
+  '/api/v1/calling',
+  '/api/v1/campaigns',
+  '/api/v1/capabilities',
+  '/api/v1/causal',
+  '/api/v1/chat',
+  '/api/v1/clients',
+  // Adrata Cloud: governed, workspace-scoped, read-only semantic query over the
+  // bitemporal record substrate.
+  '/api/v1/cloud',
+  '/api/v1/coaching',
+  '/api/v1/common-models',
+  '/api/v1/communications',
+  '/api/v1/companies',
+  '/api/v1/company-lists',
+  '/api/v1/competitors',
+  '/api/v1/compliance',
+  '/api/v1/conformal',
+  '/api/v1/contacts',
+  '/api/v1/conversations',
+  '/api/v1/content',
+  '/api/v1/credits',
+  '/api/v1/crm',
+  '/api/v1/crm-overlay',
+  '/api/v1/crm-providers',
+  '/api/v1/custom-fields',
+  '/api/v1/custom-integrations',
+  '/api/v1/customer-signals',
+  '/api/v1/customers',
+  '/api/v1/data',
+  '/api/v1/data-lake',
+  '/api/v1/deletion',
+  '/api/v1/deal-authority',
+  '/api/v1/diagnostics',
+  '/api/v1/dhc-forecast',
+  '/api/v1/documents',
+  '/api/v1/drive',
+  '/api/v1/editions',
+  '/api/v1/email',
+  '/api/v1/email-analytics',
+  '/api/v1/email-deliverability',
+  '/api/v1/email-intelligence',
+  '/api/v1/email-provisioning',
+  '/api/v1/emails',
+  '/api/v1/engagement',
+  '/api/v1/entities',
+  '/api/v1/env-audit',
+  '/api/v1/events',
+  '/api/v1/evidence',
+  '/api/v1/expansion',
+  '/api/v1/extensions',
+  '/api/v1/feature-flags',
+  '/api/v1/feature-permissions',
+  '/api/v1/files',
+  '/api/v1/forecast',
+  '/api/v1/forecasting',
+  '/api/v1/goal',
+  '/api/v1/icp-drift',
+  '/api/v1/icp-profiles',
+  '/api/v1/icp-scoring',
+  '/api/v1/icp-user-profiles',
+  '/api/v1/identify',
+  '/api/v1/imessage',
+  '/api/v1/inbox',
+  '/api/v1/ingest',
+  '/api/v1/integrations',
+  '/api/v1/intelligence',
+  '/api/v1/intent-signals',
+  '/api/v1/jobs',
+  '/api/v1/knowledge',
+  '/api/v1/lead-lifecycle',
+  '/api/v1/lead-routing',
+  '/api/v1/leads',
+  '/api/v1/leaderboard',
+  '/api/v1/linkedin',
+  '/api/v1/media',
+  '/api/v1/meetings',
+  '/api/v1/memories',
+  '/api/v1/metrics',
+  '/api/v1/migrations',
+  '/api/v1/monaco',
+  '/api/v1/morning-brief',
+  '/api/v1/mcp',
+  '/api/v1/network',
+  '/api/v1/news',
+  '/api/v1/notes',
+  '/api/v1/opportunities',
+  '/api/v1/operations',
+  '/api/v1/orchestration',
+  '/api/v1/outbound',
+  '/api/v1/oauth',
+  '/api/v1/observability',
+  '/api/v1/onboarding',
+  '/api/v1/patterns',
+  '/api/v1/people',
+  '/api/v1/pipeline',
+  '/api/v1/pipeline-stages',
+  '/api/v1/platform',
+  '/api/v1/plays',
+  '/api/v1/privacy',
+  '/api/v1/providers',
+  '/api/v1/quotas',
+  '/api/v1/realtime',
+  '/api/v1/reports',
+  '/api/v1/research',
+  '/api/v1/retention',
+  '/api/v1/revenue',
+  '/api/v1/revenue-cloud',
+  '/api/v1/sales',
+  '/api/v1/scim',
+  '/api/v1/scoring',
+  '/api/v1/security',
+  '/api/v1/self-service',
+  '/api/v1/sequences',
+  '/api/v1/settings',
+  '/api/v1/signals',
+  '/api/v1/signal-triggers',
+  '/api/v1/simple-features',
+  '/api/v1/sms',
+  '/api/v1/sso',
+  '/api/v1/speedrun',
+  '/api/v1/supersets',
+  '/api/v1/survival',
+  '/api/v1/sync',
+  '/api/v1/synthesis',
+  '/api/v1/tasks',
+  '/api/v1/targets',
+  '/api/v1/team',
+  '/api/v1/trash',
+  '/api/v1/usage',
+  '/api/v1/user-voice-profile',
+  '/api/v1/users',
+  '/api/v1/videos',
+  '/api/v1/voice',
+  '/api/v1/warmup',
+  '/api/v1/webhooks',
+  // Starfield's work boards. Reads are ordinary; a card move is a governed
+  // write and goes through the same dryRun/approved/reason/idempotencyKey
+  // contract as every other write on this bridge.
+  '/api/v1/work-board-rollups',
+  '/api/v1/work-boards',
+  '/api/v1/work-items',
+  '/api/v1/workflow-runtime',
+  '/api/v1/workflows',
+  '/api/v1/workspace',
+  '/api/v1/workspace-features',
+  '/api/v1/workspace-settings',
+  '/api/v1/zoho',
+];
+
+function matchesPathPrefix(path, prefix) {
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+
+export function normalizeApiPath(path) {
+  if (!path || typeof path !== 'string') throw new Error('path is required');
+  if (!path.startsWith('/')) throw new Error('path must start with /');
+  if (path.includes('://')) throw new Error('path must be relative, not an absolute URL');
+  return path;
+}
+
+/**
+ * The write scope the API's scope_guard will demand for a given path.
+ *
+ * Longest prefix wins, so `/api/v1/company-lists` does not accidentally match
+ * `/api/v1/companies`. Returns null when no specific scope is known — the
+ * caller then reports "unknown" rather than asserting the write will succeed.
+ */
+const PATH_WRITE_SCOPES = [
+  ['/api/v1/buyer-groups', 'write:buyer-groups'],
+  ['/api/v1/buyer-group', 'write:buyer-groups'],
+  ['/api/v1/opportunities', 'write:opportunities'],
+  ['/api/v1/partnerships', 'write:partnerships'],
+  ['/api/v1/partners', 'write:partnerships'],
+  ['/api/v1/company-lists', 'write:companies'],
+  ['/api/v1/companies', 'write:companies'],
+  ['/api/v1/contacts', 'write:people'],
+  ['/api/v1/people', 'write:people'],
+  ['/api/v1/leads', 'write:people'],
+  ['/api/v1/agent-tasks', 'write:tasks'],
+  ['/api/v1/tasks', 'write:tasks'],
+  ['/api/v1/actions', 'write:actions'],
+];
+
+export function requiredWriteScopeForPath(path) {
+  const normalized = normalizeApiPath(path);
+  let best = null;
+  for (const [prefix, scope] of PATH_WRITE_SCOPES) {
+    if (matchesPathPrefix(normalized, prefix)) {
+      if (!best || prefix.length > best.prefix.length) best = { prefix, scope };
+    }
+  }
+  return best ? best.scope : null;
+}
+
+export function validateApiBridgeRequest({
+  method,
+  path,
+  dryRun,
+  approved,
+  reason,
+  idempotencyKey,
+  grantedScope,
+}) {
+  const normalizedMethod = String(method || 'GET').toUpperCase();
+  const normalizedPath = normalizeApiPath(path);
+
+  if (!SAFE_METHODS.has(normalizedMethod)) {
+    throw new Error(`unsupported method: ${normalizedMethod}`);
+  }
+  if (BLOCKED_PREFIXES.some((prefix) => matchesPathPrefix(normalizedPath, prefix))) {
+    throw new Error(`blocked path for agent bridge: ${normalizedPath}`);
+  }
+  if (!ALLOWED_PREFIXES.some((prefix) => matchesPathPrefix(normalizedPath, prefix))) {
+    throw new Error(`path is outside the agent bridge allowlist: ${normalizedPath}`);
+  }
+
+  const isWrite = WRITE_METHODS.has(normalizedMethod);
+  if (isWrite && dryRun !== false) {
+    // A dry-run used to answer `wouldSend: true` unconditionally, which is the
+    // single most misleading thing this tool could say: it reported success for
+    // a connection holding zero write scopes, so the "safe preview" step
+    // predicted nothing about the live write that followed. Check the scope the
+    // connection actually holds and say so.
+    const requiredScope = requiredWriteScopeForPath(normalizedPath);
+    const held = String(grantedScope || '').split(/\s+/).filter(Boolean);
+    const scopeKnown = requiredScope !== null;
+    const hasScope = scopeKnown ? held.includes(requiredScope) : null;
+    const scopeChecked = grantedScope !== undefined && grantedScope !== null;
+
+    return {
+      dryRun: true,
+      method: normalizedMethod,
+      path: normalizedPath,
+      // Only claim the request would be sent when nothing known blocks it.
+      wouldSend: scopeChecked && scopeKnown ? hasScope : true,
+      requiredScope: requiredScope ?? 'unknown (no mapping for this path)',
+      scopeHeld: scopeChecked ? hasScope : 'not checked (no stored connection)',
+      ...(scopeChecked && scopeKnown && !hasScope
+        ? {
+            blocked: true,
+            reason: `connection lacks ${requiredScope}; the API will reject this with 403 insufficient_scope`,
+            fix: 'run connect_workspace with writeAccess:true and approve the scope on the consent screen',
+          }
+        : {}),
+      requiredForLiveWrite: ['dryRun:false', 'approved:true', 'reason', 'idempotencyKey'],
+      note: 'Dry-run checks method, path allowlist, and write scope. It does NOT validate the body against the endpoint schema.',
+    };
+  }
+
+  if (isWrite) {
+    if (approved !== true) throw new Error('live writes require approved:true');
+    if (!reason || !String(reason).trim()) throw new Error('live writes require a reason');
+    if (!idempotencyKey || !String(idempotencyKey).trim()) {
+      throw new Error('live writes require an idempotencyKey');
+    }
+  }
+
+  return { dryRun: false, method: normalizedMethod, path: normalizedPath };
+}
+
+/**
+ * Make a value safe to put in an HTTP header.
+ *
+ * Header values are a ByteString — Latin-1, one byte per character — and
+ * `fetch` throws outright on anything above U+00FF rather than dropping it:
+ *
+ *   TypeError: Cannot convert argument to a ByteString because the character
+ *   at index 28 has a value of 8212 which is greater than 255.
+ *
+ * 8212 is an em dash. A human writing an audit reason produces em dashes,
+ * curly quotes, arrows and accented names constantly — this repo's own skills
+ * suggest "Picked up — reproducing against staging first" — so without this the
+ * governed write path fails on the most natural reason anybody would type, and
+ * fails at the transport layer where the message names a character index rather
+ * than the field. Measured against the running stack on 2026-08-04: a live
+ * claim threw before the request was ever sent.
+ *
+ * Percent-encoding rather than stripping, because the header is an audit
+ * artefact: silently dropping characters would leave a reason that reads
+ * subtly differently from the one the caller gave. The BODY still carries the
+ * exact text — that is what lands on `work_item_column_history.reason` and what
+ * a human reads on the card — so nothing about the stored record changes here.
+ */
+export function toHeaderValue(value) {
+  return String(value).replace(/[^\x20-\x7E]/g, (character) => encodeURIComponent(character));
+}
+
+export function buildMutationHeaders({
+  reason,
+  idempotencyKey,
+  approved,
+  actor = 'mcp-agent',
+}) {
+  const headers = {};
+  if (reason) headers['X-Adrata-Reason'] = toHeaderValue(reason);
+  if (idempotencyKey) headers['Idempotency-Key'] = toHeaderValue(idempotencyKey);
+  if (approved === true) headers['X-Adrata-Approved'] = 'true';
+  if (actor) headers['X-Adrata-Actor'] = toHeaderValue(actor);
+  return headers;
+}
+
+/**
+ * Run a *typed* tool's write through exactly the governance the generic
+ * `adrata_api_request` bridge enforces.
+ *
+ * # Why this exists
+ *
+ * `validateApiBridgeRequest` + `buildMutationHeaders` were used at only two
+ * call sites (`adrata_api_request` and `move_pipeline_card`). Every typed
+ * write tool called `api()` raw, so the purpose-built tools were strictly LESS
+ * safe than the generic fallback they exist to replace: a caller could delete
+ * 50 buyer rooms — each cascading to its member seats — with one tool call,
+ * no confirmation, no audit reason, and no idempotency key, while the very
+ * same DELETE routed through `adrata_api_request` demanded all three.
+ *
+ * A write therefore previews by default and only executes with
+ * `dryRun:false` + `approved:true` + `reason` + `idempotencyKey`. 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.
+ *
+ * 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.
+ *
+ * @param api      the server's `api(method, path, opts)` callable
+ * @param args     the tool arguments, carrying dryRun/approved/reason/idempotencyKey
+ * @param request  {method, path, body, preview} describing the intended call
+ * @returns `{ dryRun: true, preview }` or `{ dryRun: false, result }`
+ */
+export async function governedWrite(api, args = {}, { method, path, body, preview = {} } = {}) {
+  const validation = validateApiBridgeRequest({
+    method,
+    path,
+    dryRun: args.dryRun,
+    approved: args.approved,
+    reason: args.reason,
+    idempotencyKey: args.idempotencyKey,
+  });
+
+  if (validation.dryRun) {
+    return {
+      dryRun: true,
+      preview: {
+        ...validation,
+        body: body ?? {},
+        ...preview,
+      },
+    };
+  }
+
+  const result = await api(validation.method, validation.path, {
+    body,
+    headers: buildMutationHeaders(args),
+  });
+  return { dryRun: false, result };
+}
+
+export function buildRealtimePayload({
+  workspaceId,
+  userId = 'agent',
+  entityType,
+  entityId,
+  entityName,
+  changes = {},
+  type = 'record_updated',
+  source = 'agent',
+}) {
+  const event = {
+    type,
+    source,
+    workspaceId,
+    userId,
+    timestamp: new Date().toISOString(),
+    entityType,
+    entityId,
+    entityName,
+    changes,
+  };
+
+  if (type === 'pipeline_stage_changed') {
+    event.previousStage = changes.previousStage;
+    event.newStage = changes.newStage;
+  }
+
+  const channels = [`workspace:${workspaceId}`];
+  if (entityType === 'company') channels.push(`company:${entityId}`);
+  if (entityType === 'opportunity') channels.push(`deal:${entityId}`);
+
+  return {
+    channels,
+    event: 'voice-update',
+    data: event,
+  };
+}
+
+export function apiBridgeCatalog() {
+  return {
+    purpose:
+      'Governed headless access to Adrata platform APIs from Claude Code, Codex, and MCP clients.',
+    read: 'GET requests run directly against allowlisted /api/v1 platform APIs.',
+    write:
+      'POST/PUT/PATCH/DELETE default to dry-run. Live writes require dryRun:false, approved:true, reason, and idempotencyKey.',
+    leastPrivilege:
+      'adrata_api_request blocks sensitive administrative surfaces even when their route families exist in the broad platform allowlist. Use purpose-built MCP tools or adrata_ai_tool_execute instead.',
+    approvalEnvelopeGap:
+      'The MCP bridge adds approval, reason, actor, and Idempotency-Key metadata for live writes, but not every downstream API endpoint has a uniform server-side approval/idempotency envelope yet. Treat adrata_api_request as a governed fallback and prefer targeted tools.',
+    realtime: 'Use realtimePublish for UI fan-out, or use move_pipeline_card for board moves.',
+    aiToolDispatcher:
+      'Use adrata_ai_tool_catalog and adrata_ai_tool_execute for the same Channels, external catalogs, ICP ranking, and batch import tools Adrata chat uses.',
+    blocked: BLOCKED_PREFIXES,
+    blockedSurfaces: BLOCKED_SURFACES,
+    allowed: ALLOWED_PREFIXES,
+    examples: [
+      {
+        tool: 'adrata_api_request',
+        read: { method: 'GET', path: '/api/v1/opportunities', params: { limit: 10 } },
+      },
+      {
+        tool: 'move_pipeline_card',
+        write: {
+          entityType: 'opportunity',
+          entityId: 'opp_123',
+          targetStage: 'proposal',
+          targetRank: 1,
+          approved: true,
+          reason: 'User asked agent to move the deal card',
+          idempotencyKey: 'move-opp_123-proposal-1',
+        },
+      },
+      {
+        tool: 'list_external_pipelines',
+        read: { kind: 'company', adapter: 'yc_oss_api', limit: 25 },
+      },
+      {
+        tool: 'import_external_pipeline_members',
+        write: {
+          channelId: '01KF...',
+          topNByIcp: 20,
+          dryRun: false,
+          approved: true,
+          reason: 'User asked agent to import the top-fit external pipeline members',
+        },
+      },
+    ],
+  };
+}

package/governance/money.js

@@ -0,0 +1,141 @@
+/**
+ * Governance envelope for MONEY writes, plus client-side pagination caps for
+ * finance list tools.
+ *
+ * Money writes — partner revenue attribution, finance approval of an
+ * attribution, and committed-vs-consumed revenue records — follow the same
+ * contract as the governed api-bridge (`api-bridge.js`):
+ *
+ *   1. `dryRun` defaults to TRUE. The default call returns a preview of the
+ *      exact request that would be sent (method, path, validated payload) and
+ *      writes nothing.
+ *   2. Live execution requires ALL of:
+ *        - `dryRun: false`
+ *        - `approved: true`      (explicit approval of this specific write)
+ *        - `auditReason`         (non-empty; why the write is happening)
+ *        - `idempotencyKey`      (unique string; reuse the SAME key on retry
+ *                                 so a network blip cannot double-book revenue)
+ *   3. A live write issues exactly one POST, carrying the reason and key as
+ *      `X-Adrata-Reason` / `Idempotency-Key` headers via the shared
+ *      `buildMutationHeaders` helper.
+ *
+ * NOTE: the Rust partner routes (`code/api/src/routes/v1/data/partners.rs`) do
+ * not yet read the `Idempotency-Key` header — server-side dedup enforcement is
+ * a follow-up. The header is sent now so the contract is stable and the API
+ * can start honouring it without another MCP release.
+ */
+
+import { buildMutationHeaders } from '../api-bridge.js';
+
+/** What a caller must supply to turn a preview into a live money write. */
+export const MONEY_WRITE_REQUIREMENTS = Object.freeze([
+  'dryRun:false',
+  'approved:true',
+  'auditReason',
+  'idempotencyKey',
+]);
+
+/**
+ * Decide whether a money-write call is a dry-run preview or a validated live
+ * write. Pure — never performs I/O.
+ *
+ * @returns `{ dryRun: true, ...preview }` for previews, or
+ *          `{ dryRun: false, method, path, body, headers }` for a validated
+ *          live write. Throws when a live write is missing approval, reason,
+ *          or idempotency key.
+ */
+export function evaluateMoneyWrite({
+  tool,
+  method = 'POST',
+  path,
+  payload,
+  dryRun,
+  approved,
+  auditReason,
+  idempotencyKey,
+}) {
+  if (dryRun !== false) {
+    return {
+      dryRun: true,
+      tool,
+      wouldSend: { method, path, body: payload ?? null },
+      requiredForLiveWrite: MONEY_WRITE_REQUIREMENTS,
+      note: 'Dry run — nothing was written. Review the payload above, then re-call with dryRun:false, approved:true, a non-empty auditReason, and an idempotencyKey to execute.',
+    };
+  }
+  if (approved !== true) {
+    throw new Error(
+      `${tool} is a live money write: it requires approved:true (explicit approval), plus auditReason and idempotencyKey. Call without dryRun:false first to preview.`,
+    );
+  }
+  if (!auditReason || !String(auditReason).trim()) {
+    throw new Error(
+      `${tool} is a live money write: it requires a non-empty auditReason explaining why this write is happening.`,
+    );
+  }
+  if (!idempotencyKey || !String(idempotencyKey).trim()) {
+    throw new Error(
+      `${tool} is a live money write: it requires an idempotencyKey (any unique string, e.g. a ULID). Reuse the SAME key when retrying so the write cannot double-book.`,
+    );
+  }
+  return {
+    dryRun: false,
+    method,
+    path,
+    body: payload,
+    headers: buildMutationHeaders({ reason: auditReason, idempotencyKey }),
+  };
+}
+
+/**
+ * Run the full money-write flow against the shared `api` helper: return the
+ * preview on dry-run, or issue exactly one governed request on a validated
+ * live write.
+ */
+export async function executeMoneyWrite(api, spec) {
+  const decision = evaluateMoneyWrite(spec);
+  if (decision.dryRun) return decision;
+  return api(decision.method, decision.path, {
+    body: decision.body,
+    headers: decision.headers,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Client-side pagination caps
+// ---------------------------------------------------------------------------
+
+/**
+ * Hard cap applied when a backing route returns an unbounded list. The Rust
+ * partner sub-list routes (attributions, work-streams, EPMs, consumption) and
+ * the installed-base invoices route accept no limit/offset, so the cap lives
+ * here until the routes grow real pagination.
+ */
+export const CLIENT_PAGE_CAP = 200;
+
+/**
+ * Apply limit/offset to an already-fetched list. Used for tools whose backing
+ * route supports no pagination: the MCP server truncates the response instead
+ * of flooding the model's context. Non-array input passes through untouched.
+ *
+ * @returns `{ rows, page }` — `page` is null for non-array input, otherwise
+ *          `{ limit, offset, returned, totalFetched, truncated, note }`.
+ */
+export function capClientSide(rows, { limit, offset } = {}) {
+  if (!Array.isArray(rows)) return { rows, page: null };
+  const off = Math.max(0, Math.trunc(Number(offset) || 0));
+  const requested = Math.trunc(Number(limit) || 0);
+  const lim = requested > 0 ? Math.min(requested, CLIENT_PAGE_CAP) : CLIENT_PAGE_CAP;
+  const sliced = rows.slice(off, off + lim);
+  return {
+    rows: sliced,
+    page: {
+      limit: lim,
+      offset: off,
+      returned: sliced.length,
+      totalFetched: rows.length,
+      truncated: off + sliced.length < rows.length,
+      note: 'Pagination applied client-side by the MCP server; the backing API route returns the full list.',
+    },
+  };
+}