feat: add —demo mode

Author: tianzhou

README.md

@@ -62,6 +62,18 @@ docker run --rm --init \
    --transport sse \
    --port 8080 \
    --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
+```
+
+```bash
+# Demo mode with sample employee database
+docker run --rm --init \
+   --name dbhub \
+   --publish 8080:8080 \
+   bytebase/dbhub \
+   --transport sse \
+   --port 8080 \
+   --demo
+```
 
 ### NPM
 
@@ -70,14 +82,19 @@ docker run --rm --init \
 npx @bytebase/dbhub --transport sse --port 8080 --dsn "postgres://user:password@localhost:5432/dbname"
 ```
 
+```bash
+# Demo mode with sample employee database
+npx @bytebase/dbhub --transport sse --port 8080 --demo
+```
+
 ### 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 - PostgreSQL example
+// claude_desktop_config.json
 {
   "mcpServers": {
     "dbhub-postgres-docker": {
@@ -104,6 +121,16 @@ npx @bytebase/dbhub --transport sse --port 8080 --dsn "postgres://user:password@
         "--dsn",
         "postgres://user:password@localhost:5432/dbname?sslmode=disable"
       ]
+    },
+    "dbhub-demo": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@bytebase/dbhub",
+        "--transport",
+        "stdio",
+        "--demo"
+      ]
     }
   }
 }
@@ -120,7 +147,13 @@ npx @bytebase/dbhub --transport sse --port 8080 --dsn "postgres://user:password@
 
 ### 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):
 
@@ -168,7 +201,8 @@ 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`                              |
 

package.json

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

src/config/demo-loader.ts

@@ -0,0 +1,54 @@
+/**
+ * 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: string): string {
+  const filePath = path.join(DEMO_DATA_DIR, fileName);
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+/**
+ * Get SQLite DSN for in-memory database
+ */
+export function getInMemorySqliteDSN(): string {
+  return 'sqlite::memory:';
+}
+
+/**
+ * Load SQL files sequentially
+ */
+export function getSqliteInMemorySetupSql(): string {
+  // 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;
+}

src/config/env.ts

@@ -71,15 +71,34 @@ export function loadEnvFiles(): string | null {
   return null;
 }
 
+/**
+ * Check if demo mode is enabled from command line args
+ * Returns true if --demo flag is provided
+ */
+export function isDemoMode(): boolean {
+  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
  */
-export function resolveDSN(): { dsn: string; source: string } | null {
+export function resolveDSN(): { dsn: string; source: string; isDemo?: boolean } | null {
   // 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' };
   }

src/connectors/interface.ts

@@ -49,8 +49,8 @@ export interface Connector {
   /** DSN parser for this connector */
   dsnParser: DSNParser;
 
-  /** Connect to the database using DSN */
-  connect(dsn: string): Promise<void>;
+  /** Connect to the database using DSN, with optional init script */
+  connect(dsn: string, initScript?: string): Promise<void>;
 
   /** Close the connection */
   disconnect(): Promise<void>;

src/connectors/manager.ts

@@ -19,7 +19,7 @@ export class ConnectorManager {
   /**
    * Initialize and connect to the database using a DSN
    */
-  async connectWithDSN(dsn: string): Promise<void> {
+  async connectWithDSN(dsn: string, initScript?: string): Promise<void> {
     // First try to find a connector that can handle this DSN
     let connector = ConnectorRegistry.getConnectorForDSN(dsn);
 
@@ -30,7 +30,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;
   }
 

src/connectors/sqlite/index.ts

@@ -84,7 +84,7 @@ export class SQLiteConnector implements Connector {
   private db: sqlite3.Database | null = null;
   private dbPath: string = ':memory:'; // Default to in-memory database
 
-  async connect(dsn: string): Promise<void> {
+  async connect(dsn: string, initScript?: string): Promise<void> {
     const config = this.dsnParser.parse(dsn);
     this.dbPath = config.dbPath;
 
@@ -96,7 +96,21 @@ export class SQLiteConnector implements Connector {
         } 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();
+          }
         }
       });
     });

src/server.ts

@@ -8,7 +8,8 @@ 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 { resolveDSN, resolveTransport, resolvePort, isDemoMode } 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';
@@ -28,7 +29,9 @@ export const SERVER_VERSION = packageJson.version;
 /**
  * Generate ASCII art banner with version information
  */
-export function generateBanner(version: string): string {
+export function generateBanner(version: string, isDemo: boolean = false): string {
+  const demoText = isDemo ? " [DEMO MODE]" : "";
+  
   return `
  _____  ____  _   _       _     
 |  __ \\|  _ \\| | | |     | |    
@@ -37,7 +40,7 @@ export function generateBanner(version: string): string {
 | |__| | |_) | | | | |_| | |_) |
 |_____/|____/|_| |_|\\__,_|_.__/ 
                                 
-v${version} - Universal Database MCP Server
+v${version}${demoText} - Universal Database MCP Server
 `;
 }
 
@@ -59,9 +62,10 @@ export async function main(): Promise<void> {
 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}
@@ -86,15 +90,23 @@ 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') {