@andezdev/tokenlite-mysql-mcp 1.0.0

package/AGENTS.md

@@ -0,0 +1,51 @@
+# 🤖 AI Agents Guide: TokenLite MySQL MCP
+
+> **Notice to LLMs, Agents, and Coding Assistants:**
+> If you are reading this file, you have been connected to the TokenLite MySQL MCP Server. This server is heavily protected and optimized to prevent hallucinations, reduce context window bloat, and block dangerous operations. 
+> 
+> **You MUST follow the rules below strictly.**
+
+## 🚨 Golden Rules
+
+1. **NEVER use `SHOW TABLES` or `DESCRIBE` manually.**
+   - **Rule**: You MUST use the `search_schema` tool instead. 
+   - **Why**: `search_schema` provides a compressed, heuristic-based Graph (Auto-Join Context) that gives you the DDL of the requested table *and* its implicitly related tables. It also injects business semantics from `metadata.json`.
+
+2. **NEVER manually query `information_schema`.**
+   - **Rule**: If a query fails because of a missing column or table (e.g., `ER_BAD_FIELD_ERROR`), you MUST use the `refresh_schema` tool to rebuild the internal graph, and then use `search_schema` again. Do not attempt to query `information_schema` directly.
+
+3. **NEVER write business metrics SQL manually.**
+   - **Rule**: Before writing analytical SQL (e.g., LTV, Revenue, Active Users, Performance), you MUST query the `get_query_templates` tool.
+   - **Why**: The company has predefined, vetted SQL templates. Hallucinating metrics leads to incorrect dashboards.
+
+4. **DO NOT add `LIMIT` to your exploratory queries.**
+   - **Rule**: When using `execute_safe_query`, the server will automatically inject a `LIMIT` (default 500) at the AST level. Do not manually append `LIMIT` unless you need a very specific offset pagination.
+
+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).
+
+---
+
+## 🛠 Available MCP Tools
+
+### `search_schema`
+**Use for:** Understanding the database structure.
+**Arguments:** `query` (string) - The name of the table you want to inspect.
+**Returns:** The SQL DDL of the matched table, the DDL of its Parent/Child tables, and Business Semantics.
+
+### `execute_safe_query`
+**Use for:** Running `SELECT` statements against the database.
+**Arguments:** `sql` (string) - The SQL query to execute.
+**Returns:** A compressed Markdown CSV table containing the results.
+**Note:** This tool runs your SQL through an AST parser to inject limits, and an `EXPLAIN` planner to block unindexed heavy scans.
+
+### `get_query_templates`
+**Use for:** Retrieving pre-approved SQL for complex calculations.
+**Arguments:** `query` (string) - A keyword like 'revenue', 'ltv', or leave empty.
+**Returns:** Vetted SQL templates that you can execute via `execute_safe_query`.
+
+### `refresh_schema`
+**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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio Hernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# TokenLite MySQL MCP
+
+[![npm version](https://badge.fury.io/js/@andezdev%2Ftokenlite-mysql-mcp.svg)](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**.
+
+---
+
+## 🌟 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.
+
+---
+
+## 📋 Requirements
+
+- Node.js v20 or higher
+- MySQL 5.7 or higher (MySQL 8.0+ recommended)
+- A MySQL user with `SELECT` and `SHOW VIEW` privileges.
+
+---
+
+## 🚀 Installation & Usage
+
+You can use this MCP server with any compatible client. Below are the configurations for the most popular ones.
+
+### 1. Claude Desktop
+
+Edit your `claude_desktop_config.json` (usually located at `%APPDATA%\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) and add the following:
+
+**Using NPX (Recommended)**
+```json
+{
+  "mcpServers": {
+    "tokenlite-mysql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@andezdev/tokenlite-mysql-mcp"
+      ],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_PORT": "3306",
+        "DB_USER": "your_db_user",
+        "DB_PASSWORD": "your_password",
+        "DB_NAME": "your_database",
+        "MCP_SAFE_QUERY_MAX_ROWS": "1000",
+        "MCP_SAFE_QUERY_ENABLE_BLOCKING": "true"
+      }
+    }
+  }
+}
+```
+
+### 2. Claude Code (CLI)
+
+You can easily integrate this server globally into Claude Code:
+
+```bash
+claude mcp add tokenlite_mysql \
+  -e DB_HOST="127.0.0.1" \
+  -e DB_PORT="3306" \
+  -e DB_USER="root" \
+  -e DB_PASSWORD="your_password" \
+  -e DB_NAME="your_database" \
+  -- npx -y @andezdev/tokenlite-mysql-mcp
+```
+
+### 3. Cursor IDE
+
+To use within Cursor IDE:
+1. Open Cursor Settings > Features > MCP.
+2. Click **+ Add New MCP Server**.
+3. Set the Type to `command`.
+4. Name it `tokenlite-mysql`.
+5. Set the command to:
+   ```bash
+   npx -y @andezdev/tokenlite-mysql-mcp
+   ```
+*(Note: Cursor handles environment variables directly in the IDE UI, make sure to add your DB credentials there).*
+
+---
+
+## ⚙️ Environment Variables Reference
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `DB_HOST` | MySQL Host address | `localhost` | No |
+| `DB_PORT` | MySQL Port | `3306` | No |
+| `DB_USER` | MySQL Username | `root` | No |
+| `DB_PASSWORD` | MySQL Password | `''` | No |
+| `DB_NAME` | MySQL Database name | `test` | Yes |
+| `MCP_SAFE_QUERY_MAX_ROWS` | Threshold for EXPLAIN to block unindexed Full Table Scans. | `1000` | No |
+| `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 |
+
+---
+
+## 🛡️ Business Intelligence Features (Opt-in)
+
+TokenLite can teach the LLM about your company's business rules. To enable this, map the absolute paths of two JSON files via `.env` or your MCP client config:
+
+### `metadata.json` (Semantic Dictionary)
+Translate integer statuses or internal jargon so the LLM understands the data.
+```json
+{
+  "orders.status": {
+    "pending": "The order is waiting for payment validation",
+    "shipped": "The order has left the warehouse"
+  }
+}
+```
+
+### `templates.json` (Pre-approved SQL)
+Stop the LLM from hallucinating complex metrics by providing vetted templates.
+```json
+[
+  {
+    "name": "Customer Lifetime Value (LTV)",
+    "description": "Calculates total revenue generated by delivered orders per customer.",
+    "sql": "SELECT c.id, SUM(oi.price) FROM customers c JOIN orders o... WHERE o.status='delivered'"
+  }
+]
+```
+
+---
+
+## 📈 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.
+
+To run the benchmark in your own environment:
+```bash
+npm run benchmark
+```
+
+### 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).
+
+*   **Generic MCP Schema Dump:** 611 tokens
+*   **TokenLite Relational Graph:** 252 tokens
+*   **📉 Schema Input Savings:** **58.7%** (up to **90%** on larger enterprise schemas)
+
+### 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 (%) |
+| :--- | :--- | :--- | :--- |
+| **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%** |
+
+---
+
+## 🐛 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.
+
+**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

