@atlassian-dc-mcp/bitbucket 0.10.0 → 0.10.2

package/src/__tests__/inbox-pr-mapper.test.ts

@@ -0,0 +1,347 @@
+import { simplifyInboxPullRequests, SimplifiedInboxPRResponse } from '../inbox-pr-mapper.js';
+
+describe('simplifyInboxPullRequests', () => {
+  const makePR = (overrides: Record<string, unknown> = {}) => ({
+    id: 101,
+    version: 0,
+    title: 'feat: Add user authentication module',
+    description: 'Implements OAuth2 login flow',
+    state: 'OPEN',
+    open: true,
+    closed: false,
+    draft: false,
+    createdDate: 1700000000000,
+    updatedDate: 1700001000000,
+    locked: false,
+    author: {
+      user: {
+        name: 'jsmith',
+        emailAddress: 'jsmith@example.com',
+        active: true,
+        displayName: 'John Smith',
+        id: 1001,
+        slug: 'jsmith',
+        type: 'NORMAL',
+        links: { self: [{ href: 'https://bitbucket.example.com/users/jsmith' }] },
+      },
+      role: 'AUTHOR',
+      approved: false,
+      status: 'UNAPPROVED',
+    },
+    fromRef: {
+      id: 'refs/heads/feat/user-auth',
+      displayId: 'feat/user-auth',
+      latestCommit: 'abc123def456abc123def456abc123def456abc1',
+      type: 'BRANCH',
+      repository: {
+        slug: 'myproject-api',
+        id: 100,
+        name: 'myproject-api',
+        hierarchyId: 'aabb11cc22dd33',
+        scmId: 'git',
+        state: 'AVAILABLE',
+        statusMessage: 'Available',
+        forkable: true,
+        project: {
+          key: 'PROJ',
+          id: 10,
+          name: 'Project Alpha',
+          public: false,
+          type: 'NORMAL',
+          links: { self: [{ href: 'https://bitbucket.example.com/projects/PROJ' }] },
+        },
+        public: false,
+        archived: false,
+        links: {
+          clone: [
+            { href: 'ssh://git@bitbucket.example.com/proj/myproject-api.git', name: 'ssh' },
+            { href: 'https://bitbucket.example.com/scm/proj/myproject-api.git', name: 'http' },
+          ],
+          self: [{ href: 'https://bitbucket.example.com/projects/PROJ/repos/myproject-api/browse' }],
+        },
+      },
+    },
+    toRef: {
+      id: 'refs/heads/main',
+      displayId: 'main',
+      latestCommit: 'def456abc123def456abc123def456abc123def4',
+      type: 'BRANCH',
+      repository: {
+        slug: 'myproject-api',
+        id: 100,
+        name: 'myproject-api',
+        project: { key: 'PROJ', id: 10, name: 'Project Alpha' },
+      },
+    },
+    reviewers: [
+      {
+        user: { name: 'adoe', displayName: 'Alice Doe', emailAddress: 'adoe@example.com', id: 1002 },
+        role: 'REVIEWER',
+        approved: false,
+        status: 'UNAPPROVED',
+      },
+      {
+        user: { name: 'bjones', displayName: 'Bob Jones', emailAddress: 'bjones@example.com', id: 1003 },
+        lastReviewedCommit: 'abc123def456abc123def456abc123def456abc1',
+        role: 'REVIEWER',
+        approved: true,
+        status: 'APPROVED',
+      },
+      {
+        user: { name: 'clee', displayName: 'Carol Lee', emailAddress: 'clee@example.com', id: 1004 },
+        role: 'REVIEWER',
+        approved: false,
+        status: 'UNAPPROVED',
+      },
+    ],
+    participants: [],
+    properties: {
+      mergeResult: { outcome: 'CLEAN', current: true },
+      resolvedTaskCount: 0,
+      commentCount: 3,
+      openTaskCount: 1,
+    },
+    links: {
+      self: [{ href: 'https://bitbucket.example.com/projects/PROJ/repos/myproject-api/pull-requests/101' }],
+    },
+    ...overrides,
+  });
+
+  const makeResponse = (prs: unknown[] = [makePR()], overrides: Record<string, unknown> = {}) => ({
+    values: prs,
+    size: prs.length,
+    isLastPage: true,
+    start: 0,
+    limit: 25,
+    ...overrides,
+  });
+
+  it('should simplify a valid inbox response with real API structure', () => {
+    const response = makeResponse();
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests).toHaveLength(1);
+    expect(result.pullRequests[0]).toEqual({
+      id: 101,
+      title: 'feat: Add user authentication module',
+      description: 'Implements OAuth2 login flow',
+      state: 'OPEN',
+      draft: false,
+      createdDate: 1700000000000,
+      updatedDate: 1700001000000,
+      link: 'https://bitbucket.example.com/projects/PROJ/repos/myproject-api/pull-requests/101',
+      author: { name: 'jsmith', displayName: 'John Smith' },
+      fromRef: 'feat/user-auth',
+      toRef: 'main',
+      repository: { slug: 'myproject-api', projectKey: 'PROJ' },
+      reviewers: [
+        { name: 'adoe', approved: false, status: 'UNAPPROVED' },
+        { name: 'bjones', approved: true, status: 'APPROVED' },
+        { name: 'clee', approved: false, status: 'UNAPPROVED' },
+      ],
+      commentCount: 3,
+      openTaskCount: 1,
+    });
+    expect(result.summary).toEqual({
+      totalCount: 1,
+      byRepository: { 'PROJ/myproject-api': 1 },
+    });
+    expect(result.isLastPage).toBe(true);
+  });
+
+  it('should extract the PR link from links.self[0].href', () => {
+    const response = makeResponse();
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests[0].link).toBe(
+      'https://bitbucket.example.com/projects/PROJ/repos/myproject-api/pull-requests/101'
+    );
+  });
+
+  it('should omit link when links.self is not present', () => {
+    const pr = makePR({ links: undefined });
+    const response = makeResponse([pr]);
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests[0].link).toBeUndefined();
+  });
+
+  it('should include commentCount and openTaskCount from properties', () => {
+    const pr = makePR({
+      properties: { commentCount: 5, openTaskCount: 2, resolvedTaskCount: 1 },
+    });
+    const response = makeResponse([pr]);
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests[0].commentCount).toBe(5);
+    expect(result.pullRequests[0].openTaskCount).toBe(2);
+  });
+
+  it('should default commentCount and openTaskCount to 0 when properties missing', () => {
+    const pr = makePR({ properties: undefined });
+    const response = makeResponse([pr]);
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests[0].commentCount).toBe(0);
+    expect(result.pullRequests[0].openTaskCount).toBe(0);
+  });
+
+  it('should include description when present', () => {
+    const response = makeResponse();
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests[0].description).toBe('Implements OAuth2 login flow');
+  });
+
+  it('should omit description when not present', () => {
+    const pr = makePR({ description: undefined });
+    const response = makeResponse([pr]);
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests[0].description).toBeUndefined();
+  });
+
+  it('should include draft status', () => {
+    const pr = makePR({ draft: true });
+    const response = makeResponse([pr]);
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests[0].draft).toBe(true);
+  });
+
+  it('should default draft to false when not present', () => {
+    const pr = makePR({ draft: undefined });
+    const response = makeResponse([pr]);
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests[0].draft).toBe(false);
+  });
+
+  it('should handle multiple PRs from different repositories', () => {
+    const pr1 = makePR();
+    const pr2 = makePR({
+      id: 200,
+      title: 'fix: Resolve cache invalidation bug',
+      fromRef: {
+        id: 'refs/heads/fix/cache-bug',
+        displayId: 'fix/cache-bug',
+        repository: { slug: 'frontend-app', project: { key: 'WEB' } },
+      },
+      toRef: {
+        id: 'refs/heads/main',
+        displayId: 'main',
+        repository: { slug: 'frontend-app', project: { key: 'WEB' } },
+      },
+      links: {
+        self: [{ href: 'https://bitbucket.example.com/projects/WEB/repos/frontend-app/pull-requests/200' }],
+      },
+    });
+    const pr3 = makePR({ id: 102, title: 'chore: Update dependencies' });
+
+    const response = makeResponse([pr1, pr2, pr3]);
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests).toHaveLength(3);
+    expect(result.summary.totalCount).toBe(3);
+    expect(result.summary.byRepository).toEqual({
+      'PROJ/myproject-api': 2,
+      'WEB/frontend-app': 1,
+    });
+  });
+
+  it('should handle empty values array', () => {
+    const response = makeResponse([]);
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests).toHaveLength(0);
+    expect(result.summary.totalCount).toBe(0);
+    expect(result.summary.byRepository).toEqual({});
+    expect(result.isLastPage).toBe(true);
+  });
+
+  it('should include nextPageStart when not the last page', () => {
+    const response = makeResponse([makePR()], {
+      isLastPage: false,
+      nextPageStart: 25,
+    });
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.isLastPage).toBe(false);
+    expect(result.nextPageStart).toBe(25);
+  });
+
+  it('should not include nextPageStart when it is the last page', () => {
+    const response = makeResponse([makePR()]);
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.isLastPage).toBe(true);
+    expect(result.nextPageStart).toBeUndefined();
+  });
+
+  it('should handle PR without author', () => {
+    const pr = makePR({ author: undefined });
+    const response = makeResponse([pr]);
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests[0].author).toBeUndefined();
+  });
+
+  it('should handle PR without reviewers', () => {
+    const pr = makePR({ reviewers: undefined });
+    const response = makeResponse([pr]);
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests[0].reviewers).toEqual([]);
+  });
+
+  it('should return original response for invalid input', () => {
+    const invalidResponse = { foo: 'bar' };
+    const result = simplifyInboxPullRequests(invalidResponse);
+
+    expect(result).toBe(invalidResponse);
+  });
+
+  it('should return original response for null input', () => {
+    const result = simplifyInboxPullRequests(null);
+    expect(result).toBeNull();
+  });
+
+  it('should return original response when values contain no valid PRs', () => {
+    const response = makeResponse([{ invalid: true }, { alsoInvalid: true }]);
+    const result = simplifyInboxPullRequests(response);
+
+    expect(result).toBe(response);
+  });
+
+  it('should use ref id as fallback when displayId is missing', () => {
+    const pr = makePR({
+      fromRef: {
+        id: 'refs/heads/feat/user-auth',
+        repository: { slug: 'myproject-api', project: { key: 'PROJ' } },
+      },
+      toRef: {
+        id: 'refs/heads/main',
+        repository: { slug: 'myproject-api', project: { key: 'PROJ' } },
+      },
+    });
+    const response = makeResponse([pr]);
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+
+    expect(result.pullRequests[0].fromRef).toBe('refs/heads/feat/user-auth');
+    expect(result.pullRequests[0].toRef).toBe('refs/heads/main');
+  });
+
+  it('should strip extra fields from the real API response', () => {
+    const response = makeResponse();
+    const result = simplifyInboxPullRequests(response) as SimplifiedInboxPRResponse;
+    const pr = result.pullRequests[0];
+
+    expect(pr).not.toHaveProperty('version');
+    expect(pr).not.toHaveProperty('open');
+    expect(pr).not.toHaveProperty('closed');
+    expect(pr).not.toHaveProperty('locked');
+    expect(pr).not.toHaveProperty('participants');
+    expect(pr).not.toHaveProperty('properties');
+    expect(pr).not.toHaveProperty('links');
+  });
+});

