@mokoconsulting/mokomysql-mcp 0.0.0-stage → 2.5.4

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# mokomysql-mcp
+
+A Model Context Protocol (MCP) server for MySQL database management — run queries, inspect
+and modify schema, manage users, perform maintenance, and use Joomla-aware helpers, all
+exposed as MCP tools that AI assistants and MCP clients can call.
+
+## Features
+
+- Execute SQL queries against a configured MySQL/MariaDB database
+- Inspect and manage schema (tables, columns, indexes)
+- User and privilege management
+- Maintenance operations (analyze, optimize, repair)
+- Joomla-specific helpers for common CMS database tasks
+
+## Requirements
+
+- An MCP-capable client (for example, Claude Code or another MCP host)
+- Network access to a MySQL or MariaDB server
+- Database credentials with the privileges required for the operations you intend to run
+
+## Installation
+
+The server is published to npm as `@mokoconsulting/mokomysql-mcp`. No manual clone or
+build is required — your MCP client runs it on demand with `npx`:
+
+```bash
+npx -y @mokoconsulting/mokomysql-mcp
+```
+
+Or install it globally:
+
+```bash
+npm install -g @mokoconsulting/mokomysql-mcp
+```
+
+## Configuration
+
+Connections are read from a JSON config file at `~/.mcp_mokomysql.json` (override the path
+with the `MYSQL_MCP_CONFIG` environment variable). See [`config.example.json`](config.example.json):
+
+```json
+{
+  "defaultConnection": "local",
+  "connections": {
+    "local": {
+      "host": "127.0.0.1",
+      "port": 3306,
+      "user": "dbuser",
+      "password": "secret",
+      "database": "joomla",
+      "ssl": false
+    }
+  }
+}
+```
+
+Full configuration reference is in the wiki — docs are **wiki-first** at MokoConsulting:
+
+**→ [Configuration (wiki)](https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp/wiki/Configuration)**
+
+It covers TLS options, environment variables (`MYSQL_MCP_CONFIG`, `MYSQL_MCP_STATE`), the sidecar
+state file, and **Joomla write safety** — writes to a Joomla database require a two-step
+`confirm_token` (the first call returns a token and does not execute); reads are never gated.
+
+The write gate is **operation-aware**. The two-step `confirm_token` is required for *every* Joomla
+write, but the "raw SQL can corrupt the ACL nested set" warning is only shown for the operations
+that can actually cause it. Joomla creates, removes, and renumbers `#__assets` / nested-set rows
+only when a row is **created or deleted** through its Table API (`Table::store()` / `Table::delete()`),
+which raw SQL bypasses — so:
+
+- A pure **in-place `UPDATE`** that does not reference a nested-set table (`#__assets`, `#__categories`,
+  `#__menu`) gets a lighter message: it still needs the token, but it cannot touch the asset tree.
+- **`INSERT` / `DELETE`** of an asset-bearing row (any table with an `asset_id` column), **DDL**, and
+  **any write to a nested-set table** keep the full nested-set/ACL warning and the integrity reminder.
+
+## Usage
+
+Register the server with your MCP client. A typical MCP client configuration entry looks like:
+
+```json
+{
+  "mcpServers": {
+    "mokomysql": {
+      "command": "npx",
+      "args": ["-y", "@mokoconsulting/mokomysql-mcp"],
+      "env": {
+        "MYSQL_MCP_CONFIG": "/home/you/.mcp_mokomysql.json",
+        "MYSQL_MCP_STATE": "/home/you/.mcp_mokomysql.state.json"
+      }
+    }
+  }
+}
+```
+
+The `env` block is where the config and sidecar paths belong — server-instance settings, kept out
+of any project repository (both are optional; see the [Configuration wiki](https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp/wiki/Configuration)).
+Once connected, the client can call the server's tools to query data, inspect schema, manage
+users, run maintenance, and invoke the Joomla helpers.
+
+## Contributing
+
+Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) and follow the
+[MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/mokocli/wiki/Home) for
+coding style, commit conventions, and the pull request process.
+
+## License
+
+Licensed under GPL-3.0-or-later — see [LICENSE](LICENSE).
+
+---
+
+*[Moko Consulting](https://mokoconsulting.tech)*

package/config.example.json

@@ -0,0 +1,26 @@
+{
+	"defaultConnection": "local",
+	"connections": {
+		"local": {
+			"host": "127.0.0.1",
+			"port": 3306,
+			"user": "root",
+			"password": "CHANGE_ME",
+			"database": "mysql",
+			"ssl": false,
+			"timezone": "Z",
+			"tags": ["localhost", "dev-db"]
+		},
+		"joomla-site": {
+			"host": "db.example.com",
+			"port": 3306,
+			"user": "joomla",
+			"password": "file:~/.ssh/tokens/JOOMLA.db.token",
+			"database": "joomla_prod",
+			"ssl": true,
+			"joomla": true,
+			"joomlaPrefix": "vkw4n_",
+			"tags": ["prod"]
+		}
+	}
+}

package/dist/README.md

@@ -0,0 +1,7 @@
+# dist/
+
+Distributable artifacts live here — the packaged installer(s) and release
+bundles emitted by the **mokocli-centric build system** (mokocli clones and runs
+the shared build tooling in CI). Generated output, not source.
+
+Only this `README.md` is tracked; everything else under `dist/` is git-ignored.

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+import type { FieldPacket } from 'mysql2/promise';
+import type { MySqlConfig } from './types.js';
+/** Result of probing a (connection, database) pair for Joomla-ness. */
+export interface JoomlaDetection {
+    /** Whether this target is treated as a Joomla database. */
+    isJoomla: boolean;
+    /** The live table prefix (e.g. "jos_", "vkw4n_"), when known. */
+    prefix: string | null;
+    /** How the verdict was reached — for surfacing in warnings. */
+    source: 'config' | 'marker' | 'auto' | 'none';
+}
+export declare class MysqlClient {
+    private pools;
+    private config;
+    /** Memoized Joomla verdicts, keyed by `${connectionKey}::${schema}`. */
+    private joomlaCache;
+    constructor(config: MySqlConfig);
+    /**
+     * Resolve the canonical identity of a target for binding/keying: the config
+     * connection key and the effective schema (explicit database or the connection
+     * default). Keeps callers consistent with how detection and markers are keyed.
+     */
+    resolveIdentity(connectionName?: string, database?: string): {
+        connKey: string;
+        schema: string;
+    };
+    /**
+     * Determine whether a target is a Joomla database, so writes can be gated.
+     * Resolution order: in-memory cache → explicit per-connection `joomla` flag
+     * (authoritative) → persisted sidecar marker (learned on a prior connect) →
+     * live schema probe for the Joomla signature (`<prefix>extensions` paired with
+     * `<prefix>assets`). A fresh probe result is persisted as a marker so future
+     * connects skip the round-trip entirely.
+     */
+    detectJoomla(connectionName?: string, database?: string): Promise<JoomlaDetection>;
+    private cache;
+    private poolFor;
+    query(sql: string, params?: unknown[], connectionName?: string, database?: string): Promise<{
+        rows: Record<string, unknown>[];
+        fields: FieldPacket[];
+    }>;
+    execute(sql: string, params?: unknown[], connectionName?: string, database?: string): Promise<{
+        affectedRows: number;
+        insertId: number;
+        changedRows: number;
+    }>;
+    closeAll(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../source/client.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAqB,WAAW,EAAmB,MAAM,gBAAgB,CAAC;AAGtF,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,YAAY,CAAC;AAE/D,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC/B,2DAA2D;IAC3D,QAAQ,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,+DAA+D;IAC/D,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;CAC9C;AAED,qBAAa,WAAW;IACvB,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,MAAM,CAAc;IAC5B,wEAAwE;IACxE,OAAO,CAAC,WAAW,CAA2C;gBAElD,MAAM,EAAE,WAAW;IAI/B;;;;OAIG;IACH,eAAe,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAKhG;;;;;;;OAOG;IACG,YAAY,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAqDxF,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,OAAO;IAoCT,KAAK,CACV,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,EAClB,cAAc,CAAC,EAAE,MAAM,EACvB,QAAQ,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;QAAC,MAAM,EAAE,WAAW,EAAE,CAAA;KAAE,CAAC;IAiBhE,OAAO,CACZ,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,EAClB,cAAc,CAAC,EAAE,MAAM,EACvB,QAAQ,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAuBrE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAM/B"}

package/dist/client.js

@@ -0,0 +1,180 @@
+/* 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.Client
+ * INGROUP: mokomysql
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
+ * PATH: /src/client.ts
+ * VERSION: 01.00.00
+ * BRIEF: MySQL client with connection pool management
+ */
+import mysql from 'mysql2/promise';
+import { getConnection } from './config.js';
+import { getMarker, markerKey, setMarker } from './state.js';
+export class MysqlClient {
+    pools = new Map();
+    config;
+    /** Memoized Joomla verdicts, keyed by `${connectionKey}::${schema}`. */
+    joomlaCache = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Resolve the canonical identity of a target for binding/keying: the config
+     * connection key and the effective schema (explicit database or the connection
+     * default). Keeps callers consistent with how detection and markers are keyed.
+     */
+    resolveIdentity(connectionName, database) {
+        const { key, conn } = getConnection(this.config, connectionName);
+        return { connKey: key, schema: database ?? conn.database ?? '' };
+    }
+    /**
+     * Determine whether a target is a Joomla database, so writes can be gated.
+     * Resolution order: in-memory cache → explicit per-connection `joomla` flag
+     * (authoritative) → persisted sidecar marker (learned on a prior connect) →
+     * live schema probe for the Joomla signature (`<prefix>extensions` paired with
+     * `<prefix>assets`). A fresh probe result is persisted as a marker so future
+     * connects skip the round-trip entirely.
+     */
+    async detectJoomla(connectionName, database) {
+        const { key, conn } = getConnection(this.config, connectionName);
+        const schema = database ?? conn.database ?? '';
+        const cacheKey = `${key}::${schema}`;
+        const cached = this.joomlaCache.get(cacheKey);
+        if (cached)
+            return cached;
+        // Explicit config flag is authoritative — no probe, and it overrides any marker.
+        if (conn.joomla === true) {
+            return this.cache(cacheKey, { isJoomla: true, prefix: conn.joomlaPrefix ?? null, source: 'config' });
+        }
+        if (conn.joomla === false) {
+            return this.cache(cacheKey, { isJoomla: false, prefix: null, source: 'config' });
+        }
+        // Without a resolvable target schema we cannot probe or key a marker.
+        if (!schema) {
+            return this.cache(cacheKey, { isJoomla: false, prefix: null, source: 'none' });
+        }
+        // Learned marker from a previous connect — instant, no round-trip.
+        const mKey = markerKey(conn.host, conn.port ?? 3306, schema);
+        const marker = await getMarker(mKey);
+        if (marker) {
+            return this.cache(cacheKey, { isJoomla: marker.joomla, prefix: marker.prefix, source: 'marker' });
+        }
+        try {
+            const { rows } = await this.query("SELECT TABLE_NAME AS name FROM information_schema.TABLES " +
+                "WHERE TABLE_SCHEMA = ? AND TABLE_NAME REGEXP '(extensions|assets)$'", [schema], connectionName);
+            const names = new Set(rows.map((r) => String(r.name)));
+            let prefix = null;
+            for (const name of names) {
+                if (!name.endsWith('extensions'))
+                    continue;
+                const candidate = name.slice(0, -'extensions'.length);
+                if (names.has(`${candidate}assets`)) {
+                    prefix = candidate;
+                    break;
+                }
+            }
+            const verdict = prefix !== null
+                ? { isJoomla: true, prefix, source: 'auto' }
+                : { isJoomla: false, prefix: null, source: 'auto' };
+            // Persist what we learned so the next connect just knows.
+            await setMarker(mKey, { joomla: verdict.isJoomla, prefix: verdict.prefix, detectedAt: new Date().toISOString() });
+            return this.cache(cacheKey, verdict);
+        }
+        catch {
+            // Probe failed (permissions, missing schema). Degrade to "none" and do
+            // not cache or persist, so a later successful probe can still classify it.
+            return { isJoomla: false, prefix: null, source: 'none' };
+        }
+    }
+    cache(cacheKey, verdict) {
+        this.joomlaCache.set(cacheKey, verdict);
+        return verdict;
+    }
+    poolFor(connectionName) {
+        const { key, conn } = getConnection(this.config, connectionName);
+        let pool = this.pools.get(key);
+        if (!pool) {
+            const opts = {
+                host: conn.host,
+                port: conn.port ?? 3306,
+                user: conn.user,
+                password: conn.password,
+                database: conn.database,
+                connectionLimit: 5,
+                waitForConnections: true,
+                timezone: conn.timezone ?? 'Z',
+                multipleStatements: false,
+            };
+            if (conn.ssl) {
+                // Default to verified TLS. A bare `ssl: true` is never silently
+                // downgraded — callers who must skip verification (trusted internal
+                // hosts with self-signed certs) opt out explicitly via
+                // `ssl: { rejectUnauthorized: false }` in their config.
+                opts.ssl = typeof conn.ssl === 'object'
+                    ? conn.ssl
+                    : { rejectUnauthorized: true };
+            }
+            pool = mysql.createPool(opts);
+            this.pools.set(key, pool);
+            // On first connect, learn (and persist) the Joomla verdict for the
+            // connection's default database so the write-gate knows immediately.
+            // Best-effort and non-blocking — never let it break pool creation.
+            if (conn.database) {
+                void this.detectJoomla(connectionName, conn.database).catch(() => undefined);
+            }
+        }
+        return pool;
+    }
+    async query(sql, params, connectionName, database) {
+        const pool = this.poolFor(connectionName);
+        const p = (params ?? []);
+        if (database) {
+            const conn = await pool.getConnection();
+            try {
+                await conn.query(`USE \`${database.replace(/`/g, '``')}\``);
+                const [rows, fields] = await conn.query(sql, p);
+                return { rows: rows, fields };
+            }
+            finally {
+                conn.release();
+            }
+        }
+        const [rows, fields] = await pool.query(sql, p);
+        return { rows: rows, fields };
+    }
+    async execute(sql, params, connectionName, database) {
+        const pool = this.poolFor(connectionName);
+        const p = (params ?? []);
+        if (database) {
+            const conn = await pool.getConnection();
+            try {
+                await conn.query(`USE \`${database.replace(/`/g, '``')}\``);
+                const [result] = await conn.execute(sql, p);
+                const r = result;
+                return { affectedRows: r.affectedRows ?? 0, insertId: r.insertId ?? 0, changedRows: r.changedRows ?? 0 };
+            }
+            finally {
+                conn.release();
+            }
+        }
+        const [result] = await pool.execute(sql, p);
+        const r = result;
+        return {
+            affectedRows: r.affectedRows ?? 0,
+            insertId: r.insertId ?? 0,
+            changedRows: r.changedRows ?? 0,
+        };
+    }
+    async closeAll() {
+        for (const [, pool] of this.pools) {
+            await pool.end();
+        }
+        this.pools.clear();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../source/client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,21 @@
+import type { MySqlConfig, MySqlConnection } from './types.js';
+/** Absolute path to the active config file (`MYSQL_MCP_CONFIG` or ~/.mcp_mokomysql.json). */
+export declare function getConfigPath(): string;
+/**
+ * Absolute path to the sidecar state file — the MCP-managed learned-marker store.
+ * `MYSQL_MCP_STATE` overrides it outright; otherwise it sits beside the config as
+ * `<config>.state.json`, so learned state always follows the config that produced it.
+ */
+export declare function getStatePath(): string;
+export declare function loadConfig(): Promise<MySqlConfig>;
+/**
+ * Normalize a name for tag matching: lowercase and strip every character
+ * that isn't a letter or digit. This makes "moko.live", "moko-live",
+ * "Moko Live" and "mokolive" all collapse to the same key.
+ */
+export declare function normalizeTag(value: string): string;
+export declare function getConnection(config: MySqlConfig, name?: string): {
+    key: string;
+    conn: MySqlConnection;
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../source/config.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAK/D,6FAA6F;AAC7F,wBAAgB,aAAa,IAAI,MAAM,CAItC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,CAyBvD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAoBxG"}

package/dist/config.js

@@ -0,0 +1,86 @@
+/* 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.Config
+ * INGROUP: mokomysql
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
+ * PATH: /src/config.ts
+ * VERSION: 01.00.00
+ * BRIEF: Configuration loader for MySQL MCP connections
+ */
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { resolveSecretRefs } from './secrets.js';
+const CONFIG_FILENAME = '.mcp_mokomysql.json';
+/** Absolute path to the active config file (`MYSQL_MCP_CONFIG` or ~/.mcp_mokomysql.json). */
+export function getConfigPath() {
+    return process.env.MYSQL_MCP_CONFIG
+        ? resolve(process.env.MYSQL_MCP_CONFIG)
+        : resolve(homedir(), CONFIG_FILENAME);
+}
+/**
+ * Absolute path to the sidecar state file — the MCP-managed learned-marker store.
+ * `MYSQL_MCP_STATE` overrides it outright; otherwise it sits beside the config as
+ * `<config>.state.json`, so learned state always follows the config that produced it.
+ */
+export function getStatePath() {
+    if (process.env.MYSQL_MCP_STATE)
+        return resolve(process.env.MYSQL_MCP_STATE);
+    return getConfigPath().replace(/\.json$/i, '') + '.state.json';
+}
+export async function loadConfig() {
+    const config_path = getConfigPath();
+    try {
+        const raw = await readFile(config_path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        // Resolve any "file:<path>" secret references (e.g. passwords in ~/.ssh/tokens).
+        await resolveSecretRefs(parsed);
+        if (!parsed.connections || Object.keys(parsed.connections).length === 0) {
+            throw new Error('No connections defined in config');
+        }
+        return {
+            connections: parsed.connections,
+            defaultConnection: parsed.defaultConnection ?? Object.keys(parsed.connections)[0],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to load config from ${config_path}: ${message}\n` +
+            `Create ${config_path} — see config.example.json for format.`);
+    }
+}
+/**
+ * Normalize a name for tag matching: lowercase and strip every character
+ * that isn't a letter or digit. This makes "moko.live", "moko-live",
+ * "Moko Live" and "mokolive" all collapse to the same key.
+ */
+export function normalizeTag(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+export function getConnection(config, name) {
+    const requested = name ?? config.defaultConnection;
+    // 1. Exact key match — fast path, preserves prior behavior exactly.
+    const direct = config.connections[requested];
+    if (direct)
+        return { key: requested, conn: direct };
+    // 2. Normalized match against connection keys and their tag shortcuts.
+    //    Returns the canonical key, never the alias/tag the caller typed.
+    const target = normalizeTag(requested);
+    for (const [key, conn] of Object.entries(config.connections)) {
+        if (normalizeTag(key) === target)
+            return { key, conn };
+        if (conn.tags?.some((tag) => normalizeTag(tag) === target))
+            return { key, conn };
+    }
+    // 3. Not found — list keys plus their tags so the caller can self-correct.
+    const available = Object.entries(config.connections)
+        .map(([key, conn]) => (conn.tags?.length ? `${key} [${conn.tags.join(', ')}]` : key))
+        .join(', ');
+    throw new Error(`Connection "${requested}" not found. Available: ${available}`);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../source/config.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { MysqlClient } from './client.js';
+import type { MySqlConfig } from './types.js';
+export declare let config: MySqlConfig;
+export declare let client: MysqlClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":";AAqBA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,eAAO,IAAI,MAAM,EAAE,WAAW,CAAC;AAC/B,eAAO,IAAI,MAAM,EAAE,WAAW,CAAC"}