@adrata/adrata-mcp 1.0.2 → 1.0.3

package/access/oauth.js

@@ -104,6 +104,22 @@ export const OAUTH_WRITE_SCOPE = [
   'write:companies', 'write:people', 'write:buyer-groups',
   'write:opportunities', 'write:actions', 'write:tasks',
   'write:partnerships', 'write:sequences', 'write:campaigns', 'write:data',
+  // Authorising an external system to write into the workspace — connecting a
+  // CRM, or binding a source-control repository to a board. Its absence was not
+  // a deliberate least-privilege call, because `read:integrations` was already
+  // granted by default: the connection could SEE every integration and connect
+  // none of them.
+  //
+  // Measured 2026-08-29. `POST /api/v1/scm/connections` returned 403
+  // insufficient_scope against a session holding ten other write scopes, so the
+  // Starfield board could not be wired to GitHub from the only layer that has a
+  // connect flow at all — there is no Connections UI for source control. Every
+  // card move stayed manual as a result.
+  //
+  // Still opt-in: this list is only requested by connect_workspace({ writeAccess:
+  // true }), so the default grant remains read-only and a leaked token cannot
+  // authorise an integration.
+  'write:integrations',
 ].join(' ');
 
 /**
@@ -576,7 +592,7 @@ async function performTokenRefresh(apiBase, fetchImpl) {
     refresh_token: tokens.refreshToken,
     // RFC 8707: keep the same audience binding the initial grant used so the
     // refreshed access token stays bound to the /api/v1/mcp resource.
-    resource: tokens.resource || canonicalResource(),
+    resource: tokens.resource || canonicalResource(apiBase),
   });
 
   let lastError;
@@ -669,7 +685,7 @@ export async function getValidToken(apiBase, { forceRefresh = false, fetchImpl =
 /**
  * Build the OAuth authorization URL.
  */
