Joomla MCP Server

Instructions

Implementation Reference

• main.py:115-198 (handler)

  The main handler function for the 'create_article' tool, decorated with @mcp.tool for registration. It handles article creation by converting text to HTML if needed, generating alias, validating category, and sending POST request to Joomla API.
  @mcp.tool(description="Create a new article on the Joomla website.") async def create_article( article_text: str, title: str = None, category_id: int = None, convert_plain_text: bool = True, published: bool = True, ) -> str: """ Create a new article on the Joomla website via its API. User will provide title, content, category, and publication status. Args: article_text (str): The content of the article (plain text or HTML). title (str, optional): The article title. Inferred from content if not provided. category_id (int, optional): The ID of the category. If not provided, lists available categories. convert_plain_text (bool): Convert plain text to HTML if True. Defaults to True. published (bool): Publish the article (True for state=1, False for state=0). Defaults to True. Returns: Success message with article title and category ID, or an error message if the request fails. """ try: if convert_plain_text: article_text = convert_text_to_html(article_text) if not title: title = ( article_text[:50].strip() + "..." if len(article_text) > 50 else article_text ) title = title.replace("\n", " ").strip() alias = generate_alias(title) if category_id is None: categories_display = await get_joomla_categories() return f"{categories_display}\nPlease specify a category ID." if not isinstance(category_id, int): return "Error: Category 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(JOOMLA_CATEGORIES_API_URL, headers=headers) if response.status_code != 200: return f"Failed to fetch categories: HTTP {response.status_code} - {response.text}" try: data = json.loads(response.text) categories = data.get("data", []) if not isinstance(categories, list) or not categories: return "Failed to create article: No valid categories found." except json.JSONDecodeError: return f"Failed to create article: Invalid category JSON - {response.text}" valid_category = any( category.get("attributes", {}).get("id") == category_id for category in categories ) if not valid_category: return f"Error: Category ID {category_id} is not valid." payload = { "alias": alias, "articletext": article_text, "catid": category_id, "language": "*", "metadesc": "", "metakey": "", "title": title, "state": 1 if published else 0, } async with httpx.AsyncClient() as client: response = await client.post( JOOMLA_ARTICLES_API_URL, json=payload, headers=headers ) if response.status_code in (200, 201): status = "published" if published else "unpublished" return f"Successfully created {status} article '{title}' in category ID {category_id}" else: return f"Failed to create article: HTTP {response.status_code} - {response.text}" except httpx.HTTPError as e: return f"Error creating article: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}"
• main.py:26-56 (helper)

  Helper function used by create_article to convert plain text input to sanitized HTML.
  def convert_text_to_html(text: str) -> str: """ Convert plain text to sanitized HTML using markdown and bleach. Args: text (str): The plain text to convert. Returns: str: Sanitized HTML content with allowed tags only. """ html = markdown.markdown(text) allowed_tags = [ "p", "br", "strong", "em", "ul", "ol", "li", "h1", "h2", "h3", "h4", "h5", "h6", ] allowed_attributes = {} sanitized_html = bleach.clean( html, tags=allowed_tags, attributes=allowed_attributes, strip=True ) return sanitized_html
• main.py:19-23 (helper)

  Helper function used by create_article to generate URL alias from title.
  def generate_alias(title: str) -> str: """Convert a title to a slug alias (lowercase, hyphens, no special chars).""" alias = re.sub(r"[^a-z0-9\s-]", "", title.lower()) alias = re.sub(r"\s+", "-", alias).strip("-") return alias