@mokoconsulting/mokomysql-mcp 0.0.0-stage → 2.5.4

package/source/secrets.ts

@@ -0,0 +1,70 @@
+/* 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-mcp.Secrets
+ * INGROUP: mokomysql-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
+ * PATH: /source/secrets.ts
+ * BRIEF: Resolve file-backed secret references in a parsed config object.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+
+/** Expand a leading "~" to the user's home directory, then resolve to absolute. */
+function expandHome(p: string): string {
+	if (p === '~') return homedir();
+	if (p.startsWith('~/') || p.startsWith('~\\')) {
+		return resolve(homedir(), p.slice(2));
+	}
+	return resolve(p);
+}
+
+/**
+ * Resolve a single config string.
+ * - "file:<path>" -> the trimmed contents of <path> (a leading "~" expands to $HOME).
+ * - anything else  -> returned unchanged, so inline literals keep working.
+ *
+ * A missing/unreadable file throws (fail loud) — a secret must never silently
+ * degrade to the literal "file:..." string.
+ */
+async function resolveRef(value: string): Promise<string> {
+	const m = /^file:(.+)$/s.exec(value.trim());
+	if (!m) return value;
+	const path = expandHome(m[1].trim());
+	try {
+		const raw = await readFile(path, 'utf-8');
+		return raw.replace(/\r?\n+$/, '');
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to read secret file "${path}" (referenced as "${value}"): ${msg}`);
+	}
+}
+
+/**
+ * Recursively resolve every "file:" secret reference in a parsed config object,
+ * in place. Lets secrets (tokens, passwords, API keys) live in files such as
+ * ~/.ssh/tokens/* instead of inline in the config JSON. Plain values are left
+ * untouched, so pre-existing inline configs remain valid.
+ */
+export async function resolveSecretRefs(obj: unknown): Promise<void> {
+	if (Array.isArray(obj)) {
+		for (let i = 0; i < obj.length; i++) {
+			const v = obj[i];
+			if (typeof v === 'string') obj[i] = await resolveRef(v);
+			else if (v && typeof v === 'object') await resolveSecretRefs(v);
+		}
+	} else if (obj && typeof obj === 'object') {
+		const rec = obj as Record<string, unknown>;
+		for (const k of Object.keys(rec)) {
+			const v = rec[k];
+			if (typeof v === 'string') rec[k] = await resolveRef(v);
+			else if (v && typeof v === 'object') await resolveSecretRefs(v);
+		}
+	}
+}

package/source/state.ts

@@ -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: mokomysql.State
+ * INGROUP: mokomysql
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
+ * PATH: /source/state.ts
+ * BRIEF: Sidecar state store for learned Joomla markers (per host:port/database).
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { getStatePath } from './config.js';
+import type { JoomlaMarker, MySqlState } from './types.js';
+
+let cache: MySqlState | null = null;
+/** Serializes write-through so concurrent setMarker calls can't clobber the file. */
+let writeChain: Promise<void> = Promise.resolve();
+
+/** Stable key for a learned verdict: identifies the physical database target. */
+export function markerKey(host: string, port: number, database: string): string {
+	return `${host}:${port}/${database}`;
+}
+
+/** Load the sidecar once into memory; a missing/corrupt file is an empty store. */
+export async function loadState(): Promise<MySqlState> {
+	if (cache) return cache;
+	try {
+		const parsed = JSON.parse(await readFile(getStatePath(), 'utf-8')) as Partial<MySqlState>;
+		cache = parsed && typeof parsed.markers === 'object' && parsed.markers !== null
+			? { markers: parsed.markers }
+			: { markers: {} };
+	} catch {
+		cache = { markers: {} };
+	}
+	return cache;
+}
+
+export async function getMarker(key: string): Promise<JoomlaMarker | undefined> {
+	return (await loadState()).markers[key];
+}
+
+/**
+ * Record a learned verdict and persist it. The write is best-effort: an unwritable
+ * sidecar (read-only home, permissions) must not break queries — the in-memory
+ * cache still carries the verdict for this process, we just can't remember it next time.
+ */
+export async function setMarker(key: string, marker: JoomlaMarker): Promise<void> {
+	const state = await loadState();
+	state.markers[key] = marker;
+	writeChain = writeChain.then(async () => {
+		try {
+			await writeFile(getStatePath(), JSON.stringify(state, null, '\t') + '\n', 'utf-8');
+		} catch (e) {
+			process.stderr.write(`mokomysql: could not write state file ${getStatePath()}: ${e}\n`);
+		}
+	});
+	await writeChain;
+}

package/source/types.ts

@@ -0,0 +1,91 @@
+/* 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.Types
+ * INGROUP: mokomysql
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
+ * PATH: /src/types.ts
+ * VERSION: 01.00.00
+ * BRIEF: TypeScript type definitions for MySQL MCP server
+ */
+
+export interface MySqlSslConfig {
+	/** Verify the server certificate against a CA. Defaults to true. */
+	rejectUnauthorized?: boolean;
+	/** PEM CA certificate(s) to trust. */
+	ca?: string;
+	/** PEM client certificate. */
+	cert?: string;
+	/** PEM client private key. */
+	key?: string;
+}
+
+export interface MySqlConnection {
+	host: string;
+	port?: number;
+	user: string;
+	password: string;
+	database?: string;
+	/**
+	 * TLS for the connection. `true` enables TLS with certificate verification
+	 * (secure default). Pass an object to customize — e.g. `{ ca: '...' }` for a
+	 * private CA, or `{ rejectUnauthorized: false }` to explicitly opt out of
+	 * verification (insecure; only for trusted internal hosts with self-signed
+	 * certs). A bare `true` is never silently downgraded.
+	 */
+	ssl?: boolean | MySqlSslConfig;
+	timezone?: string;
+	/**
+	 * Extra keyword shortcuts that resolve to this connection.
+	 * Matched case-insensitively with all punctuation stripped, so
+	 * "moko.live", "moko-live", "Moko Live" and "mokolive" are equivalent.
+	 */
+	tags?: string[];
+	/**
+	 * Marks this connection as pointing at a Joomla database. Writes to a Joomla DB
+	 * require the two-step `confirm_token` handshake (first call returns a token and
+	 * does not execute; the same call repeated with the token runs it) on top of the
+	 * usual `confirm: true` — reads stay unrestricted. Leave unset to auto-detect from
+	 * the schema signature (presence of `<prefix>extensions` + `<prefix>assets`);
+	 * set `true` to force the gate on, or `false` to force it off and skip detection.
+	 */
+	joomla?: boolean;
+	/**
+	 * Joomla table prefix for this connection (e.g. "jos_", "vkw4n_"). Only used when
+	 * `joomla: true` is set explicitly — it lets the nested-set guard recognize
+	 * `#__assets`/`#__categories`/`#__menu` without a schema probe. When omitted, the
+	 * prefix is derived from the detected signature tables.
+	 */
+	joomlaPrefix?: string;
+}
+
+export interface MySqlConfig {
+	connections: Record<string, MySqlConnection>;
+	defaultConnection: string;
+}
+
+/**
+ * A learned Joomla verdict for one `host:port/database` target, persisted to the
+ * sidecar state file so the server knows the target is Joomla on future connects
+ * without re-probing the schema.
+ */
+export interface JoomlaMarker {
+	joomla: boolean;
+	/** Live table prefix (e.g. "jos_", "vkw4n_") when known. */
+	prefix: string | null;
+	/** ISO timestamp of when the verdict was learned. */
+	detectedAt: string;
+}
+
+/**
+ * Sidecar state the MCP manages itself (distinct from the user-authored config).
+ * Lives next to the config as `<config>.state.json`. Pure cache: delete it and
+ * the server re-detects; an explicit per-connection `joomla` flag overrides it.
+ */
+export interface MySqlState {
+	markers: Record<string, JoomlaMarker>;
+}

package/tsconfig.json

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