mcp-server-bitbucket

Instructions

Args:
    limit: Maximum number of results (default: 50)

Returns:
    List of projects with key, name, and description

Implementation Reference

• src/server.py:608-625 (handler)

  MCP tool handler function for 'list_projects'. Registers the tool, handles errors, formats output, calls Bitbucket client, and uses ProjectSummary model for response.

  @mcp.tool()
  @handle_bitbucket_error
  @formatted
  def list_projects(limit: int = 50) -> dict:
      """List projects in the workspace.
  
      Args:
          limit: Maximum number of results (default: 50)
  
      Returns:
          List of projects with key, name, and description
      """
      client = get_client()
      projects = client.list_projects(limit=validate_limit(limit))
      return {
          "projects": [ProjectSummary.from_api(p).model_dump() for p in projects],
      }

• src/bitbucket_client.py:754-770 (helper)

  Core BitbucketClient method implementing the API call to list projects using paginated endpoint.

  def list_projects(
      self,
      limit: int = 50,
  ) -> list[dict[str, Any]]:
      """List projects in workspace.
  
      Args:
          limit: Maximum results to return
  
      Returns:
          List of project info dicts
      """
      return self._paginated_list(
          f"workspaces/{self.workspace}/projects",
          limit=limit,
      )

• src/models.py:397-425 (schema)

  Pydantic model ProjectSummary used in list_projects tool response, with from_api factory and field validators for truncation.

  class ProjectSummary(BaseModel):
      """Project info for list responses."""
  
      key: str
      name: str
      description: str = ""
      private: bool = True
      created: Optional[str] = None
  
      @field_validator("description", mode="before")
      @classmethod
      def truncate_description(cls, v: Any) -> str:
          return (v or "")[:100]
  
      @field_validator("created", mode="before")
      @classmethod
      def truncate_ts(cls, v: Any) -> Optional[str]:
          return truncate_timestamp(v)
  
      @classmethod
      def from_api(cls, data: dict) -> "ProjectSummary":
          return cls(
              key=data.get("key", ""),
              name=data.get("name", ""),
              description=data.get("description"),
              private=data.get("is_private", True),
              created=data.get("created_on"),
          )

• src/server.py:608-608 (registration)

  MCP tool registration decorator for list_projects.

  @mcp.tool()

• src/models.py:427-452 (schema)

  Related Pydantic model ProjectDetail used in get_project tool (companion to list_projects).

  class ProjectDetail(BaseModel):
      """Project info for get responses."""
  
      key: str
      name: str
      description: str = ""
      private: bool = True
      created: Optional[str] = None
      updated: Optional[str] = None
  
      @field_validator("created", "updated", mode="before")
      @classmethod
      def truncate_ts(cls, v: Any) -> Optional[str]:
          return truncate_timestamp(v)
  
      @classmethod
      def from_api(cls, data: dict) -> "ProjectDetail":
          return cls(
              key=data.get("key", ""),
              name=data.get("name", ""),
              description=data.get("description", ""),
              private=data.get("is_private", True),
              created=data.get("created_on"),
              updated=data.get("updated_on"),
          )