@bytebase/dbhub 0.0.7 → 0.1.0

package/README.md

@@ -20,20 +20,34 @@ DBHub is a universal database gateway implementing the Model Context Protocol (M
  |      Clients     |    |              |    |                  |
  |                  |    |              +--->+     MySQL        |
  |                  |    |              |    |                  |
- |                  |    |              +--->+     DuckDB       |
- |                  |    |              |    |      (soon)      |
  |                  |    |              +--->+  Other Databases |
- |                  |    |              |    |     (coming)     |
+ |                  |    |              |    |                  |
  +------------------+    +--------------+    +------------------+
       MCP Clients           MCP Server             Databases
 ```
 
-## Features
+## Supported Matrix
+
+### Database Resources
+
+| Resource               | URI Format | PostgreSQL | MySQL | SQL Server | SQLite |
+|------------------------|:----------:|:----------:|:-----:|:----------:|:------:|
+| Tables                 | `db://tables` |     ✅     |   ✅  |     ✅     |   ✅   |
+| Schema                 | `db://schema/{tableName}` |     ✅     |   ✅  |     ✅     |   ✅   |
+
+### Database Tools
+
+| Tool                   | Command Name       | PostgreSQL | MySQL | SQL Server | SQLite |
+|------------------------|:------------------:|:----------:|:-----:|:----------:|:------:|
+| Execute Query          | `run_query`        |     ✅     |   ✅  |     ✅     |   ✅   |
+| List Connectors        | `list_connectors`  |     ✅     |   ✅  |     ✅     |   ✅   |
+
+### Prompt Capabilities
 
-- Browse available tables in the database
-- View schema information for tables
-- Run read-only SQL queries against the database
-- Safety checks to prevent dangerous queries
+| Prompt                 | Command Name     | PostgreSQL | MySQL | SQL Server | SQLite |
+|------------------------|:----------------:|:----------:|:-----:|:----------:|:------:|
+| Generate SQL           | `generate_sql`   |     ✅     |   ✅  |     ✅     |   ✅   |
+| Explain DB Elements    | `explain_db`     |     ✅     |   ✅  |     ✅     |   ✅   |
 
 ## Installation
 
@@ -48,24 +62,17 @@ docker run --rm --init \
    --transport sse \
    --port 8080 \
    --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
+```
 
-# SQLite in-memory example
-docker run --rm --init \
-   --name dbhub \
-   --publish 8080:8080 \
-   bytebase/dbhub \
-   --transport sse \
-   --port 8080 \
-   --dsn "sqlite::memory:"
-
-# MySQL example
+```bash
+# Demo mode with sample employee database
 docker run --rm --init \
    --name dbhub \
    --publish 8080:8080 \
    bytebase/dbhub \
    --transport sse \
    --port 8080 \
-   --dsn "mysql://user:password@localhost:3306/dbname"
+   --demo
 ```
 
 ### NPM
@@ -73,19 +80,80 @@ docker run --rm --init \
 ```bash
 # PostgreSQL example
 npx @bytebase/dbhub --transport sse --port 8080 --dsn "postgres://user:password@localhost:5432/dbname"
+```
 
-# SQLite example
-npx @bytebase/dbhub --transport sse --port 8080 --dsn "sqlite:///path/to/database.db"
+```bash
+# Demo mode with sample employee database
+npx @bytebase/dbhub --transport sse --port 8080 --demo
+```
 
-# MySQL example
-npx @bytebase/dbhub --transport sse --port 8080 --dsn "mysql://user:password@localhost:3306/dbname"
+### Claude Desktop
+
+![claude-desktop](https://raw.githubusercontent.com/bytebase/dbhub/main/resources/images/claude-desktop.webp)
+
+- Claude Desktop only supports `stdio` transport https://github.com/orgs/modelcontextprotocol/discussions/16
+
+```json
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "dbhub-postgres-docker": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "bytebase/dbhub",
+        "--transport",
+        "stdio",
+        "--dsn",
+        // Use host.docker.internal as the host if connecting to the local db
+        "postgres://user:password@host.docker.internal:5432/dbname?sslmode=disable"
+      ]
+    },
+    "dbhub-postgres-npx": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@bytebase/dbhub",
+        "--transport",
+        "stdio",
+        "--dsn",
+        "postgres://user:password@localhost:5432/dbname?sslmode=disable"
+      ]
+    },
+    "dbhub-demo": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@bytebase/dbhub",
+        "--transport",
+        "stdio",
+        "--demo"
+      ]
+    }
+  }
+}
 ```
 
+### Cursor
+
+![cursor](https://raw.githubusercontent.com/bytebase/dbhub/main/resources/images/cursor.webp)
+
+- Cursor supports both `stdio` and `sse`.
+- Follow [Cursor MCP guide](https://docs.cursor.com/context/model-context-protocol) and make sure to use [Agent](https://docs.cursor.com/chat/agent) mode.
+
 ## Usage
 
 ### Configure your database connection
 
-Database Source Name (DSN) is required to connect to your database. You can provide this in several ways:
+You can use DBHub in demo mode with a sample employee database for testing:
+
+```bash
+pnpm dev --demo
+```
+
+For real databases, a Database Source Name (DSN) is required. You can provide this in several ways:
 
 - **Command line argument** (highest priority):
 
@@ -107,8 +175,6 @@ Database Source Name (DSN) is required to connect to your database. You can prov
   DSN=postgres://user:password@localhost:5432/dbname?sslmode=disable
   ```
 
