manage_article_state

Instructions

Implementation Reference

• main.py:201-203 (registration)

  The @mcp.tool decorator that registers the manage_article_state function as an MCP tool.

  @mcp.tool(
      description="Manage the state of an existing article on the Joomla website (published, unpublished, archived, trashed)"
  )

• main.py:204-258 (handler)

  The core handler function that implements the logic for managing Joomla article states via API: fetches current state, validates target state, and performs PATCH update if needed.

  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)}"

• main.py:310-310 (helper)

  Helper usage of manage_article_state within the move_article_to_trash tool to set state to trashed (-2).

  return await manage_article_state(article_id, -2)