package/src/bitbucket-service.ts

@@ -4,6 +4,7 @@ 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';
 
 export class BitbucketService {
   constructor(host: string, token: string, fullBaseUrl?: string) {
@@ -496,6 +497,38 @@ 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)
+   * @returns Promise with inbox pull requests data
+   */
+  async getInboxPullRequests(start?: number, limit: number = 25) {
+    const result = await handleApiOperation(
+      () => __request(OpenAPI, {
+        method: 'GET',
+        url: '/api/latest/inbox/pull-requests',
+        query: {
+          'start': start,
+          'limit': limit,
+        },
+        errors: {
+          401: 'The currently authenticated user is not permitted to access the inbox.',
+        },
+      }),
+      'Error fetching inbox pull requests'
+    );
+
+    if (result.success && result.data) {
+      return {
+        success: true,
+        data: simplifyInboxPullRequests(result.data),
+      };
+    }
+
+    return result;
+  }
+
   static validateConfig(): string[] {
     // Check for BITBUCKET_HOST or its alternative BITBUCKET_API_BASE_PATH
     const requiredEnvVars = ['BITBUCKET_API_TOKEN'] as const;
@@ -621,5 +654,9 @@ export const bitbucketToolSchemas = {
     targetRefId: z.string().describe("The ID of the target ref (e.g., 'refs/heads/main')"),
     sourceRepoId: z.string().optional().describe("Optional ID of the repository in which the source ref exists"),
     targetRepoId: z.string().optional().describe("Optional ID of the repository in which the target ref exists")
+  },
+  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")
   }
 };

