The CLI in CI

Gate a pipeline on breaking contract changes with mcpi-cli

What it does

mcpi-cli is the free, CI-shaped surface over the same diff engine as the app. Prebuilt binaries for macOS and Linux ship with every GitHub release. Two core commands:

sh
# Print a server's contract as JSON — commit it next to the code
mcpi-cli snapshot https://mcp.example.dev/mcp --out contract.json

# Classify what changed. Exits 1 on breaking, 2 on operational failure.
mcpi-cli diff contract.json https://mcp.example.dev/mcp

The exit code is the contract: 0 clean or compatible, 1 breaking, 2 something went wrong operationally. A pipeline gates on it directly.

Sources

Either side of a diff (and the argument of snapshot) is one of four forms:

Form Meaning
contract.json A snapshot file
https://… Dialled live over streamable HTTP
stdio:npx -y my-server Spawned and snapshotted over stdio
@v1.2 A baseline pinned in the mcpi desktop app

@baseline sources read the same local store the desktop app writes — pin a contract as "v1.2" in the app, gate on @v1.2 in a script. Auth for live sources is --header "Authorization: Bearer …"; the CLI never opens a browser and never touches the keychain.

Output

diff prints Markdown by default (--format json for machines) — the identical artifact the app's Copy as Markdown button produces, so the report in your PR matches the drawer on your screen.

GitHub Actions

hauju/mcpi-action wraps the CLI: it installs the prebuilt binary, runs the diff, and posts the classified report as a PR comment.

yaml
- name: Contract gate
  uses: hauju/mcpi-action@v1
  with:
    source: https://mcp.example.dev/mcp
    baseline: contract.json
    headers: |
      Authorization: Bearer ${{ secrets.MCP_TOKEN }}

A breaking change fails the job. To update the committed contract after an intentional change, re-run snapshot and commit the result.

Publishing to the directory

If your server is listed on the directory and you have claimed it, CI can push an owner-reported snapshot into the listing's public contract history:

sh
mcpi-cli publish stdio:node ./server.js --listing my-server --api-key $MCPI_API_KEY

The listing then shows a changelog your users can subscribe to, marked as owner-reported.

Navigation