move_article_to_trash

Instructions

Implementation Reference

• main.py:265-267 (registration)

  Registers the 'move_article_to_trash' tool with the FastMCP server using the @mcp.tool decorator, providing a description.

  @mcp.tool(
      description="Delete an article by moving to the trashed state on the Joomla website, allowing recovery."
  )

• main.py:268-315 (handler)

  The main handler function for the 'move_article_to_trash' tool. It verifies the article exists, optionally checks the title matches, ensures it's not already trashed, and delegates to manage_article_state(article_id, -2) to update the state to trashed.

  async def move_article_to_trash(article_id: int, expected_title: str = None) -> str:
      """
      Delete an article by moving it to the trashed state (-2) on the Joomla website via its API.
      Verifies article existence and optionally checks the title to prevent moving the wrong article.
      The article remains in the database for potential recovery.
  
      Args:
          article_id(int): The ID of the article to move to trash.
          expected_title: Optional title to verify the correct article (case-insensitive partial match).
  
      Returns:
          Result string indicating success or failure.
      """
      try:
          if not isinstance(article_id, int):
              return "Error: Article ID must be an integer."
          headers = {
              "Accept": "application/vnd.api+json",
              "Content-Type": "application/json",
              "User-Agent": "JoomlaArticlesMCP/1.0",
              "Authorization": f"Bearer {BEARER_TOKEN}",
          }
          async with httpx.AsyncClient() as client:
              response = await client.get(
                  f"{JOOMLA_ARTICLES_API_URL}/{article_id}", headers=headers
              )
          if response.status_code != 200:
              return (
                  f"Failed to find article: HTTP {response.status_code} - {response.text}"
              )
          try:
              data = json.loads(response.text)
              article_data = data.get("data", {}).get("attributes", {})
              title = article_data.get("title", "Unknown")
              current_state = article_data.get("state", 0)
          except json.JSONDecodeError:
              return f"Failed to parse article data: Invalid JSON - {response.text}"
          if expected_title:
              if not title.lower().find(expected_title.lower()) >= 0:
                  return f"Error: Article ID {article_id} has title '{title}', which does not match expected title '{expected_title}'."
          if current_state == -2:
              return f"Article '{title}' (ID: {article_id}) is already in trashed state."
          return await manage_article_state(article_id, -2)
      except httpx.HTTPError as e:
          return f"Error moving article to trash: {str(e)}. Please check network connectivity or Joomla API availability."
      except Exception as e:
          return f"Unexpected error: {str(e)}. Please try again or contact support."

• main.py:204-259 (helper)

  Supporting function 'manage_article_state' used by move_article_to_trash to perform the actual state update to trashed (-2). This is a shared utility for managing article states.

  async def manage_article_state(article_id: int, target_state: int) -> str:
      """
      Manage the state of an existing article on the Joomla website via its API. Updates the article to the
      user-specified state (published=1, unpublished=0, archived=2, trashed=-2) if it differs from the current state.
  
      Args:
          article_id(int): The ID of the existing article to check and update.
          target_state: The desired state for the article (1=published, 0=unpublished, 2=archived, -2=trashed).
  
      Returns:
          Success message with article title, ID, and state change, or an error message if the request fails.
      """
      try:
          if not isinstance(article_id, int):
              return "Error: Article ID must be an integer."
          valid_states = {1, 0, 2, -2}
          if target_state not in valid_states:
              return f"Error: Invalid target state {target_state}. Valid states are 1 (published), 0 (unpublished), 2 (archived), -2 (trashed)."
          headers = {
              "Accept": "application/vnd.api+json",
              "Content-Type": "application/json",
              "User-Agent": "JoomlaArticlesMCP/1.0",
              "Authorization": f"Bearer {BEARER_TOKEN}",
          }
          async with httpx.AsyncClient() as client:
              response = await client.get(
                  f"{JOOMLA_ARTICLES_API_URL}/{article_id}", headers=headers
              )
          if response.status_code != 200:
              return f"Failed to fetch article: HTTP {response.status_code} - {response.text}"
          try:
              data = json.loads(response.text)
              article_data = data.get("data", {}).get("attributes", {})
              current_state = article_data.get("state", 0)
              title = article_data.get("title", "Unknown")
          except json.JSONDecodeError:
              return f"Failed to parse article data: Invalid JSON - {response.text}"
          state_map = {1: "published", 0: "unpublished", 2: "archived", -2: "trashed"}
          current_state_name = state_map.get(current_state, "unknown")
          target_state_name = state_map.get(target_state, "unknown")
          if current_state == target_state:
              return f"Article '{title}' (ID: {article_id}) is already in {current_state_name} state."
          payload = {"state": target_state}
          async with httpx.AsyncClient() as client:
              response = await client.patch(
                  f"{JOOMLA_ARTICLES_API_URL}/{article_id}", json=payload, headers=headers
              )
          if response.status_code in (200, 204):
              return f"Successfully updated article '{title}' (ID: {article_id}) from {current_state_name} to {target_state_name} state."
          else:
              return f"Failed to update article state: HTTP {response.status_code} - {response.text}"
      except httpx.HTTPError as e:
          return f"Error updating article state: {str(e)}"
      except Exception as e:
          return f"Unexpected error: {str(e)}"