package/src/inbox-pr-mapper.ts

@@ -0,0 +1,183 @@
+interface InboxPRUser {
+  name: string;
+  emailAddress?: string;
+  displayName?: string;
+}
+
+interface InboxPRRef {
+  id: string;
+  displayId: string;
+  latestCommit?: string;
+  repository?: {
+    slug: string;
+    project?: {
+      key: string;
+    };
+  };
+}
+
+interface InboxPRReviewer {
+  user: InboxPRUser;
+  approved: boolean;
+  status: string;
+}
+
+interface InboxPullRequest {
+  id: number;
+  title: string;
+  description?: string;
+  state: string;
+  draft?: boolean;
+  createdDate: number;
+  updatedDate: number;
+  author?: {
+    user: InboxPRUser;
+  };
+  fromRef: InboxPRRef;
+  toRef: InboxPRRef;
+  reviewers?: InboxPRReviewer[];
+  properties?: {
+    commentCount?: number;
+    openTaskCount?: number;
+  };
+  links?: {
+    self?: { href: string }[];
+  };
+}
+
+interface InboxPRResponse {
+  values: InboxPullRequest[];
+  size: number;
+  isLastPage: boolean;
+  start: number;
+  limit: number;
+  nextPageStart?: number;
+}
+
+// Simplified interfaces
+interface SimplifiedInboxPR {
+  id: number;
+  title: string;
+  description?: string;
+  state: string;
+  draft: boolean;
+  createdDate: number;
+  updatedDate: number;
+  link?: string;
+  author?: {
+    name: string;
+    displayName?: string;
+  };
+  fromRef: string;
+  toRef: string;
+  repository: {
+    slug: string;
+    projectKey: string;
+  };
+  reviewers: {
+    name: string;
+    approved: boolean;
+    status: string;
+  }[];
+  commentCount: number;
+  openTaskCount: number;
+}
+
+export interface SimplifiedInboxPRResponse {
+  pullRequests: SimplifiedInboxPR[];
+  summary: {
+    totalCount: number;
+    byRepository: Record<string, number>;
+  };
+  isLastPage: boolean;
+  nextPageStart?: number;
+}
+
+// Type guards
+function isInboxPRResponse(obj: unknown): obj is InboxPRResponse {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    Array.isArray((obj as InboxPRResponse).values) &&
+    typeof (obj as InboxPRResponse).isLastPage === 'boolean'
+  );
+}
+
+function isInboxPullRequest(obj: unknown): obj is InboxPullRequest {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    typeof (obj as InboxPullRequest).id === 'number' &&
+    typeof (obj as InboxPullRequest).title === 'string' &&
+    typeof (obj as InboxPullRequest).state === 'string'
+  );
+}
+
+function simplifyInboxPR(pr: InboxPullRequest): SimplifiedInboxPR {
+  const repo = pr.toRef?.repository ?? pr.fromRef?.repository;
+  const link = pr.links?.self?.[0]?.href;
+
+  return {
+    id: pr.id,
+    title: pr.title,
+    ...(pr.description !== undefined && { description: pr.description }),
+    state: pr.state,
+    draft: pr.draft ?? false,
+    createdDate: pr.createdDate,
+    updatedDate: pr.updatedDate,
+    ...(link && { link }),
+    ...(pr.author?.user && {
+      author: {
+        name: pr.author.user.name,
+        ...(pr.author.user.displayName && { displayName: pr.author.user.displayName }),
+      },
+    }),
+    fromRef: pr.fromRef?.displayId ?? pr.fromRef?.id,
+    toRef: pr.toRef?.displayId ?? pr.toRef?.id,
+    repository: {
+      slug: repo?.slug ?? 'unknown',
+      projectKey: repo?.project?.key ?? 'unknown',
+    },
+    reviewers: (pr.reviewers ?? []).map(r => ({
+      name: r.user.name,
+      approved: r.approved,
+      status: r.status,
+    })),
+    commentCount: pr.properties?.commentCount ?? 0,
+    openTaskCount: pr.properties?.openTaskCount ?? 0,
+  };
+}
+
+export function simplifyInboxPullRequests(response: unknown): SimplifiedInboxPRResponse | unknown {
+  if (!isInboxPRResponse(response)) {
+    return response;
+  }
+
+  const pullRequests: SimplifiedInboxPR[] = [];
+
+  for (const pr of response.values) {
+    if (isInboxPullRequest(pr)) {
+      pullRequests.push(simplifyInboxPR(pr));
+    }
+  }
+
+  if (pullRequests.length === 0 && response.values.length > 0) {
+    return response;
+  }
+
+  const byRepository: Record<string, number> = {};
+  for (const pr of pullRequests) {
+    const repoKey = `${pr.repository.projectKey}/${pr.repository.slug}`;
+    byRepository[repoKey] = (byRepository[repoKey] ?? 0) + 1;
+  }
+
+  return {
+    pullRequests,
+    summary: {
+      totalCount: pullRequests.length,
+      byRepository,
+    },
+    isLastPage: response.isLastPage,
+    ...(response.nextPageStart !== undefined && { nextPageStart: response.nextPageStart }),
+  };
+}

package/src/index.ts

@@ -163,4 +163,14 @@ server.tool(
   }
 );
 
+server.tool(
+  "bitbucket_getInboxPullRequests",
+  "Get pull requests from the authenticated user's inbox that need their review. Returns PRs across all repositories where the user is a reviewer.",
+  bitbucketToolSchemas.getInboxPullRequests,
+  async ({ start, limit }) => {
+    const result = await bitbucketService.getInboxPullRequests(start, limit);
+    return formatToolResponse(result);
+  }
+);
+
 await connectServer(server);