@@ -0,0 +1,42 @@
+import mysql from 'mysql2/promise';
+import dotenv from 'dotenv';
+import { injectLimitAst, analyzeQueryPlan } from './optimizer.js';
+// Supress dotenv logs so they don't corrupt the MCP JSON-RPC stdout stream
+dotenv.config({ quiet: true });
+export const pool = mysql.createPool({
+    host: process.env.DB_HOST || 'localhost',
+    port: parseInt(process.env.DB_PORT || '3306', 10),
+    user: process.env.DB_USER || 'root',
+    password: process.env.DB_PASSWORD || '',
+    database: process.env.DB_NAME || 'test',
+    waitForConnections: true,
+    connectionLimit: 10,
+    queueLimit: 0,
+    connectTimeout: 10000 // 10 seconds
+});
+export function getDbName() {
+    return process.env.DB_NAME || 'test';
+}
+/**
+ * Executes a safe query with a Timeout.
+ */
+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({
+        sql: astOptimizedSql,
+        timeout: 15000
+    });
+    return rows;
+}
+export async function pingDb() {
+    try {
+        await pool.query('SELECT 1');
+        return true;
+    }
+    catch (e) {
+        return false;
+    }
+}

package/dist/db/metadata.js

@@ -0,0 +1,63 @@
+import fs from 'fs';
+import Fuse from 'fuse.js';
+import dotenv from 'dotenv';
+dotenv.config({ quiet: true });
+let metadataCache = {};
+let templatesCache = [];
+let templateSearcher = null;
+export function initMetadata() {
+    const metadataPath = process.env.MCP_METADATA_PATH;
+    if (metadataPath && fs.existsSync(metadataPath)) {
+        try {
+            const raw = fs.readFileSync(metadataPath, 'utf8');
+            metadataCache = JSON.parse(raw);
+            console.error(`[tokenlite-mysql-mcp] Loaded metadata dictionary from ${metadataPath}`);
+        }
+        catch (err) {
+            console.error(`[tokenlite-mysql-mcp] Error loading metadata.json:`, err);
+        }
+    }
+    const templatesPath = process.env.MCP_TEMPLATES_PATH;
+    if (templatesPath && fs.existsSync(templatesPath)) {
+        try {
+            const raw = fs.readFileSync(templatesPath, 'utf8');
+            templatesCache = JSON.parse(raw);
+            templateSearcher = new Fuse(templatesCache, {
+                keys: ['name', 'description'],
+                threshold: 0.5,
+                ignoreLocation: true
+            });
+            console.error(`[tokenlite-mysql-mcp] Loaded ${templatesCache.length} SQL templates from ${templatesPath}`);
+        }
+        catch (err) {
+            console.error(`[tokenlite-mysql-mcp] Error loading templates.json:`, err);
+        }
+    }
+}
+/**
+ * Extracts all semantic definitions relevant to a specific table.
+ * Example: if metadata has "orders.status", and tableName is "orders", it returns that chunk.
+ */
+export function getTableSemantics(tableName) {
+    const semantics = {};
+    const prefix = `${tableName}.`;
+    for (const key of Object.keys(metadataCache)) {
+        if (key.startsWith(prefix) || key === tableName) {
+            semantics[key] = metadataCache[key];
+        }
+    }
+    return semantics;
+}
+/**
+ * Performs a fuzzy search on the loaded templates.
+ */
+export function searchTemplates(query) {
+    if (!templateSearcher)
+        return [];
+    // If query is empty, return all (capped to a safe limit, e.g., 10)
+    if (!query.trim()) {
+        return templatesCache.slice(0, 10);
+    }
+    const results = templateSearcher.search(query);
+    return results.map(r => r.item);
+}

