@imenam/database-mcp 1.0.9

package/README.md

@@ -0,0 +1,157 @@
+# Custom MySQL MCP
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI agents (Cursor, Claude Desktop, etc.) interact with a MySQL, PostgreSQL, or SQLite database — query data, inspect schemas, and optionally execute write operations. Comes with a persistent GUI (tabs, settings) accessible through the central proxy.
+
+---
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `list_tables` | List all tables in the connected database |
+| `describe_table` | Get the schema of a table (columns, types, keys, defaults) |
+| `execute_query` | Execute a read-only `SELECT` query and return results |
+| `execute_write` | Execute a write statement (`INSERT`, `UPDATE`, `DELETE`, `ALTER`…) — requires `MYSQL_MCP_ALLOW_WRITE=true` |
+
+---
+
+## Configuration in Cursor
+
+Add the following to your Cursor MCP configuration file (`~/.cursor/mcp.json` or your project's `.cursor/mcp.json`):
+
+### Via HTTP proxy (database-exposer)
+
+Use this mode when you have a `database-exposer` instance deployed. No database credentials needed locally.
+
+```json
+{
+  "mcpServers": {
+    "my-database": {
+      "command": "npx",
+      "args": ["-y", "custom-mysql-mcp"],
+      "env": {
+        "DB_PROXY_URL": "https://data.example.com",
+        "DB_PROXY_TOKEN": "<your-query-token>"
+      }
+    }
+  }
+}
+```
+
+### Via NPX (direct connection)
+
+```json
+{
+  "mcpServers": {
+    "custom-mysql-mcp": {
+      "command": "npx",
+      "args": ["-y", "custom-mysql-mcp"],
+      "env": {
+        "MYSQL_MCP_HOST": "127.0.0.1",
+        "MYSQL_MCP_PORT": "3306",
+        "MYSQL_MCP_DATABASE": "my_database",
+        "MYSQL_MCP_USERNAME": "my_user",
+        "MYSQL_MCP_PASSWORD": "my_password",
+        "MYSQL_MCP_ALLOW_WRITE": "false",
+        "PROXY_URL": "http://localhost:4242",
+        "CONFIG_PATH": "/path/to/persistent/config-dir"
+      }
+    }
+  }
+}
+```
+
+### Via local install
+
+```json
+{
+  "mcpServers": {
+    "custom-mysql-mcp": {
+      "command": "node",
+      "args": ["/absolute/path/to/custom-mysql-mcp/dist/index.js"],
+      "env": {
+        "MYSQL_MCP_HOST": "127.0.0.1",
+        "MYSQL_MCP_PORT": "3306",
+        "MYSQL_MCP_DATABASE": "my_database",
+        "MYSQL_MCP_USERNAME": "my_user",
+        "MYSQL_MCP_PASSWORD": "my_password",
+        "MYSQL_MCP_ALLOW_WRITE": "false",
+        "PROXY_URL": "http://localhost:4242",
+        "CONFIG_PATH": "/path/to/persistent/config-dir"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Environment Variables
+
+### HTTP Proxy mode (database-exposer)
+
+If `DB_PROXY_URL` and `DB_PROXY_TOKEN` are both set, the MCP routes all queries through an HTTP REST endpoint instead of connecting directly to the database. This mode is fully transparent to the agent — the same tools are available.
+
+| Variable | Required | Description |
+|---|---|---|
+| `DB_PROXY_URL` | Yes† | Base URL of the `database-exposer` instance (e.g. `https://data.example.com`) |
+| `DB_PROXY_TOKEN` | Yes† | Bearer token for the `database-exposer` API |
+
+> **†** Both variables must be set together to activate proxy mode. If only one is present, the server falls back to direct connection mode.
+
+> **Read-only:** The `database-exposer` API only accepts `SELECT`, `SHOW`, `DESCRIBE`, and `EXPLAIN` queries. `execute_write` is automatically disabled in proxy mode.
+
+### Direct connection
+
+| Variable | Required | Description |
+|---|---|---|
+| `MYSQL_MCP_DB_TYPE` | No | Database driver: `mysql` (default), `postgres`, or `sqlite` |
+| `MYSQL_MCP_HOST` | Yes* | Database server hostname or IP address |
+| `MYSQL_MCP_PORT` | Yes* | Database server port (`3306` for MySQL, `5432` for Postgres) |
+| `MYSQL_MCP_DATABASE` | Yes* | Name of the database to connect to |
+| `MYSQL_MCP_USERNAME` | Yes* | Database username |
+| `MYSQL_MCP_PASSWORD` | Yes* | Database password |
+| `MYSQL_MCP_SQLITE_PATH` | Yes** | Path to the SQLite file (`**` required only when `MYSQL_MCP_DB_TYPE=sqlite`) |
+| `MYSQL_MCP_ALLOW_WRITE` | No | Set to `true` to enable write operations. Defaults to **read-only**. |
+| `MYSQL_MCP_DEFAULT_MAX_ROWS` | No | Maximum rows returned by MCP tools. Defaults to `10`. |
+| `MYSQL_MCP_DEFAULT_MAX_CELL_LENGTH` | No | Max characters per cell before truncation. Defaults to `50`. |
+
+> **Security note:** Write operations are disabled by default. You must explicitly set `MYSQL_MCP_ALLOW_WRITE=true` to allow `INSERT`, `UPDATE`, `DELETE`, and other write statements.
+
+> **Result limits:** By default, `execute_query` and `execute_write` return at most 10 rows, with cell values truncated at 50 characters. The response includes a `meta.was_row_limited` field to indicate when more results are available. These limits can be overridden per call via the `max_rows` and `max_cell_length` parameters, or globally via environment variables.
+
+### GUI & proxy
+
+| Variable | Required | Description |
+|---|---|---|
+| `PROXY_URL` | No | URL of the central proxy. Required to enable the GUI (e.g. `http://localhost:4242`). |
+| `PROXY_APP_PATH` | No | Registration path in the proxy. Defaults to `/mysql-mcp`. |
+| `PROXY_APP_NAME` | No | Display name in the proxy dashboard. Defaults to `MySQL MCP`. |
+| `CONFIG_PATH` | No | Directory where the GUI config file (`config.json`) is stored. Can be absolute or relative to the project root. Defaults to `<project root>/data/`. |
+| `MCP_LOG_DIR` | No | Directory where log files are written. |
+
+> **Config persistence:** The GUI saves open tabs (name + SQL content) and general settings (max results) to `config.json` inside `CONFIG_PATH`. Reloading the page or restarting the server restores the exact state. Set `CONFIG_PATH` to a directory outside the MCP installation folder so data survives reinstalls and `npx` cache clears.
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode (no build required)
+npm run dev
+
+# Build for production
+npm run build
+
+# Start the compiled server
+npm start
+```
+
+---
+
+## License
+
+ISC

package/dist/db.js

@@ -0,0 +1,257 @@
+import mysql from 'mysql2/promise';
+import pg from 'pg';
+import Database from 'better-sqlite3';
+function getDbConfig() {
+    const host = process.env.MYSQL_MCP_HOST;
+    const port = process.env.MYSQL_MCP_PORT;
+    const database = process.env.MYSQL_MCP_DATABASE;
+    const user = process.env.MYSQL_MCP_USERNAME;
+    const password = process.env.MYSQL_MCP_PASSWORD;
+    if (!host || !port || !database || !user || !password) {
+        throw new Error('Missing required environment variables: MYSQL_MCP_HOST, MYSQL_MCP_PORT, MYSQL_MCP_DATABASE, MYSQL_MCP_USERNAME, MYSQL_MCP_PASSWORD');
+    }
+    return {
+        host,
+        port: parseInt(port, 10),
+        database,
+        user,
+        password,
+    };
+}
+function getDbType() {
+    const t = process.env.MYSQL_MCP_DB_TYPE?.toLowerCase();
+    if (!t || t === 'mysql')
+        return 'mysql';
+    if (t === 'postgres')
+        return 'postgres';
+    if (t === 'sqlite')
+        return 'sqlite';
+    throw new Error(`Unsupported MYSQL_MCP_DB_TYPE: "${t}". Supported values: mysql, postgres, sqlite`);
+}
+// --- MySQL Adapter ---
+class MysqlAdapter {
+    async getConnection() {
+        const config = getDbConfig();
+        return mysql.createConnection({
+            host: config.host,
+            port: config.port,
+            database: config.database,
+            user: config.user,
+            password: config.password,
+            connectTimeout: 10000,
+        });
+    }
+    async query(sql) {
+        const connection = await this.getConnection();
+        try {
+            const [rows] = await connection.execute(sql);
+            return rows;
+        }
+        finally {
+            await connection.end();
+        }
+    }
+    async listTables() {
+        const connection = await this.getConnection();
+        try {
+            const [rows] = await connection.execute('SHOW TABLES');
+            return rows.map((row) => Object.values(row)[0]);
+        }
+        finally {
+            await connection.end();
+        }
+    }
+    async describeTable(tableName) {
+        if (!/^[\w$]+$/i.test(tableName)) {
+            throw new Error(`Invalid table name: "${tableName}". Only alphanumeric characters, underscores and dollar signs are allowed.`);
+        }
+        const connection = await this.getConnection();
+        try {
+            const [rows] = await connection.execute(`DESCRIBE \`${tableName}\``);
+            return rows;
+        }
+        finally {
+            await connection.end();
+        }
+    }
+}
+// --- PostgreSQL Adapter ---
+class PostgresAdapter {
+    async getClient() {
+        const config = getDbConfig();
+        const client = new pg.Client({
+            host: config.host,
+            port: config.port,
+            database: config.database,
+            user: config.user,
+            password: config.password,
+            connectionTimeoutMillis: 10000,
+        });
+        await client.connect();
+        return client;
+    }
+    async query(sql) {
+        const client = await this.getClient();
+        try {
+            const result = await client.query(sql);
+            return result.rows;
+        }
+        finally {
+            await client.end();
+        }
+    }
+    async listTables() {
+        const client = await this.getClient();
+        try {
+            const result = await client.query(`SELECT table_name FROM information_schema.tables
+         WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+         ORDER BY table_name`);
+            return result.rows.map((row) => row.table_name);
+        }
+        finally {
+            await client.end();
+        }
+    }
+    async describeTable(tableName) {
+        if (!/^[\w$]+$/i.test(tableName)) {
+            throw new Error(`Invalid table name: "${tableName}". Only alphanumeric characters, underscores and dollar signs are allowed.`);
+        }
+        const client = await this.getClient();
+        try {
+            const result = await client.query(`SELECT
+           column_name AS "Field",
+           data_type   AS "Type",
+           is_nullable AS "Null",
+           COALESCE(column_default, '') AS "Default",
+           '' AS "Key",
+           '' AS "Extra"
+         FROM information_schema.columns
+         WHERE table_name = $1
+         ORDER BY ordinal_position`, [tableName]);
+            return result.rows;
+        }
+        finally {
+            await client.end();
+        }
+    }
+}
+// --- SQLite Adapter ---
+class SqliteAdapter {
+    getDb() {
+        const path = process.env.MYSQL_MCP_SQLITE_PATH;
+        if (!path) {
+            throw new Error('Missing required environment variable: MYSQL_MCP_SQLITE_PATH');
+        }
+        return new Database(path, { readonly: false });
+    }
+    async query(sql) {
+        const db = this.getDb();
+        try {
+            const stmt = db.prepare(sql);
+            if (stmt.reader) {
+                return stmt.all();
+            }
+            const info = stmt.run();
+            return [{ changes: info.changes, lastInsertRowid: String(info.lastInsertRowid) }];
+        }
+        finally {
+            db.close();
+        }
+    }
+    async listTables() {
+        const db = this.getDb();
+        try {
+            const rows = db
+                .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name`)
+                .all();
+            return rows.map((row) => row.name);
+        }
+        finally {
+            db.close();
+        }
+    }
+    async describeTable(tableName) {
+        if (!/^[\w$]+$/i.test(tableName)) {
+            throw new Error(`Invalid table name: "${tableName}". Only alphanumeric characters, underscores and dollar signs are allowed.`);
+        }
+        const db = this.getDb();
+        try {
+            const rows = db.prepare(`PRAGMA table_info(${tableName})`).all();
+            return rows.map((row) => ({
+                Field: row.name,
+                Type: row.type,
+                Null: row.notnull ? 'NO' : 'YES',
+                Key: row.pk ? 'PK' : '',
+                Default: row.dflt_value,
+                Extra: '',
+            }));
+        }
+        finally {
+            db.close();
+        }
+    }
+}
+// --- HTTP Proxy Adapter ---
+class HttpProxyAdapter {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.token = token;
+    }
+    async postQuery(sql, params = []) {
+        const res = await fetch(`${this.baseUrl}/query`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.token}`,
+            },
+            body: JSON.stringify({ sql, params }),
+        });
+        const json = await res.json();
+        if (!res.ok) {
+            throw new Error(json.error ?? `HTTP ${res.status}`);
+        }
+        return json.data ?? [];
+    }
+    async query(sql) {
+        return this.postQuery(sql);
+    }
+    async listTables() {
+        const rows = await this.postQuery('SHOW TABLES');
+        return rows.map((row) => Object.values(row)[0]);
+    }
+    async describeTable(tableName) {
+        if (!/^[\w$]+$/i.test(tableName)) {
+            throw new Error(`Invalid table name: "${tableName}". Only alphanumeric characters, underscores and dollar signs are allowed.`);
+        }
+        return this.postQuery(`DESCRIBE \`${tableName}\``);
+    }
+}
+// --- Factory ---
+export function isProxyMode() {
+    return !!(process.env.DB_PROXY_URL && process.env.DB_PROXY_TOKEN);
+}
+function getAdapter() {
+    const proxyUrl = process.env.DB_PROXY_URL;
+    const proxyToken = process.env.DB_PROXY_TOKEN;
+    if (proxyUrl && proxyToken) {
+        return new HttpProxyAdapter(proxyUrl, proxyToken);
+    }
+    const type = getDbType();
+    if (type === 'postgres')
+        return new PostgresAdapter();
+    if (type === 'sqlite')
+        return new SqliteAdapter();
+    return new MysqlAdapter();
+}
+// --- Public API (unchanged) ---
+export async function executeQuery(sql) {
+    return getAdapter().query(sql);
+}
+export async function listTables() {
+    return getAdapter().listTables();
+}
+export async function describeTable(tableName) {
+    return getAdapter().describeTable(tableName);
+}

