mcptest docs GitHub

Install mcptest from npm

mcptest publishes a native binary distribution on npm under @soapbucket/mcptest. The package layout follows the esbuild and biome pattern: one umbrella package and five platform-specific binary packages selected by npm at install time.

Quickstart

npm install -g @soapbucket/mcptest
mcptest --version

Or, without a global install:

npx @soapbucket/mcptest run tests/

npm install runs the postinstall hook bundled in the wrapper, which checks that the right platform binary landed. If your platform matches one of the five we publish (see below), the binary is on PATH immediately. If it does not, the wrapper falls back to a one-time download into ~/.cache/mcptest/bin/<version>/ on first run.

How the install works

The umbrella package @soapbucket/mcptest declares the following optionalDependencies:

PackageOSArch
@soapbucket/mcptest-linux-x64Linuxx64
@soapbucket/mcptest-linux-arm64Linuxarm64
@soapbucket/mcptest-darwin-x64macOSx64
@soapbucket/mcptest-darwin-arm64macOSarm64 (Apple Silicon)
@soapbucket/mcptest-win32-x64Windowsx64

Each platform package pins its os and cpu fields, so npm picks exactly one for a given machine. The native binary lives inside the platform package; the umbrella @soapbucket/mcptest ships only the Node shim that locates and runs it.

The shim is in examples/npm-wrapper/bin/mcptest.js in this repo. When the bin.mcptest field on the umbrella is run, the shim:

  1. Reads process.platform and process.arch.
  2. Resolves the matching @soapbucket/mcptest-<platform> package.
  3. Spawns the bundled binary with the caller's argv via spawnSync, so exit codes and signals pass through unchanged.

Provenance

The publishing workflow at .github/workflows/release-npm.yml uses GitHub Actions OIDC plus npm publish --provenance so every tarball carries a signed attestation linking it to the tag on this repo. Run

npm view @soapbucket/mcptest --json | jq '.dist.attestations'

to verify the most recent release before installing in a security-sensitive environment.

Troubleshooting

mcptest: unsupported platform. npm did not install any matching binary package and the on-the-fly download path could not identify your platform. Build from source (cargo install --path crates/mcptest) or file an issue with your process.platform / process.arch.

Install completes but mcptest --version fails. Run with npm_config_loglevel=verbose to see whether the postinstall hook found a platform package. If it did not, delete node_modules/, set npm_config_optional=true, and reinstall.

Behind a corporate proxy. Both npm install and the fallback download honor standard HTTPS_PROXY / HTTP_PROXY environment variables.