@atlassian-dc-mcp/bitbucket 0.28.0 → 0.30.0

package/src/index.ts

@@ -1,6 +1,7 @@
 import { connectServer, createMcpServer, formatToolResponse, initializeRuntimeConfig } from '@atlassian-dc-mcp/common';
 import { BitbucketService, bitbucketToolSchemas } from './bitbucket-service.js';
 import { getBitbucketRuntimeConfig, getDefaultPageSize } from './config.js';
+import { resolveMergeGateway } from './merge-gateway.js';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
@@ -139,10 +140,10 @@ server.tool(
 
 server.tool(
   "bitbucket_updatePullRequestComment",
-  "Update an existing pull request comment. Use to edit text, change severity, or change state. On a BLOCKER (task) comment, state: 'RESOLVED' ticks the task. NOTE: this is the task-tick, not the thread-level 'Resolve' button on regular comment threads — that is a separate concept (CommentThread.resolved) and is not exposed by this endpoint. Requires the current 'version' from optimistic locking; fetch it via bitbucket_getPR_CommentsAndAction or use the version returned when the comment was created.",
+  "Update an existing pull request comment. Use to edit text, change severity, change task state, or resolve/reopen the comment thread. On a BLOCKER (task) comment, state: 'RESOLVED' ticks the task; threadResolved: true toggles the thread-level 'Resolve' button. These are independent and can be set separately. Requires the current 'version' from optimistic locking; fetch it via bitbucket_getPR_CommentsAndAction or use the version returned when the comment was created.",
   bitbucketToolSchemas.updatePullRequestComment,
-  async ({ projectKey, repositorySlug, pullRequestId, commentId, version, text, state, severity, output }) => {
-    const result = await bitbucketService.updatePullRequestComment(projectKey, repositorySlug, pullRequestId, commentId, version, text, state, severity, output);
+  async ({ projectKey, repositorySlug, pullRequestId, commentId, version, text, state, severity, threadResolved, output }) => {
+    const result = await bitbucketService.updatePullRequestComment(projectKey, repositorySlug, pullRequestId, commentId, version, text, state, severity, threadResolved, output);
     return formatToolResponse(result);
   }
 );
@@ -170,10 +171,10 @@ server.tool(
 
 server.tool(
   "bitbucket_createPullRequest",
-  "Create a new pull request in a Bitbucket repository. IMPORTANT: Before creating a PR, use bitbucket_getRequiredReviewers to fetch required reviewers for the source and target branches to ensure the PR is not created without mandatory reviewers.",
+  "Create a new pull request in a Bitbucket repository. Supports fork-based pull requests by passing fromProjectKey/fromRepositorySlug when the source repository differs from the destination (projectKey/repositorySlug). IMPORTANT: Before creating a PR, use bitbucket_getRequiredReviewers to fetch required reviewers for the source and target branches to ensure the PR is not created without mandatory reviewers.",
   bitbucketToolSchemas.createPullRequest,
-  async ({ projectKey, repositorySlug, title, description, fromRefId, toRefId, reviewers, draft, output }) => {
-    const result = await bitbucketService.createPullRequest(projectKey, repositorySlug, title, description, fromRefId, toRefId, reviewers, draft, output);
+  async ({ projectKey, repositorySlug, title, description, fromRefId, toRefId, reviewers, draft, output, fromProjectKey, fromRepositorySlug }) => {
+    const result = await bitbucketService.createPullRequest(projectKey, repositorySlug, title, description, fromRefId, toRefId, reviewers, draft, output, fromProjectKey, fromRepositorySlug);
     return formatToolResponse(result);
   }
 );
@@ -188,6 +189,44 @@ server.tool(
   }
 );
 
+server.tool(
+  "bitbucket_canMergePullRequest",
+  "Check whether a pull request can be merged. Read-only: returns canMerge, whether the pull request is conflicted, and any merge-check vetoes (e.g. missing approvals, unresolved tasks, failed builds). Use this before bitbucket_mergePullRequest to see what is blocking a merge.",
+  bitbucketToolSchemas.canMergePullRequest,
+  async ({ projectKey, repositorySlug, pullRequestId }) => {
+    const result = await bitbucketService.getPullRequestMergeability(projectKey, repositorySlug, pullRequestId);
+    return formatToolResponse(result);
+  }
+);
+
+const mergeGateway = resolveMergeGateway();
+
+// Merging lands code on a shared branch and cannot be undone through the API, so the tool is
+// only registered when the operator has explicitly enabled it for specific repositories.
+if (mergeGateway.enabled) {
+  const scope = `Allowed on this server: ${mergeGateway.repos.join(', ')}`
+    + (mergeGateway.targetRefs.length > 0 ? `; target branches: ${mergeGateway.targetRefs.join(', ')}` : '')
+    + '.';
+  server.tool(
+    "bitbucket_mergePullRequest",
+    `Merge a pull request. IMPORTANT: you MUST first call bitbucket_getPullRequest to get the current 'version' — it is required for optimistic locking and a stale version is rejected. The merge is refused if the pull request is conflicted or a merge check vetoes it; use bitbucket_canMergePullRequest to inspect blockers first. This operation is not reversible through the API. ${scope}`,
+    bitbucketToolSchemas.mergePullRequest,
+    async ({ projectKey, repositorySlug, pullRequestId, version, strategyId, message, output }) => {
+      const result = await bitbucketService.mergePullRequest({
+        projectKey,
+        repositorySlug,
+        pullRequestId,
+        version,
+        strategyId,
+        message,
+        output,
+        gateway: mergeGateway,
+      });
+      return formatToolResponse(result);
+    }
+  );
+}
+
 server.tool(
   "bitbucket_getRequiredReviewers",
   "Get required reviewers for pull request creation. Returns a set of users who are required reviewers for pull requests created from the given source repository and ref to the given target ref in this repository.",

package/src/merge-gateway.ts

@@ -0,0 +1,132 @@
+/**
+ * Operator-controlled gate for merging pull requests.
+ *
+ * A merge writes to a shared branch and cannot be undone through the API, so it is
+ * disabled by default: `bitbucket_mergePullRequest` is not even registered unless the
+ * operator enables it and names the repositories it may merge in. The allowed scope is
+ * read from the environment once at startup, so the model can never select or widen it.
+ * Read-only mergeability checks are not gated.
+ */
+export interface MergeGateway {
+  /** Whether merging is enabled and at least one valid repository pattern resolved. */
+  enabled: boolean;
+  /** Allowed `PROJECT/repository-slug` targets; a `PROJECT/*` entry allows the whole project. */
+  repos: string[];
+  /** Allowed target refs; a trailing `*` matches a prefix. Empty means any ref in an allowed repository. */
+  targetRefs: string[];
+}
+
+type Env = Record<string, string | undefined>;
+type Warn = (message: string) => void;
+
+const DISABLED: MergeGateway = { enabled: false, repos: [], targetRefs: [] };
+
+const REPO_ENTRY_RE = /^[^\s/]+\/[^\s/]+$/;
+
+function readBool(env: Env, name: string): boolean {
+  const value = env[name]?.trim().toLowerCase();
+  return value === 'true' || value === '1' || value === 'yes';
+}
+
+function parseList(raw: string | undefined): string[] {
+  return (raw ?? '').split(/[,;\s]+/).map(entry => entry.trim()).filter(Boolean);
+}
+
+function dedupe(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+/**
+ * Accepts `PROJECT/repository-slug` or `PROJECT/*`. The project key is upper-cased and
+ * the slug lower-cased to match the casing the REST API uses, so comparisons are exact.
+ */
+function normalizeRepoEntry(entry: string, warn: Warn): string | undefined {
+  if (!REPO_ENTRY_RE.test(entry)) {
+    warn(`Ignoring merge repository entry that is not "PROJECT/repository-slug" or "PROJECT/*": "${entry}"`);
+    return undefined;
+  }
+  const [projectKey, slug] = entry.split('/');
+  if (projectKey === '*') {
+    warn(`Ignoring merge repository entry that would allow every project: "${entry}"`);
+    return undefined;
+  }
+  return `${projectKey.toUpperCase()}/${slug.toLowerCase()}`;
+}
+
+/** Bare branch names are expanded so operators can write `develop` instead of `refs/heads/develop`. */
+function normalizeRefEntry(entry: string): string {
+  return entry.startsWith('refs/') ? entry : `refs/heads/${entry}`;
+}
+
+function matchesPattern(value: string, pattern: string): boolean {
+  return pattern.endsWith('*') ? value.startsWith(pattern.slice(0, -1)) : value === pattern;
+}
+
+/**
+ * Reads the merge gateway configuration from the environment. Merging only activates
+ * when the flag is set and at least one repository entry is valid; otherwise a warning
+ * is logged and the gateway stays disabled.
+ */
+export function resolveMergeGateway(options?: { env?: Env; warn?: Warn }): MergeGateway {
+  const env = options?.env ?? process.env;
+  const warn = options?.warn ?? ((message: string) => console.error(`[merge-gateway] ${message}`));
+
+  if (!readBool(env, 'BITBUCKET_MERGE_ENABLED')) {
+    return DISABLED;
+  }
+
+  const repos = dedupe(
+    parseList(env.BITBUCKET_MERGE_ALLOWED_REPOS)
+      .map(entry => normalizeRepoEntry(entry, warn))
+      .filter((entry): entry is string => Boolean(entry)),
+  );
+
+  if (repos.length === 0) {
+    warn(
+      'Merging was enabled but no valid repository is configured (set BITBUCKET_MERGE_ALLOWED_REPOS ' +
+        'to a list of "PROJECT/repository-slug" or "PROJECT/*" entries); the merge tool will stay disabled.',
+    );
+    return DISABLED;
+  }
+
+  return {
+    enabled: true,
+    repos,
+    targetRefs: dedupe(parseList(env.BITBUCKET_MERGE_ALLOWED_TARGET_REFS).map(normalizeRefEntry)),
+  };
+}
+
+/** Throws unless the gateway allows merging in this repository. No network call. */
+export function assertRepoMergeAllowed(gateway: MergeGateway, projectKey: string, repositorySlug: string): void {
+  if (!gateway.enabled) {
+    throw new Error(
+      'Merging pull requests is disabled on this server. Enable it with BITBUCKET_MERGE_ENABLED ' +
+        'and list the allowed repositories in BITBUCKET_MERGE_ALLOWED_REPOS.',
+    );
+  }
+  const target = `${projectKey.toUpperCase()}/${repositorySlug.toLowerCase()}`;
+  if (!gateway.repos.some(pattern => matchesPattern(target, pattern))) {
+    throw new Error(
+      `Merging is not allowed in ${target} on this server. Allowed: ${gateway.repos.join(', ')}.`,
+    );
+  }
+}
+
+/** Throws unless the gateway allows merging into this target ref. A gateway with no ref restriction allows all. */
+export function assertTargetRefMergeAllowed(gateway: MergeGateway, targetRefId: string | undefined): void {
+  if (gateway.targetRefs.length === 0) {
+    return;
+  }
+  if (!targetRefId) {
+    throw new Error(
+      'Could not determine the target branch of the pull request, and this server restricts which ' +
+        'branches may be merged into (BITBUCKET_MERGE_ALLOWED_TARGET_REFS); refusing to merge.',
+    );
+  }
+  if (!gateway.targetRefs.some(pattern => matchesPattern(targetRefId, pattern))) {
+    throw new Error(
+      `Merging into ${targetRefId} is not allowed on this server. ` +
+        `Allowed target refs: ${gateway.targetRefs.join(', ')}.`,
+    );
+  }
+}

package/src/pr-comment-mapper.ts

@@ -148,6 +148,7 @@ interface SimplifiedComment {
   comments: SimplifiedComment[];
   threadResolved: boolean;
   state: string;
+  severity: string;
 }
 
 interface SimplifiedActivity {
@@ -167,6 +168,8 @@ export interface SimplifiedPRResponse {
     prAuthor?: SimplifiedUser;
     commentCount: number;
     unresolvedCount: number;
+    blockerCount: number;
+    unresolvedBlockerCount: number;
   };
 }
 
@@ -271,7 +274,8 @@ function simplifyComment(comment: Comment, ancestorIds: Set<number> = new Set())
       .filter(childComment => !nextAncestorIds.has(childComment.id))
       .map(childComment => simplifyComment(childComment, nextAncestorIds)),
     threadResolved: comment.threadResolved,
-    state: comment.state
+    state: comment.state,
+    severity: comment.severity
   };
 }
 
@@ -361,9 +365,11 @@ export function simplifyBitbucketPRComments(
   // Find PR author (usually the one who OPENED the PR)
   const prAuthor = activities.find(a => a.action === 'OPENED')?.user;
 
-  // Count comments and unresolved threads
+  // Count comments, unresolved threads and blocker tasks
   const comments = activities.filter(a => a.action === 'COMMENTED' && a.comment);
   const unresolvedCount = comments.filter(a => a.comment && !a.comment.threadResolved).length;
+  const blockers = comments.filter(a => a.comment && a.comment.severity === 'BLOCKER');
+  const unresolvedBlockerCount = blockers.filter(a => a.comment && a.comment.state !== 'RESOLVED').length;
 
   return {
     isLastPage: filteredResponse.isLastPage ?? true,
@@ -372,7 +378,9 @@ export function simplifyBitbucketPRComments(
       totalActivities: activities.length,
       ...(prAuthor && { prAuthor }),
       commentCount: comments.length,
-      unresolvedCount
+      unresolvedCount,
+      blockerCount: blockers.length,
+      unresolvedBlockerCount
     }
   };
 }

package/src/pr-merge.ts

@@ -0,0 +1,94 @@
+import { handleApiOperation } from '@atlassian-dc-mcp/common';
+import { PullRequestsService } from './bitbucket-client/index.js';
+import {
+  BitbucketMutationOutputMode,
+  shapeMergeability,
+  shapePullRequestAck,
+} from './bitbucket-response-mapper.js';
+import { assertRepoMergeAllowed, assertTargetRefMergeAllowed, type MergeGateway } from './merge-gateway.js';
+
+export interface MergePullRequestParams {
+  projectKey: string;
+  repositorySlug: string;
+  pullRequestId: string;
+  /** Current PR version, required for optimistic locking. */
+  version: number;
+  gateway: MergeGateway;
+  strategyId?: string;
+  message?: string;
+  output?: BitbucketMutationOutputMode;
+}
+
+/** Read-only mergeability check: reports conflicts and merge-check vetoes. */
+export async function fetchMergeability(projectKey: string, repositorySlug: string, pullRequestId: string) {
+  const result = await handleApiOperation(
+    () => PullRequestsService.canMerge(projectKey, pullRequestId, repositorySlug),
+    'Error checking pull request mergeability',
+  );
+
+  if (result.success && result.data) {
+    return { ...result, data: shapeMergeability(result.data) };
+  }
+
+  return result;
+}
+
+function describeVetoes(vetoes: Array<{ summary?: string; detail?: string }>): string {
+  return vetoes
+    .map(veto => [veto.summary, veto.detail].filter(Boolean).join(' — '))
+    .filter(Boolean)
+    .join('; ');
+}
+
+async function assertMergeable(projectKey: string, repositorySlug: string, pullRequestId: string): Promise<void> {
+  const mergeability = shapeMergeability(
+    await PullRequestsService.canMerge(projectKey, pullRequestId, repositorySlug),
+  );
+  if (mergeability.canMerge) {
+    return;
+  }
+  const cause = mergeability.conflicted ? 'it has conflicts' : 'a merge check vetoed the merge';
+  const reasons = describeVetoes(mergeability.vetoes);
+  throw new Error(`Pull request cannot be merged: ${cause}${reasons ? `. ${reasons}` : ''}`);
+}
+
+/** Only fetches the pull request when the operator restricts target branches. */
+async function assertTargetRefAllowed(params: MergePullRequestParams): Promise<void> {
+  if (params.gateway.targetRefs.length === 0) {
+    return;
+  }
+  const pullRequest: any = await PullRequestsService.get3(
+    params.projectKey,
+    params.pullRequestId,
+    params.repositorySlug,
+  );
+  assertTargetRefMergeAllowed(params.gateway, pullRequest?.toRef?.id);
+}
+
+/**
+ * Merge a pull request under the operator's merge policy. Order matters: the repository
+ * (and target branch, when restricted) is checked before any request, and the mergeability
+ * check runs before the POST so a conflicted or vetoed pull request is refused without
+ * issuing the write.
+ */
+export async function mergePullRequest(params: MergePullRequestParams) {
+  const { projectKey, repositorySlug, pullRequestId, version, gateway } = params;
+
+  const result = await handleApiOperation(async () => {
+    assertRepoMergeAllowed(gateway, projectKey, repositorySlug);
+    await assertTargetRefAllowed(params);
+    await assertMergeable(projectKey, repositorySlug, pullRequestId);
+
+    return PullRequestsService.merge(projectKey, pullRequestId, repositorySlug, String(version), {
+      version,
+      ...(params.strategyId ? { strategyId: params.strategyId } : {}),
+      ...(params.message ? { message: params.message } : {}),
+    });
+  }, 'Error merging pull request');
+
+  if (result.success && result.data && params.output !== 'full') {
+    return { ...result, data: shapePullRequestAck(result.data) };
+  }
+
+  return result;
+}