Port v1.5 web dev backend (vite-hono-plugin + remote-server bootstrap) (#1321)

* feat(web): port v1.5 dev backend (vite-hono-plugin + sandbox + remote-server bootstrap)

Ports the v1.5 in-process dev backend into v2 so `npm run dev` serves the
Hono remote-server (`/api/*`) alongside the Vite-served browser app. Without
this, the browser-side `createRemoteTransport` had nothing to talk to during
local development.

Adds under `clients/web/server/`:
- vite-hono-plugin.ts (Hono middleware on the Vite dev server; gated to
  `apply: 'serve'` and skipped when `process.env.VITEST` is set so it stays
  inert in vitest/storybook runs)
- sandbox-controller.ts (standalone HTTP server for the MCP Apps sandbox)
- web-server-config.ts (env parsing + initial-config payload + banner;
  `autoOpen` defaults off under VITEST so test runs don't shell out to `open`)
- server.ts (standalone Hono prod server for the future v2 launcher, #1246)
- start-vite-dev-server.ts (in-process Vite starter for the future launcher)
- vite-base-config.ts (shared optimizeDeps exclusions)

Wires `honoMiddlewarePlugin(buildWebServerConfigFromEnv())` into
`vite.config.ts` with `apply: 'serve'`. Adds the `open` dependency and a
DOM lib + `@inspector/core/*` path alias to `tsconfig.node.json` so the
dev-backend files type-check alongside vite.config.ts.

Coverage: web-server-config.ts (100% lines), sandbox-controller.ts (91% lines),
and vite-base-config.ts (100%) all clear the per-file gate. The Vite plugin,
prod server, and dev-server starter are excluded from coverage as runtime
glue exercised by `npm run dev` end-to-end (callers covered separately;
their logic lives in core/mcp/remote/node, which integration tests already
exercise).

Closes #1320.
Unblocks #1244 (Wire App.tsx) — its test plan can now run end-to-end.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(web/server): address PR review feedback on the dev-backend port

- sandbox-controller: resolve start() with empty values on listen error
  (e.g. EADDRINUSE on a fixed MCP_SANDBOX_PORT) instead of leaving the
  promise pending forever. Without this, the Vite plugin's
  `await sandboxController.start()` could hang the entire dev backend on a
  port collision. Banner now silently omits the sandbox line; getUrl()
  keeps returning null. Adds a regression test exercising the EADDRINUSE
  path against a real socket.
- vite-hono-plugin: listen for `error` and `close` on the incoming request
  stream (in addition to `end`) so an aborted POST/PUT (browser navigates
  mid-upload) doesn't leak the middleware indefinitely.
- vite-hono-plugin: add a `.catch()` to the initial `pump()` kickoff so a
  sync throw before the first `await reader.read()` can't surface as an
  unhandled rejection.
- sandbox_proxy.html: drop the stale CSP comment — v1.5's sandbox HTTP
  server never set CSP either; this PR doesn't regress anything. Replace
  with the actual isolation model (iframe sandbox attribute + origin
  allowlist) so future readers don't assume a CSP header is enforced.
- Hoist `WebServerHandle` to a shared `server/types.ts` so the future
  launcher port (#1246) doesn't need to pick one of two duplicate
  declarations.
- Extract `resolveAutoOpen()` helper out of the triple-nested ternary in
  `buildWebServerConfigFromEnv` for legibility, with the three-way logic
  documented in one place.
- Add an inline comment explaining why
  `webServerConfigToInitialPayload` falls back to streamable-http for
  unknown discriminators (forward-compat with future SDK transports)
  rather than throwing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: cliffhall

AGENTS.md

@@ -8,6 +8,15 @@ This is an application for inspecting MCP servers. Has three incarnations, Web,
 inspector/
 ├── clients/
 │   ├── web/                            # Web client (Vite + React + Mantine)
+│   │   ├── src/                        # Browser source (React app, hooks, components)
+│   │   ├── server/                     # Node-only dev/prod backend wiring:
+│   │   │                               #   vite-hono-plugin.ts (Hono middleware on the Vite dev server),
+│   │   │                               #   server.ts (standalone Hono prod server),
+│   │   │                               #   start-vite-dev-server.ts (in-process Vite starter for the launcher),
+│   │   │                               #   web-server-config.ts (env parsing + initial-config payload + banner),
+│   │   │                               #   sandbox-controller.ts (MCP Apps sandbox HTTP server),
+│   │   │                               #   vite-base-config.ts (shared optimizeDeps exclusions)
+│   │   └── static/                     # sandbox_proxy.html (served by sandbox-controller for MCP Apps tab)
 │   ├── cli/                            # CLI client
 │   ├── tui/                            # TUI client
 │   ├── launcher/                       # Shared launcher

clients/web/package-lock.json

@@ -34,6 +34,7 @@
     "ajv": "^8.17.1",
     "atomically": "^2.1.1",
     "hono": "^4.12.18",
+    "open": "^10.2.0",
     "pino": "^9.14.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",

clients/web/package.json

@@ -0,0 +1,136 @@
+/**
+ * Sandbox server controller: start/close and get URL.
+ * Used by server.ts (prod) and the Vite plugin (dev/test). Same process lifecycle as the main server.
+ */
+
+import { createServer, type Server } from "node:http";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export interface SandboxControllerOptions {
+  /** Port to bind (0 = dynamic). */
+  port: number;
+  /** Host to bind (default localhost). */
+  host?: string;
+}
+
+export interface SandboxController {
+  start(): Promise<{ port: number; url: string }>;
+  close(): Promise<void>;
+  getUrl(): string | null;
+}
+
+/**
+ * Resolve sandbox port from env: MCP_SANDBOX_PORT → SERVER_PORT → 0 (dynamic).
+ */
+export function resolveSandboxPort(): number {
+  const fromSandbox = process.env.MCP_SANDBOX_PORT;
+  if (fromSandbox !== undefined && fromSandbox !== "") {
+    const n = parseInt(fromSandbox, 10);
+    if (!Number.isNaN(n) && n >= 0) return n;
+  }
+  const fromServer = process.env.SERVER_PORT;
+  if (fromServer !== undefined && fromServer !== "") {
+    const n = parseInt(fromServer, 10);
+    if (!Number.isNaN(n) && n >= 0) return n;
+  }
+  return 0;
+}
+
+export function createSandboxController(
+  options: SandboxControllerOptions,
+): SandboxController {
+  const { port, host = "localhost" } = options;
+  let server: Server | null = null;
+  let sandboxUrl: string | null = null;
+
+  let sandboxHtml: string;
+  try {
+    const sandboxHtmlPath = join(__dirname, "../static/sandbox_proxy.html");
+    sandboxHtml = readFileSync(sandboxHtmlPath, "utf-8");
+  } catch (e) {
+    sandboxHtml =
+      "<!DOCTYPE html><html><body>Sandbox not loaded: " +
+      String((e as Error).message) +
+      "</body></html>";
+  }
+
+  return {
+    async start(): Promise<{ port: number; url: string }> {
+      if (server && sandboxUrl) {
+        const p = parseInt(new URL(sandboxUrl).port, 10);
+        return { port: p, url: sandboxUrl };
+      }
+      return new Promise((resolve) => {
+        // Guard so a `listen` error followed by a (theoretically possible)
+        // late `listening` callback doesn't double-resolve the promise. The
+        // first signal wins.
+        let settled = false;
+        const settle = (value: { port: number; url: string }) => {
+          if (settled) return;
+          settled = true;
+          resolve(value);
+        };
+
+        server = createServer((req, res) => {
+          if (
+            req.method !== "GET" ||
+            (req.url !== "/sandbox" && req.url !== "/sandbox/")
+          ) {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("Not Found");
+            return;
+          }
+          res.writeHead(200, {
+            "Content-Type": "text/html; charset=utf-8",
+            "Cache-Control": "no-store, no-cache, must-revalidate",
+            Pragma: "no-cache",
+          });
+          res.end(sandboxHtml);
+        });
+        server.on("error", (err: NodeJS.ErrnoException) => {
+          if (err.code === "EADDRINUSE") {
+            console.error(
+              `Sandbox: port ${port || "dynamic"} in use. MCP Apps tab may not work.`,
+            );
+          } else {
+            console.error("Sandbox server error:", err);
+          }
+          // Best-effort degradation: resolve with empty values rather than
+          // rejecting so callers (the Vite plugin in particular) keep
+          // attaching `/api/*`. `sandboxUrl` stays null, `getUrl()` keeps
+          // returning null, and the banner omits the sandbox line.
+          server = null;
+          settle({ port: 0, url: "" });
+        });
+        server.listen(port, host, () => {
+          const addr = server!.address();
+          const actualPort =
+            typeof addr === "object" && addr !== null && "port" in addr
+              ? addr.port
+              : (addr as unknown as number);
+          sandboxUrl = `http://${host}:${actualPort}/sandbox`;
+          settle({ port: actualPort, url: sandboxUrl });
+        });
+      });
+    },
+
+    async close(): Promise<void> {
+      if (!server) return;
+      return new Promise((resolve) => {
+        server!.close(() => {
+          server = null;
+          sandboxUrl = null;
+          resolve();
+        });
+      });
+    },
+
+    getUrl(): string | null {
+      return sandboxUrl;
+    },
+  };
+}

clients/web/server/sandbox-controller.ts

@@ -0,0 +1,147 @@
+/**
+ * Hono production server. Export startHonoServer(config) for in-process use by the runner.
+ * When run as the main module (e.g. node dist/server.js), build config from env and start.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
+import open from "open";
+import { serve } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { Hono } from "hono";
+import { createRemoteApp } from "../../../core/mcp/remote/node/server.ts";
+import { createSandboxController } from "./sandbox-controller.js";
+import type { WebServerConfig } from "./web-server-config.js";
+import {
+  webServerConfigToInitialPayload,
+  buildWebServerConfigFromEnv,
+  printServerBanner,
+} from "./web-server-config.js";
+import type { WebServerHandle } from "./types.js";
+
+export type { WebServerHandle };
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Start the Hono production server in-process. Returns a handle that closes sandbox then HTTP server.
+ * Caller owns SIGINT/SIGTERM; do not register signal handlers here.
+ */
+export async function startHonoServer(
+  config: WebServerConfig,
+): Promise<WebServerHandle> {
+  const sandboxController = createSandboxController({
+    port: config.sandboxPort,
+    host: config.sandboxHost,
+  });
+  await sandboxController.start();
+
+  const resolvedAuthToken =
+    config.authToken ||
+    (config.dangerouslyOmitAuth ? "" : randomBytes(32).toString("hex"));
+
+  const rootPath = config.staticRoot ?? __dirname;
+
+  const { app: apiApp } = createRemoteApp({
+    authToken: config.dangerouslyOmitAuth ? undefined : resolvedAuthToken,
+    dangerouslyOmitAuth: config.dangerouslyOmitAuth,
+    storageDir: config.storageDir,
+    allowedOrigins: config.allowedOrigins,
+    sandboxUrl: sandboxController.getUrl() ?? undefined,
+    logger: config.logger,
+    initialConfig: webServerConfigToInitialPayload(config),
+  });
+
+  const app = new Hono();
+  app.use("/api/*", async (c) => {
+    return apiApp.fetch(c.req.raw);
+  });
+
+  app.get("/", async (c) => {
+    try {
+      const indexPath = join(rootPath, "index.html");
+      const html = readFileSync(indexPath, "utf-8");
+      return c.html(html);
+    } catch (error) {
+      console.error("Error serving index.html:", error);
+      return c.notFound();
+    }
+  });
+
+  app.use(
+    "/*",
+    serveStatic({
+      root: rootPath,
+      rewriteRequestPath: (path) => {
+        if (!path.includes(".") && !path.startsWith("/api")) {
+          return "/index.html";
+        }
+        return path;
+      },
+    }),
+  );
+
+  const httpServer = serve(
+    {
+      fetch: app.fetch,
+      port: config.port,
+      hostname: config.hostname,
+    },
+    (info) => {
+      const sandboxUrl = sandboxController.getUrl();
+      const url = printServerBanner(
+        config,
+        info.port,
+        resolvedAuthToken,
+        sandboxUrl ?? undefined,
+      );
+      if (config.autoOpen) {
+        open(url);
+      }
+    },
+  );
+
+  httpServer.on("error", (err: Error) => {
+    if (err.message.includes("EADDRINUSE")) {
+      console.error(
+        `MCP Inspector PORT IS IN USE at http://${config.hostname}:${config.port}`,
+      );
+      process.exit(1);
+    } else {
+      throw err;
+    }
+  });
+
+  return {
+    async close(): Promise<void> {
+      await sandboxController.close();
+      if ("closeAllConnections" in httpServer) {
+        httpServer.closeAllConnections();
+      }
+      await new Promise<void>((resolve, reject) => {
+        httpServer.close((err) => (err ? reject(err) : resolve()));
+      });
+    },
+  };
+}
+
+/** Run when this file is executed as the main module (e.g. node dist/server.js). */
+async function runStandalone(): Promise<void> {
+  const config = buildWebServerConfigFromEnv();
+  const handle = await startHonoServer(config);
+  const shutdown = () => {
+    void handle.close().then(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+const isMain =
+  process.argv[1] !== undefined &&
+  resolve(process.argv[1]) === resolve(__filename);
+if (isMain) {
+  void runStandalone();
+}