@adrata/adrata-mcp 1.0.42 → 1.0.43

package/access/tiers.js

@@ -247,6 +247,13 @@ export const TOOL_TIERS = {
   get_work_board_rollup: TIERS.ENTERPRISE,
   list_work_board_rollups: TIERS.ENTERPRISE,
   set_work_board_archived: TIERS.ENTERPRISE,
+  // Launches: a lens over the boards (tools/work-launch-tools.js).
+  list_work_launches: TIERS.ENTERPRISE,
+  get_work_launch: TIERS.ENTERPRISE,
+  create_work_launch: TIERS.ENTERPRISE,
+  update_work_launch: TIERS.ENTERPRISE,
+  add_work_item_to_launch: TIERS.ENTERPRISE,
+  remove_work_item_from_launch: TIERS.ENTERPRISE,
   set_work_board_column_wip_limit: TIERS.ENTERPRISE,
   attach_work_item_qa_evidence: TIERS.ENTERPRISE,
   verify_work_item_qa_evidence_playback: TIERS.ENTERPRISE,

package/api-bridge.js

@@ -211,6 +211,8 @@ const ALLOWED_PREFIXES = [
   '/api/v1/work-board-rollups',
   '/api/v1/work-boards',
   '/api/v1/work-items',
+  // A launch is a lens over the boards; its writes are board writes.
+  '/api/v1/work-launches',
   // The containers above the cards (initiative / epic / feature) and the
   // "add this to the roadmap" verb. Creating an epic proposal is a governed
   // write like any other; the strategic commitment itself still moves through
@@ -343,6 +345,7 @@ const PATH_WRITE_SCOPES = [
   ['/api/v1/work-boards', 'write:tasks'],
   ['/api/v1/work-items', 'write:tasks'],
   ['/api/v1/work-board-rollups', 'write:tasks'],
+  ['/api/v1/work-launches', 'write:tasks'],
 ];
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrata/adrata-mcp",
-  "version": "1.0.42",
+  "version": "1.0.43",
   "description": "Adrata MCP Server \u2014 connect Claude Code, Codex, Gemini, Cursor, and other AI tools to your CRM. About 275 tools registered at startup for companies, people, deals, actions, buyer groups, warm intros, webhooks and intelligence, plus 65 more behind eight named toolsets you load with enable_toolset.",
   "type": "module",
   "main": "server.js",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "start": "node server.js",
-    "test": "node --test analytics.test.js server.test.js api-bridge.test.js http/edge-block.test.js http/rate-limit.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 security.cap-contract.test.js tool-annotations.test.js toolsets.test.js toolsets/communications.test.js toolsets/prospecting.test.js access/auth.test.js access/oauth-callback.test.js access/oauth-session.test.js access/oauth-capabilities.test.js access/oauth-scope-grantability.test.js scripts/local-dev-server.test.js tools/competitive-coverage.test.js tools/describe-count.test.js tools/email-tools.test.js tools/scheduling.test.js tools/work-board-tools.test.js tools/work-hub/audit.test.js tools/work-hub/field-changes.test.js tools/work-hub/criteria-quality.test.js tools/roadmap-tools.test.js tools/provisioning/onboarding-tools.test.js tools/source-control/connection-tools.test.js governance/money.test.js http/rate-limit-policy.test.js"
+    "test": "node --test analytics.test.js server.test.js api-bridge.test.js http/edge-block.test.js http/rate-limit.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 security.cap-contract.test.js tool-annotations.test.js toolsets.test.js toolsets/communications.test.js toolsets/prospecting.test.js access/auth.test.js access/oauth-callback.test.js access/oauth-session.test.js access/oauth-capabilities.test.js access/oauth-scope-grantability.test.js scripts/local-dev-server.test.js tools/competitive-coverage.test.js tools/describe-count.test.js tools/email-tools.test.js tools/scheduling.test.js tools/work-board-tools.test.js tools/launches/work-launch-tools.test.js tools/work-hub/audit.test.js tools/work-hub/field-changes.test.js tools/work-hub/criteria-quality.test.js tools/roadmap-tools.test.js tools/provisioning/onboarding-tools.test.js tools/source-control/connection-tools.test.js governance/money.test.js http/rate-limit-policy.test.js"
   },
   "keywords": [
     "mcp",

package/server.js

@@ -53,6 +53,7 @@ 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 { registerWorkLaunchTools } from './tools/launches/work-launch-tools.js';
 import { registerSourceControlTools } from './tools/source-control/connection-tools.js';
 import { registerRoadmapTools } from './tools/roadmap-tools.js';
 import { registerProvisioningTools } from './tools/provisioning/onboarding-tools.js';
@@ -2395,6 +2396,18 @@ registerWorkBoardTools(server, {
   getGrantedScope: () => loadTokens()?.scope,
 });
 
+// ===== LAUNCH TOOLS =====
+// A launch is a lens over the boards — a named, dated set a card can be on
+// without leaving its board. Same governed contract; see work-launch-tools.js.
+registerWorkLaunchTools(server, {
+  z,
+  api,
+  ok,
+  validateApiBridgeRequest,
+  buildMutationHeaders,
+  getGrantedScope: () => loadTokens()?.scope,
+});
+
 registerSourceControlTools(server, {
   z,
   api,

package/server.json

@@ -3,7 +3,7 @@
   "name": "com.adrata/adrata-mcp",
   "description": "Adrata revenue-intelligence MCP server: companies, people, opportunities, actions, buyer groups, enrichment, email, and workspace operations for AI agents.",
   "status": "active",
-  "version": "1.0.42",
+  "version": "1.0.43",
   "websiteUrl": "https://adrata.com/developers",
   "repository": {
     "url": "https://github.com/adrata/adrata",
@@ -15,7 +15,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@adrata/adrata-mcp",
-      "version": "1.0.42",
+      "version": "1.0.43",
       "transport": {
         "type": "stdio"
       },

package/tool-annotations.js

@@ -123,6 +123,12 @@ const DOMAIN_OVERRIDES = {
   add_to_roadmap: 'board',
   audit_work_hub: 'board',
   set_work_board_archived: 'board',
+  list_work_launches: 'board',
+  get_work_launch: 'board',
+  create_work_launch: 'board',
+  update_work_launch: 'board',
+  add_work_item_to_launch: 'board',
+  remove_work_item_from_launch: 'board',
   list_forms: 'forms',
   get_form: 'forms',
   create_form: 'forms',
@@ -253,6 +259,9 @@ const IDEMPOTENT_WRITES = new Set([
   // overwritten — which makes a retry with the same key land on the same state.
   // The restore is a plain clear of the same five columns.
   'archive_work_item', 'unarchive_work_item',
+  // A launch membership is an upsert keyed on (launch, card): replaying the
+  // same add re-ranks the same row; a repeat remove deletes a row already gone.
+  'create_work_launch', 'update_work_launch', 'add_work_item_to_launch', 'remove_work_item_from_launch',
   // A repeat block is the same edge (the pair is unique), and a repeat
   // unblock deletes a row that is already gone. Neither compounds.
   'block_work_item', 'unblock_work_item',

package/tools/launches/work-launch-tools.js

@@ -0,0 +1,286 @@
+/**
+ * Launch tools for the Adrata MCP server — a named, dated set of cards that
+ * must ship together, read as a LENS over the boards.
+ *
+ * The design: `spoq/epics/backlog/launches-are-lenses/EPIC.md`. The short form
+ * an agent needs before touching these:
+ *
+ *   - A launch is NOT a board. A card stays on its own board, in its own
+ *     column, under its own epic; membership here changes none of that and
+ *     none of the board's instruments. Do not transfer a card to "put it on a
+ *     launch" — that is the model these tools exist to replace.
+ *   - A card can be on MANY launches. Priority (p0 | p1 | p2) is per launch and
+ *     lives on the membership, because the card's one tag column is spoken
+ *     for (on the Adrata board it is `severity`, and a P0 written there would
+ *     overwrite `critical`).
+ *   - Membership is a CLAIM with provenance — who decided, how sure, and why —
+ *     on the same terms as `set_work_item_tag`. An agent that decides a card
+ *     belongs on a launch is `model` and must give a confidence.
+ *   - Readiness is COUNTS, derived on read, never a percentage and never
+ *     stored (hierarchy Decision 4).
+ *
+ * "Get all the P0s done" is `get_work_launch` with `priority: "p0"`: the cards
+ * come back ranked and each one says why it is there.
+ *
+ * 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.
+ */
+
+const GOVERNED_NOTE =
+  ' 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 — adding a card that is already on the launch re-ranks it rather than duplicating it).';
+
+const PRIORITIES = ['p0', 'p1', 'p2'];
+const EFFORTS = ['quick', 'standard', 'deep'];
+
+/**
+ * Narrow a launch's cards by priority. Pure and exported so the filter rule —
+ * the one thing a "give me the P0s" call can silently get wrong — is testable
+ * without a server.
+ *
+ * `unranked` selects cards on the launch with NO priority, which is a real
+ * state ("on the launch, not yet ranked") and must be reachable, on the same
+ * reasoning the scope control keeps `Unassigned` and `Untyped` selectable.
+ */
+export function filterLaunchCards(cards, priority, effort) {
+  let list = Array.isArray(cards) ? cards : [];
+  if (priority === 'unranked') list = list.filter((card) => !card?.launchPriority);
+  else if (priority) list = list.filter((card) => card?.launchPriority === priority);
+  if (effort === 'unjudged') list = list.filter((card) => !card?.launchEffort);
+  else if (effort) list = list.filter((card) => card?.launchEffort === effort);
+  return list;
+}
+
+/**
+ * Register the launch tools.
+ *
+ * @param {McpServer} server
+ * @param {object} deps - { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope }
+ */
+export function registerWorkLaunchTools(
+  server,
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope = () => undefined }
+) {
+
+  server.tool(
+    'list_work_launches',
+    'List the launches in the workspace — each a named, dated set of cards that must ship together, with its readiness as COUNTS (cards, p0/p1/p2/unranked, and how many sit in each stage). A launch is a lens over the boards, not a board: its cards stay on their own boards. Start here; get_work_launch needs an id from this list.',
+    {},
+    async () => {
+      const data = await api('GET', '/api/v1/work-launches');
+      const launches = data?.data || [];
+      return ok({ count: launches.length, launches });
+    }
+  );
+
+  server.tool(
+    'get_work_launch',
+    'Read one launch whole: its readiness counts and every member card the caller can see, p0 first. Each card carries its home board and column, its own tag, the ids it is blockedBy, and its membership claim — launchPriority, launchEffort (quick | standard | deep: a routing signal, not an estimate), launchReason, launchSource, launchConfidence. Pass priority to narrow: "p0" is the answer to "get all the P0s done"; "unranked" finds cards nobody has ranked. Pass effort to pick the quick wins for a fast lane, or the deep ones for a heavier model and a higher effort tier.',
+    {
+      launchId: z.string().describe('Launch id from list_work_launches.'),
+      priority: z
+        .enum([...PRIORITIES, 'unranked'])
+        .optional()
+        .describe('Narrow the cards to one priority band, or to the unranked ones. Omit for all.'),
+      effort: z
+        .enum([...EFFORTS, 'unjudged'])
+        .optional()
+        .describe('Narrow to quick wins, standard work, deep exploration, or the cards nobody has judged. Omit for all.'),
+    },
+    async (args) => {
+      const data = await api('GET', `/api/v1/work-launches/${encodeURIComponent(args.launchId)}`);
+      const launch = data?.data;
+      if (!launch) return ok({ launch: null });
+      const { cards: all = [], ...rest } = launch;
+      const cards = filterLaunchCards(all, args.priority, args.effort);
+      return ok({
+        launch: rest,
+        filter: args.priority ?? null,
+        effort: args.effort ?? null,
+        count: cards.length,
+        of: all.length,
+        cards,
+      });
+    }
+  );
+
+  server.tool(
+    'create_work_launch',
+    `Create a launch: a named, dated set of cards that must ship together. It owns no columns and no cards of its own — add cards with add_work_item_to_launch and they stay exactly where they are on their boards. Check list_work_launches first; two launches with one intent is a list nobody trusts.${GOVERNED_NOTE}`,
+    {
+      name: z.string().describe('e.g. "Adrata September Launch". Named for the outcome, not the month alone.'),
+      description: z
+        .string()
+        .optional()
+        .describe('Who it is for and what "live" means — the sentence a reader needs to judge whether a card belongs.'),
+      targetOn: z.string().optional().describe('The day it must be live, YYYY-MM-DD. A date, never an hour.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live write.'),
+      approved: z.boolean().optional().describe('Required true for a live write.'),
+      reason: z.string().optional().describe('Required for a live write: the audit reason.'),
+      idempotencyKey: z.string().optional().describe('Required for a live write. Reuse on retry.'),
+    },
+    async (args) => {
+      const path = '/api/v1/work-launches';
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldCreate: { name: args.name, description: args.description, targetOn: args.targetOn },
+        });
+      }
+      const data = await api('POST', path, {
+        body: { name: args.name, description: args.description, targetOn: args.targetOn },
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ created: true, launch: data?.data });
+    }
+  );
+
+  server.tool(
+    'update_work_launch',
+    `Rename a launch, move its target day, set its lifecycle (open | shipped | abandoned), or archive it. Status is the LIFECYCLE, not progress — progress is derived from the member cards and cannot be set. Archiving hides the launch from lists and from every card's launch chips; nothing is deleted.${GOVERNED_NOTE}`,
+    {
+      launchId: z.string().describe('Launch id from list_work_launches.'),
+      name: z.string().optional(),
+      description: z.string().optional(),
+      targetOn: z.string().optional().describe('YYYY-MM-DD, or "" to clear the date.'),
+      status: z.enum(['open', 'shipped', 'abandoned']).optional(),
+      archived: z.boolean().optional(),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live write.'),
+      approved: z.boolean().optional().describe('Required true for a live write.'),
+      reason: z.string().optional().describe('Required for a live write: the audit reason.'),
+      idempotencyKey: z.string().optional().describe('Required for a live write. Reuse on retry.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-launches/${encodeURIComponent(args.launchId)}`;
+      const preview = validateApiBridgeRequest({
+        method: 'PATCH',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      const body = {
+        name: args.name,
+        description: args.description,
+        targetOn: args.targetOn,
+        status: args.status,
+        isArchived: args.archived,
+      };
+      if (preview?.dryRun) return ok({ ...preview, wouldUpdate: body });
+      const data = await api('PATCH', path, { body, headers: buildMutationHeaders(args) });
+      return ok({ updated: true, launch: data?.data });
+    }
+  );
+
+  server.tool(
+    'add_work_item_to_launch',
+    `Put a card on a launch, with a priority and the reason it belongs there. The card does NOT move: it keeps its board, column, tag and epic — a launch is a lens. Adding a card that is already on the launch re-ranks it and replaces its reason and provenance. source is who decided: an agent classifying a card is "model" and MUST give a confidence; claiming "human" would launder a guess as a person's judgement.${GOVERNED_NOTE}`,
+    {
+      launchId: z.string().describe('Launch id from list_work_launches.'),
+      itemId: z.string().describe('Card id.'),
+      priority: z
+        .enum(PRIORITIES)
+        .optional()
+        .describe(
+          'p0 = cannot go live without it, or the first hour lies; p1 = the first week is not indispensable without it; p2 = launch quality that can trail by a week or two. Omit to add unranked.'
+        ),
+      effort: z
+        .enum(EFFORTS)
+        .optional()
+        .describe(
+          'quick = a known fix in a known place, hours not days; standard = ordinary card work; deep = needs exploration or a design (a heavier model / higher effort tier). A routing signal, never an estimate. Omit to leave unjudged.'
+        ),
+      membershipReason: z
+        .string()
+        .describe('Why this card is on the launch, in a sentence. Shown on the launch beside the card.'),
+      source: z.enum(['human', 'model', 'rules']).describe('Who decided membership.'),
+      confidence: z.number().min(0).max(1).optional().describe('0-1. REQUIRED when source is "model".'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live write.'),
+      approved: z.boolean().optional().describe('Required true for a live write.'),
+      reason: z.string().optional().describe('Required for a live write: the audit reason.'),
+      idempotencyKey: z.string().optional().describe('Required for a live write. Reuse on retry.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-launches/${encodeURIComponent(args.launchId)}/items`;
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      const body = {
+        itemId: args.itemId,
+        priority: args.priority,
+        effort: args.effort,
+        reason: args.membershipReason,
+        source: args.source,
+        confidence: args.confidence,
+      };
+      if (preview?.dryRun) return ok({ ...preview, wouldAdd: body });
+      const data = await api('POST', path, { body, headers: buildMutationHeaders(args) });
+      const launch = data?.data;
+      return ok({
+        added: true,
+        launchId: args.launchId,
+        itemId: args.itemId,
+        priority: args.priority ?? null,
+        effort: args.effort ?? null,
+        readiness: launch?.readiness,
+      });
+    }
+  );
+
+  server.tool(
+    'remove_work_item_from_launch',
+    `Take a card off a launch. The card itself is untouched — it stays on its board in its column. Use this when a card was added in error or the launch no longer needs it; to say a card is DONE, move it on its board instead and the launch's readiness will show it.${GOVERNED_NOTE}`,
+    {
+      launchId: z.string().describe('Launch id from list_work_launches.'),
+      itemId: z.string().describe('Card id.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live write.'),
+      approved: z.boolean().optional().describe('Required true for a live write.'),
+      reason: z.string().optional().describe('Required for a live write: the audit reason.'),
+      idempotencyKey: z.string().optional().describe('Required for a live write. Reuse on retry.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-launches/${encodeURIComponent(args.launchId)}/items/${encodeURIComponent(args.itemId)}`;
+      const preview = validateApiBridgeRequest({
+        method: 'DELETE',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        return ok({ ...preview, wouldRemove: { launchId: args.launchId, itemId: args.itemId } });
+      }
+      const data = await api('DELETE', path, { headers: buildMutationHeaders(args) });
+      return ok({ removed: true, launchId: args.launchId, itemId: args.itemId, readiness: data?.data?.readiness });
+    }
+  );
+}
+
+/** Tool names registered here, for the tier map and the toolset manifest. */
+export const WORK_LAUNCH_TOOL_NAMES = [
+  'list_work_launches',
+  'get_work_launch',
+  'create_work_launch',
+  'update_work_launch',
+  'add_work_item_to_launch',
+  'remove_work_item_from_launch',
+];