package/dist/db/optimizer.js

@@ -0,0 +1,92 @@
+import pkg from 'node-sql-parser';
+const { Parser } = pkg;
+export class OptimizerError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'OptimizerError';
+        this.code = code;
+    }
+}
+const parser = new Parser();
+function getMaxRows() {
+    return process.env.MCP_SAFE_QUERY_MAX_ROWS ? parseInt(process.env.MCP_SAFE_QUERY_MAX_ROWS, 10) : 1000;
+}
+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.
+ */
+export function injectLimitAst(sql, maxLimit = 500) {
+    if (sql.trim().toUpperCase().startsWith('SHOW')) {
+        return sql;
+    }
+    try {
+        const astOpt = { database: 'MySQL' };
+        let ast = parser.astify(sql, astOpt);
+        // AST can be an array if multiple statements are provided.
+        if (Array.isArray(ast)) {
+            if (ast.length > 1) {
+                throw new OptimizerError("Security Error: Multiple statements are not allowed.");
+            }
+            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;
+            }
+        }
+        return parser.sqlify(ast, astOpt);
+    }
+    catch (e) {
+        if (e instanceof OptimizerError) {
+            throw e;
+        }
+        throw new OptimizerError(`SQL Syntax Error or Unsupported Feature: ${e.message}`);
+    }
+}
+/**
+ * Analyzes the query using EXPLAIN. If a Full Table Scan (type: ALL) is detected
+ * on a table with more rows than MAX_ROWS, it blocks the query.
+ */
+export async function analyzeQueryPlan(sql, pool) {
+    if (!isBlockingEnabled())
+        return;
+    if (sql.trim().toUpperCase().startsWith('SHOW'))
+        return;
+    try {
+        const [planRows] = await pool.query(`EXPLAIN ${sql}`);
+        const maxRows = getMaxRows();
+        for (const row of planRows) {
+            // In standard EXPLAIN, row.type is the join type. 'ALL' means full table scan.
+            if (row.type && row.type.toUpperCase() === 'ALL') {
+                const estimatedRows = parseInt(row.rows, 10);
+                if (!isNaN(estimatedRows) && estimatedRows > maxRows) {
+                    throw new OptimizerError(`Full table scan detected on table '${row.table}'. Estimated rows: ${estimatedRows}. Please add an indexed filter (e.g., a specific ID) to your WHERE clause.`);
+                }
+            }
+        }
+    }
+    catch (e) {
+        if (e instanceof OptimizerError) {
+            throw e;
+        }
+        throw new OptimizerError(`Query Analysis Error: ${e.message}`, e.code);
+    }
+}

