@mokoconsulting/mcp-mokosuite 1.0.0

package/src/index.ts

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+/* 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
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mcp-mokosuite.Server
+ * INGROUP: mcp-mokosuite
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mcp-mokosuite
+ * PATH: /src/index.ts
+ * VERSION: 01.00.00
+ * BRIEF: MCP server entry point — registers MokoSuite (Layer 0 / Platform) tools
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { loadConfig, getConnection } from './config.js';
+import { ApiClient } from './client.js';
+import { hasRemoteControl } from './signing.js';
+import type { ApiConfig, ApiResponse } from './types.js';
+
+/** Base path for MokoSuiteClient Web Services (appended after /api/index.php). */
+const MSC = '/v1/mokosuiteclient';
+
+let config: ApiConfig;
+
+function clientFor(connection?: string): ApiClient {
+	return new ApiClient(getConnection(config, connection));
+}
+
+function formatResponse(res: ApiResponse): { content: Array<{ type: 'text'; text: string }> } {
+	if (res.status >= 400) {
+		return {
+			content: [{ type: 'text' as const, text: `Error: HTTP ${res.status}: ${JSON.stringify(res.data, null, 2)}` }],
+		};
+	}
+	return {
+		content: [{ type: 'text' as const, text: JSON.stringify(res.data, null, 2) }],
+	};
+}
+
+function text(message: string): { content: Array<{ type: 'text'; text: string }> } {
+	return { content: [{ type: 'text' as const, text: message }] };
+}
+
+// ── Shared parameter definitions ────────────────────────────────────────
+
+const ConnectionParam = {
+	connection: z.string().optional().describe('Named MokoSuite site/connection from config (uses default if omitted)'),
+};
+
+const ConfirmParam = {
+	confirm: z.boolean().describe('Must be true — this operates on ALL users of the target site and is not reversible'),
+};
+
+function requireConfirm(confirm: boolean): { content: Array<{ type: 'text'; text: string }> } | null {
+	return confirm ? null : text('Refused: set `confirm: true` to run this fleet-wide destructive operation.');
+}
+
+// ── Server ──────────────────────────────────────────────────────────────
+
+const server = new McpServer({
+	name: 'mcp-mokosuite',
+	version: '1.0.0',
+});
+
+// ════════════════════════════════════════════════════════════════════════
+// FOUNDATION — connectivity & generic access
+// ════════════════════════════════════════════════════════════════════════
+
+server.tool(
+	'mokosuite_ping',
+	'Check reachability of a MokoSuite site (calls its dashboard endpoint and reports HTTP status).',
+	{ ...ConnectionParam },
+	async ({ connection }) => {
+		const client = clientFor(connection);
+		try {
+			const res = await client.get(`${MSC}/dashboard`);
+			return text(`Reachable — HTTP ${res.status} from ${MSC}/dashboard`);
+		} catch (err) {
+			return text(`Unreachable: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	},
+);
+
+server.tool(
+	'list_connections',
+	'List configured MokoSuite connections, their role, and which credential tiers are available.',
+	{},
+	async () => {
+		const lines = Object.entries(config.connections).map(([name, conn]) => {
+			const is_default = name === config.defaultConnection ? ' (default)' : '';
+			const role = conn.role ?? 'client';
+			const tiers = ['read/CRUD'];
+			if (hasRemoteControl(conn)) tiers.push('remote-control');
+			return `  ${name}${is_default} [${role}]: ${conn.baseUrl}  — tiers: ${tiers.join(', ')}`;
+		});
+		return text(`Configured MokoSuite connections:\n${lines.join('\n')}`);
+	},
+);
+
+server.tool(
+	'api_request',
+	'Make a raw request to any MokoSuite/Joomla Web Services endpoint (escape hatch). Path is relative to /api/index.php.',
+	{
+		method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
+		endpoint: z.string().describe('Path relative to /api/index.php (e.g. "/v1/mokosuiteclient/health")'),
+		body: z.record(z.string(), z.unknown()).optional().describe('Request body for POST/PUT/PATCH'),
+		params: z.record(z.string(), z.string()).optional().describe('Query parameters'),
+		...ConnectionParam,
+	},
+	async ({ method, endpoint, body, params, connection }) => {
+		const client = clientFor(connection);
+		switch (method) {
+			case 'GET': return formatResponse(await client.get(endpoint, params));
+			case 'POST': return formatResponse(await client.post(endpoint, body));
+			case 'PUT': return formatResponse(await client.put(endpoint, body));
+			case 'PATCH': return formatResponse(await client.patch(endpoint, body));
+			case 'DELETE': return formatResponse(await client.delete(endpoint));
+		}
+	},
+);
+
+// ════════════════════════════════════════════════════════════════════════
+// LAYER 0 — Platform (MokoSuiteClient) — READS  (Joomla API token)
+// ════════════════════════════════════════════════════════════════════════
+
+server.tool(
+	'client_get_health',
+	'Get the full 16-check health diagnostics for a MokoSuite site (db, filesystem, cache, extensions, backup, security, ssl, cron, errors, content, users, mail, seo, template, config).',
+	{ ...ConnectionParam },
+	async ({ connection }) => formatResponse(await clientFor(connection).get(`${MSC}/health`)),
+);
+
+server.tool(
+	'client_get_dashboard',
+	'Get the summarized dashboard for a MokoSuite site (health summary, Joomla/PHP versions, plugin states).',
+	{ ...ConnectionParam },
+	async ({ connection }) => formatResponse(await clientFor(connection).get(`${MSC}/dashboard`)),
+);
+
+server.tool(
+	'client_list_extensions',
+	'List installed extensions on a MokoSuite site, with versions and available update info.',
+	{ ...ConnectionParam },
+	async ({ connection }) => formatResponse(await clientFor(connection).get(`${MSC}/extensions`)),
+);
+
+server.tool(
+	'client_list_plugins',
+	'List the MokoSuite feature plugins on a site and their enabled/disabled state.',
+	{ ...ConnectionParam },
+	async ({ connection }) => formatResponse(await clientFor(connection).get(`${MSC}/plugins`)),
+);
+
+server.tool(
+	'client_list_snapshots',
+	'List the baseline snapshots available on a MokoSuite site.',
+	{ ...ConnectionParam },
+	async ({ connection }) => formatResponse(await clientFor(connection).get(`${MSC}/snapshot`)),
+);
+
+server.tool(
+	'client_list_users',
+	'List Joomla users on a MokoSuite site.',
+	{ ...ConnectionParam },
+	async ({ connection }) => formatResponse(await clientFor(connection).get(`${MSC}/users`)),
+);
+
+server.tool(
+	'client_export_users',
+	'Export the users of a MokoSuite site.',
+	{ ...ConnectionParam },
+	async ({ connection }) => formatResponse(await clientFor(connection).get(`${MSC}/users/export`)),
+);
+
+// ════════════════════════════════════════════════════════════════════════
+// LAYER 0 — Platform — ACTIONS  (Joomla API token, core.manage)
+// ════════════════════════════════════════════════════════════════════════
+
+server.tool(
+	'client_clear_cache',
+	'Clear all Joomla caches and opcache on a MokoSuite site.',
+	{ ...ConnectionParam },
+	async ({ connection }) => formatResponse(await clientFor(connection).post(`${MSC}/cache`)),
+);
+
+server.tool(
+	'client_check_updates',
+	'Run the Joomla update finder on a MokoSuite site and report the number of available updates.',
+	{ ...ConnectionParam },
+	async ({ connection }) => formatResponse(await clientFor(connection).post(`${MSC}/update`)),
+);
+
+server.tool(
+	'client_install_extension',
+	'Install an extension on a MokoSuite site from a remote ZIP URL (64MB cap). Privileged — use trusted URLs only.',
+	{
+		url: z.string().describe('HTTPS URL of the extension ZIP to install'),
+		...ConnectionParam,
+	},
+	async ({ url, connection }) => formatResponse(await clientFor(connection).post(`${MSC}/install`, { url })),
+);
+
+server.tool(
+	'client_toggle_plugin',
+	'Enable or disable a MokoSuite feature plugin on a site by its extension id.',
+	{
+		extension_id: z.number().describe('Joomla extension id of the plugin to toggle'),
+		...ConnectionParam,
+	},
+	async ({ extension_id, connection }) => formatResponse(await clientFor(connection).post(`${MSC}/plugins`, { task: 'toggle', extension_id })),
+);
+
+server.tool(
+	'client_create_snapshot',
+	'Create a baseline snapshot on a MokoSuite site.',
+	{
+		label: z.string().optional().describe('Optional label for the snapshot'),
+		...ConnectionParam,
+	},
+	async ({ label, connection }) => formatResponse(await clientFor(connection).post(`${MSC}/snapshot`, label ? { label } : {})),
+);
+
+server.tool(
+	'client_reset_snapshot',
+	'Restore a named baseline snapshot on a MokoSuite site.',
+	{
+		name: z.string().describe('Name of the baseline snapshot to restore'),
+		...ConnectionParam,
+	},
+	async ({ name, connection }) => formatResponse(await clientFor(connection).post(`${MSC}/reset`, { name })),
+);
+
+server.tool(
+	'client_sync_push',
+	'Push a content sync from this MokoSuite site to a target site.',
+	{
+		target: z.string().optional().describe('Target site identifier/URL for the sync (per site sync config)'),
+		...ConnectionParam,
+	},
+	async ({ target, connection }) => formatResponse(await clientFor(connection).post(`${MSC}/sync`, target ? { target } : {})),
+);
+
+// ════════════════════════════════════════════════════════════════════════
+// LAYER 0 — Platform — REMOTE-CONTROL  (RSA-signed; requires HQ credentials)
+// ════════════════════════════════════════════════════════════════════════
+
+server.tool(
+	'client_provision_reset',
+	'Reset a MokoSuite site for a new client (clears hits, purges version history, regenerates tokens, revokes user tokens). RSA-signed remote-control tier.',
+	{ ...ConfirmParam, ...ConnectionParam },
+	async ({ confirm, connection }) => {
+		const guard = requireConfirm(confirm);
+		if (guard) return guard;
+		return formatResponse(await clientFor(connection).remoteControl('POST', `${MSC}/provision-reset`));
+	},
+);
+
+server.tool(
+	'client_remote_login',
+	'Get a one-time master login URL (60s TTL) for a MokoSuite site. RSA-signed remote-control tier.',
+	{ ...ConnectionParam },
+	async ({ connection }) => formatResponse(await clientFor(connection).remoteControl('POST', `${MSC}/remote-login`)),
+);
+
+server.tool(
+	'client_users_reset_passwords',
+	'Reset passwords for ALL users on a MokoSuite site. RSA-signed remote-control tier.',
+	{ ...ConfirmParam, ...ConnectionParam },
+	async ({ confirm, connection }) => {
+		const guard = requireConfirm(confirm);
+		if (guard) return guard;
+		return formatResponse(await clientFor(connection).remoteControl('POST', `${MSC}/users/reset-passwords`));
+	},
+);
+
+server.tool(
+	'client_users_reset_2fa',
+	'Reset two-factor authentication for ALL users on a MokoSuite site. RSA-signed remote-control tier.',
+	{ ...ConfirmParam, ...ConnectionParam },
+	async ({ confirm, connection }) => {
+		const guard = requireConfirm(confirm);
+		if (guard) return guard;
+		return formatResponse(await clientFor(connection).remoteControl('POST', `${MSC}/users/reset-2fa`));
+	},
+);
+
+server.tool(
+	'client_users_disable_all',
+	'Block ALL users on a MokoSuite site. RSA-signed remote-control tier.',
+	{ ...ConfirmParam, ...ConnectionParam },
+	async ({ confirm, connection }) => {
+		const guard = requireConfirm(confirm);
+		if (guard) return guard;
+		return formatResponse(await clientFor(connection).remoteControl('POST', `${MSC}/users/disable-all`));
+	},
+);
+
+server.tool(
+	'client_users_enable_all',
+	'Unblock ALL users on a MokoSuite site. RSA-signed remote-control tier.',
+	{ ...ConfirmParam, ...ConnectionParam },
+	async ({ confirm, connection }) => {
+		const guard = requireConfirm(confirm);
+		if (guard) return guard;
+		return formatResponse(await clientFor(connection).remoteControl('POST', `${MSC}/users/enable-all`));
+	},
+);
+
+server.tool(
+	'client_users_force_logout',
+	'Terminate ALL user sessions on a MokoSuite site. RSA-signed remote-control tier.',
+	{ ...ConfirmParam, ...ConnectionParam },
+	async ({ confirm, connection }) => {
+		const guard = requireConfirm(confirm);
+		if (guard) return guard;
+		return formatResponse(await clientFor(connection).remoteControl('POST', `${MSC}/users/force-logout`));
+	},
+);
+
+// ── Start Server ────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+	config = await loadConfig();
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+
+main().catch((err) => {
+	process.stderr.write(`Fatal: ${err}\n`);
+	process.exit(1);
+});

package/src/signing.ts

@@ -0,0 +1,67 @@
+/* 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
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mcp-mokosuite.Signing
+ * INGROUP: mcp-mokosuite
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mcp-mokosuite
+ * PATH: /src/signing.ts
+ * VERSION: 01.00.00
+ * BRIEF: RSA request-signing for the MokoSuiteClient remote-control tier
+ */
+
+import { readFileSync } from 'node:fs';
+import { createSign } from 'node:crypto';
+import type { ApiConnection } from './types.js';
+
+/**
+ * MokoSuiteClient's remote-control routes (provision-reset, remote-login, mass user ops)
+ * are `public` but require defence-in-depth headers that only MokoSuiteHQ can generate.
+ * HQ signs the payload `domain|timestamp|token` with its RSA-2048 private key (SHA-256);
+ * the client verifies against a baked-in public keyring within a 300-second freshness
+ * window. This reproduces that scheme so the MCP can act as HQ.
+ *
+ * @throws if the connection is missing the remote-control credentials or the key is unreadable.
+ */
+export function buildRemoteControlHeaders(conn: ApiConnection): Record<string, string> {
+	if (!conn.healthApiToken) {
+		throw new Error('Remote-control requires "healthApiToken" in the connection config.');
+	}
+	if (!conn.rsaPrivateKeyPath) {
+		throw new Error('Remote-control requires "rsaPrivateKeyPath" (HQ RSA-2048 private key) in the connection config.');
+	}
+
+	const domain = new URL(conn.baseUrl).hostname;
+	const timestamp = Math.floor(Date.now() / 1000).toString();
+	const payload = `${domain}|${timestamp}|${conn.healthApiToken}`;
+
+	let privateKey: string;
+	try {
+		privateKey = readFileSync(conn.rsaPrivateKeyPath, 'utf-8');
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Cannot read RSA private key at ${conn.rsaPrivateKeyPath}: ${message}`);
+	}
+
+	let signature: string;
+	try {
+		signature = createSign('RSA-SHA256').update(payload).sign(privateKey, 'base64');
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to RSA-sign remote-control payload: ${message}`);
+	}
+
+	return {
+		'X-MokoSuite-Signature': signature,
+		'X-MokoSuite-Timestamp': timestamp,
+		'X-MokoSuite-Key-Version': String(conn.keyVersion ?? 1),
+	};
+}
+
+/** True when a connection carries the credentials needed for the remote-control tier. */
+export function hasRemoteControl(conn: ApiConnection): boolean {
+	return Boolean(conn.healthApiToken && conn.rsaPrivateKeyPath);
+}

package/src/types.ts

@@ -0,0 +1,63 @@
+/* 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
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mcp-mokosuite.Types
+ * INGROUP: mcp-mokosuite
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mcp-mokosuite
+ * PATH: /src/types.ts
+ * VERSION: 01.00.00
+ * BRIEF: TypeScript type definitions for MokoSuite MCP server
+ */
+
+/** A connection is either a MokoSuite client site or the MokoSuite HQ control plane. */
+export type ConnectionRole = 'client' | 'hq';
+
+/**
+ * Connection configuration for a single MokoSuite instance.
+ *
+ * MokoSuiteClient exposes two auth tiers on the same base URL:
+ *  - **Reads / CRUD** — the site's Joomla Web Services Bearer token (`apiToken`),
+ *    authorised against `core.manage`. This is all most tools need.
+ *  - **Remote-control** (provision-reset, remote-login, mass user ops) — the routes are
+ *    `public` and instead validate the site's `healthApiToken` plus an RSA signature that
+ *    only MokoSuiteHQ can produce. Configure `healthApiToken` + `rsaPrivateKeyPath` to let
+ *    this MCP act as HQ for those operations.
+ */
+export interface ApiConnection {
+	/** Base URL of the site root (no trailing slash); "/api/index.php" is appended. */
+	baseUrl: string;
+	/** Joomla Web Services Bearer token — used for read/CRUD tools. */
+	apiToken: string;
+	/** Whether this connection is a client site (default) or the HQ control plane. */
+	role?: ConnectionRole;
+	/** Skip TLS certificate verification (self-signed certs). */
+	insecure?: boolean;
+
+	// ── Remote-control tier (optional — lets the MCP act as MokoSuiteHQ) ──────
+	/** Per-site 64-hex `health_api_token` required by the remote-control routes. */
+	healthApiToken?: string;
+	/** Path to HQ's RSA-2048 private key (PEM) used to sign remote-control requests. */
+	rsaPrivateKeyPath?: string;
+	/** Signing key version advertised to the client's public keyring (default 1). */
+	keyVersion?: number;
+}
+
+/**
+ * Top-level configuration supporting multiple named connections.
+ */
+export interface ApiConfig {
+	connections: Record<string, ApiConnection>;
+	defaultConnection: string;
+}
+
+/**
+ * Normalized API response returned by the HTTP client.
+ */
+export interface ApiResponse {
+	status: number;
+	data: unknown;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "Node16",
+		"moduleResolution": "Node16",
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}