Joomla MCP Server

Instructions

Implementation Reference

• main.py:80-112 (handler)

  The async function get_joomla_categories fetches categories from the Joomla API using httpx, parses the JSON response, and formats a list of category IDs and titles. It includes comprehensive error handling for HTTP errors, JSON parsing, and general exceptions. The @mcp.tool decorator registers it as an MCP tool.

  @mcp.tool(description="Retrieve all categories from the Joomla website.")
  async def get_joomla_categories() -> str:
      """Retrieve all categories from the Joomla website via its API."""
      try:
          headers = {
              "Accept": "application/vnd.api+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):
                  return f"Error: Expected a list of categories, got {type(categories).__name__}: {response.text}"
              if not categories:
                  return "No categories found."
              result = "Available categories:\n"
              for category in categories:
                  attributes = category.get("attributes", {})
                  category_id = attributes.get("id", "N/A")
                  category_title = attributes.get("title", "N/A")
                  result += f"- ID: {category_id}, Title: {category_title}\n"
              return result
          except json.JSONDecodeError:
              return f"Error parsing categories response: Invalid JSON - {response.text}"
      except httpx.HTTPError as e:
          return f"Error fetching categories: {str(e)}"
      except Exception as e:
          return f"Unexpected error: {str(e)}"