mcp-server-bitbucket

Instructions

Args:
    project_key: Filter by project key (optional)
    search: Simple search term for repository name (optional)
            Uses fuzzy matching: search="anzsic" finds "anzsic_classifier"
    query: Advanced Bitbucket query syntax (optional)
           Examples:
           - name ~ "api" (partial name match)
           - description ~ "classifier" (search description)
           - is_private = false (public repos only)
           - name ~ "test" AND is_private = true
    limit: Maximum number of results (default: 50, max: 100)

Returns:
    List of repositories with basic info

Implementation Reference

• src/server.py:160-205 (handler)

  MCP tool handler for list_repositories: validates input, calls BitbucketClient.list_repositories, formats output using RepositorySummary models.

  @mcp.tool()
  @handle_bitbucket_error
  @formatted
  def list_repositories(
      project_key: Optional[str] = None,
      search: Optional[str] = None,
      query: Optional[str] = None,
      limit: int = 50,
  ) -> dict:
      """List and search repositories in the workspace.
  
      Args:
          project_key: Filter by project key (optional)
          search: Simple search term for repository name (optional)
                  Uses fuzzy matching: search="anzsic" finds "anzsic_classifier"
          query: Advanced Bitbucket query syntax (optional)
                 Examples:
                 - name ~ "api" (partial name match)
                 - description ~ "classifier" (search description)
                 - is_private = false (public repos only)
                 - name ~ "test" AND is_private = true
          limit: Maximum number of results (default: 50, max: 100)
  
      Returns:
          List of repositories with basic info
      """
      client = get_client()
  
      # Convert simple search to query syntax
      # Sanitize search term to prevent BQL injection
      effective_query = query
      if search and not query:
          safe_search = sanitize_search_term(search)
          effective_query = f'name ~ "{safe_search}"'
  
      validated_limit = validate_limit(limit)
  
      repos = client.list_repositories(
          project_key=project_key,
          query=effective_query,
          limit=validated_limit,
      )
      return {
          "repositories": [RepositorySummary.from_api(r).model_dump() for r in repos],
      }

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

  Tool registration via FastMCP @mcp.tool() decorator.

  @mcp.tool()

• src/models.py:30-53 (schema)

  Pydantic model used for output schema/formatting of repository summaries in list_repositories response.

  class RepositorySummary(BaseModel):
      """Repository info for list responses."""
  
      name: str
      full_name: str
      description: str = ""
      private: bool = True
      project: Optional[str] = None
  
      @field_validator("description", mode="before")
      @classmethod
      def truncate_description(cls, v: Any) -> str:
          return (v or "")[:100]
  
      @classmethod
      def from_api(cls, data: dict) -> "RepositorySummary":
          return cls(
              name=data.get("name", ""),
              full_name=data.get("full_name", ""),
              description=data.get("description"),
              private=data.get("is_private", True),
              project=(data.get("project") or {}).get("key"),
          )

• src/bitbucket_client.py:342-380 (helper)

  Core BitbucketClient method implementing the API call to list repositories, called by the MCP handler.

  def list_repositories(
      self,
      project_key: Optional[str] = None,
      query: Optional[str] = None,
      limit: int = 50,
  ) -> list[dict[str, Any]]:
      """List repositories in workspace.
  
      Args:
          project_key: Filter by project (optional)
          query: Search query using Bitbucket query syntax (optional)
                 Examples:
                 - name ~ "anzsic" (partial name match)
                 - name = "exact-name" (exact name match)
                 - description ~ "api" (search in description)
                 - is_private = true (filter by visibility)
          limit: Maximum results to return
  
      Returns:
          List of repository info dicts
      """
      params = {"pagelen": min(limit, 100)}
  
      # Build query string
      q_parts = []
      if project_key:
          q_parts.append(f'project.key="{project_key}"')
      if query:
          q_parts.append(query)
  
      if q_parts:
          params["q"] = " AND ".join(q_parts)
  
      result = self._request(
          "GET",
          f"repositories/{self.workspace}",
          params=params,
      )
      return result.get("values", []) if result else []