package/dist/db/schema.js

@@ -0,0 +1,84 @@
+import { pool, getDbName } from './index.js';
+export let schemaGraph = new Map();
+/**
+ * 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).
+ */
+export async function buildSchemaGraph() {
+    const dbName = getDbName();
+    const newGraph = new Map();
+    // Fetch all tables
+    const [tables] = await pool.query(`SELECT TABLE_NAME FROM information_schema.tables WHERE TABLE_SCHEMA = ? AND TABLE_TYPE = 'BASE TABLE'`, [dbName]);
+    const tableNames = new Set();
+    for (const row of tables) {
+        tableNames.add(row.TABLE_NAME);
+        newGraph.set(row.TABLE_NAME, {
+            name: row.TABLE_NAME,
+            foreignKeys: []
+        });
+    }
+    // Fetch Explicit Foreign Keys
+    const [fks] = await pool.query(`SELECT 
+            TABLE_NAME, 
+            COLUMN_NAME, 
+            REFERENCED_TABLE_NAME, 
+            REFERENCED_COLUMN_NAME 
+         FROM information_schema.key_column_usage 
+         WHERE TABLE_SCHEMA = ? AND REFERENCED_TABLE_NAME IS NOT NULL`, [dbName]);
+    const explicitFkSignatures = new Set();
+    for (const row of fks) {
+        const tableNode = newGraph.get(row.TABLE_NAME);
+        if (tableNode) {
+            tableNode.foreignKeys.push({
+                columnName: row.COLUMN_NAME,
+                referencedTable: row.REFERENCED_TABLE_NAME,
+                referencedColumn: row.REFERENCED_COLUMN_NAME,
+                isHeuristic: false
+            });
+            // Keep a signature to avoid duplicating with heuristics
+            explicitFkSignatures.add(`${row.TABLE_NAME}.${row.COLUMN_NAME}`);
+        }
+    }
+    // The Heuristic Engine: Fetch columns that end with '_id'
+    // This is extremely lightweight because we filter at the DB engine level.
+    const [idColumns] = await pool.query(`SELECT TABLE_NAME, COLUMN_NAME 
+         FROM information_schema.columns 
+         WHERE TABLE_SCHEMA = ? AND COLUMN_NAME LIKE '%\\_id'`, [dbName]);
+    for (const row of idColumns) {
+        const tableName = row.TABLE_NAME;
+        const columnName = row.COLUMN_NAME;
+        const signature = `${tableName}.${columnName}`;
+        if (explicitFkSignatures.has(signature)) {
+            continue; // Already an explicit FK, skip heuristic
+        }
+        // Try to guess the target table name. e.g. 'company_id' -> 'company' or 'companies'
+        const baseName = columnName.slice(0, -3); // remove '_id'
+        let targetTable = null;
+        if (tableNames.has(baseName)) {
+            targetTable = baseName;
+        }
+        else if (tableNames.has(baseName + 's')) {
+            targetTable = baseName + 's';
+        }
+        else if (tableNames.has(baseName + 'es')) {
+            targetTable = baseName + 'es';
+        }
+        else if (baseName.endsWith('y') && tableNames.has(baseName.slice(0, -1) + 'ies')) {
+            // company -> companies
+            targetTable = baseName.slice(0, -1) + 'ies';
+        }
+        if (targetTable) {
+            const tableNode = newGraph.get(tableName);
+            if (tableNode) {
+                tableNode.foreignKeys.push({
+                    columnName: columnName,
+                    referencedTable: targetTable,
+                    referencedColumn: 'id', // assumption
+                    isHeuristic: true
+                });
+            }
+        }
+    }
+    schemaGraph = newGraph;
+    console.error(`[tokenlite-mysql-mcp] Schema Graph built successfully. Indexed ${schemaGraph.size} tables.`);
+}

