@mokoconsulting/mcp-mokosuite 1.0.0

package/dist/signing.js

@@ -0,0 +1,62 @@
+/* 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';
+/**
+ * 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) {
+    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;
+    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;
+    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) {
+    return Boolean(conn.healthApiToken && conn.rsaPrivateKeyPath);
+}
+//# sourceMappingURL=signing.js.map

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+/** 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;
+    /** 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,16 @@
+/* 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
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/docs/API.md

@@ -0,0 +1,63 @@
+<!--
+Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+SPDX-License-Identifier: GPL-3.0-or-later
+
+# FILE INFORMATION
+DEFGROUP: mcp-mokosuite.Documentation
+PATH: /docs/API.md
+VERSION: 01.00.00
+BRIEF: MCP tool reference documentation
+-->
+
+# API Reference
+
+All tools accept an optional `connection` parameter to target a specific named connection. If omitted, the default connection is used.
+
+## Example Resources
+
+> Replace these example tools with your actual API tools.
+
+### `example_resources_list`
+List resources with optional search.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `search` | string | No | Search query |
+| `limit` | number | No | Max results |
+| `page` | number | No | Page number (0-based) |
+
+### `example_resource_get`
+Get a single resource by ID.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | number | Yes | Resource ID |
+
+### `example_resource_create`
+Create a new resource.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Resource name |
+| `description` | string | No | Resource description |
+
+## Generic
+
+### `api_request`
+Make a raw API request to any endpoint.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `method` | `"GET"` / `"POST"` / `"PUT"` / `"PATCH"` / `"DELETE"` | Yes | HTTP method |
+| `endpoint` | string | Yes | API path |
+| `body` | object | No | Request body |
+| `params` | object | No | Query parameters |
+
+### `list_connections`
+List all configured connections. No parameters.
+
+## Revision History
+
+| Date | Version | Author | Notes |
+| --- | --- | --- | --- |
+| 2026-05-07 | 0.0.1 | jmiller | Initial template API reference |

package/docs/ARCHITECTURE.md

@@ -0,0 +1,73 @@
+<!--
+Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+SPDX-License-Identifier: GPL-3.0-or-later
+
+# FILE INFORMATION
+DEFGROUP: mcp-mokosuite.Documentation
+PATH: /docs/ARCHITECTURE.md
+VERSION: 01.00.00
+BRIEF: Architecture overview and design decisions
+-->
+
+# Architecture
+
+## Overview
+
+mcp-mokosuite is a Model Context Protocol (MCP) server that bridges AI assistants with a REST API.
+
+```
+AI Assistant  <-->  MCP (stdio)  <-->  ApiClient  <-->  REST API
+```
+
+## Components
+
+### `src/index.ts` — Server Entry Point
+
+Registers all MCP tools with `McpServer` from `@modelcontextprotocol/sdk`. Each tool maps to one or more API endpoints. Uses Zod schemas for input validation.
+
+Includes shared helpers:
+- `formatResponse()` — normalizes error/success responses into MCP text content
+- `paginationQuery()` — builds pagination query params
+- `ConnectionParam` / `PaginationParams` — reusable Zod parameter spreads
+
+### `src/client.ts` — HTTP Client
+
+The `ApiClient` class handles all HTTP communication:
+- Uses `node:https` / `node:http` (not `fetch`) for reliable self-signed cert support
+- Supports GET, POST, PUT, PATCH, DELETE
+- JSON serialization/deserialization with error handling
+
+### `src/config.ts` — Configuration Loader
+
+Loads connection details from `~/.<project>.json`. Supports multiple named connections with a configurable default.
+
+### `src/types.ts` — Type Definitions
+
+TypeScript interfaces for `ApiConnection`, `ApiConfig`, and `ApiResponse`.
+
+### `scripts/setup.mjs` — Interactive Setup
+
+Node.js script using `readline/promises` for interactive config creation.
+
+## Design Decisions
+
+### Why `node:https` instead of `fetch`?
+
+Node.js 24's built-in `fetch` does not honor self-signed certificate bypass. The classic `node:https` module with `rejectUnauthorized: false` works reliably across all Node.js versions.
+
+### Why multiple named connections?
+
+Multi-instance 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. `ApiClient` constructs the API URL, attaches auth headers, and makes the HTTP request
+4. Response is parsed as JSON and returned as MCP tool output
+
+## Revision History
+
+| Date | Version | Author | Notes |
+| --- | --- | --- | --- |
+| 2026-05-07 | 0.0.1 | jmiller | Initial architecture document |

package/docs/INSTALLATION.md

@@ -0,0 +1,102 @@
+<!--
+Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+SPDX-License-Identifier: GPL-3.0-or-later
+
+# FILE INFORMATION
+DEFGROUP: mcp-mokosuite.Documentation
+PATH: /docs/INSTALLATION.md
+VERSION: 01.00.00
+BRIEF: Installation and setup instructions
+-->
+
+# Installation
+
+## Prerequisites
+
+- **Node.js** 20.0.0 or later
+- **npm** (included with Node.js)
+- Access to the target API with valid credentials
+
+## Install
+
+```sh
+git clone https://git.mokoconsulting.tech/MokoConsulting/mcp-mokosuite.git
+cd mcp-mokosuite
+npm install
+npm run build
+npm run setup
+```
+
+The setup wizard will prompt for:
+
+1. **Connection name** — a label for this instance (e.g. `production`, `staging`)
+2. **API URL** — the base URL of the instance
+3. **API key/token** — authentication credentials
+4. **TLS verification** — whether to skip certificate verification (for self-signed certs)
+
+Run `npm run setup` again to add more connections.
+
+## Register with Claude Code
+
+Add to your Claude Code MCP settings (`~/.claude.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "mcp-mokosuite": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/mcp-mokosuite/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Code after adding the server.
+
+## Configuration File
+
+The config is stored at `~/.mcp-mokosuite.json`:
+
+```json
+{
+  "defaultConnection": "production",
+  "connections": {
+    "production": {
+      "baseUrl": "https://api.example.com",
+      "apiKey": "your-api-key"
+    },
+    "staging": {
+      "baseUrl": "https://api-staging.example.com",
+      "apiKey": "your-staging-key",
+      "insecure": true
+    }
+  }
+}
+```
+
+You can also set the `MOKOSUITE_CONFIG` environment variable to use a config file at a custom path.
+
+## Verification
+
+```sh
+npm start
+```
+
+If configured correctly, the server will start listening on stdio.
+
+## Troubleshooting
+
+### "Failed to load config" error
+Run `npm run setup` to create the config file.
+
+### Connection errors
+- Verify the API is reachable from your machine
+- For self-signed certs, set `"insecure": true`
+- Ensure the API key/token is valid
+
+## Revision History
+
+| Date | Version | Author | Notes |
+| --- | --- | --- | --- |
+| 2026-05-07 | 0.0.1 | jmiller | Initial installation guide |

package/docs/index.md

@@ -0,0 +1,12 @@
+<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+     SPDX-License-Identifier: GPL-3.0-or-later -->
+
+# mcp-mokosuite Documentation
+
+See the [README](../README.md) for quick start, customization guide, and tool patterns.
+
+## Documents
+
+- [INSTALLATION.md](./INSTALLATION.md) — Prerequisites, install, setup, troubleshooting
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — Component overview, design decisions, data flow
+- [API.md](./API.md) — Full MCP tool reference with parameter tables

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "@mokoconsulting/mcp-mokosuite",
+	"version": "1.0.0",
+	"description": "MCP server for MokoSuite (Joomla) REST API v1 operations",
+	"type": "module",
+	"main": "dist/index.js",
+	"bin": {
+		"mokosuite-api-mcp": "dist/index.js"
+	},
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsc --watch",
+		"start": "node dist/index.js",
+		"lint": "eslint src/",
+		"setup": "node scripts/setup.mjs",
+		"clean": "rm -rf dist/"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.12.1",
+		"zod": "^3.24.4"
+	},
+	"devDependencies": {
+		"@types/node": "^22.15.3",
+		"typescript": "^5.8.3"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"license": "GPL-3.0-or-later",
+	"author": "Moko Consulting <hello@mokoconsulting.tech>",
+	"repository": {
+		"type": "git",
+		"url": "https://git.mokoconsulting.tech/MokoConsulting/mcp-mokosuite.git"
+	}
+}

package/src/client.ts

@@ -0,0 +1,142 @@
+/* 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.Client
+ * INGROUP: mcp-mokosuite
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mcp-mokosuite
+ * PATH: /src/client.ts
+ * VERSION: 01.00.00
+ * BRIEF: HTTP client for the MokoSuite (Joomla Web Services) API
+ */
+
+import * as https from 'node:https';
+import * as http from 'node:http';
+import type { ApiConnection, ApiResponse } from './types.js';
+import { buildRemoteControlHeaders } from './signing.js';
+
+// ── Endpoint conventions ────────────────────────────────────────────────
+// Joomla Web Services live under /api/index.php; MokoSuiteClient routes are
+// registered at /v1/mokosuiteclient/* (see MSC_BASE in index.ts).
+const API_PREFIX = '/api/index.php';
+const TIMEOUT_MS = 30_000;
+// ────────────────────────────────────────────────────────────────────────
+
+export class ApiClient {
+	private readonly conn: ApiConnection;
+	private readonly base_url: string;
+	private readonly headers: Record<string, string>;
+	private readonly insecure: boolean;
+
+	constructor(conn: ApiConnection) {
+		this.conn = conn;
+		this.base_url = conn.baseUrl.replace(/\/+$/, '') + API_PREFIX;
+
+		// Read/CRUD tier: Joomla Web Services authenticate via a Bearer API token.
+		this.headers = {
+			'Authorization': `Bearer ${conn.apiToken}`,
+			'Content-Type': 'application/json',
+			'Accept': 'application/vnd.api+json',
+		};
+		this.insecure = conn.insecure ?? false;
+	}
+
+	async get(endpoint: string, params?: Record<string, string>): Promise<ApiResponse> {
+		return this.request(this.buildUrl(endpoint, params), 'GET');
+	}
+
+	async post(endpoint: string, body?: unknown): Promise<ApiResponse> {
+		return this.request(this.buildUrl(endpoint), 'POST', body);
+	}
+
+	async put(endpoint: string, body: unknown): Promise<ApiResponse> {
+		return this.request(this.buildUrl(endpoint), 'PUT', body);
+	}
+
+	async patch(endpoint: string, body: unknown): Promise<ApiResponse> {
+		return this.request(this.buildUrl(endpoint), 'PATCH', body);
+	}
+
+	async delete(endpoint: string): Promise<ApiResponse> {
+		return this.request(this.buildUrl(endpoint), 'DELETE');
+	}
+
+	/**
+	 * Remote-control tier: swap the auth to the site's `health_api_token` and attach the
+	 * RSA signature headers HQ uses, then issue a GET or POST. Requires the connection to
+	 * carry `healthApiToken` + `rsaPrivateKeyPath`.
+	 */
+	async remoteControl(method: 'GET' | 'POST', endpoint: string, body?: unknown, params?: Record<string, string>): Promise<ApiResponse> {
+		const signed: Record<string, string> = {
+			...buildRemoteControlHeaders(this.conn),
+			'Authorization': `Bearer ${this.conn.healthApiToken}`,
+		};
+		return this.request(this.buildUrl(endpoint, params), method, body, signed);
+	}
+
+	private buildUrl(endpoint: string, params?: Record<string, string>): string {
+		const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+		const url = new URL(`${this.base_url}${path}`);
+		if (params) {
+			for (const [key, value] of Object.entries(params)) {
+				url.searchParams.set(key, value);
+			}
+		}
+		return url.toString();
+	}
+
+	private request(url: string, method: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<ApiResponse> {
+		return new Promise((resolve, reject) => {
+			const parsed = new URL(url);
+			const is_https = parsed.protocol === 'https:';
+			const transport = is_https ? https : http;
+
+			const options: https.RequestOptions = {
+				hostname: parsed.hostname,
+				port: parsed.port || (is_https ? 443 : 80),
+				path: parsed.pathname + parsed.search,
+				method,
+				headers: { ...this.headers, ...(extraHeaders ?? {}) },
+				timeout: TIMEOUT_MS,
+			};
+
+			if (this.insecure && is_https) {
+				options.rejectUnauthorized = false;
+			}
+
+			const payload = body !== undefined ? JSON.stringify(body) : undefined;
+			if (payload) {
+				(options.headers as Record<string, string>)['Content-Length'] = Buffer.byteLength(payload).toString();
+			}
+
+			const req = transport.request(options, (res) => {
+				const chunks: Buffer[] = [];
+				res.on('data', (chunk: Buffer) => chunks.push(chunk));
+				res.on('end', () => {
+					const raw = Buffer.concat(chunks).toString('utf-8');
+					let data: unknown;
+					try {
+						data = JSON.parse(raw);
+					} catch {
+						data = raw;
+					}
+					resolve({ status: res.statusCode ?? 0, data });
+				});
+			});
+
+			req.on('error', (err) => reject(err));
+			req.on('timeout', () => {
+				req.destroy();
+				reject(new Error('Request timed out'));
+			});
+
+			if (payload) {
+				req.write(payload);
+			}
+			req.end();
+		});
+	}
+}

package/src/config.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.Config
+ * INGROUP: mcp-mokosuite
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mcp-mokosuite
+ * PATH: /src/config.ts
+ * VERSION: 01.00.00
+ * BRIEF: Configuration loader for MokoSuite MCP connections
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import type { ApiConfig, ApiConnection } from './types.js';
+
+// ── Customize this ──────────────────────────────────────────────────────
+// Change the filename to match your project (e.g. ".dolibarr-api-mcp.json")
+const CONFIG_FILENAME = '.mcp_mokosuite.json';
+// Change the env var name to match your project
+const CONFIG_ENV_VAR = 'MOKOSUITE_CONFIG';
+// ────────────────────────────────────────────────────────────────────────
+
+export async function loadConfig(): Promise<ApiConfig> {
+	const config_path = process.env[CONFIG_ENV_VAR]
+		? resolve(process.env[CONFIG_ENV_VAR]!)
+		: resolve(homedir(), CONFIG_FILENAME);
+
+	try {
+		const raw = await readFile(config_path, 'utf-8');
+		const parsed = JSON.parse(raw) as Partial<ApiConfig>;
+
+		if (!parsed.connections || Object.keys(parsed.connections).length === 0) {
+			throw new Error('No connections defined in config');
+		}
+
+		return {
+			connections: parsed.connections,
+			defaultConnection: parsed.defaultConnection ?? Object.keys(parsed.connections)[0],
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(
+			`Failed to load config from ${config_path}: ${message}\n` +
+			`Create ${config_path} — see config.example.json for format.`,
+		);
+	}
+}
+
+export function getConnection(config: ApiConfig, name?: string): ApiConnection {
+	const key = name ?? config.defaultConnection;
+	const conn = config.connections[key];
+	if (!conn) {
+		throw new Error(
+			`Connection "${key}" not found. Available: ${Object.keys(config.connections).join(', ')}`,
+		);
+	}
+	return conn;
+}