@adrata/adrata-mcp 1.0.0 → 1.0.2

package/tool-annotations.js

@@ -11,8 +11,8 @@
  *   2. Tag each tool with a domain "pack" (crm, email, calendar, enrichment,
  *      ...) so a client can request least-privilege scopes. When
  *      ADRATA_MCP_ENABLED_DOMAINS is set, tools outside the enabled packs are
- *      refused at dispatch — a lightweight scoped-tool-pack enforcement that
- *      avoids shipping N separate servers.
+ *      omitted from registration by the server and refused at dispatch as
+ *      defense in depth. A model never pays context for foreign product tools.
  *
  * Pure/stateless so it is unit-testable.
  */
@@ -39,10 +39,15 @@ const DOMAIN_OVERRIDES = {
   get_current_user: 'workspace',
 
   // Governed API bridge.
-  adrata_api_catalog: 'bridge',
-  adrata_api_request: 'bridge',
-  adrata_ai_tool_catalog: 'bridge',
-  adrata_ai_tool_execute: 'bridge',
+  // Broad backwards-compatible escape hatches stay on the unprofiled Adrata
+  // server. Product profiles use the namespace-bound capability bridge below.
+  adrata_api_catalog: 'legacy_bridge',
+  adrata_api_request: 'legacy_bridge',
+  adrata_ai_tool_catalog: 'legacy_bridge',
+  adrata_ai_tool_execute: 'legacy_bridge',
+  search_capabilities: 'bridge',
+  describe_capability: 'bridge',
+  run_capability: 'bridge',
 
   // Enrichment / external intelligence.
   enrich_company: 'enrichment',
@@ -105,9 +110,43 @@ const DOMAIN_OVERRIDES = {
 
   // Adrata Cloud: the bitemporal record substrate read.
   get_cloud_records: 'cloud',
+
+  // Starfield roadmap and future application families.
+  list_work_scopes: 'board',
+  add_to_roadmap: 'board',
+  audit_work_hub: 'board',
+  set_work_board_archived: 'board',
+  list_forms: 'forms',
+  get_form: 'forms',
+  create_form: 'forms',
+  update_form: 'forms',
+  publish_form: 'forms',
+  list_surveys: 'surveys',
+  get_survey: 'surveys',
+  create_survey: 'surveys',
+  publish_survey: 'surveys',
+
+  // Workspace membership is administration, never the general catch-all.
+  list_users: 'admin',
+  get_user: 'admin',
 };
 
 const DOMAIN_PREFIX_RULES = [
+  // Starfield's work boards. FIRST, because several of these names also contain
+  // tokens claimed by later rules and the first match wins.
+  //
+  // Without this rule all fourteen board tools resolved to the `general`
+  // catch-all along with sixty unrelated ones, which made the scoped-pack
+  // mechanism unable to express the one scope somebody actually wants: a
+  // coding agent that reads and actions the build board and reaches nothing
+  // else. `ADRATA_MCP_ENABLED_DOMAINS=general` would have granted 74 tools
+  // including CRM deletes. Naming the pack does not narrow anything on its own
+  // — `checkDomainScope` is inert unless the env var is set — it just makes the
+  // narrow scope expressible.
+  [/(work_item|work_board)/, 'board'],
+  [/(^|_)(form|forms)(_|$)/, 'forms'],
+  [/(^|_)(survey|surveys)(_|$)/, 'surveys'],
+  [/(workflow|automation)/, 'workflows'],
   [/^(create_email_account|list_email_accounts|warmup_email|get_email_health)/, 'infra'],
   [/^(search_domains|purchase_domain|setup_domain|verify_domain|list_domains)/, 'infra'],
   [/^(create_sequence|list_sequences|get_sequence|add_sequence_step|activate_sequence|pause_sequence|get_sequence_analytics|enroll_contacts|list_campaigns|get_campaign)/, 'sequences'],
@@ -151,6 +190,11 @@ export function checkDomainScope(name) {
   return { allowed: false, reason: 'domain_not_in_scope', domain, enabled: [...enabled] };
 }
 
+/** Whether a scoped server should advertise/register this tool at all. */
+export function shouldRegisterTool(name) {
+  return checkDomainScope(name).allowed;
+}
+
 // ---------------------------------------------------------------------------
 // Behaviour classification (readOnly / destructive / idempotent / openWorld)
 // ---------------------------------------------------------------------------
@@ -192,6 +236,12 @@ const IDEMPOTENT_WRITES = new Set([
   'add_to_company_list', 'find_or_create_person', 'find_or_create_company',
   'save_memory', 'manage_custom_fields', 'build_pursuit_command_center',
   'update_buyer_group', 'update_buyer_group_member',
+  // Every Starfield board write is governed by a required idempotency key.
+  // Retrying the same key replays; it never appends a second transition,
+  // comment, criterion, or card.
+  'move_work_item', 'set_work_board_column_wip_limit', 'set_work_item_tag', 'set_work_item_kind',
+  'create_work_item', 'comment_on_work_item', 'flag_work_item',
+  'add_work_item_acceptance_criterion',
 ]);
 
 // Non-read tools that create new state / have side effects each call.
@@ -219,7 +269,7 @@ function isReadOnly(name) {
   if (isDestructive(name) || IDEMPOTENT_WRITES.has(name) || NON_IDEMPOTENT_WRITES.has(name)) {
     return false;
   }
-  return /^(get_|list_|search_|find_(?!or_create)|count_|describe_|check_|inspect_|rank_|score_|who_am_i|recall|workspace_status|morning_brief|export_data)/.test(name)
+  return /^(get_|list_|audit_|search_|find_(?!or_create)|count_|describe_|check_|inspect_|rank_|score_|who_am_i|recall|workspace_status|morning_brief|export_data)/.test(name)
     || name.endsWith('_catalog')
     || name.endsWith('_analytics')
     || name.endsWith('_status');

package/tools/billing.js

@@ -141,7 +141,11 @@ export function registerBillingTools(server, { api, ok, auth }) {
           plan: auth.tier,
           status: 'active',
           message: 'Subscription details are available in your Adrata dashboard.',
-          dashboard_url: 'https://app.adrata.com/settings/billing',
+          // Was `https://app.adrata.com/settings/billing`. That host has no DNS
+          // record (verified NXDOMAIN, 2026-08-18), so this fallback — which
+          // fires precisely when the billing endpoint is unavailable, i.e. when
+          // the user most needs a working link — handed them a dead URL.
+          dashboard_url: 'https://adrata.com/settings/billing',
         });
       }
     }

