mcp-server-bitbucket

Instructions

Args:
    repo_slug: Repository slug
    limit: Maximum number of results (default: 50)

Returns:
    List of branches with commit info

Implementation Reference

• src/server.py:695-712 (handler)

  MCP tool handler function for 'list_branches'. Registers the tool with @mcp.tool(), handles errors and formatting, calls BitbucketClient.list_branches, and returns formatted list using BranchSummary models.

  @mcp.tool()
  @handle_bitbucket_error
  @formatted
  def list_branches(repo_slug: str, limit: int = 50) -> dict:
      """List branches in a repository.
  
      Args:
          repo_slug: Repository slug
          limit: Maximum number of results (default: 50)
  
      Returns:
          List of branches with commit info
      """
      client = get_client()
      branches = client.list_branches(repo_slug, limit=validate_limit(limit))
      return {
          "branches": [BranchSummary.from_api(b).model_dump() for b in branches],
      }

• src/models.py:221-253 (schema)

  Pydantic model BranchSummary used for output schema validation and formatting in the list_branches tool response.

  class BranchSummary(BaseModel):
      """Branch info for list responses."""
  
      name: str
      commit: str
      message: str = ""
      date: Optional[str] = None
  
      @field_validator("commit", mode="before")
      @classmethod
      def truncate_hash(cls, v: Any) -> str:
          return (v or "")[:12]
  
      @field_validator("message", mode="before")
      @classmethod
      def first_line(cls, v: Any) -> str:
          return (v or "").split("\n")[0]
  
      @field_validator("date", mode="before")
      @classmethod
      def truncate_ts(cls, v: Any) -> Optional[str]:
          return truncate_timestamp(v)
  
      @classmethod
      def from_api(cls, data: dict) -> "BranchSummary":
          target = data.get("target") or {}
          return cls(
              name=data.get("name", ""),
              commit=target.get("hash", ""),
              message=target.get("message"),
              date=target.get("date"),
          )

• src/bitbucket_client.py:1249-1266 (helper)

  Core BitbucketClient helper method that performs the API call to list branches using _paginated_list and _repo_path utilities.

  def list_branches(
      self,
      repo_slug: str,
      limit: int = 50,
  ) -> list[dict[str, Any]]:
      """List branches in a repository.
  
      Args:
          repo_slug: Repository slug
          limit: Maximum results to return
  
      Returns:
          List of branch info dicts
      """
      return self._paginated_list(
          self._repo_path(repo_slug, "refs", "branches"),
          limit=limit,
      )