mcp-server-bitbucket

Instructions

Args:
    repo_slug: Repository slug
    kind: Type of restriction. Common values:
          - "push" - Restrict who can push
          - "force" - Restrict force push
          - "delete" - Restrict branch deletion
          - "restrict_merges" - Restrict who can merge
          - "require_passing_builds_to_merge" - Require CI to pass
          - "require_approvals_to_merge" - Require PR approvals
          - "require_default_reviewer_approvals_to_merge"
          - "require_no_changes_requested"
          - "require_tasks_to_be_completed"
    pattern: Branch pattern (e.g., "main", "release/*"). Required for glob match.
    branch_match_kind: How to match branches - "glob" (pattern) or "branching_model" (development/production)
    branch_type: Branch type when using branching_model - "development", "production", or specific category
    value: Numeric value for restrictions that need it (e.g., number of required approvals)

Returns:
    Created restriction info with ID

Implementation Reference

• src/server.py:1371-1417 (handler)

  MCP tool handler that creates a branch restriction using the Bitbucket client.

  @mcp.tool()
  @handle_bitbucket_error
  @formatted
  def create_branch_restriction(
      repo_slug: str,
      kind: str,
      pattern: str = "",
      branch_match_kind: str = "glob",
      branch_type: str = "",
      value: int = 0,
  ) -> dict:
      """Create a branch restriction (protection rule).
  
      Args:
          repo_slug: Repository slug
          kind: Type of restriction. Common values:
                - "push" - Restrict who can push
                - "force" - Restrict force push
                - "delete" - Restrict branch deletion
                - "restrict_merges" - Restrict who can merge
                - "require_passing_builds_to_merge" - Require CI to pass
                - "require_approvals_to_merge" - Require PR approvals
                - "require_default_reviewer_approvals_to_merge"
                - "require_no_changes_requested"
                - "require_tasks_to_be_completed"
          pattern: Branch pattern (e.g., "main", "release/*"). Required for glob match.
          branch_match_kind: How to match branches - "glob" (pattern) or "branching_model" (development/production)
          branch_type: Branch type when using branching_model - "development", "production", or specific category
          value: Numeric value for restrictions that need it (e.g., number of required approvals)
  
      Returns:
          Created restriction info with ID
      """
      client = get_client()
      result = client.create_branch_restriction(
          repo_slug,
          kind=kind,
          pattern=pattern,
          branch_match_kind=branch_match_kind,
          branch_type=branch_type if branch_type else None,
          value=value if value else None,
      )
      return {
          "id": result.get("id"),
          "kind": result.get("kind"),
      }

• src/bitbucket_client.py:1378-1433 (helper)

  BitbucketClient helper method that performs the API POST request to create the branch restriction.

  def create_branch_restriction(
      self,
      repo_slug: str,
      kind: str,
      pattern: str = "",
      branch_match_kind: str = "glob",
      branch_type: Optional[str] = None,
      users: Optional[list[dict]] = None,
      groups: Optional[list[dict]] = None,
      value: Optional[int] = None,
  ) -> dict[str, Any]:
      """Create a branch restriction.
  
      Args:
          repo_slug: Repository slug
          kind: Restriction type. Options:
                - require_passing_builds_to_merge
                - require_approvals_to_merge
                - require_default_reviewer_approvals_to_merge
                - require_no_changes_requested
                - require_tasks_to_be_completed
                - require_commits_behind
                - push, force, delete, restrict_merges
          pattern: Branch pattern (e.g., "main", "release/*")
          branch_match_kind: "glob" or "branching_model"
          branch_type: If branch_match_kind is "branching_model":
                       development, production, feature, bugfix, release, hotfix
          users: List of users exempt from restriction
          groups: List of groups exempt from restriction
          value: Number value (e.g., required approvals count)
  
      Returns:
          Created restriction info
      """
      payload: dict[str, Any] = {
          "kind": kind,
          "branch_match_kind": branch_match_kind,
      }
  
      if branch_match_kind == "glob" and pattern:
          payload["pattern"] = pattern
      if branch_match_kind == "branching_model" and branch_type:
          payload["branch_type"] = branch_type
      if users:
          payload["users"] = users
      if groups:
          payload["groups"] = groups
      if value is not None:
          payload["value"] = value
  
      result = self._request(
          "POST",
          self._repo_path(repo_slug, "branch-restrictions"),
          json=payload,
      )
      return self._require_result(result, "create branch restriction", kind)

• src/models.py:600-623 (schema)

  Pydantic model defining the structure of branch restriction data, used for serialization in related tools.

  class BranchRestriction(BaseModel):
      """Branch restriction info."""
  
      id: int
      kind: str
      pattern: str = ""
      branch_match_kind: Optional[str] = None
      branch_type: Optional[str] = None
      value: Optional[int] = None
      users: list[str] = []
      groups: list[str] = []
  
      @classmethod
      def from_api(cls, data: dict) -> "BranchRestriction":
          return cls(
              id=data.get("id", 0),
              kind=data.get("kind", ""),
              pattern=data.get("pattern", ""),
              branch_match_kind=data.get("branch_match_kind"),
              branch_type=data.get("branch_type"),
              value=data.get("value"),
              users=[u.get("display_name", "") for u in data.get("users", [])],
              groups=[g.get("name", "") for g in data.get("groups", [])],
          )