Skip to content

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

@cliffhall

Description

@cliffhall

Background

The v2 web client's npm run dev is currently plain Vite — it has no in-process backend. The browser-side InspectorClient connects via createRemoteTransport({ baseUrl: window.location.origin }) (see core/mcp/remote/createRemoteTransport.ts), which expects a remote server to be reachable at the same origin under /api/*. With no dev backend, npm run dev can't drive a real connect/disconnect cycle against any MCP server.

core/mcp/remote/node/createRemoteApp already lives in v2 (ported in #1302). What's missing is the wiring that mounts it onto the Vite dev server and the production Hono server. v1.5 has this wiring in clients/web/src/:

  • vite-hono-plugin.ts (158 LOC) — Vite plugin that adds Hono middleware for /api/* and bridges SSE through the Vite HTTP server.
  • sandbox-controller.ts (~120 LOC) — Starts the Apps sandbox HTTP server on a dynamic port and serves sandbox_proxy.html.
  • web-server-config.ts (~194 LOC) — WebServerConfig, buildWebServerConfigFromEnv(), webServerConfigToInitialPayload(), printServerBanner().
  • vite-base-config.ts (~40 LOC) — Shared Vite base config consumed by both vite.config.ts and the in-process dev server.
  • server.ts (~148 LOC) — Production Hono server factory (startHonoServer) for built artifacts.
  • start-vite-dev-server.ts (~48 LOC) — In-process Vite dev-server entry point used by the launcher.
  • static/sandbox_proxy.html (~197 LOC) — HTML shell loaded into the MCP Apps tab iframe.

#1244 (Wire App.tsx) is blocked on this — its test plan calls for an end-to-end connect/disconnect cycle, which requires the dev backend to be reachable from the browser.

Scope

Port from v1.5/main into clients/web/src/ (or a sibling clients/web/server/ directory — placement is a design choice for this issue):

  • vite-hono-plugin.ts
  • sandbox-controller.ts
  • web-server-config.ts
  • vite-base-config.ts
  • server.ts
  • start-vite-dev-server.ts
  • static/sandbox_proxy.html

Update clients/web/vite.config.ts to import honoMiddlewarePlugin and buildWebServerConfigFromEnv (mirroring v1.5's call site):

plugins: [react(), honoMiddlewarePlugin(buildWebServerConfigFromEnv())],

Add the open npm dependency to clients/web/package.json (v1.5 uses ^10.1.0).

Reconcile naming/imports: @modelcontextprotocol/inspector-core/* in v1.5 maps to @inspector/core/* in v2 (per the Vite alias).

Acceptance criteria

  • npm run dev starts Vite plus an embedded Hono backend reachable at http://localhost:<port>/api/*.
  • createRemoteApp is instantiated with webServerConfigToInitialPayload(config) and the resolved auth token is logged in the banner (or absence logged when dangerouslyOmitAuth is set).
  • The Apps sandbox server starts on a separate dynamic port and sandbox_proxy.html is served from it.
  • npm run validate clean (lint / build / format / typecheck / unit coverage).
  • npm run test:integration still passes (no regression in integration tests, which already exercise core/mcp/remote/node/*).
  • A new unit test covers buildWebServerConfigFromEnv env-parsing branches and webServerConfigToInitialPayload shape. Per-file coverage gate (≥90 lines / ≥85 stmts / ≥80 fns / ≥50 branches) holds.
  • AGENTS.md "Project Structure" is updated to enumerate the new dev-backend files.

Test plan

  • Manual: npm run dev, open the printed URL, confirm browser devtools shows successful requests to /api/health (or equivalent) and /api/mcp/events connects without 401/404.
  • Manual: connect to npx @modelcontextprotocol/server-filesystem from the browser via the dev backend.
  • CI: full validate + integration suites pass.

Out of scope

Unblocks

Related

  • v1.5 source of truth: git show origin/v1.5/main:clients/web/src/vite-hono-plugin.ts (and the sibling files listed in Scope).
  • v2 backend factory already ported: core/mcp/remote/node/server.ts (createRemoteApp).
  • v2 transport already ported: core/mcp/remote/createRemoteTransport.ts.

Metadata

Metadata

Assignees

No one assigned

    Labels

    v2Issues and PRs for v2

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions