@andezdev/tokenlite-mysql-mcp 1.0.0 → 3.0.0

package/AGENTS.md

@@ -23,7 +23,7 @@
 
 5. **Fixing Optimizer Blocks (Full Table Scans).**
    - **Rule**: If the `execute_safe_query` tool throws an `OptimizerError: Full table scan detected`, it means your query is scanning too many rows without an index.
-   - **Action**: You MUST rewrite the query to include a `WHERE` clause that uses an indexed column (e.g., a primary key or foreign key).
+   - **Action**: Use `explain_query` to see the full EXPLAIN output, then rewrite the query to include a `WHERE` clause that uses an indexed column (e.g., a primary key or foreign key).
 
 ---
 
@@ -49,3 +49,15 @@
 **Use for:** Forcing the server to rescan the database and update its internal graph.
 **Arguments:** None.
 **Use when:** You receive an error that a table or column doesn't exist, implying the schema changed.
+
+### `explain_query`
+**Use for:** Analyzing the execution plan of a SELECT query before running it.
+**Arguments:** `sql` (string) - The SELECT query to analyze.
+**Returns:** The MySQL EXPLAIN output as CSV showing join types, index usage, and estimated row counts.
+**Use when:** Your query was blocked by the optimizer (`OptimizerError`) or you want to verify it uses indexes before executing.
+
+### `ping`
+**Use for:** Checking if the database connection is alive and healthy.
+**Arguments:** None.
+**Returns:** JSON with `status` (`"ok"` or `"error"`), `server_version`, and `pool` stats (`active`, `idle`, `queue` connection counts).
+**Use when:** You suspect a connection issue or want to verify the server is operational before running queries.

package/README.md

@@ -1,6 +1,6 @@
 # TokenLite MySQL MCP
 