-### Supported DSN formats
-
 DBHub supports the following database connection string formats:
 
 | Database   | DSN Format                                                | Example                                                 |
@@ -135,119 +201,11 @@ DBHub supports the following database connection string formats:
 
 | Option    | Description                                                     | Default                             |
 | :-------- | :-------------------------------------------------------------- | :---------------------------------- |
-| dsn       | Database connection string                                      | Required if not set via environment |
+| demo      | Run in demo mode with sample employee database                  | `false`                             |
+| dsn       | Database connection string                                      | Required if not in demo mode        |
 | transport | Transport mode: `stdio` or `sse`                                | `stdio`                             |
 | port      | HTTP server port (only applicable when using `--transport=sse`) | `8080`                              |
 
-### Claude Desktop
-
-![claude-desktop](https://raw.githubusercontent.com/bytebase/dbhub/main/resources/images/claude-desktop.webp)
-
-- Claude Desktop only supports `stdio` transport https://github.com/orgs/modelcontextprotocol/discussions/16
-
-#### Docker
-
-```json
-// claude_desktop_config.json - PostgreSQL example
-{
-  "mcpServers": {
-    "dbhub-postgres": {
-      "command": "docker",
-      "args": [
-        "run",
-        "-i",
-        "--rm",
-        "bytebase/dbhub",
-        "--transport",
-        "stdio",
-        "--dsn",
-        // Use host.docker.internal as the host if connecting to the local db
-        "postgres://user:password@host.docker.internal:5432/dbname?sslmode=disable"
-      ]
-    }
-  }
-}
-```
-
-```json
-// claude_desktop_config.json - SQLite example (in-memory)
-{
-  "mcpServers": {
-    "dbhub-sqlite": {
-      "command": "docker",
-      "args": [
-        "run",
-        "-i",
-        "--rm",
-        "bytebase/dbhub",
-        "--transport",
-        "stdio",
-        "--dsn",
-        "sqlite::memory:"
-      ]
-    }
-  }
-}
-```
-
-#### NPX
-
-```json
-// claude_desktop_config.json - PostgreSQL example
-{
-  "mcpServers": {
-    "dbhub-postgres": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@bytebase/dbhub",
-        "--transport",
-        "stdio",
-        "--dsn",
-        "postgres://user:password@localhost:5432/dbname?sslmode=disable"
-      ]
-    }
-  }
-}
-```
-
-```json
-// claude_desktop_config.json - SQLite example
-{
-  "mcpServers": {
-    "dbhub-sqlite": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@bytebase/dbhub",
-        "--transport",
-        "stdio",
-        "--dsn",
-        "sqlite:///path/to/database.db"
-      ]
-    }
-  }
-}
-```
-
-```json
-// claude_desktop_config.json - MySQL example
-{
-  "mcpServers": {
-    "dbhub-mysql": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@bytebase/dbhub",
-        "--transport",
-        "stdio",
-        "--dsn",
-        "mysql://user:password@localhost:3306/dbname"
-      ]
-    }
-  }
-}
-```
 
 ## Development
 
@@ -276,15 +234,6 @@ DBHub supports the following database connection string formats:
 ```bash
 # PostgreSQL example
 TRANSPORT=stdio DSN="postgres://user:password@localhost:5432/dbname?sslmode=disable" npx @modelcontextprotocol/inspector node /path/to/dbhub/dist/index.js
-
-# SQLite example
-TRANSPORT=stdio DSN="sqlite:///path/to/database.db" npx @modelcontextprotocol/inspector node /path/to/dbhub/dist/index.js
-
-# SQLite in-memory example  
-TRANSPORT=stdio DSN="sqlite::memory:" npx @modelcontextprotocol/inspector node /path/to/dbhub/dist/index.js
-
-# MySQL example
-TRANSPORT=stdio DSN="mysql://user:password@localhost:3306/dbname" npx @modelcontextprotocol/inspector node /path/to/dbhub/dist/index.js
 ```
 
 #### SSE

package/dist/config/demo-loader.js

@@ -0,0 +1,45 @@
+/**
+ * Demo data loader for SQLite in-memory database
+ *
+ * This module loads the sample employee database into the SQLite in-memory database
+ * when the --demo flag is specified.
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+// Create __dirname equivalent for ES modules
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Path to sample data files
+const DEMO_DATA_DIR = path.join(__dirname, '..', '..', 'resources', 'employee-sqlite');
+/**
+ * Load SQL file contents
+ */
+export function loadSqlFile(fileName) {
+    const filePath = path.join(DEMO_DATA_DIR, fileName);
+    return fs.readFileSync(filePath, 'utf8');
+}
+/**
+ * Get SQLite DSN for in-memory database
+ */
+export function getInMemorySqliteDSN() {
+    return 'sqlite::memory:';
+}
+/**
+ * Load SQL files sequentially
+ */
+export function getSqliteInMemorySetupSql() {
+    // First, load the schema
+    let sql = loadSqlFile('employee.sql');
+    // Replace .read directives with the actual file contents
+    // This is necessary because in-memory SQLite can't use .read
+    const readRegex = /\.read\s+([a-zA-Z0-9_]+\.sql)/g;
+    let match;
+    while ((match = readRegex.exec(sql)) !== null) {
+        const includePath = match[1];
+        const includeContent = loadSqlFile(includePath);
+        // Replace the .read line with the file contents
+        sql = sql.replace(match[0], includeContent);
+    }
+    return sql;
+}

package/dist/config/env.js

@@ -62,6 +62,14 @@ export function loadEnvFiles() {
     }
     return null;
 }
