retrieve_label

Instructions

Implementation Reference

• plane_mcp/tools/labels.py:81-94 (handler)

  Handler function that executes the 'retrieve_label' tool logic. Takes project_id and label_id, initializes a PlaneClient, and calls client.labels.retrieve() to fetch the label from the Plane API.

  @mcp.tool()
  def retrieve_label(project_id: str, label_id: str) -> Label:
      """
      Retrieve a label by ID.
  
      Args:
          project_id: UUID of the project
          label_id: UUID of the label
  
      Returns:
          Label object
      """
      client, workspace_slug = get_plane_client_context()
      return client.labels.retrieve(workspace_slug=workspace_slug, project_id=project_id, label_id=label_id)

• plane_mcp/tools/labels.py:16-155 (registration)

  Registration function that registers all label tools (including 'retrieve_label') with the FastMCP server using the @mcp.tool() decorator.

  def register_label_tools(mcp: FastMCP) -> None:
      """Register all label-related tools with the MCP server."""
  
      @mcp.tool()
      def list_labels(
          project_id: str,
          params: dict[str, Any] | None = None,
      ) -> list[Label]:
          """
          List all labels in a project.
  
          Args:
              project_id: UUID of the project
              params: Optional query parameters as a dictionary
  
          Returns:
              List of Label objects
          """
          client, workspace_slug = get_plane_client_context()
          response: PaginatedLabelResponse = client.labels.list(
              workspace_slug=workspace_slug, project_id=project_id, params=params
          )
          return response.results
  
      @mcp.tool()
      def create_label(
          project_id: str,
          name: str,
          color: str | None = None,
          description: str | None = None,
          parent: str | None = None,
          sort_order: float | None = None,
          external_source: str | None = None,
          external_id: str | None = None,
      ) -> Label:
          """
          Create a new label.
  
          Args:
              project_id: UUID of the project
              name: Label name
              color: Label color (hex color code)
              description: Label description
              parent: UUID of the parent label (for nested labels)
              sort_order: Sort order for the label
              external_source: External system source name
              external_id: External system identifier
  
          Returns:
              Created Label object
          """
          client, workspace_slug = get_plane_client_context()
  
          data = CreateLabel(
              name=name,
              color=color,
              description=description,
              parent=parent,
              sort_order=sort_order,
              external_source=external_source,
              external_id=external_id,
          )
  
          return client.labels.create(workspace_slug=workspace_slug, project_id=project_id, data=data)
  
      @mcp.tool()
      def retrieve_label(project_id: str, label_id: str) -> Label:
          """
          Retrieve a label by ID.
  
          Args:
              project_id: UUID of the project
              label_id: UUID of the label
  
          Returns:
              Label object
          """
          client, workspace_slug = get_plane_client_context()
          return client.labels.retrieve(workspace_slug=workspace_slug, project_id=project_id, label_id=label_id)
  
      @mcp.tool()
      def update_label(
          project_id: str,
          label_id: str,
          name: str | None = None,
          color: str | None = None,
          description: str | None = None,
          parent: str | None = None,
          sort_order: float | None = None,
          external_source: str | None = None,
          external_id: str | None = None,
      ) -> Label:
          """
          Update a label by ID.
  
          Args:
              project_id: UUID of the project
              label_id: UUID of the label
              name: Label name
              color: Label color (hex color code)
              description: Label description
              parent: UUID of the parent label (for nested labels)
              sort_order: Sort order for the label
              external_source: External system source name
              external_id: External system identifier
  
          Returns:
              Updated Label object
          """
          client, workspace_slug = get_plane_client_context()
  
          data = UpdateLabel(
              name=name,
              color=color,
              description=description,
              parent=parent,
              sort_order=sort_order,
              external_source=external_source,
              external_id=external_id,
          )
  
          return client.labels.update(
              workspace_slug=workspace_slug,
              project_id=project_id,
              label_id=label_id,
              data=data,
          )
  
      @mcp.tool()
      def delete_label(project_id: str, label_id: str) -> None:
          """
          Delete a label by ID.
  
          Args:
              project_id: UUID of the project
              label_id: UUID of the label
          """
          client, workspace_slug = get_plane_client_context()
          client.labels.delete(workspace_slug=workspace_slug, project_id=project_id, label_id=label_id)

• plane_mcp/tools/__init__.py:27-48 (registration)

  Central registration function that calls register_label_tools(mcp) to register the 'retrieve_label' tool along with all other tools.

  def register_tools(mcp: FastMCP) -> None:
      """Register all tools with the MCP server."""
      register_project_tools(mcp)
      register_work_item_tools(mcp)
      register_work_item_activity_tools(mcp)
      register_work_item_comment_tools(mcp)
      register_work_item_link_tools(mcp)
      register_work_item_relation_tools(mcp)
      register_work_log_tools(mcp)
      register_cycle_tools(mcp)
      register_user_tools(mcp)
      register_module_tools(mcp)
      register_initiative_tools(mcp)
      register_intake_tools(mcp)
      register_label_tools(mcp)
      register_page_tools(mcp)
      register_work_item_property_tools(mcp)
      register_work_item_type_tools(mcp)
      register_state_tools(mcp)
      register_workspace_tools(mcp)
      register_epic_tools(mcp)
      register_milestone_tools(mcp)

• plane_mcp/client.py:21-74 (helper)

  Helper function that initializes and returns a PlaneClient instance with workspace context, used by the retrieve_label handler to make API calls.

  def get_plane_client_context() -> PlaneClientContext:
      """
      Initialize and return a PlaneClient instance with workspace context.
  
      Authentication is handled by the PlaneOAuthProvider, which supports:
      1. Environment variables (PLANE_API_KEY + PLANE_WORKSPACE_SLUG)
      2. HTTP headers (x-api-key + x-workspace-slug)
      3. OAuth access token
  
      Environment variables:
      - PLANE_INTERNAL_BASE_URL: Internal URL for Plane API (preferred for server-to-server calls)
      - PLANE_BASE_URL: Base URL for Plane API (fallback, default: https://api.plane.so)
  
      Returns:
          PlaneClientContext containing configured PlaneClient instance and workspace slug
  
      Raises:
          ConfigurationError: If access token is not available or workspace slug is missing
      """
      base_url = os.getenv("PLANE_INTERNAL_BASE_URL") or os.getenv("PLANE_BASE_URL", "https://api.plane.so")
      workspace_slug = os.getenv("PLANE_WORKSPACE_SLUG", "")
  
      api_key = os.getenv("PLANE_API_KEY", "")
      access_token = None
  
      # Get access token from the OAuth provider (which handles all auth methods)
      stored_access_token: AccessToken | None = get_access_token()
      if stored_access_token:
          # Determine authentication method to use appropriate PlaneClient constructor
          auth_method = stored_access_token.claims.get("auth_method", "oauth")
          token = stored_access_token.token
          workspace_slug = stored_access_token.claims.get("workspace_slug", "")
  
          # For API key auth methods, use api_key parameter; for OAuth, use access_token
          if auth_method in ("api_key_env", "api_key_header"):
              api_key = token
          else:
              access_token = token
  
      if access_token:
          client = PlaneClient(
              base_url=base_url,
              access_token=access_token,
          )
      else:
          client = PlaneClient(
              base_url=base_url,
              api_key=api_key,
          )
  
      return PlaneClientContext(
          client=client,
          workspace_slug=workspace_slug,
      )