mcp-server-bitbucket

Instructions

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 []