Skip to content

Installation

mcpdev is a single Go binary. Supported operating systems are Linux, macOS, and Windows (amd64 and arm64). The module requires Go 1.27 (go 1.27.3 in go.mod).

go install

go install github.com/phillarmonic/mcpdev/cmd/mcpdev@latest

Pin a release tag when you need a known snapshot schema and protocol matrix:

go install github.com/phillarmonic/mcpdev/cmd/mcpdev@v0.1.1

go install does not apply the release -ldflags. Identity then comes from runtime/debug.ReadBuildInfo: module version, vcs.revision, and vcs.time (policy vcs_time). go run reports version 0.1.1 with policy unknown. xdrun build runs go build, so in a Git checkout Go's VCS stamping fills those keys: the version becomes a pseudo-version such as 0.0.0-20261110195728-cb5bf007d015, commit is the full revision, build_time is the commit time, and the policy is vcs_time.

From a checkout:

xdrun install
# or
go install ./cmd/mcpdev

Using an AI coding agent? The mcpdev skill carries the CLI contract, copyable profiles, and scenario templates, and installs with Repertoire:

repertoire add mcpdev --catalog phillarmonic

See AI agents.

Release archives

GitHub Releases attach checksummed archives named

mcpdev_<version>_<os>_<arch>.tar.gz (Linux and macOS) or .zip (Windows).

Each archive contains one binary (mcpdev or mcpdev.exe). SHA256SUMS sits next to the archives (GNU sha256sum two-space format).

Pack locally:

xdrun pack

xdrun pack cross-compiles with CGO_ENABLED=0 and -trimpath, stamps version/commit/build time, writes dist/, then unpacks the host triple and runs mcpdev --format json version plus a stdio inspect tools against testdata/servers/stdio-lab. Cross-compiled archives are not executed on the pack host.

Build-time policy in mcpdev version:

build_time_policy When
source_date_epoch SOURCE_DATE_EPOCH was set while packing
git_commit pack used the HEAD committer unix time
vcs_time Go embedded vcs.time (go install of a module version)
unknown unstamped local build

Reproducible timestamps use that unix epoch for archive member mtimes as well as build_time.

Check identity

mcpdev version
mcpdev --format json version

JSON result includes version, commit, build_time, build_time_policy, snapshot_schema (currently 1), goos, and goarch. A snapshot file from an older mcpdev that writes a greater schema_version is rejected rather than guessed.

GitHub Actions

phillarmonic/setup-mcpdev installs the release archive on a runner, verifies it against SHA256SUMS, and adds it to PATH:

- uses: phillarmonic/setup-mcpdev@v1
  with:
    version: 'v0.1.1'

Inputs, outputs, and CI examples are in GitHub Actions.

Platform notes

Stdio children are launched as argv (no shell). Paths with spaces are one argv slot. On Unix, the child is a new process group (Setpgid). On Windows, CREATE_NEW_PROCESS_GROUP is set and os.Process.Signal / Kill are used; shutdown still closes stdin first. Helper and fixture binaries built in tests use a .exe suffix on Windows so go build -o and exec refer to the same path.

Watch mode maps fsnotify create/write/remove/rename/chmod, recursively adds new directories, and ignores bin/, dist/, and other generated trees. macOS may emit extra chmod events; they coalesce with the debounce window.

CI runs xdrun ci on Ubuntu and the focused process/transport/watch package set on Ubuntu, macOS, and Windows (xdrun matrix). Those tests do not skip core process or watch behavior per OS.