@mokoconsulting/mokomysql-mcp 2.5.4 → 2.6.0

package/source/index.ts

@@ -1,1100 +1,1105 @@
-#!/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: mokomysql.Server
- * INGROUP: mokomysql
- * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
- * PATH: /src/index.ts
- * VERSION: 01.00.00
- * BRIEF: MCP server entry point — registers all MySQL management tools
- */
-
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createHash, randomBytes } from 'node:crypto';
-import { z } from 'zod';
-import { loadConfig } from './config.js';
-import { MysqlClient } from './client.js';
-import type { MySqlConfig } from './types.js';
-
-export let config: MySqlConfig;
-export let client: MysqlClient;
-
-function formatRows(rows: Record<string, unknown>[]): { content: Array<{ type: 'text'; text: string }> } {
-	const text = rows.length === 0
-		? 'No rows returned.'
-		: JSON.stringify(rows, null, 2);
-	return { content: [{ type: 'text' as const, text: `${rows.length} row(s)\n${text}` }] };
-}
-
-function formatResult(r: { affectedRows: number; insertId: number; changedRows: number }): { content: Array<{ type: 'text'; text: string }> } {
-	return { content: [{ type: 'text' as const, text: `Affected rows: ${r.affectedRows} | Insert ID: ${r.insertId} | Changed rows: ${r.changedRows}` }] };
-}
-
-function formatError(err: unknown): { content: Array<{ type: 'text'; text: string }> } {
-	const e = err as { code?: string; message?: string };
-	const code = e.code ? ` [${e.code}]` : '';
-	const msg = e.message ?? String(err);
-	return { content: [{ type: 'text' as const, text: `MySQL Error${code}: ${msg}` }] };
-}
-
-function esc(identifier: string): string {
-	return '`' + identifier.replace(/`/g, '``') + '`';
-}
-
-/**
- * Classify a statement as a read. Only SELECT/SHOW/EXPLAIN/DESCRIBE are treated
- * as reads (they stay unrestricted on Joomla DBs); everything else — including
- * `WITH`, `SET`, and all DML/DDL — is conservatively treated as a write so the
- * double-confirm gate errs toward safety. Leading comments/whitespace are stripped.
- */
-function isReadStatement(sql: string): boolean {
-	const stripped = sql
-		.replace(/\/\*[\s\S]*?\*\//g, ' ')       // /* block comments */
-		.replace(/^\s*(--|#)[^\n]*$/gm, ' ')      // -- and # line comments
-		.trim();
-	return /^(SELECT|SHOW|EXPLAIN|DESCRIBE|DESC)\b/i.test(stripped);
-}
-
-/**
- * Classify a write statement by its leading keyword, so the gate can tell apart the
- * operations that actually mutate Joomla's structural invariants from those that don't.
- *
- * The asset/nested-set coupling lives in the Joomla Table API, which raw SQL bypasses
- * (verified against joomla-cms 5.2.3): `Table::store()` creates/updates a `#__assets`
- * row and only renumbers the nested set when a node is NEW or MOVED (Table.php:913-916;
- * Nested.php:696,720); `Table::delete()` removes the asset row before the entity row
- * (Table.php:1053-1065). A raw in-place `UPDATE` never enters `store()`, so it cannot
- * create, delete, or renumber an asset / nested-set row. A raw `INSERT`/`DELETE` of an
- * asset-bearing entity (any table with an `asset_id` column — Table.php:208-209), by
- * contrast, desynchronizes `#__assets` (no paired asset row, or an orphaned one). DDL
- * and anything unrecognized are treated as structurally hazardous, conservatively.
- */
-type WriteOp = 'INSERT' | 'UPDATE' | 'DELETE' | 'DDL' | 'OTHER';
-function classifyWrite(sql: string): WriteOp {
-	const s = sql
-		.replace(/\/\*[\s\S]*?\*\//g, ' ')       // /* block comments */
-		.replace(/^\s*(--|#)[^\n]*$/gm, ' ')      // -- and # line comments
-		.trim();
-	if (/^(INSERT|REPLACE)\b/i.test(s)) return 'INSERT';
-	if (/^UPDATE\b/i.test(s)) return 'UPDATE';
-	if (/^DELETE\b/i.test(s)) return 'DELETE';
-	if (/^(CREATE|ALTER|DROP|TRUNCATE|RENAME)\b/i.test(s)) return 'DDL';
-	return 'OTHER';
-}
-
-/**
- * Known MySQL privilege identifiers accepted by GRANT/REVOKE. Compared
- * case-insensitively against each comma-separated token supplied by the caller
- * so an arbitrary string can never be interpolated raw into a GRANT statement.
- */
-const ALLOWED_PRIVILEGES = new Set([
-	'SELECT', 'INSERT', 'UPDATE', 'DELETE', 'CREATE', 'DROP', 'RELOAD',
-	'SHUTDOWN', 'PROCESS', 'FILE', 'REFERENCES', 'INDEX', 'ALTER',
-	'SHOW DATABASES', 'SUPER', 'CREATE TEMPORARY TABLES', 'LOCK TABLES',
-	'EXECUTE', 'REPLICATION SLAVE', 'REPLICATION CLIENT', 'CREATE VIEW',
-	'SHOW VIEW', 'CREATE ROUTINE', 'ALTER ROUTINE', 'CREATE USER', 'EVENT',
-	'TRIGGER', 'GRANT OPTION', 'ALL', 'ALL PRIVILEGES', 'USAGE',
-]);
-
-/**
- * Validate a comma-separated `privileges` string against ALLOWED_PRIVILEGES.
- * Rejects parentheses (column-level grants) and any unknown token so nothing
- * unvetted reaches the raw GRANT/REVOKE statement. Returns the normalized,
- * uppercased, re-joined privilege list safe for interpolation.
- */
-function validatePrivileges(privileges: string): string {
-	if (/[()]/.test(privileges)) {
-		throw new Error('Column-level privileges (parentheses) are not supported. Supply plain privilege names only.');
-	}
-	const tokens = privileges.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
-	if (tokens.length === 0) {
-		throw new Error('No privileges supplied.');
-	}
-	const normalized: string[] = [];
-	for (const tok of tokens) {
-		const upper = tok.toUpperCase().replace(/\s+/g, ' ');
-		if (!ALLOWED_PRIVILEGES.has(upper)) {
-			throw new Error(`Rejected unknown or unsafe privilege: "${tok}". Allowed: ${[...ALLOWED_PRIVILEGES].join(', ')}.`);
-		}
-		normalized.push(upper);
-	}
-	return normalized.join(', ');
-}
-
-/** Joomla nested-set tables — raw lft/rgt writes here are the hazardous ones. */
-const NESTED_SET_SUFFIXES = ['assets', 'categories', 'menu'] as const;
-
-/**
- * Find Joomla nested-set tables referenced by a statement. With a known prefix
- * the match is precise (`<prefix>assets`); without one it falls back to matching
- * the bare table names as whole identifiers, which may over-warn but never
- * silently misses a hazardous target.
- */
-function nestedSetTablesHit(sql: string, prefix: string | null): string[] {
-	const names = NESTED_SET_SUFFIXES.map((s) => (prefix !== null ? `${prefix}${s}` : s));
-	const hits: string[] = [];
-	for (const name of names) {
-		// Match the identifier with optional backtick quoting, on word boundaries.
-		const re = new RegExp('(^|[^a-z0-9_`])`?' + name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '`?([^a-z0-9_`]|$)', 'i');
-		if (re.test(sql)) hits.push(name);
-	}
-	return hits;
-}
-
-const ConnectionParam = {
-	connection: z.string().optional().describe('Named connection from config (uses default if omitted)'),
-};
-
-const DatabaseParam = {
-	database: z.string().describe('Database name'),
-};
-
-const TableParam = {
-	table: z.string().describe('Table name'),
-};
-
-const ConfirmParam = {
-	confirm: z.boolean().describe('Must be true to execute this destructive operation'),
-};
-
-const JoomlaTokenParam = {
-	confirm_token: z.string().optional().describe(
-		'Second-step acknowledgement token for a write to a Joomla database. Leave empty on the ' +
-		'first call: the write is NOT executed and a token bound to this exact statement+target is ' +
-		'returned. Repeat the SAME call with that token to actually run it. Reads are never gated; ' +
-		'non-Joomla databases ignore this and run on confirm alone.',
-	),
-};
-
-// ── Joomla write gate: mandatory two-step challenge/acknowledge ──────────
-//
-// Writes to a Joomla DB must never execute from a single call (an interrupted or
-// careless raw write silently corrupts the nested-set tables — see issue #39). The
-// first call issues a one-time token bound to the exact statement+target and does
-// NOT run; only a second call echoing that token proceeds.
-//
-// The gate is operation-aware (issue #65): the two-step token is required for EVERY
-// Joomla write, but the nested-set/ACL-corruption warning is reserved for the writes
-// that can actually cause it — INSERT/DELETE of asset-bearing rows, DDL, and any write
-// to a nested-set table. A pure in-place UPDATE that avoids the nested-set tables gets
-// a lighter message, because that coupling lives in the Joomla Table API (store()/
-// delete()), which raw SQL bypasses entirely.
-
-interface PendingWrite {
-	/** Binds the token to a specific normalized op + connection + schema. */
-	bindHash: string;
-	/** Epoch ms when issued, for TTL expiry. */
-	issuedAt: number;
-}
-
-const TOKEN_TTL_MS = 5 * 60 * 1000;
-const pendingWrites = new Map<string, PendingWrite>();
-
-function bindHashFor(op: string, connKey: string, schema: string): string {
-	const normalized = op.trim().replace(/\s+/g, ' ');
-	// JSON framing keeps the three parts unambiguously separated (no delimiter can
-	// bleed across fields) while staying printable text.
-	return createHash('sha256').update(JSON.stringify([connKey, schema, normalized])).digest('hex');
-}
-
-type GateResult = { ok: true } | { ok: false; text: string };
-
-/**
- * Enforce the two-step gate for a write `op` (raw SQL, or a synthetic descriptor
- * like `DROP TABLE db.table` for the structured tools). Reads and non-Joomla
- * targets pass straight through. On a Joomla write: a valid matching token runs it
- * (and is consumed); anything else returns a fresh challenge and does NOT execute.
- */
-async function joomlaWriteGate(
-	op: string,
-	connection: string | undefined,
-	database: string | undefined,
-	confirmToken: string | undefined,
-): Promise<GateResult> {
-	if (isReadStatement(op)) return { ok: true };
-	const j = await client.detectJoomla(connection, database);
-	if (!j.isJoomla) return { ok: true };
-
-	const { connKey, schema } = client.resolveIdentity(connection, database);
-	const bindHash = bindHashFor(op, connKey, schema);
-	const now = Date.now();
-
-	if (confirmToken) {
-		const pending = pendingWrites.get(confirmToken);
-		if (pending && pending.bindHash === bindHash && now - pending.issuedAt <= TOKEN_TTL_MS) {
-			pendingWrites.delete(confirmToken); // one-time use
-			return { ok: true };
-		}
-		// Mismatched / expired / unknown token → fall through and re-challenge.
-	}
-
-	const token = randomBytes(9).toString('hex');
-	pendingWrites.set(token, { bindHash, issuedAt: now });
-	const nested = nestedSetTablesHit(op, j.prefix);
-	const writeOp = classifyWrite(op);
-	// A pure in-place UPDATE that does not reference a nested-set table cannot create,
-	// delete, or renumber an #__assets / nested-set row (that coupling lives in the Joomla
-	// Table API, which raw SQL bypasses — see classifyWrite). Such statements still get the
-	// two-step gate (an interrupted or mis-scoped raw write can corrupt row data), but NOT
-	// the misleading nested-set/ACL-corruption framing. Everything else — INSERT/DELETE,
-	// DDL, anything unrecognized, and any write to a nested-set table — keeps it.
-	const inPlaceUpdate = writeOp === 'UPDATE' && nested.length === 0;
-	const lines = [
-		'⛔ WRITE to a Joomla database — a second confirmation is REQUIRED. This call did NOT execute.',
-		'',
-	];
-	if (inPlaceUpdate) {
-		lines.push(
-			'This is an in-place UPDATE that does not touch a nested-set table (assets / categories / menu),',
-			'so it will NOT create, remove, or renumber ACL asset rows or nested sets — Joomla only mutates',
-			'those on row creation/deletion, which raw SQL bypasses. The two-step confirm still applies because',
-			'an interrupted or mis-scoped raw write can corrupt row data. To proceed, repeat the SAME call adding:',
-			`    confirm_token: "${token}"`,
-			'(one-time, valid ~5 min, bound to this exact statement + target).',
-		);
-	} else {
-		lines.push(
-			'Joomla tables carry structural invariants (nested sets, ACL) that raw SQL can corrupt, and an',
-			'interrupted write can leave the database broken. To proceed, repeat the SAME call adding:',
-			`    confirm_token: "${token}"`,
-			'(one-time, valid ~5 min, bound to this exact statement + target).',
-		);
-	}
-	if (nested.length) {
-		lines.push(
-			'',
-			`⚠ Targets nested-set table(s): ${nested.join(', ')}.`,
-			'Strongly prefer the Joomla Web Services API / CLI, which maintains lft/rgt automatically.',
-			'If you must write raw, complete the whole operation in one go, then verify integrity:',
-			'max(rgt) == 2 × node_count, no duplicate lft/rgt, no lft >= rgt, children within parent bounds.',
-		);
-	} else if (writeOp === 'INSERT' || writeOp === 'DELETE') {
-		lines.push(
-			'',
-			`⚠ Raw ${writeOp} of a row. If the target is asset-bearing (any table with an asset_id column —`,
-			'articles, categories, modules, contacts, banners, newsfeeds, fields, tags, …), Joomla pairs each',
-			'row with a #__assets ACL row via Table::store()/delete(). Raw SQL bypasses that: an INSERT leaves',
-			'the new row with no asset row (broken ACL), a DELETE orphans the asset row. Strongly prefer the',
-			'Joomla Web Services API / CLI, which maintains the asset tree automatically.',
-		);
-	}
-	return { ok: false, text: lines.join('\n') };
-}
-
-const LimitParam = {
-	limit: z.number().optional().describe('Max rows to return (default 500, max 10000)'),
-};
-
-const server = new McpServer({
-	name: '@mokoconsulting/mokomysql-mcp',
-	version: '1.0.0',
-});
-
-// ── Connection & Server Info ────────────────────────────────────────────
-
-server.tool(
-	'mysql_connections_list',
-	'List all configured MySQL connection names with host/port/user (no passwords)',
-	{ ...ConnectionParam },
-	async () => {
-		const entries = Object.entries(config.connections).map(([name, c]) => ({
-			name,
-			host: c.host,
-			port: c.port ?? 3306,
-			user: c.user,
-			database: c.database ?? '(none)',
-			default: name === config.defaultConnection,
-		}));
-		return formatRows(entries);
-	},
-);
-
-server.tool(
-	'mysql_server_version',
-	'Get MySQL server version and uptime',
-	{ ...ConnectionParam },
-	async ({ connection }) => {
-		try {
-			const { rows } = await client.query(
-				"SELECT VERSION() AS version, @@hostname AS hostname, @@port AS port, " +
-				"VARIABLE_VALUE AS uptime FROM performance_schema.global_status WHERE VARIABLE_NAME = 'Uptime'",
-				[], connection,
-			);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_server_status',
-	'Show MySQL server status variables (SHOW GLOBAL STATUS)',
-	{ ...ConnectionParam, filter: z.string().optional().describe('LIKE pattern to filter (e.g. "Threads%")') },
-	async ({ connection, filter }) => {
-		try {
-			const sql = filter ? `SHOW GLOBAL STATUS LIKE ?` : 'SHOW GLOBAL STATUS';
-			const params = filter ? [filter] : [];
-			const { rows } = await client.query(sql, params, connection);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_server_variables',
-	'Show MySQL system variables (SHOW GLOBAL VARIABLES)',
-	{ ...ConnectionParam, filter: z.string().optional().describe('LIKE pattern to filter (e.g. "innodb%")') },
-	async ({ connection, filter }) => {
-		try {
-			const sql = filter ? `SHOW GLOBAL VARIABLES LIKE ?` : 'SHOW GLOBAL VARIABLES';
-			const params = filter ? [filter] : [];
-			const { rows } = await client.query(sql, params, connection);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-// ── Database Management ─────────────────────────────────────────────────
-
-server.tool(
-	'mysql_databases_list',
-	'List all databases with sizes',
-	{ ...ConnectionParam },
-	async ({ connection }) => {
-		try {
-			const { rows } = await client.query(
-				"SELECT s.SCHEMA_NAME AS `database`, " +
-				"ROUND(SUM(t.DATA_LENGTH + t.INDEX_LENGTH) / 1024 / 1024, 2) AS size_mb, " +
-				"COUNT(t.TABLE_NAME) AS tables_count, " +
-				"s.DEFAULT_CHARACTER_SET_NAME AS charset, " +
-				"s.DEFAULT_COLLATION_NAME AS collation " +
-				"FROM information_schema.SCHEMATA s " +
-				"LEFT JOIN information_schema.TABLES t ON s.SCHEMA_NAME = t.TABLE_SCHEMA " +
-				"GROUP BY s.SCHEMA_NAME ORDER BY size_mb DESC",
-				[], connection,
-			);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_database_create',
-	'Create a new database',
-	{ ...ConnectionParam, ...DatabaseParam, charset: z.string().optional().describe('Character set (default utf8mb4)'), collation: z.string().optional().describe('Collation (default utf8mb4_unicode_ci)') },
-	async ({ connection, database, charset, collation }) => {
-		try {
-			const cs = charset ?? 'utf8mb4';
-			const co = collation ?? 'utf8mb4_unicode_ci';
-			const r = await client.execute(
-				`CREATE DATABASE ${esc(database)} CHARACTER SET ${esc(cs)} COLLATE ${esc(co)}`,
-				[], connection,
-			);
-			return formatResult(r);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_database_drop',
-	'Drop a database — DESTRUCTIVE, requires confirm=true. If the database is Joomla, also requires the two-step confirm_token.',
-	{ ...ConnectionParam, ...DatabaseParam, ...ConfirmParam, ...JoomlaTokenParam },
-	async ({ connection, database, confirm, confirm_token }) => {
-		if (!confirm) return { content: [{ type: 'text' as const, text: 'Aborted: confirm must be true to drop a database.' }] };
-		const op = `DROP DATABASE ${esc(database)}`;
-		const gate = await joomlaWriteGate(op, connection, database, confirm_token);
-		if (!gate.ok) return { content: [{ type: 'text' as const, text: gate.text }] };
-		try {
-			const r = await client.execute(op, [], connection);
-			return formatResult(r);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_database_size',
-	'Show database size breakdown by table',
-	{ ...ConnectionParam, ...DatabaseParam },
-	async ({ connection, database }) => {
-		try {
-			const { rows } = await client.query(
-				"SELECT TABLE_NAME AS `table`, TABLE_ROWS AS rows_estimate, " +
-				"ROUND(DATA_LENGTH / 1024 / 1024, 2) AS data_mb, " +
-				"ROUND(INDEX_LENGTH / 1024 / 1024, 2) AS index_mb, " +
-				"ROUND((DATA_LENGTH + INDEX_LENGTH) / 1024 / 1024, 2) AS total_mb, " +
-				"ENGINE AS engine " +
-				"FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? ORDER BY total_mb DESC",
-				[database], connection,
-			);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-// ── Table Management ────────────────────────────────────────────────────
-
-server.tool(
-	'mysql_tables_list',
-	'List all tables in a database with engine, row count estimate, and size',
-	{ ...ConnectionParam, ...DatabaseParam },
-	async ({ connection, database }) => {
-		try {
-			const { rows } = await client.query(
-				"SELECT TABLE_NAME AS `table`, ENGINE AS engine, TABLE_ROWS AS rows_estimate, " +
-				"ROUND((DATA_LENGTH + INDEX_LENGTH) / 1024, 2) AS size_kb, " +
-				"TABLE_COLLATION AS collation, AUTO_INCREMENT AS auto_increment " +
-				"FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME",
-				[database], connection,
-			);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_table_describe',
-	'Show columns, types, keys, and indexes for a table',
-	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
-	async ({ connection, database, table }) => {
-		try {
-			const { rows: cols } = await client.query(
-				`SHOW FULL COLUMNS FROM ${esc(database)}.${esc(table)}`,
-				[], connection,
-			);
-			const { rows: idxs } = await client.query(
-				`SHOW INDEX FROM ${esc(database)}.${esc(table)}`,
-				[], connection,
-			);
-			return { content: [{ type: 'text' as const, text: `Columns:\n${JSON.stringify(cols, null, 2)}\n\nIndexes:\n${JSON.stringify(idxs, null, 2)}` }] };
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_table_create',
-	'Execute a CREATE TABLE DDL statement. On a Joomla database this requires the two-step confirm_token.',
-	{ ...ConnectionParam, sql: z.string().describe('Full CREATE TABLE SQL statement'), ...JoomlaTokenParam },
-	async ({ connection, sql, confirm_token }) => {
-		const gate = await joomlaWriteGate(sql, connection, undefined, confirm_token);
-		if (!gate.ok) return { content: [{ type: 'text' as const, text: gate.text }] };
-		try {
-			const r = await client.execute(sql, [], connection);
-			return formatResult(r);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_table_drop',
-	'Drop a table — DESTRUCTIVE, requires confirm=true. On a Joomla database also requires the two-step confirm_token.',
-	{ ...ConnectionParam, ...DatabaseParam, ...TableParam, ...ConfirmParam, ...JoomlaTokenParam },
-	async ({ connection, database, table, confirm, confirm_token }) => {
-		if (!confirm) return { content: [{ type: 'text' as const, text: 'Aborted: confirm must be true.' }] };
-		const op = `DROP TABLE ${esc(database)}.${esc(table)}`;
-		const gate = await joomlaWriteGate(op, connection, database, confirm_token);
-		if (!gate.ok) return { content: [{ type: 'text' as const, text: gate.text }] };
-		try {
-			const r = await client.execute(op, [], connection);
-			return formatResult(r);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_table_truncate',
-	'Truncate a table (removes all rows, resets auto-increment) — DESTRUCTIVE, requires confirm=true. On a Joomla database also requires the two-step confirm_token.',
-	{ ...ConnectionParam, ...DatabaseParam, ...TableParam, ...ConfirmParam, ...JoomlaTokenParam },
-	async ({ connection, database, table, confirm, confirm_token }) => {
-		if (!confirm) return { content: [{ type: 'text' as const, text: 'Aborted: confirm must be true.' }] };
-		const op = `TRUNCATE TABLE ${esc(database)}.${esc(table)}`;
-		const gate = await joomlaWriteGate(op, connection, database, confirm_token);
-		if (!gate.ok) return { content: [{ type: 'text' as const, text: gate.text }] };
-		try {
-			const r = await client.execute(op, [], connection);
-			return formatResult(r);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_table_rename',
-	'Rename a table. On a Joomla database this requires the two-step confirm_token.',
-	{ ...ConnectionParam, ...DatabaseParam, from: z.string().describe('Current table name'), to: z.string().describe('New table name'), ...JoomlaTokenParam },
-	async ({ connection, database, from, to, confirm_token }) => {
-		const op = `RENAME TABLE ${esc(database)}.${esc(from)} TO ${esc(database)}.${esc(to)}`;
-		const gate = await joomlaWriteGate(op, connection, database, confirm_token);
-		if (!gate.ok) return { content: [{ type: 'text' as const, text: gate.text }] };
-		try {
-			const r = await client.execute(op, [], connection);
-			return formatResult(r);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-// ── Query Execution ─────────────────────────────────────────────────────
-
-server.tool(
-	'mysql_query_select',
-	'Execute a SELECT query and return results as JSON (auto-limited to prevent huge results)',
-	{ ...ConnectionParam, ...DatabaseParam, sql: z.string().describe('SELECT query to execute'), ...LimitParam },
-	async ({ connection, database, sql, limit }) => {
-		try {
-			if (!isReadStatement(sql)) {
-				return formatError(new Error('mysql_query_select only runs read-only statements (SELECT/SHOW/EXPLAIN/DESCRIBE). Use mysql_query_execute for writes.'));
-			}
-			const max = Math.min(limit ?? 500, 10000);
-			const hasLimit = /\bLIMIT\s+\d/i.test(sql);
-			const finalSql = hasLimit ? sql : `${sql} LIMIT ${max}`;
-			const { rows } = await client.query(finalSql, [], connection, database);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_query_execute',
-	'Execute INSERT, UPDATE, DELETE, or DDL — requires confirm=true. Writes to a Joomla database ' +
-	'additionally require the two-step confirm_token (first call returns a token and does NOT run; ' +
-	'repeat with the token to execute). Reads stay unrestricted.',
-	{ ...ConnectionParam, ...DatabaseParam, sql: z.string().describe('SQL statement to execute'), ...ConfirmParam, ...JoomlaTokenParam },
-	async ({ connection, database, sql, confirm, confirm_token }) => {
-		if (!confirm) return { content: [{ type: 'text' as const, text: 'Aborted: confirm must be true to execute write operations.' }] };
-		const gate = await joomlaWriteGate(sql, connection, database, confirm_token);
-		if (!gate.ok) return { content: [{ type: 'text' as const, text: gate.text }] };
-		try {
-			const r = await client.execute(sql, [], connection, database);
-			const result = formatResult(r);
-			// Surface a post-write integrity reminder for nested-set tables.
-			if (!isReadStatement(sql)) {
-				const j = await client.detectJoomla(connection, database);
-				const nested = j.isJoomla ? nestedSetTablesHit(sql, j.prefix) : [];
-				if (nested.length) {
-					result.content.unshift({
-						type: 'text' as const,
-						text: `⚠ Wrote to Joomla nested-set table(s): ${nested.join(', ')}. ` +
-							'Verify integrity (max(rgt) == 2 × node_count, no dup/overlapping lft/rgt) before relying on the data.\n',
-					});
-				}
-			}
-			return result;
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_query_explain',
-	'Run EXPLAIN on a query to show execution plan',
-	{ ...ConnectionParam, ...DatabaseParam, sql: z.string().describe('Query to explain') },
-	async ({ connection, database, sql }) => {
-		try {
-			if (!isReadStatement(sql)) {
-				return formatError(new Error('mysql_query_explain only explains read-only statements (SELECT/SHOW/EXPLAIN/DESCRIBE).'));
-			}
-			const { rows } = await client.query(`EXPLAIN ${sql}`, [], connection, database);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-// ── Schema Inspection ───────────────────────────────────────────────────
-
-server.tool(
-	'mysql_schema_show_create_table',
-	'Show the CREATE TABLE DDL for a table',
-	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
-	async ({ connection, database, table }) => {
-		try {
-			const { rows } = await client.query(
-				`SHOW CREATE TABLE ${esc(database)}.${esc(table)}`,
-				[], connection,
-			);
-			const ddl = (rows[0] as Record<string, unknown>)?.['Create Table'] ?? '';
-			return { content: [{ type: 'text' as const, text: String(ddl) }] };
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_schema_indexes',
-	'List all indexes on a table',
-	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
-	async ({ connection, database, table }) => {
-		try {
-			const { rows } = await client.query(
-				`SHOW INDEX FROM ${esc(database)}.${esc(table)}`,
-				[], connection,
-			);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_schema_foreign_keys',
-	'List all foreign key constraints on a table',
-	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
-	async ({ connection, database, table }) => {
-		try {
-			const { rows } = await client.query(
-				"SELECT CONSTRAINT_NAME, COLUMN_NAME, REFERENCED_TABLE_SCHEMA, " +
-				"REFERENCED_TABLE_NAME, REFERENCED_COLUMN_NAME " +
-				"FROM information_schema.KEY_COLUMN_USAGE " +
-				"WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? AND REFERENCED_TABLE_NAME IS NOT NULL",
-				[database, table], connection,
-			);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_schema_full',
-	'Export CREATE TABLE DDL for all tables in a database',
-	{ ...ConnectionParam, ...DatabaseParam },
-	async ({ connection, database }) => {
-		try {
-			const { rows: tables } = await client.query(
-				"SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME",
-				[database], connection,
-			);
-			const ddls: string[] = [];
-			for (const t of tables) {
-				const name = String((t as Record<string, unknown>).TABLE_NAME);
-				const { rows } = await client.query(`SHOW CREATE TABLE ${esc(database)}.${esc(name)}`, [], connection);
-				const ddl = String((rows[0] as Record<string, unknown>)?.['Create Table'] ?? '');
-				ddls.push(`-- Table: ${name}\n${ddl};\n`);
-			}
-			return { content: [{ type: 'text' as const, text: ddls.join('\n') }] };
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-// ── User Management ─────────────────────────────────────────────────────
-
-server.tool(
-	'mysql_users_list',
-	'List all MySQL users with host and authentication plugin',
-	{ ...ConnectionParam },
-	async ({ connection }) => {
-		try {
-			const { rows } = await client.query(
-				"SELECT User, Host, plugin, account_locked FROM mysql.user ORDER BY User, Host",
-				[], connection,
-			);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_user_grants',
-	'Show grants for a MySQL user',
-	{ ...ConnectionParam, user: z.string().describe('Username'), host: z.string().optional().describe('Host (default %)') },
-	async ({ connection, user, host }) => {
-		try {
-			const h = host ?? '%';
-			const { rows } = await client.query(`SHOW GRANTS FOR ?@?`, [user, h], connection);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_user_create',
-	'Create a MySQL user',
-	{ ...ConnectionParam, user: z.string(), host: z.string().optional().describe('Host (default localhost)'), password: z.string() },
-	async ({ connection, user, host, password }) => {
-		try {
-			const h = host ?? 'localhost';
-			const r = await client.execute(
-				`CREATE USER ${esc(user)}@${esc(h)} IDENTIFIED BY ?`,
-				[password], connection,
-			);
-			return formatResult(r);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_user_drop',
-	'Drop a MySQL user — DESTRUCTIVE, requires confirm=true',
-	{ ...ConnectionParam, user: z.string(), host: z.string().optional(), ...ConfirmParam },
-	async ({ connection, user, host, confirm }) => {
-		if (!confirm) return { content: [{ type: 'text' as const, text: 'Aborted: confirm must be true.' }] };
-		try {
-			const h = host ?? '%';
-			const r = await client.execute(`DROP USER ${esc(user)}@${esc(h)}`, [], connection);
-			return formatResult(r);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_user_grant',
-	'Grant privileges to a user on a database',
-	{ ...ConnectionParam, user: z.string(), host: z.string().optional(), privileges: z.string().describe('e.g. "SELECT, INSERT" or "ALL PRIVILEGES"'), database: z.string(), table: z.string().optional().describe('Table name (default * for all)') },
-	async ({ connection, user, host, privileges, database, table }) => {
-		try {
-			const safePrivileges = validatePrivileges(privileges);
-			const h = host ?? '%';
-			const t = table ?? '*';
-			const r = await client.execute(
-				`GRANT ${safePrivileges} ON ${esc(database)}.${t === '*' ? '*' : esc(t)} TO ${esc(user)}@${esc(h)}`,
-				[], connection,
-			);
-			await client.execute('FLUSH PRIVILEGES', [], connection);
-			return formatResult(r);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_user_revoke',
-	'Revoke privileges from a user',
-	{ ...ConnectionParam, user: z.string(), host: z.string().optional(), privileges: z.string(), database: z.string(), table: z.string().optional() },
-	async ({ connection, user, host, privileges, database, table }) => {
-		try {
-			const safePrivileges = validatePrivileges(privileges);
-			const h = host ?? '%';
-			const t = table ?? '*';
-			const r = await client.execute(
-				`REVOKE ${safePrivileges} ON ${esc(database)}.${t === '*' ? '*' : esc(t)} FROM ${esc(user)}@${esc(h)}`,
-				[], connection,
-			);
-			await client.execute('FLUSH PRIVILEGES', [], connection);
-			return formatResult(r);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-// ── Maintenance ─────────────────────────────────────────────────────────
-
-server.tool(
-	'mysql_maintenance_optimize',
-	'Run OPTIMIZE TABLE to reclaim space and defragment',
-	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
-	async ({ connection, database, table }) => {
-		try {
-			const { rows } = await client.query(`OPTIMIZE TABLE ${esc(database)}.${esc(table)}`, [], connection);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_maintenance_analyze',
-	'Run ANALYZE TABLE to update index statistics',
-	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
-	async ({ connection, database, table }) => {
-		try {
-			const { rows } = await client.query(`ANALYZE TABLE ${esc(database)}.${esc(table)}`, [], connection);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_maintenance_check',
-	'Run CHECK TABLE to verify table integrity',
-	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
-	async ({ connection, database, table }) => {
-		try {
-			const { rows } = await client.query(`CHECK TABLE ${esc(database)}.${esc(table)}`, [], connection);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_processlist',
-	'Show running MySQL processes',
-	{ ...ConnectionParam },
-	async ({ connection }) => {
-		try {
-			const { rows } = await client.query('SHOW FULL PROCESSLIST', [], connection);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_process_kill',
-	'Kill a MySQL process by ID — requires confirm=true',
-	{ ...ConnectionParam, process_id: z.number().describe('Process ID to kill'), ...ConfirmParam },
-	async ({ connection, process_id, confirm }) => {
-		if (!confirm) return { content: [{ type: 'text' as const, text: 'Aborted: confirm must be true.' }] };
-		try {
-			const r = await client.execute(`KILL ${Number(process_id)}`, [], connection);
-			return formatResult(r);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-// ── Export ───────────────────────────────────────────────────────────────
-
-server.tool(
-	'mysql_export_table_sql',
-	'Export table structure and data as SQL INSERT statements (no shell exec)',
-	{ ...ConnectionParam, ...DatabaseParam, ...TableParam, include_data: z.boolean().optional().describe('Include INSERT statements (default true)'), row_limit: z.number().optional().describe('Max rows for data export (default 1000)') },
-	async ({ connection, database, table, include_data, row_limit }) => {
-		try {
-			const { rows: ddlRows } = await client.query(`SHOW CREATE TABLE ${esc(database)}.${esc(table)}`, [], connection);
-			const ddl = String((ddlRows[0] as Record<string, unknown>)?.['Create Table'] ?? '');
-			const parts: string[] = [`-- Export of ${database}.${table}`, `DROP TABLE IF EXISTS ${esc(table)};`, ddl + ';', ''];
-
-			if (include_data !== false) {
-				const max = Math.min(row_limit ?? 1000, 10000);
-				const { rows, fields } = await client.query(
-					`SELECT * FROM ${esc(database)}.${esc(table)} LIMIT ${max}`,
-					[], connection,
-				);
-				const colNames = fields.map(f => esc(String(f.name))).join(', ');
-				for (const row of rows) {
-					const vals = fields.map(f => {
-						const v = (row as Record<string, unknown>)[String(f.name)];
-						if (v === null) return 'NULL';
-						if (typeof v === 'number') return String(v);
-						return "'" + String(v).replace(/'/g, "''") + "'";
-					}).join(', ');
-					parts.push(`INSERT INTO ${esc(table)} (${colNames}) VALUES (${vals});`);
-				}
-			}
-			return { content: [{ type: 'text' as const, text: parts.join('\n') }] };
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_export_query_csv',
-	'Execute a SELECT and return results as CSV',
-	{ ...ConnectionParam, ...DatabaseParam, sql: z.string().describe('SELECT query'), ...LimitParam },
-	async ({ connection, database, sql, limit }) => {
-		try {
-			const max = Math.min(limit ?? 500, 10000);
-			const hasLimit = /\bLIMIT\s+\d/i.test(sql);
-			const finalSql = hasLimit ? sql : `${sql} LIMIT ${max}`;
-			const { rows, fields } = await client.query(finalSql, [], connection);
-
-			const header = fields.map(f => String(f.name)).join(',');
-			const lines = rows.map(row =>
-				fields.map(f => {
-					const v = (row as Record<string, unknown>)[String(f.name)];
-					if (v === null) return '';
-					const s = String(v);
-					return s.includes(',') || s.includes('"') || s.includes('\n')
-						? '"' + s.replace(/"/g, '""') + '"'
-						: s;
-				}).join(','),
-			);
-			return { content: [{ type: 'text' as const, text: [header, ...lines].join('\n') }] };
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-// ── Joomla Helpers ──────────────────────────────────────────────────────
-
-const JoomlaParams = {
-	table_prefix: z.string().optional().describe('Joomla table prefix (default "jos_")'),
-};
-
-server.tool(
-	'mysql_joomla_extensions',
-	'List installed Joomla extensions from #__extensions',
-	{ ...ConnectionParam, ...DatabaseParam, ...JoomlaParams, type: z.string().optional().describe('Filter by type: component, module, plugin, template, library, package') },
-	async ({ connection, database, table_prefix, type }) => {
-		try {
-			const pfx = table_prefix ?? 'jos_';
-			let sql = `SELECT extension_id, name, type, element, folder, enabled, access, protected, manifest_cache FROM ${esc(database)}.${esc(pfx + 'extensions')}`;
-			const params: string[] = [];
-			if (type) {
-				sql += ' WHERE type = ?';
-				params.push(type);
-			}
-			sql += ' ORDER BY type, name';
-			const { rows } = await client.query(sql, params, connection);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_joomla_users',
-	'List Joomla users with username, email, last visit, and block status',
-	{ ...ConnectionParam, ...DatabaseParam, ...JoomlaParams, ...LimitParam },
-	async ({ connection, database, table_prefix, limit }) => {
-		try {
-			const pfx = table_prefix ?? 'jos_';
-			const max = Math.min(limit ?? 100, 1000);
-			const { rows } = await client.query(
-				`SELECT id, name, username, email, block, lastvisitDate, registerDate FROM ${esc(database)}.${esc(pfx + 'users')} ORDER BY id LIMIT ${max}`,
-				[], connection,
-			);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_joomla_articles',
-	'List Joomla articles from #__content',
-	{ ...ConnectionParam, ...DatabaseParam, ...JoomlaParams, state: z.number().optional().describe('Filter: 1=published, 0=unpublished, -1=archived, -2=trashed'), ...LimitParam },
-	async ({ connection, database, table_prefix, state, limit }) => {
-		try {
-			const pfx = table_prefix ?? 'jos_';
-			const max = Math.min(limit ?? 100, 1000);
-			let sql = `SELECT id, title, alias, state, catid, created, modified, publish_up, publish_down, hits FROM ${esc(database)}.${esc(pfx + 'content')}`;
-			const params: unknown[] = [];
-			if (state !== undefined) {
-				sql += ' WHERE state = ?';
-				params.push(state);
-			}
-			sql += ` ORDER BY id DESC LIMIT ${max}`;
-			const { rows } = await client.query(sql, params, connection);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_joomla_sessions',
-	'Count active Joomla sessions and show session stats',
-	{ ...ConnectionParam, ...DatabaseParam, ...JoomlaParams },
-	async ({ connection, database, table_prefix }) => {
-		try {
-			const pfx = table_prefix ?? 'jos_';
-			const { rows } = await client.query(
-				`SELECT COUNT(*) AS total_sessions, ` +
-				`SUM(CASE WHEN guest = 1 THEN 1 ELSE 0 END) AS guest_sessions, ` +
-				`SUM(CASE WHEN guest = 0 THEN 1 ELSE 0 END) AS user_sessions, ` +
-				`MIN(time) AS oldest_session, MAX(time) AS newest_session ` +
-				`FROM ${esc(database)}.${esc(pfx + 'session')}`,
-				[], connection,
-			);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-server.tool(
-	'mysql_joomla_config',
-	'Read Joomla global configuration values from the extensions table params',
-	{ ...ConnectionParam, ...DatabaseParam, ...JoomlaParams },
-	async ({ connection, database, table_prefix }) => {
-		try {
-			const pfx = table_prefix ?? 'jos_';
-			const { rows } = await client.query(
-				`SELECT extension_id, name, params FROM ${esc(database)}.${esc(pfx + 'extensions')} WHERE type = 'component' AND element = 'com_config' LIMIT 1`,
-				[], connection,
-			);
-			return formatRows(rows);
-		} catch (e) {
-			return formatError(e);
-		}
-	},
-);
-
-// ── Bootstrap ───────────────────────────────────────────────────────────
-
-async function main() {
-	try {
-		config = await loadConfig();
-		client = new MysqlClient(config);
-	} catch (err) {
-		process.stderr.write(`${err}\n`);
-		process.exit(1);
-	}
-
-	const cleanup = async () => {
-		await client.closeAll();
-		process.exit(0);
-	};
-	process.on('SIGINT', cleanup);
-	process.on('SIGTERM', cleanup);
-
-	const transport = new StdioServerTransport();
-	await server.connect(transport);
-}
-
-main().catch((err) => {
-	process.stderr.write(`Fatal: ${err}\n`);
-	process.exit(1);
-});
+#!/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: mokomysql.Server
+ * INGROUP: mokomysql
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
+ * PATH: /src/index.ts
+ * VERSION: 01.00.00
+ * BRIEF: MCP server entry point — registers all MySQL management tools
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createHash, randomBytes } from 'node:crypto';
+import { z } from 'zod';
+import { loadConfig } from './config.js';
+import { MysqlClient } from './client.js';
+import type { MySqlConfig } from './types.js';
+
+export let config: MySqlConfig;
+export let client: MysqlClient;
+
+function formatRows(rows: Record<string, unknown>[]): { content: Array<{ type: 'text'; text: string }> } {
+	const text = rows.length === 0
+		? 'No rows returned.'
+		: JSON.stringify(rows, null, 2);
+	return { content: [{ type: 'text' as const, text: `${rows.length} row(s)\n${text}` }] };
+}
+
+function formatResult(r: { affectedRows: number; insertId: number; changedRows: number }): { content: Array<{ type: 'text'; text: string }> } {
+	return { content: [{ type: 'text' as const, text: `Affected rows: ${r.affectedRows} | Insert ID: ${r.insertId} | Changed rows: ${r.changedRows}` }] };
+}
+
+function formatError(err: unknown): { content: Array<{ type: 'text'; text: string }> } {
+	const e = err as { code?: string; message?: string };
+	const code = e.code ? ` [${e.code}]` : '';
+	const msg = e.message ?? String(err);
+	return { content: [{ type: 'text' as const, text: `MySQL Error${code}: ${msg}` }] };
+}
+
+function esc(identifier: string): string {
+	return '`' + identifier.replace(/`/g, '``') + '`';
+}
+
+/**
+ * Classify a statement as a read. Only SELECT/SHOW/EXPLAIN/DESCRIBE are treated
+ * as reads (they stay unrestricted on Joomla DBs); everything else — including
+ * `WITH`, `SET`, and all DML/DDL — is conservatively treated as a write so the
+ * double-confirm gate errs toward safety. Leading comments/whitespace are stripped.
+ */
+function isReadStatement(sql: string): boolean {
+	const stripped = sql
+		.replace(/\/\*[\s\S]*?\*\//g, ' ')       // /* block comments */
+		.replace(/^\s*(--|#)[^\n]*$/gm, ' ')      // -- and # line comments
+		.trim();
+	return /^(SELECT|SHOW|EXPLAIN|DESCRIBE|DESC)\b/i.test(stripped);
+}
+
+/**
+ * Classify a write statement by its leading keyword, so the gate can tell apart the
+ * operations that actually mutate Joomla's structural invariants from those that don't.
+ *
+ * The asset/nested-set coupling lives in the Joomla Table API, which raw SQL bypasses
+ * (verified against joomla-cms 5.2.3): `Table::store()` creates/updates a `#__assets`
+ * row and only renumbers the nested set when a node is NEW or MOVED (Table.php:913-916;
+ * Nested.php:696,720); `Table::delete()` removes the asset row before the entity row
+ * (Table.php:1053-1065). A raw in-place `UPDATE` never enters `store()`, so it cannot
+ * create, delete, or renumber an asset / nested-set row. A raw `INSERT`/`DELETE` of an
+ * asset-bearing entity (any table with an `asset_id` column — Table.php:208-209), by
+ * contrast, desynchronizes `#__assets` (no paired asset row, or an orphaned one). DDL
+ * and anything unrecognized are treated as structurally hazardous, conservatively.
+ */
+type WriteOp = 'INSERT' | 'UPDATE' | 'DELETE' | 'DDL' | 'OTHER';
+function classifyWrite(sql: string): WriteOp {
+	const s = sql
+		.replace(/\/\*[\s\S]*?\*\//g, ' ')       // /* block comments */
+		.replace(/^\s*(--|#)[^\n]*$/gm, ' ')      // -- and # line comments
+		.trim();
+	if (/^(INSERT|REPLACE)\b/i.test(s)) return 'INSERT';
+	if (/^UPDATE\b/i.test(s)) return 'UPDATE';
+	if (/^DELETE\b/i.test(s)) return 'DELETE';
+	if (/^(CREATE|ALTER|DROP|TRUNCATE|RENAME)\b/i.test(s)) return 'DDL';
+	return 'OTHER';
+}
+
+/**
+ * Known MySQL privilege identifiers accepted by GRANT/REVOKE. Compared
+ * case-insensitively against each comma-separated token supplied by the caller
+ * so an arbitrary string can never be interpolated raw into a GRANT statement.
+ */
+const ALLOWED_PRIVILEGES = new Set([
+	'SELECT', 'INSERT', 'UPDATE', 'DELETE', 'CREATE', 'DROP', 'RELOAD',
+	'SHUTDOWN', 'PROCESS', 'FILE', 'REFERENCES', 'INDEX', 'ALTER',
+	'SHOW DATABASES', 'SUPER', 'CREATE TEMPORARY TABLES', 'LOCK TABLES',
+	'EXECUTE', 'REPLICATION SLAVE', 'REPLICATION CLIENT', 'CREATE VIEW',
+	'SHOW VIEW', 'CREATE ROUTINE', 'ALTER ROUTINE', 'CREATE USER', 'EVENT',
+	'TRIGGER', 'GRANT OPTION', 'ALL', 'ALL PRIVILEGES', 'USAGE',
+]);
+
+/**
+ * Validate a comma-separated `privileges` string against ALLOWED_PRIVILEGES.
+ * Rejects parentheses (column-level grants) and any unknown token so nothing
+ * unvetted reaches the raw GRANT/REVOKE statement. Returns the normalized,
+ * uppercased, re-joined privilege list safe for interpolation.
+ */
+function validatePrivileges(privileges: string): string {
+	if (/[()]/.test(privileges)) {
+		throw new Error('Column-level privileges (parentheses) are not supported. Supply plain privilege names only.');
+	}
+	const tokens = privileges.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
+	if (tokens.length === 0) {
+		throw new Error('No privileges supplied.');
+	}
+	const normalized: string[] = [];
+	for (const tok of tokens) {
+		const upper = tok.toUpperCase().replace(/\s+/g, ' ');
+		if (!ALLOWED_PRIVILEGES.has(upper)) {
+			throw new Error(`Rejected unknown or unsafe privilege: "${tok}". Allowed: ${[...ALLOWED_PRIVILEGES].join(', ')}.`);
+		}
+		normalized.push(upper);
+	}
+	return normalized.join(', ');
+}
+
+/** Joomla nested-set tables — raw lft/rgt writes here are the hazardous ones. */
+const NESTED_SET_SUFFIXES = ['assets', 'categories', 'menu'] as const;
+
+/**
+ * Find Joomla nested-set tables referenced by a statement. With a known prefix
+ * the match is precise (`<prefix>assets`); without one it falls back to matching
+ * the bare table names as whole identifiers, which may over-warn but never
+ * silently misses a hazardous target.
+ */
+function nestedSetTablesHit(sql: string, prefix: string | null): string[] {
+	const names = NESTED_SET_SUFFIXES.map((s) => (prefix !== null ? `${prefix}${s}` : s));
+	const hits: string[] = [];
+	for (const name of names) {
+		// Match the identifier with optional backtick quoting, on word boundaries.
+		const re = new RegExp('(^|[^a-z0-9_`])`?' + name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '`?([^a-z0-9_`]|$)', 'i');
+		if (re.test(sql)) hits.push(name);
+	}
+	return hits;
+}
+
+const ConnectionParam = {
+	connection: z.string().optional().describe('Named connection from config (uses default if omitted)'),
+};
+
+const DatabaseParam = {
+	database: z.string().describe('Database name'),
+};
+
+const TableParam = {
+	table: z.string().describe('Table name'),
+};
+
+const ConfirmParam = {
+	confirm: z.boolean().describe('Must be true to execute this destructive operation'),
+};
+
+const JoomlaTokenParam = {
+	confirm_token: z.string().optional().describe(
+		'Second-step acknowledgement token for a write to a Joomla database. Leave empty on the ' +
+		'first call: the write is NOT executed and a token bound to this exact statement+target is ' +
+		'returned. Repeat the SAME call with that token to actually run it. Reads are never gated; ' +
+		'non-Joomla databases ignore this and run on confirm alone.',
+	),
+};
+
+// ── Joomla write gate: mandatory two-step challenge/acknowledge ──────────
+//
+// Writes to a Joomla DB must never execute from a single call (an interrupted or
+// careless raw write silently corrupts the nested-set tables — see issue #39). The
+// first call issues a one-time token bound to the exact statement+target and does
+// NOT run; only a second call echoing that token proceeds.
+//
+// The gate is operation-aware (issue #65): the two-step token is required for EVERY
+// Joomla write, but the nested-set/ACL-corruption warning is reserved for the writes
+// that can actually cause it — INSERT/DELETE of asset-bearing rows, DDL, and any write
+// to a nested-set table. A pure in-place UPDATE that avoids the nested-set tables gets
+// a lighter message, because that coupling lives in the Joomla Table API (store()/
+// delete()), which raw SQL bypasses entirely.
+
+interface PendingWrite {
+	/** Binds the token to a specific normalized op + connection + schema. */
+	bindHash: string;
+	/** Epoch ms when issued, for TTL expiry. */
+	issuedAt: number;
+}
+
+const TOKEN_TTL_MS = 5 * 60 * 1000;
+const pendingWrites = new Map<string, PendingWrite>();
+
+function bindHashFor(op: string, connKey: string, schema: string): string {
+	const normalized = op.trim().replace(/\s+/g, ' ');
+	// JSON framing keeps the three parts unambiguously separated (no delimiter can
+	// bleed across fields) while staying printable text.
+	return createHash('sha256').update(JSON.stringify([connKey, schema, normalized])).digest('hex');
+}
+
+type GateResult = { ok: true } | { ok: false; text: string };
+
+/**
+ * Enforce the two-step gate for a write `op` (raw SQL, or a synthetic descriptor
+ * like `DROP TABLE db.table` for the structured tools). Reads and non-Joomla
+ * targets pass straight through. On a Joomla write: a valid matching token runs it
+ * (and is consumed); anything else returns a fresh challenge and does NOT execute.
+ */
+async function joomlaWriteGate(
+	op: string,
+	connection: string | undefined,
+	database: string | undefined,
+	confirmToken: string | undefined,
+): Promise<GateResult> {
+	if (isReadStatement(op)) return { ok: true };
+	const j = await client.detectJoomla(connection, database);
+	if (!j.isJoomla) return { ok: true };
+
+	const { connKey, schema } = client.resolveIdentity(connection, database);
+	const bindHash = bindHashFor(op, connKey, schema);
+	const now = Date.now();
+
+	if (confirmToken) {
+		const pending = pendingWrites.get(confirmToken);
+		if (pending && pending.bindHash === bindHash && now - pending.issuedAt <= TOKEN_TTL_MS) {
+			pendingWrites.delete(confirmToken); // one-time use
+			return { ok: true };
+		}
+		// Mismatched / expired / unknown token → fall through and re-challenge.
+	}
+
+	const token = randomBytes(9).toString('hex');
+	pendingWrites.set(token, { bindHash, issuedAt: now });
+	const nested = nestedSetTablesHit(op, j.prefix);
+	const writeOp = classifyWrite(op);
+	// A pure in-place UPDATE that does not reference a nested-set table cannot create,
+	// delete, or renumber an #__assets / nested-set row (that coupling lives in the Joomla
+	// Table API, which raw SQL bypasses — see classifyWrite). Such statements still get the
+	// two-step gate (an interrupted or mis-scoped raw write can corrupt row data), but NOT
+	// the misleading nested-set/ACL-corruption framing. Everything else — INSERT/DELETE,
+	// DDL, anything unrecognized, and any write to a nested-set table — keeps it.
+	const inPlaceUpdate = writeOp === 'UPDATE' && nested.length === 0;
+	const lines = [
+		'⛔ WRITE to a Joomla database — a second confirmation is REQUIRED. This call did NOT execute.',
+		'',
+	];
+	if (inPlaceUpdate) {
+		lines.push(
+			'This is an in-place UPDATE that does not touch a nested-set table (assets / categories / menu),',
+			'so it will NOT create, remove, or renumber ACL asset rows or nested sets — Joomla only mutates',
+			'those on row creation/deletion, which raw SQL bypasses. The two-step confirm still applies because',
+			'an interrupted or mis-scoped raw write can corrupt row data. To proceed, repeat the SAME call adding:',
+			`    confirm_token: "${token}"`,
+			'(one-time, valid ~5 min, bound to this exact statement + target).',
+		);
+	} else {
+		lines.push(
+			'Joomla tables carry structural invariants (nested sets, ACL) that raw SQL can corrupt, and an',
+			'interrupted write can leave the database broken. To proceed, repeat the SAME call adding:',
+			`    confirm_token: "${token}"`,
+			'(one-time, valid ~5 min, bound to this exact statement + target).',
+		);
+	}
+	if (nested.length) {
+		lines.push(
+			'',
+			`⚠ Targets nested-set table(s): ${nested.join(', ')}.`,
+			'Strongly prefer the Joomla Web Services API / CLI, which maintains lft/rgt automatically.',
+			'If you must write raw, complete the whole operation in one go, then verify integrity:',
+			'max(rgt) == 2 × node_count, no duplicate lft/rgt, no lft >= rgt, children within parent bounds.',
+		);
+	} else if (writeOp === 'INSERT' || writeOp === 'DELETE') {
+		lines.push(
+			'',
+			`⚠ Raw ${writeOp} of a row. If the target is asset-bearing (any table with an asset_id column —`,
+			'articles, categories, modules, contacts, banners, newsfeeds, fields, tags, …), Joomla pairs each',
+			'row with a #__assets ACL row via Table::store()/delete(). Raw SQL bypasses that: an INSERT leaves',
+			'the new row with no asset row (broken ACL), a DELETE orphans the asset row. Strongly prefer the',
+			'Joomla Web Services API / CLI, which maintains the asset tree automatically.',
+		);
+	}
+	return { ok: false, text: lines.join('\n') };
+}
+
+const LimitParam = {
+	limit: z.number().optional().describe('Max rows to return (default 500, max 10000)'),
+};
+
+const server = new McpServer({
+	name: '@mokoconsulting/mokomysql-mcp',
+	version: '1.0.0',
+});
+
+// ── Connection & Server Info ────────────────────────────────────────────
+
+server.tool(
+	'mysql_connections_list',
+	'List all configured MySQL connection names with host/port/user (no passwords)',
+	{ ...ConnectionParam },
+	async () => {
+		const entries = Object.entries(config.connections).map(([name, c]) => ({
+			name,
+			host: c.host,
+			port: c.port ?? 3306,
+			user: c.user,
+			database: c.database ?? '(none)',
+			default: name === config.defaultConnection,
+		}));
+		return formatRows(entries);
+	},
+);
+
+server.tool(
+	'mysql_server_version',
+	'Get MySQL server version and uptime',
+	{ ...ConnectionParam },
+	async ({ connection }) => {
+		try {
+			const { rows } = await client.query(
+				"SELECT VERSION() AS version, @@hostname AS hostname, @@port AS port, " +
+				"VARIABLE_VALUE AS uptime FROM performance_schema.global_status WHERE VARIABLE_NAME = 'Uptime'",
+				[], connection,
+			);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_server_status',
+	'Show MySQL server status variables (SHOW GLOBAL STATUS)',
+	{ ...ConnectionParam, filter: z.string().optional().describe('LIKE pattern to filter (e.g. "Threads%")') },
+	async ({ connection, filter }) => {
+		try {
+			const sql = filter ? `SHOW GLOBAL STATUS LIKE ?` : 'SHOW GLOBAL STATUS';
+			const params = filter ? [filter] : [];
+			const { rows } = await client.query(sql, params, connection);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_server_variables',
+	'Show MySQL system variables (SHOW GLOBAL VARIABLES)',
+	{ ...ConnectionParam, filter: z.string().optional().describe('LIKE pattern to filter (e.g. "innodb%")') },
+	async ({ connection, filter }) => {
+		try {
+			const sql = filter ? `SHOW GLOBAL VARIABLES LIKE ?` : 'SHOW GLOBAL VARIABLES';
+			const params = filter ? [filter] : [];
+			const { rows } = await client.query(sql, params, connection);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+// ── Database Management ─────────────────────────────────────────────────
+
+server.tool(
+	'mysql_databases_list',
+	'List all databases with sizes',
+	{ ...ConnectionParam },
+	async ({ connection }) => {
+		try {
+			const { rows } = await client.query(
+				"SELECT s.SCHEMA_NAME AS `database`, " +
+				"ROUND(SUM(t.DATA_LENGTH + t.INDEX_LENGTH) / 1024 / 1024, 2) AS size_mb, " +
+				"COUNT(t.TABLE_NAME) AS tables_count, " +
+				"s.DEFAULT_CHARACTER_SET_NAME AS charset, " +
+				"s.DEFAULT_COLLATION_NAME AS collation " +
+				"FROM information_schema.SCHEMATA s " +
+				"LEFT JOIN information_schema.TABLES t ON s.SCHEMA_NAME = t.TABLE_SCHEMA " +
+				"GROUP BY s.SCHEMA_NAME ORDER BY size_mb DESC",
+				[], connection,
+			);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_database_create',
+	'Create a new database',
+	{ ...ConnectionParam, ...DatabaseParam, charset: z.string().optional().describe('Character set (default utf8mb4)'), collation: z.string().optional().describe('Collation (default utf8mb4_unicode_ci)') },
+	async ({ connection, database, charset, collation }) => {
+		try {
+			const cs = charset ?? 'utf8mb4';
+			const co = collation ?? 'utf8mb4_unicode_ci';
+			const r = await client.execute(
+				`CREATE DATABASE ${esc(database)} CHARACTER SET ${esc(cs)} COLLATE ${esc(co)}`,
+				[], connection,
+			);
+			return formatResult(r);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_database_drop',
+	'Drop a database — DESTRUCTIVE, requires confirm=true. If the database is Joomla, also requires the two-step confirm_token.',
+	{ ...ConnectionParam, ...DatabaseParam, ...ConfirmParam, ...JoomlaTokenParam },
+	async ({ connection, database, confirm, confirm_token }) => {
+		if (!confirm) return { content: [{ type: 'text' as const, text: 'Aborted: confirm must be true to drop a database.' }] };
+		const op = `DROP DATABASE ${esc(database)}`;
+		const gate = await joomlaWriteGate(op, connection, database, confirm_token);
+		if (!gate.ok) return { content: [{ type: 'text' as const, text: gate.text }] };
+		try {
+			const r = await client.execute(op, [], connection);
+			return formatResult(r);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_database_size',
+	'Show database size breakdown by table',
+	{ ...ConnectionParam, ...DatabaseParam },
+	async ({ connection, database }) => {
+		try {
+			const { rows } = await client.query(
+				"SELECT TABLE_NAME AS `table`, TABLE_ROWS AS rows_estimate, " +
+				"ROUND(DATA_LENGTH / 1024 / 1024, 2) AS data_mb, " +
+				"ROUND(INDEX_LENGTH / 1024 / 1024, 2) AS index_mb, " +
+				"ROUND((DATA_LENGTH + INDEX_LENGTH) / 1024 / 1024, 2) AS total_mb, " +
+				"ENGINE AS engine " +
+				"FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? ORDER BY total_mb DESC",
+				[database], connection,
+			);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+// ── Table Management ────────────────────────────────────────────────────
+
+server.tool(
+	'mysql_tables_list',
+	'List all tables in a database with engine, row count estimate, and size',
+	{ ...ConnectionParam, ...DatabaseParam },
+	async ({ connection, database }) => {
+		try {
+			const { rows } = await client.query(
+				"SELECT TABLE_NAME AS `table`, ENGINE AS engine, TABLE_ROWS AS rows_estimate, " +
+				"ROUND((DATA_LENGTH + INDEX_LENGTH) / 1024, 2) AS size_kb, " +
+				"TABLE_COLLATION AS collation, AUTO_INCREMENT AS auto_increment " +
+				"FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME",
+				[database], connection,
+			);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_table_describe',
+	'Show columns, types, keys, and indexes for a table',
+	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
+	async ({ connection, database, table }) => {
+		try {
+			const { rows: cols } = await client.query(
+				`SHOW FULL COLUMNS FROM ${esc(database)}.${esc(table)}`,
+				[], connection,
+			);
+			const { rows: idxs } = await client.query(
+				`SHOW INDEX FROM ${esc(database)}.${esc(table)}`,
+				[], connection,
+			);
+			return { content: [{ type: 'text' as const, text: `Columns:\n${JSON.stringify(cols, null, 2)}\n\nIndexes:\n${JSON.stringify(idxs, null, 2)}` }] };
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_table_create',
+	'Execute a CREATE TABLE DDL statement. On a Joomla database this requires the two-step confirm_token.',
+	{ ...ConnectionParam, sql: z.string().describe('Full CREATE TABLE SQL statement'), ...JoomlaTokenParam },
+	async ({ connection, sql, confirm_token }) => {
+		const gate = await joomlaWriteGate(sql, connection, undefined, confirm_token);
+		if (!gate.ok) return { content: [{ type: 'text' as const, text: gate.text }] };
+		try {
+			const r = await client.execute(sql, [], connection);
+			return formatResult(r);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_table_drop',
+	'Drop a table — DESTRUCTIVE, requires confirm=true. On a Joomla database also requires the two-step confirm_token.',
+	{ ...ConnectionParam, ...DatabaseParam, ...TableParam, ...ConfirmParam, ...JoomlaTokenParam },
+	async ({ connection, database, table, confirm, confirm_token }) => {
+		if (!confirm) return { content: [{ type: 'text' as const, text: 'Aborted: confirm must be true.' }] };
+		const op = `DROP TABLE ${esc(database)}.${esc(table)}`;
+		const gate = await joomlaWriteGate(op, connection, database, confirm_token);
+		if (!gate.ok) return { content: [{ type: 'text' as const, text: gate.text }] };
+		try {
+			const r = await client.execute(op, [], connection);
+			return formatResult(r);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_table_truncate',
+	'Truncate a table (removes all rows, resets auto-increment) — DESTRUCTIVE, requires confirm=true. On a Joomla database also requires the two-step confirm_token.',
+	{ ...ConnectionParam, ...DatabaseParam, ...TableParam, ...ConfirmParam, ...JoomlaTokenParam },
+	async ({ connection, database, table, confirm, confirm_token }) => {
+		if (!confirm) return { content: [{ type: 'text' as const, text: 'Aborted: confirm must be true.' }] };
+		const op = `TRUNCATE TABLE ${esc(database)}.${esc(table)}`;
+		const gate = await joomlaWriteGate(op, connection, database, confirm_token);
+		if (!gate.ok) return { content: [{ type: 'text' as const, text: gate.text }] };
+		try {
+			const r = await client.execute(op, [], connection);
+			return formatResult(r);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_table_rename',
+	'Rename a table. On a Joomla database this requires the two-step confirm_token.',
+	{ ...ConnectionParam, ...DatabaseParam, from: z.string().describe('Current table name'), to: z.string().describe('New table name'), ...JoomlaTokenParam },
+	async ({ connection, database, from, to, confirm_token }) => {
+		const op = `RENAME TABLE ${esc(database)}.${esc(from)} TO ${esc(database)}.${esc(to)}`;
+		const gate = await joomlaWriteGate(op, connection, database, confirm_token);
+		if (!gate.ok) return { content: [{ type: 'text' as const, text: gate.text }] };
+		try {
+			const r = await client.execute(op, [], connection);
+			return formatResult(r);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+// ── Query Execution ─────────────────────────────────────────────────────
+
+server.tool(
+	'mysql_query_select',
+	'Execute a SELECT query and return results as JSON (auto-limited to prevent huge results)',
+	{ ...ConnectionParam, ...DatabaseParam, sql: z.string().describe('SELECT query to execute'), ...LimitParam },
+	async ({ connection, database, sql, limit }) => {
+		try {
+			if (!isReadStatement(sql)) {
+				return formatError(new Error('mysql_query_select only runs read-only statements (SELECT/SHOW/EXPLAIN/DESCRIBE). Use mysql_query_execute for writes.'));
+			}
+			const max = Math.min(limit ?? 500, 10000);
+			const hasLimit = /\bLIMIT\s+\d/i.test(sql);
+			const finalSql = hasLimit ? sql : `${sql} LIMIT ${max}`;
+			const { rows } = await client.query(finalSql, [], connection, database);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_query_execute',
+	'Execute INSERT, UPDATE, DELETE, or DDL — requires confirm=true. Writes to a Joomla database ' +
+	'additionally require the two-step confirm_token (first call returns a token and does NOT run; ' +
+	'repeat with the token to execute). Reads stay unrestricted.',
+	{ ...ConnectionParam, ...DatabaseParam, sql: z.string().describe('SQL statement to execute'), ...ConfirmParam, ...JoomlaTokenParam },
+	async ({ connection, database, sql, confirm, confirm_token }) => {
+		if (!confirm) return { content: [{ type: 'text' as const, text: 'Aborted: confirm must be true to execute write operations.' }] };
+		const gate = await joomlaWriteGate(sql, connection, database, confirm_token);
+		if (!gate.ok) return { content: [{ type: 'text' as const, text: gate.text }] };
+		try {
+			const r = await client.execute(sql, [], connection, database);
+			const result = formatResult(r);
+			// Surface a post-write integrity reminder for nested-set tables.
+			if (!isReadStatement(sql)) {
+				const j = await client.detectJoomla(connection, database);
+				const nested = j.isJoomla ? nestedSetTablesHit(sql, j.prefix) : [];
+				if (nested.length) {
+					result.content.unshift({
+						type: 'text' as const,
+						text: `⚠ Wrote to Joomla nested-set table(s): ${nested.join(', ')}. ` +
+							'Verify integrity (max(rgt) == 2 × node_count, no dup/overlapping lft/rgt) before relying on the data.\n',
+					});
+				}
+			}
+			return result;
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_query_explain',
+	'Run EXPLAIN on a query to show execution plan',
+	{ ...ConnectionParam, ...DatabaseParam, sql: z.string().describe('Query to explain') },
+	async ({ connection, database, sql }) => {
+		try {
+			if (!isReadStatement(sql)) {
+				return formatError(new Error('mysql_query_explain only explains read-only statements (SELECT/SHOW/EXPLAIN/DESCRIBE).'));
+			}
+			const { rows } = await client.query(`EXPLAIN ${sql}`, [], connection, database);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+// ── Schema Inspection ───────────────────────────────────────────────────
+
+server.tool(
+	'mysql_schema_show_create_table',
+	'Show the CREATE TABLE DDL for a table',
+	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
+	async ({ connection, database, table }) => {
+		try {
+			const { rows } = await client.query(
+				`SHOW CREATE TABLE ${esc(database)}.${esc(table)}`,
+				[], connection,
+			);
+			const ddl = (rows[0] as Record<string, unknown>)?.['Create Table'] ?? '';
+			return { content: [{ type: 'text' as const, text: String(ddl) }] };
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_schema_indexes',
+	'List all indexes on a table',
+	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
+	async ({ connection, database, table }) => {
+		try {
+			const { rows } = await client.query(
+				`SHOW INDEX FROM ${esc(database)}.${esc(table)}`,
+				[], connection,
+			);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_schema_foreign_keys',
+	'List all foreign key constraints on a table',
+	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
+	async ({ connection, database, table }) => {
+		try {
+			const { rows } = await client.query(
+				"SELECT CONSTRAINT_NAME, COLUMN_NAME, REFERENCED_TABLE_SCHEMA, " +
+				"REFERENCED_TABLE_NAME, REFERENCED_COLUMN_NAME " +
+				"FROM information_schema.KEY_COLUMN_USAGE " +
+				"WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? AND REFERENCED_TABLE_NAME IS NOT NULL",
+				[database, table], connection,
+			);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_schema_full',
+	'Export CREATE TABLE DDL for all tables in a database',
+	{ ...ConnectionParam, ...DatabaseParam },
+	async ({ connection, database }) => {
+		try {
+			const { rows: tables } = await client.query(
+				"SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME",
+				[database], connection,
+			);
+			const ddls: string[] = [];
+			for (const t of tables) {
+				const name = String((t as Record<string, unknown>).TABLE_NAME);
+				const { rows } = await client.query(`SHOW CREATE TABLE ${esc(database)}.${esc(name)}`, [], connection);
+				const ddl = String((rows[0] as Record<string, unknown>)?.['Create Table'] ?? '');
+				ddls.push(`-- Table: ${name}\n${ddl};\n`);
+			}
+			return { content: [{ type: 'text' as const, text: ddls.join('\n') }] };
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+// ── User Management ─────────────────────────────────────────────────────
+
+server.tool(
+	'mysql_users_list',
+	'List all MySQL users with host and authentication plugin',
+	{ ...ConnectionParam },
+	async ({ connection }) => {
+		try {
+			const { rows } = await client.query(
+				"SELECT User, Host, plugin, account_locked FROM mysql.user ORDER BY User, Host",
+				[], connection,
+			);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_user_grants',
+	'Show grants for a MySQL user',
+	{ ...ConnectionParam, user: z.string().describe('Username'), host: z.string().optional().describe('Host (default %)') },
+	async ({ connection, user, host }) => {
+		try {
+			const h = host ?? '%';
+			const { rows } = await client.query(`SHOW GRANTS FOR ?@?`, [user, h], connection);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_user_create',
+	'Create a MySQL user',
+	{ ...ConnectionParam, user: z.string(), host: z.string().optional().describe('Host (default localhost)'), password: z.string() },
+	async ({ connection, user, host, password }) => {
+		try {
+			const h = host ?? 'localhost';
+			const r = await client.execute(
+				`CREATE USER ${esc(user)}@${esc(h)} IDENTIFIED BY ?`,
+				[password], connection,
+			);
+			return formatResult(r);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_user_drop',
+	'Drop a MySQL user — DESTRUCTIVE, requires confirm=true',
+	{ ...ConnectionParam, user: z.string(), host: z.string().optional(), ...ConfirmParam },
+	async ({ connection, user, host, confirm }) => {
+		if (!confirm) return { content: [{ type: 'text' as const, text: 'Aborted: confirm must be true.' }] };
+		try {
+			const h = host ?? '%';
+			const r = await client.execute(`DROP USER ${esc(user)}@${esc(h)}`, [], connection);
+			return formatResult(r);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_user_grant',
+	'Grant privileges to a user on a database',
+	{ ...ConnectionParam, user: z.string(), host: z.string().optional(), privileges: z.string().describe('e.g. "SELECT, INSERT" or "ALL PRIVILEGES"'), database: z.string(), table: z.string().optional().describe('Table name (default * for all)') },
+	async ({ connection, user, host, privileges, database, table }) => {
+		try {
+			const safePrivileges = validatePrivileges(privileges);
+			const h = host ?? '%';
+			const t = table ?? '*';
+			const r = await client.execute(
+				`GRANT ${safePrivileges} ON ${esc(database)}.${t === '*' ? '*' : esc(t)} TO ${esc(user)}@${esc(h)}`,
+				[], connection,
+			);
+			await client.execute('FLUSH PRIVILEGES', [], connection);
+			return formatResult(r);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_user_revoke',
+	'Revoke privileges from a user',
+	{ ...ConnectionParam, user: z.string(), host: z.string().optional(), privileges: z.string(), database: z.string(), table: z.string().optional() },
+	async ({ connection, user, host, privileges, database, table }) => {
+		try {
+			const safePrivileges = validatePrivileges(privileges);
+			const h = host ?? '%';
+			const t = table ?? '*';
+			const r = await client.execute(
+				`REVOKE ${safePrivileges} ON ${esc(database)}.${t === '*' ? '*' : esc(t)} FROM ${esc(user)}@${esc(h)}`,
+				[], connection,
+			);
+			await client.execute('FLUSH PRIVILEGES', [], connection);
+			return formatResult(r);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+// ── Maintenance ─────────────────────────────────────────────────────────
+
+server.tool(
+	'mysql_maintenance_optimize',
+	'Run OPTIMIZE TABLE to reclaim space and defragment',
+	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
+	async ({ connection, database, table }) => {
+		try {
+			const { rows } = await client.query(`OPTIMIZE TABLE ${esc(database)}.${esc(table)}`, [], connection);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_maintenance_analyze',
+	'Run ANALYZE TABLE to update index statistics',
+	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
+	async ({ connection, database, table }) => {
+		try {
+			const { rows } = await client.query(`ANALYZE TABLE ${esc(database)}.${esc(table)}`, [], connection);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_maintenance_check',
+	'Run CHECK TABLE to verify table integrity',
+	{ ...ConnectionParam, ...DatabaseParam, ...TableParam },
+	async ({ connection, database, table }) => {
+		try {
+			const { rows } = await client.query(`CHECK TABLE ${esc(database)}.${esc(table)}`, [], connection);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_processlist',
+	'Show running MySQL processes',
+	{ ...ConnectionParam },
+	async ({ connection }) => {
+		try {
+			const { rows } = await client.query('SHOW FULL PROCESSLIST', [], connection);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_process_kill',
+	'Kill a MySQL process by ID — requires confirm=true',
+	{ ...ConnectionParam, process_id: z.number().describe('Process ID to kill'), ...ConfirmParam },
+	async ({ connection, process_id, confirm }) => {
+		if (!confirm) return { content: [{ type: 'text' as const, text: 'Aborted: confirm must be true.' }] };
+		try {
+			const r = await client.execute(`KILL ${Number(process_id)}`, [], connection);
+			return formatResult(r);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+// ── Export ───────────────────────────────────────────────────────────────
+
+server.tool(
+	'mysql_export_table_sql',
+	'Export table structure and data as SQL INSERT statements (no shell exec). ' +
+	'WARNING — replay foot-gun: the output begins with "DROP TABLE IF EXISTS <table>;" and ' +
+	'the INSERTs are hand-quoted (not parameterized). Re-running the dump DROPS the existing ' +
+	'table (and all its rows) before recreating it, so never replay it against a database where ' +
+	'the target table already holds data you intend to keep. Values are escaped only for single ' +
+	'quotes, not full binary-safe encoding — prefer mysqldump for authoritative backups.',
+	{ ...ConnectionParam, ...DatabaseParam, ...TableParam, include_data: z.boolean().optional().describe('Include INSERT statements (default true)'), row_limit: z.number().optional().describe('Max rows for data export (default 1000)') },
+	async ({ connection, database, table, include_data, row_limit }) => {
+		try {
+			const { rows: ddlRows } = await client.query(`SHOW CREATE TABLE ${esc(database)}.${esc(table)}`, [], connection);
+			const ddl = String((ddlRows[0] as Record<string, unknown>)?.['Create Table'] ?? '');
+			const parts: string[] = [`-- Export of ${database}.${table}`, `DROP TABLE IF EXISTS ${esc(table)};`, ddl + ';', ''];
+
+			if (include_data !== false) {
+				const max = Math.min(row_limit ?? 1000, 10000);
+				const { rows, fields } = await client.query(
+					`SELECT * FROM ${esc(database)}.${esc(table)} LIMIT ${max}`,
+					[], connection,
+				);
+				const colNames = fields.map(f => esc(String(f.name))).join(', ');
+				for (const row of rows) {
+					const vals = fields.map(f => {
+						const v = (row as Record<string, unknown>)[String(f.name)];
+						if (v === null) return 'NULL';
+						if (typeof v === 'number') return String(v);
+						return "'" + String(v).replace(/'/g, "''") + "'";
+					}).join(', ');
+					parts.push(`INSERT INTO ${esc(table)} (${colNames}) VALUES (${vals});`);
+				}
+			}
+			return { content: [{ type: 'text' as const, text: parts.join('\n') }] };
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_export_query_csv',
+	'Execute a SELECT and return results as CSV',
+	{ ...ConnectionParam, ...DatabaseParam, sql: z.string().describe('SELECT query'), ...LimitParam },
+	async ({ connection, database, sql, limit }) => {
+		try {
+			const max = Math.min(limit ?? 500, 10000);
+			const hasLimit = /\bLIMIT\s+\d/i.test(sql);
+			const finalSql = hasLimit ? sql : `${sql} LIMIT ${max}`;
+			const { rows, fields } = await client.query(finalSql, [], connection);
+
+			const header = fields.map(f => String(f.name)).join(',');
+			const lines = rows.map(row =>
+				fields.map(f => {
+					const v = (row as Record<string, unknown>)[String(f.name)];
+					if (v === null) return '';
+					const s = String(v);
+					return s.includes(',') || s.includes('"') || s.includes('\n')
+						? '"' + s.replace(/"/g, '""') + '"'
+						: s;
+				}).join(','),
+			);
+			return { content: [{ type: 'text' as const, text: [header, ...lines].join('\n') }] };
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+// ── Joomla Helpers ──────────────────────────────────────────────────────
+
+const JoomlaParams = {
+	table_prefix: z.string().optional().describe('Joomla table prefix (default "jos_")'),
+};
+
+server.tool(
+	'mysql_joomla_extensions',
+	'List installed Joomla extensions from #__extensions',
+	{ ...ConnectionParam, ...DatabaseParam, ...JoomlaParams, type: z.string().optional().describe('Filter by type: component, module, plugin, template, library, package') },
+	async ({ connection, database, table_prefix, type }) => {
+		try {
+			const pfx = table_prefix ?? 'jos_';
+			let sql = `SELECT extension_id, name, type, element, folder, enabled, access, protected, manifest_cache FROM ${esc(database)}.${esc(pfx + 'extensions')}`;
+			const params: string[] = [];
+			if (type) {
+				sql += ' WHERE type = ?';
+				params.push(type);
+			}
+			sql += ' ORDER BY type, name';
+			const { rows } = await client.query(sql, params, connection);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_joomla_users',
+	'List Joomla users with username, email, last visit, and block status',
+	{ ...ConnectionParam, ...DatabaseParam, ...JoomlaParams, ...LimitParam },
+	async ({ connection, database, table_prefix, limit }) => {
+		try {
+			const pfx = table_prefix ?? 'jos_';
+			const max = Math.min(limit ?? 100, 1000);
+			const { rows } = await client.query(
+				`SELECT id, name, username, email, block, lastvisitDate, registerDate FROM ${esc(database)}.${esc(pfx + 'users')} ORDER BY id LIMIT ${max}`,
+				[], connection,
+			);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_joomla_articles',
+	'List Joomla articles from #__content',
+	{ ...ConnectionParam, ...DatabaseParam, ...JoomlaParams, state: z.number().optional().describe('Filter: 1=published, 0=unpublished, -1=archived, -2=trashed'), ...LimitParam },
+	async ({ connection, database, table_prefix, state, limit }) => {
+		try {
+			const pfx = table_prefix ?? 'jos_';
+			const max = Math.min(limit ?? 100, 1000);
+			let sql = `SELECT id, title, alias, state, catid, created, modified, publish_up, publish_down, hits FROM ${esc(database)}.${esc(pfx + 'content')}`;
+			const params: unknown[] = [];
+			if (state !== undefined) {
+				sql += ' WHERE state = ?';
+				params.push(state);
+			}
+			sql += ` ORDER BY id DESC LIMIT ${max}`;
+			const { rows } = await client.query(sql, params, connection);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_joomla_sessions',
+	'Count active Joomla sessions and show session stats',
+	{ ...ConnectionParam, ...DatabaseParam, ...JoomlaParams },
+	async ({ connection, database, table_prefix }) => {
+		try {
+			const pfx = table_prefix ?? 'jos_';
+			const { rows } = await client.query(
+				`SELECT COUNT(*) AS total_sessions, ` +
+				`SUM(CASE WHEN guest = 1 THEN 1 ELSE 0 END) AS guest_sessions, ` +
+				`SUM(CASE WHEN guest = 0 THEN 1 ELSE 0 END) AS user_sessions, ` +
+				`MIN(time) AS oldest_session, MAX(time) AS newest_session ` +
+				`FROM ${esc(database)}.${esc(pfx + 'session')}`,
+				[], connection,
+			);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+server.tool(
+	'mysql_joomla_config',
+	'Read Joomla global configuration values from the extensions table params',
+	{ ...ConnectionParam, ...DatabaseParam, ...JoomlaParams },
+	async ({ connection, database, table_prefix }) => {
+		try {
+			const pfx = table_prefix ?? 'jos_';
+			const { rows } = await client.query(
+				`SELECT extension_id, name, params FROM ${esc(database)}.${esc(pfx + 'extensions')} WHERE type = 'component' AND element = 'com_config' LIMIT 1`,
+				[], connection,
+			);
+			return formatRows(rows);
+		} catch (e) {
+			return formatError(e);
+		}
+	},
+);
+
+// ── Bootstrap ───────────────────────────────────────────────────────────
+
+async function main() {
+	try {
+		config = await loadConfig();
+		client = new MysqlClient(config);
+	} catch (err) {
+		process.stderr.write(`${err}\n`);
+		process.exit(1);
+	}
+
+	const cleanup = async () => {
+		await client.closeAll();
+		process.exit(0);
+	};
+	process.on('SIGINT', cleanup);
+	process.on('SIGTERM', cleanup);
+
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+
+main().catch((err) => {
+	process.stderr.write(`Fatal: ${err}\n`);
+	process.exit(1);
+});