package/dist/db/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+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 { buildSchemaGraph } from "./db/schema.js";
+import { initMetadata } from "./db/metadata.js";
+import dotenv from "dotenv";
+dotenv.config({ quiet: true });
+async function main() {
+    const server = new McpServer({
+        name: "tokenlite-mysql-mcp",
+        version: "1.0.0",
+    });
+    // Build Semantic Graph on startup
+    await buildSchemaGraph();
+    // Load Metadata and Templates
+    initMetadata();
+    // Register MCP Tools
+    registerSearchSchemaTool(server);
+    registerExecuteQueryTool(server);
+    registerRefreshSchemaTool(server);
+    registerGetTemplatesTool(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/dist/server.js

@@ -0,0 +1,11 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerExecuteQueryTool } from "./tools/executeQuery.js";
+import { registerSearchSchemaTool } from "./tools/searchSchema.js";
+import { registerRefreshSchemaTool } from "./tools/refreshSchema.js";
+export const server = new McpServer({
+    name: "tokenlite-mysql-server",
+    version: "1.0.0",
+});
+registerExecuteQueryTool(server);
+registerSearchSchemaTool(server);
+registerRefreshSchemaTool(server);

package/dist/tools/executeQuery.js

@@ -0,0 +1,33 @@
+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 }]
+        };
+    }
+    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.`;
+        }
+        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."),
+    }, handleExecuteQuery);
+}

package/dist/tools/getTemplates.js

@@ -0,0 +1,24 @@
+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);
+}

package/dist/tools/refreshSchema.js

@@ -0,0 +1,17 @@
+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 () => {
+        try {
+            await buildSchemaGraph();
+            return {
+                content: [{ type: "text", text: "Schema Graph rebuilt successfully. You can now use search_schema to explore the updated relationships." }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Failed to rebuild schema graph: ${error.message}` }],
+                isError: true
+            };
+        }
+    });
+}

