docs: update README from wiki Home

2026-05-10 18:39:20 +00:00
parent 3f89873f19
commit 5c16823219
1 changed files with 65 additions and 257 deletions
@@ -1,296 +1,104 @@
-<!--	Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
-
-	This file is part of a Moko Consulting project.
-
-	SPDX-LICENSE-IDENTIFIER: GPL-3.0-or-later
-
-	This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
-
-	This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
-	You should have received a copy of the GNU General Public License (./LICENSE).
-
-	# FILE INFORMATION
-	DEFGROUP: joomla-api-mcp.Documentation
-	INGROUP: joomla-api-mcp
-	REPO: https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp
-	VERSION: 01.00.00
-	PATH: ./README.md
-	BRIEF: MCP server for Joomla Web Services API operations
-->
-
-
-[![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 <hello@mokoconsulting.tech>
+---

-## 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)*