@dbx-app/mcp-server 0.2.2 → 0.4.0

package/README.md

@@ -7,9 +7,10 @@ MCP server for [DBX](https://github.com/t8y2/dbx) — lets AI agents (Claude Cod
 ## Features
 
 - **Zero config** — Automatically reads your DBX connections (including passwords from system keyring)
-- **7 tools** — List/add/remove connections, list tables, describe table, execute SQL, open table in DBX UI
+- **8 tools** — List/add/remove connections, list tables, describe table, get schema context, execute SQL, open table in DBX UI
 - **Connection pooling** — Reuses database connections across queries
-- **PostgreSQL & MySQL** — Supports PostgreSQL, MySQL, and compatible databases (Doris, StarRocks, etc.)
+- **Direct execution** — PostgreSQL, MySQL, SQLite, and compatible databases (Doris, StarRocks, etc.) can run without opening DBX
+- **Read-only by default** — SQL execution blocks write and dangerous statements unless explicitly enabled
 - **DBX UI integration** — Open tables directly in the DBX desktop app from your AI agent
 
 ## Quick Start
@@ -73,9 +74,24 @@ In Claude Code, just ask:
 | `dbx_remove_connection` | Remove a database connection |
 | `dbx_list_tables` | List tables and views for a connection |
 | `dbx_describe_table` | Get column definitions for a table |
+| `dbx_get_schema_context` | Get compact table and column context for writing SQL |
 | `dbx_execute_query` | Execute a SQL query (max 100 rows) |
 | `dbx_open_table` | Open a table in DBX desktop app UI |
 
+## SQL Safety
+
+`dbx_execute_query` is read-only by default. To allow write statements such as `INSERT` or `UPDATE`, set:
+
+```bash
+DBX_MCP_ALLOW_WRITES=1
+```
+
+Dangerous statements such as `DROP`, `TRUNCATE`, and `ALTER` remain blocked unless you also set:
+
+```bash
+DBX_MCP_ALLOW_DANGEROUS_SQL=1
+```
+
 ## How It Works
 
 ```
@@ -94,6 +110,8 @@ The MCP server reads your database connections from DBX's SQLite database:
 
 The `dbx_open_table` tool communicates with the running DBX app to open tables directly in the UI. This requires DBX to be running. If DBX is not running, the tool will return an error message.
 
+PostgreSQL, MySQL, SQLite, Doris, StarRocks, and Redshift queries run directly from the MCP server. Other database types still use the DBX desktop bridge for query, table, and column operations unless `DBX_WEB_URL` is configured.
+
 ## Requirements
 
 - [DBX](https://github.com/t8y2/dbx) installed with at least one connection configured
@@ -112,9 +130,10 @@ MIT
 ### 特性
 
 - **零配置** — 自动读取 DBX 的连接配置
-- **7 个工具** — 列出/添加/删除连接、列出表、查看表结构、执行 SQL、在 DBX 中打开表
+- **8 个工具** — 列出/添加/删除连接、列出表、查看表结构、获取 Schema 上下文、执行 SQL、在 DBX 中打开表
 - **连接池** — 跨查询复用数据库连接
-- **PostgreSQL 和 MySQL** — 支持 PostgreSQL、MySQL 及兼容数据库（Doris、StarRocks 等）
+- **直接执行** — PostgreSQL、MySQL、SQLite 及兼容数据库（Doris、StarRocks 等）无需打开 DBX 即可查询
+- **默认只读** — SQL 执行默认拦截写操作和危险语句
 - **DBX UI 联动** — 从 AI 助手直接在 DBX 桌面端打开表
 
 ### 快速开始
@@ -164,9 +183,24 @@ npx @dbx-app/mcp-server
 | `dbx_remove_connection` | 删除数据库连接 |
 | `dbx_list_tables` | 列出指定连接的表和视图 |
 | `dbx_describe_table` | 获取表的列定义 |
+| `dbx_get_schema_context` | 获取适合 AI 写 SQL 的紧凑表结构上下文 |
 | `dbx_execute_query` | 执行 SQL 查询（最多返回 100 行） |
 | `dbx_open_table` | 在 DBX 桌面端打开指定表 |
 
+### SQL 安全
+
+`dbx_execute_query` 默认只读。若要允许 `INSERT`、`UPDATE` 等写操作，设置：
+
+```bash
+DBX_MCP_ALLOW_WRITES=1
+```
+
+`DROP`、`TRUNCATE`、`ALTER` 等危险语句仍会被拦截，除非额外设置：
+
+```bash
+DBX_MCP_ALLOW_DANGEROUS_SQL=1
+```
+
 ### 工作原理
 
 MCP Server 从 DBX 的 SQLite 数据库读取连接信息：
@@ -179,6 +213,8 @@ MCP Server 从 DBX 的 SQLite 数据库读取连接信息：
 
 `dbx_open_table` 工具通过本地 HTTP 接口与运行中的 DBX 应用通信，直接在 UI 中打开表。需要 DBX 正在运行。
 
+PostgreSQL、MySQL、SQLite、Doris、StarRocks、Redshift 查询可由 MCP Server 直接执行。其他数据库类型的查询、表列表、字段读取仍会走 DBX 桌面端 bridge，除非配置了 `DBX_WEB_URL` 使用 Web 后端。
+
 ### 系统要求
 
 - 已安装 [DBX](https://github.com/t8y2/dbx) 并配置了至少一个数据库连接

package/dist/connections.d.ts

@@ -10,8 +10,15 @@ export interface ConnectionConfig {
     database?: string;
     url_params?: string;
     ssh_enabled: boolean;
+    proxy_enabled?: boolean;
+    proxy_type?: "socks5" | "http";
+    proxy_host?: string;
+    proxy_port?: number;
+    proxy_username?: string;
+    proxy_password?: string;
     ssl: boolean;
 }
+export declare function canonicalizeConnection(config: ConnectionConfig): ConnectionConfig;
 export declare function loadConnections(): Promise<ConnectionConfig[]>;
 export declare function findConnection(name: string): Promise<ConnectionConfig | undefined>;
 export declare function addConnection(config: Omit<ConnectionConfig, "id">): Promise<ConnectionConfig>;

package/dist/connections.js

@@ -2,6 +2,24 @@ import { join } from "node:path";
 import { homedir, platform } from "node:os";
 import { randomUUID } from "node:crypto";
 import Database from "better-sqlite3";
+export function canonicalizeConnection(config) {
+    if (config.db_type === "mysql" && config.driver_profile?.toLowerCase() === "tdengine") {
+        return {
+            ...config,
+            db_type: "tdengine",
+            driver_profile: "tdengine",
+            port: config.port === 0 || config.port === 6030 ? 6041 : config.port,
+        };
+    }
+    if (config.db_type === "tdengine") {
+        return {
+            ...config,
+            driver_profile: "tdengine",
+            port: config.port || 6041,
+        };
+    }
+    return config;
+}
 function appDataDir() {
     const home = homedir();
     switch (platform()) {
@@ -18,7 +36,9 @@ function openDb(readonly = false) {
     return new Database(dbPath, { readonly });
 }
 function getSecret(db, connectionId, key) {
-    const row = db.prepare("SELECT secret FROM connection_secrets WHERE connection_id = ? AND key = ?").get(connectionId, key);
+    const row = db
+        .prepare("SELECT secret FROM connection_secrets WHERE connection_id = ? AND key = ?")
+        .get(connectionId, key);
     return row?.secret ?? "";
 }
 export async function loadConnections() {
@@ -27,10 +47,12 @@ export async function loadConnections() {
         const rows = db.prepare("SELECT id, config_json FROM connections").all();
         const configs = [];
         for (const row of rows) {
-            const config = JSON.parse(row.config_json);
+            const config = canonicalizeConnection(JSON.parse(row.config_json));
             config.id = row.id;
             if (!config.password)
                 config.password = getSecret(db, row.id, "password");
+            if (!config.proxy_password)
+                config.proxy_password = getSecret(db, row.id, "proxy_password");
             configs.push(config);
         }
         db.close();
@@ -47,20 +69,21 @@ export async function findConnection(name) {
 export async function addConnection(config) {
     const id = randomUUID();
     const db = openDb();
+    const normalized = canonicalizeConnection({ ...config, id });
     const full = {
         id,
-        name: config.name,
-        db_type: config.db_type,
-        driver_profile: config.driver_profile ?? config.db_type,
+        name: normalized.name,
+        db_type: normalized.db_type,
+        driver_profile: normalized.driver_profile ?? normalized.db_type,
         driver_label: null,
-        url_params: config.url_params ?? "",
-        host: config.host,
-        port: config.port,
-        username: config.username,
+        url_params: normalized.url_params ?? "",
+        host: normalized.host,
+        port: normalized.port,
+        username: normalized.username,
         password: "",
-        database: config.database ?? null,
+        database: normalized.database ?? null,
         color: null,
-        ssh_enabled: config.ssh_enabled ?? false,
+        ssh_enabled: normalized.ssh_enabled ?? false,
         ssh_host: "",
         ssh_port: 22,
         ssh_user: "",
@@ -68,20 +91,29 @@ export async function addConnection(config) {
         ssh_key_path: "",
         ssh_key_passphrase: "",
         ssh_expose_lan: false,
-        ssl: config.ssl ?? false,
+        proxy_enabled: normalized.proxy_enabled ?? false,
+        proxy_type: normalized.proxy_type ?? "socks5",
+        proxy_host: normalized.proxy_host ?? "",
+        proxy_port: normalized.proxy_port ?? 1080,
+        proxy_username: normalized.proxy_username ?? "",
+        proxy_password: "",
+        ssl: normalized.ssl ?? false,
         sysdba: false,
         connection_string: null,
     };
     const configJson = JSON.stringify(full);
     const insert = db.transaction(() => {
         db.prepare("INSERT INTO connections (id, config_json) VALUES (?, ?)").run(id, configJson);
-        if (config.password) {
-            db.prepare("INSERT INTO connection_secrets (connection_id, key, secret) VALUES (?, ?, ?)").run(id, "password", config.password);
+        if (normalized.password) {
+            db.prepare("INSERT INTO connection_secrets (connection_id, key, secret) VALUES (?, ?, ?)").run(id, "password", normalized.password);
+        }
+        if (normalized.proxy_password) {
+            db.prepare("INSERT INTO connection_secrets (connection_id, key, secret) VALUES (?, ?, ?)").run(id, "proxy_password", normalized.proxy_password);
         }
     });
     insert();
     db.close();
-    return { ...config, id };
+    return normalized;
 }
 export async function removeConnection(name) {
     const connection = await findConnection(name);

package/dist/database.js

@@ -1,7 +1,14 @@
+import { createServer, connect as netConnect } from "node:net";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir, platform } from "node:os";
+import Database from "better-sqlite3";
+import { sqlSafetyFromEnv } from "./sql-safety.js";
 const MAX_ROWS = 100;
 const IDLE_TIMEOUT_MS = 5 * 60 * 1000;
 const QUERY_TIMEOUT_MS = 30_000;
 const pools = new Map();
+const proxyTunnels = new Map();
 function poolKey(config) {
     return `${config.id}:${config.database || ""}`;
 }
@@ -26,8 +33,9 @@ async function getPgPool(config) {
         return existing.pool;
     }
     const pg = await import("pg");
+    const endpoint = await connectionEndpoint(config);
     const pool = new pg.default.Pool({
-        connectionString: buildConnectionUrl(config),
+        connectionString: buildConnectionUrl(config, endpoint),
         max: 3,
         idleTimeoutMillis: 30_000,
         connectionTimeoutMillis: 10_000,
@@ -46,8 +54,9 @@ async function getMysqlPool(config) {
         return existing.pool;
     }
     const mysql = await import("mysql2/promise");
+    const endpoint = await connectionEndpoint(config);
     const pool = mysql.default.createPool({
-        uri: buildConnectionUrl(config),
+        uri: buildConnectionUrl(config, endpoint),
         connectionLimit: 3,
         idleTimeout: 30_000,
         connectTimeout: 10_000,
@@ -57,18 +66,195 @@ async function getMysqlPool(config) {
     resetIdleTimer(key, entry);
     return pool;
 }
-function buildConnectionUrl(config) {
+async function connectionEndpoint(config) {
+    if (!config.proxy_enabled || !config.proxy_host)
+        return { host: config.host, port: config.port };
+    const existing = proxyTunnels.get(config.id);
+    if (existing)
+        return { host: "127.0.0.1", port: existing.port };
+    const server = createServer((inbound) => {
+        connectViaProxy(config)
+            .then((outbound) => {
+            inbound.pipe(outbound);
+            outbound.pipe(inbound);
+        })
+            .catch(() => inbound.destroy());
+    });
+    const port = await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (address && typeof address === "object")
+                resolve(address.port);
+            else
+                reject(new Error("Failed to bind proxy tunnel"));
+        });
+    });
+    proxyTunnels.set(config.id, { server, port });
+    return { host: "127.0.0.1", port };
+}
+function buildConnectionUrl(config, endpoint) {
     const db = config.database || "";
     const params = config.url_params || "";
     const suffix = params ? `?${params}` : "";
     if (isMysqlType(config.db_type)) {
-        return `mysql://${encodeURIComponent(config.username)}:${encodeURIComponent(config.password)}@${config.host}:${config.port}/${db}${suffix}`;
+        return `mysql://${encodeURIComponent(config.username)}:${encodeURIComponent(config.password)}@${endpoint.host}:${endpoint.port}/${db}${suffix}`;
+    }
+    return `postgres://${encodeURIComponent(config.username)}:${encodeURIComponent(config.password)}@${endpoint.host}:${endpoint.port}/${db}${suffix}`;
+}
+function connectViaProxy(config) {
+    return new Promise((resolve, reject) => {
+        const socket = netConnect(config.proxy_port || 1080, config.proxy_host || "127.0.0.1");
+        socket.once("error", reject);
+        socket.once("connect", () => {
+            if ((config.proxy_type || "socks5") === "http") {
+                httpConnect(socket, config, resolve, reject);
+            }
+            else {
+                socks5Connect(socket, config, resolve, reject);
+            }
+        });
+    });
+}
+function httpConnect(socket, config, resolve, reject) {
+    const target = `${config.host}:${config.port}`;
+    const lines = [`CONNECT ${target} HTTP/1.1`, `Host: ${target}`];
+    if (config.proxy_username || config.proxy_password) {
+        const token = Buffer.from(`${config.proxy_username || ""}:${config.proxy_password || ""}`).toString("base64");
+        lines.push(`Proxy-Authorization: Basic ${token}`);
     }
-    return `postgres://${encodeURIComponent(config.username)}:${encodeURIComponent(config.password)}@${config.host}:${config.port}/${db}${suffix}`;
+    socket.write(`${lines.join("\r\n")}\r\n\r\n`);
+    let buffer = Buffer.alloc(0);
+    socket.on("data", function onData(chunk) {
+        buffer = Buffer.concat([buffer, chunk]);
+        const end = buffer.indexOf("\r\n\r\n");
+        if (end < 0)
+            return;
+        socket.off("data", onData);
+        const head = buffer.subarray(0, end).toString("utf8");
+        if (!/^HTTP\/1\.[01] 200\b/.test(head)) {
+            reject(new Error(`HTTP proxy CONNECT failed: ${head.split("\r\n")[0] || "invalid response"}`));
+            socket.destroy();
+            return;
+        }
+        const rest = buffer.subarray(end + 4);
+        if (rest.length)
+            socket.unshift(rest);
+        resolve(socket);
+    });
+}
+function socks5Connect(socket, config, resolve, reject) {
+    const wantsAuth = !!(config.proxy_username || config.proxy_password);
+    socket.write(Buffer.from(wantsAuth ? [0x05, 0x02, 0x00, 0x02] : [0x05, 0x01, 0x00]));
+    socket.once("data", (method) => {
+        if (method.length < 2 || method[0] !== 0x05) {
+            reject(new Error("Invalid SOCKS greeting"));
+            socket.destroy();
+            return;
+        }
+        if (method[1] === 0x02) {
+            const user = Buffer.from(config.proxy_username || "");
+            const pass = Buffer.from(config.proxy_password || "");
+            socket.write(Buffer.concat([Buffer.from([0x01, user.length]), user, Buffer.from([pass.length]), pass]));
+            socket.once("data", (auth) => {
+                if (auth.length < 2 || auth[1] !== 0x00) {
+                    reject(new Error("SOCKS proxy authentication failed"));
+                    socket.destroy();
+                    return;
+                }
+                sendSocksConnect(socket, config, resolve, reject);
+            });
+        }
+        else if (method[1] === 0x00) {
+            sendSocksConnect(socket, config, resolve, reject);
+        }
+        else {
+            reject(new Error("SOCKS proxy rejected authentication methods"));
+            socket.destroy();
+        }
+    });
+}
+function sendSocksConnect(socket, config, resolve, reject) {
+    const host = Buffer.from(config.host);
+    socket.write(Buffer.concat([Buffer.from([0x05, 0x01, 0x00, 0x03, host.length]), host, portBytes(config.port)]));
+    socket.once("data", (res) => {
+        if (res.length < 4 || res[0] !== 0x05 || res[1] !== 0x00) {
+            reject(new Error(`SOCKS proxy connect failed with code ${res[1] ?? "unknown"}`));
+            socket.destroy();
+            return;
+        }
+        resolve(socket);
+    });
+}
+function portBytes(port) {
+    const buf = Buffer.alloc(2);
+    buf.writeUInt16BE(port);
+    return buf;
 }
 function isMysqlType(dbType) {
     return dbType === "mysql" || dbType === "doris" || dbType === "starrocks";
 }