-[![npm version](https://badge.fury.io/js/@andezdev%2Ftokenlite-mysql-mcp.svg)](https://badge.fury.io/js/@andezdev%2Ftokenlite-mysql-mcp)
+[![npm version](https://badge.fury.io/js/@andezdev%2Ftokenlite-mysql-mcp.svg?icon=si%3Anpm)](https://badge.fury.io/js/@andezdev%2Ftokenlite-mysql-mcp)
 
 A robust and secure MySQL database server implemented under Anthropic's **Model Context Protocol (MCP)**. 
 Designed specifically to solve the shortcomings of current generic MCP servers through **Graceful Degradation, Active Performance Protection, and Aggressive Token Optimization**.
@@ -10,9 +10,11 @@ Designed specifically to solve the shortcomings of current generic MCP servers t
 ## 🌟 Core Pillars
 
 1. **Safe-Query Optimizer (AST & EXPLAIN)**: Protects production databases by pre-analyzing queries. Blocks unindexed Full Table Scans that exceed configurable thresholds and injects strict `LIMIT` clauses automatically at the AST level.
-2. **Business Intelligence Injection**: Bridges the gap between raw data and company logic. Automatically attaches semantic dictionaries (`metadata.json`) to database schema exploration, and exposes a Semantic Template Search tool (`templates.json`) so the LLM uses pre-approved analytical queries instead of hallucinating them.
-3. **Graph-Based Semantic Schema**: Avoids sending giant schemas to the LLM that saturate the context window. When a table is searched, the engine uses heuristics to deduce implicit relationships and packages the exact "Auto-Join Context".
-4. **CSV Token Compression**: Database results are efficiently transformed into tabular CSV markdown, saving up to 60% of Output Tokens compared to verbose JSON.
+2. **Granular AST-Based Write Permissions**: By default, TokenLite is 100% Read-Only. You can surgically enable specific write operations (INSERT, UPDATE, DELETE, DDL) via environment variables. The firewall uses strict AST parsing to prevent SQL injection and comment-bypass attacks, and strictly prohibits privilege escalation commands (like `GRANT` or `CALL`).
+3. **Session-Level Defense in Depth**: If the server is configured in strict Read-Only mode (all write variables disabled), TokenLite injects `SET SESSION TRANSACTION READ ONLY` directly into the connection pool sockets. This guarantees that even if a theoretical bypass exists in the AST parser, the MySQL engine itself will physically reject any data modification.
+4. **Business Intelligence Injection**: Bridges the gap between raw data and company logic. Automatically attaches semantic dictionaries (`metadata.json`) to database schema exploration, and exposes Semantic Templates via the official **MCP Prompts API** (`templates.json`) so the LLM uses pre-approved analytical queries instead of hallucinating them.
+5. **Graph-Based Semantic Schema**: Avoids sending giant schemas to the LLM that saturate the context window. When a table is searched, the engine uses heuristics to deduce implicit relationships and packages the exact "Auto-Join Context".
+6. **CSV Token Compression**: Database results are efficiently transformed into tabular CSV markdown, saving up to 60% of Output Tokens compared to verbose JSON.
 
 ---
 
@@ -98,6 +100,19 @@ To use within Cursor IDE:
 | `MCP_SAFE_QUERY_ENABLE_BLOCKING`| Enable or disable the EXPLAIN guardrail. | `true` | No |
 | `MCP_METADATA_PATH` | Absolute path to your custom `metadata.json` dictionary. | (Disabled) | No |
 | `MCP_TEMPLATES_PATH` | Absolute path to your custom `templates.json` queries. | (Disabled) | No |
+| `TOOL_PREFIX` | Prefix for tool names (useful when running multiple instances). | Random (e.g., `db_a1b2_`) | No |
+| `MYSQL_QUERY_TIMEOUT` | Max execution time for a query (in ms). Aborts heavy queries to protect against DoS. | `15000` | No |
+| `MYSQL_CONNECTION_LIMIT` | Max concurrent pool connections. | `10` | No |
+| `MYSQL_CONNECT_TIMEOUT` | Max time to wait for a socket to establish (in ms). | `10000` | No |
+| `MYSQL_RETRY_ATTEMPTS` | Max retries on transient connection errors (`ECONNREFUSED`, `PROTOCOL_CONNECTION_LOST`, etc.). | `3` | No |
+| `MYSQL_RETRY_DELAY_MS` | Base delay (ms) for exponential backoff between retries (1s, 2s, 4s...). | `1000` | No |
+| `MYSQL_QUEUE_LIMIT` | Max queued requests when all pool connections are busy. Prevents unbounded growth if MySQL is down. | `50` | No |
+| `MCP_DDL_CACHE_TTL` | Time-to-live (in seconds) for cached DDL statements. Reduces latency on repeated `search_schema` calls. Invalidated by `refresh_schema`. | `60` | No |
+| `MCP_LOG_LEVEL` | Minimum severity for MCP log notifications: `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`. | `info` | No |
+| `ALLOW_INSERT_OPERATION` | Enable `INSERT` and `REPLACE` queries. | `false` | No |
+| `ALLOW_UPDATE_OPERATION` | Enable `UPDATE` queries. | `false` | No |
+| `ALLOW_DELETE_OPERATION` | Enable `DELETE` and `TRUNCATE` queries. | `false` | No |
+| `ALLOW_DDL_OPERATION` | Enable Data Definition Language (`CREATE`, `ALTER`, `DROP`, `RENAME`). | `false` | No |
 
 ---
 
@@ -132,40 +147,91 @@ Stop the LLM from hallucinating complex metrics by providing vetted templates.
 
 ## 📈 Benchmarks & Token Savings
 
-TokenLite includes an automated, precise benchmark suite using official `cl100k_base` tokenization (matching models like Claude 3.5 Sonnet and GPT-4) to measure efficiency improvements.
+TokenLite includes an automated benchmark suite using `o200k_base` tokenization (GPT-4o/GPT-5 standard) to measure efficiency improvements. Token counts are approximate — Claude 4.x uses a proprietary tokenizer; actual counts may vary slightly.
 
 To run the benchmark in your own environment:
 ```bash
 npm run benchmark
 ```
 
+### Baseline: Standard MCP Pattern
+The benchmark compares against the standard pattern used by generic MySQL MCP servers: full schema exposed as `information_schema.columns` in pretty-printed JSON, and query results returned as `JSON.stringify(rows, null, 2)` with execution time metadata.
+
 ### 1. Schema Discovery (Input Tokens)
-Traditional MCP servers dump the entire schema to the LLM. For large databases, this consumes thousands of input tokens on every turn. TokenLite's relational graph serves a localized **Auto-Join Context** (target table + direct parent tables + direct child tables).
+Standard MCP servers dump the entire schema to the LLM. For large databases, this consumes thousands of input tokens on every turn. TokenLite's relational graph serves a localized **Auto-Join Context** (target table + direct parent tables + direct child tables).
+
+| Scenario | Standard MCP Pattern | TokenLite | 📉 Savings |
+| :--- | :--- | :--- | :--- |
+| **Mock (50 tables, Enterprise CRM)** | 15,566 tokens | 883 tokens | **94.3%** |
+| **Live (7 tables, Test DB)** | 1,892 tokens | 257 tokens | **86.4%** |
 
-*   **Generic MCP Schema Dump:** 611 tokens
-*   **TokenLite Relational Graph:** 252 tokens
-*   **📉 Schema Input Savings:** **58.7%** (up to **90%** on larger enterprise schemas)
+Savings scale with the number of tables: the more tables in the database, the higher the savings because the standard pattern dumps all of them while TokenLite only fetches the target + 1-hop relationships.
 
 ### 2. Query Result Payloads (Output Tokens)
 TokenLite converts raw database rows to a dense, structured CSV layout. This avoids JSON syntax overhead (brackets, braces, repeated keys) and compresses the output payload returned to the LLM.
 
-| Rows Returned | Generic MCP JSON (Tokens) | TokenLite CSV (Tokens) | 📉 Output Savings (%) |
+**Mock data** (varied: NULLs, long descriptions, mixed lengths):
+
+| Rows Returned | Standard MCP Pattern (Tokens) | TokenLite CSV (Tokens) | 📉 Output Savings (%) |
+| :--- | :--- | :--- | :--- |
+| **10 rows** | 1,167 | 592 | **49.3%** |
+| **50 rows** | 5,805 | 2,875 | **50.5%** |
+| **100 rows** | 11,607 | 5,734 | **50.6%** |
+| **500 rows** | 57,998 | 28,578 | **50.7%** |
+
+**Live data** (real MySQL test database with NULLs, ENUMs, variable-length text):
+
+| Rows Returned | Standard MCP Pattern (Tokens) | TokenLite CSV (Tokens) | 📉 Output Savings (%) |
 | :--- | :--- | :--- | :--- |
-| **10 rows** | 1,153 | 590 | **48.8%** |
-| **50 rows** | 5,764 | 2,861 | **50.3%** |
-| **100 rows** | 11,527 | 5,699 | **50.5%** |
-| **500 rows** | 57,635 | 28,407 | **50.7%** |
+| **10 rows** | 1,007 | 575 | **42.9%** |
+| **50 rows** | 5,029 | 2,845 | **43.4%** |
+| **100 rows** | 10,071 | 5,699 | **43.4%** |
+| **500 rows** | 50,327 | 28,441 | **43.5%** |
 
 ---
 
+## 📊 Logging & Observability
+
+TokenLite uses MCP-native logging via `notifications/message` instead of raw stderr output. Clients that support MCP logging (e.g., MCP Inspector) will receive structured log messages with severity levels, logger names, and JSON data.
+
+**Severity levels** (from least to most severe): `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`.
+
+The server emits logs at `info` level and above by default. Control the minimum level via `MCP_LOG_LEVEL` or dynamically at runtime through the MCP `logging/setLevel` request.
+
+Before the MCP session is established (e.g., during pool initialization), logs fall back to stderr.
+
+---
+
+## 🌐 Advanced Networking & Remote Connections
+
+By design, `tokenlite-mysql-mcp` adheres to the Unix philosophy: it does one thing (AI-driven MySQL interactions) and does it securely via the standard `stdio` transport. It deliberately avoids bloating the codebase with HTTP servers or built-in SSH clients. 
+
+If you need to connect to remote databases or expose this server over the network, here are the recommended, enterprise-grade alternatives:
+
+### 1. Connecting to Remote Databases (SSH Tunnels)
+Instead of embedding SSH libraries, we recommend using native OS tunnels. This is much more secure, respects your `~/.ssh/config`, and supports advanced authentication (2FA, hardware keys).
+
+Simply open a terminal and run:
+
+```bash
+ssh -N -L 3306:127.0.0.1:3306 user@your-remote-server.com
+```
+Then, point `tokenlite-mysql-mcp` to `localhost` and port `3306`.
+
+### 2. Exposing the MCP Server over HTTP/Network
+If you need to host this MCP Server in the cloud (AWS, GCP) and have multiple Claude desktop clients connect to it remotely via HTTP/SSE, do not modify this codebase to add Express/HTTP logic. 
+Instead, wrap the process using standard open-source MCP proxies like [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy). This cleanly separates the transport layer security from the AI logic.
+
 ## 🐛 Troubleshooting
 
 **Error: `OptimizerError: Full table scan detected...`**
 The LLM attempted to execute a query that requires scanning thousands of rows without using an index. 
-*Solution*: The LLM will automatically see this error and try to rewrite the query with an indexed `WHERE` clause. If you truly need to scan the whole table, increase `MCP_SAFE_QUERY_MAX_ROWS` in your config.
+*Solution*: Use `explain_query` to see the full EXPLAIN output and understand why the query was blocked. Rewrite the query with an indexed `WHERE` clause. If you truly need to scan the whole table, increase `MCP_SAFE_QUERY_MAX_ROWS` in your config.
 
 **Error: `calling "initialize": invalid character...`**
 This means the MCP JSON-RPC protocol crashed. Ensure you are passing the correct DB credentials and that the database is running and accessible from the machine where the MCP server runs.
 
 ---
 *Built for the AI Engineering era.*
+
+---

package/dist/db/index.js

@@ -1,8 +1,29 @@
 import mysql from 'mysql2/promise';
 import dotenv from 'dotenv';
 import { injectLimitAst, analyzeQueryPlan } from './optimizer.js';
+import { log } from '../utils/logger.js';
 // Supress dotenv logs so they don't corrupt the MCP JSON-RPC stdout stream
 dotenv.config({ quiet: true });
+const MAX_RETRY_ATTEMPTS = parseInt(process.env.MYSQL_RETRY_ATTEMPTS || '3', 10);
+const RETRY_BASE_DELAY_MS = parseInt(process.env.MYSQL_RETRY_DELAY_MS || '1000', 10);
+const QUEUE_LIMIT = parseInt(process.env.MYSQL_QUEUE_LIMIT || '50', 10);
+const RETRYABLE_ERRORS = new Set([
+    'ECONNREFUSED',
+    'PROTOCOL_CONNECTION_LOST',
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ER_CON_COUNT_ERROR',
+]);
+export function isRetryableError(error) {
+    if (RETRYABLE_ERRORS.has(error.code))
+        return true;
+    if (error.message?.includes('Connection lost'))
+        return true;
+    return false;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
 export const pool = mysql.createPool({
     host: process.env.DB_HOST || 'localhost',
     port: parseInt(process.env.DB_PORT || '3306', 10),
@@ -10,33 +31,110 @@ export const pool = mysql.createPool({
     password: process.env.DB_PASSWORD || '',
     database: process.env.DB_NAME || 'test',
     waitForConnections: true,
-    connectionLimit: 10,
-    queueLimit: 0,
-    connectTimeout: 10000 // 10 seconds
+    connectionLimit: parseInt(process.env.MYSQL_CONNECTION_LIMIT || '10', 10),
+    queueLimit: QUEUE_LIMIT,
+    connectTimeout: parseInt(process.env.MYSQL_CONNECT_TIMEOUT || '10000', 10)
+});
+pool.pool.on('enqueue', () => {
+    log("warning", `All connections busy, request queued (limit: ${QUEUE_LIMIT}).`, "pool");
 });
+// Session-Level Defense in Depth
+const allowInsert = process.env.ALLOW_INSERT_OPERATION === 'true';
+const allowUpdate = process.env.ALLOW_UPDATE_OPERATION === 'true';
+const allowDelete = process.env.ALLOW_DELETE_OPERATION === 'true';
+const allowDdl = process.env.ALLOW_DDL_OPERATION === 'true';
+const isStrictReadOnlyMode = !(allowInsert || allowUpdate || allowDelete || allowDdl);
+if (isStrictReadOnlyMode) {
+    pool.on('connection', (connection) => {
+        // At runtime this is a callback connection, despite what TS types say
+        connection.query('SET SESSION TRANSACTION READ ONLY', (err) => {
+            if (err) {
+                log("warning", `Failed to set connection to READ ONLY: ${err.message}`, "pool");
+            }
+        });
+    });
+}
 export function getDbName() {
     return process.env.DB_NAME || 'test';
 }
 /**
- * Executes a safe query with a Timeout.
+ * Executes a safe query with a Timeout and Granular Permissions.
  */
 export async function executeSafeQuery(sql) {
     // AST Validation and Limit Injection
-    const astOptimizedSql = injectLimitAst(sql);
-    // Pre-flight Analysis
-    await analyzeQueryPlan(astOptimizedSql, pool);
-    const [rows] = await pool.query({
+    const { sql: astOptimizedSql, astType } = injectLimitAst(sql);
+    // Permission Enforcement
+    if (astType !== 'select' && astType !== 'show') {
+        const blockedTypes = ['call', 'grant', 'revoke', 'set', 'use'];
+        if (blockedTypes.includes(astType)) {
+            throw new Error(`Security Error: Dangerous operation '${astType}' is strictly prohibited.`);
+        }
+        const allowInsert = process.env.ALLOW_INSERT_OPERATION === 'true';
+        const allowUpdate = process.env.ALLOW_UPDATE_OPERATION === 'true';
+        const allowDelete = process.env.ALLOW_DELETE_OPERATION === 'true';
+        const allowDdl = process.env.ALLOW_DDL_OPERATION === 'true';
+        let isAllowed = false;
+        if ((astType === 'insert' || astType === 'replace') && allowInsert)
+            isAllowed = true;
+        else if (astType === 'update' && allowUpdate)
+            isAllowed = true;
+        else if ((astType === 'delete' || astType === 'truncate') && allowDelete)
+            isAllowed = true;
+        else if (['create', 'alter', 'drop', 'rename'].includes(astType) && allowDdl)
+            isAllowed = true;
+        if (!isAllowed) {
+            throw new Error(`Security Error: Operation '${astType}' is disabled in the server configuration.`);
+        }
+    }
+    // Pre-flight Analysis (Only blocks full table scans on SELECT)
+    if (astType === 'select') {
+        await analyzeQueryPlan(astOptimizedSql, pool);
+    }
+    const rows = await queryWithRetry({
         sql: astOptimizedSql,
-        timeout: 15000
+        timeout: parseInt(process.env.MYSQL_QUERY_TIMEOUT || '15000', 10)
     });
     return rows;
 }
+async function queryWithRetry(opts) {
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRY_ATTEMPTS; attempt++) {
+        try {
+            const [rows] = await pool.query(opts);
+            return rows;
+        }
+        catch (error) {
+            lastError = error;
+            if (!isRetryableError(error)) {
+                throw error;
+            }
+            if (attempt < MAX_RETRY_ATTEMPTS) {
+                const delay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt);
+                log("warning", `Connection error (${error.code}), retrying in ${delay}ms (attempt ${attempt + 1}/${MAX_RETRY_ATTEMPTS})...`, "pool");
+                await sleep(delay);
+            }
+        }
+    }
+    throw lastError;
+}
 export async function pingDb() {
     try {
-        await pool.query('SELECT 1');
+        await queryWithRetry({ sql: 'SELECT 1' });
         return true;
     }
     catch (e) {
         return false;
     }
 }
+/**
+ * Gracefully shuts down the MySQL connection pool.
+ */
+export async function closePool() {
+    try {
+        await pool.end();
+        log("info", "Database connection pool closed gracefully.", "pool");
+    }
+    catch (error) {
+        log("error", `Error closing database connection pool: ${error.message}`, "pool");
+    }
+}

package/dist/db/metadata.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import Fuse from 'fuse.js';
 import dotenv from 'dotenv';
+import { log } from '../utils/logger.js';
 dotenv.config({ quiet: true });
 let metadataCache = {};
 let templatesCache = [];
@@ -11,10 +12,10 @@ export function initMetadata() {
         try {
             const raw = fs.readFileSync(metadataPath, 'utf8');
             metadataCache = JSON.parse(raw);
-            console.error(`[tokenlite-mysql-mcp] Loaded metadata dictionary from ${metadataPath}`);
+            log("info", `Loaded metadata dictionary from ${metadataPath}`, "metadata");
         }
         catch (err) {
-            console.error(`[tokenlite-mysql-mcp] Error loading metadata.json:`, err);
+            log("error", `Error loading metadata.json: ${err}`, "metadata");
         }
     }
     const templatesPath = process.env.MCP_TEMPLATES_PATH;
@@ -27,10 +28,10 @@ export function initMetadata() {
                 threshold: 0.5,
                 ignoreLocation: true
             });
-            console.error(`[tokenlite-mysql-mcp] Loaded ${templatesCache.length} SQL templates from ${templatesPath}`);
+            log("info", `Loaded ${templatesCache.length} SQL templates from ${templatesPath}`, "metadata");
         }
         catch (err) {
-            console.error(`[tokenlite-mysql-mcp] Error loading templates.json:`, err);
+            log("error", `Error loading templates.json: ${err}`, "metadata");
         }
     }
 }

package/dist/db/optimizer.js

@@ -16,11 +16,11 @@ function isBlockingEnabled() {
     return process.env.MCP_SAFE_QUERY_ENABLE_BLOCKING !== 'false';
 }
 /**
- * Parses the SQL query to AST, injects a LIMIT if missing, and returns the modified SQL.
+ * Parses the SQL query to AST, injects a LIMIT if missing for SELECTs, and returns the modified SQL and AST type.
  */
 export function injectLimitAst(sql, maxLimit = 500) {
     if (sql.trim().toUpperCase().startsWith('SHOW')) {
-        return sql;
+        return { sql, astType: 'show' };
     }
     try {
         const astOpt = { database: 'MySQL' };
@@ -32,27 +32,29 @@ export function injectLimitAst(sql, maxLimit = 500) {
             }
             ast = ast[0];
         }
-        if (ast.type !== 'select') {
-            throw new OptimizerError("Security Error: Only SELECT or SHOW statements are allowed.");
-        }
-        if (!ast.limit) {
-            ast.limit = {
-                seperator: "",
-                value: [
-                    { type: 'number', value: maxLimit }
-                ]
-            };
-        }
-        else {
-            // Check if existing limit exceeds maxLimit
-            // @ts-ignore
-            const limitValue = ast.limit.value[0]?.value;
-            if (typeof limitValue === 'number' && limitValue > maxLimit) {
-                // @ts-ignore
-                ast.limit.value[0].value = maxLimit;
+        // @ts-ignore
+        const type = ast.type?.toLowerCase();
+        // Only inject LIMIT and sqlify if it's a SELECT query.
+        // For DML/DDL, we just return the original SQL to avoid parser mangling.
+        if (type === 'select') {
+            const selectAst = ast;
+            if (!selectAst.limit) {
+                selectAst.limit = {
+                    seperator: "",
+                    value: [
+                        { type: 'number', value: maxLimit }
+                    ]
+                };
+            }
+            else {
+                const limitValue = selectAst.limit.value[0]?.value;
+                if (typeof limitValue === 'number' && limitValue > maxLimit) {
+                    selectAst.limit.value[0].value = maxLimit;
+                }
             }
+            return { sql: parser.sqlify(selectAst, astOpt), astType: type };
         }
-        return parser.sqlify(ast, astOpt);
+        return { sql, astType: type };
     }
     catch (e) {
         if (e instanceof OptimizerError) {

package/dist/db/schema.js

@@ -1,5 +1,32 @@
 import { pool, getDbName } from './index.js';
+import { log } from '../utils/logger.js';
 export let schemaGraph = new Map();
+const DDL_CACHE_TTL_MS = parseInt(process.env.MCP_DDL_CACHE_TTL || '60', 10) * 1000;
+const ddlCache = new Map();
+export function invalidateDdlCache() {
+    ddlCache.clear();
+}
+const SAFE_TABLE_NAME = /^[a-zA-Z0-9_]+$/;
+export async function getTableDDL(tableName) {
+    if (!SAFE_TABLE_NAME.test(tableName)) {
+        return null;
+    }
+    const cached = ddlCache.get(tableName);
+    if (cached && Date.now() < cached.expiresAt) {
+        return cached.ddl;
+    }
+    try {
+        const [rows] = await pool.query(`SHOW CREATE TABLE \`${tableName}\``);
+        const ddl = (rows && rows.length > 0)
+            ? (rows[0]['Create Table'] || rows[0]['Create View'])
+            : null;
+        ddlCache.set(tableName, { ddl, expiresAt: Date.now() + DDL_CACHE_TTL_MS });
+        return ddl;
+    }
+    catch (e) {
+        return null;
+    }
+}
 /**
  * Connects to the database and builds the relational graph in-memory.
  * Optimized for low RAM usage by only extracting node names and edges (no DDL/Columns cached).
@@ -79,6 +106,7 @@ export async function buildSchemaGraph() {
             }
         }
     }
+    invalidateDdlCache();
     schemaGraph = newGraph;
-    console.error(`[tokenlite-mysql-mcp] Schema Graph built successfully. Indexed ${schemaGraph.size} tables.`);
+    log("info", `Schema Graph built successfully. Indexed ${schemaGraph.size} tables.`, "schema");
 }

package/dist/index.js

@@ -4,26 +4,53 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { registerExecuteQueryTool } from "./tools/executeQuery.js";
 import { registerSearchSchemaTool } from "./tools/searchSchema.js";
 import { registerRefreshSchemaTool } from "./tools/refreshSchema.js";
-import { registerGetTemplatesTool } from "./tools/getTemplates.js";
+import { registerPingTool } from "./tools/ping.js";
+import { registerExplainQueryTool } from "./tools/explainQuery.js";
+import { registerTemplatesPrompt } from "./prompts/templates.js";
+import { registerTableResources } from "./resources/tables.js";
 import { buildSchemaGraph } from "./db/schema.js";
 import { initMetadata } from "./db/metadata.js";
+import { closePool } from "./db/index.js";
+import { initLogger } from "./utils/logger.js";
 import dotenv from "dotenv";
 dotenv.config({ quiet: true });
 async function main() {
     const server = new McpServer({
         name: "tokenlite-mysql-mcp",
         version: "1.0.0",
+    }, {
+        capabilities: {
+            logging: {},
+        },
     });
+    initLogger(server);
     // Build Semantic Graph on startup
     await buildSchemaGraph();
     // Load Metadata and Templates
     initMetadata();
-    // Register MCP Tools
-    registerSearchSchemaTool(server);
-    registerExecuteQueryTool(server);
-    registerRefreshSchemaTool(server);
-    registerGetTemplatesTool(server);
+    // Generate or use provided tool prefix (dev_, prod_ ...)
+    let prefix = process.env.TOOL_PREFIX;
+    if (!prefix) {
+        const randomStr = Math.random().toString(36).substring(2, 6);
+        prefix = `db_${randomStr}_`;
+    }
+    // Register MCP tools & prompts & resources
+    registerSearchSchemaTool(server, prefix);
+    registerExecuteQueryTool(server, prefix);
+    registerRefreshSchemaTool(server, prefix);
+    registerPingTool(server, prefix);
+    registerExplainQueryTool(server, prefix);
+    registerTemplatesPrompt(server, prefix);
+    registerTableResources(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    const cleanup = async () => {
+        console.error('\n[tokenlite-mysql-mcp] Shutting down server...');
+        await server.close();
+        await closePool();
+        process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
 }
 main().catch(console.error);

package/dist/prompts/templates.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { searchTemplates } from "../db/metadata.js";
+export function registerTemplatesPrompt(server, prefix = "") {
+    server.prompt(`${prefix}query_templates`, "Official company SQL templates for business metrics. Use this as a starting point to avoid writing SQL from scratch.", {
+        query: z.string().optional().describe("Keyword to search for in templates (e.g., 'revenue', 'ltv').")
+    }, ({ query }) => {
+        const results = searchTemplates(query || "");
+        if (results.length === 0) {
+            return {
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: "No SQL templates found matching your query."
+                        }
+                    }
+                ]
+            };
+        }
+        let output = "--- PRE-APPROVED SQL TEMPLATES ---\n\n";
+        for (const t of results) {
+            output += `### ${t.name}\n`;
+            output += `Description: ${t.description}\n`;
+            output += `SQL:\n\`\`\`sql\n${t.sql}\n\`\`\`\n\n`;
+        }
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: output
+                    }
+                }
+            ]
+        };
+    });
+}

package/dist/resources/tables.js

@@ -0,0 +1,50 @@
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { schemaGraph, getTableDDL } from "../db/schema.js";
+import { getTableSemantics } from "../db/metadata.js";
+export function registerTableResources(server) {
+    // List all available tables
+    server.resource("schema", "mysql://schema", { description: "Lists all available tables in the database schema" }, async (uri) => {
+        const tables = Array.from(schemaGraph.keys());
+        if (tables.length === 0) {
+            return {
+                contents: [{
+                        uri: uri.href,
+                        text: "Schema Graph is empty. Make sure the database is connected."
+                    }]
+            };
+        }
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: `Available tables in the database:\n\n${tables.map(t => `- ${t}`).join('\n')}`
+                }]
+        };
+    });
+    // DDL for a specific table
+    server.resource("table", new ResourceTemplate("mysql://tables/{name}", { list: undefined }), { description: "Exposes the SQL DDL and semantic dictionary of a specific table" }, async (uri, { name }) => {
+        const tableName = typeof name === 'string' ? name : String(name);
+        const ddl = await getTableDDL(tableName);
+        if (!ddl) {
+            return {
+                contents: [{
+                        uri: uri.href,
+                        text: `Table '${tableName}' not found or could not fetch DDL.`
+                    }]
+            };
+        }
+        let output = `-- === TABLE: ${tableName} ===\n${ddl};\n`;
+        // Append Semantics if available
+        const semantics = getTableSemantics(tableName);
+        if (Object.keys(semantics).length > 0) {
+            output += `\n/* SEMANTIC DICTIONARY:\n`;
+            output += JSON.stringify(semantics, null, 2);
+            output += `\n*/\n`;
+        }
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: output
+                }]
+        };
+    });
+}

package/dist/tools/executeQuery.js

@@ -2,32 +2,51 @@ import { z } from "zod";
 import { executeSafeQuery } from "../db/index.js";
 import { jsonToCsv } from "../utils/csvFormatter.js";
 export async function handleExecuteQuery({ sql }) {
-    if (!sql.trim().toUpperCase().startsWith("SELECT") && !sql.trim().toUpperCase().startsWith("SHOW")) {
-        return {
-            content: [{ type: "text", text: "Security Error: Only SELECT or SHOW statements are allowed." }],
-            isError: true
-        };
-    }
     try {
-        const rows = await executeSafeQuery(sql);
-        const csvData = jsonToCsv(rows);
-        return {
-            content: [{ type: "text", text: csvData }]
-        };
+        const result = await executeSafeQuery(sql);
+        // If it's a SELECT, result are rows
+        if (Array.isArray(result)) {
+            const csvData = jsonToCsv(result);
+            return {
+                content: [{ type: "text", text: csvData }]
+            };
+        }
+        // If it's a DML/DDL operation, result is a ResultSetHeader object
+        else {
+            const header = result;
+            const message = `Operation executed successfully.\nAffected rows: ${header.affectedRows || 0}` +
+                (header.insertId ? `\nInsert ID: ${header.insertId}` : '') +
+                (header.changedRows ? `\nChanged rows: ${header.changedRows}` : '');
+            return {
+                content: [{ type: "text", text: message }]
+            };
+        }
     }
     catch (error) {
         let errorMessage = error.name === 'OptimizerError' ? error.message : `Database Error: ${error.message}`;
         if (error.code === 'ER_BAD_FIELD_ERROR' || error.message?.includes('Unknown column')) {
             errorMessage += `\n\nHint: If you believe this column exists, the DBA might have just added it. Please call the 'refresh_schema' tool and try again.`;
         }
+        else if (error.code === 'PROTOCOL_SEQUENCE_TIMEOUT' || error.message?.includes('timeout')) {
+            errorMessage += `\n\nHint: The query took too long and was aborted to protect the database (DoS protection). Please optimize your query by using better filters, utilizing indexes, or ask the user to increase the MYSQL_QUERY_TIMEOUT.`;
+        }
         return {
             content: [{ type: "text", text: errorMessage }],
             isError: true
         };
     }
 }
-export function registerExecuteQueryTool(server) {
-    server.tool("execute_safe_query", "Executes a safe SELECT query on the database. Large results are automatically truncated. CRITICAL: NEVER use this tool (e.g., SHOW TABLES or querying information_schema) to understand the database structure. You MUST ALWAYS use the 'search_schema' tool first to understand the relationships and tables before writing any JOIN queries.", {
-        sql: z.string().describe("SQL SELECT statement to execute."),
+export function registerExecuteQueryTool(server, prefix = "") {
+    const allowInsert = process.env.ALLOW_INSERT_OPERATION === 'true';
+    const allowUpdate = process.env.ALLOW_UPDATE_OPERATION === 'true';
+    const allowDelete = process.env.ALLOW_DELETE_OPERATION === 'true';
+    const allowDdl = process.env.ALLOW_DDL_OPERATION === 'true';
+    // If any write operation is enabled, this tool is no longer read-only
+    const isReadOnly = !(allowInsert || allowUpdate || allowDelete || allowDdl);
+    server.tool(`${prefix}execute_safe_query`, "Executes a safe SELECT query on the database. Large results are automatically truncated. CRITICAL: NEVER use this tool (e.g., SHOW TABLES or querying information_schema) to understand the database structure. You MUST ALWAYS use the 'search_schema' tool first to understand the relationships and tables before writing any JOIN queries.", {
+        sql: z.string().max(10000).describe("SQL SELECT statement to execute."),
+    }, {
+        readOnlyHint: isReadOnly,
+        destructiveHint: allowDelete || allowDdl,
     }, handleExecuteQuery);
 }

package/dist/tools/explainQuery.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { pool } from "../db/index.js";
+import { jsonToCsv } from "../utils/csvFormatter.js";
+export async function handleExplainQuery({ sql }) {
+    try {
+        const [rows] = await pool.query(`EXPLAIN ${sql}`);
+        const csv = jsonToCsv(rows);
+        return {
+            content: [{ type: "text", text: csv }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `EXPLAIN Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+}
+export function registerExplainQueryTool(server, prefix = "") {
+    server.tool(`${prefix}explain_query`, "Returns the MySQL EXPLAIN output for a SELECT query. Use this to understand index usage, join types, and row estimates before rewriting a blocked or slow query.", {
+        sql: z.string().max(10000).describe("The SELECT query to analyze."),
+    }, {
+        readOnlyHint: true,
+        idempotentHint: true,
+    }, handleExplainQuery);
+}

package/dist/tools/ping.js

@@ -0,0 +1,37 @@
+import { pool } from "../db/index.js";
+export async function handlePing() {
+    const rawPool = pool.pool;
+    const poolInfo = {
+        active: rawPool._allConnections?.length ?? 0,
+        idle: rawPool._freeConnections?.length ?? 0,
+        queue: rawPool._connectionQueue?.length ?? 0,
+    };
+    try {
+        const [rows] = await pool.query("SELECT VERSION() AS version");
+        const response = {
+            status: "ok",
+            server_version: rows[0]?.version,
+            pool: poolInfo,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+        };
+    }
+    catch (error) {
+        const response = {
+            status: "error",
+            pool: poolInfo,
+            error: error.message,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+            isError: true,
+        };
+    }
+}
+export function registerPingTool(server, prefix = "") {
+    server.tool(`${prefix}ping`, "Health check: verifies the database connection is alive and returns pool stats and server version.", {}, {
+        readOnlyHint: true,
+        openWorldHint: false,
+    }, handlePing);
+}

package/dist/tools/refreshSchema.js

@@ -1,6 +1,6 @@
 import { buildSchemaGraph } from "../db/schema.js";
-export function registerRefreshSchemaTool(server) {
-    server.tool("refresh_schema", "Forces the MCP server to rebuild the internal Schema Graph. Use this if you suspect a DBA recently added a table, column, or foreign key and the search_schema or execute queries are failing.", {}, async () => {
+export function registerRefreshSchemaTool(server, prefix = "") {
+    server.tool(`${prefix}refresh_schema`, "Forces the MCP server to rebuild the internal Schema Graph. Use this if you suspect a DBA recently added a table, column, or foreign key and the search_schema or execute queries are failing.", {}, { readOnlyHint: true, idempotentHint: true }, async () => {
         try {
             await buildSchemaGraph();
             return {

package/dist/tools/searchSchema.js

@@ -1,20 +1,7 @@
 import { z } from "zod";
 import Fuse from "fuse.js";
-import { pool } from "../db/index.js";
-import { schemaGraph } from "../db/schema.js";
+import { schemaGraph, getTableDDL } from "../db/schema.js";
 import { getTableSemantics } from "../db/metadata.js";
-async function getTableDDL(tableName) {
-    try {
-        const [rows] = await pool.query(`SHOW CREATE TABLE \`${tableName}\``);
-        if (rows && rows.length > 0) {
-            return rows[0]['Create Table'] || rows[0]['Create View'];
-        }
-        return null;
-    }
-    catch (e) {
-        return null;
-    }
-}
 export async function handleSearchSchema({ query }) {
     if (schemaGraph.size === 0) {
         return {
@@ -81,13 +68,13 @@ export async function handleSearchSchema({ query }) {
     if (inferredHints.length > 0) {
         output += "\n-- === HEURISTIC GRAPH HINTS ===\n" + inferredHints.join("\n");
     }
-    output += "\n\n/* ⚠️ CRITICAL REMINDER: If you are asked to calculate business metrics (LTV, revenue, etc.), DO NOT write the SQL manually. You MUST use the `get_query_templates` tool first to fetch the official template. */";
+    output += "\n\n/* ⚠️ CRITICAL REMINDER: If you are asked to calculate business metrics (LTV, revenue, etc.), DO NOT write the SQL manually. You MUST use the `query_templates` prompt first to fetch the official template. */";
     return {
         content: [{ type: "text", text: output }]
     };
 }
-export function registerSearchSchemaTool(server) {
-    server.tool("search_schema", "CRITICAL TOOL FOR SCHEMA EXPLORATION: Use this tool FIRST to understand the database structure. Searches for a table and returns its exact SQL DDL, along with the DDL of its direct parent and child tables (Auto-Join Context). Do NOT use execute_safe_query for schema exploration.", {
-        query: z.string().describe("The name of the table or entity to search for (e.g. 'users', 'invoices')."),
-    }, handleSearchSchema);
+export function registerSearchSchemaTool(server, prefix = "") {
+    server.tool(`${prefix}search_schema`, "CRITICAL TOOL FOR SCHEMA EXPLORATION: Use this tool FIRST to understand the database structure. Searches for a table and returns its exact SQL DDL, along with the DDL of its direct parent and child tables (Auto-Join Context). Do NOT use execute_safe_query for schema exploration.", {
+        query: z.string().max(200).describe("The name of the table or entity to search for (e.g. 'users', 'invoices')."),
+    }, { readOnlyHint: true, openWorldHint: false }, handleSearchSchema);
 }

package/dist/utils/logger.js

@@ -0,0 +1,39 @@
+import { SetLevelRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+const SEVERITY_ORDER = [
+    "debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"
+];
+let mcpServer = null;
+let minLevel = process.env.MCP_LOG_LEVEL || "info";
+function severityIndex(level) {
+    return SEVERITY_ORDER.indexOf(level);
+}
+export function initLogger(server) {
+    mcpServer = server;
+    server.server.setRequestHandler(SetLevelRequestSchema, async (request) => {
+        const requested = request.params?.level;
+        if (requested && SEVERITY_ORDER.includes(requested)) {
+            minLevel = requested;
+        }
+        return {};
+    });
+}
+export function getMinLevel() {
+    return minLevel;
+}
+export async function log(level, data, logger) {
+    if (severityIndex(level) < severityIndex(minLevel)) {
+        return;
+    }
+    if (mcpServer) {
+        try {
+            await mcpServer.sendLoggingMessage({ level, data, logger });
+            return;
+        }
+        catch {
+            // MCP session not ready yet, fall through to stderr
+        }
+    }
+    const prefix = logger ? `[${logger}]` : "[tokenlite-mysql-mcp]";
+    const msg = typeof data === "string" ? data : JSON.stringify(data);
+    console.error(`${prefix} [${level}] ${msg}`);
+}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@andezdev/tokenlite-mysql-mcp",
-  "version": "1.0.0",
+  "version": "3.0.0",
+  "mcpName": "io.github.andezdev/tokenlite-mysql-mcp",
   "description": "A secure, efficient, and intelligent MySQL server for the Model Context Protocol",
   "main": "dist/index.js",
   "type": "module",
@@ -39,8 +40,10 @@
   "homepage": "https://github.com/andezdev/tokenlite-mysql-mcp#readme",
   "scripts": {
     "build": "tsc",
+    "prepublishOnly": "npm run build",
     "start": "node dist/index.js",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "inspect-graph": "tsx scripts/inspect-graph.ts",
     "benchmark": "tsx scripts/benchmark.ts",
@@ -59,6 +62,7 @@
     "@commitlint/config-conventional": "^21.0.2",
     "@types/node": "^22.10.1",
     "@types/node-sql-parser": "^1.0.0",
+    "@vitest/coverage-v8": "^4.1.8",
     "husky": "^9.1.7",
     "js-tiktoken": "^1.0.21",
     "ts-node": "^10.9.2",

package/dist/tools/getTemplates.js

@@ -1,24 +0,0 @@
-import { z } from "zod";
-import { searchTemplates } from "../db/metadata.js";
-export function handleGetTemplates({ query }) {
-    const results = searchTemplates(query || "");
-    if (results.length === 0) {
-        return {
-            content: [{ type: "text", text: "No SQL templates found matching your query." }]
-        };
-    }
-    let output = "--- PRE-APPROVED SQL TEMPLATES ---\n\n";
-    for (const t of results) {
-        output += `### ${t.name}\n`;
-        output += `Description: ${t.description}\n`;
-        output += `SQL:\n\`\`\`sql\n${t.sql}\n\`\`\`\n\n`;
-    }
-    return {
-        content: [{ type: "text", text: output }]
-    };
-}
-export function registerGetTemplatesTool(server) {
-    server.tool("get_query_templates", "NEVER write SQL for business metrics (like LTV, Revenue, Performance) manually. YOU MUST ALWAYS use this tool first to retrieve the official company SQL template. Pass a keyword to search, or leave empty to list all templates.", {
-        query: z.string().optional().describe("Keyword to search for in templates (e.g., 'revenue', 'ltv')."),
-    }, handleGetTemplates);
-}