package/dist/tools/searchSchema.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import Fuse from "fuse.js";
+import { pool } from "../db/index.js";
+import { schemaGraph } 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 {
+            content: [{ type: "text", text: "Schema Graph is empty. Make sure the database is connected." }],
+            isError: true
+        };
+    }
+    // Search for the table
+    const tableNodes = Array.from(schemaGraph.values());
+    const fuse = new Fuse(tableNodes, {
+        keys: ["name"],
+        threshold: 0.4 // somewhat fuzzy
+    });
+    const results = fuse.search(query);
+    if (results.length === 0) {
+        return {
+            content: [{ type: "text", text: `No table found matching '${query}'. Use refresh_schema() if you believe it was recently added.` }],
+            isError: true
+        };
+    }
+    const targetTable = results[0].item;
+    // Traversal: Find Parent tables (the tables targetTable points to)
+    const parentTableNames = new Set();
+    const inferredHints = [];
+    for (const fk of targetTable.foreignKeys) {
+        parentTableNames.add(fk.referencedTable);
+        if (fk.isHeuristic) {
+            inferredHints.push(`/* INFERRED PARENT: \`${targetTable.name}\`.\`${fk.columnName}\` -> \`${fk.referencedTable}\`.\`${fk.referencedColumn}\` */`);
+        }
+    }
+    // Traversal: Find Child tables (tables that point to targetTable)
+    const childTableNames = new Set();
+    for (const node of tableNodes) {
+        for (const fk of node.foreignKeys) {
+            if (fk.referencedTable === targetTable.name) {
+                childTableNames.add(node.name);
+                if (fk.isHeuristic) {
+                    inferredHints.push(`/* INFERRED CHILD: \`${node.name}\`.\`${fk.columnName}\` -> \`${targetTable.name}\`.\`${fk.referencedColumn}\` */`);
+                }
+            }
+        }
+    }
+    // Fetch DDLs dynamically
+    const tablesToFetch = [targetTable.name, ...parentTableNames, ...childTableNames];
+    const ddls = [];
+    for (const tableName of tablesToFetch) {
+        const ddl = await getTableDDL(tableName);
+        if (ddl) {
+            let header = tableName === targetTable.name
+                ? `-- === MATCHED TABLE ===\n`
+                : `-- === RELATED TABLE ===\n`;
+            let tableStr = header + ddl + ";\n";
+            // Append Semantics
+            const semantics = getTableSemantics(tableName);
+            if (Object.keys(semantics).length > 0) {
+                tableStr += `/* SEMANTIC DICTIONARY:\n`;
+                tableStr += JSON.stringify(semantics, null, 2);
+                tableStr += `\n*/\n`;
+            }
+            ddls.push(tableStr);
+        }
+    }
+    let output = ddls.join("\n");
+    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. */";
+    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);
+}

package/dist/utils/csvFormatter.js

@@ -0,0 +1,30 @@
+/**
+ * Converts an array of JSON objects (typically returned by MySQL)
+ * to a tabular CSV format to save LLM tokens.
+ */
+export function jsonToCsv(data) {
+    if (!data || data.length === 0) {
+        return "No data returned.";
+    }
+    const headers = Object.keys(data[0]);
+    const csvRows = [];
+    // Add headers
+    csvRows.push(headers.join(","));
+    // Add rows
+    for (const row of data) {
+        const values = headers.map(header => {
+            const val = row[header];
+            if (val === null || val === undefined) {
+                return "";
+            }
+            // If the value contains commas, quotes, or newlines, it must be escaped
+            const strVal = String(val);
+            if (strVal.includes(",") || strVal.includes("\"") || strVal.includes("\n")) {
+                return `"${strVal.replace(/"/g, "\"\"")}"`;
+            }
+            return strVal;
+        });
+        csvRows.push(values.join(","));
+    }
+    return csvRows.join("\n");
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@andezdev/tokenlite-mysql-mcp",
+  "version": "1.0.0",
+  "description": "A secure, efficient, and intelligent MySQL server for the Model Context Protocol",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "tokenlite-mysql-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Antonio Hernandez",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "mysql",
+    "model-context-protocol",
+    "claude",
+    "ai",
+    "llm",
+    "database",
+    "sql",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andezdev/tokenlite-mysql-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/andezdev/tokenlite-mysql-mcp/issues"
+  },
+  "homepage": "https://github.com/andezdev/tokenlite-mysql-mcp#readme",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "inspect-graph": "tsx scripts/inspect-graph.ts",
+    "benchmark": "tsx scripts/benchmark.ts",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "dotenv": "^16.4.7",
+    "fuse.js": "^7.4.0",
+    "mysql2": "^3.12.0",
+    "node-sql-parser": "^5.4.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
+    "@types/node": "^22.10.1",
+    "@types/node-sql-parser": "^1.0.0",
+    "husky": "^9.1.7",
+    "js-tiktoken": "^1.0.21",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.7"
+  }
+}