Bitbucket MCP Server

Instructions

Implementation Reference

• src/tools/pull-requests/listPullRequests.ts:28-92 (handler)

  The handler function that implements the core logic of the 'list_pull_requests' tool. It uses the provided axios instance to query the Bitbucket API for pull requests in the specified repository, optionally filtered by state, formats the results as a markdown list, and returns structured content or an error message.

  export async function listPullRequests(
    axiosInstance: AxiosInstance,
    config: Config,
    args: any
  ): Promise<{ content: Array<{ type: string; text: string }> }> {
    try {
      const { repository_name, state } = args;
  
      if (!repository_name) {
        throw new Error('Repository name is required');
      }
  
      console.error(`Fetching pull requests for repository: ${repository_name}`);
  
      const response = await axiosInstance.get<
        BitbucketPaginatedResponse<PullRequest>
      >(
        `/repositories/${config.BITBUCKET_WORKSPACE}/${repository_name}/pullrequests`,
        {
          params: {
            state: state,
          },
        }
      );
  
      const pullRequests = response.data.values;
      const summary = `Found ${
        pullRequests.length
      } pull requests in repository "${repository_name}" ${
        state ? `with state ${state}` : ''
      }`;
  
      const prList = pullRequests
        .map(
          pr => `**PR #${pr.id}: ${pr.title}**
  - State: ${pr.state}
  - Author: ${pr.author.display_name}
  - Source: ${pr.source.branch.name}
  - Destination: ${pr.destination.branch.name}
  - URL: ${pr.links.html.href}`
        )
        .join('\n\n');
  
      return {
        content: [
          {
            type: 'text',
            text: `${summary}\n\n${prList}`,
          },
        ],
      };
    } catch (error) {
      console.error('Error fetching pull requests:', error);
      return {
        content: [
          {
            type: 'text',
            text: `Error fetching pull requests: ${
              error instanceof Error ? error.message : 'Unknown error'
            }`,
          },
        ],
      };
    }
  } 

• src/tools/pull-requests/listPullRequests.ts:8-26 (schema)

  The tool schema definition including name, description, and input schema for validation (requires repository_name, optional state).

  export const listPullRequestsTool = {
    name: 'list_pull_requests',
    description: 'List all pull requests in a repository.',
    inputSchema: {
      type: 'object',
      properties: {
        repository_name: {
          type: 'string',
          description: 'Name of the repository (repo slug)',
        },
        state: {
          type: 'string',
          description: 'The state of the pull request.',
          enum: ['OPEN', 'MERGED', 'DECLINED'],
        },
      },
      required: ['repository_name'],
    },
  };

• src/index.ts:111-135 (registration)

  Registration of the listPullRequestsTool schema in the ListToolsRequestHandler, making the tool discoverable by MCP clients.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      // Repositories
      listRepositoriesTool,
      getRepositoryDetailsTool,
      // Commits
      listCommitsTool,
      getCommitTool,
      // Branching Model
      updateRepositoryBranchingModelSettingsTool,
      updateProjectBranchingModelSettingsTool,
      listBranchRestrictionsTool,
      getBranchRestrictionTool,
      // Projects
      getProjectTool,
      listDefaultReviewersTool,
      // Pull Requests
      listPullRequestsTool,
      getPullRequestTool,
      createPullRequestTool,
      updatePullRequestTool,
      // Workspaces
      listWorkspacesTool,
    ],
  }));

• src/index.ts:142-173 (registration)

  Registration of the handler mapping for 'list_pull_requests' to listPullRequests function in the CallToolRequestHandler dispatch logic.

  const handlers: Record<
    string,
    (
      axiosInstance: AxiosInstance,
      config: Config,
      args: any
    ) => Promise<{ content: Array<{ type: string; text: string }> }>
  > = {
    // Repositories
    list_repositories: listRepositories,
    get_repository_details: getRepositoryDetails,
    // Commits
    list_commits: listCommits,
    get_commit: getCommit,
    // Branching Model
    update_repository_branching_model_settings:
      updateRepositoryBranchingModelSettings,
    update_project_branching_model_settings:
      updateProjectBranchingModelSettings,
    list_branch_restrictions: listBranchRestrictions,
    get_branch_restriction: getBranchRestriction,
    // Projects
    get_project: getProject,
    list_default_reviewers: listDefaultReviewers,
    // Pull Requests
    list_pull_requests: listPullRequests,
    get_pull_request: getPullRequest,
    create_pull_request: createPullRequest,
    update_pull_request: updatePullRequest,
    // Workspaces
    list_workspaces: listWorkspaces,
  };

• src/index.ts:53-56 (registration)

  Import statement that brings the handler and tool schema into the main server file for registration.

  import {
    listPullRequests,
    listPullRequestsTool,
  } from './tools/pull-requests/listPullRequests.js';