Joomla MCP Server

Instructions

Implementation Reference

• main.py:115-198 (handler)

  The primary handler function decorated with @mcp.tool, implementing the logic to create a new Joomla article: handles input parameters, converts text to HTML if needed, generates alias, validates category, and posts 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-57 (helper)

  Supporting function to convert plain text input to sanitized HTML, used by create_article when convert_plain_text is True.

  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)

  Utility function to generate a URL-friendly alias/slug from the article title, used in create_article payload.

  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