Documentation: phillarmonic.github.io/mcpdev
AI agent skill: mcpdev — install with Repertoire
Connect to a changing MCP binary or HTTP endpoint, inspect it, call it, snapshot and semantically diff its public interface, and watch rebuilds without restarting an AI harness.
mcpdev is a Go command-line client. It treats MCP 2025-11-25 (stateful initialize) and 2026-07-28 (stateless per-request _meta) as distinct wire eras. Built-in transports are stdio and Streamable HTTP. gRPC is not a standard MCP transport. There is no browser UI, hosted tunnel, or background daemon.
Requires Go 1.27. Linux, macOS, and Windows (amd64 and arm64) are supported.
go install github.com/phillarmonic/mcpdev/cmd/mcpdev@latest
mcpdev versionFrom a checkout:
xdrun install
# or
go install ./cmd/mcpdevChecksummed release archives, mcpdev version JSON fields, and Windows .exe notes are in Installation.
In GitHub Actions, phillarmonic/setup-mcpdev installs the same archive and verifies it against SHA256SUMS. See GitHub Actions.
mcpdev is built to be driven by an agent: one command is one connection, results go to stdout, diagnostics go to stderr, and every outcome is an exit class rather than a message to parse.
The mcpdev skill
carries the CLI contract, copyable mcpdev.toml profiles, smoke and error suites,
and the protocol/failure reference. Install it with
Repertoire, the package manager
for portable agent skills:
repertoire add mcpdev --catalog phillarmonicThe skill also writes an AGENTS.md pointer, so a repository that declares it
tells its agent when to load mcpdev. Targets, updates, and the package
contents: AI agents.
The motivating loop is: rebuild a local stdio server, inspect it, lock a baseline, then let watch keep the last good binary while you edit.
Build the in-repo stdio fixture:
mkdir -p ./bin
go build -o ./bin/stdio-lab ./testdata/servers/stdio-lab
mcpdev inspect --command ./bin/stdio-labinspect starts a new child every time. You do not reconfigure Cursor, Claude, or another host. Pin an era with --protocol 2025-11-25 or --protocol 2026-07-28; default --protocol auto probes server/discover then may fall back to initialize.
mcpdev --command ./bin/stdio-lab test testdata/scenarios/valid/stdio.jsonYAML/JSON suite shape: Scenario format. Guide: Declarative tests.
mcpdev snapshot --command ./bin/stdio-lab --out testdata/mcpdev/baseline.json
mcpdev diff testdata/mcpdev/baseline.json --command ./bin/stdio-labIncomplete collection still writes a new --out path and exits 60. It does not replace an existing baseline. CI should match exit 40 (interface change) and 60 (indeterminate), not scrape stderr. Guide: Snapshots and diffs.
--rebuild is an argv array (no sh -c). Successful builds rename --staging onto --artifact. Failed builds leave the last good file in place. --command is the argv that runs after a successful promote.
mcpdev --command ./bin/weather watch \
--rebuild go --rebuild build --rebuild -o --rebuild ./bin/weather.partial --rebuild ./cmd/weather \
--staging ./bin/weather.partial --artifact ./bin/weather --debounce 200msCtrl-C cancels in-flight rebuilds and shuts the child down (stdin close, then interrupt, then kill). Full flags and generation rules: Watch and rebuild.
Streamable HTTP uses --url instead of --command (never both):
mcpdev --url http://127.0.0.1:8080/mcp inspectThe Zensical site is built from docs/ (xdrun ci includes a strict docs build).
| Topic | Page |
|---|---|
Install and version |
Installation |
| Install the release binary in CI | GitHub Actions |
| Drive the CLI from an AI agent | AI agents |
| Commands, stdout/stderr, exit classes | CLI |
| Protocol eras and fallback | Compatibility |
| Inspect | Inspect a server |
| Tests | Declarative tests |
| Snapshot / diff | Snapshots and diffs |
| Watch | Watch and rebuild |
| Framing, negotiation, auth, timeouts, leftover processes | Troubleshooting |
The site index groups every page by task: docs/index.md.
Repository automation is defined with drun, which provides the xdrun interpreter. The spec lives in .drun/spec.drun; the drun skill is part of the same Repertoire catalog as mcpdev.
xdrun --list
xdrun cixdrun ci is the required quality gate (format, vet, lint, tests, build, security, vulnerabilities, documentation). Do not tag, push, or publish from this workflow unless the repository owner asks for that specific action.
MIT. See LICENSE.