@adrata/adrata-mcp 1.0.1 → 1.0.2

package/server.js

@@ -31,7 +31,13 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { authenticate, reauthenticate, checkToolAccess, assertOAuthIssuerMatchesTarget } from './access/auth.js';
+import {
+  authenticate,
+  reauthenticate,
+  checkToolAccess,
+  assertOAuthIssuerMatchesTarget,
+  getValidAgentToken,
+} from './access/auth.js';
 import { TIERS } from './access/tiers.js';
 import { findCompany, findPerson } from './tools/free-search.js';
 import { applySecurityLayer } from './security.js';
@@ -44,9 +50,11 @@ import { connectWorkspace, disconnectWorkspace, getConnectionStatus, getValidTok
 import { registerEnterpriseTools } from './tools/enterprise-tools.js';
 import { registerEmailTools } from './tools/email-tools.js';
 import { registerWorkBoardTools } from './tools/work-board-tools.js';
+import { registerRoadmapTools } from './tools/roadmap-tools.js';
 import { registerPaperTools } from './tools/paper-tools.js';
 import { register as registerAlwaysLoadedTools } from './toolsets/revenue/always-loaded.js';
 import { register as registerExtensibilityTools } from './toolsets/extensibility.js';
+import { registerSpaceTools } from './toolsets/spaces.js';
 import { getDemoAvailability, scheduleDemo, scheduleMeeting } from './tools/scheduling.js';
 import { registerAnalytics } from './analytics.js';
 import {
@@ -56,8 +64,11 @@ import {
   governedWrite,
   validateApiBridgeRequest,
 } from './api-bridge.js';
-import { buildToolAnnotations, checkDomainScope } from './tool-annotations.js';
+import { buildToolAnnotations, checkDomainScope, shouldRegisterTool } from './tool-annotations.js';
 import { executeMoneyWrite, capClientSide, CLIENT_PAGE_CAP } from './governance/money.js';
+import { applyProductProfile, assertProductCapabilityRef } from './product-profile.js';
+
+applyProductProfile();
 
 let AUTH = authenticate();
 const API_BASE = AUTH.apiUrl || process.env.ADRATA_API_URL || 'https://api.adrata.com';
@@ -132,6 +143,18 @@ async function api(method, path, { params, body, headers: extraHeaders } = {}) {
     }
     currentToken = freshToken;
     auth.token = freshToken;
+  } else if (auth.source === 'agent_config') {
+    let freshToken;
+    try {
+      freshToken = await getValidAgentToken(API_BASE);
+    } catch (err) {
+      throw refreshFailureError(err);
+    }
+    if (!freshToken) {
+      throw new Error('No shared adrata login session found. Run adrata login before using governed tools.');
+    }
+    currentToken = freshToken;
+    auth.token = freshToken;
   }
 
   const headers = { 'Content-Type': 'application/json' };
@@ -168,13 +191,22 @@ async function api(method, path, { params, body, headers: extraHeaders } = {}) {
     auth.token = refreshedToken;
     res = await request(currentToken);
   }
-  // The shared agent session (agent.json) has no refresh path inside the MCP —
-  // the @adrata agent owns rotation. An expired session needs a re-login, and
-  // that must not read like a generic API failure.
   if (res.status === 401 && auth.source === 'agent_config') {
-    throw new Error(
-      'The shared `adrata login` session was rejected (401) — it may have expired. Run `adrata login` (or `@adrata login`) to sign in again.',
-    );
+    let refreshedToken;
+    try {
+      refreshedToken = await getValidAgentToken(API_BASE, {
+        forceRefresh: true,
+        rejectedToken: currentToken,
+      });
+    } catch (err) {
+      throw refreshFailureError(err);
+    }
+    if (!refreshedToken) {
+      throw new Error('No shared adrata login session found. Run adrata login before using governed tools.');
+    }
+    currentToken = refreshedToken;
+    auth.token = refreshedToken;
+    res = await request(currentToken);
   }
 
   const text = await res.text();
@@ -277,6 +309,11 @@ const server = new McpServer({ name: SERVER_NAME, version: '1.0.0' });
 
 const _originalTool = server.tool.bind(server);
 server.tool = function gatedTool(name, ...rest) {
+  // Product-scoped servers do not merely refuse foreign tools after a model
+  // has already loaded their schemas. They omit them from tools/list entirely.
+  // The unprofiled Adrata server retains its full backwards-compatible surface.
+  if (!shouldRegisterTool(name)) return undefined;
+
   // server.tool(name, [description], [schema], handler) — handler is always last.
   const handler = rest[rest.length - 1];
   const gatedHandler = async function gatedHandler(...handlerArgs) {
@@ -472,6 +509,81 @@ server.tool('switch_workspace',
 
 // ===== ADRATA AGENT API BRIDGE =====
 
+const PRODUCT_NAMESPACE = process.env.ADRATA_MCP_PRODUCT?.trim().toLowerCase() || null;
+
+function assertProductCapability(capability, requested) {
+  const ref = capability?.ref;
+  if (!capability?.toolName || typeof ref !== 'string') {
+    throw new Error(`Adrata Cloud returned no exact capability for ${requested}`);
+  }
+  assertProductCapabilityRef(ref, PRODUCT_NAMESPACE);
+  return capability;
+}
+
+async function resolveExactCapability(reference) {
+  const response = await api('GET', '/api/v1/ai/crm-tools/capabilities/describe', {
+    params: { ref: reference },
+  });
+  return assertProductCapability(response?.capability ?? response?.data?.capability, reference);
+}
+
+server.tool('search_capabilities',
+  'Search the authorized capability registry without loading schemas into context. A branded server fixes the namespace to its product. Search is discovery only: describe one exact result before run_capability, and never execute a fuzzy result.',
+  {
+    query: z.string().optional().describe('Plain-language intent. Empty lists a bounded sample.'),
+    namespace: z.string().optional().describe('Optional only on the unprofiled server; a product profile cannot search another product.'),
+    limit: z.number().int().min(1).max(50).optional().describe('Bounded result count; defaults server-side.'),
+  },
+  async (args) => {
+    const requestedNamespace = args.namespace?.trim().toLowerCase();
+    if (PRODUCT_NAMESPACE && requestedNamespace && requestedNamespace !== PRODUCT_NAMESPACE) {
+      throw new Error(`${SERVER_NAME} search is fixed to the ${PRODUCT_NAMESPACE} namespace.`);
+    }
+    return ok(await api('GET', '/api/v1/ai/crm-tools/capabilities/search', {
+      params: {
+        q: args.query,
+        namespace: PRODUCT_NAMESPACE || requestedNamespace,
+        limit: args.limit,
+      },
+    }));
+  });
+
+server.tool('describe_capability',
+  'Resolve one exact, versioned capability reference and return its input schema, risk, and execution metadata. This never executes the capability.',
+  { ref: z.string().describe('Exact /product/domain/action reference; never a fuzzy search phrase.') },
+  async (args) => ok({ capability: await resolveExactCapability(args.ref) }));
+
+server.tool('run_capability',
+  'Run one exact capability through the governed dispatcher. Defaults to dry-run. Live writes remain subject to server-bound approval, reason, spend, policy, and idempotency controls. Product profiles refuse references outside their namespace.',
+  {
+    ref: z.string().describe('Exact /product/domain/action reference returned by search/describe.'),
+    arguments: z.record(z.unknown()).optional(),
+    dryRun: z.boolean().optional().describe('Defaults true. Set false only after reviewing the exact schema and preview.'),
+    reason: z.string().optional(),
+    confirmationToken: z.string().optional().describe('Single-use server-bound token when the capability requires one.'),
+    confirmSpend: z.boolean().optional(),
+    idempotencyKey: z.string().optional().describe('Required by governed live writes/spend. Reuse the same key on retry.'),
+  },
+  async (args) => {
+    const capability = await resolveExactCapability(args.ref);
+    const body = {
+      toolName: capability.toolName,
+      capabilityRef: capability.ref,
+      capabilityVersion: capability.version,
+      arguments: args.arguments || {},
+      dryRun: args.dryRun !== false,
+      ...(args.reason ? { reason: args.reason } : {}),
+      ...(args.confirmationToken ? { confirmationToken: args.confirmationToken } : {}),
+      ...(args.confirmSpend === true ? { confirmSpend: true } : {}),
+      ...(args.idempotencyKey ? { idempotencyKey: args.idempotencyKey } : {}),
+    };
+    const headers = {};
+    if (args.idempotencyKey) headers['idempotency-key'] = args.idempotencyKey;
+    if (args.reason) headers['x-adrata-reason'] = args.reason;
+    if (args.confirmSpend === true) headers['x-adrata-approved'] = 'true';
+    return ok(await api('POST', '/api/v1/ai/crm-tools/execute', { body, headers }));
+  });
+
 server.tool('adrata_api_catalog',
   'Describe the governed Adrata API bridge for Claude Code/Codex. Use this to discover how to call any allowlisted platform API safely from the agent layer.',
   {},
@@ -943,6 +1055,63 @@ server.tool('find_person',
   { name: z.string().describe('Full name of the person to research (e.g. "Patrick Collison", "Jensen Huang")') },
   async (a) => findPerson(a.name));
 
+// ===== GOVERNED WRITES (shared) =====
+//
+// The buyer-group tools below already route every write through `governedWrite`
+// — the same dryRun/approved/reason/idempotencyKey contract `adrata_api_request`
+// enforces. The core record tools did NOT, and they are the ones an agent
+// actually reaches for: measured against the local stack on 2026-08-19,
+// `create_person`, `update_person` and `delete_person` each executed live with
+// no preview, no approval, no audit reason and no idempotency key, while the
+// IDENTICAL `PATCH /api/v1/people/{id}` sent through `adrata_api_request`
+// previewed and refused. The purpose-built tool was strictly less safe than the
+// generic fallback it exists to replace.
+//
+// CLAUDE.md's workspace rules require live CRM writes to carry explicit
+// approval, an audit reason and an idempotency key. These definitions move that
+// from documentation into enforcement for companies, people and notes.
+
+/** Governance fields every governed write tool accepts. */
+const governedWriteArgs = {
+  dryRun: z.boolean().optional().describe('Defaults to true. Returns a preview of the exact call instead of performing it. Set false to execute.'),
+  approved: z.boolean().optional().describe('Required (true) for a live write. Records that the caller confirmed the mutation; it does not by itself grant scope.'),
+  reason: z.string().optional().describe('Required for a live write. Recorded as the audit reason (X-Adrata-Reason).'),
+  idempotencyKey: z.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 scope. `/notes` is one:
+ * it sits in the API's `GRANDFATHERED_UNMAPPED` debt register
+ * (code/api/crates/middleware/src/scope_guard/grandfathered.rs), and there is
+ * no `write:notes` in the scope catalogue at all. Naming one here would invent
+ * a grantable scope that does not exist and send a caller hunting a consent
+ * checkbox they will never find — so the note says what is actually true.
+ */
+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.`;
+}
+
+/** Shared handler: preview object on a dry run, tool payload on a live write. */
+async function runGovernedWrite(args, request, onSuccess = (r) => r) {
+  try {
+    const outcome = await governedWrite(api, args, request);
+    if (outcome.dryRun) return ok(outcome.preview);
+    return ok(onSuccess(outcome.result));
+  } catch (err) {
+    return ok({ error: true, message: err.message });
+  }
+}
+
 // ===== COMPANIES =====
 
 server.tool('search_companies', 'Search companies by name, domain, industry, or status. Returns customFields.',
@@ -952,16 +1121,27 @@ server.tool('search_companies', 'Search companies by name, domain, industry, or
 server.tool('get_company', 'Get full company details including customFields, lastAction, intelligence data.',
   { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/companies/${a.id}`)));
 
-server.tool('create_company', 'Create a new company.',
-  { name: z.string(), domain: z.string().optional(), industry: z.string().optional(), website: z.string().optional(), status: z.string().optional(), customFields: z.record(z.unknown()).optional() },
-  async (a) => ok(await api('POST', '/api/v1/companies', { body: a })));
+server.tool('create_company', `Create a new company.${governedWriteNote('write:companies')}`,
+  { name: z.string(), domain: z.string().optional(), industry: z.string().optional(), website: z.string().optional(), status: z.string().optional(), customFields: z.record(z.unknown()).optional(), ...governedWriteArgs },
+  async ({ dryRun, approved, reason, idempotencyKey, ...f }) => runGovernedWrite(
+    { dryRun, approved, reason, idempotencyKey },
+    { method: 'POST', path: '/api/v1/companies', body: body(f), preview: { entity: 'company', operation: 'create' } },
+  ));
 
-server.tool('update_company', 'Update company fields. customFields are JSONB-merged.',
-  { id: z.string(), name: z.string().optional(), industry: z.string().optional(), website: z.string().optional(), status: z.string().optional(), customFields: z.record(z.unknown()).optional() },
-  async ({ id, ...f }) => ok(await api('PATCH', `/api/v1/companies/${id}`, { body: body(f) })));
+server.tool('update_company', `Update company fields. customFields are JSONB-merged.${governedWriteNote('write:companies')}`,
+  { id: z.string(), name: z.string().optional(), domain: z.string().optional(), industry: z.string().optional(), website: z.string().optional(), status: z.string().optional(), customFields: z.record(z.unknown()).optional(), ...governedWriteArgs },
+  async ({ id, dryRun, approved, reason, idempotencyKey, ...f }) => runGovernedWrite(
+    { dryRun, approved, reason, idempotencyKey },
+    { method: 'PATCH', path: `/api/v1/companies/${id}`, body: body(f), preview: { entity: 'company', entityId: id, operation: 'update', fields: Object.keys(body(f)) } },
+  ));
 
-server.tool('delete_company', 'Soft-delete a company.',
-  { id: z.string() }, async (a) => { await api('DELETE', `/api/v1/companies/${a.id}`); return ok({ deleted: a.id }); });
+server.tool('delete_company', `Soft-delete a company.${governedWriteNote('write:companies')}`,
+  { id: z.string(), ...governedWriteArgs },
+  async ({ id, ...g }) => runGovernedWrite(
+    g,
+    { method: 'DELETE', path: `/api/v1/companies/${id}`, preview: { entity: 'company', entityId: id, operation: 'soft-delete' } },
+    () => ({ deleted: id }),
+  ));
 
 server.tool('get_company_people', 'List all people at a company.',
   { companyId: z.string(), ...page },
@@ -993,7 +1173,7 @@ server.tool('search_people', 'Search people by name, email, company, title. Retu
 server.tool('get_person', 'Get full person details including customFields, lastAction, companyName.',
   { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/people/${a.id}`)));
 
-server.tool('create_person', 'Create a new person/contact. Set contactCategory:"Introducer" for someone you know who is NOT a sales target — they stay out of pipeline. Set customFields.researchOnly:true to suppress buyer-room and pursuit side effects on import.',
+server.tool('create_person', `Create a new person/contact. Set contactCategory:"Introducer" for someone you know who is NOT a sales target — they stay out of pipeline. Set customFields.researchOnly:true to suppress buyer-room and pursuit side effects on import.${governedWriteNote('write:people')}`,
   {
     name: z.string().optional(), firstName: z.string().optional(), lastName: z.string().optional(),
     email: z.string().optional(), phone: z.string().optional(), title: z.string().optional(),
@@ -1004,15 +1184,27 @@ server.tool('create_person', 'Create a new person/contact. Set contactCategory:"
     linkedinUrl: z.string().optional(),
     customFields: z.record(z.unknown()).optional()
       .describe('Set researchOnly:true to suppress automatic Room creation and pursuit side effects.'),
+    ...governedWriteArgs,
   },
-  async (a) => ok(await api('POST', '/api/v1/people', { body: a })));
+  async ({ dryRun, approved, reason, idempotencyKey, ...f }) => runGovernedWrite(
+    { dryRun, approved, reason, idempotencyKey },
+    { method: 'POST', path: '/api/v1/people', body: body(f), preview: { entity: 'person', operation: 'create' } },
+  ));
 
-server.tool('update_person', 'Update person fields. customFields are JSONB-merged. Works for leads too. Change contactCategory to move someone between pipeline (Lead/Prospect) and known-relationship-only (Introducer).',
-  { id: z.string(), name: z.string().optional(), firstName: z.string().optional(), lastName: z.string().optional(), email: z.string().optional(), title: z.string().optional(), phone: z.string().optional(), status: z.string().optional(), contactCategory: z.enum(['Lead', 'Prospect', 'Introducer']).optional().describe('Lead/Prospect enter pipeline; Introducer is kept out of pipeline.'), linkedinUrl: z.string().optional(), customFields: z.record(z.unknown()).optional() },
-  async ({ id, ...f }) => ok(await api('PATCH', `/api/v1/people/${id}`, { body: body(f) })));
+server.tool('update_person', `Update person fields. customFields are JSONB-merged. Works for leads too. Change contactCategory to move someone between pipeline (Lead/Prospect) and known-relationship-only (Introducer).${governedWriteNote('write:people')}`,
+  { id: z.string(), name: z.string().optional(), firstName: z.string().optional(), lastName: z.string().optional(), email: z.string().optional(), title: z.string().optional(), phone: z.string().optional(), companyId: z.string().optional(), status: z.string().optional(), contactCategory: z.enum(['Lead', 'Prospect', 'Introducer']).optional().describe('Lead/Prospect enter pipeline; Introducer is kept out of pipeline.'), linkedinUrl: z.string().optional(), customFields: z.record(z.unknown()).optional(), ...governedWriteArgs },
+  async ({ id, dryRun, approved, reason, idempotencyKey, ...f }) => runGovernedWrite(
+    { dryRun, approved, reason, idempotencyKey },
+    { method: 'PATCH', path: `/api/v1/people/${id}`, body: body(f), preview: { entity: 'person', entityId: id, operation: 'update', fields: Object.keys(body(f)) } },
+  ));
 
-server.tool('delete_person', 'Soft-delete a person.',
-  { id: z.string() }, async (a) => { await api('DELETE', `/api/v1/people/${a.id}`); return ok({ deleted: a.id }); });
+server.tool('delete_person', `Soft-delete a person.${governedWriteNote('write:people')}`,
+  { id: z.string(), ...governedWriteArgs },
+  async ({ id, ...g }) => runGovernedWrite(
+    g,
+    { method: 'DELETE', path: `/api/v1/people/${id}`, preview: { entity: 'person', entityId: id, operation: 'soft-delete' } },
+    () => ({ deleted: id }),
+  ));
 
 // ===== OPPORTUNITIES =====
 
@@ -1071,20 +1263,31 @@ server.tool('list_today_actions', 'List actions scheduled for today.',
 // the API bound nowhere: create failed validation and update was a silent
 // no-op that still answered 200. Send `content` and keep accepting `body` as
 // the tool-facing argument name so existing agent prompts keep working.
-server.tool('create_note', 'Add a note to a person, company, or opportunity.',
-  { body: z.string().describe('The note text.'), companyId: z.string().optional(), personId: z.string().optional(), opportunityId: z.string().optional() },
-  async ({ body: text, ...rest }) => ok(await api('POST', '/api/v1/notes', { body: { content: text, ...rest } })));
+server.tool('create_note', `Add a note to a person, company, or opportunity.${governedWriteNote(null)}`,
+  { body: z.string().describe('The note text.'), companyId: z.string().optional(), personId: z.string().optional(), opportunityId: z.string().optional(), ...governedWriteArgs },
+  async ({ body: text, dryRun, approved, reason, idempotencyKey, ...rest }) => runGovernedWrite(
+    { dryRun, approved, reason, idempotencyKey },
+    { method: 'POST', path: '/api/v1/notes', body: { content: text, ...body(rest) }, preview: { entity: 'note', operation: 'create' } },
+  ));
 
 server.tool('list_notes', 'List notes, filterable by entity.',
   { companyId: z.string().optional(), personId: z.string().optional(), opportunityId: z.string().optional(), search: z.string().optional(), ...page },
   async (a) => ok(await api('GET', '/api/v1/notes', { params: { ...a, limit: a.limit || 25, page: a.page || 1 } })));
 
-server.tool('update_note', 'Update note content.',
-  { id: z.string(), body: z.string().describe('The new note text.') },
-  async (a) => ok(await api('PUT', `/api/v1/notes/${a.id}`, { body: { content: a.body } })));
+server.tool('update_note', `Update note content.${governedWriteNote(null)}`,
+  { id: z.string(), body: z.string().describe('The new note text.'), ...governedWriteArgs },
+  async ({ id, body: text, ...g }) => runGovernedWrite(
+    g,
+    { method: 'PUT', path: `/api/v1/notes/${id}`, body: { content: text }, preview: { entity: 'note', entityId: id, operation: 'update' } },
+  ));
 
-server.tool('delete_note', 'Delete a note.',
-  { id: z.string() }, async (a) => { await api('DELETE', `/api/v1/notes/${a.id}`); return ok({ deleted: a.id }); });
+server.tool('delete_note', `Delete a note.${governedWriteNote(null)}`,
+  { id: z.string(), ...governedWriteArgs },
+  async ({ id, ...g }) => runGovernedWrite(
+    g,
+    { method: 'DELETE', path: `/api/v1/notes/${id}`, preview: { entity: 'note', entityId: id, operation: 'delete' } },
+    () => ({ deleted: id }),
+  ));
 
 // ===== BUYER GROUPS =====
 //
@@ -1094,27 +1297,10 @@ server.tool('delete_note', 'Delete a note.',
 // enforces — before this, the typed tools bypassed it entirely and were the
 // least governed path to the most destructive operation in the toolset.
 
-/** Governance fields every buyer-group write tool accepts. */
-const governedWriteArgs = {
-  dryRun: z.boolean().optional().describe('Defaults to true. Returns a preview of the exact call instead of performing it. Set false to execute.'),
-  approved: z.boolean().optional().describe('Required (true) for a live write. Records that the caller confirmed the mutation; it does not by itself grant scope.'),
-  reason: z.string().optional().describe('Required for a live write. Recorded as the audit reason (X-Adrata-Reason).'),
-  idempotencyKey: z.string().optional().describe('Required for a live write. Sent as Idempotency-Key so a retry cannot double-apply.'),
-};
-
-const GOVERNED_WRITE_NOTE =
-  ' Governed write: previews by default. A live write requires dryRun:false plus approved:true, a reason, and an idempotencyKey, and the connection must hold write:buyer-groups (connect_workspace with writeAccess:true).';
-
-/** Shared handler shape: preview object on a dry run, tool payload on a live write. */
-async function runGovernedBuyerGroupWrite(args, request, onSuccess) {
-  try {
-    const outcome = await governedWrite(api, args, request);
-    if (outcome.dryRun) return ok(outcome.preview);
-    return ok(onSuccess(outcome.result));
-  } catch (err) {
-    return ok({ error: true, message: err.message });
-  }
-}
+// `governedWriteArgs`, `governedWriteNote` and `runGovernedWrite` are defined
+// once above the COMPANIES section and shared by every governed write tool.
+const GOVERNED_WRITE_NOTE = governedWriteNote('write:buyer-groups');
+const runGovernedBuyerGroupWrite = runGovernedWrite;
 
 server.tool('list_buyer_groups', 'List buyer groups — the decision-making units at companies.',
   { companyId: z.string().optional(), ...page },
@@ -1526,17 +1712,39 @@ server.tool('get_meeting_action_items', 'Get action items from a meeting.',
 
 // ===== INTELLIGENCE =====
 
-server.tool('enrich_company', 'Trigger enrichment for a company — firmographic, news, competitors.',
-  { companyId: z.string() },
-  async (a) => ok(await api('POST', `/api/v1/companies/${a.companyId}/enrich`)));
+// Enrichment is the one write in this file that spends money on every call.
+// A person `collect` is 20 Coresignal credits and a company multi-source call
+// is 20 (see CLAUDE.md's credit table and
+// code/api/crates/integrations/src/coresignal/company_multi_source.rs), drawn
+// from a single unified pool. These two tools were ungoverned POSTs, so an
+// agent could fan enrichment across a list and spend the pool with no preview,
+// no approval and no idempotency key — meaning a retry re-bought the same
+// record. They are governed for cost, not just for audit.
+server.tool('enrich_company', `Trigger enrichment for a company — firmographic, news, competitors. SPENDS VENDOR CREDITS.${governedWriteNote('write:companies')}`,
+  { companyId: z.string(), ...governedWriteArgs },
+  async ({ companyId, ...g }) => runGovernedWrite(
+    g,
+    {
+      method: 'POST',
+      path: `/api/v1/companies/${companyId}/enrich`,
+      preview: { entity: 'company', entityId: companyId, operation: 'enrich', spendsVendorCredits: true },
+    },
+  ));
 
 server.tool('get_company_firmographics', 'Get employee count and revenue metadata for a company, including value/range, source, confidence, freshness, and missing fields.',
   { companyId: z.string() },
   async (a) => ok(await api('GET', `/api/v1/companies/${a.companyId}/firmographics`)));
 
-server.tool('enrich_person', 'Trigger enrichment for a person — professional info, social profiles.',
-  { personId: z.string() },
-  async (a) => ok(await api('POST', `/api/v1/people/${a.personId}/enrich`)));
+server.tool('enrich_person', `Trigger enrichment for a person — professional info, social profiles. SPENDS VENDOR CREDITS (a Coresignal collect is 20 credits per person).${governedWriteNote('write:people')}`,
+  { personId: z.string(), ...governedWriteArgs },
+  async ({ personId, ...g }) => runGovernedWrite(
+    g,
+    {
+      method: 'POST',
+      path: `/api/v1/people/${personId}/enrich`,
+      preview: { entity: 'person', entityId: personId, operation: 'enrich', spendsVendorCredits: true },
+    },
+  ));
 
 server.tool('get_intent_signals', 'Get buying intent signals for a company.',
   { companyId: z.string() },
@@ -2055,6 +2263,17 @@ registerWorkBoardTools(server, {
   ok,
   validateApiBridgeRequest,
   buildMutationHeaders,
+  getGrantedScope: () => loadTokens()?.scope,
+});
+
+// The containers above the cards, and the "add this to the roadmap" verb
+// (company/decisions/2026-08-06-spoq-roadmap-sync.md).
+registerRoadmapTools(server, {
+  z,
+  api,
+  ok,
+  validateApiBridgeRequest,
+  buildMutationHeaders,
 });
 
 // ===== DEMO SCHEDULING: Cal.com integration (free tier) =====
@@ -2120,6 +2339,11 @@ registerAlwaysLoadedTools(server, api, AUTH);
 // still gates activation on policy review.
 registerExtensibilityTools(server, api, AUTH);
 
+// The nine spaces, as reads. These were written, tiered and then never loaded — exported from
+// their module and imported nowhere, so every one of them was dark. An agent asking "what's in
+// Service" got nothing, while the app answered it fine.
+registerSpaceTools(server, { z, api, ok });
+
 // ---------------------------------------------------------------------------
 // Start
 // ---------------------------------------------------------------------------

package/server.json

@@ -35,12 +35,6 @@
       ]
     }
   ],
-  "remotes": [
-    {
-      "type": "streamable-http",
-      "url": "https://mcp.adrata.com/mcp"
-    }
-  ],
   "_meta": {
     "com.adrata": {
       "authorization": {

package/skills/board-review/SKILL.md

@@ -10,6 +10,12 @@ making*. Card counts do not answer it. Time does.
 
 ## Scope
 
+Start with `audit_work_hub` when the question is whether the workspace can be
+trusted as an operating ledger. It checks every visible full board for missing
+owners, missing criteria, missing work types, unhandled active passes, stale
+cards, and truncated reads. Use the board and roll-up reads below when you need
+the narrative behind those named findings.
+
 - One team's board → `get_work_board`.
 - Everything, across every client → `get_work_board_rollup` with `rollupId:
   "all"`. This one has no membership rows, so it always includes a board created
@@ -66,9 +72,11 @@ policy for its own cards.
 
 ## Do not equate tag schemes
 
-Boards can use different vocabularies — severity, priority, kind, impact. A P1
+Boards can use different URGENCY vocabularies — severity, priority, impact. A P1
 is not a Critical, and nothing in this product will translate one into the
-other. Rank within each board's own scheme and report them as they are. If you
+other. (`kind` is NOT one of them: what a card *is* — bug, story, chore — is a
+separate field, orthogonal to how urgent it is, so a card can be a bug AND
+Critical. Read it as `kind` on the card, never as the board's `tagScheme`.) Rank within each board's own scheme and report them as they are. If you
 need a single ordering across boards, say what you ordered by and that it is
 your own reading, not the boards'.
 

package/skills/incident-to-card/SKILL.md

@@ -37,13 +37,19 @@ validates against. The same sentences, doing both jobs. A card without them
 makes the agent guess and gives QA nothing to check, which is how a card gets
 signed off on the wrong thing.
 
-**There is no acceptance-criteria field.** They live in the card's `body`, under
-an `Acceptance criteria` heading, one checkable outcome per line:
-
-```
-Acceptance criteria
-- Exporting 10,000 rows completes without a 504.
-- The export button is disabled until the download starts.
+Acceptance criteria are first-class records, separate from the card's `body`.
+Pass them to `create_work_item.acceptanceCriteria` as executable
+where/given/when/then checks:
+
+```json
+[
+  {
+    "whereText": "Exports in the production-like staging workspace",
+    "givenText": "An account list contains 10,000 rows",
+    "whenText": "The seller starts a CSV export",
+    "thenText": "The download begins without a 504 and the button stays disabled until it does"
+  }
+]
 ```
 
 Two rules that decide whether you have written them correctly:
@@ -56,13 +62,14 @@ Two rules that decide whether you have written them correctly:
   one, ten means you should have filed two.
 - **Do not invent them**, on exactly the terms you do not invent a repro. If the
   reporter never said what "fixed" looks like, write "acceptance criteria
-  unknown — reporter did not state what fixed looks like" and file it. That is a
-  triage problem for a human, and naming it is what gets it triaged; a made-up
-  criterion is worse, because QA will sign the card off against it.
+  unknown — reporter did not state what fixed looks like" in the body and file
+  it with `acceptanceCriteria` empty. That is a triage problem for a human, and
+  naming it is what gets it triaged; a made-up criterion is worse, because QA
+  will sign the card off against it.
 
 Implementation steps are **not** criteria and never become their own cards:
-"create a React hook", "rename the CSS variables" are lines in this body, in a
-checklist under the criteria. There are deliberately no sub-tasks on this board.
+"create a React hook", "rename the CSS variables" are implementation notes in
+the body. There are deliberately no sub-tasks on this board.
 
 ## Writing it
 
@@ -80,8 +87,8 @@ grep for.
    the workspace serves, use that company's board.
 2. `get_work_board` → find the Triage column (the first one) and read the
    board's `tagScheme`.
-3. `create_work_item` with the title, the body, and `product` if you can tell
-   which one it belongs to.
+3. `create_work_item` with the title, the body, `acceptanceCriteria`, and
+   `product` if you can tell which one it belongs to.
 
 **Leave `assigneeUserId` empty.** Filing a card is not picking it up, and an
 assignee put on at filing time is a name nobody agreed to. An unowned card in the
@@ -113,7 +120,8 @@ decisions someone has to make.
 ## Writes
 
 `create_work_item` and `set_work_item_tag` are governed writes: they preview by
-default. Show the human the card you are about to file — title, body, tag — and
+default. Show the human the card you are about to file — title, body, criteria,
+tag — and
 file it only after they say yes, with `dryRun: false`, `approved: true`, a
 `reason`, and an `idempotencyKey`. Reuse the same key on retry so a flaky
 connection does not file the same incident twice.

package/skills/ship-the-card/SKILL.md

@@ -24,7 +24,8 @@ board untouched is work nobody can see.
 3. `get_work_board` for the card's board when you need the target column id —
    `move_work_item` moves to a column id, and only `get_work_board` has them.
 4. `get_work_item` for the full body, `get_work_item_history` for how it got
-   here, and `get_work_item_comments` for what people have SAID about it.
+   here, `list_work_item_acceptance_criteria` for the executable definition of
+   done, and `get_work_item_comments` for what people have SAID about it.
    **Read both before starting.** A card that has bounced out of a review column
    twice was rejected for a reason: the history says WHEN it bounced, the
    comments say WHY. Repeating a rejected approach is the most expensive mistake
@@ -102,9 +103,9 @@ Two things to carry back to the card:
   learns to ignore them.
 - if the fix is bigger than the card, do not quietly expand scope. Finish what
   the card asked for and report the rest as a card that should exist. If you
-  file it yourself, file it the way `incident-to-card` says: a title, a body
-  carrying **acceptance criteria** — what would prove it done, one checkable
-  outcome per line — and no assignee. A card you file from here arrives
+  file it yourself, file it the way `incident-to-card` says: a title, a body,
+  first-class **acceptance criteria** in where/when/then form, and no assignee.
+  A card you file from here arrives
   attributed to you automatically (the server stamps the creator from your
   session), so the next person at aligning can ask you what you meant; what it
   must not arrive with is a list of outcomes nobody can check.