feat(inspector): stdio MCP server transport support (#132)

* feat(inspector): stdio MCP server transport support

Add stdio transport alongside existing HTTP for connecting to MCP servers
that communicate over stdin/stdout.

## Architecture
- ConnectionParams discriminated union: { transport: 'http', url } | { transport: 'stdio', command, args?, env?, cwd? }
- ONE branch point at createTestClient() — all other code is transport-agnostic
- Auto-restart for stdio with exponential backoff (1s, 2s, 4s, max 3 retries)

## Changes

### Types & Transport (Phase 1)
- Add ConnectionParams type to @mcp-apps-kit/testing
- createTestClient() accepts ConnectionParams, branches to StdioClientTransport or StreamableHTTPClientTransport
- Add onTransportClose callback to TestClientOptions
- Add connectionParams field to ConnectionState

### Connection Chain (Phase 2)
- ConnectionManager.connect() accepts ConnectionParams with input validation
- Auto-restart logic: onTransportClose → exponential backoff reconnect (stdio only)
- ConnectionRegistry.createConnection() accepts ConnectionParams
- All callers updated (28+ test files, 4 source files)

### Tool API (Phase 3)
- connect_to_server tool supports both transports via Zod union schema
- Backward compatible: plain { url } still works (defaults to HTTP)

### Dashboard API (Phase 4)
- POST /dashboard/connections accepts ConnectionParams body
- Backward compat: { url } without transport field defaults to HTTP
- Response includes transport type

### Dashboard UI (Phase 5)
- Transport dropdown (HTTP/stdio) in ConnectionBar
- stdio mode: command + args inputs replace URL input
- Advanced Settings toggle: env vars + cwd (stdio only)
- Server history stores transport type, shows stdio: badge
- Selecting stdio history entry populates command/args fields

* fix(inspector): resolve stdio auto-restart race condition and label inconsistency

- Add connectionGeneration counter to ConnectionManager to prevent
  stale restart attempts after explicit disconnect()
- Align label format in test-client.ts to match connection.ts
  ('stdio: command' with space)
- Add stdio-transport behavioral test suite (18 tests)

* fix(inspector): remove unnecessary type assertion in connect tool

* test(testing): improve test-client coverage for stdio transport paths

Add mocked unit tests covering stdio/HTTP transport creation, env
merging, cwd forwarding, onTransportClose wiring, connection error
labels, and client operations (callTool, history, disconnect).

Branches coverage: 49.73% → 52.41% (above 50% threshold).

* fix(inspector): address PR review comments

- Throw error for missing HTTP URL instead of falling back to empty
  string (connect.ts)
- Use element-wise args comparison in server history dedup instead of
  join(' ') which can collide different arrays (useServerHistory.ts)
- Reset autoRestartAttempts on successful reconnect so subsequent
  crashes get full retry budget (connection.ts)
- Wrap disconnect() in auto-restart catch with .catch() to prevent
  swallowed errors (connection.ts)
- Standardize stdio label format with space after colon (connect.ts)

* fix(inspector): convert advanced settings to popover dropdown

- Replace inline collapsible with floating Popover component
- Settings gear button on right side of connection bar
- Popover: dark bg, shadow, z-1000, dismiss on click-outside/Escape
- Reusable Popover accepts panelStyle for future settings
- Button order: connect/disconnect → settings → close
- No header layout shift when settings are open

* fix(inspector): address PR review comments — security docs, label consistency, UI guards

- Standardize stdio display label to 'stdio:command args' (no space after colon)
  across connection.ts, connect.ts, test-client.ts and all tests
- Hoist argsEqual() to module scope in useServerHistory.ts for proper
  element-wise array comparison (prevents join collision)
- Add type guard for non-string args in history filter
- Add isCreating guard on handleKeyDown and handleSelectHistory in
  ConnectionBar.tsx to prevent duplicate connection requests
- Add JSDoc security warning on ConnectionParams.env about process.env merge
- Add inline SECURITY NOTE in test-client.ts env merging code

* security(testing): allowlist parent env vars for stdio child processes

Replace full process.env merge with explicit safe-var allowlist (PATH, HOME,
LANG, NODE_ENV, XDG dirs, etc.) when spawning stdio child processes.
Sensitive variables (API keys, credentials, tokens) are never inherited
automatically.

Add inheritEnv flag to ConnectionParams for explicit control:
- When env is provided: only safe parent vars + user overrides (default)
- When inheritEnv=false: only safe parent vars
- When neither env nor inheritEnv set: Node.js default (full process.env)

Addresses PR #132 security review comment on env var leakage.

---------

Co-authored-by: Sirius <sirius@clawd.bot>

Author: gabrypavanello

examples/minimal/tests/advanced-features.test.ts

@@ -393,9 +393,12 @@ describe("Advanced Features", () => {
       const server = await startTestServer(app, { port: testPort });
       await new Promise((resolve) => setTimeout(resolve, 100));
 
-      const client = await createTestClient(`http://localhost:${testPort}/v1/mcp`, {
-        trackHistory: true,
-      });
+      const client = await createTestClient(
+        { transport: "http", url: `http://localhost:${testPort}/v1/mcp` },
+        {
+          trackHistory: true,
+        }
+      );
 
       await client.callTool("greet", { name: "History1" });
       await client.callTool("greet", { name: "History2" });
@@ -418,7 +421,10 @@ describe("Advanced Features", () => {
       const testPort = 3014;
       const server = await startTestServer(app, { port: testPort });
       await new Promise((resolve) => setTimeout(resolve, 100));
-      const client = await createTestClient(`http://localhost:${testPort}/v1/mcp`);
+      const client = await createTestClient({
+        transport: "http",
+        url: `http://localhost:${testPort}/v1/mcp`,
+      });
 
       const tools = await client.listTools();
       expect(tools.some((t) => t.name === "greet")).toBe(true);
@@ -435,9 +441,12 @@ describe("Advanced Features", () => {
       await new Promise((resolve) => setTimeout(resolve, 100));
 
       // Client with short timeout
-      const client = await createTestClient(`http://localhost:${testPort}/v1/mcp`, {
-        timeout: 5000, // 5 second timeout
-      });
+      const client = await createTestClient(
+        { transport: "http", url: `http://localhost:${testPort}/v1/mcp` },
+        {
+          timeout: 5000, // 5 second timeout
+        }
+      );
 
       // Should complete within timeout
       const result = await client.callTool("greet", { name: "Timeout" });

examples/minimal/tests/greet-v1.test.ts

@@ -16,9 +16,12 @@ describe("Greet Tool V1", () => {
     const server = await startTestServer(app, { port: testPort });
     await new Promise((resolve) => setTimeout(resolve, 100));
 
-    const client = await createTestClient(`http://localhost:${testPort}/v1/mcp`, {
-      trackHistory: true,
-    });
+    const client = await createTestClient(
+      { transport: "http", url: `http://localhost:${testPort}/v1/mcp` },
+      {
+        trackHistory: true,
+      }
+    );
 
     env = {
       server,

examples/minimal/tests/greet-v2.test.ts

@@ -16,9 +16,12 @@ describe("Greet Tool V2", () => {
     const server = await startTestServer(app, { port: testPort });
     await new Promise((resolve) => setTimeout(resolve, 100));
 
-    const client = await createTestClient(`http://localhost:${testPort}/v2/mcp`, {
-      trackHistory: true,
-    });
+    const client = await createTestClient(
+      { transport: "http", url: `http://localhost:${testPort}/v2/mcp` },
+      {
+        trackHistory: true,
+      }
+    );
 
     env = {
       server,

examples/minimal/tests/integration.test.ts

@@ -15,10 +15,13 @@ describe("Minimal Example Integration", () => {
     const server = await startTestServer(app, { port: testPort });
     await new Promise((resolve) => setTimeout(resolve, 100));
 
-    const client = await createTestClient(`http://localhost:${testPort}/v1/mcp`, {
-      trackHistory: true,
-      timeout: 10000,
-    });
+    const client = await createTestClient(
+      { transport: "http", url: `http://localhost:${testPort}/v1/mcp` },
+      {
+        trackHistory: true,
+        timeout: 10000,
+      }
+    );
 
     env = {
       server,

examples/minimal/tests/integration/versioning.test.ts

@@ -17,13 +17,19 @@ describe("Versioning", () => {
     mainServer = await startTestServer(app as unknown, { port: testPort });
     await new Promise((resolve) => setTimeout(resolve, 100));
 
-    const v1Client = await createTestClient(`http://localhost:${testPort}/v1/mcp`, {
-      trackHistory: true,
-    });
-
-    const v2Client = await createTestClient(`http://localhost:${testPort}/v2/mcp`, {
-      trackHistory: true,
-    });
+    const v1Client = await createTestClient(
+      { transport: "http", url: `http://localhost:${testPort}/v1/mcp` },
+      {
+        trackHistory: true,
+      }
+    );
+
+    const v2Client = await createTestClient(
+      { transport: "http", url: `http://localhost:${testPort}/v2/mcp` },
+      {
+        trackHistory: true,
+      }
+    );
 
     v1Env = {
       server: mainServer,

examples/weather-app/tests/integration/server.test.ts

@@ -17,10 +17,13 @@ describe("Weather App MCP Server", () => {
     const server = await startTestServer(app, { port: 0 });
     await new Promise((r) => setTimeout(r, 100));
 
-    const client = await createTestClient(server.mcpUrl, {
-      trackHistory: true,
-      timeout: 15000,
-    });
+    const client = await createTestClient(
+      { transport: "http", url: server.mcpUrl },
+      {
+        trackHistory: true,
+        timeout: 15000,
+      }
+    );
 
     env = {
       server,

packages/create-app/src/index.ts

@@ -556,7 +556,7 @@ describe("${name} MCP Server", () => {
     const server = await startTestServer(app, { port: 0 });
     await new Promise((r) => setTimeout(r, 100));
 
-    const client = await createTestClient(server.mcpUrl, {
+    const client = await createTestClient({ transport: "http", url: server.mcpUrl }, {
       trackHistory: true,
       timeout: 10000,
     });
@@ -1106,7 +1106,7 @@ describe("${name} MCP Server", () => {
     const server = await startTestServer(app, { port: 0 });
     await new Promise((r) => setTimeout(r, 100));
 
-    const client = await createTestClient(server.mcpUrl, {
+    const client = await createTestClient({ transport: "http", url: server.mcpUrl }, {
       trackHistory: true,
       timeout: 10000,
     });

packages/inspector/src/connection-registry.ts

@@ -6,6 +6,7 @@
 
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
+import type { ConnectionParams } from "@mcp-apps-kit/testing";
 import { ConnectionManager } from "./connection";
 import type { ConnectOptions, ConnectionStatusOutput, InspectorServerOptions } from "./types";
 
@@ -61,12 +62,12 @@ export class ConnectionRegistry extends EventEmitter {
   /**
    * Create a new connection and connect to the target server.
    *
-   * @param url - MCP server URL to connect to.
+   * @param params - Connection parameters (transport type + config).
    * @param options - Connection options passed to the ConnectionManager.
    * @returns The new connection id and manager instance.
    */
   async createConnection(
-    url: string,
+    params: ConnectionParams,
     options?: ConnectOptions
   ): Promise<{ id: string; connectionManager: ConnectionManager }> {
     if (this.connections.size >= this.maxConnections) {
@@ -80,7 +81,7 @@ export class ConnectionRegistry extends EventEmitter {
     });
 
     try {
-      await connectionManager.connect(url, options);
+      await connectionManager.connect(params, options);
     } catch (error) {
       try {
         await connectionManager.disconnect();