package/tools/roadmap-tools.js

@@ -0,0 +1,192 @@
+/**
+ * Roadmap tools for the Adrata MCP server — the "add this to the roadmap" verb.
+ *
+ * The design these implement is `company/decisions/2026-08-06-spoq-roadmap-sync.md`:
+ * the roadmap is ONE truth per field across two stores. Git (`spoq/epics/`)
+ * owns strategic commitment — that an epic exists, its slug, its title, its
+ * tier, its prose. Starfield owns operational state — features, cards,
+ * columns, owners. No field has two writers, so the stores cannot disagree
+ * about anything either one owns.
+ *
+ * That split is why "add this to the roadmap" is deliberately TWO acts:
+ *
+ *   1. `add_to_roadmap` (here) creates a PROPOSED epic-level scope through
+ *      `POST /api/v1/work-scopes` — the same endpoint the app uses — so the
+ *      idea is on the board and the Roadmap page the moment a human approves
+ *      the write.
+ *   2. The git half is the AGENT'S work, not this server's: write
+ *      `spoq/epics/backlog/<slug>/EPIC.md` and open a PR. This server talks
+ *      to the API over HTTP from wherever it is installed; it has no
+ *      checkout, and pretending a database row alone changed the roadmap of
+ *      record would be exactly the lie the decision record exists to prevent.
+ *      The tool's response says so instead, every time.
+ *
+ * The scope this tool creates carries no `source_roadmap_slug` — that column
+ * is the importer's, set only when the epic's PR merges to main and the
+ * import reconciles the tree. A scope born here is a Starfield-owned proposal
+ * until git confirms it, which is the true state of an idea whose PR has not
+ * landed.
+ *
+ * Writes follow the same governed contract as every write on this server:
+ * dryRun defaults to TRUE; a live write needs dryRun:false AND approved:true
+ * AND a reason AND an idempotencyKey.
+ */
+
+/**
+ * Derive the spoq directory slug the agent should use for the git half.
+ *
+ * Deliberately the same shape the 373 existing directories use: lowercase,
+ * hyphen-separated, ASCII. This is a SUGGESTION for the response text — the
+ * agent may adjust it — so it aims for "obviously right most of the time",
+ * not for a normative spec of slugs.
+ */
+export function suggestSlug(title) {
+  return String(title ?? '')
+    .toLowerCase()
+    .replace(/['’]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+}
+
+/**
+ * The instruction that keeps the two halves of "add to the roadmap" together.
+ *
+ * Returned on every successful create AND on every dry-run preview, because
+ * the agent deciding whether to ask for approval is the same agent that must
+ * plan the PR. One omission here and the board and the repo drift on day one.
+ */
+export function gitHalfInstructions(title) {
+  const slug = suggestSlug(title) || '<slug>';
+  return (
+    `This scope is a Starfield-side proposal only — the roadmap of record is the git tree. ` +
+    `To make it a strategic commitment: create spoq/epics/backlog/${slug}/EPIC.md ` +
+    `(the directory basename is the epic's identity; keep it stable), write the epic as prose ` +
+    `with a "## Status" heading, and open a PR. When that PR merges to main, the importer ` +
+    `links the merged slug to this scope by exact title match — so keep the EPIC.md title ` +
+    `byte-identical to this scope's title, or expect two visible rows to merge by hand later.`
+  );
+}
+
+/**
+ * Register the roadmap tools.
+ *
+ * @param {McpServer} server - the MCP server instance (already tier-gated)
+ * @param {object} deps - { z, api, ok, validateApiBridgeRequest, buildMutationHeaders }
+ */
+export function registerRoadmapTools(
+  server,
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders }
+) {
+  server.tool(
+    'list_work_scopes',
+    `The containers ABOVE the cards: every initiative, epic, and feature in the workspace, flat, each with its parent id and its counted progress (cards / shipped / in QA). This is the roadmap as Starfield sees it — an epic whose source_roadmap_slug is set was imported from spoq/epics/ in the repo and its title and status are owned by git (change them through a PR, not here); a scope with no slug was born in Starfield.
+
+Progress is COUNTS, never a percentage: "7 of 12 shipped" is honest where "58%" is a feeling. A scope with zero cards is a real state (a commitment nobody has broken down yet), not an error.
+
+Use this before add_to_roadmap: if an epic with the same intent already exists, the roadmap needs your card or feature under it, not a duplicate epic beside it.`,
+    {},
+    async () => {
+      const data = await api('GET', '/api/v1/work-scopes');
+      const scopes = data?.data || [];
+      return ok({
+        count: scopes.length,
+        scopes,
+        note:
+          scopes.length === 0
+            ? 'No scopes yet. Either the workspace has no roadmap containers, or the work_scopes schema has not been deployed here.'
+            : undefined,
+      });
+    }
+  );
+
+  server.tool(
+    'add_to_roadmap',
+    `Add an idea to the roadmap as a PROPOSED epic — the "add this to the roadmap" verb. Creates an epic-level scope (status: proposed, i.e. below the line) through the same endpoint the app uses, so it appears on the Roadmap page immediately.
+
+THIS IS HALF THE JOB, AND THE TOOL WILL SAY SO. The roadmap of record is the git tree (spoq/epics/ — see company/decisions/2026-08-06-spoq-roadmap-sync.md): a database row makes the idea visible, a merged PR makes it a commitment. The response tells you the exact spoq/ path to create; if you are an agent with a checkout, plan on writing the EPIC.md and opening the PR as your next step, with the SAME title.
+
+DO NOT use this for work that belongs under an existing epic — check list_work_scopes first and file a card (create_work_item) or ask a human to add a feature instead. A roadmap of near-duplicate epics is how a roadmap stops being read.${''}
+
+Governed write: previews by default. A live write requires dryRun:false plus approved:true, a reason, and an idempotencyKey (reuse the SAME key on retry — the server replays instead of creating a second epic).`,
+    {
+      title: z
+        .string()
+        .describe(
+          'What the epic is, as a statement of the outcome. This exact string becomes the scope title AND should be the EPIC.md title in the PR — the importer adopts this scope by byte-identical title match when the PR merges.'
+        ),
+      parentScopeId: z
+        .string()
+        .optional()
+        .describe(
+          'Initiative to hang this epic under, from list_work_scopes. OMIT unless one genuinely claims it — most epics are parentless and that is legal forever.'
+        ),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to create it.'),
+      approved: z.boolean().optional().describe('Required true for a live create.'),
+      reason: z
+        .string()
+        .optional()
+        .describe(
+          'Required for a live create: why this belongs on the roadmap — the ask or evidence that produced it, not "add epic".'
+        ),
+      idempotencyKey: z.string().optional().describe('Required for a live create.'),
+    },
+    async (args) => {
+      const path = '/api/v1/work-scopes';
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldCreate: {
+            level: 'epic',
+            title: args.title,
+            parentScopeId: args.parentScopeId,
+          },
+          gitHalf: gitHalfInstructions(args.title),
+        });
+      }
+
+      let data;
+      try {
+        data = await api('POST', path, {
+          body: {
+            title: args.title,
+            level: 'epic',
+            parentScopeId: args.parentScopeId,
+          },
+          headers: buildMutationHeaders(args),
+        });
+      } catch (error) {
+        // The work-scopes routes land with PR #1819. Against an API without
+        // them the failure is a bare 404, which reads as "you did something
+        // wrong" when the truth is "this deployment cannot do this yet" —
+        // name the real situation instead of letting the agent retry a wall.
+        if (/404/.test(String(error?.message ?? ''))) {
+          return ok({
+            error: true,
+            message:
+              'This API deployment has no /api/v1/work-scopes routes yet (they land with the work_scopes schema, PR #1819). ' +
+              'The git half still works: ' +
+              gitHalfInstructions(args.title),
+          });
+        }
+        throw error;
+      }
+      return ok({
+        created: true,
+        scope: data?.data,
+        gitHalf: gitHalfInstructions(args.title),
+      });
+    }
+  );
+}
+
+/** Tool names registered here, for the tier map. */
+export const ROADMAP_TOOL_NAMES = ['list_work_scopes', 'add_to_roadmap'];