Getting Started

npm-launcher is a library for wrapper packages. End users install the wrapper (e.g. npx @mcptoolshop/sovereignty), not npm-launcher directly.

Install

Add npm-launcher as a dependency in your wrapper package:

npm install @mcptoolshop/npm-launcher

How it works

Here is the full lifecycle when a user runs your wrapper:

npx @mcptoolshop/sovereignty tutorial
        |
        v
  wrapper sets config JSON
        |
        v
  npm-launcher resolves platform (linux-x64, darwin-arm64, etc.)
        |
        v
  checks local cache (~/.cache/mcptoolshop/<tool>/<version>/)
        |
        +-- cached --> run binary
        |
        +-- not cached:
             fetch checksums-<version>.txt from GitHub Release
             download <tool>-<version>-<os>-<arch>[.exe]
             verify SHA256
             cache + chmod +x
             run binary

Supported platforms

Platform	Asset suffix
Linux x64	<tool>-<ver>-linux-x64
macOS ARM64	<tool>-<ver>-darwin-arm64
macOS x64	<tool>-<ver>-darwin-x64
Windows x64	<tool>-<ver>-win-x64.exe

CLI flags

npm-launcher answers these flags itself:

Flag	Description
--launcher-version	Print the launcher version and exit, with or without a wrapper
--version, -V	Print the launcher version and exit, only when run on its own (no config)
--help, -h	Show the launcher’s usage, only when run on its own (no config)
--print-cache-path	Show where binaries are cached for the configured tool
--clear-cache	Remove cached binaries for the configured tool

Through a wrapper, every other argument goes to the tool, --version and --help included (since 1.2.0), so npx @mcptoolshop/<tool> --version prints the tool’s version. The tool sees its own name as argv[0], so its help reads Usage: <tool> ... rather than the cached file name. The cache management flags require a configured wrapper.

Quick example

A minimal wrapper package has three files: package.json, a bin script, and a dependency on npm-launcher. See the Wrapper Guide for the complete walkthrough.