From 5c16823219b148eecb7725dd4e0096ccaa19db95 Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Sun, 10 May 2026 18:39:20 +0000 Subject: [PATCH] docs: update README from wiki Home --- README.md | 322 +++++++++++------------------------------------------- 1 file changed, 65 insertions(+), 257 deletions(-) diff --git a/README.md b/README.md index a62c418..063c130 100644 --- a/README.md +++ b/README.md @@ -1,296 +1,104 @@ - - - -[![Version](https://img.shields.io/badge/version-01.00.00-blue.svg?logo=v&logoColor=white)](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/releases/tag/v00) -[![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green.svg?logo=gnu&logoColor=white)](LICENSE) -[![Node](https://img.shields.io/badge/Node.js-20%2B-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org) - # joomla-api-mcp -[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) +MCP server for Joomla Web Services API operations -A Model Context Protocol (MCP) server that exposes the Joomla 4/5/6 Web Services API as tools for AI assistants. +![Language](https://img.shields.io/badge/Markdown-000000?style=flat-square&logo=markdown&logoColor=white) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green?style=flat-square) ![Wiki](https://img.shields.io/badge/wiki-joomla-api-mcp-blue?style=flat-square) -Connects to Joomla instances over HTTP using the built-in REST API (`/api/index.php/v1`) and API token authentication. Claude, Cursor, and other MCP clients can manage articles, categories, users, menus, plugins, and more — without SSH or direct server access. -## Table of Contents +Model Context Protocol server for the Joomla Web Services API -- full CRUD for articles, categories, users, menus, contacts, tags, media, plugins, and more. -- [Background](#background) -- [Install](#install) -- [Usage](#usage) -- [Tools](#tools) -- [Configuration](#configuration) -- [Contributing](#contributing) -- [License](#license) -- [Maintainers](#maintainers) +--- -## Background +| | | +|---|---| +| **Type** | MCP Server | +| **Language** | Node.js | +| **Tools** | 67 tools across 15 resource groups | +| **License** | GPL-3.0-or-later | +| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp) (primary) | -Joomla 4+ ships with a full Web Services API that supports content management, user administration, and site configuration over REST. This MCP server wraps that API into structured tools, enabling: +--- -- Article management (list, create, update, delete, publish) -- Category management (list, create, update, delete) -- User administration (list, create, update, delete, groups) -- Menu and menu item inspection -- Plugin listing and enable/disable toggling -- Module and template listing -- Tag, contact, banner, and newsfeed management -- Media file browsing -- Application configuration read/write -- Private messaging -- Custom field inspection -- Raw API passthrough for any endpoint +## Overview -Supports multiple named connections for managing several Joomla instances from a single MCP server. +joomla-api-mcp wraps the entire Joomla Web Services REST API into MCP tools that Claude Code can call directly. It supports multi-site connections via named connection configs. -## Install +### Resource Coverage -```sh -git clone https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp.git -cd joomla-api-mcp -npm install -npm run build -npm run setup -``` +| Group | Operations | +|-------|------------| +| Articles | list, get, create, update, delete | +| Categories | list, create, update, delete | +| Users | list, get, create, update, delete, groups | +| Contacts | list, get, create, update, delete | +| Menus | list types, list/get/create/update/delete items | +| Tags | list, get, create, update, delete | +| Custom Fields | list, get, create, delete | +| Plugins | list, update (enable/disable) | +| Modules | list | +| Templates | list | +| Media | list, get file, delete file, create folder | +| Banners | list, get, create, delete, list clients | +| Newsfeeds | list, get, create, delete | +| Messages | list, get, send, delete | +| Redirects | list, create, delete | +| Config | get, update | +| Content History | list versions | +| Checkin | unlock checked-out items | +| Associations | list multilingual associations | +| Generic | raw API request, list connections | -The setup wizard will prompt for your Joomla site URL and API token. Run it again to add more connections — each site gets its own name, URL, and API key so you can manage multiple Joomla instances from a single MCP server. +--- -## Usage +## Wiki Pages -### Add to Claude Code +### Guides -In your Claude Code MCP settings (`~/.claude.json` or project `.mcp.json`): +- [Installation](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/wiki/INSTALLATION) -- setup, .env configuration, Claude Code registration, multi-site connections -```json -{ - "mcpServers": { - "joomla": { - "command": "node", - "args": ["/path/to/joomla-api-mcp/dist/index.js"] - } - } -} -``` +### Reference -### Configuration +- [API](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/wiki/API) -- all 67 tools with parameters, grouped by resource type +- [Architecture](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/wiki/ARCHITECTURE) -- source file map, component design, connection handling -The easiest way to configure is `npm run setup`, which walks you through it interactively. Run it multiple times to add connections for each Joomla site you manage. +### Templates -You can also create the config manually. Copy `config.example.json` to `~/.joomla-api-mcp.json` and edit: +- [Templates Index](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/wiki/templates-index) -- workflow and config templates +- [README Template](templates-README-template) -- README template for MCP repos -```sh -cp config.example.json ~/.joomla-api-mcp.json -``` +--- -Each connection needs the Joomla site's base URL and an API token (generated in Joomla under Users > Edit User > API Token): +## Related Wikis -```json -{ - "defaultConnection": "production", - "connections": { - "local-dev": { - "baseUrl": "https://localhost:8080", - "apiToken": "your-joomla-api-token-here", - "insecure": true - }, - "production": { - "baseUrl": "https://www.example.com", - "apiToken": "your-production-api-token" - }, - "staging": { - "baseUrl": "https://staging.example.com", - "apiToken": "your-staging-api-token" - } - } -} -``` +| Repo | Purpose | +|------|---------| +| [backup-mcp](https://git.mokoconsulting.tech/MokoConsulting/backup-mcp/wiki) | Backup MCP (uses Joomla API for Akeeba) | +| [MokoWaaS](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki) | Joomla WaaS system plugin | +| [Template-Client-WaaS](https://git.mokoconsulting.tech/MokoConsulting/Template-Client-WaaS/wiki) | Client site template | +| [MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/wiki) | Joomla admin template | -| Field | Required | Description | -|-------|----------|-------------| -| `baseUrl` | Yes | Joomla site URL (no trailing slash) | -| `apiToken` | Yes | Joomla API token (Bearer auth) | -| `insecure` | No | Skip TLS verification for self-signed certs | +--- -## Tools (67) +> **[MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki)** -- central standards hub for all Moko Consulting projects. -### Articles +--- -| Tool | Description | -|------|-------------| -| `joomla_articles_list` | List articles with optional category, state, and search filters | -| `joomla_article_get` | Get a single article by ID | -| `joomla_article_create` | Create a new article | -| `joomla_article_update` | Update an existing article | -| `joomla_article_delete` | Delete an article | -### Categories -| Tool | Description | -|------|-------------| -| `joomla_categories_list` | List content categories | -| `joomla_category_create` | Create a new category | -| `joomla_category_update` | Update a category | -| `joomla_category_delete` | Delete a category | +--- -### Users +## Documentation -| Tool | Description | -|------|-------------| -| `joomla_users_list` | List users with optional search, group, and state filters | -| `joomla_user_get` | Get a single user by ID | -| `joomla_user_create` | Create a user with auto-generated secure password | -| `joomla_user_update` | Update a user | -| `joomla_user_delete` | Delete a user | -| `joomla_user_groups_list` | List user groups | - -### Contacts - -| Tool | Description | -|------|-------------| -| `joomla_contacts_list` | List contacts with optional search | -| `joomla_contact_get` | Get a single contact by ID | -| `joomla_contact_create` | Create a new contact | -| `joomla_contact_update` | Update an existing contact | -| `joomla_contact_delete` | Delete a contact | - -### Menus - -| Tool | Description | -|------|-------------| -| `joomla_menus_list` | List menu types | -| `joomla_menu_items_list` | List menu items for a menu type | -| `joomla_menu_item_get` | Get a single menu item by ID | -| `joomla_menu_item_create` | Create a new menu item | -| `joomla_menu_item_update` | Update a menu item | -| `joomla_menu_item_delete` | Delete a menu item | - -### Tags - -| Tool | Description | -|------|-------------| -| `joomla_tags_list` | List tags with optional search | -| `joomla_tag_get` | Get a single tag by ID | -| `joomla_tag_create` | Create a tag | -| `joomla_tag_update` | Update a tag | -| `joomla_tag_delete` | Delete a tag | - -### Custom Fields - -| Tool | Description | -|------|-------------| -| `joomla_fields_list` | List custom fields for a context | -| `joomla_field_get` | Get a single custom field by ID | -| `joomla_field_create` | Create a custom field | -| `joomla_field_delete` | Delete a custom field | - -### Banners - -| Tool | Description | -|------|-------------| -| `joomla_banners_list` | List banners | -| `joomla_banner_get` | Get a single banner by ID | -| `joomla_banner_create` | Create a new banner | -| `joomla_banner_delete` | Delete a banner | -| `joomla_banner_clients_list` | List banner clients | - -### Newsfeeds - -| Tool | Description | -|------|-------------| -| `joomla_newsfeeds_list` | List newsfeeds | -| `joomla_newsfeed_get` | Get a single newsfeed by ID | -| `joomla_newsfeed_create` | Create a new newsfeed | -| `joomla_newsfeed_delete` | Delete a newsfeed | - -### Messages - -| Tool | Description | -|------|-------------| -| `joomla_messages_list` | List private messages | -| `joomla_message_get` | Get a single private message | -| `joomla_message_send` | Send a private message to a user | -| `joomla_message_delete` | Delete a private message | - -### Media - -| Tool | Description | -|------|-------------| -| `joomla_media_list` | List media files in a folder | -| `joomla_media_file_get` | Get metadata for a specific media file | -| `joomla_media_file_delete` | Delete a media file | -| `joomla_media_folder_create` | Create a new media folder | - -### Redirects - -| Tool | Description | -|------|-------------| -| `joomla_redirects_list` | List URL redirects | -| `joomla_redirect_create` | Create a URL redirect | -| `joomla_redirect_delete` | Delete a URL redirect | - -### Plugins - -| Tool | Description | -|------|-------------| -| `joomla_plugins_list` | List plugins with optional type, state, and search filters | -| `joomla_plugin_update` | Enable or disable a plugin | - -### Other - -| Tool | Description | -|------|-------------| -| `joomla_modules_list` | List site or admin modules | -| `joomla_templates_list` | List site or admin templates | -| `joomla_languages_list` | List installed content languages | -| `joomla_content_history_list` | List version history for a content item | -| `joomla_checkin` | Check in (unlock) a checked-out content item | -| `joomla_associations_list` | List multilingual associations for a content item | -| `joomla_config_get` | Get application configuration | -| `joomla_config_update` | Update application configuration values | -| `joomla_api_request` | Raw API request to any Joomla endpoint | -| `joomla_list_connections` | List configured connections | - -All tools accept an optional `connection` parameter to target a specific named connection. +Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/wiki). ## Contributing -Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests. - -This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md) Code of Conduct. +See the wiki for development guidelines and contribution instructions. ## License -This project is licensed under the GNU General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details. +This project is licensed under the GNU General Public License v3.0 or later -- see the [LICENSE](LICENSE) file. -Copyright © 2026 Moko Consulting +--- -## Maintainers - -[@mokoconsulting-tech](https://git.mokoconsulting.tech/MokoConsulting) - -For questions or support, please contact: hello@mokoconsulting.tech - -## Revision History - -| Date | Version | Author | Notes | -| --- | --- | --- | --- | -| 2026-04-23 | 0.0.1 | jmiller | Initial MCP server with Joomla Web Services API tools | +*[Moko Consulting](https://mokoconsulting.tech) -- [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)* -- 2.52.0