@dbx-app/mcp-server 0.4.1 → 0.4.3

package/README.md

@@ -48,7 +48,7 @@ Or for development (from source):
   "mcpServers": {
     "dbx": {
       "command": "npx",
-      "args": ["tsx", "mcp/src/index.ts"],
+      "args": ["tsx", "packages/mcp-server/src/index.ts"],
       "cwd": "/path/to/dbx"
     }
   }
@@ -65,6 +65,18 @@ In Claude Code, just ask:
 - "Query the average salary from employees"
 - "Open the orders table in DBX"
 
+## CLI
+
+For terminal, script, and Codex workflows, install the dedicated CLI package:
+
+```bash
+npm install -g @dbx-app/cli
+dbx connections list --json
+dbx query local "select 1" --json
+```
+
+See the [DBX CLI README](../cli/README.md) for command details.
+
 ## Tools
 
 | Tool | Description |
@@ -174,6 +186,18 @@ npx @dbx-app/mcp-server
 - "查询最近 7 天的订单数量"
 - "打开 orders 表"
 
+### CLI
+
+终端、脚本和 Codex 工作流请安装独立 CLI 包：
+
+```bash
+npm install -g @dbx-app/cli
+dbx connections list --json
+dbx query local "select 1" --json
+```
+
+命令详情见 [DBX CLI README](../cli/README.md)。
+
 ### 工具列表
 
 | 工具 | 说明 |

package/dist/index.d.ts

@@ -1,2 +1,6 @@
 #!/usr/bin/env node
-export {};
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Backend } from "@dbx-app/node-core";
+export declare function createDbxMcpServer(backend: Backend, options?: {
+    isWebMode?: boolean;
+}): McpServer;

package/dist/index.js

@@ -1,31 +1,9 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { pathToFileURL } from "node:url";
 import { z } from "zod";
-import { readFile } from "node:fs/promises";
-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) {
-    const web = await import("./web-backend.js");
-    backend = web;
-}
-else {
-    backend = {
-        loadConnections: desktopLoadConnections,
-        findConnection: desktopFindConnection,
-        addConnection: desktopAddConnection,
-        removeConnection: desktopRemoveConnection,
-        listTables: desktopListTables,
-        describeTable: desktopDescribeTable,
-        executeQuery: desktopExecuteQuery,
-    };
-}
+import { buildSchemaContext, createBackend, evaluateSqlSafety, formatSchemaContext, notifyReload, postBridge, sqlSafetyFromEnv, } from "@dbx-app/node-core";
 function text(s) {
     return { content: [{ type: "text", text: s }] };
 }
@@ -36,200 +14,175 @@ function mdTable(headers, rows) {
     const body = rows.map((r) => `| ${r.map((c, i) => (c || "").padEnd(widths[i])).join(" | ")} |`).join("\n");
     return `${header}\n${sep}\n${body}`;
 }
