[stuffbucket]

On Windows, Settings → Integrations said "MCP servers don't run on Windows yet", so Work IQ and every other MCP server were off limits there. The broker refused to start because nothing guaranteed that the MCP servers it starts, and their children, would end when it did. This change provides that guarantee and removes the gate.

How containment works on Windows

• Before it starts anything, maximal-mcp-broker serve creates a Job Object with JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE and assigns its own process to it. It calls kernel32 through bun:ffi (packages/mcp-broker/src/windows-job.ts), checks the assignment with IsProcessInJob, and keeps the only handle open until it exits. The handle can't be inherited, and the job doesn't allow breakaway. If the broker is already in a job (a Windows runner, or anything that starts Maximal inside one), its job is nested in that one.
• The MCP servers the broker starts, and anything they start, are in the job. When the broker exits or is terminated, Windows kills all of them.
• If Windows refuses any step, the broker starts nothing. It writes MCP_BROKER_CONTAINMENT_UNAVAILABLE step=<step> error=<code> to stderr and exits with status 78. On Windows only, the supervisor reports the broker as unavailable with the problem containment-unavailable and doesn't keep retrying. Settings says "MCP servers couldn't start" and points to the MCP server log.
• When the supervisor stops the broker, it asks it to shut down, waits a bounded time, then calls TerminateProcess on it. That closes the job, which ends every descendant.
• However serve stops (a shutdown frame, stdin closing, the --parent-pid process gone, a signal, or an error), the broker exits at most 3 seconds after it begins closing, even if an open session holds its HTTP server. A crashed sidecar therefore can't leave a broker behind: its stdin closes, and the parent watchdog notices within a second.

Updates and installers

• The NSIS installer and uninstaller now end every maximal-mcp-broker.exe first, through PREINSTALL and PREUNINSTALL hooks (shell/src-tauri/windows/hooks.nsh, wired in tauri.conf.json), as the MSI and install.ps1 already do. A contract test checks the hooks and the wiring.
• The in-place update also ends them right after stopping the sidecar (stop_mcp_brokers_for_update in shell/src-tauri/src/lib.rs). A broker, or a Claude Desktop stdio adapter running the same file, would otherwise hold maximal-mcp-broker.exe open, and the installer couldn't replace it. I couldn't compile the shell for Windows locally (ring needs MSVC headers). I checked the Windows-only std calls with rustc --target x86_64-pc-windows-msvc, and the Tauri spawn_blocking signature against its source.

Other Windows fixes on this path

• .cmd and .bat servers: the MCP SDK starts stdio servers with cross-spawn. It runs a .cmd file through cmd.exe /d /s /c with its arguments escaped, so these servers work and are safe from CVE-2024-27980. The Windows test runs its server through a .cmd file in a folder whose name contains a space, to prove this.
• The broker's Windows baseline environment now includes the variables the MCP SDK passes to stdio servers by default: USERNAME, PROGRAMDATA, PROGRAMFILES, PROGRAMFILES(X86), PROGRAMW6432, and PROCESSOR_ARCHITECTURE.
• On Windows, the development broker build is now found as maximal-mcp-broker.exe.
• Work IQ detection now also follows npm's workiq.cmd launcher on PATH to the package in the node_modules folder next to it.
• When Maximal adopts an entry you already had in Claude Desktop's regular config, on Windows it now reads %APPDATA%\Claude and the Microsoft Store app's %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude, not %LOCALAPPDATA%\Claude. The folders it reads are passed in, so tests never read the real user's config.

Settings copy

The MCP panel's broker messages (starting, recovering, keeps stopping, missing, and couldn't start) moved from hardcoded English into the i18n catalogs, in all nine full catalogs. The old "don't run on Windows" copy was never in the catalogs; it is gone from the panel, the CLI, and the API. The translations are mine, so @jessicadowney should review the wording.

Tests

• Unit tests for the Job Object wrapper with injected kernel32 bindings: the structure layout, the order of calls, and failing closed at each step.
• Supervisor tests for Windows, in tests/mcp-broker-supervisor-windows.test.ts. The helpers moved to tests/helpers/broker-supervisor.ts to keep the original file under the line limit. They check how the broker is spawned, that stopping it ends in TerminateProcess and never a group kill, that exit status 78 makes the broker unavailable only on Windows, that other crashes still restart it, and that the sidecar and the broker agree on status 78.
• packages/mcp-broker/test/windows-containment.test.ts runs only on win32, against the compiled broker. Its MCP server is started through a .cmd file and starts a child of its own. The test opens a session, then checks that cmd.exe, the server, and its child are all gone within 5 seconds in each of these cases:
  • the broker is terminated;
  • the --parent-pid process dies;
  • the broker shuts down cleanly;
  • the process that owns the broker's stdin dies;
  • the broker started inside an existing job (the launcher confirms with IsProcessInJob).
• A sixth case checks that a refused job makes the broker exit with status 78 before it writes anything to stdout. I couldn't make Windows refuse the job for real: it nested even under a job with UI limits. So this case runs the source broker with a test-only Bun preload (test/refuse-job-preload.ts) that makes AssignProcessToJobObject report failure. The broker itself has no switch for this.
• The windows-broker CI job on windows-latest builds the broker and runs the whole broker suite against the compiled .exe. It then runs the containment test again against the minified build:target --target=bun-windows-x64 build that releases ship.
• The adapter test that stops the adapter with SIGTERM is skipped on Windows. There kill() is TerminateProcess and runs no handler, and clients stop the adapter by closing stdin, which another test covers.

Release-As: 0.5.0