Stop the npm wrapper's platform-package auto-install from writing to the caller's package.json

[Dan Dombrowski (djdmbrwsk)]

Problem

When the wrapper can't require its platform package, it auto-installs it with a bare npm install (eng/npm/wrapper/index.js#L48-L52):

execSync(`npm install ${platformPackageName}@${packageVersion}`, {
  stdio: ['inherit', 'inherit', 'pipe'],
  timeout: 60000
})

There's no --no-save and no --prefix, and cwd is inherited from whoever spawned the wrapper. For an MCP client that's an unrelated user project, so npm walks up from there, finds the user's package.json, and saves @azure/mcp-<platform>-<arch> into their dependencies and lockfile. --no-save is only applied on the second attempt (L58), which never runs because the first one succeeds.

I hit this as an unexplained @azure/mcp-darwin-arm64 entry in the dependencies of a Next.js app with no Azure involvement — it then propagates to CI and to every other developer on the repo via the lockfile.

Why the fallback fires at all

npm skips optionalDependencies whose engines don't match the running Node, and 3.0.0-beta.27 raised engines.node to >=22.0.0 on the wrapper and the platform packages. On Node 20 the platform package is silently omitted from the install:

$ node -v && npm i @azure/mcp@3.0.0-beta.30 --ignore-scripts && ls node_modules/@azure/
v20.19.4
mcp

$ node -v && npm i @azure/mcp@3.0.0-beta.30 --ignore-scripts && ls node_modules/@azure/
v22.22.0
mcp  mcp-darwin-arm64

The wrapper's own engines mismatch is just an EBADENGINE warning (it's a direct dependency), so the install looks clean and the failure only shows up at runtime. That skip is what puts users on this code path; whether >=22.0.0 is the intended floor is a separate question I've left alone here.

Fix

• Install into a private .platform directory inside the wrapper package, with --no-save and an explicit --prefix, and resolve the platform package from that path. The directory intentionally has no package.json: pointing npm at the wrapper's own manifest is a no-op, because the platform package is declared there as an optionalDependency that npm is already skipping.
• Stop inheriting stdout for the install. Under server start that's the JSON-RPC channel, so npm output written there can corrupt the protocol stream. The wrapper's own messages already go to stderr.
• Add the Node version to the troubleshooting output, since the engines skip is the likeliest cause and is otherwise invisible.

Verification

macOS arm64, npm 11.6.1, against @azure/mcp@3.0.0-beta.30.

Before (Node 20, wrapper run from a project directory):

-{"name":"ctrl","version":"1.0.0","dependencies":{"@azure/mcp":"^3.0.0-beta.30"}}
+{"name":"ctrl","version":"1.0.0","dependencies":{"@azure/mcp":"^3.0.0-beta.30","@azure/mcp-darwin-arm64":"^3.0.0-beta.30"}}

After (same setup, patched wrapper):

$ node node_modules/@azure/mcp/index.js --version > stdout.txt 2> stderr.txt; echo "exit=$?"
exit=0

$ cat stdout.txt          # clean - no npm output on the protocol channel
3.0.0-beta.30+bd96686782eb9b62c47662b941de4c4b9eb0aaf7

$ cat stderr.txt
Installing missing platform package: @azure/mcp-darwin-arm64
✅ Successfully installed and loaded @azure/mcp-darwin-arm64

$ ls node_modules/@azure/mcp/.platform/node_modules/@azure/
mcp-darwin-arm64

$ diff package.json.before package.json && diff package-lock.json.before package-lock.json
# no output - both unchanged

Happy path (Node 22, platform package present): unchanged — the server runs, the fallback never fires, and no .platform directory is created.

Notes

• No test updates: there's no existing test coverage for eng/npm/wrapper/index.js. Happy to add some if you'd like a preferred location.
• I couldn't find an existing issue for this; glad to open one to link if that's required by the PR process.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
There may be pipelines that require an authorized user to comment /azp run to run.

[github-actions]

Thank you for your contribution Dan Dombrowski (@djdmbrwsk)! We will review the pull request and get back to you soon.

[Copilot]

Pull request overview

This pull request updates the Azure MCP npm wrapper’s platform-package fallback installation flow to avoid mutating the caller’s project files and to keep stdout clean for JSON-RPC transport.

Changes:

• Install missing @azure/mcp-<platform>-<arch> packages into a private .platform directory under the wrapper instead of the caller’s working directory (using --prefix and --no-save).
• Stop sending npm install output to stdout to avoid corrupting the MCP protocol stream during server start.
• Improve troubleshooting output by including the running Node version and the wrapper’s engines.node constraint.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
servers/Azure.Mcp.Server/CHANGELOG.md	Adds a release note describing the wrapper fix and stdout behavior change.
eng/npm/wrapper/index.js	Redirects auto-install into a private directory, updates module resolution accordingly, and enhances diagnostics.

[Dan Dombrowski (djdmbrwsk)]

@microsoft-github-policy-service agree