Joomla MCP Server

Instructions

Implementation Reference

• main.py:265-315 (handler)

  The handler function for the 'move_article_to_trash' tool, registered via @mcp.tool decorator. It fetches the article by ID, optionally verifies the title, checks if already trashed, and delegates to manage_article_state(article_id, -2) to set state to trashed.
  @mcp.tool( description="Delete an article by moving to the trashed state on the Joomla website, allowing recovery." ) 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 helper function manage_article_state used by move_article_to_trash to perform the actual state change to trashed (-2).
  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)}"