wiki/joomla-api-mcp/ARCHITECTURE.md

← Home

Architecture

Overview

joomla-api-mcp is a Model Context Protocol (MCP) server that bridges AI assistants (Claude Code, Cursor, etc.) with Joomla's built-in Web Services REST API.

AI Assistant  <-->  MCP (stdio)  <-->  JoomlaClient  <-->  Joomla REST API
                                                           /api/index.php/v1

Components

src/index.ts — Server Entry Point

Registers all MCP tools with the McpServer from @modelcontextprotocol/sdk. Each tool maps to one or more Joomla API endpoints. Uses Zod schemas for input validation.

src/client.ts — HTTP Client

The JoomlaClient class handles all HTTP communication with Joomla instances:

• Uses node:https / node:http for requests (not fetch) to support self-signed TLS certificates on Node.js 24+
• Authenticates via Bearer token in the Authorization header
• Sends Accept: application/vnd.api+json per Joomla's JSON:API spec
• Includes a JSON parser that handles Joomla responses that may append HTML error fragments after valid JSON

src/config.ts — Configuration Loader

Loads connection details from ~/.joomla-api-mcp.json. Supports multiple named connections with a configurable default.

src/types.ts — Type Definitions

TypeScript interfaces for JoomlaConnection, JoomlaConfig, and ApiResponse.

scripts/setup.mjs — Interactive Setup

Node.js script using readline/promises that walks users through creating the config file. Supports adding multiple connections incrementally.

Design Decisions

Why node:https instead of fetch?

Node.js 24's built-in fetch (undici-based) does not honor NODE_TLS_REJECT_UNAUTHORIZED=0 for self-signed certificate bypass. The classic node:https module with rejectUnauthorized: false works reliably across all Node.js versions.

Why JSON recovery parsing?

Joomla's API sometimes returns valid JSON with text/html content-type, and may append HTML error fragments (e.g. template errors) after the JSON body. The tryParseJson method handles this by finding the last valid JSON boundary when standard parsing fails.

Why per-connection API tokens?

Each Joomla site requires its own API token scoped to a specific user. Multi-site support is a core use case — managing staging, production, and dev environments from a single MCP server.

Data Flow

1. AI assistant sends a tool call via MCP stdio transport
2. index.ts validates parameters with Zod and resolves the connection
3. JoomlaClient constructs the API URL, attaches auth headers, and makes the HTTP request
4. Response is parsed (with JSON recovery if needed) and returned as MCP tool output

Revision History

Date	Version	Author	Notes
2026-04-23	0.0.1	jmiller	Initial architecture document

---

Repo: joomla-api-mcp · MokoStandards

Revision	Date	Author	Description
1.0	2026-05-09	Moko Consulting	Initial version