mcp-mokonyx

Model Context Protocol (MCP) server for the Mokonyx platform. It lets AI assistants like Claude operate Mokonyx client sites through the MokonyxPlatform Joomla Web Services API (base path /v1/mokonyxplatform) — health, dashboards, extensions, plugins, snapshots, cache/updates, content sync, and (via HQ credentials) provisioning, remote login, and fleet-wide user operations — plus the MokonyxCRM and MokonyxStoreLocator Web Services.

Features

• Broad tool surface across the platform, extensions store, social analytics, CRM, and store-locator APIs — reads, actions, and RSA-signed remote-control.
• Multi-site — every named connection is a Mokonyx site (or the HQ control plane); all tools accept an optional connection parameter.
• Two credential tiers — a Joomla Web Services Bearer token for read/CRUD, plus an optional health_api_token + HQ RSA private key for the remote-control tier.
• Safety guards — destructive fleet-wide operations require an explicit confirm: true.
• TypeScript-first, ESM, node:https transport (reliable self-signed cert support).

Installation

npm install -g @mokoconsulting/mcp-mokonyx

Or run on demand with npx:

npx @mokoconsulting/mcp-mokonyx

Create ~/.mcp_mokonyx.json (or point $MOKONYX_CONFIG at a file) — see config.example.json:

{
  "defaultConnection": "moko-live",
  "connections": {
    "moko-live": { "baseUrl": "https://mokoconsulting.tech", "apiToken": "your-joomla-api-token" }
  }
}

• apiToken — a Joomla Web Services API token (Users → Manage → API Tokens) for the read/CRUD tools.
• healthApiToken + rsaPrivateKeyPath + keyVersion (optional) — the site's health_api_token and HQ's RSA-2048 signing key, required only for the remote-control tools (provision-reset, remote-login, mass user ops).

Credential token files

Instead of an inline apiToken, a connection's token can live in a token file so secrets stay out of the config JSON. A token file is JSON:

{ "domain": "clarksvillefurs.com", "username": "webmaster", "api_key": "<joomla-web-services-token>" }

api_key is the Joomla token verbatim (the base64 string Joomla issues — it is not decoded). A bare token on a single line is also accepted. The token is resolved per connection with this precedence (a token file wins over inline):

1. apiTokenFile — an explicit path (~ expands). Use this for client sites, whose token file lives in the client's own repo, e.g. "apiTokenFile": "~/Clients/client-mokonyx-clarksvillefurs/clarksvillefurs.com.webmaster.token".
2. Auto-discovery — if neither apiTokenFile nor apiToken is set, the loader looks for ~/.ssh/tokens/<host>.webmaster.token (host derived from baseUrl). Use this for moko sites — drop the file in ~/.ssh/tokens/ and omit the token from the config.
3. apiToken — an inline literal (back-compat).

If a token file's domain doesn't match the connection host, the loader warns (this catches a mis-copied key). Always gitignore *.token in client repos.

Usage

Register the server with your MCP client (e.g. Claude Code / Claude Desktop):

{
  "mcpServers": {
    "mokonyx": { "command": "npx", "args": ["-y", "@mokoconsulting/mcp-mokonyx"] }
  }
}

Then ask the assistant to use the tools, e.g. "check the health of the moko-dev site" → platform_get_health. Representative tools:

| Tier | Tools | |---|---| | Foundation | mokonyx_ping, list_connections, api_request | | Reads | platform_get_health, platform_get_dashboard, platform_list_extensions, platform_list_plugins, platform_list_snapshots, platform_list_users, platform_export_users, platform_content_by_field, platform_content_field_count | | Actions | platform_clear_cache, platform_check_updates, platform_install_extension, platform_toggle_plugin, platform_create_snapshot, platform_reset_snapshot, platform_sync_push | | Remote-control (RSA-signed) | platform_provision_reset, platform_remote_login, platform_users_reset_passwords, platform_users_reset_2fa, platform_users_disable_all, platform_users_enable_all, platform_users_force_logout | | CRM | crm_contacts_list, crm_contact_get, crm_contact_create, crm_companies_list, crm_company_get, crm_deals_list, crm_deal_get, crm_deal_create, crm_pipeline_list, crm_activities_list, crm_invoices_list | | Store Locator | storelocator_locations_list, storelocator_location_get, storelocator_location_create, storelocator_location_update, storelocator_location_delete |

All tools target the default connection unless a connection argument names another site. Remote-control tools require the second credential tier and destructive ones require confirm: true.

Site requirements per tool family

| Tool family | Requires on the target site | |---|---| | api_request, and any tool hitting /v1/content/* (platform_content_by_field, platform_content_field_count) | Joomla core content Web Services — available on every Joomla site. | | platform_* | The MokonyxPlatform component + its plg_webservices_mokonyxplatform plugin, installed and enabled. | | store_* | The MokonyxExtensions component + its plg_webservices_mokonyxextensions plugin, installed and enabled. | | social_* | The MokonyxSocial component + its webservices plugin, installed and enabled. | | crm_* | The MokonyxCRM component + its plg_webservices_mokonyxcrm plugin, installed and enabled (base path /v1/mokonyx/crm). | | storelocator_* | The MokonyxStoreLocator component + its plg_webservices_mokonyxstorelocator plugin, installed and enabled. |

Joomla only serves a component over the REST API while its plg_webservices_* plugin is enabled (and plugins install disabled by default). When a platform_*/store_*/social_* tool returns an HTTP 404 with Joomla's generic "Resource not found", this server reports that the corresponding Web Services plugin is likely not installed/enabled on that site rather than a bare 404 — install/update the MokonyxExtensions package and enable the plugin under Extensions → Plugins. Use mokonyx_ping to check platform-API availability up front. See MokonyxExtensions#137.

Development

npm install       # install dependencies
npm run build     # compile TypeScript to dist/
npm run dev       # watch mode
npm start         # run the compiled server

Contributing

Contributions follow MokoStandards. See CONTRIBUTING.md. Develop on feature branches, use Authored-by: Moko Consulting in commits, and open a PR to main.

License

Licensed under the GNU General Public License v3.0 or later — see LICENSE.

Moko Consulting — MokoStandards