@atlassian-dc-mcp/bitbucket 0.12.2 → 0.13.0

package/src/bitbucket-service.ts

@@ -2,15 +2,47 @@ import { z } from 'zod';
 import { OpenAPI, ProjectService, PullRequestsService, RepositoryService } from './bitbucket-client/index.js';
 import { request as __request } from './bitbucket-client/core/request.js';
 import { handleApiOperation } from '@atlassian-dc-mcp/common';
-import { simplifyBitbucketPRComments } from './pr-comment-mapper.js';
-import { simplifyBitbucketPRChanges } from './pr-changes-mapper.js';
 import { simplifyInboxPullRequests } from './inbox-pr-mapper.js';
+import { getDefaultPageSize, getMissingConfig } from './config.js';
+import {
+  BitbucketMutationOutputMode,
+  BitbucketOutputMode,
+  shapePullRequestAck,
+  shapePullRequestChangesResponse,
+  shapePullRequestCommentAck,
+  shapePullRequestCommentsResponse,
+} from './bitbucket-response-mapper.js';
+
+function resolveToken(token: string | (() => string | undefined), missingTokenMessage: string) {
+  return async () => {
+    const resolvedToken = typeof token === 'function' ? token() : token;
+    if (!resolvedToken) {
+      throw new Error(missingTokenMessage);
+    }
+    return resolvedToken;
+  };
+}
 
 export class BitbucketService {
-  constructor(host: string, token: string, fullBaseUrl?: string) {
-    OpenAPI.BASE = fullBaseUrl ?? `https://${host}/rest`;
-    OpenAPI.TOKEN = token;
+  private readonly getPageSize: () => number;
+
+  constructor(
+    host: string | undefined,
+    token: string | (() => string | undefined),
+    fullBaseUrl?: string,
+    getPageSize: () => number = getDefaultPageSize,
+  ) {
+    if (fullBaseUrl) {
+      OpenAPI.BASE = fullBaseUrl;
+    } else if (host) {
+      OpenAPI.BASE = `https://${host}/rest`;
+    } else {
+      throw new Error('Either host or fullBaseUrl must be provided');
+    }
+
+    OpenAPI.TOKEN = resolveToken(token, 'Missing required environment variable: BITBUCKET_API_TOKEN');
     OpenAPI.VERSION = '1.0';
+    this.getPageSize = getPageSize;
   }
 
   /**
@@ -24,7 +56,7 @@ export class BitbucketService {
    * @returns Promise with commits data
    */
   async getCommits(projectKey: string, repositorySlug: string, path?: string, since?: string, until?: string,
-    limit: number = 25
+    limit?: number
   ) {
     return handleApiOperation(
       () => RepositoryService.getCommits(
@@ -40,7 +72,7 @@ export class BitbucketService {
         undefined, // merges
         undefined, // ignoreMissing
         0, // start
-        limit
+        limit ?? this.getPageSize()
       ),
       'Error fetching commits'
     );
@@ -54,9 +86,9 @@ export class BitbucketService {
    * @param limit Optional pagination limit (default: 25)
    * @returns Promise with projects data
    */
-  async getProjects(name?: string, permission?: string, start?: number, limit: number = 25) {
+  async getProjects(name?: string, permission?: string, start?: number, limit?: number) {
     return handleApiOperation(
-      () => ProjectService.getProjects(name, permission, start, limit),
+      () => ProjectService.getProjects(name, permission, start, limit ?? this.getPageSize()),
       'Error fetching projects'
     );
   }
@@ -80,9 +112,9 @@ export class BitbucketService {
    * @param limit Optional pagination limit (default: 25)
    * @returns Promise with repositories data
    */
-  async getRepositories(projectKey: string, start?: number, limit: number = 25) {
+  async getRepositories(projectKey: string, start?: number, limit?: number) {
     return handleApiOperation(
-      () => ProjectService.getRepositories(projectKey, start, limit),
+      () => ProjectService.getRepositories(projectKey, start, limit ?? this.getPageSize()),
       'Error fetching repositories'
     );
   }
@@ -128,7 +160,7 @@ export class BitbucketService {
     order?: string,
     direction?: string,
     start?: number,
-    limit: number = 25
+    limit?: number
   ) {
     return handleApiOperation(
       () => PullRequestsService.getPage(
@@ -143,7 +175,7 @@ export class BitbucketService {
         order,
         direction,
         start,
-        limit
+        limit ?? this.getPageSize()
       ),
       'Error fetching pull requests'
     );
@@ -167,8 +199,13 @@ export class BitbucketService {
     );
   }
 
-  async getPullRequestCommentsAndActions(projectKey: string, repositorySlug: string, pullRequestId: string, start?: number,
-    limit: number = 25
+  async getPullRequestCommentsAndActions(
+    projectKey: string,
+    repositorySlug: string,
+    pullRequestId: string,
+    start?: number,
+    limit?: number,
+    output: BitbucketOutputMode = 'compact'
   ) {
     const result = await handleApiOperation(
       () => PullRequestsService.getActivities(
@@ -178,17 +215,15 @@ export class BitbucketService {
         undefined,
         undefined,
         start,
-        limit
+        limit ?? this.getPageSize()
       ),
       'Error fetching pull request comments'
     );
 
-    // Apply simplification if the API call was successful
     if (result.success && result.data) {
-      const simplifiedData = simplifyBitbucketPRComments(result.data);
       return {
         success: true,
-        data: simplifiedData
+        data: shapePullRequestCommentsResponse(result.data, output)
       };
     }
 
@@ -217,7 +252,8 @@ export class BitbucketService {
     untilId?: string,
     withComments?: string,
     start?: number,
-    limit: number = 25
+    limit?: number,
+    output: BitbucketOutputMode = 'compact'
   ) {
     const result = await handleApiOperation(
       () => PullRequestsService.streamChanges1(
@@ -229,17 +265,15 @@ export class BitbucketService {
         untilId,
         withComments,
         start,
-        limit
+        limit ?? this.getPageSize()
       ),
       'Error fetching pull request changes'
     );
 
-    // Apply simplification if the API call was successful
     if (result.success && result.data) {
-      const simplifiedData = simplifyBitbucketPRChanges(result.data);
       return {
         ...result,
-        data: simplifiedData
+        data: shapePullRequestChangesResponse(result.data, output)
       };
     }
 
@@ -270,7 +304,8 @@ export class BitbucketService {
     filePath?: string,
     line?: number,
     lineType?: 'ADDED' | 'REMOVED' | 'CONTEXT',
-    pending?: boolean
+    pending?: boolean,
+    output: BitbucketMutationOutputMode = 'ack'
   ) {
     const comment: any = {
       text
@@ -302,7 +337,7 @@ export class BitbucketService {
       }
     }
 
-    return handleApiOperation(
+    const result = await handleApiOperation(
       () => PullRequestsService.createComment2(
         projectKey,
         pullRequestId,
@@ -311,6 +346,15 @@ export class BitbucketService {
       ),
       'Error posting pull request comment'
     );
+
+    if (result.success && result.data && output !== 'full') {
+      return {
+        ...result,
+        data: shapePullRequestCommentAck(result.data),
+      };
+    }
+
+    return result;
   }
 
   /**
@@ -452,7 +496,8 @@ export class BitbucketService {
     description: string | undefined,
     fromRefId: string,
     toRefId: string,
-    reviewers?: string[]
+    reviewers?: string[],
+    output: BitbucketMutationOutputMode = 'ack'
   ) {
     const pullRequestData: any = {
       title,
@@ -485,10 +530,19 @@ export class BitbucketService {
       }));
     }
 
-    return handleApiOperation(
+    const result = await handleApiOperation(
       () => PullRequestsService.create(projectKey, repositorySlug, pullRequestData),
       'Error creating pull request'
     );
+
+    if (result.success && result.data && output !== 'full') {
+      return {
+        ...result,
+        data: shapePullRequestAck(result.data),
+      };
+    }
+
+    return result;
   }
 
   /**
@@ -509,7 +563,8 @@ export class BitbucketService {
     version: number,
     title?: string,
     description?: string,
-    reviewers?: string[]
+    reviewers?: string[],
+    output: BitbucketMutationOutputMode = 'ack'
   ) {
     const pullRequestData: any = {
       version
@@ -531,10 +586,19 @@ export class BitbucketService {
       }));
     }
 
-    return handleApiOperation(
+    const result = await handleApiOperation(
       () => PullRequestsService.update(projectKey, pullRequestId, repositorySlug, pullRequestData),
       'Error updating pull request'
     );
+
+    if (result.success && result.data && output !== 'full') {
+      return {
+        ...result,
+        data: shapePullRequestAck(result.data),
+      };
+    }
+
+    return result;
   }
 
   /**
@@ -577,7 +641,7 @@ export class BitbucketService {
    * @param closedSince Optional timestamp (in milliseconds) to filter PRs closed after this date
    * @param order Order: NEWEST (default), OLDEST, or PARTICIPANT
    * @param start Optional pagination start
-   * @param limit Pagination limit (default: 10)
+   * @param limit Pagination limit (defaults to the package page size)
    * @returns Promise with dashboard pull requests data
    */
   async getDashboardPullRequests(
@@ -586,7 +650,7 @@ export class BitbucketService {
     closedSince?: number,
     order: string = 'NEWEST',
     start?: number,
-    limit: number = 10
+    limit?: number
   ) {
     return handleApiOperation(
       () => __request(OpenAPI, {
@@ -598,7 +662,7 @@ export class BitbucketService {
           'closedSince': closedSince,
           'order': order,
           'start': start,
-          'limit': limit,
+          'limit': limit ?? this.getPageSize(),
         },
         errors: {
           401: 'The currently authenticated user is not permitted to access the dashboard.',
@@ -611,17 +675,17 @@ export class BitbucketService {
   /**
    * Get pull requests from the authenticated user's inbox (PRs awaiting review)
    * @param start Optional pagination start
-   * @param limit Optional pagination limit (default: 25)
+   * @param limit Optional pagination limit (defaults to the package page size)
    * @returns Promise with inbox pull requests data
    */
-  async getInboxPullRequests(start?: number, limit: number = 25) {
+  async getInboxPullRequests(start?: number, limit?: number) {
     const result = await handleApiOperation(
       () => __request(OpenAPI, {
         method: 'GET',
         url: '/api/latest/inbox/pull-requests',
         query: {
           'start': start,
-          'limit': limit,
+          'limit': limit ?? this.getPageSize(),
         },
         errors: {
           401: 'The currently authenticated user is not permitted to access the inbox.',
@@ -641,16 +705,7 @@ export class BitbucketService {
   }
 
   static validateConfig(): string[] {
-    // Check for BITBUCKET_HOST or its alternative BITBUCKET_API_BASE_PATH
-    const requiredEnvVars = ['BITBUCKET_API_TOKEN'] as const;
-    const missingVars: string[] = requiredEnvVars.filter(varName => !process.env[varName]);
-
-    // Special handling for BITBUCKET_HOST with BITBUCKET_API_BASE_PATH as an alternative
-    if (!process.env.BITBUCKET_HOST && !process.env.BITBUCKET_API_BASE_PATH) {
-      missingVars.push('BITBUCKET_HOST or BITBUCKET_API_BASE_PATH');
-    }
-
-    return missingVars;
+    return getMissingConfig();
   }
 }
 
@@ -659,7 +714,7 @@ export const bitbucketToolSchemas = {
     name: z.string().optional().describe("Filter projects by name"),
     permission: z.string().optional().describe("Filter projects by permission"),
     start: z.number().optional().describe("Start number for pagination"),
-    limit: z.number().optional().default(25).describe("Number of items to return")
+    limit: z.number().optional().describe("Number of items to return. If not passed, the package default page size is used.")
   },
   getPullRequests: {
     projectKey: z.string().describe("The project key"),
@@ -673,7 +728,7 @@ export const bitbucketToolSchemas = {
     order: z.string().optional().describe("(optional, defaults to NEWEST) the order to return pull requests in, either OLDEST (as in: \"oldest first\") or NEWEST"),
     direction: z.string().optional().describe("(optional, defaults to INCOMING) the direction relative to the specified repository. Either INCOMING or OUTGOING"),
     start: z.number().optional().describe("Start number for the page (inclusive). If not passed, first page is assumed"),
-    limit: z.number().optional().default(25).describe("Number of items to return. If not passed, a page size of 25 is used")
+    limit: z.number().optional().describe("Number of items to return. If not passed, the package default page size is used.")
   },
   getPullRequest: {
     projectKey: z.string().describe("The project key"),
@@ -686,7 +741,7 @@ export const bitbucketToolSchemas = {
   getRepositories: {
     projectKey: z.string().describe("The project key"),
     start: z.number().optional().describe("Start number for pagination"),
-    limit: z.number().optional().default(25).describe("Number of items to return")
+    limit: z.number().optional().describe("Number of items to return. If not passed, the package default page size is used.")
   },
   getRepository: {
     projectKey: z.string().describe("The project key"),
@@ -698,14 +753,15 @@ export const bitbucketToolSchemas = {
     path: z.string().optional().describe("Optional path to filter commits by"),
     since: z.string().optional().describe("The commit ID (exclusively) to retrieve commits after"),
     until: z.string().optional().describe("The commit ID (inclusively) to retrieve commits before"),
-    limit: z.number().optional().default(25).describe("Number of items to return")
+    limit: z.number().optional().describe("Number of items to return. If not passed, the package default page size is used.")
   },
   getPullRequestComments: {
     projectKey: z.string().describe("The project key"),
     repositorySlug: z.string().describe("The repository slug"),
     pullRequestId: z.string().describe("The pull request ID"),
     start: z.number().optional().describe("Start number for pagination"),
-    limit: z.number().optional().default(25).describe("Number of items to return")
+    limit: z.number().optional().describe("Number of items to return. If not passed, the package default page size is used."),
+    output: z.enum(['summary', 'compact', 'full']).optional().describe("Choose between summary lines, compact structured output, or the full API payload. Defaults to compact.")
   },
   getPullRequestChanges: {
     projectKey: z.string().describe("The project key"),
@@ -716,7 +772,8 @@ export const bitbucketToolSchemas = {
     untilId: z.string().optional().describe("The until commit hash to stream changes for a RANGE arbitrary change scope"),
     withComments: z.string().optional().describe("true to apply comment counts in the changes (default), false to stream changes without comment counts"),
     start: z.number().optional().describe("Start number for pagination"),
-    limit: z.number().optional().default(25).describe("Number of items to return")
+    limit: z.number().optional().describe("Number of items to return. If not passed, the package default page size is used."),
+    output: z.enum(['summary', 'compact', 'full']).optional().describe("Choose between summary lines, compact structured output, or the full API payload. Defaults to compact.")
   },
   postPullRequestComment: {
     projectKey: z.string().describe("The project key"),
@@ -727,7 +784,8 @@ export const bitbucketToolSchemas = {
     filePath: z.string().optional().describe("File path for file-specific comments"),
     line: z.number().optional().describe("Line number for line-specific comments"),
     lineType: z.enum(['ADDED', 'REMOVED', 'CONTEXT']).optional().describe("Line type for line comments"),
-    pending: z.boolean().optional().describe("If true, creates a pending (draft) comment not visible to others until the review is submitted via bitbucket_submitPullRequestReview. Only works when filePath is provided — top-level PR comments (no filePath) are always posted live.")
+    pending: z.boolean().optional().describe("If true, creates a pending (draft) comment not visible to others until the review is submitted via bitbucket_submitPullRequestReview. Only works when filePath is provided — top-level PR comments (no filePath) are always posted live."),
+    output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
   },
   getUser: {
     userSlug: z.string().optional().describe("Exact slug of the user to look up (e.g. 'tdepole'). Use this to confirm a known slug or fetch a user's details."),
@@ -760,7 +818,8 @@ export const bitbucketToolSchemas = {
     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')"),
-    reviewers: z.array(z.string()).optional().describe("Optional array of reviewer usernames")
+    reviewers: z.array(z.string()).optional().describe("Optional array of reviewer usernames"),
+    output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
   },
   updatePullRequest: {
     projectKey: z.string().describe("The project key"),
@@ -769,7 +828,8 @@ export const bitbucketToolSchemas = {
     version: z.number().describe("The current version of the pull request (required for optimistic locking)"),
     title: z.string().optional().describe("The new title for the pull request"),
     description: z.string().optional().describe("The new description for the pull request"),
-    reviewers: z.array(z.string()).optional().describe("Optional array of reviewer usernames to set")
+    reviewers: z.array(z.string()).optional().describe("Optional array of reviewer usernames to set"),
+    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"),
@@ -785,10 +845,10 @@ export const bitbucketToolSchemas = {
     closedSince: z.number().optional().describe("Timestamp in milliseconds. If state is not OPEN, return only PRs closed after this date"),
     order: z.enum(['NEWEST', 'OLDEST', 'PARTICIPANT']).optional().default('NEWEST').describe("Order of results: NEWEST (default), OLDEST, or PARTICIPANT"),
     start: z.number().optional().describe("Start number for pagination"),
-    limit: z.number().optional().default(10).describe("Number of items to return (default: 10)")
+    limit: z.number().optional().describe("Number of items to return. If not passed, the package default page size is used.")
   },
   getInboxPullRequests: {
     start: z.number().optional().describe("Start number for the page (inclusive). If not passed, first page is assumed"),
-    limit: z.number().optional().default(25).describe("Number of items to return. If not passed, a page size of 25 is used")
+    limit: z.number().optional().describe("Number of items to return. If not passed, the package default page size is used.")
   }
 };

package/src/config.ts

@@ -0,0 +1,13 @@
+import { getProductRuntimeConfig, validateProductRuntimeConfig } from '@atlassian-dc-mcp/common';
+
+export function getBitbucketRuntimeConfig() {
+  return getProductRuntimeConfig('bitbucket');
+}
+
+export function getDefaultPageSize() {
+  return getBitbucketRuntimeConfig().defaultPageSize;
+}
+
+export function getMissingConfig() {
+  return validateProductRuntimeConfig('bitbucket');
+}

package/src/index.ts

@@ -1,9 +1,8 @@
-import { connectServer, createMcpServer, formatToolResponse } from '@atlassian-dc-mcp/common';
-import dotenv from 'dotenv';
+import { connectServer, createMcpServer, formatToolResponse, initializeRuntimeConfig } from '@atlassian-dc-mcp/common';
 import { BitbucketService, bitbucketToolSchemas } from './bitbucket-service.js';
+import { getBitbucketRuntimeConfig, getDefaultPageSize } from './config.js';
 
-// Load environment variables
-dotenv.config();
+initializeRuntimeConfig();
 
 const missingVars = BitbucketService.validateConfig();
 if (missingVars.length > 0) {
@@ -11,10 +10,12 @@ if (missingVars.length > 0) {
   process.exit(1);
 }
 
+const bitbucketConfig = getBitbucketRuntimeConfig();
 const bitbucketService = new BitbucketService(
-  process.env.BITBUCKET_HOST!,
-  process.env.BITBUCKET_API_TOKEN!,
-  process.env.BITBUCKET_API_BASE_PATH,
+  bitbucketConfig.host,
+  () => getBitbucketRuntimeConfig().token,
+  bitbucketConfig.apiBasePath,
+  getDefaultPageSize,
 );
 
 const server = createMcpServer({
@@ -96,8 +97,8 @@ server.tool(
   "bitbucket_getPR_CommentsAndAction",
   "Get comments for a Bitbucket pull request and other actions, like approvals",
   bitbucketToolSchemas.getPullRequestComments,
-  async ({ projectKey, repositorySlug, pullRequestId, start, limit }) => {
-    const result = await bitbucketService.getPullRequestCommentsAndActions(projectKey, repositorySlug, pullRequestId, start, limit);
+  async ({ projectKey, repositorySlug, pullRequestId, start, limit, output }) => {
+    const result = await bitbucketService.getPullRequestCommentsAndActions(projectKey, repositorySlug, pullRequestId, start, limit, output);
     return formatToolResponse(result);
   }
 );
@@ -106,8 +107,8 @@ server.tool(
   "bitbucket_getPullRequestChanges",
   "Get the changes for a Bitbucket pull request",
   bitbucketToolSchemas.getPullRequestChanges,
-  async ({ projectKey, repositorySlug, pullRequestId, sinceId, changeScope, untilId, withComments, start, limit }) => {
-    const result = await bitbucketService.getPullRequestChanges(projectKey, repositorySlug, pullRequestId, sinceId, changeScope, untilId, withComments, start, limit);
+  async ({ projectKey, repositorySlug, pullRequestId, sinceId, changeScope, untilId, withComments, start, limit, output }) => {
+    const result = await bitbucketService.getPullRequestChanges(projectKey, repositorySlug, pullRequestId, sinceId, changeScope, untilId, withComments, start, limit, output);
     return formatToolResponse(result);
   }
 );
@@ -126,8 +127,8 @@ server.tool(
   "bitbucket_postPullRequestComment",
   "Post a comment to a Bitbucket pull request. Use pending: true to create a draft comment that is only visible to you until you call bitbucket_submitPullRequestReview. NOTE: pending only works when filePath is provided (file-level or inline comments). True top-level PR comments (no filePath) are always posted live and cannot be drafted.",
   bitbucketToolSchemas.postPullRequestComment,
-  async ({ projectKey, repositorySlug, pullRequestId, text, parentId, filePath, line, lineType, pending }) => {
-    const result = await bitbucketService.postPullRequestComment(projectKey, repositorySlug, pullRequestId, text, parentId, filePath, line, lineType, pending);
+  async ({ projectKey, repositorySlug, pullRequestId, text, parentId, filePath, line, lineType, pending, output }) => {
+    const result = await bitbucketService.postPullRequestComment(projectKey, repositorySlug, pullRequestId, text, parentId, filePath, line, lineType, pending, output);
     return formatToolResponse(result);
   }
 );
@@ -157,8 +158,8 @@ 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.",
   bitbucketToolSchemas.createPullRequest,
-  async ({ projectKey, repositorySlug, title, description, fromRefId, toRefId, reviewers }) => {
-    const result = await bitbucketService.createPullRequest(projectKey, repositorySlug, title, description, fromRefId, toRefId, reviewers);
+  async ({ projectKey, repositorySlug, title, description, fromRefId, toRefId, reviewers, output }) => {
+    const result = await bitbucketService.createPullRequest(projectKey, repositorySlug, title, description, fromRefId, toRefId, reviewers, output);
     return formatToolResponse(result);
   }
 );
@@ -167,8 +168,8 @@ server.tool(
   "bitbucket_updatePullRequest",
   "Update the title, description, reviewers, destination branch or draft status of an existing pull request. IMPORTANT: The reviewers parameter replaces ALL existing reviewers. If you want to preserve existing reviewers, first fetch the current PR details (using bitbucket_getPullRequests filtered by ID) and include those reviewers along with any new ones you want to add.",
   bitbucketToolSchemas.updatePullRequest,
-  async ({ projectKey, repositorySlug, pullRequestId, version, title, description, reviewers }) => {
-    const result = await bitbucketService.updatePullRequest(projectKey, repositorySlug, pullRequestId, version, title, description, reviewers);
+  async ({ projectKey, repositorySlug, pullRequestId, version, title, description, reviewers, output }) => {
+    const result = await bitbucketService.updatePullRequest(projectKey, repositorySlug, pullRequestId, version, title, description, reviewers, output);
     return formatToolResponse(result);
   }
 );