Joomla MCP Server

Instructions

Implementation Reference

• main.py:317-411 (handler)

  The main handler function for the 'update_article' tool. It is decorated with @mcp.tool, which also serves as registration. The function fetches the existing article, prepares the update payload (handling title alias generation, text to HTML conversion), and sends a PATCH request to the Joomla API to update specified fields: title, introtext, fulltext, metadesc.
  @mcp.tool(description="Update an existing article on the Joomla website.") async def update_article( article_id: int, title: str = None, introtext: str = None, fulltext: str = None, metadesc: str = None, convert_plain_text: bool = True, ) -> str: """ Update an existing article on the Joomla website via its API. Allows updating the title, introtext, fulltext, and meta description. Provide both introtext and fulltext together for articles with separate introductory and main content, or provide only fulltext for articles where a single body of content is sufficient. Introtext alone is not sufficient and will be ignored unless accompanied by fulltext. Before updating, confirm the article's title and ID are correct. Only articles with both introtext and fulltext will be updated. Args: article_id(int): The ID of the article to update. Don't prompt user for article_id, infer it by running the get_joomla_articles tool. title (str, optional): New title for the article. introtext (str, optional): Introductory text (requires fulltext if provided). fulltext: Optional full content for the article (plain text or HTML). Used as primary content if provided alone, or as main content if provided with introtext. metadesc: Optional meta description for the article. convert_plain_text: Whether to auto-convert plain text to HTML for introtext and fulltext (default: True). Returns: Result string indicating success or failure. """ try: if not isinstance(article_id, int): return "Error: Article ID must be an integer." if not any([title, introtext, fulltext, metadesc]): return "Error: At least one of title, introtext, fulltext, or metadesc must be provided." 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", {}) current_title = article_data.get("title", "Unknown") except json.JSONDecodeError: return f"Failed to parse article data: Invalid JSON - {response.text}" payload = {} if title: payload["title"] = title payload["alias"] = generate_alias(title) if metadesc: payload["metadesc"] = metadesc if introtext: payload["introtext"] = ( convert_text_to_html(introtext) if convert_plain_text else introtext ) if fulltext: payload["fulltext"] = ( convert_text_to_html(fulltext) if convert_plain_text else fulltext ) elif fulltext: payload["articletext"] = ( convert_text_to_html(fulltext) if convert_plain_text else fulltext ) 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): updated_fields = [] if title: updated_fields.append(f"title to '{title}'") if introtext: updated_fields.append("introtext") if fulltext: updated_fields.append("fulltext" if introtext else "body") if metadesc: updated_fields.append("metadesc") return f"Successfully updated article '{current_title}' (ID: {article_id}) {', '.join(updated_fields)}." else: error_detail = response.text return f"Failed to update article: HTTP {response.status_code} - {error_detail}. This may indicate a server-side issue or insufficient permissions. Please verify the bearer token permissions and Joomla server logs." except httpx.HTTPError as e: return f"Error updating article: {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."