@adrata/adrata-mcp 1.0.19 → 1.0.40

package/tools/source-control/connection-tools.js

@@ -1,5 +1,8 @@
 /** Read-only, product-visible health for Starfield's source-control ingestion. */
-export function registerSourceControlTools(server, { z, api, ok }) {
+export function registerSourceControlTools(
+  server,
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope }
+) {
   server.tool(
     'list_source_control_connections',
     'List source-control connections with repository binding count, last durably acknowledged delivery, rejection state, actionable health, and the exact webhook events that are safe to enable.',
@@ -23,9 +26,122 @@ export function registerSourceControlTools(server, { z, api, ok }) {
       return ok({ events: response?.data ?? response ?? [] });
     }
   );
+
+  server.tool(
+    'bind_repository_to_board',
+    'Bind one repository to one board, so a merged pull request carrying a card id moves that card by itself.'
+      + ' Until a board is bound, every merge on it advances nothing and the column timestamps are hand-typed,'
+      + ' which is the input every cycle-time and control chart is built from.'
+      + ' Name BOTH mergeFromColumnId and mergeToColumnId or neither: one end alone is a half-configured rule'
+      + ' that silently does nothing, and the database CHECK constraint refuses it.'
+      + ' 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 — a duplicate bind is refused as a 409).',
+    {
+      connectionId: z.string().describe('Source-control connection id, from list_source_control_connections.'),
+      boardId: z.string().describe('Board id from list_work_boards. One board binds once per connection.'),
+      externalRepoId: z.string().describe('The vendor’s own repository id, not its name.'),
+      externalFullName: z.string().describe('owner/name, e.g. adrata/adrata.'),
+      mergeFromColumnId: z
+        .string()
+        .optional()
+        .describe('Where a merged pull request’s card must be coming FROM. Both ends or neither.'),
+      mergeToColumnId: z
+        .string()
+        .optional()
+        .describe('Where it goes on merge. Both ends or neither.'),
+      onMergeAction: z
+        .enum(['advance', 'suggest', 'ignore'])
+        .optional()
+        .describe('Defaults to advance. `suggest` records the proposal without moving the card.'),
+      branchSample: z
+        .array(z.string())
+        .optional()
+        .describe(
+          'Recent branch names, newest first. NOT stored: the server measures how many already carry a card'
+            + ' reference and seeds the link strategies from what the repository actually does, rather than from'
+            + ' a form somebody filled in. Omitting it means the strategies are chosen without that evidence.'
+        ),
+      advanceOnlyWhenAllMerged: z
+        .boolean()
+        .optional()
+        .describe('Advance only when no linked change request is still open. Defaults true.'),
+      openPullsCardIntoProgress: z
+        .boolean()
+        .optional()
+        .describe('Does an OPENED pull request pull its card into In progress? Defaults false.'),
+      stagingEnvironmentName: z
+        .string()
+        .optional()
+        .describe('Exact vendor environment name. Absence means that evidence is not configured; never infer a role from a word like "staging".'),
+      productionEnvironmentName: z.string().optional().describe('Exact vendor environment name.'),
+      dryRun: z.boolean().optional().default(true),
+      approved: z.boolean().optional().default(false),
+      reason: z.string().optional(),
+      idempotencyKey: z.string().optional(),
+    },
+    async (args) => {
+      // Refused HERE rather than at the API, because the 400 this produces reads
+      // as a validation error about a column and the actual mistake is that only
+      // one end was named. `scm_repositories_move_shape_chk` enforces the same
+      // shape in the database; this says why before the round trip.
+      const from = args.mergeFromColumnId;
+      const to = args.mergeToColumnId;
+      if (Boolean(from) !== Boolean(to)) {
+        return ok({
+          error: true,
+          message:
+            'Name both mergeFromColumnId and mergeToColumnId, or neither. One end alone is a half-configured'
+            + ' move rule: it is accepted nowhere, and if it were, it would silently never fire — the failure'
+            + ' mode that takes longest to notice.',
+        });
+      }
+
+      const path = `/api/v1/scm/connections/${encodeURIComponent(args.connectionId)}/repositories`;
+      const body = {
+        boardId: args.boardId,
+        externalRepoId: args.externalRepoId,
+        externalFullName: args.externalFullName,
+        mergeFromColumnId: from,
+        mergeToColumnId: to,
+        onMergeAction: args.onMergeAction,
+        branchSample: args.branchSample,
+        advanceOnlyWhenAllMerged: args.advanceOnlyWhenAllMerged,
+        openPullsCardIntoProgress: args.openPullsCardIntoProgress,
+        stagingEnvironmentName: args.stagingEnvironmentName,
+        productionEnvironmentName: args.productionEnvironmentName,
+      };
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        body,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview.dryRun) {
+        return ok({
+          dryRun: true,
+          action: `Bind ${args.externalFullName} to board ${args.boardId}`,
+          movesCardsOnMerge:
+            to === undefined
+              ? 'No. Without both column ends this binding records deliveries but advances nothing.'
+              : `Yes: a merged pull request moves its card ${from} -> ${to}.`,
+          note: 'Nothing was written. Confirm to create the binding.',
+        });
+      }
+      const data = await api('POST', path, {
+        body,
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ bound: true, repository: data?.data ?? data });
+    }
+  );
 }
 
 export const SOURCE_CONTROL_TOOL_NAMES = [
   'list_source_control_connections',
   'get_source_control_connection_events',
+  'bind_repository_to_board',
 ];