-const server = new McpServer({
-    name: "dbx",
-    version: "0.3.0",
-});
-server.tool("dbx_list_connections", "List all database connections configured in DBX", {}, async () => {
-    const connections = await backend.loadConnections();
-    if (connections.length === 0)
-        return text("No connections configured in DBX.");
-    const rows = connections.map((c) => [c.name, c.db_type, c.host, String(c.port), c.database || ""]);
-    return text(mdTable(["Name", "Type", "Host", "Port", "Database"], rows));
-});
-server.tool("dbx_list_tables", "List tables and views for a database connection", {
-    connection_name: z.string().describe("Name of the DBX connection"),
-    schema: z.string().optional().describe("Schema name (default: public for PostgreSQL)"),
-}, async ({ connection_name, schema }) => {
-    const config = await backend.findConnection(connection_name);
-    if (!config)
-        return text(`Connection "${connection_name}" not found`);
-    const tables = await backend.listTables(config, schema);
-    if (tables.length === 0)
-        return text("No tables found.");
-    const rows = tables.map((t) => [t.name, t.type]);
-    return text(mdTable(["Table", "Type"], rows));
-});
-server.tool("dbx_describe_table", "Get column definitions for a table", {
-    connection_name: z.string().describe("Name of the DBX connection"),
-    table: z.string().describe("Table name"),
-    schema: z.string().optional().describe("Schema name (default: public for PostgreSQL)"),
-}, async ({ connection_name, table, schema }) => {
-    const config = await backend.findConnection(connection_name);
-    if (!config)
-        return text(`Connection "${connection_name}" not found`);
-    const columns = await backend.describeTable(config, table, schema);
-    if (columns.length === 0)
-        return text("No columns found.");
-    const rows = columns.map((c) => [
-        c.is_primary_key ? `${c.name} (PK)` : c.name,
-        c.data_type,
-        c.is_nullable ? "YES" : "NO",
-        c.column_default ?? "",
-        c.comment ?? "",
-    ]);
-    return text(mdTable(["Column", "Type", "Nullable", "Default", "Comment"], rows));
-});
-server.tool("dbx_execute_query", "Execute a SQL query on a database connection (max 100 rows returned)", {
-    connection_name: z.string().describe("Name of the DBX connection"),
-    sql: z.string().describe("SQL query to execute"),
-}, async ({ connection_name, sql }) => {
-    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)
-            return text(`Query executed. ${result.row_count} row(s) affected.`);
-        const rows = result.rows.map((r) => result.columns.map((c) => formatCell(r[c])));
-        return text(`${mdTable(result.columns, rows)}\n\n${result.row_count} row(s)`);
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        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, 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().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"),
-    ssl: z.boolean().default(false).describe("Enable SSL"),
-}, async ({ name, db_type, host, port, username, password, database, ssl }) => {
-    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: resolvedPort,
-        username,
-        password,
-        database,
-        ssl,
-        ssh_enabled: false,
+export function createDbxMcpServer(backend, options = {}) {
+    const isWebMode = options.isWebMode ?? !!process.env.DBX_WEB_URL;
+    const server = new McpServer({
+        name: "dbx",
+        version: "0.4.2",
     });
-    await notifyReload();
-    return text(`Connection "${config.name}" added (id: ${config.id}).`);
-});
-server.tool("dbx_remove_connection", "Remove a database connection from DBX", {
-    connection_name: z.string().describe("Name of the connection to remove"),
-}, async ({ connection_name }) => {
-    const removed = await backend.removeConnection(connection_name);
-    if (!removed)
-        return text(`Connection "${connection_name}" not found.`);
-    await notifyReload();
-    return text(`Connection "${connection_name}" removed.`);
-});
-function formatCell(value) {
-    if (value === null || value === undefined)
-        return "NULL";
-    if (typeof value === "object")
-        return JSON.stringify(value);
-    return String(value);
-}
-function appDataDir() {
-    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 getBridgeUrl() {
-    const portFile = join(appDataDir(), "mcp-bridge-port");
-    const port = (await readFile(portFile, "utf-8")).trim();
-    return `http://127.0.0.1:${port}`;
-}
-async function notifyReload() {
-    try {
-        const bridgeUrl = await getBridgeUrl();
-        await fetch(`${bridgeUrl}/reload-connections`, { method: "POST" });
-    }
-    catch { }
-}
-// Desktop-only tools: open table and execute-and-show require the Tauri bridge
-if (!isWebMode) {
-    server.tool("dbx_open_table", "Open a table in DBX desktop app UI. Requires DBX to be running.", {
+    server.tool("dbx_list_connections", "List all database connections configured in DBX", {}, async () => {
+        const connections = await backend.loadConnections();
+        if (connections.length === 0)
+            return text("No connections configured in DBX.");
+        const rows = connections.map((c) => [c.name, c.db_type, c.host, String(c.port), c.database || ""]);
+        return text(mdTable(["Name", "Type", "Host", "Port", "Database"], rows));
+    });
+    server.tool("dbx_list_tables", "List tables and views for a database connection", {
         connection_name: z.string().describe("Name of the DBX connection"),
-        table: z.string().describe("Table name to open"),
-        database: z.string().optional().describe("Database name"),
-        schema: z.string().optional().describe("Schema name"),
-    }, async ({ connection_name, table, database, schema }) => {
-        return bridgeRequest("/open-table", { connection_name, table, database, schema }, `Opened ${table} in DBX`);
+        schema: z.string().optional().describe("Schema name (default: public for PostgreSQL)"),
+    }, async ({ connection_name, schema }) => {
+        const config = await backend.findConnection(connection_name);
+        if (!config)
+            return text(`Connection "${connection_name}" not found`);
+        const tables = await backend.listTables(config, schema);
+        if (tables.length === 0)
+            return text("No tables found.");
+        const rows = tables.map((t) => [t.name, t.type]);
+        return text(mdTable(["Table", "Type"], rows));
     });
-    server.tool("dbx_execute_and_show", "Execute a SQL query in DBX desktop app UI and show results there. Requires DBX to be running.", {
+    server.tool("dbx_describe_table", "Get column definitions for a table", {
+        connection_name: z.string().describe("Name of the DBX connection"),
+        table: z.string().describe("Table name"),
+        schema: z.string().optional().describe("Schema name (default: public for PostgreSQL)"),
+    }, async ({ connection_name, table, schema }) => {
+        const config = await backend.findConnection(connection_name);
+        if (!config)
+            return text(`Connection "${connection_name}" not found`);
+        const columns = await backend.describeTable(config, table, schema);
+        if (columns.length === 0)
+            return text("No columns found.");
+        const rows = columns.map((c) => [
+            c.is_primary_key ? `${c.name} (PK)` : c.name,
+            c.data_type,
+            c.is_nullable ? "YES" : "NO",
+            c.column_default ?? "",
+            c.comment ?? "",
+        ]);
+        return text(mdTable(["Column", "Type", "Nullable", "Default", "Comment"], rows));
+    });
+    server.tool("dbx_execute_query", "Execute a SQL query on a database connection (max 100 rows returned)", {
         connection_name: z.string().describe("Name of the DBX connection"),
         sql: z.string().describe("SQL query to execute"),
-        database: z.string().optional().describe("Database name"),
-    }, async ({ connection_name, sql, database }) => {
+    }, async ({ connection_name, sql }) => {
+        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}`);
-        return bridgeRequest("/execute-query", { connection_name, sql, database }, "Query sent to DBX");
+        try {
+            const result = await backend.executeQuery(config, sql);
+            if (result.columns.length === 0)
+                return text(`Query executed. ${result.row_count} row(s) affected.`);
+            const rows = result.rows.map((r) => result.columns.map((c) => formatCell(r[c])));
+            return text(`${mdTable(result.columns, rows)}\n\n${result.row_count} row(s)`);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return text(`Query error: ${msg}`);
+        }
     });
-}
-async function bridgeRequest(path, body, successMsg) {
-    try {
-        const bridgeUrl = await getBridgeUrl();
-        const res = await fetch(`${bridgeUrl}${path}`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(body),
+    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, 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().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"),
+        ssl: z.boolean().default(false).describe("Enable SSL"),
+    }, async ({ name, db_type, host, port, username, password, database, ssl }) => {
+        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: resolvedPort,
+            username,
+            password,
+            database,
+            ssl,
+            ssh_enabled: false,
+        });
+        await notifyReload();
+        return text(`Connection "${config.name}" added (id: ${config.id}).`);
+    });
+    server.tool("dbx_remove_connection", "Remove a database connection from DBX", {
+        connection_name: z.string().describe("Name of the connection to remove"),
+    }, async ({ connection_name }) => {
+        const removed = await backend.removeConnection(connection_name);
+        if (!removed)
+            return text(`Connection "${connection_name}" not found.`);
+        await notifyReload();
+        return text(`Connection "${connection_name}" removed.`);
+    });
+    // Desktop-only tools: open table and execute-and-show require the Tauri bridge
+    if (!isWebMode) {
+        server.tool("dbx_open_table", "Open a table in DBX desktop app UI. Requires DBX to be running.", {
+            connection_name: z.string().describe("Name of the DBX connection"),
+            table: z.string().describe("Table name to open"),
+            database: z.string().optional().describe("Database name"),
+            schema: z.string().optional().describe("Schema name"),
+        }, async ({ connection_name, table, database, schema }) => {
+            return bridgeRequest("/open-table", { connection_name, table, database, schema }, `Opened ${table} in DBX`);
+        });
+        server.tool("dbx_execute_and_show", "Execute a SQL query in DBX desktop app UI and show results there. Requires DBX to be running.", {
+            connection_name: z.string().describe("Name of the DBX connection"),
+            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");
         });
-        if (res.ok)
-            return text(successMsg);
-        return text(`Failed: ${await res.text()}`);
-    }
-    catch {
-        return text("DBX is not running. Please start DBX first.");
     }
+    return server;
+}
+function formatCell(value) {
+    if (value === null || value === undefined)
+        return "NULL";
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
+async function bridgeRequest(path, body, successMsg) {
+    const res = await postBridge(path, body);
+    if (res.ok)
+        return text(successMsg);
+    return text(res.text.startsWith("DBX is not running") ? res.text : `Failed: ${res.text}`);
 }
 async function main() {
+    const backend = await createBackend();
+    const server = createDbxMcpServer(backend);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-main().catch((e) => {
-    console.error("MCP Server failed to start:", e);
-    process.exit(1);
-});
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((e) => {
+        console.error("MCP Server failed to start:", e);
+        process.exit(1);
+    });
+}

package/package.json

@@ -1,21 +1,20 @@
 {
   "name": "@dbx-app/mcp-server",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "mcpName": "io.github.t8y2/dbx",
   "description": "MCP server for DBX — query databases from Claude Code, Cursor, and other AI agents",
   "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
   "bin": {
+    "mcp-server": "dist/index.js",
     "dbx-mcp-server": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "server.json"
   ],
-  "scripts": {
-    "start": "tsx src/index.ts",
-    "test": "tsx --test tests/*.test.ts",
-    "build": "tsc",
-    "prepublishOnly": "tsc"
-  },
   "keywords": [
     "mcp",
     "database",
@@ -29,28 +28,22 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/t8y2/dbx",
-    "directory": "mcp"
+    "directory": "packages/mcp-server"
   },
-  "homepage": "https://github.com/t8y2/dbx/tree/main/mcp",
+  "homepage": "https://github.com/t8y2/dbx/tree/main/packages/mcp-server",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "better-sqlite3": "^12.9.0",
-    "keytar": "^7.9.0",
-    "mysql2": "^3.14.1",
-    "pg": "^8.16.0",
-    "zod": "^3.25.20"
+    "zod": "^3.25.20",
+    "@dbx-app/node-core": "^0.4.3"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.15.21",
-    "@types/pg": "^8.15.4",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "better-sqlite3",
-      "esbuild"
-    ]
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "test": "pnpm --filter @dbx-app/node-core build && tsx --test tests/*.test.ts",
+    "build": "pnpm --filter @dbx-app/node-core build && tsc"
   }
-}
+}

package/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.t8y2/dbx",
+  "description": "Query and manage databases from AI agents using connections configured in DBX.",
+  "repository": {
+    "url": "https://github.com/t8y2/dbx",
+    "source": "github"
+  },
+  "version": "0.4.3",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@dbx-app/mcp-server",
+      "version": "0.4.3",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/dist/connections.d.ts

@@ -1,25 +0,0 @@
-export interface ConnectionConfig {
-    id: string;
-    name: string;
-    db_type: string;
-    driver_profile?: string;
-    host: string;
-    port: number;
-    username: string;
-    password: string;
-    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>;
-export declare function removeConnection(name: string): Promise<boolean>;