+/**
+ * Check if demo mode is enabled from command line args
+ * Returns true if --demo flag is provided
+ */
+export function isDemoMode() {
+    const args = parseCommandLineArgs();
+    return args.demo === 'true';
+}
 /**
  * Resolve DSN from command line args, environment variables, or .env files
  * Returns the DSN and its source, or null if not found
@@ -69,7 +77,16 @@ export function loadEnvFiles() {
 export function resolveDSN() {
     // Get command line arguments
     const args = parseCommandLineArgs();
-    // 1. Check command line arguments first (highest priority)
+    // Check for demo mode first (highest priority)
+    if (isDemoMode()) {
+        // Will use in-memory SQLite with demo data
+        return {
+            dsn: 'sqlite::memory:',
+            source: 'demo mode',
+            isDemo: true
+        };
+    }
+    // 1. Check command line arguments 
     if (args.dsn) {
         return { dsn: args.dsn, source: 'command line argument' };
     }

package/dist/connectors/manager.js

@@ -15,7 +15,7 @@ export class ConnectorManager {
     /**
      * Initialize and connect to the database using a DSN
      */
-    async connectWithDSN(dsn) {
+    async connectWithDSN(dsn, initScript) {
         // First try to find a connector that can handle this DSN
         let connector = ConnectorRegistry.getConnectorForDSN(dsn);
         if (!connector) {
@@ -23,7 +23,7 @@ export class ConnectorManager {
         }
         this.activeConnector = connector;
         // Connect to the database
-        await this.activeConnector.connect(dsn);
+        await this.activeConnector.connect(dsn, initScript);
         this.connected = true;
     }
     /**

package/dist/connectors/sqlite/index.js

@@ -67,7 +67,7 @@ export class SQLiteConnector {
         this.db = null;
         this.dbPath = ':memory:'; // Default to in-memory database
     }
-    async connect(dsn) {
+    async connect(dsn, initScript) {
         const config = this.dsnParser.parse(dsn);
         this.dbPath = config.dbPath;
         return new Promise((resolve, reject) => {
@@ -79,7 +79,22 @@ export class SQLiteConnector {
                 else {
                     // Can't use console.log here because it will break the stdio transport
                     console.error("Successfully connected to SQLite database");
-                    resolve();
+                    // If an initialization script is provided, run it
+                    if (initScript) {
+                        this.db.exec(initScript, (err) => {
+                            if (err) {
+                                console.error("Failed to initialize database with script:", err);
+                                reject(err);
+                            }
+                            else {
+                                console.error("Successfully initialized database with script");
+                                resolve();
+                            }
+                        });
+                    }
+                    else {
+                        resolve();
+                    }
                 }
             });
         });

package/dist/server.js

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'url';
 import { ConnectorManager } from './connectors/manager.js';
 import { ConnectorRegistry } from './connectors/interface.js';
 import { resolveDSN, resolveTransport, resolvePort } from './config/env.js';
+import { getSqliteInMemorySetupSql } from './config/demo-loader.js';
 import { registerResources } from './resources/index.js';
 import { registerTools } from './tools/index.js';
 import { registerPrompts } from './prompts/index.js';
@@ -23,7 +24,8 @@ export const SERVER_VERSION = packageJson.version;
 /**
  * Generate ASCII art banner with version information
  */
-export function generateBanner(version) {
+export function generateBanner(version, isDemo = false) {
+    const demoText = isDemo ? " [DEMO MODE]" : "";
     return `
  _____  ____  _   _       _     
 |  __ \\|  _ \\| | | |     | |    
@@ -32,7 +34,7 @@ export function generateBanner(version) {
 | |__| | |_) | | | | |_| | |_) |
 |_____/|____/|_| |_|\\__,_|_.__/ 
                                 
-v${version} - Universal Database MCP Server
+v${version}${demoText} - Universal Database MCP Server
 `;
 }
 /**
@@ -51,9 +53,10 @@ export async function main() {
 ERROR: Database connection string (DSN) is required.
 Please provide the DSN in one of these ways (in order of priority):
 
-1. Command line argument: --dsn="your-connection-string"
-2. Environment variable: export DSN="your-connection-string"
-3. .env file: DSN=your-connection-string
+1. Use demo mode: --demo (uses in-memory SQLite with sample employee database)
+2. Command line argument: --dsn="your-connection-string"
+3. Environment variable: export DSN="your-connection-string"
+4. .env file: DSN=your-connection-string
 
 Example formats:
 ${sampleFormats}
@@ -75,13 +78,21 @@ See documentation for more details on configuring database connections.
         const connectorManager = new ConnectorManager();
         console.error(`Connecting with DSN: ${dsnData.dsn}`);
         console.error(`DSN source: ${dsnData.source}`);
-        await connectorManager.connectWithDSN(dsnData.dsn);
+        // If in demo mode, load the employee database
+        if (dsnData.isDemo) {
+            console.error('Running in demo mode with sample employee database');
+            const initScript = getSqliteInMemorySetupSql();
+            await connectorManager.connectWithDSN(dsnData.dsn, initScript);
+        }
+        else {
+            await connectorManager.connectWithDSN(dsnData.dsn);
+        }
         // Resolve transport type
         const transportData = resolveTransport();
         console.error(`Using transport: ${transportData.type}`);
         console.error(`Transport source: ${transportData.source}`);
         // Print ASCII art banner with version and slogan
-        console.error(generateBanner(SERVER_VERSION));
+        console.error(generateBanner(SERVER_VERSION, dsnData.isDemo));
         // Set up transport based on type
         if (transportData.type === 'sse') {
             // Set up Express server for SSE transport

package/dist/tools/list-connectors.js

@@ -1,22 +1,42 @@
 import { ConnectorManager } from '../connectors/manager.js';
 import { ConnectorRegistry } from '../connectors/interface.js';
 import { createToolSuccessResponse } from '../utils/response-formatter.js';
+import { isDemoMode } from '../config/env.js';
 /**
  * list_connectors tool handler
  * Lists all available database connectors and their sample DSNs
+ * Indicates which connector is active based on current DSN
  */
 export async function listConnectorsToolHandler(_args, _extra) {
     const connectors = ConnectorManager.getAvailableConnectors();
     const samples = ConnectorRegistry.getAllSampleDSNs();
+    // Get active connector if possible
+    let activeConnectorId = null;
+    try {
+        // Check if we have an active connection using static method
+        const activeConnector = ConnectorManager.getCurrentConnector();
+        activeConnectorId = activeConnector.id;
+    }
+    catch (error) {
+        // No active connector yet or not connected
+    }
+    // If we're in demo mode, SQLite should be active
+    const isDemo = isDemoMode();
+    if (isDemo && !activeConnectorId) {
+        activeConnectorId = 'sqlite';
+    }
     // Convert to a more structured format
     const sampleObjects = Object.entries(samples).map(([id, dsn]) => ({
         id,
-        dsn
+        dsn,
+        active: id === activeConnectorId
     }));
     // Prepare response data
     const responseData = {
         connectors: sampleObjects,
-        count: sampleObjects.length
+        count: sampleObjects.length,
+        activeConnector: activeConnectorId,
+        demoMode: isDemo
     };
     // Use the utility to create a standardized response
     return createToolSuccessResponse(responseData);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytebase/dbhub",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "description": "Universal Database MCP Server",
   "main": "dist/index.js",
   "type": "module",