+function isDirectType(dbType) {
+    switch (dbType) {
+        case "postgres":
+        case "redshift":
+        case "mysql":
+        case "doris":
+        case "starrocks":
+        case "sqlite":
+            return true;
+        default:
+            return false;
+    }
+}
+function bridgeAppDataDir() {
+    const home = homedir();
+    switch (platform()) {
+        case "darwin":
+            return join(home, "Library", "Application Support", "com.dbx.app");
+        case "win32":
+            return join(process.env.APPDATA || join(home, "AppData", "Roaming"), "com.dbx.app");
+        default:
+            return join(home, ".config", "com.dbx.app");
+    }
+}
+async function bridgeDataRequest(path, body) {
+    let bridgeUrl;
+    try {
+        const portFile = join(bridgeAppDataDir(), "mcp-bridge-port");
+        const port = (await readFile(portFile, "utf-8")).trim();
+        bridgeUrl = `http://127.0.0.1:${port}`;
+    }
+    catch {
+        throw new Error("DBX desktop app is not running. This database type requires DBX to be running for query execution.");
+    }
+    const res = await fetch(`${bridgeUrl}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const errBody = await res.text().catch(() => "");
+        let errorMsg;
+        try {
+            const parsed = JSON.parse(errBody);
+            errorMsg = parsed.error || errBody;
+        }
+        catch {
+            errorMsg = errBody;
+        }
+        throw new Error(errorMsg || `Bridge request failed: ${res.status}`);
+    }
+    return res.json();
+}
+function convertBridgeQueryResult(result) {
+    const rows = result.rows.slice(0, MAX_ROWS).map((row) => {
+        const obj = {};
+        result.columns.forEach((col, i) => { obj[col] = row[i]; });
+        return obj;
+    });
+    return { columns: result.columns, rows, row_count: rows.length };
+}
 function withTimeout(promise, ms) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => reject(new Error(`Query timed out after ${ms}ms`)), ms);
@@ -109,14 +295,64 @@ async function mysqlQuery(config, sql, params) {
     });
 }
 async function query(config, sql, params) {
+    if (config.db_type === "sqlite")
+        return sqliteQuery(config, sql);
     if (isMysqlType(config.db_type))
         return mysqlQuery(config, sql, params);
     return pgQuery(config, sql, params);
 }
+function sqlitePath(config) {
+    return expandTilde(config.host || config.database || "");
+}
+function expandTilde(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/"))
+        return join(homedir(), path.slice(2));
+    return path;
+}
+function quoteSqliteIdentifier(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}
+function sqliteQuery(config, sql) {
+    const db = new Database(sqlitePath(config), { readonly: !sqlSafetyFromEnv().allowWrites });
+    try {
+        const stmt = db.prepare(sql);
+        if (stmt.reader) {
+            const rows = stmt.all().slice(0, MAX_ROWS);
+            return { columns: stmt.columns().map((column) => column.name), rows, row_count: rows.length };
+        }
+        const result = stmt.run();
+        return { columns: [], rows: [], row_count: result.changes };
+    }
+    finally {
+        db.close();
+    }
+}
 export async function executeQuery(config, sql) {
-    return query(config, sql);
+    if (isDirectType(config.db_type)) {
+        return query(config, sql);
+    }
+    const result = await bridgeDataRequest("/data/execute-query", {
+        connection_name: config.name,
+        database: config.database || "",
+        sql,
+    });
+    return convertBridgeQueryResult(result);
 }
 export async function listTables(config, schema) {
+    if (config.db_type === "sqlite") {
+        const result = await query(config, `SELECT name, type FROM sqlite_master WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%' ORDER BY name`);
+        return result.rows.map((r) => ({ name: String(r.name || ""), type: String(r.type || "table") }));
+    }
+    if (!isDirectType(config.db_type)) {
+        const tables = await bridgeDataRequest("/data/list-tables", {
+            connection_name: config.name,
+            database: config.database || "",
+            schema: schema || "",
+        });
+        return tables.map((t) => ({ name: t.name, type: t.table_type || "TABLE" }));
+    }
     let result;
     if (isMysqlType(config.db_type)) {
         result = await query(config, `SELECT TABLE_NAME AS name, TABLE_TYPE AS type FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() ORDER BY TABLE_NAME`);
@@ -127,6 +363,33 @@ export async function listTables(config, schema) {
     return result.rows.map((r) => ({ name: String(r.name || r.NAME), type: String(r.type || r.TYPE || "TABLE") }));
 }
 export async function describeTable(config, table, schema) {
+    if (config.db_type === "sqlite") {
+        const result = await query(config, `PRAGMA table_info(${quoteSqliteIdentifier(table)})`);
+        return result.rows.map((r) => ({
+            name: String(r.name || ""),
+            data_type: String(r.type || ""),
+            is_nullable: Number(r.notnull || 0) === 0,
+            column_default: r.dflt_value != null ? String(r.dflt_value) : null,
+            is_primary_key: Number(r.pk || 0) > 0,
+            comment: null,
+        }));
+    }
+    if (!isDirectType(config.db_type)) {
+        const columns = await bridgeDataRequest("/data/describe-table", {
+            connection_name: config.name,
+            database: config.database || "",
+            schema: schema || "",
+            table,
+        });
+        return columns.map((c) => ({
+            name: c.name,
+            data_type: c.data_type,
+            is_nullable: c.is_nullable,
+            column_default: c.column_default,
+            is_primary_key: c.is_primary_key,
+            comment: c.comment,
+        }));
+    }
     let result;
     if (isMysqlType(config.db_type)) {
         result = await query(config, `SELECT c.COLUMN_NAME AS name, c.DATA_TYPE AS data_type, c.IS_NULLABLE = 'YES' AS is_nullable, c.COLUMN_DEFAULT AS column_default, c.COLUMN_KEY = 'PRI' AS is_primary_key, c.COLUMN_COMMENT AS comment FROM information_schema.COLUMNS c WHERE c.TABLE_SCHEMA = DATABASE() AND c.TABLE_NAME = ? ORDER BY c.ORDINAL_POSITION`, [table]);

package/dist/index.js

@@ -7,6 +7,8 @@ import { join } from "node:path";
 import { homedir, platform } from "node:os";
 import { loadConnections as desktopLoadConnections, findConnection as desktopFindConnection, addConnection as desktopAddConnection, removeConnection as desktopRemoveConnection, } from "./connections.js";
 import { listTables as desktopListTables, describeTable as desktopDescribeTable, executeQuery as desktopExecuteQuery, } from "./database.js";
+import { buildSchemaContext, formatSchemaContext } from "./schema-context.js";
+import { evaluateSqlSafety, sqlSafetyFromEnv } from "./sql-safety.js";
 const isWebMode = !!process.env.DBX_WEB_URL;
 let backend;
 if (isWebMode) {
@@ -36,7 +38,7 @@ function mdTable(headers, rows) {
 }
 const server = new McpServer({
     name: "dbx",
-    version: "0.2.1",
+    version: "0.3.0",
 });
 server.tool("dbx_list_connections", "List all database connections configured in DBX", {}, async () => {
     const connections = await backend.loadConnections();
@@ -85,6 +87,9 @@ server.tool("dbx_execute_query", "Execute a SQL query on a database connection (
     const config = await backend.findConnection(connection_name);
     if (!config)
         return text(`Connection "${connection_name}" not found`);
+    const safety = evaluateSqlSafety(sql, sqlSafetyFromEnv());
+    if (!safety.allowed)
+        return text(`Query blocked: ${safety.reason}`);
     try {
         const result = await backend.executeQuery(config, sql);
         if (result.columns.length === 0)
@@ -97,11 +102,27 @@ server.tool("dbx_execute_query", "Execute a SQL query on a database connection (
         return text(`Query error: ${msg}`);
     }
 });
+server.tool("dbx_get_schema_context", "Get compact table and column context for writing SQL", {
+    connection_name: z.string().describe("Name of the DBX connection"),
+    schema: z.string().optional().describe("Schema name (default: public for PostgreSQL)"),
+    tables: z.array(z.string()).optional().describe("Specific table names to include"),
+    max_tables: z.number().int().min(1).max(20).default(8).describe("Maximum number of tables to include"),
+}, async ({ connection_name, schema, tables, max_tables }) => {
+    const config = await backend.findConnection(connection_name);
+    if (!config)
+        return text(`Connection "${connection_name}" not found`);
+    const context = await buildSchemaContext(backend, config, { schema, tables, maxTables: max_tables });
+    if (context.tables.length === 0)
+        return text("No matching tables found.");
+    return text(formatSchemaContext(context));
+});
 server.tool("dbx_add_connection", "Add a new database connection to DBX", {
     name: z.string().describe("Connection name"),
-    db_type: z.string().describe("Database type: postgres, mysql, sqlite, redis, duckdb, clickhouse, sqlserver, mongodb, oracle, elasticsearch"),
+    db_type: z
+        .string()
+        .describe("Database type: postgres, mysql, sqlite, redis, duckdb, clickhouse, sqlserver, mongodb, oracle, elasticsearch, doris, starrocks, redshift, dameng, kingbase, highgo, vastbase, goldendb, gaussdb, h2, snowflake, trino, hive, db2, informix, neo4j, cassandra, bigquery, kylin, sundb, tdengine, jdbc, access"),
     host: z.string().describe("Database host"),
-    port: z.number().describe("Database port"),
+    port: z.number().optional().describe("Database port (TDengine defaults to 6041)"),
     username: z.string().default("").describe("Username"),
     password: z.string().default("").describe("Password"),
     database: z.string().optional().describe("Default database name"),
@@ -110,9 +131,20 @@ server.tool("dbx_add_connection", "Add a new database connection to DBX", {
     const existing = await backend.findConnection(name);
     if (existing)
         return text(`Connection "${name}" already exists.`);
+    const FILE_BASED_TYPES = new Set(["sqlite", "duckdb", "access"]);
+    const resolvedPort = port ?? (db_type === "tdengine" ? 6041 : FILE_BASED_TYPES.has(db_type) ? 0 : undefined);
+    if (resolvedPort === undefined)
+        return text("Port is required for this database type.");
     const config = await backend.addConnection({
-        name, db_type, host, port, username, password,
-        database, ssl, ssh_enabled: false,
+        name,
+        db_type,
+        host,
+        port: resolvedPort,
+        username,
+        password,
+        database,
+        ssl,
+        ssh_enabled: false,
     });
     await notifyReload();
     return text(`Connection "${config.name}" added (id: ${config.id}).`);
@@ -171,6 +203,9 @@ if (!isWebMode) {
         sql: z.string().describe("SQL query to execute"),
         database: z.string().optional().describe("Database name"),
     }, async ({ connection_name, sql, database }) => {
+        const safety = evaluateSqlSafety(sql, sqlSafetyFromEnv());
+        if (!safety.allowed)
+            return text(`Query blocked: ${safety.reason}`);
         return bridgeRequest("/execute-query", { connection_name, sql, database }, "Query sent to DBX");
     });
 }

package/dist/schema-context.d.ts

@@ -0,0 +1,25 @@
+import type { ConnectionConfig } from "./connections.js";
+import type { ColumnInfo, TableInfo } from "./database.js";
+export interface SchemaContextBackend {
+    listTables(config: ConnectionConfig, schema?: string): Promise<TableInfo[]>;
+    describeTable(config: ConnectionConfig, table: string, schema?: string): Promise<ColumnInfo[]>;
+}
+export interface SchemaContextOptions {
+    schema?: string;
+    tables?: string[];
+    maxTables?: number;
+}
+export interface SchemaContextTable {
+    name: string;
+    type: string;
+    columns: ColumnInfo[];
+}
+export interface SchemaContext {
+    connection: string;
+    database: string;
+    schema: string;
+    truncated: boolean;
+    tables: SchemaContextTable[];
+}
+export declare function buildSchemaContext(backend: SchemaContextBackend, config: ConnectionConfig, options?: SchemaContextOptions): Promise<SchemaContext>;
+export declare function formatSchemaContext(context: SchemaContext): string;

package/dist/schema-context.js

@@ -0,0 +1,43 @@
+const DEFAULT_MAX_TABLES = 8;
+export async function buildSchemaContext(backend, config, options = {}) {
+    const maxTables = Math.max(1, Math.min(options.maxTables ?? DEFAULT_MAX_TABLES, 20));
+    const availableTables = await backend.listTables(config, options.schema);
+    const requested = new Set((options.tables ?? []).map((table) => table.toLowerCase()));
+    const selected = requested.size
+        ? availableTables.filter((table) => requested.has(table.name.toLowerCase()))
+        : availableTables.slice(0, maxTables);
+    const limited = selected.slice(0, maxTables);
+    const tables = await Promise.all(limited.map(async (table) => ({
+        name: table.name,
+        type: table.type,
+        columns: await backend.describeTable(config, table.name, options.schema),
+    })));
+    return {
+        connection: config.name,
+        database: config.database || "",
+        schema: options.schema || "",
+        truncated: selected.length > limited.length || (!requested.size && availableTables.length > limited.length),
+        tables,
+    };
+}
+export function formatSchemaContext(context) {
+    const header = [
+        `Connection: ${context.connection}`,
+        context.database ? `Database: ${context.database}` : "",
+        context.schema ? `Schema: ${context.schema}` : "",
+    ].filter(Boolean);
+    const sections = context.tables.map((table) => {
+        const lines = table.columns.map((column) => {
+            const parts = [
+                column.name,
+                column.data_type,
+                column.is_nullable ? "NULL" : "NOT NULL",
+                column.is_primary_key ? "PK" : "",
+            ].filter(Boolean);
+            return `- ${parts.join(" ")}${column.comment ? ` -- ${column.comment}` : ""}`;
+        });
+        return [`## ${table.name}`, `Type: ${table.type}`, ...lines].join("\n");
+    });
+    const suffix = context.truncated ? "\n\nNote: table list was truncated; request specific table names for more context." : "";
+    return `${header.join("\n")}\n\n${sections.join("\n\n")}${suffix}`;
+}

package/dist/sql-safety.d.ts

@@ -0,0 +1,10 @@
+export interface SqlSafetyOptions {
+    allowWrites?: boolean;
+    allowDangerous?: boolean;
+}
+export interface SqlSafetyDecision {
+    allowed: boolean;
+    reason?: string;
+}
+export declare function evaluateSqlSafety(sql: string, options?: SqlSafetyOptions): SqlSafetyDecision;
+export declare function sqlSafetyFromEnv(env?: NodeJS.ProcessEnv): SqlSafetyOptions;

package/dist/sql-safety.js

@@ -0,0 +1,103 @@
+const READ_KEYWORDS = new Set(["select", "with", "show", "describe", "desc", "explain"]);
+const DANGEROUS_KEYWORDS = new Set(["drop", "truncate", "alter"]);
+export function evaluateSqlSafety(sql, options = {}) {
+    const statements = splitSqlStatements(sql);
+    if (statements.length === 0)
+        return { allowed: false, reason: "SQL is empty." };
+    if (statements.length > 1)
+        return { allowed: false, reason: "Only one SQL statement is allowed per MCP query." };
+    const normalized = stripSqlCommentsAndStrings(statements[0]).trim();
+    const firstKeyword = normalized.match(/^[a-zA-Z_]+/)?.[0]?.toLowerCase();
+    if (!firstKeyword)
+        return { allowed: false, reason: "SQL statement is not recognized." };
+    const tokens = normalized.toLowerCase().match(/[a-z_]+/g) ?? [];
+    const dangerous = tokens.find((token) => DANGEROUS_KEYWORDS.has(token));
+    if (dangerous && !options.allowDangerous) {
+        return { allowed: false, reason: `Dangerous SQL keyword "${dangerous.toUpperCase()}" is blocked.` };
+    }
+    if (!options.allowWrites && !READ_KEYWORDS.has(firstKeyword)) {
+        return {
+            allowed: false,
+            reason: "MCP SQL execution is read-only by default. Set DBX_MCP_ALLOW_WRITES=1 to allow write statements.",
+        };
+    }
+    if (options.allowWrites && !options.allowDangerous) {
+        if (firstKeyword === "update" && !tokens.includes("where")) {
+            return { allowed: false, reason: "UPDATE statements must include a WHERE clause." };
+        }
+        if (firstKeyword === "delete" && !tokens.includes("where")) {
+            return { allowed: false, reason: "DELETE statements must include a WHERE clause." };
+        }
+    }
+    return { allowed: true };
+}
+export function sqlSafetyFromEnv(env = process.env) {
+    return {
+        allowWrites: env.DBX_MCP_ALLOW_WRITES === "1" || env.DBX_MCP_ALLOW_WRITES === "true",
+        allowDangerous: env.DBX_MCP_ALLOW_DANGEROUS_SQL === "1" || env.DBX_MCP_ALLOW_DANGEROUS_SQL === "true",
+    };
+}
+function splitSqlStatements(sql) {
+    const statements = [];
+    let current = "";
+    let quote = null;
+    let inLineComment = false;
+    let inBlockComment = false;
+    for (let i = 0; i < sql.length; i++) {
+        const char = sql[i];
+        const next = sql[i + 1];
+        if (inLineComment) {
+            current += char;
+            if (char === "\n")
+                inLineComment = false;
+            continue;
+        }
+        if (inBlockComment) {
+            current += char;
+            if (char === "*" && next === "/") {
+                current += next;
+                i++;
+                inBlockComment = false;
+            }
+            continue;
+        }
+        if (quote) {
+            current += char;
+            if (char === quote) {
+                if (next === quote) {
+                    current += next;
+                    i++;
+                }
+                else {
+                    quote = null;
+                }
+            }
+            continue;
+        }
+        if (char === "-" && next === "-")
+            inLineComment = true;
+        if (char === "/" && next === "*")
+            inBlockComment = true;
+        if (char === "'" || char === '"' || char === "`")
+            quote = char;
+        if (char === ";") {
+            if (current.trim())
+                statements.push(current.trim());
+            current = "";
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current.trim())
+        statements.push(current.trim());
+    return statements;
+}
+function stripSqlCommentsAndStrings(sql) {
+    return sql
+        .replace(/--.*$/gm, " ")
+        .replace(/\/\*[\s\S]*?\*\//g, " ")
+        .replace(/'([^']|'')*'/g, "''")
+        .replace(/"([^"]|"")*"/g, '""')
+        .replace(/`([^`]|``)*`/g, "``");
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dbx-app/mcp-server",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "mcpName": "io.github.t8y2/dbx",
-  "description": "MCP server for DBX \u2014 query databases from Claude Code, Cursor, and other AI agents",
+  "description": "MCP server for DBX — query databases from Claude Code, Cursor, and other AI agents",
   "type": "module",
   "bin": {
     "dbx-mcp-server": "dist/index.js"
@@ -12,6 +12,7 @@
   ],
   "scripts": {
     "start": "tsx src/index.ts",
+    "test": "tsx --test tests/*.test.ts",
     "build": "tsc",
     "prepublishOnly": "tsc"
   },
@@ -52,4 +53,4 @@
       "esbuild"
     ]
   }
-}
+}