mcp-server-bitbucket

Instructions

Args:
    repo_slug: Repository slug
    state: Filter by state: OPEN, MERGED, DECLINED, SUPERSEDED (default: OPEN)
    limit: Maximum number of results (default: 20, max: 100)

Returns:
    List of PRs with basic info

Implementation Reference

• src/server.py:272-304 (handler)

  The primary MCP tool handler function 'list_pull_requests'. It validates input parameters, calls the Bitbucket client method, formats the response using PullRequestSummary models, and handles errors.

  @mcp.tool()
  @handle_bitbucket_error
  @formatted
  def list_pull_requests(
      repo_slug: str,
      state: str = "OPEN",
      limit: int = 20,
  ) -> dict:
      """List pull requests in a repository.
  
      Args:
          repo_slug: Repository slug
          state: Filter by state: OPEN, MERGED, DECLINED, SUPERSEDED (default: OPEN)
          limit: Maximum number of results (default: 20, max: 100)
  
      Returns:
          List of PRs with basic info
      """
      # Validate state - use enum value or default to OPEN
      try:
          validated_state = PRState(state.upper()).value
      except ValueError:
          validated_state = PRState.OPEN.value
  
      client = get_client()
      prs = client.list_pull_requests(repo_slug, state=validated_state, limit=validate_limit(limit))
      return {
          "pull_requests": [
              PullRequestSummary.from_api(pr, client.extract_pr_url(pr)).model_dump()
              for pr in prs
          ],
      }

• src/bitbucket_client.py:449-471 (helper)

  The BitbucketClient helper method that implements the paginated API request to Bitbucket's pullrequests endpoint.

  def list_pull_requests(
      self,
      repo_slug: str,
      state: str = "OPEN",
      limit: int = 50,
  ) -> list[dict[str, Any]]:
      """List pull requests for a repository.
  
      Args:
          repo_slug: Repository slug
          state: PR state filter (OPEN, MERGED, DECLINED, SUPERSEDED)
          limit: Maximum results to return
  
      Returns:
          List of PR info dicts
      """
      return self._paginated_list(
          self._repo_path(repo_slug, "pullrequests"),
          limit=limit,
          max_page=50,
          state=state,
      )

• src/models.py:91-113 (schema)

  Pydantic model PullRequestSummary used for output schema validation and transformation in the list_pull_requests tool response.

  class PullRequestSummary(BaseModel):
      """PR info for list responses."""
  
      id: int
      title: str
      state: str
      author: Optional[str] = None
      source_branch: Optional[str] = None
      destination_branch: Optional[str] = None
      url: str = ""
  
      @classmethod
      def from_api(cls, data: dict, url: str = "") -> "PullRequestSummary":
          return cls(
              id=data.get("id", 0),
              title=data.get("title", ""),
              state=data.get("state", ""),
              author=(data.get("author") or {}).get("display_name"),
              source_branch=(data.get("source") or {}).get("branch", {}).get("name"),
              destination_branch=(data.get("destination") or {}).get("branch", {}).get("name"),
              url=url,
          )