-function buildAuthUrl(apiBase, clientId, redirectUri, state, pkce, scope = OAUTH_SCOPE) {
+export function buildAuthUrl(apiBase, clientId, redirectUri, state, pkce, scope = OAUTH_SCOPE) {
   // Use the web app's OAuth authorize page (user-facing login + consent screen)
   const url = new URL(`${OAUTH_BASE_PATH}/authorize`, apiBase);
   url.searchParams.set('client_id', clientId);
@@ -680,7 +696,7 @@ function buildAuthUrl(apiBase, clientId, redirectUri, state, pkce, scope = OAUTH
   url.searchParams.set('source', 'mcp');
   // RFC 8707 Resource Indicator — request a token audience-bound to this MCP
   // resource so it cannot be replayed against a different service.
-  url.searchParams.set('resource', canonicalResource());
+  url.searchParams.set('resource', canonicalResource(apiBase));
   url.searchParams.set('code_challenge', pkce.challenge);
   url.searchParams.set('code_challenge_method', 'S256');
   return { url: url.toString(), state, codeVerifier: pkce.verifier };
@@ -853,7 +869,7 @@ export function createOAuthCallbackRequestHandler({
 /**
  * Exchange an authorization code for tokens.
  */
-async function exchangeCode(apiBase, code, clientId, codeVerifier, redirectUri) {
+export async function exchangeCode(apiBase, code, clientId, codeVerifier, redirectUri, fetchImpl = fetch) {
   const url = new URL(`${OAUTH_BASE_PATH}/token`, apiBase);
   const body = new URLSearchParams({
     grant_type: 'authorization_code',
@@ -861,10 +877,10 @@ async function exchangeCode(apiBase, code, clientId, codeVerifier, redirectUri)
     code,
     code_verifier: codeVerifier,
     redirect_uri: redirectUri,
-    resource: canonicalResource(),
+    resource: canonicalResource(apiBase),
   });
 
-  const res = await fetch(url.toString(), {
+  const res = await fetchImpl(url.toString(), {
     method: 'POST',
     headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
     body,
@@ -1026,7 +1042,7 @@ export async function connectWorkspace(apiBase, { writeAccess = false } = {}) {
     clientId,
     clientRegistration: registration.clientRegistration,
     tokenEndpointAuthMethod: registration.tokenEndpointAuthMethod,
-    resource: canonicalResource(),
+    resource: canonicalResource(apiBase),
     apiBase,
     connectedAt: new Date().toISOString(),
   };

package/access/resource-metadata.js

@@ -35,8 +35,16 @@ export function authorizationServers() {
  * The canonical resource identifier for this MCP server. RFC 8707 clients
  * send this as the `resource` parameter so the AS can bind the token's
  * audience to it. Defaults to the REST MCP resource the Rust AS advertises.
+ *
+ * Client flows pass their explicit API base so a staging authorization request
+ * cannot accidentally ask for a production-bound token. Hosted resource-server
+ * callers omit it and continue to use the configured authorization server.
+ *
+ * @param {string} [apiBase] - Explicit authorization-server/API base for a
+ *   client connection.
  */
-export function canonicalResource() {
+export function canonicalResource(apiBase) {
+  if (apiBase) return `${apiBase.replace(/\/$/, '')}/api/v1/mcp`;
   if (process.env.ADRATA_MCP_RESOURCE) return process.env.ADRATA_MCP_RESOURCE.trim();
   const as = authorizationServers()[0] || 'https://api.adrata.com';
   return `${as.replace(/\/$/, '')}/api/v1/mcp`;

package/access/tiers.js

@@ -234,6 +234,8 @@ export const TOOL_TIERS = {
   set_work_item_kind: TIERS.ENTERPRISE,
   create_work_item: TIERS.ENTERPRISE,
   add_work_item_acceptance_criterion: TIERS.ENTERPRISE,
+  satisfy_work_item_acceptance_criterion: TIERS.ENTERPRISE,
+  unsatisfy_work_item_acceptance_criterion: TIERS.ENTERPRISE,
   comment_on_work_item: TIERS.ENTERPRISE,
   flag_work_item: TIERS.ENTERPRISE,
   // The containers above the cards, and the "add this to the roadmap" verb.

package/api-bridge.js

@@ -171,6 +171,14 @@ const ALLOWED_PREFIXES = [
   '/api/v1/retention',
   '/api/v1/revenue',
   '/api/v1/revenue-cloud',
+  // Source control connections and their repository bindings. The board
+  // cannot learn that a pull request merged unless something can create the
+  // connection and register the callback, and until this row existed the
+  // bridge refused every /scm path — so the receiver at /webhooks/scm sat
+  // mounted and reachable with no connection ever pointing at it.
+  // The unauthenticated receiver itself is NOT here: it is mounted below the
+  // auth layer and is not an agent-callable path.
+  '/api/v1/scm',
   '/api/v1/scoring',
   '/api/v1/security',
   '/api/v1/self-service',
@@ -279,6 +287,14 @@ const PATH_WRITE_SCOPES = [
   // All three are listed separately because `matchesPathPrefix` is
   // segment-boundary matched: `/work-boards` does not annex
   // `/work-board-rollups`.
+  // Authorising a source-control account is the same act as connecting a CRM —
+  // an external system permitted to write into the workspace — so scope_guard
+  // maps it onto the integrations family rather than a new one. Deliberately
+  // not an `admin:` scope: those refuse first-party bypass and a human session
+  // JWT carries an empty permission list, which would 403 every person opening
+  // the Connections screen. Mirrors `family_matches(path, "/scm")` in
+  // code/api/crates/middleware/src/scope_guard/mod.rs.
+  ['/api/v1/scm', 'write:integrations'],
   ['/api/v1/work-boards', 'write:tasks'],
   ['/api/v1/work-items', 'write:tasks'],
   ['/api/v1/work-board-rollups', 'write:tasks'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrata/adrata-mcp",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Adrata MCP Server \u2014 connect Claude Code, Codex, Gemini, Cursor, and other AI tools to your CRM. 80+ tools for companies, people, deals, actions, buyer groups, warm intros, webhooks, intelligence, and more.",
   "type": "module",
   "main": "server.js",

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

@@ -110,6 +110,28 @@ Two things to carry back to the card:
   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.
 
+## Tick what you ran
+
+Before you move the card on, tick the criteria you actually executed, with
+`satisfy_work_item_acceptance_criterion` and the evidence in `note` — a build
+number, a run link, the caveat that makes it honest. An untouched checkbox says
+nothing about whether the check passed; it says nobody has been near it, which
+is the same thing an abandoned card says.
+
+Ticking from a build column records `claimed`, not `verified`, and so does
+ticking your own card at a QA gate. That is the rule, not a refusal: the grade
+is derived from where the card was standing and who you are, and the engineer
+who built the thing cannot verify it. Tick anyway — `claimed` is a real state
+that says the work is believed done, and it is what QA reads before deciding
+what to re-run. What you must not do is tick a box you did not execute to make
+the count look better: the QA gate reads `verified`, so it stops either way, and
+all the false tick achieves is turning an honest "shipped with two open" into a
+claim somebody later believes.
+
+If a tick turns out to be wrong, `unsatisfy_work_item_acceptance_criterion`
+takes it off. It clears the note with it, so if the evidence is worth keeping,
+put it on the card with `comment_on_work_item` first.
+
 ## Submit it
 
 When the change is ready for review, `move_work_item` it onward — no `claim`

package/tool-annotations.js

@@ -242,6 +242,12 @@ const IDEMPOTENT_WRITES = new Set([
   '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',
+  // Ticking and un-ticking are both genuinely idempotent, and for different
+  // reasons worth keeping straight: a repeat tick is a no-op because the server
+  // only writes the ticker, column and note where they were empty, and a repeat
+  // un-tick clears columns that are already NULL. Neither can compound.
+  'satisfy_work_item_acceptance_criterion',
+  'unsatisfy_work_item_acceptance_criterion',
 ]);
 
 // Non-read tools that create new state / have side effects each call.

package/tools/work-board-tools.js

@@ -131,6 +131,19 @@ export function describeMissingAcceptanceCriteria(criteria) {
   return 'This card would have no executable acceptance criteria. It can be captured, but it is not ready for build or QA until at least one where/when/then criterion is added.';
 }
 
+/**
+ * The satisfaction sub-resource of one criterion, POSTed to tick and DELETEd to
+ * un-tick.
+ *
+ * One function for both verbs because they address the SAME resource: a tick
+ * and its removal that disagreed about the path would fail asymmetrically —
+ * ticks landing and un-ticks 404ing — which is the failure that leaves a board
+ * with checkboxes nobody can clear.
+ */
+export function criterionSatisfactionPath(itemId, criterionId) {
+  return `/api/v1/work-items/${encodeURIComponent(itemId)}/acceptance-criteria/${encodeURIComponent(criterionId)}/satisfaction`;
+}
+
 /** One target stage's WIP state before and after a proposed move. */
 export function projectColumnWip({ limit, count, cardAlreadyThere, truncated = false }) {
   const projected = count + (cardAlreadyThere ? 0 : 1);
@@ -885,6 +898,160 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
       return ok({ added: true, criterion: data?.data });
     }
   );
+
+  server.tool(
+    'satisfy_work_item_acceptance_criterion',
+    `Tick one acceptance criterion, with the evidence that made you believe it. This is the act that turns a checklist into proof: a criterion nobody ticks is indistinguishable from one nobody ran, and a board full of untouched checkboxes reports the same thing whether the work was verified or abandoned.
+
+WHERE YOU TICK FROM DECIDES WHAT THE TICK IS WORTH, and it is not a permission you can ask for. The grade is derived on every read from the card's CURRENT column and from who you are:
+
+  • \`verified\` — ticked while the card stands in a QA stage ("Staging QA1" or "Staging QA2"), by somebody who neither wrote the criterion nor owns the card.
+  • \`claimed\` — everything else. Ticked in a build column, or ticked at a QA gate by the card's owner or by the person who authored the check. A real and useful state: it says the work is believed done. It is self-assessment, and the board never counts it as verification.
+
+So the engineer who built the card CANNOT verify their own work, and neither can whoever wrote the criterion — not because the tick is refused, but because it grades as \`claimed\` however it is worded. Nothing here fails on that account; you get the criterion back carrying a grade, and the grade may not be the one you expected. If you want \`verified\`, the card has to be standing at a QA gate and somebody else has to be doing the ticking.
+
+TICK WHAT YOU RAN, not what you believe. The card face prints met over total; the QA exit gate reads the VERIFIED count. So a card whose boxes were all ticked by its own author reads 5/5 on the face and still stops the gate — which is the design working. Ticking without running the check converts an honest "we shipped with two open" into a false "all met", and the false version is the one that gets believed later.
+
+FIRST TICK WINS. The server records the ticker, the column and the note only where they were empty, so a second person ticking an already-ticked box cannot overwrite the first person's evidence, and re-ticking is a no-op rather than an upgrade. To re-tick under different circumstances, un-tick it first with unsatisfy_work_item_acceptance_criterion — that clears the ticker, the column and the note together, so the next tick cannot inherit somebody else's evidence.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      criterionId: z
+        .string()
+        .describe('Criterion id from list_work_item_acceptance_criteria — the `id`, not the `ordinal`.'),
+      note: z
+        .string()
+        .optional()
+        .describe(
+          'OPTIONAL, and the most useful field here: the evidence. A build number, a PR or run link, or the caveat that makes the tick honest ("only checked on Safari"). Stored on the criterion and shown beside it, so it is what a release review reads instead of taking the tick on trust. Omit it when there is genuinely nothing to add — an invented note is worse than none.'
+        ),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to record the tick.'),
+      approved: z.boolean().optional().describe('Required true for a live tick.'),
+      reason: z
+        .string()
+        .optional()
+        .describe(
+          'Required for a live tick: the audit reason — how you checked this, not what the criterion already says. The evidence a human reads on the card is `note`.'
+        ),
+      idempotencyKey: z
+        .string()
+        .optional()
+        .describe('Required for a live tick. Reuse the SAME key on retry.'),
+    },
+    async (args) => {
+      const unauditable = args.dryRun === false ? describeUnauditableReason(args.reason) : null;
+      if (unauditable) return ok({ error: true, message: unauditable });
+
+      const path = criterionSatisfactionPath(args.itemId, args.criterionId);
+      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,
+          wouldSatisfy: {
+            itemId: args.itemId,
+            criterionId: args.criterionId,
+            note: args.note ?? null,
+          },
+          // Said in the preview because the preview is where a caller decides
+          // whether to go live, and the one thing it CANNOT tell them is the
+          // answer they want. Predicting the grade here would need the card's
+          // current column and the criterion's author, and a prediction made
+          // from a stale read is worse than an honest refusal to predict.
+          gradeIsDerived:
+            'The grade is computed at read time from the column this card is standing in and from who you are, so this preview cannot tell you which you will get. Ticking from a QA stage, as somebody who is neither the criterion\'s author nor the card\'s owner, grades `verified`; anything else grades `claimed`.',
+        });
+      }
+
+      const data = await api('POST', path, {
+        // The note is the only field this endpoint takes, and it is optional:
+        // `SatisfyCriterionRequest` defaults it, so an omitted note is a valid
+        // body rather than a missing one. Sending `{}` is deliberate — a tick
+        // with nothing to add must stay recordable, because the alternative is
+        // an agent inventing evidence to satisfy a required field.
+        body: args.note === undefined ? {} : { note: args.note },
+        headers: buildMutationHeaders(args),
+      });
+      const criterion = data?.data;
+      return ok({
+        satisfied: true,
+        criterion,
+        // The grade is the answer, and it is the server's to give. Echoing an
+        // optimistic "verified" from the request would be this tool asserting
+        // the exact fact the grading rule exists to withhold.
+        grade: criterion?.grade,
+        ...(criterion?.grade === 'claimed'
+          ? {
+              gradeNote:
+                'Recorded as `claimed`, not `verified`: either the card was not standing in a QA stage, or you wrote this criterion or own the card. That is the rule working rather than a failure — the tick stands and the card face counts it. Verification needs a QA stage and a different pair of hands.',
+            }
+          : {}),
+      });
+    }
+  );
+
+  server.tool(
+    'unsatisfy_work_item_acceptance_criterion',
+    `Un-tick one acceptance criterion, back to \`unmet\`. Use it when the check turns out not to hold, when it was ticked against the wrong build, or when it was ticked from a build column and has to be re-run at the gate to count as verified.
+
+This exists so that ticking is safe to do. A box nobody can clear is a box people hesitate to tick, and that hesitation is exactly how a board ends up with a full checklist that nobody has ever touched — so shipping the tick without its counterpart would have left the same problem in a new shape.
+
+It clears the WHOLE circumstance together — the ticker, the column, the note and the timestamp — never just the timestamp. Otherwise the next tick would inherit somebody else's evidence: a criterion re-ticked in Aligning would keep reading as verified in QA1, attributed to a person who was not there. So the cost is real, and it is the note: the first ticker's evidence is gone. If it is worth keeping, put it on the card with comment_on_work_item BEFORE you clear it.
+
+Anyone who can see the card may un-tick, including somebody undoing another person's tick. The audit reason is the only record of why, so write it for them.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      criterionId: z
+        .string()
+        .describe('Criterion id from list_work_item_acceptance_criteria — the `id`, not the `ordinal`.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to clear the tick.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      reason: z
+        .string()
+        .optional()
+        .describe(
+          'Required for a live change: why this tick is coming off — the check failed on a later build, it was run against the wrong environment, it needs re-running at the gate. This is the only record the original ticker will have of losing their evidence.'
+        ),
+      idempotencyKey: z
+        .string()
+        .optional()
+        .describe('Required for a live change. Reuse the SAME key on retry.'),
+    },
+    async (args) => {
+      const unauditable = args.dryRun === false ? describeUnauditableReason(args.reason) : null;
+      if (unauditable) return ok({ error: true, message: unauditable });
+
+      const path = criterionSatisfactionPath(args.itemId, args.criterionId);
+      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,
+          wouldUnsatisfy: { itemId: args.itemId, criterionId: args.criterionId },
+          clears:
+            'The ticker, the column the tick happened in, the evidence note, and the timestamp — all four together, so a later tick cannot inherit this one. Copy the note onto the card first if it is worth keeping.',
+        });
+      }
+
+      const data = await api('DELETE', path, { headers: buildMutationHeaders(args) });
+      const criterion = data?.data;
+      return ok({ unsatisfied: true, criterion, grade: criterion?.grade });
+    }
+  );
+
   server.tool(
     'comment_on_work_item',
     `Say something on a card: a question, a finding, or the reason a QA pass sent it back. This is the ONLY place to put a fact that contradicts the card — the ship-the-card skill tells you to say so on the card rather than silently fixing something else, and this is where that goes. Do NOT overwrite the card's body to make the point: the body is the original request, and rewriting it destroys the evidence of what was actually asked for.
@@ -1022,6 +1189,8 @@ export const WORK_BOARD_TOOL_NAMES = [
   'set_work_item_kind',
   'create_work_item',
   'add_work_item_acceptance_criterion',
+  'satisfy_work_item_acceptance_criterion',
+  'unsatisfy_work_item_acceptance_criterion',
   'get_work_item_comments',
   'comment_on_work_item',
   'flag_work_item',