@atlassian-dc-mcp/bitbucket 0.29.0 → 0.31.0

package/src/__tests__/pr-merge.test.ts

@@ -0,0 +1,206 @@
+import { PullRequestsService } from '../bitbucket-client/index.js';
+import { fetchMergeability, mergePullRequest } from '../pr-merge.js';
+import type { MergeGateway } from '../merge-gateway.js';
+
+jest.mock('../bitbucket-client/index.js', () => ({
+  PullRequestsService: {
+    canMerge: jest.fn(),
+    merge: jest.fn(),
+    get3: jest.fn(),
+  },
+  OpenAPI: { BASE: '', TOKEN: '', VERSION: '' },
+}));
+
+const canMerge = PullRequestsService.canMerge as jest.Mock;
+const merge = PullRequestsService.merge as jest.Mock;
+const getPullRequest = PullRequestsService.get3 as jest.Mock;
+
+const OPEN_GATEWAY: MergeGateway = { enabled: true, repos: ['PROJ/demo'], targetRefs: [] };
+const CLEAN = { canMerge: true, conflicted: false, outcome: 'CLEAN', vetoes: [] };
+const MERGED_PR = {
+  id: 42,
+  version: 3,
+  title: 'Add merge tool',
+  state: 'MERGED',
+  fromRef: { id: 'refs/heads/feature' },
+  toRef: { id: 'refs/heads/develop' },
+  reviewers: [],
+};
+
+const baseParams = {
+  projectKey: 'PROJ',
+  repositorySlug: 'demo',
+  pullRequestId: '42',
+  version: 2,
+};
+
+describe('fetchMergeability', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('shapes vetoes into summary/detail pairs', async () => {
+    canMerge.mockResolvedValue({
+      canMerge: false,
+      conflicted: false,
+      outcome: 'VETOED',
+      vetoes: [{ summaryMessage: 'Not enough approvals', detailedMessage: '2 required, 1 given' }],
+    });
+
+    const result = await fetchMergeability('PROJ', 'demo', '42');
+
+    expect(canMerge).toHaveBeenCalledWith('PROJ', '42', 'demo');
+    expect(result.data).toEqual({
+      canMerge: false,
+      conflicted: false,
+      outcome: 'VETOED',
+      vetoes: [{ summary: 'Not enough approvals', detail: '2 required, 1 given' }],
+    });
+  });
+
+  it('reports API failures without shaping', async () => {
+    canMerge.mockRejectedValue(new Error('boom'));
+
+    const result = await fetchMergeability('PROJ', 'demo', '42');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('boom');
+  });
+});
+
+describe('mergePullRequest', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('merges with the version as an optimistic lock and returns a compact ack', async () => {
+    canMerge.mockResolvedValue(CLEAN);
+    merge.mockResolvedValue(MERGED_PR);
+
+    const result = await mergePullRequest({ ...baseParams, gateway: OPEN_GATEWAY });
+
+    expect(merge).toHaveBeenCalledWith('PROJ', '42', 'demo', '2', { version: 2 });
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual({
+      id: 42,
+      version: 3,
+      title: 'Add merge tool',
+      state: 'MERGED',
+      fromRefId: 'refs/heads/feature',
+      toRefId: 'refs/heads/develop',
+      reviewerCount: 0,
+    });
+  });
+
+  it('passes the strategy and message through, and can return the full payload', async () => {
+    canMerge.mockResolvedValue(CLEAN);
+    merge.mockResolvedValue(MERGED_PR);
+
+    const result = await mergePullRequest({
+      ...baseParams,
+      gateway: OPEN_GATEWAY,
+      strategyId: 'squash',
+      message: 'Squashed',
+      output: 'full',
+    });
+
+    expect(merge).toHaveBeenCalledWith('PROJ', '42', 'demo', '2', {
+      version: 2,
+      strategyId: 'squash',
+      message: 'Squashed',
+    });
+    expect(result.data).toBe(MERGED_PR);
+  });
+
+  it('refuses without any request when merging is disabled', async () => {
+    const result = await mergePullRequest({
+      ...baseParams,
+      gateway: { enabled: false, repos: [], targetRefs: [] },
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/disabled on this server/);
+    expect(canMerge).not.toHaveBeenCalled();
+    expect(merge).not.toHaveBeenCalled();
+  });
+
+  it('refuses a repository outside the allowed list without any request', async () => {
+    const result = await mergePullRequest({
+      ...baseParams,
+      repositorySlug: 'other-repo',
+      gateway: OPEN_GATEWAY,
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/not allowed in PROJ\/other-repo/);
+    expect(merge).not.toHaveBeenCalled();
+  });
+
+  it('refuses a target branch outside the allowed refs and never merges', async () => {
+    getPullRequest.mockResolvedValue({ toRef: { id: 'refs/heads/master' } });
+
+    const result = await mergePullRequest({
+      ...baseParams,
+      gateway: { enabled: true, repos: ['PROJ/demo'], targetRefs: ['refs/heads/develop'] },
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/refs\/heads\/master is not allowed/);
+    expect(canMerge).not.toHaveBeenCalled();
+    expect(merge).not.toHaveBeenCalled();
+  });
+
+  it('merges when the pull request targets an allowed branch', async () => {
+    getPullRequest.mockResolvedValue({ toRef: { id: 'refs/heads/release/1.2' } });
+    canMerge.mockResolvedValue(CLEAN);
+    merge.mockResolvedValue(MERGED_PR);
+
+    const result = await mergePullRequest({
+      ...baseParams,
+      gateway: { enabled: true, repos: ['PROJ/demo'], targetRefs: ['refs/heads/release/*'] },
+    });
+
+    expect(result.success).toBe(true);
+    expect(merge).toHaveBeenCalled();
+  });
+
+  it('does not fetch the pull request when target branches are unrestricted', async () => {
+    canMerge.mockResolvedValue(CLEAN);
+    merge.mockResolvedValue(MERGED_PR);
+
+    await mergePullRequest({ ...baseParams, gateway: OPEN_GATEWAY });
+
+    expect(getPullRequest).not.toHaveBeenCalled();
+  });
+
+  it('refuses a conflicted pull request before issuing the merge', async () => {
+    canMerge.mockResolvedValue({ canMerge: false, conflicted: true, outcome: 'CONFLICTED', vetoes: [] });
+
+    const result = await mergePullRequest({ ...baseParams, gateway: OPEN_GATEWAY });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/has conflicts/);
+    expect(merge).not.toHaveBeenCalled();
+  });
+
+  it('refuses a vetoed pull request and reports the veto reasons', async () => {
+    canMerge.mockResolvedValue({
+      canMerge: false,
+      conflicted: false,
+      vetoes: [{ summaryMessage: 'Unresolved tasks', detailedMessage: '1 open task' }],
+    });
+
+    const result = await mergePullRequest({ ...baseParams, gateway: OPEN_GATEWAY });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/merge check vetoed the merge\. Unresolved tasks — 1 open task/);
+    expect(merge).not.toHaveBeenCalled();
+  });
+
+  it('surfaces a server-side merge failure such as a stale version', async () => {
+    canMerge.mockResolvedValue(CLEAN);
+    merge.mockRejectedValue({ status: 409, statusText: 'Conflict', body: { errors: [{ message: 'stale' }] } });
+
+    const result = await mergePullRequest({ ...baseParams, gateway: OPEN_GATEWAY });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Error merging pull request: 409 Conflict');
+    expect(result.details).toEqual({ errors: [{ message: 'stale' }] });
+  });
+});

