fix: make MCP server start on native Windows#4
Open
trostmarvin wants to merge 1 commit into
Open
Conversation
The aseprite MCP server never started on native Windows, so no mcp__aseprite__ tools were exposed (willibrandon#3). Two independent causes: 1. .mcp.json set PIXEL_MCP_CONFIG to "${HOME}/...". HOME is not set on native Windows outside Git Bash, and Claude Code refuses to start a server whose env expansion fails ("Missing environment variables: HOME" in /doctor). The variable is dead weight anyway: pixel-mcp only reads ~/.config/pixel-mcp/config.json and never consults PIXEL_MCP_CONFIG. Remove the env block. 2. The server command points at bin/pixel-mcp, a bash wrapper script that native Windows cannot execute. Ship the new pixel-mcp launcher (willibrandon/pixel-mcp#18) as bin/pixel-mcp.exe: Windows appends .exe when spawning the extensionless command path and runs the launcher, which execs pixel-mcp-windows-amd64.exe beside it. Unix platforms keep executing the bash wrapper unchanged. Verified on Windows 11 with claude --plugin-dir: all 50 aseprite tools are exposed with both changes; removing only the env block still yields 0 tools, confirming both fixes are required. Also normalize skill frontmatter names to kebab-case directory names, and add .gitattributes so core.autocrlf on Windows checkouts cannot rewrite the bash wrapper to CRLF (which breaks its shebang under Git Bash). Fixes willibrandon#3 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #3 (the MCP-tools-not-exposed part; see notes on skills below).
Root cause
Two independent breakers on native Windows:
.mcp.jsonenv expansion fails.PIXEL_MCP_CONFIGwas set to${HOME}/...—HOMEdoesn't exist on native Windows outside Git Bash, and Claude Code refuses to start the server (/doctor: "Missing environment variables: HOME"). The variable is dead weight anyway: pixel-mcp only reads~/.config/pixel-mcp/config.jsonand never consultsPIXEL_MCP_CONFIG. This PR removes the env block.bin/pixel-mcpis a bash shebang script; native Windows can't execute it. This PR ships the new launcher from Add a Go launcher for cross-platform plugin use pixel-mcp#18 asbin/pixel-mcp.exe: Windows appends.exewhen spawning the extensionless command path and runs the launcher, which startspixel-mcp-windows-amd64.exebeside it. macOS/Linux keep executing the bash wrapper at the unchanged.mcp.jsonpath.Notably, the server binary itself was never broken: v0.5.0
pixel-mcp-windows-amd64.exeanswers MCP stdio correctly when driven with clean pipes (matches the reporter's own finding in #3, "responds with 49 tools when queried manually").Verification (Windows 11, real Claude Code via
--plugin-dir)bin/pixel-mcp.exeBoth changes are required. Also verified from WSL2 (Linux binary via the bash wrapper): handshake succeeds.
Also included
namefields normalized to kebab-case directory names (Pixel Art Creator→pixel-art-creator), per your findings in Skills not recognized on Windows - 'Unknown skill' error #3..gitattributesforcing LF forbin/pixel-mcpand*.sh, and marking binaries as binary —core.autocrlf=truecheckouts on Windows were rewriting the wrapper to CRLF, which breaks its shebang under Git Bash.allowed-toolsleft comma-separated: current docs accept comma-separated, space-separated, and YAML list forms.Note on the bundled exe
bin/pixel-mcp.exehere is built from the launcher PR branch (willibrandon/pixel-mcp#25). Once that merges and releases, you'll likely want to replace it with the releasedpixel-mcp-launcher-windows-amd64.exeartifact.🤖 Generated with Claude Code