Windows: /mcp UI fails to spawn bin/devkit (extensionless shell script)

[5uck1ess]

Summary

On Windows, Claude Code's in-session MCP launcher cannot spawn bin/devkit because it's an extensionless POSIX shell script (#!/bin/sh). The /mcp UI shows devkit-engine as failed, even though claude mcp list (CLI) reports it as connected. The two disagree because they use different process-spawn code paths.

Environment

• OS: Windows 11
• Claude Code CLI (latest)
• devkit plugin v2.1.6 (download fix from PR bin/devkit: fix Windows first-run install (curl+schannel bug, #58) #59 works — engine binary is present)
• Shell: Git Bash available on PATH

Reproduction

1. Install devkit plugin on Windows.
2. Let v2.1.6 download bin/devkit-engine-v2.1.6-windows-amd64.exe (works fine post-bin/devkit: fix Windows first-run install (curl+schannel bug, #58) #59).
3. Open Claude Code, run /mcp → plugin:devkit:devkit-engine shows × failed.
4. In the same session, run claude mcp list → shows ✓ Connected.

Root cause (proven, not speculation)

bin/devkit has no file extension. Claude Code UI spawns MCP servers via Node child_process.spawn without shell:true on Windows. Windows CreateProcess can't execute a shebang script directly, and CMD can't either because the file has no .exe/.cmd/.bat extension.

Reproduced both failure modes with Node:

// 1) Direct spawn (what CC UI does):
spawn('…/bin/devkit', ['mcp'])
// → Error: spawn ENOENT

// 2) Spawn via shell:true (cmd.exe):
spawn('…/bin/devkit', ['mcp'], { shell: true })
// → stderr: "'…/bin/devkit' is not recognized as an internal or external command"

Spawning the already-downloaded engine .exe directly works perfectly — it prints devkit MCP server ready and responds to JSON-RPC over stdio:

spawn('…/bin/devkit-engine-v2.1.6-windows-amd64.exe', ['mcp'])
// → "devkit MCP server ready" on stderr, accepts MCP requests on stdin

claude mcp list succeeds because it uses a different probe path (likely invokes via sh.exe), which masks the UI-launcher issue from simple CLI checks.

Proposed fix

Ship a Windows-compatible launcher. Two options:

Option A — bin/devkit.cmd shim (recommended, minimal)

Add bin/devkit.cmd:

@echo off
sh "%~dp0devkit" %*

Then make plugin.json select per platform, or ship the .cmd and let Claude Code pick it up automatically (Windows spawn treats .cmd as executable).

Pros: keeps the existing download/resume wrapper logic. Requires sh.exe on PATH, but Git Bash is effectively universal on dev Windows and the current script already assumes POSIX tooling.

Option B — platform-specific command in plugin.json

Point mcpServers.devkit-engine.command at the engine .exe directly on Windows. Loses the auto-download wrapper on first run, but once the engine is downloaded (the current wrapper still handles that for other codepaths), direct launch is simpler and has no shell dependency.

Option C — bin/devkit.ps1

PowerShell equivalent that can locate and exec the engine. More portable than .cmd (no dependency on sh.exe), but more code to maintain.

Option A is the smallest diff and matches how most POSIX-first CLIs ship on Windows.

Local workaround (confirmed working)

Edit ~/.claude/plugins/cache/5uck1ess-plugins/devkit/2.1.6/.claude-plugin/plugin.json:

-      "command": "${CLAUDE_PLUGIN_ROOT}/bin/devkit",
+      "command": "${CLAUDE_PLUGIN_ROOT}/bin/devkit-engine-v2.1.6-windows-amd64.exe",

After this change, /mcp UI shows devkit-engine as connected. Gets clobbered on next plugin update, which is why an upstream fix is needed.

Related

• bin/devkit wrapper fails on Windows (Git Bash): curl schannel error 23 on checksums.txt download #58 / bin/devkit: fix Windows first-run install (curl+schannel bug, #58) #59 — Windows install (download) fix in v2.1.6. That fix is working: the engine binary downloads correctly. This issue is a separate Windows-launch problem that only manifests in the Claude Code /mcp UI.

[5uck1ess]

Thanks for the incredibly thorough diagnosis — spawn without shell:true on an extensionless shebang script lines up with everything I'm seeing.

Before I land a fix, I want to pick the minimal-diff path that actually works in the CC UI launcher, not just in my head. Would you be willing to try one verification on your Windows box? Pick whichever is easier — either tells me which direction to go:

Variant 1 — .cmd shim + updated command

1. In the cached plugin dir, create bin/devkit.cmd:

   @echo off
   sh "%~dp0devkit" %*

2. Edit .claude-plugin/plugin.json:

   -      "command": "${CLAUDE_PLUGIN_ROOT}/bin/devkit",
   +      "command": "${CLAUDE_PLUGIN_ROOT}/bin/devkit.cmd",

3. Restart CC, check /mcp.

If that lights up green, I'll ship the shim and make plugin.json platform-agnostic by renaming / dual-pointing.

Variant 2 — does CC honor an unchanged command if a sibling .cmd exists?

Drop just bin/devkit.cmd (same contents as above) next to bin/devkit, leave plugin.json pointing at bin/devkit, restart CC. I don't think Node spawn does extension fallback without shell:true, but if CC happens to wrap the spawn in shell:true on Windows, this would Just Work and we'd need zero plugin.json surgery. Worth 30 seconds to rule out.

Also — does your local workaround (pointing command directly at devkit-engine-v2.1.6-windows-amd64.exe) actually launch the MCP server successfully through the /mcp UI, or only make the status turn green? I want to confirm stdio JSON-RPC flows end-to-end, not just that the process spawns.

I'm simultaneously digging through CC's bundled launcher to see how it parses plugin.json and whether there's any process.platform branching for MCP command resolution. Will post back here with what I find.

[5uck1ess]

Tested both variants on the same box (Node v24.14.1, CC latest, Windows 11). Both of your proposed paths fail at the spawn layer — only the direct .exe works. Also confirmed full MCP stdio end-to-end through the workaround.

Test matrix

I ran each case against child_process.spawn with no shell:true (the only known way the CC UI launcher is reaching the plugin, per my original repro).

Variant 2 — .cmd sibling, plugin.json unchanged (command: bin/devkit)

spawn('…/bin/devkit', ['mcp']) → Error: spawn ENOENT

Node does not do PATHEXT extension fallback on absolute paths. Even with a bin/devkit.cmd sibling present, Node looks for a literal file called devkit and fails. PATHEXT only applies when Node resolves a bare command through PATH. Variant 2 is dead.

Variant 1 — .cmd shim, plugin.json command = bin/devkit.cmd

spawn('…/bin/devkit.cmd', ['mcp'])
→ Error: spawn EINVAL
    at ChildProcess.spawn (node:internal/child_process:421:11)

This is CVE-2024-27980. Since Node 20.12.2 / 21.7.3 / 18.20.2, spawning .bat/.cmd without shell: true is blocked at the runtime level to prevent argument-injection attacks. Unless the CC launcher explicitly opts in with shell: true (which from our repro it clearly doesn't, or Variant 2 would already work), any .cmd shim will throw EINVAL before it even runs. Variant 1 is dead too.

So: any fix that puts .cmd/.bat in the spawn path is a non-starter on modern Node unless CC changes its launcher.

End-to-end confirmation of the .exe-direct workaround

You specifically asked whether my plugin.json → .exe workaround actually carries stdio JSON-RPC end-to-end or just makes the status turn green. I spoke real MCP at it with newline-delimited framing:

const p = spawn(
  '…/bin/devkit-engine-v2.1.6-windows-amd64.exe',
  ['mcp'],
  { stdio: ['pipe', 'pipe', 'pipe'] }
);
send({ jsonrpc:'2.0', id:1, method:'initialize', params:{ … } });
send({ jsonrpc:'2.0', method:'notifications/initialized', params:{} });
send({ jsonrpc:'2.0', id:2, method:'tools/list', params:{} });

Result:

[err] warning: could not load principles: _principles.yml not found
[err] devkit MCP server ready
initialize:  OK  serverInfo = { name: "devkit-engine", version: "1.0.0" }
tools/list:  OK  count = 4  first3 = [ 'devkit_advance', 'devkit_list', 'devkit_start' ]

Full protocol roundtrip: initialize → notifications/initialized → tools/list returning all 4 tools. Not just process-start smoke — real MCP traffic. The workaround is genuinely working, not just green.

(Side note: the _principles.yml not found warning on stderr is cosmetic — probably a separate missing-bundled-asset issue worth a quick grep, but unrelated to this bug.)

Viable fix directions

Given .cmd/.bat are off the table:

A — Platform-branched command (simplest, no new files)

If CC's plugin.json parser supports per-platform branching (process.platform-keyed), point at the .exe on win32 and the shell wrapper elsewhere. Needs a quick check of the CC plugin spec — if it does support it, this is a two-line fix with zero shim maintenance.

B — PowerShell wrapper (.ps1 invoked via powershell.exe)

"command": "powershell.exe",
"args": [
  "-NoProfile",
  "-ExecutionPolicy", "Bypass",
  "-File", "${CLAUDE_PLUGIN_ROOT}/bin/devkit.ps1",
  "mcp"
]

powershell.exe is itself an .exe, so spawn accepts it. The .ps1 can replicate the download/resume/checksum logic from bin/devkit. Downsides: PowerShell is heavier than sh, and you'd maintain two wrapper implementations. Upside: single plugin.json works on all platforms if Unix branch points at sh + bin/devkit args similarly.

C — Tiny native launcher stub (bin/devkit-launcher.exe)

Ship (or build at install time) a ~50-line Go/Rust/Zig binary whose sole job is to exec the platform engine with whatever args came in, downloading it first if missing. Most work, but cleanest: zero shell dependency, works in any launcher, and folds the download logic into something statically checked.

D — Rename/switch strategy

Change the existing download wrapper's name to bin/devkit.sh and commit a bin/devkit.exe for Windows that does the same job. Then plugin.json can select devkit.sh vs devkit.exe per platform — no .cmd/.bat anywhere.

---

My recommendation: A first (if supported), otherwise C. D is also reasonable and keeps the architecture uniform.

Happy to help test whichever you pick — I've got a warm Windows repro now and the .exe-direct workaround in place so I'm unblocked.

[5uck1ess]

Incredible detective work — the CVE-2024-27980 angle is the key finding I missed. That blows up every .cmd/.bat-in-spawn-path idea, which also means your Option A (platform-branched command) is unreachable for a different reason I dug up on my side: I pulled strings out of the CC binary and the plugin.json parser uses Zod h.strictObject on the mcpServers.* schema — extra keys are rejected. So there's no {win32: ..., darwin: ...} branching accepted by the manifest today. A and D (rename-per-platform) are both dead on the CC side, independently of the Node side.

That leaves B (PowerShell) or C (native launcher stub) from your list — but I want to float a fifth option that I think sidesteps everything:

Option E — command: "sh", args: ["…/bin/devkit", "mcp"]

   "mcpServers": {
     "devkit-engine": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/bin/devkit",
-      "args": ["mcp"]
+      "command": "sh",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/devkit", "mcp"]
     }
   }

Why I think this works on both sides:

POSIX (macOS/Linux). Trivially. /bin/sh /path/bin/devkit mcp — shell is always on PATH, shebang becomes irrelevant because sh is invoking the script directly as an argument.

Windows. The CC binary hard-requires Git Bash — I pulled this exact error string out of claude.exe:

"Claude Code on Windows requires git-bash (https://git-scm.com/downloads/win). If installed but not in PATH, set environment variable pointing to your bash.exe, similar to: CLAUDE_CODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe"

It process.exit(1)s if bash can't be found. So we can safely assume sh.exe is reachable on any Windows box where CC is already running. Crucially:

1. command: \"sh\" is a bare command name, so Node's child_process.spawn runs its PATH + PATHEXT resolver, picks up sh.exe, and spawns it.
2. .exe spawns are not blocked by CVE-2024-27980 — that only applies to .cmd/.bat. So no EINVAL.
3. Git Bash's sh.exe auto-translates the Windows-style ${CLAUDE_PLUGIN_ROOT} path MSYS-style internally, so the script resolves correctly.
4. The existing bin/devkit already contains the MINGW*|MSYS*|CYGWIN* branch in detect_platform and the full MSYS cygpath fallback logic for gh/PowerShell downloaders — so it's already been designed to run under Git Bash. We'd just be invoking it via sh explicitly instead of relying on the OS to resolve a shebang.

If this works, the entire fix is a two-line plugin.json diff. No new files, no duplicated download logic, no .cmd/.bat/.ps1 shim to maintain, no CVE exposure, no platform branching in the manifest (which isn't supported anyway).

The ask

Would you be willing to run one more 30-second test on your Windows box? Edit the cached plugin.json exactly as in the diff above, restart CC, and check:

1. /mcp UI status for devkit-engine — does it go green?
2. One actual tool call against it in-session (devkit_list is cheap) — does the JSON-RPC roundtrip?

If yes to both, I'll ship this as the fix for v2.1.7 today and close out the issue. If it fails, I'll move to Option C (tiny Go launcher stub built into the existing engine build matrix — bin/devkit-launcher-windows-amd64.exe that just locates and execs the engine, shipped in the release tarball so ${CLAUDE_PLUGIN_ROOT}/bin/devkit-launcher.exe is a real .exe that spawn accepts directly).

Also noting the _principles.yml not found warning for follow-up — filing that as a separate issue once this one lands.

Thanks again for the thoroughness on this — the CVE reference saved me from shipping something broken.

[5uck1ess]

Option E works. Validated via Node child_process.spawn repro + claude mcp list CLI probe. UI confirmation from Tym coming after a CC restart — will edit this comment or reply when that's in hand.

Patch applied

~/.claude/plugins/cache/5uck1ess-plugins/devkit/2.1.6/.claude-plugin/plugin.json:

   "mcpServers": {
     "devkit-engine": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/bin/devkit",
-      "args": ["mcp"]
+      "command": "sh",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/bin/devkit",
+        "mcp"
+      ]
     }
   }

Spawn repro (what the CC UI launcher does)

spawn('sh', ['…/bin/devkit', 'mcp'], { stdio: ['pipe','pipe','pipe'] })

No shell: true. No EINVAL. sh resolves through PATH + PATHEXT to /usr/bin/sh (Git Bash sh.exe), Node spawns it as a normal .exe — CVE-2024-27980 doesn't apply because it's not a .cmd/.bat. Your read of the CC internals is correct: Git Bash is a hard prerequisite, so sh is guaranteed present on any Windows box running CC.

Full MCP roundtrip through the new launcher

[err] warning: could not load principles: _principles.yml not found
[err] devkit MCP server ready

[1] initialize   → OK  serverInfo = { name: "devkit-engine", version: "1.0.0" }
[2] tools/list   → OK  count=4  names=[ devkit_advance, devkit_list, devkit_start, devkit_status ]
[3] tools/call devkit_list → JSON-RPC response returned

Transport is clean end-to-end. initialize → notifications/initialized → tools/list → tools/call all roundtrip correctly through sh → bin/devkit → exec → engine binary.

Side finding worth filing separately

tools/call devkit_list returned a valid JSON-RPC response but with isError: true and this content:

no workflows directory: open
  C:\Users\tymra\.claude\plugins\cache\context-mode\context-mode\1.0.75\workflows:
  The system cannot find the file specified.

The engine is resolving its workflows directory relative to another plugin's cache dir (context-mode/1.0.75) rather than its own (5uck1ess-plugins/devkit/2.1.6). Looks like a CLAUDE_PLUGIN_ROOT/cwd cross-contamination in the engine, completely unrelated to the launcher — filing that as a separate issue. The launcher fix here is good regardless.

CLI probe

$ claude mcp list
plugin:devkit:devkit-engine: sh C:/Users/tymra/.claude/plugins/cache/5uck1ess-plugins/devkit/2.1.6/bin/devkit mcp - ✓ Connected

Verdict

Option E is the right fix:

• Two-line plugin.json diff. No new files, no duplicated wrappers.
• POSIX side unchanged in behavior — /bin/sh /path/bin/devkit mcp is what shebang resolution would have done anyway.
• Windows side goes through sh.exe which is guaranteed present because CC won't boot without it.
• Existing bin/devkit already has the MSYS/MINGW/Cygwin branch in detect_platform + cygpath fallbacks, so it's already been designed to run under Git Bash. This change just makes that path explicit instead of relying on OS shebang resolution.
• No CVE-2024-27980 exposure — .exe spawns are unaffected.
• Works with CC's strict Zod plugin.json schema — no per-platform branching needed.

Ship it as v2.1.7. I'll follow up with the UI confirmation shortly, and open a separate issue for the CLAUDE_PLUGIN_ROOT cross-contamination + the _principles.yml not found warning.

[5uck1ess]

Update: I've got a proving-ground branch ready and I need a 5-minute Windows verification from you before I write the real launcher, if you're willing.

What I verified since your last comment

Docs + binary-strings dig (definitive):

• plugin.json.mcpServers.* inline schema is h.strictObject({command, args, env}) — no platform branching possible. That killed every path-branching idea including Option A from your list.
• .cmd/.bat in the spawn chain is CVE-2024-27980 dead, as you established.
• BUT — plugin.json.mcpServers also accepts a path or URL to an MCPB bundle (`WI8().describe("Path or URL to MCPB file...")` in the CC binary schema).
• MCPB = DXT renamed. Spec at modelcontextprotocol/mcpb. The manifest schema does support `platform_overrides` keyed on `darwin`/`win32`/`linux`, and the runtime resolver code that applies them is live in the CC binary.
• Reference implementations using this exact pattern: kubefwd/mcpb/manifest.json and github-mcp-server-mcpb/manifest.json. Both are Go-binary MCP servers with a `platform_overrides.win32` entry pointing at `.exe` alongside a POSIX entry — literally devkit's situation.

Empirical test on macOS:
Built a trivial `test.mcpb` with a `platform_overrides.darwin` that swaps scripts, wired it into a throwaway plugin via `plugin.json.mcpServers: "./test.mcpb"`. CC:

1. Unpacked the `.mcpb` zip into `/.mcpb-cache//`
2. Wrote a metadata sidecar (`source`, `contentHash`, `extractedPath`, `cachedAt`, `lastChecked`)
3. Resolved `platform_overrides.darwin` and spawned the override script (not the base) — verified by which file path showed up in `claude mcp list`
4. Expanded `${__dirname}` correctly to the unpacked cache dir

So on Mac/Linux the full wiring is proven. What I can't verify from a Mac is whether `platform_overrides.win32` fires end-to-end in CC's actual Windows MCP spawn context, which is where your expertise comes in.

The proving-ground branch

Branch: `fix/windows-mcpb-wiring-probe` — intentionally not a PR, this is a probe, not the fix.

What it does:

• Replaces inline `mcpServers` with `"mcpServers": "./devkit.mcpb"`
• Ships a small (~1.7MB) `devkit.mcpb` at the repo root containing:
  • `manifest.json` with `platform_overrides.win32` exactly like kubefwd's pattern
  • `server/devkit` — a 5-line POSIX shell proxy that `exec`s `$CLAUDE_PLUGIN_ROOT/bin/devkit` with the original args. POSIX behavior stays 100% identical to today — the existing wrapper does all the download/checksum/exec work, the proxy just forwards to it. Verified on my Mac: cold-start unpack works, `/mcp` shows Connected, full engine handshake.
  • `server/devkit.exe` — a tiny Go stub (GOOS=windows GOARCH=amd64 CGO_ENABLED=0, statically linked). It does NOT implement MCP protocol. It prints a distinctive marker plus diagnostics to stderr and sleeps 60s. `/mcp` will mark it failed-to-connect; that's fine, we're probing the spawn layer, not the protocol layer.

What I need you to verify

Switch to the probe branch on your Windows box:

```

In the cached plugin dir, overwrite with the probe branch

cd ~/.claude/plugins/cache/5uck1ess-plugins/devkit/2.1.6

(grab plugin.json + devkit.mcpb from

https://github.com/5uck1ess/devkit/tree/fix/windows-mcpb-wiring-probe

and drop them into place — or just git clone the branch over it)

```

Restart CC, then collect evidence for six specific things:

1. /mcp spawn path — does `devkit-engine` appear at all? What's the exact command line shown? It should be `/.mcpb-cache//server/devkit.exe mcp` — the `.exe`, not the shell script, and not the old `bin/devkit` path. If it shows the shell script path, `platform_overrides.win32` didn't fire.

2. Stderr marker — somewhere in CC's MCP error log for `devkit-engine` you should see the literal string `DEVKIT-WIRING-PROBE: WIN32_OVERRIDE_ACTIVE`. If yes, the Go stub actually ran in CC's Windows spawn context.

3. `CLAUDE_PLUGIN_ROOT` env var — one of the stub's stderr lines is `DEVKIT-WIRING-PROBE: CLAUDE_PLUGIN_ROOT=…`. I need to know if it's populated or empty. The real launcher will depend on it to locate `plugin.json` and find the right engine version.

4. `CLAUDE_PLUGIN_DATA` env var — same question, second stub line. The real launcher will cache engine downloads there (persistent across plugin updates).

5. `${__dirname}` expansion — the `executable=` stderr line should show the full path to `server/devkit.exe` as a native Windows path (backslashes, drive letter). I want to confirm CC isn't handing us an MSYS-style `/c/Users/…` path.

6. `.mcpb-cache//` layout on Windows — does CC unpack `devkit.mcpb` into `.mcpb-cache//` in the plugin dir the same way it does on Mac? `find .mcpb-cache -type f` should show `manifest.json`, `server/devkit`, `server/devkit.exe`, plus a `.metadata.json` sidecar.

A one-paragraph dump of whatever you find (or a screenshot of `/mcp`'s error log + the `find` output) is plenty. I don't need the full JSON-RPC test kit this time — spawn-layer evidence is what I'm after.

If all six check out, I'll immediately start the real launcher: a Go port of `bin/devkit`'s download/checksum/resume loop that also stdio-proxies into the downloaded engine on Windows. If any of them fail, I want to know how they fail so I can redirect.

Rollback: if any of this breaks your CC session, `rm devkit.mcpb` and restore `plugin.json` to point at `bin/devkit` again (pre-probe state on `main`).

PR #61 can stay open or closed, your call — it's superseded either way.

Thanks again for the rigor.