fix: only run http server/admin console if --transport http (#144)

* docs: add design for disabling HTTP server in stdio mode

Addresses issue #143 where stdio transport still starts HTTP server
on port 8080, causing conflicts when running multiple instances.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix: disable HTTP server when using stdio transport

Fixes #143 - Multiple DBHub instances with stdio transport can now
run simultaneously without port conflicts.

Changes:
- HTTP server (admin console, /mcp endpoint, API) only starts in http mode
- stdio mode is now pure MCP-over-stdio with no network listeners
- Updated console output to show helpful connection message for stdio users

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* docs: update transport option documentation

Clarifies the behavior difference between stdio and http transports:
- stdio: pure MCP-over-stdio, no HTTP server, allows multiple instances
- http: HTTP server with admin console, MCP endpoint, and APIs

Related to #143

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* chore: remove plan

* chore: minor tweak

---------

Co-authored-by: Claude <[email protected]>

Author: tianzhou

docs/config/server-options.mdx

@@ -152,22 +152,31 @@ title: "Server Options"
   Transport protocol for MCP communication.
 
   **Options:**
-  - `stdio` - For desktop tools (Claude Desktop, Claude Code, Cursor with stdio config)
-  - `http` - For browser and network clients, streamable HTTP transport
+  - `stdio` - For desktop tools (Claude Desktop, Claude Code, Cursor). Pure MCP-over-stdio with no HTTP server.
+  - `http` - For browser and network clients. Starts HTTP server with MCP endpoint, admin console, and API.
+
+  | Feature | `stdio` | `http` |
+  |---------|:-------:|:------:|
+  | MCP communication | stdin/stdout | HTTP POST `/mcp` |
+  | Admin console | ❌ | ✅ `http://host:port/` |
+  | Health check | ❌ | ✅ `/healthz` |
+  | API | ❌ | ✅ `/api/xxx` |
+  | Multiple instances | ✅ No port conflicts | Requires different ports |
 
   ```bash
-  # stdio (default) - for Claude Desktop, Claude Code
+  # stdio (default) - for Claude Desktop, Claude Code, Cursor
+  # No HTTP server started
   npx @bytebase/dbhub --transport stdio --dsn "..."
 
-  # http - for web clients and remote access
+  # http - for web clients, admin console, and remote access
   npx @bytebase/dbhub --transport http --port 8080 --dsn "..."
   ```
 </ParamField>
 
 ### port
 
 <ParamField path="--port" type="number" env="PORT" default="8080">
-  HTTP server port. Only applicable when using `--transport=http`.
+  HTTP server port. Only used when `--transport=http`. Ignored for stdio transport.
 
   ```bash
   npx @bytebase/dbhub --transport http --port 3000 --dsn "..."

src/server.ts

@@ -124,12 +124,12 @@ See documentation for more details on configuring database connections.
     // Resolve transport type (for MCP server)
     const transportData = resolveTransport();
     console.error(`MCP transport: ${transportData.type}`);
-    console.error(`Transport source: ${transportData.source}`);
 
-    // Resolve port for HTTP server (always start HTTP for frontend)
-    const portData = resolvePort();
-    const port = portData.port;
-    console.error(`HTTP server port: ${port} (source: ${portData.source})`);
+    // Resolve port for HTTP server (only needed for http transport)
+    const portData = transportData.type === "http" ? resolvePort() : null;
+    if (portData) {
+      console.error(`HTTP server port: ${portData.port} (source: ${portData.source})`);
+    }
 
     // Print ASCII art banner with version and slogan
     const readonly = isReadOnlyMode();
@@ -161,46 +161,47 @@ See documentation for more details on configuring database connections.
 
     console.error(generateBanner(SERVER_VERSION, activeModes));
 
-    // Always set up Express server for frontend (regardless of MCP transport)
-    const app = express();
-
-    // Enable JSON parsing
-    app.use(express.json());
-
-    // Handle CORS and security headers
-    app.use((req, res, next) => {
-      // Validate Origin header to prevent DNS rebinding attacks
-      const origin = req.headers.origin;
-      if (origin && !origin.startsWith('http://localhost') && !origin.startsWith('https://localhost')) {
-        return res.status(403).json({ error: 'Forbidden origin' });
-      }
-
-      res.header('Access-Control-Allow-Origin', origin || 'http://localhost');
-      res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-      res.header('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');
-      res.header('Access-Control-Allow-Credentials', 'true');
-
-      if (req.method === 'OPTIONS') {
-        return res.sendStatus(200);
-      }
-      next();
-    });
-
-    // Serve static frontend files
-    const frontendPath = path.join(__dirname, "public");
-    app.use(express.static(frontendPath));
-
-    // Health check endpoint
-    app.get("/healthz", (req, res) => {
-      res.status(200).send("OK");
-    });
-
-    // Data sources API endpoints
-    app.get("/api/sources", listSources);
-    app.get("/api/sources/:sourceId", getSource);
-
-    // Set up MCP endpoint if using HTTP transport
+    // Set up transport-specific server
     if (transportData.type === "http") {
+      // HTTP transport: Start Express server with MCP endpoint and admin console
+      const port = portData!.port;
+      const app = express();
+
+      // Enable JSON parsing
+      app.use(express.json());
+
+      // Handle CORS and security headers
+      app.use((req, res, next) => {
+        // Validate Origin header to prevent DNS rebinding attacks
+        const origin = req.headers.origin;
+        if (origin && !origin.startsWith('http://localhost') && !origin.startsWith('https://localhost')) {
+          return res.status(403).json({ error: 'Forbidden origin' });
+        }
+
+        res.header('Access-Control-Allow-Origin', origin || 'http://localhost');
+        res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+        res.header('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');
+        res.header('Access-Control-Allow-Credentials', 'true');
+
+        if (req.method === 'OPTIONS') {
+          return res.sendStatus(200);
+        }
+        next();
+      });
+
+      // Serve static frontend files
+      const frontendPath = path.join(__dirname, "public");
+      app.use(express.static(frontendPath));
+
+      // Health check endpoint
+      app.get("/healthz", (req, res) => {
+        res.status(200).send("OK");
+      });
+
+      // Data sources API endpoints
+      app.get("/api/sources", listSources);
+      app.get("/api/sources/:sourceId", getSource);
+
       // Main endpoint for streamable HTTP transport
       app.post("/mcp", async (req, res) => {
         try {
@@ -222,36 +223,31 @@ See documentation for more details on configuring database connections.
           }
         }
       });
-    }
 
-    // SPA fallback - serve index.html for all non-API routes
-    app.get("*", (req, res) => {
-      res.sendFile(path.join(frontendPath, "index.html"));
-    });
-
-    // Start the HTTP server (always for frontend)
-    app.listen(port, '0.0.0.0', () => {
-      // In development mode, suggest using the Vite dev server for hot reloading
-      if (process.env.NODE_ENV === 'development') {
-        console.error('🚀 Development mode detected!');
-        console.error('   Admin console dev server (with HMR): http://localhost:5173');
-        console.error('   Backend API: http://localhost:8080');
-        console.error('');
-      } else {
-        console.error(`Admin console at http://0.0.0.0:${port}/`);
-      }
-
-      if (transportData.type === "http") {
-        console.error(`MCP server endpoint at http://0.0.0.0:${port}/mcp`);
-      }
-    });
+      // SPA fallback - serve index.html for all non-API routes
+      app.get("*", (req, res) => {
+        res.sendFile(path.join(frontendPath, "index.html"));
+      });
 
-    // If using STDIO transport, also set up STDIO connection for MCP
-    if (transportData.type === "stdio") {
+      // Start the HTTP server
+      app.listen(port, '0.0.0.0', () => {
+        // In development mode, suggest using the Vite dev server for hot reloading
+        if (process.env.NODE_ENV === 'development') {
+          console.error('Development mode detected!');
+          console.error('   Admin console dev server (with HMR): http://localhost:5173');
+          console.error('   Backend API: http://localhost:8080');
+          console.error('');
+        } else {
+          console.error(`Admin console at http://0.0.0.0:${port}/`);
+        }
+        console.error(`MCP server endpoint at http://0.0.0.0:${port}/mcp`);
+      });
+    } else {
+      // STDIO transport: Pure MCP-over-stdio, no HTTP server
       const server = createServer();
       const transport = new StdioServerTransport();
-      console.error("Starting MCP with STDIO transport");
       await server.connect(transport);
+      console.error("MCP server running on stdio");
 
       // Listen for SIGINT to gracefully shut down
       process.on("SIGINT", async () => {