Skip to content

GitHub Actions

phillarmonic/setup-mcpdev installs the published mcpdev release binary on a runner, checks the archive against the release SHA256SUMS, and adds it to PATH. The job then runs the same binary the release published, without a Go toolchain.

Install the binary

- name: Checkout
  uses: actions/checkout@v7

- name: Setup mcpdev
  uses: phillarmonic/setup-mcpdev@v1

- name: Check identity
  run: mcpdev version

@v1 tracks the newest 1.x action release. Pin the exact tag (@v1.0.0) when a workflow needs a fixed action revision.

The action tag and the mcpdev version are separate. with.version selects the CLI release:

version Result
latest (default) Newest stable release
v0 or v0.1 Newest release on that line
v0.1.1 Exact tag
- uses: phillarmonic/setup-mcpdev@v1
  with:
    version: 'v0.1.1'

Supported targets are Linux, macOS, and Windows on amd64 and arm64: mcpdev_<version>_<os>_<arch>.tar.gz, or .zip on Windows. Archive contents and build-time policy are in Installation.

Outputs

Output Meaning
version Installed binary version, without the v prefix (0.1.1)
path Absolute path to the installed binary
cache-hit Whether the binary came from the action cache

The install step fails when the extracted binary reports a version other than the requested tag, so a mislabelled archive cannot pass silently.

Interface gate

Commit a baseline snapshot next to the server, then diff the rebuilt binary in the job. Exit 40 means the interface changed at or above --fail-on; exit 60 means a catalog did not finish collecting. Both fail the step by default.

name: MCP interface

on: [pull_request]

jobs:
  interface:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-go@v6
        with:
          go-version-file: go.mod

      - uses: phillarmonic/setup-mcpdev@v1

      - name: Rebuild the server
        run: go build -o ./bin/server ./cmd/server

      - name: Compare against the committed baseline
        run: mcpdev diff testdata/mcpdev/baseline.json --command ./bin/server --fail-on breaking

Refresh the baseline locally when a change is intentional:

mcpdev snapshot --command ./bin/server --out testdata/mcpdev/baseline.json

Classification rules and the full exit table are in Snapshots and diffs.

Declarative suites and JUnit

- name: Run the suite
  run: mcpdev --command ./bin/server --junit ./tmp/mcpdev-junit.xml test testdata/scenarios

- name: Upload the JUnit report
  if: always()
  uses: actions/upload-artifact@v6
  with:
    name: mcpdev-junit
    path: ./tmp/mcpdev-junit.xml

Assertion failures become JUnit failure records; connection, protocol, and cleanup problems become error records. Suite shape and failure classes are in Declarative tests.

Caching

The action caches the installed binary under a key built from the mcpdev version and the runner platform. Set cache: 'false' to download on every job. A restored binary still goes through the version check, and a fresh download is always checked against SHA256SUMS.

Failure modes

Symptom Cause
mcpdev: command not found The setup step did not run, or the runner platform is unsupported
Checksum mismatch The archive and SHA256SUMS disagree; report the release instead of retrying
Version mismatch The tag and the archive disagree; pin a different release

Hosted runners include the curl, jq, tar, and checksum tools the action uses.