mcp-server-bitbucket

Instructions

Use this to report CI/CD status from external systems.

Args:
    repo_slug: Repository slug
    commit: Commit hash
    state: Status state - one of: SUCCESSFUL, FAILED, INPROGRESS, STOPPED
    key: Unique identifier for this status (e.g., "my-ci-system")
    url: URL to the build details (optional)
    name: Display name for the status (optional)
    description: Status description (optional)

Returns:
    Created status info

Implementation Reference

• src/server.py:858-908 (handler)

  MCP tool handler function registered with @mcp.tool(). Validates the state parameter using CommitStatusState enum and delegates to BitbucketClient.create_commit_status. Returns a formatted response with status details.

  @mcp.tool()
  @handle_bitbucket_error
  @formatted
  def create_commit_status(
      repo_slug: str,
      commit: str,
      state: str,
      key: str,
      url: Optional[str] = None,
      name: Optional[str] = None,
      description: Optional[str] = None,
  ) -> dict:
      """Create a build status for a commit.
  
      Use this to report CI/CD status from external systems.
  
      Args:
          repo_slug: Repository slug
          commit: Commit hash
          state: Status state - one of: SUCCESSFUL, FAILED, INPROGRESS, STOPPED
          key: Unique identifier for this status (e.g., "my-ci-system")
          url: URL to the build details (optional)
          name: Display name for the status (optional)
          description: Status description (optional)
  
      Returns:
          Created status info
      """
      # Validate state - must be a valid CommitStatusState
      try:
          validated_state = CommitStatusState(state.upper()).value
      except ValueError:
          return {"success": False, "error": f"Invalid state '{state}'. Must be one of: SUCCESSFUL, FAILED, INPROGRESS, STOPPED"}
  
      client = get_client()
      result = client.create_commit_status(
          repo_slug=repo_slug,
          commit=commit,
          state=validated_state,
          key=key,
          url=url,
          name=name,
          description=description,
      )
      return {
          "key": result.get("key"),
          "state": result.get("state"),
          "name": result.get("name"),
          "url": result.get("url"),
      }

• src/bitbucket_client.py:909-949 (helper)

  BitbucketClient helper method that makes the actual API POST request to create a commit status at /repositories/{workspace}/{repo_slug}/commit/{commit}/statuses/build. Handles payload construction, API call with error handling/retry, and result validation.

  def create_commit_status(
      self,
      repo_slug: str,
      commit: str,
      state: str,
      key: str,
      url: Optional[str] = None,
      name: Optional[str] = None,
      description: Optional[str] = None,
  ) -> dict[str, Any]:
      """Create a build status for a commit.
  
      Args:
          repo_slug: Repository slug
          commit: Commit hash
          state: Status state (SUCCESSFUL, FAILED, INPROGRESS, STOPPED)
          key: Unique identifier for this status
          url: URL to the build (optional)
          name: Display name (optional)
          description: Status description (optional)
  
      Returns:
          Created status info
      """
      payload = {
          "state": state,
          "key": key,
      }
      if url:
          payload["url"] = url
      if name:
          payload["name"] = name
      if description:
          payload["description"] = description
  
      result = self._request(
          "POST",
          self._repo_path(repo_slug, "commit", commit, "statuses", "build"),
          json=payload,
      )
      return self._require_result(result, "create status for commit", commit)

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

  The @mcp.tool() decorator registers this function as an MCP tool, automatically generating input/output schemas from type hints and docstring.

  @mcp.tool()