package/src/bitbucket-response-mapper.ts

@@ -52,6 +52,8 @@ export function shapePullRequestCommentsResponse(
           totalActivities: Array.isArray(filteredResponse.values) ? filteredResponse.values.length : 0,
           commentCount: getCommentSummary(filteredResponse, options).length,
           unresolvedCount: 0,
+          blockerCount: 0,
+          unresolvedBlockerCount: 0,
         },
     items: getCommentSummary(filteredResponse, options),
   };
@@ -100,12 +102,37 @@ export function shapePullRequestAck(pullRequest: any): Record<string, any> {
   };
 }
 
+export interface MergeVeto {
+  summary?: string;
+  detail?: string;
+}
+
+export function shapeMergeability(mergeability: any): {
+  canMerge: boolean;
+  conflicted: boolean;
+  outcome?: string;
+  vetoes: MergeVeto[];
+} {
+  const vetoes = Array.isArray(mergeability?.vetoes) ? mergeability.vetoes : [];
+  return {
+    canMerge: mergeability?.canMerge === true,
+    conflicted: mergeability?.conflicted === true,
+    ...(typeof mergeability?.outcome === 'string' ? { outcome: mergeability.outcome } : {}),
+    vetoes: vetoes.map((veto: any) => ({
+      ...(typeof veto?.summaryMessage === 'string' ? { summary: veto.summaryMessage } : {}),
+      ...(typeof veto?.detailedMessage === 'string' ? { detail: veto.detailedMessage } : {}),
+    })),
+  };
+}
+
 export function shapePullRequestCommentAck(comment: any): Record<string, any> {
   const link = getLink(comment?.links);
   return {
     ...(comment?.id !== undefined ? { id: comment.id } : {}),
     ...(comment?.parent?.id !== undefined ? { parentId: comment.parent.id } : {}),
     ...(typeof comment?.state === 'string' ? { state: comment.state } : {}),
+    ...(typeof comment?.threadResolved === 'boolean' ? { threadResolved: comment.threadResolved } : {}),
+    ...(typeof comment?.severity === 'string' ? { severity: comment.severity } : {}),
     pending: comment?.state === 'PENDING',
     ...(typeof comment?.anchor?.path === 'string'
       ? {

package/src/bitbucket-service.ts

@@ -4,6 +4,7 @@ import { request as __request } from './bitbucket-client/core/request.js';
 import { handleApiOperation, resolveOpenApiBase } from '@atlassian-dc-mcp/common';
 import { simplifyInboxPullRequests } from './inbox-pr-mapper.js';
 import { BITBUCKET_PRODUCT, getDefaultPageSize, getMissingConfig } from './config.js';
+import { fetchMergeability, mergePullRequest, type MergePullRequestParams } from './pr-merge.js';
 import {
   BitbucketMutationOutputMode,
   BitbucketOutputMode,
@@ -214,6 +215,25 @@ export class BitbucketService {
     );
   }
 
+  /**
+   * Get the raw content of a file in a repository
+   * @param projectKey The project key
+   * @param repositorySlug The repository slug
+   * @param path The path to the file in the repository
+   * @param at Optional branch, tag or commit to read the file at. Defaults to the repository default branch
+   * @returns Promise with the raw file content
+   */
+  async getFileContent(projectKey: string, repositorySlug: string, path: string, at?: string) {
+    projectKey = projectKey.toUpperCase();
+    repositorySlug = repositorySlug.toLowerCase();
+    // Leading slashes would produce a double slash in the URL and a 404 from Bitbucket.
+    const filePath = path.replace(/^\/+/, '');
+    return handleApiOperation(
+      () => RepositoryService.streamRaw(filePath, projectKey, repositorySlug, at),
+      'Error fetching file content'
+    );
+  }
+
   /**
    * Get pull requests for a repository
    * @param projectKey The project key
@@ -460,18 +480,20 @@ export class BitbucketService {
   }
 
   /**
-   * Update an existing pull request comment. Use this to edit text, change severity, or change state.
-   * On a BLOCKER (task) comment, setting state to 'RESOLVED' ticks the task. Note: this is NOT the same
-   * as the thread-level "Resolve" button on regular comment threads — that operates on CommentThread.resolved
-   * and is a separate concept not exposed by this endpoint.
+   * Update an existing pull request comment. Use this to edit text, change severity, change state, or
+   * resolve/reopen a comment thread. State and thread resolution are independent: `state` is the task
+   * state of a BLOCKER comment ('RESOLVED' ticks the task, 'OPEN' un-ticks it), while `threadResolved`
+   * toggles the thread-level "Resolve" button. A root BLOCKER comment can hold these independently, so
+   * they are sent as separate fields.
    * @param projectKey The project key
    * @param repositorySlug The repository slug
    * @param pullRequestId The pull request ID
    * @param commentId The comment ID to update
    * @param version The current version of the comment (required for optimistic locking)
    * @param text Optional new comment text
-   * @param state Optional new state. On a BLOCKER comment, 'RESOLVED' ticks the task and 'OPEN' un-ticks it.
+   * @param state Optional new task state. On a BLOCKER comment, 'RESOLVED' ticks the task and 'OPEN' un-ticks it.
    * @param severity Optional new severity. 'BLOCKER' converts a comment into a task, 'NORMAL' converts a task back to a regular comment.
+   * @param threadResolved Optional thread resolution. `true` resolves the comment thread, `false` reopens it.
    * @returns Promise with updated comment data
    */
   async updatePullRequestComment(
@@ -483,6 +505,7 @@ export class BitbucketService {
     text?: string,
     state?: 'OPEN' | 'RESOLVED',
     severity?: 'NORMAL' | 'BLOCKER',
+    threadResolved?: boolean,
     output: BitbucketMutationOutputMode = 'ack'
   ) {
     projectKey = projectKey.toUpperCase();
@@ -501,6 +524,10 @@ export class BitbucketService {
       comment.severity = severity;
     }
 
+    if (threadResolved !== undefined) {
+      comment.threadResolved = threadResolved;
+    }
+
     const result = await handleApiOperation(
       () => PullRequestsService.updateComment2(
         projectKey,
@@ -522,6 +549,36 @@ export class BitbucketService {
     return result;
   }
 
+  /**
+   * Check whether a pull request can be merged. Read-only: reports conflicts and any
+   * merge-check vetoes without changing anything.
+   * @param projectKey The project key
+   * @param repositorySlug The repository slug
+   * @param pullRequestId The pull request ID
+   * @returns Promise with the mergeability status
+   */
+  async getPullRequestMergeability(projectKey: string, repositorySlug: string, pullRequestId: string) {
+    return fetchMergeability(projectKey.toUpperCase(), repositorySlug.toLowerCase(), pullRequestId);
+  }
+
+  /**
+   * Merge a pull request. Only permitted for repositories (and target branches) the operator
+   * allowed through the merge gateway; see merge-gateway.ts. A conflicted or vetoed pull
+   * request is refused before the merge request is sent.
+   * @param params.version The current pull request version, required for optimistic locking
+   * @param params.strategyId Optional merge strategy id (e.g. 'no-ff', 'squash', 'ff')
+   * @param params.message Optional merge commit message
+   * @param params.gateway The resolved operator merge policy
+   * @returns Promise with the merged pull request
+   */
+  async mergePullRequest(params: MergePullRequestParams) {
+    return mergePullRequest({
+      ...params,
+      projectKey: params.projectKey.toUpperCase(),
+      repositorySlug: params.repositorySlug.toLowerCase(),
+    });
+  }
+
   /**
    * Get a user by slug, or search for users by name/email filter
    * @param userSlug Optional exact slug to look up a specific user
@@ -649,8 +706,8 @@ export class BitbucketService {
 
   /**
    * Create a pull request
-   * @param projectKey The project key
-   * @param repositorySlug The repository slug
+   * @param projectKey The project key (also used as the destination repository's project)
+   * @param repositorySlug The repository slug (also used as the destination repository's slug)
    * @param title The pull request title
    * @param description Optional pull request description
    * @param fromRefId The source branch (e.g., 'refs/heads/feature-branch')
@@ -658,6 +715,10 @@ export class BitbucketService {
    * @param reviewers Optional array of reviewer usernames
    * @param draft Optional flag to create the pull request as a draft
    * @param output Return a compact acknowledgement or the full API response. Defaults to 'ack'.
+   * @param fromProjectKey Optional source repository's project key, when it differs from
+   *   projectKey (fork-based pull requests). Defaults to projectKey.
+   * @param fromRepositorySlug Optional source repository's slug, when it differs from
+   *   repositorySlug (fork-based pull requests). Defaults to repositorySlug.
    * @returns Promise with created pull request data
    */
   async createPullRequest(
@@ -669,7 +730,9 @@ export class BitbucketService {
     toRefId: string,
     reviewers?: string[],
     draft?: boolean,
-    output: BitbucketMutationOutputMode = 'ack'
+    output: BitbucketMutationOutputMode = 'ack',
+    fromProjectKey?: string,
+    fromRepositorySlug?: string
   ) {
     projectKey = projectKey.toUpperCase();
     repositorySlug = repositorySlug.toLowerCase();
@@ -679,9 +742,9 @@ export class BitbucketService {
       fromRef: {
         id: fromRefId,
         repository: {
-          slug: repositorySlug,
+          slug: (fromRepositorySlug ?? repositorySlug).toLowerCase(),
           project: {
-            key: projectKey
+            key: (fromProjectKey ?? projectKey).toUpperCase()
           }
         }
       },
@@ -984,6 +1047,12 @@ export const bitbucketToolSchemas = {
     projectKey: z.string().describe("The project key"),
     repositorySlug: z.string().describe("The repository slug")
   },
+  getFileContent: {
+    projectKey: z.string().describe("The project key"),
+    repositorySlug: z.string().describe("The repository slug"),
+    path: z.string().describe("Path to the file in the repository (e.g. 'src/index.ts')"),
+    at: z.string().optional().describe("A branch, tag or commit to read the file at (e.g. 'refs/heads/main', 'feature/x', or a commit id). Defaults to the repository's default branch")
+  },
   getCommits: {
     projectKey: z.string().describe("The project key"),
     repositorySlug: z.string().describe("The repository slug"),
@@ -1035,8 +1104,9 @@ export const bitbucketToolSchemas = {
     commentId: z.string().describe("The ID of the comment to update"),
     version: z.number().describe("The current version of the comment, required for optimistic locking. Get it from bitbucket_getPR_CommentsAndAction or from the response of the original post/update."),
     text: z.string().optional().describe("New comment text. Omit to leave unchanged."),
-    state: z.enum(['OPEN', 'RESOLVED']).optional().describe("New state. On a BLOCKER (task) comment, 'RESOLVED' ticks the task and 'OPEN' un-ticks it. This is NOT the thread-level 'Resolve' button on regular comment threads — that is a separate concept (CommentThread.resolved) and is not exposed by this endpoint."),
+    state: z.enum(['OPEN', 'RESOLVED']).optional().describe("New task state. On a BLOCKER (task) comment, 'RESOLVED' ticks the task and 'OPEN' un-ticks it. This is the task state only — to resolve or reopen the comment thread itself use threadResolved."),
     severity: z.enum(['NORMAL', 'BLOCKER']).optional().describe("New severity. Use 'BLOCKER' to convert a comment into a task, 'NORMAL' to convert it back."),
+    threadResolved: z.boolean().optional().describe("Thread resolution. Set true to resolve the comment thread (the 'Resolve' button) or false to reopen it. Independent of state: a BLOCKER comment's task state and its thread resolution can differ."),
     output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
   },
   getUser: {
@@ -1064,15 +1134,17 @@ export const bitbucketToolSchemas = {
     whitespace: z.string().optional().describe("Optional whitespace flag which can be set to 'ignore-all'")
   },
   createPullRequest: {
-    projectKey: z.string().describe("The project key"),
-    repositorySlug: z.string().describe("The repository slug"),
+    projectKey: z.string().describe("The destination repository's project key"),
+    repositorySlug: z.string().describe("The destination repository's slug"),
     title: z.string().describe("The pull request title"),
     description: z.string().optional().describe("The pull request description"),
     fromRefId: z.string().describe("The source branch reference ID (e.g., 'refs/heads/feature-branch')"),
     toRefId: z.string().describe("The destination branch reference ID (e.g., 'refs/heads/main')"),
     draft: z.boolean().optional().describe("If true, the pull request is created as a draft (work-in-progress) and cannot be merged until marked ready."),
     reviewers: z.array(z.string()).optional().describe("Optional array of reviewer usernames (use the 'name' field from Bitbucket user objects, not 'slug')"),
-    output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
+    output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack."),
+    fromProjectKey: z.string().optional().describe("The source repository's project key, when creating a fork-based pull request where the source repository differs from the destination repository (projectKey). Defaults to projectKey."),
+    fromRepositorySlug: z.string().optional().describe("The source repository's slug, when creating a fork-based pull request where the source repository differs from the destination repository (repositorySlug). Defaults to repositorySlug.")
   },
   updatePullRequest: {
     projectKey: z.string().describe("The project key"),
@@ -1085,6 +1157,20 @@ export const bitbucketToolSchemas = {
     reviewers: z.array(z.string()).optional().describe("Optional array of reviewer usernames to set (use the 'name' field from Bitbucket user objects, not 'slug')"),
     output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
   },
+  canMergePullRequest: {
+    projectKey: z.string().describe("The project key"),
+    repositorySlug: z.string().describe("The repository slug"),
+    pullRequestId: z.string().describe("The pull request ID")
+  },
+  mergePullRequest: {
+    projectKey: z.string().describe("The project key"),
+    repositorySlug: z.string().describe("The repository slug"),
+    pullRequestId: z.string().describe("The pull request ID"),
+    version: z.number().describe("The current version of the pull request (required for optimistic locking). Fetch it with bitbucket_getPullRequest immediately before merging — the server rejects a stale version, which is what stops a merge of code you have not seen."),
+    strategyId: z.string().optional().describe("Merge strategy id, e.g. 'no-ff', 'ff', 'ff-only', 'rebase-no-ff', 'rebase-ff-only', 'squash', 'squash-ff-only'. Omit to use the strategy configured for the repository."),
+    message: z.string().optional().describe("Commit message for the merge commit. Omit to let Bitbucket generate it."),
+    output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
+  },
   getRequiredReviewers: {
     projectKey: z.string().describe("The project key"),
     repositorySlug: z.string().describe("The repository slug"),

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);
@@ -67,6 +68,16 @@ server.tool(
   }
 );
 
+server.tool(
+  "bitbucket_getFileContent",
+  "Get the raw content of a file in a Bitbucket repository, at a branch, tag or commit. Use this to read a source file without cloning the repository. 'at' defaults to the repository's default branch. Pointing 'path' at a directory returns that directory's git tree listing instead of file content.",
+  bitbucketToolSchemas.getFileContent,
+  async ({ projectKey, repositorySlug, path, at }) => {
+    const result = await bitbucketService.getFileContent(projectKey, repositorySlug, path, at);
+    return formatToolResponse(result);
+  }
+);
+
 server.tool(
   "bitbucket_getCommits",
   "Get commits for a Bitbucket repository",
@@ -139,10 +150,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 +181,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 +199,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.",