package/dist/gui.js

@@ -0,0 +1,161 @@
+import express from 'express';
+import bodyParser from 'body-parser';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { setupLogging, ProxyClient } from '@imenam/mcp-gui-interface';
+import { executeQuery, listTables, describeTable } from './db.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, '..');
+setupLogging({ processLabel: 'GUI', logDir: process.env.MCP_LOG_DIR });
+if (!process.env.PROXY_URL) {
+    process.stderr.write('[GUI] PROXY_URL non défini — arrêt.\n');
+    process.exit(0);
+}
+// --- Config persistence ---
+const configDir = process.env.CONFIG_PATH
+    ? (path.isAbsolute(process.env.CONFIG_PATH)
+        ? process.env.CONFIG_PATH
+        : path.resolve(rootDir, process.env.CONFIG_PATH))
+    : path.join(rootDir, 'data');
+const configPath = path.join(configDir, 'config.json');
+const defaultConfig = {
+    tabs: [{ id: 'default', name: 'Onglet 1', sql: '' }],
+    settings: { maxResults: 100 },
+    activeTabId: 'default',
+};
+function loadConfig() {
+    try {
+        if (fs.existsSync(configPath)) {
+            const raw = fs.readFileSync(configPath, 'utf-8');
+            return { ...defaultConfig, ...JSON.parse(raw) };
+        }
+    }
+    catch (e) {
+        console.error('[GUI] Failed to load config:', e);
+    }
+    return { ...defaultConfig };
+}
+function saveConfig(config) {
+    try {
+        const dir = path.dirname(configPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    }
+    catch (e) {
+        console.error('[GUI] Failed to save config:', e);
+    }
+}
+// --- Query helpers ---
+const READ_ONLY_PREFIXES = ['SELECT', 'SHOW', 'DESCRIBE', 'EXPLAIN', 'WITH'];
+function isReadOnly(sql) {
+    const normalized = sql.trim().toUpperCase();
+    return READ_ONLY_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+// --- Express app ---
+const app = express();
+app.use(bodyParser.json());
+app.use(express.static(path.join(__dirname, '../public/dist')));
+app.get(/^(?!\/api\/|\/proxy\/)/, (_req, res) => {
+    res.sendFile(path.join(__dirname, '../public/dist/index.html'));
+});
+app.get('/proxy/health', (_req, res) => {
+    res.status(200).json({ status: 'healthy' });
+});
+app.get('/api/config', (_req, res) => {
+    const config = loadConfig();
+    res.json({ success: true, config });
+});
+app.put('/api/config', (req, res) => {
+    const config = req.body;
+    if (!config || !Array.isArray(config.tabs) || !config.settings) {
+        res.status(400).json({ success: false, error: 'Invalid config' });
+        return;
+    }
+    saveConfig(config);
+    res.json({ success: true });
+});
+app.get('/api/tables', async (_req, res) => {
+    try {
+        const tables = await listTables();
+        res.json({ success: true, tables });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        res.status(500).json({ success: false, error: message });
+    }
+});
+app.get('/api/describe/:table', async (req, res) => {
+    try {
+        const columns = await describeTable(req.params.table);
+        res.json({ success: true, columns });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        res.status(500).json({ success: false, error: message });
+    }
+});
+app.post('/api/query', async (req, res) => {
+    const { sql, max_rows } = req.body;
+    if (!sql || typeof sql !== 'string') {
+        res.status(400).json({ success: false, error: 'sql is required' });
+        return;
+    }
+    if (!isReadOnly(sql) && process.env.MYSQL_MCP_ALLOW_WRITE?.trim().toLowerCase() !== 'true') {
+        res.status(403).json({
+            success: false,
+            error: 'Write operations are disabled. Set MYSQL_MCP_ALLOW_WRITE=true to enable them.',
+        });
+        return;
+    }
+    try {
+        const rawResult = await executeQuery(sql);
+        const result = Array.isArray(rawResult) && max_rows != null
+            ? rawResult.slice(0, max_rows)
+            : rawResult;
+        res.json({ success: true, result });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        res.status(500).json({ success: false, error: message });
+    }
+});
+async function startServer() {
+    const proxyClient = new ProxyClient(process.env.PROXY_URL);
+    const result = await proxyClient.register({
+        path: process.env.PROXY_APP_PATH ?? '/mysql-mcp',
+        name: process.env.PROXY_APP_NAME ?? 'MySQL MCP',
+    });
+    if (!result.success) {
+        process.stderr.write('[GUI] Enregistrement proxy échoué — arrêt.\n');
+        process.exit(1);
+    }
+    const port = result.port;
+    app.post('/api/stop', async (_req, res) => {
+        console.error('POST /api/stop called');
+        res.json({ success: true, message: 'Stopping...' });
+        await proxyClient.unregister();
+        setTimeout(() => {
+            if (process.send && process.connected) {
+                process.send({ type: 'STOP' });
+            }
+            else {
+                process.exit(0);
+            }
+        }, 500);
+    });
+    const serverListener = app.listen(port, () => {
+        console.error(`GUI Server running at http://localhost:${port}`);
+    });
+    serverListener.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+            console.error(`PORT CONFLICT: Port ${port} is already in use.`);
+        }
+        else {
+            console.error(`SERVER ERROR: ${err.message}`);
+        }
+    });
+}
+startServer();