From f6e25d49d08a930faa99f81cb2cb25b42cbe0592 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Wed, 18 Nov 2026 12:54:47 -0500 Subject: [PATCH] ci: rename everything-mcp-diff.yml to mcp-interface-diff.yml (step 2) Step 2 of the rename staged in #5463. The placeholder shipped to main in the v2.5.0 milestone merge, so GitHub can dispatch the new file name. - Move the interface diff's contents into mcp-interface-diff.yml, with its push, pull_request, release and workflow_dispatch triggers, and delete everything-mcp-diff.yml. - Point both version workflows' dispatch loops, and the diff's own `gh run list --workflow` calls, at the new name. - Update TOOLING_PATHS, the version PR CI test (which now pins the end state instead of the placeholder), RELEASING.md, the release skill, docs/quality-gate.md and the AGENTS.md tree. Closes #5527 Co-Authored-By: Claude Fable 5.2 Signed-off-by: cliffhall --- .claude/skills/release/SKILL.md | 2 +- .github/workflows/everything-mcp-diff.yml | 432 ------------------ .github/workflows/mcp-interface-diff.yml | 447 +++++++++++++++++-- .github/workflows/prepare-python-release.yml | 4 +- .github/workflows/version-packages.yml | 2 +- AGENTS.md | 3 +- RELEASING.md | 2 +- docs/quality-gate.md | 4 +- scripts/interface-diff.mjs | 2 +- scripts/lib/interface-diff-servers.mjs | 4 +- scripts/version-pr-ci.test.mjs | 48 +- 11 files changed, 464 insertions(+), 486 deletions(-) delete mode 100644 .github/workflows/everything-mcp-diff.yml diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index e939551079..ae178c578b 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -216,7 +216,7 @@ Then, on the PR: (that fires `pull_request`; they run on `push`). If a status does not appear, dispatch its workflow by hand: `gh workflow run typescript.yml --ref changeset-release/v2/main` (or - `python.yml`, `dco.yml`, `everything-mcp-diff.yml`). + `python.yml`, `dco.yml`, `mcp-interface-diff.yml`). 3. **Read it**: each bump matches the semver policy in `RELEASING.md`, each `CHANGELOG.md` entry says what a user of the server needs to know, the consumed changeset files are deleted, and `package-lock.json` records the diff --git a/.github/workflows/everything-mcp-diff.yml b/.github/workflows/everything-mcp-diff.yml deleted file mode 100644 index 3de61944a4..0000000000 --- a/.github/workflows/everything-mcp-diff.yml +++ /dev/null @@ -1,432 +0,0 @@ -# Tracks public interface changes to the MCP servers: how each server's tools, -# resources, prompts and capabilities evolve, so a reviewer sees the protocol -# surface a change moves without running anything (useful for SDK compliance -# validation and catching regressions). -# -# Contributed by @SamMorrowDrums in #3260 for the Everything server, adapted for -# v2/main in #4860, and extended to every server in #5428: -# -# - The check is `npm run interface-diff` (scripts/interface-diff.mjs), which -# drives the `mcp-server-diff` CLI, an exact-pinned root devDependency. The -# same script is a `local:gate` stage, and `scripts/lib/workflow-gate.test.mjs` -# requires every npm script a workflow runs to be one, so CI and the gate run -# the same check. No third-party action runs here. -# - A server is diffed only when the change touches it: its own directory, a -# package it resolves in the root lockfile, the root tsconfig (TypeScript -# servers), or the diff tooling itself (every server). A `paths` filter -# cannot say "the lockfile changed in a way that reaches this server", and -# almost every TypeScript PR rewrites the lockfile, so the workflow runs on -# every change and the `changes` job asks the script which servers to diff -# (`--list`, the same selection the gate makes). `diff` and `comment` fan out -# over that list, one matrix leg per server. -# - The base is chosen per event below rather than by the tool, whose default -# (the merge-base with origin/main) is the wrong base for PRs to v2/main. -# - Untrusted code (the PR's install, build and server, and the selection -# script) runs only in `changes` and `diff`, which hold a read-only token and -# no persisted credentials. Each sticky comment (one per server, found again -# by its marker) is posted by `comment`, which holds `pull-requests: write` -# and runs none of the PR's code, and only for PRs from this repository: a -# fork PR's token is read-only, so there the report is in the job summary and -# the `mcp-diff-report-` artifact. `pull_request_target` is -# deliberately not used, since it would run the fork's build next to a write -# token. If fork PRs need the comment too, the way is a separate -# `workflow_run` workflow that posts the artifact without checking anything -# out. The server names `comment` reads come from `changes`, which ran PR -# code, so it checks each against the known list before using it. -# -# A changed interface does not fail the run: the diff is information for the -# reviewer. A diff that cannot run (a base that does not build, a server that -# cannot be probed) does. -# -# A server's comment is left as it is when a later push stops touching that -# server; it then describes the last push that did. -# -# The version PRs are pushed and opened with the workflow token, whose events -# start no `pull_request` run here: GitHub holds each one as -# `action_required`, or fails it with no jobs (#5173). So the Version Packages -# and Prepare Python Release workflows dispatch this one on the PR's branch, as -# they do the CI workflows (#5110), and the `dispatch-status` jobs report the -# dispatched run on the PR as a commit status. -# -# The file keeps its `everything-` name although it diffs every server: GitHub -# dispatches only a workflow whose file exists on the default branch (`main`), -# and both version workflows dispatch this one by file name from `v2/main`, so -# renaming it here would break their dispatch until the next milestone merge. -# The rename is staged instead: `mcp-interface-diff.yml` lands on `main` first -# as a dispatch-only placeholder (#5463), then #5527 moves this file's contents -# there, switches the callers and deletes this file. -# -# See: https://github.com/modelcontextprotocol/inspector/issues/1034 -name: MCP Interface Diff - -on: - push: - branches: [main, v2/main] - # No branch filter: PRs to v2/main and to main both run, and so does a PR - # stacked on another PR's branch. The base is the PR's own base either way. - pull_request: - # A published Release (a milestone, tagged vX.Y.Z on main; see RELEASING.md) - # surfaces the cumulative interface delta since the previous Release, for - # each server that changed in between. This replaces #3260's - # `typescript-servers-*` tag trigger: those tags stopped in 2024, and no - # release since has used them. - release: - types: [published] - # Manual trigger: the branch chosen in "Use workflow from" is the head, and - # `compare_ref` any base. #3260 also took a `target_ref`, but a target that - # predates the interface-diff script has no `npm run interface-diff` to run, - # so the head is the dispatched branch instead. - workflow_dispatch: - inputs: - compare_ref: - description: "Base ref to compare against (commit SHA, tag, or branch; defaults to the merge-base with v2/main)" - required: false - default: "" - -permissions: - contents: read - -# Superseded runs on the same PR are cancelled. Every other run gets a group -# of its own: a group holds one running and one pending run, so a shared group -# would drop a push's run when two more queued behind it. -concurrency: - group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} - -jobs: - changes: - name: Choose the servers to diff - timeout-minutes: 10 - runs-on: ubuntu-latest - permissions: - contents: read - outputs: - base: ${{ steps.base.outputs.ref }} - servers: ${{ steps.list.outputs.servers }} - steps: - - name: Checkout repository - uses: actions/checkout@v6 - with: - # The base is found in history, so all of it is needed, tags - # included (the release base is the previous Release's tag). - fetch-depth: 0 - # The event's own commit (the merge commit for a PR), not a branch - # ref that a later push could move before this step runs. - ref: ${{ github.sha }} - persist-credentials: false - - # No install: the selection imports nothing outside Node. - - uses: actions/setup-node@v7 - with: - node-version: 24 - - - name: Choose the base to compare against - id: base - env: - EVENT: ${{ github.event_name }} - PR_BASE: ${{ github.event.pull_request.base.sha }} - BEFORE: ${{ github.event.before }} - INPUT_BASE: ${{ inputs.compare_ref }} - TAG: ${{ github.event.release.tag_name }} - PUBLISHED: ${{ github.event.release.published_at }} - REPO: ${{ github.repository }} - GH_TOKEN: ${{ github.token }} - run: | - case "$EVENT" in - # The checkout is the PR's merge commit, so its base tip is - # exactly what the PR changes. - pull_request) base="$PR_BASE" ;; - # The branch as it was before this push; a new branch has none. - push) - if [ -n "$BEFORE" ] && [ "$BEFORE" != 0000000000000000000000000000000000000000 ]; then - base="$BEFORE" - else - base=$(git rev-parse HEAD^) - fi ;; - # The Release published just before this one (so a re-run of an - # older Release still compares against ITS predecessor). Not - # `git describe`: the date-stamped releases tagged commits that - # never reached main, so the nearest ancestor tag is years older - # than the last release. - release) - base=$(gh release list --repo "$REPO" --exclude-drafts --exclude-pre-releases --limit 50 \ - --json tagName,publishedAt \ - --jq "map(select(.tagName != \"$TAG\" and .publishedAt < \"$PUBLISHED\")) | sort_by(.publishedAt) | last | .tagName // empty") - if [ -z "$base" ]; then echo "no earlier Release to compare against" >&2; exit 1; fi ;; - workflow_dispatch) - if [ -n "$INPUT_BASE" ]; then - base="$INPUT_BASE" - else - base=$(git merge-base HEAD origin/v2/main) - fi ;; - *) echo "unexpected event: $EVENT" >&2; exit 1 ;; - esac - # Resolved to a SHA here, so every leg compares against the same - # commit even if a branch named as the base moves meanwhile. - base=$(git rev-parse --verify "$base^{commit}") - echo "Comparing against $base" - echo "ref=$base" >> "$GITHUB_OUTPUT" - - - name: List the servers the change touches - id: list - env: - BASE: ${{ steps.base.outputs.ref }} - run: | - # The reasons go to the log on stderr; stdout is the JSON list. - servers=$(npm run --silent interface-diff -- --base "$BASE" --list) - echo "Servers to diff: $servers" - echo "servers=$servers" >> "$GITHUB_OUTPUT" - { - if [ "$servers" = "[]" ]; then - echo "No server changed since \`$BASE\`; there is no interface to diff." - else - echo "Diffing: $(jq -r 'map("`" + .server + "`") | join(", ")' <<<"$servers")" - fi - } >> "$GITHUB_STEP_SUMMARY" - - diff: - name: Diff ${{ matrix.server }} - needs: changes - if: needs.changes.outputs.servers != '[]' - timeout-minutes: 15 - runs-on: ubuntu-latest - permissions: - contents: read - strategy: - # One server's broken diff must not hide another's report. - fail-fast: false - matrix: - include: ${{ fromJSON(needs.changes.outputs.servers) }} - steps: - - name: Checkout repository - uses: actions/checkout@v6 - with: - # The base is built from history. - fetch-depth: 0 - ref: ${{ github.sha }} - persist-credentials: false - - - uses: actions/setup-node@v7 - with: - node-version: 24 - cache: npm - - # A root `npm ci` runs every workspace's `prepare`, which builds it, so - # a TypeScript head build the diff probes exists after this step. It also - # installs `mcp-server-diff`, which every leg needs. - - name: Install dependencies and build - run: npm ci - - - name: Install uv - if: matrix.language == 'py' - uses: astral-sh/setup-uv@v7 - - # The diff probes a Python head with `uv run --no-sync`, so its - # environment is synced here, as the gate's `validate:py` does. - - name: Sync the Python server - if: matrix.language == 'py' - working-directory: src/${{ matrix.server }} - run: uv sync --locked - - - name: Diff the interface - env: - BASE: ${{ needs.changes.outputs.base }} - SERVER: ${{ matrix.server }} - run: npm run interface-diff -- --base "$BASE" --server "$SERVER" --report-dir mcp-diff-report - - - name: Write the job summary - if: always() - env: - SERVER: ${{ matrix.server }} - run: | - report="mcp-diff-report/$SERVER/report.md" - { - if [ -f "$report" ]; then - # A step summary holds at most 1 MiB. - head -c 900000 "$report" - if [ "$(wc -c < "$report")" -gt 900000 ]; then - echo "" - echo "_The report is truncated here; the full report is in the run's \`mcp-diff-report-$SERVER\` artifact._" - fi - else - echo "The interface diff produced no report; see the job log." - fi - echo "" - echo "---" - echo "" - echo "ℹ️ **Interpreting Results**" - echo "" - echo "These are reference servers, so a change to one's interface may indicate:" - echo "- New MCP protocol features being demonstrated" - echo "- Updated tool schemas or descriptions" - echo "- New resources, prompts, or capabilities" - echo "" - echo "Review changes to ensure they align with the intended protocol updates." - } >> "$GITHUB_STEP_SUMMARY" - - - name: Upload the report - if: always() - uses: actions/upload-artifact@v7 - with: - name: mcp-diff-report-${{ matrix.server }} - path: mcp-diff-report/ - if-no-files-found: ignore - - # A dispatched run's checks are left out of the status rollup a pull request - # reads, so on a dispatch these two jobs mirror the run onto the commit as a - # status, as in typescript.yml (whose comments hold the reasoning): pending - # at the start, then the result. Every other event skips both. Unlike - # typescript.yml's (#5223), the pending job also stays silent when a newer - # dispatched run exists, so a late or re-run older run cannot reset the - # newer run's result to pending, which its own result job would then leave. - dispatch-status-pending: - name: Report the dispatched run as pending - if: github.event_name == 'workflow_dispatch' - timeout-minutes: 5 - runs-on: ubuntu-latest - permissions: - statuses: write - # To look for a newer dispatched run of this workflow on the commit. - actions: read - steps: - - name: Set the commit status to pending - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - GH_REPO: ${{ github.repository }} - run: | - # A re-run keeps its run ID, so a newer run means this one is - # superseded and the status is no longer its to set. - NEWER=$(gh run list --workflow everything-mcp-diff.yml --event workflow_dispatch \ - --commit "$GITHUB_SHA" --json databaseId \ - --jq "[.[] | select(.databaseId > $GITHUB_RUN_ID)] | length") || NEWER=0 - if [ "${NEWER:-0}" -gt 0 ]; then - echo "Superseded by a newer dispatched run, which reports instead" - exit 0 - fi - gh api "repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA" \ - -f state=pending -f context="Interface diff (dispatched)" \ - -f description="Dispatched run in progress" \ - -f target_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" - - # `comment` runs only on `pull_request`, so on a dispatch it is skipped, - # which counts as passed, and so is `diff` when no server changed; the report - # is in the run's summary and artifacts. - dispatch-status: - name: Report the dispatched run's result - if: github.event_name == 'workflow_dispatch' && always() - needs: [dispatch-status-pending, changes, diff, comment] - timeout-minutes: 5 - runs-on: ubuntu-latest - permissions: - statuses: write - # To look for a newer dispatched run of this workflow on the commit. - actions: read - steps: - - name: Set the commit status to the run's result - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - GH_REPO: ${{ github.repository }} - NEEDS: ${{ toJSON(needs) }} - run: | - # A run superseded by a newer dispatch on the same commit posts - # nothing, whatever its jobs' results: the newer run owns the status - # (#5178). A failed lookup counts as no newer run, so this run still - # reports: a stale status is better than one left pending. - NEWER=$(gh run list --workflow everything-mcp-diff.yml --event workflow_dispatch \ - --commit "$GITHUB_SHA" --json databaseId \ - --jq "[.[] | select(.databaseId > $GITHUB_RUN_ID)] | length") || NEWER=0 - if [ "${NEWER:-0}" -gt 0 ]; then - echo "Superseded by a newer dispatched run, which reports instead" - exit 0 - fi - if jq -e 'all(.[]; .result == "success" or .result == "skipped")' <<<"$NEEDS" >/dev/null; then - STATE=success DESCRIPTION="The diff ran; the report is in the run's summary" - elif jq -e 'any(.[]; .result == "failure")' <<<"$NEEDS" >/dev/null; then - STATE=failure DESCRIPTION="The diff could not run; open the run for details" - else - STATE=error DESCRIPTION="The run was cancelled; dispatch it again" - fi - gh api "repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA" \ - -f state="$STATE" -f context="Interface diff (dispatched)" \ - -f description="$DESCRIPTION" \ - -f target_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" - - # Post (or update) one sticky PR comment per diffed server so reviewers can - # see the diff without navigating to the Actions tab, found again by its - # per-server marker and edited on each push. This job checks nothing out and - # runs none of the PR's code; it only reads the report the `diff` leg - # uploaded. Dependabot's PRs are same-repo but get a read-only token, so they - # are skipped like fork PRs and keep the job summary and the artifact. - comment: - name: Post the ${{ matrix.server }} diff on the PR - needs: [changes, diff] - if: >- - always() && - github.event_name == 'pull_request' && - github.event.pull_request.head.repo.full_name == github.repository && - github.event.pull_request.user.login != 'dependabot[bot]' && - needs.changes.result == 'success' && - needs.changes.outputs.servers != '[]' && - (needs.diff.result == 'success' || needs.diff.result == 'failure') - timeout-minutes: 5 - runs-on: ubuntu-latest - permissions: - pull-requests: write - strategy: - fail-fast: false - matrix: - include: ${{ fromJSON(needs.changes.outputs.servers) }} - steps: - # The list came from a job that ran the PR's code; only a known server - # name reaches an artifact name, a marker or a path below. - - name: Check the server name - env: - SERVER: ${{ matrix.server }} - run: | - case "$SERVER" in - everything|filesystem|memory|sequentialthinking|fetch|git|time) ;; - *) echo "::error::Not a known server: $SERVER"; exit 1 ;; - esac - - - name: Download the report - uses: actions/download-artifact@v8 - continue-on-error: true - with: - name: mcp-diff-report-${{ matrix.server }} - path: mcp-diff-report - - - name: Post / update sticky PR comment - env: - GH_TOKEN: ${{ github.token }} - REPO: ${{ github.repository }} - PR: ${{ github.event.pull_request.number }} - HEAD_SHA: ${{ github.event.pull_request.head.sha }} - SERVER: ${{ matrix.server }} - RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} - run: | - marker="" - report="mcp-diff-report/$SERVER/report.md" - { - echo "$marker" - if [ -f "$report" ]; then - # A comment holds at most 65536 characters. - head -c 60000 "$report" - if [ "$(wc -c < "$report")" -gt 60000 ]; then - echo "" - echo "_The report is truncated here; the full report is in the run's \`mcp-diff-report-$SERVER\` artifact._" - fi - else - echo "## \`$SERVER\`: MCP interface diff" - echo "" - echo "❌ The diff job produced no report; see the run's log." - fi - echo "" - echo "Updated by [this run]($RUN_URL) for \`$HEAD_SHA\`." - } > body.md - id=$(gh api --paginate "repos/$REPO/issues/$PR/comments" \ - --jq ".[] | select(.user.login == \"github-actions[bot]\" and (.body | startswith(\"$marker\"))) | .id" | head -n 1) - if [ -n "$id" ]; then - gh api -X PATCH "repos/$REPO/issues/comments/$id" -F body=@body.md > /dev/null - else - gh api "repos/$REPO/issues/$PR/comments" -F body=@body.md > /dev/null - fi diff --git a/.github/workflows/mcp-interface-diff.yml b/.github/workflows/mcp-interface-diff.yml index 4bda642ed5..e8ca5936e7 100644 --- a/.github/workflows/mcp-interface-diff.yml +++ b/.github/workflows/mcp-interface-diff.yml @@ -1,42 +1,435 @@ -# Placeholder for the MCP interface diff's future file name (#5463, Step 1 of -# a rename staged across a milestone merge). +# Tracks public interface changes to the MCP servers: how each server's tools, +# resources, prompts and capabilities evolve, so a reviewer sees the protocol +# surface a change moves without running anything (useful for SDK compliance +# validation and catching regressions). # -# The interface diff lives in `everything-mcp-diff.yml`, a name left over from -# when it diffed only the Everything server. GitHub dispatches a workflow only -# when its file exists on the default branch (`main`), and both version -# workflows (`version-packages.yml`, `prepare-python-release.yml`) dispatch -# the diff by file name from `v2/main`. Renaming it in one step on `v2/main` -# would break their dispatch until the next milestone merge. So the rename is -# staged: +# Contributed by @SamMorrowDrums in #3260 for the Everything server, adapted for +# v2/main in #4860, and extended to every server in #5428: # -# 1. This file ships to `main` in a milestone merge. It is a placeholder, not -# a copy of the diff: a dispatch resolves the file name on `main` but runs -# the file as it is on the dispatched ref, so a placeholder makes the name -# dispatchable as well as a copy would, without a second copy to keep in -# step meanwhile. It has only a `workflow_dispatch` trigger, so it never -# runs beside the real diff on a push or a pull request. -# 2. After that merge, #5527 (Step 2) moves `everything-mcp-diff.yml`'s -# contents here, switches the callers to this name, and deletes the old -# file. +# - The check is `npm run interface-diff` (scripts/interface-diff.mjs), which +# drives the `mcp-server-diff` CLI, an exact-pinned root devDependency. The +# same script is a `local:gate` stage, and `scripts/lib/workflow-gate.test.mjs` +# requires every npm script a workflow runs to be one, so CI and the gate run +# the same check. No third-party action runs here. +# - A server is diffed only when the change touches it: its own directory, a +# package it resolves in the root lockfile, the root tsconfig (TypeScript +# servers), or the diff tooling itself (every server). A `paths` filter +# cannot say "the lockfile changed in a way that reaches this server", and +# almost every TypeScript PR rewrites the lockfile, so the workflow runs on +# every change and the `changes` job asks the script which servers to diff +# (`--list`, the same selection the gate makes). `diff` and `comment` fan out +# over that list, one matrix leg per server. +# - The base is chosen per event below rather than by the tool, whose default +# (the merge-base with origin/main) is the wrong base for PRs to v2/main. +# - Untrusted code (the PR's install, build and server, and the selection +# script) runs only in `changes` and `diff`, which hold a read-only token and +# no persisted credentials. Each sticky comment (one per server, found again +# by its marker) is posted by `comment`, which holds `pull-requests: write` +# and runs none of the PR's code, and only for PRs from this repository: a +# fork PR's token is read-only, so there the report is in the job summary and +# the `mcp-diff-report-` artifact. `pull_request_target` is +# deliberately not used, since it would run the fork's build next to a write +# token. If fork PRs need the comment too, the way is a separate +# `workflow_run` workflow that posts the artifact without checking anything +# out. The server names `comment` reads come from `changes`, which ran PR +# code, so it checks each against the known list before using it. # -# Until then, nothing dispatches this file, and a manual dispatch only says -# where the diff is. -name: MCP Interface Diff (rename placeholder) +# A changed interface does not fail the run: the diff is information for the +# reviewer. A diff that cannot run (a base that does not build, a server that +# cannot be probed) does. +# +# A server's comment is left as it is when a later push stops touching that +# server; it then describes the last push that did. +# +# The version PRs are pushed and opened with the workflow token, whose events +# start no `pull_request` run here: GitHub holds each one as +# `action_required`, or fails it with no jobs (#5173). So the Version Packages +# and Prepare Python Release workflows dispatch this one on the PR's branch, as +# they do the CI workflows (#5110), and the `dispatch-status` jobs report the +# dispatched run on the PR as a commit status. +# +# The file was `everything-mcp-diff.yml` until #5527, a name left over from +# when it diffed only the Everything server. GitHub dispatches only a workflow +# whose file exists on the default branch (`main`), and both version workflows +# dispatch this one by file name from `v2/main`, so the rename was staged +# across a milestone merge: this name reached `main` first as a dispatch-only +# placeholder (#5463, in v2.5.0), and only then did #5527 move the diff here, +# switch the callers and delete the old file. Renaming it again takes the same +# two steps. `main` keeps its own `everything-mcp-diff.yml` until the next +# milestone merge deletes it there; nothing dispatches it, and `main` takes no +# other push or pull request in between. +# +# See: https://github.com/modelcontextprotocol/inspector/issues/1034 +name: MCP Interface Diff on: + push: + branches: [main, v2/main] + # No branch filter: PRs to v2/main and to main both run, and so does a PR + # stacked on another PR's branch. The base is the PR's own base either way. + pull_request: + # A published Release (a milestone, tagged vX.Y.Z on main; see RELEASING.md) + # surfaces the cumulative interface delta since the previous Release, for + # each server that changed in between. This replaces #3260's + # `typescript-servers-*` tag trigger: those tags stopped in 2024, and no + # release since has used them. + release: + types: [published] + # Manual trigger: the branch chosen in "Use workflow from" is the head, and + # `compare_ref` any base. #3260 also took a `target_ref`, but a target that + # predates the interface-diff script has no `npm run interface-diff` to run, + # so the head is the dispatched branch instead. workflow_dispatch: + inputs: + compare_ref: + description: "Base ref to compare against (commit SHA, tag, or branch; defaults to the merge-base with v2/main)" + required: false + default: "" permissions: contents: read +# Superseded runs on the same PR are cancelled. Every other run gets a group +# of its own: a group holds one running and one pending run, so a shared group +# would drop a push's run when two more queued behind it. +concurrency: + group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + jobs: - placeholder: - name: Point to the interface diff + changes: + name: Choose the servers to diff + timeout-minutes: 10 + runs-on: ubuntu-latest + permissions: + contents: read + outputs: + base: ${{ steps.base.outputs.ref }} + servers: ${{ steps.list.outputs.servers }} + steps: + - name: Checkout repository + uses: actions/checkout@v6 + with: + # The base is found in history, so all of it is needed, tags + # included (the release base is the previous Release's tag). + fetch-depth: 0 + # The event's own commit (the merge commit for a PR), not a branch + # ref that a later push could move before this step runs. + ref: ${{ github.sha }} + persist-credentials: false + + # No install: the selection imports nothing outside Node. + - uses: actions/setup-node@v7 + with: + node-version: 24 + + - name: Choose the base to compare against + id: base + env: + EVENT: ${{ github.event_name }} + PR_BASE: ${{ github.event.pull_request.base.sha }} + BEFORE: ${{ github.event.before }} + INPUT_BASE: ${{ inputs.compare_ref }} + TAG: ${{ github.event.release.tag_name }} + PUBLISHED: ${{ github.event.release.published_at }} + REPO: ${{ github.repository }} + GH_TOKEN: ${{ github.token }} + run: | + case "$EVENT" in + # The checkout is the PR's merge commit, so its base tip is + # exactly what the PR changes. + pull_request) base="$PR_BASE" ;; + # The branch as it was before this push; a new branch has none. + push) + if [ -n "$BEFORE" ] && [ "$BEFORE" != 0000000000000000000000000000000000000000 ]; then + base="$BEFORE" + else + base=$(git rev-parse HEAD^) + fi ;; + # The Release published just before this one (so a re-run of an + # older Release still compares against ITS predecessor). Not + # `git describe`: the date-stamped releases tagged commits that + # never reached main, so the nearest ancestor tag is years older + # than the last release. + release) + base=$(gh release list --repo "$REPO" --exclude-drafts --exclude-pre-releases --limit 50 \ + --json tagName,publishedAt \ + --jq "map(select(.tagName != \"$TAG\" and .publishedAt < \"$PUBLISHED\")) | sort_by(.publishedAt) | last | .tagName // empty") + if [ -z "$base" ]; then echo "no earlier Release to compare against" >&2; exit 1; fi ;; + workflow_dispatch) + if [ -n "$INPUT_BASE" ]; then + base="$INPUT_BASE" + else + base=$(git merge-base HEAD origin/v2/main) + fi ;; + *) echo "unexpected event: $EVENT" >&2; exit 1 ;; + esac + # Resolved to a SHA here, so every leg compares against the same + # commit even if a branch named as the base moves meanwhile. + base=$(git rev-parse --verify "$base^{commit}") + echo "Comparing against $base" + echo "ref=$base" >> "$GITHUB_OUTPUT" + + - name: List the servers the change touches + id: list + env: + BASE: ${{ steps.base.outputs.ref }} + run: | + # The reasons go to the log on stderr; stdout is the JSON list. + servers=$(npm run --silent interface-diff -- --base "$BASE" --list) + echo "Servers to diff: $servers" + echo "servers=$servers" >> "$GITHUB_OUTPUT" + { + if [ "$servers" = "[]" ]; then + echo "No server changed since \`$BASE\`; there is no interface to diff." + else + echo "Diffing: $(jq -r 'map("`" + .server + "`") | join(", ")' <<<"$servers")" + fi + } >> "$GITHUB_STEP_SUMMARY" + + diff: + name: Diff ${{ matrix.server }} + needs: changes + if: needs.changes.outputs.servers != '[]' + timeout-minutes: 15 + runs-on: ubuntu-latest + permissions: + contents: read + strategy: + # One server's broken diff must not hide another's report. + fail-fast: false + matrix: + include: ${{ fromJSON(needs.changes.outputs.servers) }} + steps: + - name: Checkout repository + uses: actions/checkout@v6 + with: + # The base is built from history. + fetch-depth: 0 + ref: ${{ github.sha }} + persist-credentials: false + + - uses: actions/setup-node@v7 + with: + node-version: 24 + cache: npm + + # A root `npm ci` runs every workspace's `prepare`, which builds it, so + # a TypeScript head build the diff probes exists after this step. It also + # installs `mcp-server-diff`, which every leg needs. + - name: Install dependencies and build + run: npm ci + + - name: Install uv + if: matrix.language == 'py' + uses: astral-sh/setup-uv@v7 + + # The diff probes a Python head with `uv run --no-sync`, so its + # environment is synced here, as the gate's `validate:py` does. + - name: Sync the Python server + if: matrix.language == 'py' + working-directory: src/${{ matrix.server }} + run: uv sync --locked + + - name: Diff the interface + env: + BASE: ${{ needs.changes.outputs.base }} + SERVER: ${{ matrix.server }} + run: npm run interface-diff -- --base "$BASE" --server "$SERVER" --report-dir mcp-diff-report + + - name: Write the job summary + if: always() + env: + SERVER: ${{ matrix.server }} + run: | + report="mcp-diff-report/$SERVER/report.md" + { + if [ -f "$report" ]; then + # A step summary holds at most 1 MiB. + head -c 900000 "$report" + if [ "$(wc -c < "$report")" -gt 900000 ]; then + echo "" + echo "_The report is truncated here; the full report is in the run's \`mcp-diff-report-$SERVER\` artifact._" + fi + else + echo "The interface diff produced no report; see the job log." + fi + echo "" + echo "---" + echo "" + echo "ℹ️ **Interpreting Results**" + echo "" + echo "These are reference servers, so a change to one's interface may indicate:" + echo "- New MCP protocol features being demonstrated" + echo "- Updated tool schemas or descriptions" + echo "- New resources, prompts, or capabilities" + echo "" + echo "Review changes to ensure they align with the intended protocol updates." + } >> "$GITHUB_STEP_SUMMARY" + + - name: Upload the report + if: always() + uses: actions/upload-artifact@v7 + with: + name: mcp-diff-report-${{ matrix.server }} + path: mcp-diff-report/ + if-no-files-found: ignore + + # A dispatched run's checks are left out of the status rollup a pull request + # reads, so on a dispatch these two jobs mirror the run onto the commit as a + # status, as in typescript.yml (whose comments hold the reasoning): pending + # at the start, then the result. Every other event skips both. Unlike + # typescript.yml's (#5223), the pending job also stays silent when a newer + # dispatched run exists, so a late or re-run older run cannot reset the + # newer run's result to pending, which its own result job would then leave. + dispatch-status-pending: + name: Report the dispatched run as pending + if: github.event_name == 'workflow_dispatch' + timeout-minutes: 5 + runs-on: ubuntu-latest + permissions: + statuses: write + # To look for a newer dispatched run of this workflow on the commit. + actions: read + steps: + - name: Set the commit status to pending + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GH_REPO: ${{ github.repository }} + run: | + # A re-run keeps its run ID, so a newer run means this one is + # superseded and the status is no longer its to set. + NEWER=$(gh run list --workflow mcp-interface-diff.yml --event workflow_dispatch \ + --commit "$GITHUB_SHA" --json databaseId \ + --jq "[.[] | select(.databaseId > $GITHUB_RUN_ID)] | length") || NEWER=0 + if [ "${NEWER:-0}" -gt 0 ]; then + echo "Superseded by a newer dispatched run, which reports instead" + exit 0 + fi + gh api "repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA" \ + -f state=pending -f context="Interface diff (dispatched)" \ + -f description="Dispatched run in progress" \ + -f target_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" + + # `comment` runs only on `pull_request`, so on a dispatch it is skipped, + # which counts as passed, and so is `diff` when no server changed; the report + # is in the run's summary and artifacts. + dispatch-status: + name: Report the dispatched run's result + if: github.event_name == 'workflow_dispatch' && always() + needs: [dispatch-status-pending, changes, diff, comment] timeout-minutes: 5 runs-on: ubuntu-latest + permissions: + statuses: write + # To look for a newer dispatched run of this workflow on the commit. + actions: read steps: - - name: Say where the interface diff runs + - name: Set the commit status to the run's result + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GH_REPO: ${{ github.repository }} + NEEDS: ${{ toJSON(needs) }} + run: | + # A run superseded by a newer dispatch on the same commit posts + # nothing, whatever its jobs' results: the newer run owns the status + # (#5178). A failed lookup counts as no newer run, so this run still + # reports: a stale status is better than one left pending. + NEWER=$(gh run list --workflow mcp-interface-diff.yml --event workflow_dispatch \ + --commit "$GITHUB_SHA" --json databaseId \ + --jq "[.[] | select(.databaseId > $GITHUB_RUN_ID)] | length") || NEWER=0 + if [ "${NEWER:-0}" -gt 0 ]; then + echo "Superseded by a newer dispatched run, which reports instead" + exit 0 + fi + if jq -e 'all(.[]; .result == "success" or .result == "skipped")' <<<"$NEEDS" >/dev/null; then + STATE=success DESCRIPTION="The diff ran; the report is in the run's summary" + elif jq -e 'any(.[]; .result == "failure")' <<<"$NEEDS" >/dev/null; then + STATE=failure DESCRIPTION="The diff could not run; open the run for details" + else + STATE=error DESCRIPTION="The run was cancelled; dispatch it again" + fi + gh api "repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA" \ + -f state="$STATE" -f context="Interface diff (dispatched)" \ + -f description="$DESCRIPTION" \ + -f target_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" + + # Post (or update) one sticky PR comment per diffed server so reviewers can + # see the diff without navigating to the Actions tab, found again by its + # per-server marker and edited on each push. This job checks nothing out and + # runs none of the PR's code; it only reads the report the `diff` leg + # uploaded. Dependabot's PRs are same-repo but get a read-only token, so they + # are skipped like fork PRs and keep the job summary and the artifact. + comment: + name: Post the ${{ matrix.server }} diff on the PR + needs: [changes, diff] + if: >- + always() && + github.event_name == 'pull_request' && + github.event.pull_request.head.repo.full_name == github.repository && + github.event.pull_request.user.login != 'dependabot[bot]' && + needs.changes.result == 'success' && + needs.changes.outputs.servers != '[]' && + (needs.diff.result == 'success' || needs.diff.result == 'failure') + timeout-minutes: 5 + runs-on: ubuntu-latest + permissions: + pull-requests: write + strategy: + fail-fast: false + matrix: + include: ${{ fromJSON(needs.changes.outputs.servers) }} + steps: + # The list came from a job that ran the PR's code; only a known server + # name reaches an artifact name, a marker or a path below. + - name: Check the server name + env: + SERVER: ${{ matrix.server }} + run: | + case "$SERVER" in + everything|filesystem|memory|sequentialthinking|fetch|git|time) ;; + *) echo "::error::Not a known server: $SERVER"; exit 1 ;; + esac + + - name: Download the report + uses: actions/download-artifact@v8 + continue-on-error: true + with: + name: mcp-diff-report-${{ matrix.server }} + path: mcp-diff-report + + - name: Post / update sticky PR comment + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + PR: ${{ github.event.pull_request.number }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} + SERVER: ${{ matrix.server }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} run: | - echo "This file is a placeholder for a staged rename (#5463, #5527)." - echo "The MCP interface diff runs from .github/workflows/everything-mcp-diff.yml:" - echo " gh workflow run everything-mcp-diff.yml --ref " + marker="" + report="mcp-diff-report/$SERVER/report.md" + { + echo "$marker" + if [ -f "$report" ]; then + # A comment holds at most 65536 characters. + head -c 60000 "$report" + if [ "$(wc -c < "$report")" -gt 60000 ]; then + echo "" + echo "_The report is truncated here; the full report is in the run's \`mcp-diff-report-$SERVER\` artifact._" + fi + else + echo "## \`$SERVER\`: MCP interface diff" + echo "" + echo "❌ The diff job produced no report; see the run's log." + fi + echo "" + echo "Updated by [this run]($RUN_URL) for \`$HEAD_SHA\`." + } > body.md + id=$(gh api --paginate "repos/$REPO/issues/$PR/comments" \ + --jq ".[] | select(.user.login == \"github-actions[bot]\" and (.body | startswith(\"$marker\"))) | .id" | head -n 1) + if [ -n "$id" ]; then + gh api -X PATCH "repos/$REPO/issues/comments/$id" -F body=@body.md > /dev/null + else + gh api "repos/$REPO/issues/$PR/comments" -F body=@body.md > /dev/null + fi diff --git a/.github/workflows/prepare-python-release.yml b/.github/workflows/prepare-python-release.yml index a9e5b6c469..78dbb4e873 100644 --- a/.github/workflows/prepare-python-release.yml +++ b/.github/workflows/prepare-python-release.yml @@ -112,7 +112,7 @@ jobs: echo "Generated by the **Prepare Python Release** workflow. Nothing is published until a maintainer publishes a GitHub Release." echo echo "> [!NOTE]" - echo "> A push made with the workflow token starts no CI, so the workflow dispatched the TypeScript, Python, DCO and interface diff workflows on this branch. Their results show on this PR as the \`TypeScript (dispatched)\`, \`Python (dispatched)\`, \`DCO (dispatched)\` and \`Interface diff (dispatched)\` statuses. To run them again: \`gh workflow run python.yml --ref $BRANCH\` (and \`typescript.yml\`, \`dco.yml\`, \`everything-mcp-diff.yml\`)." + echo "> A push made with the workflow token starts no CI, so the workflow dispatched the TypeScript, Python, DCO and interface diff workflows on this branch. Their results show on this PR as the \`TypeScript (dispatched)\`, \`Python (dispatched)\`, \`DCO (dispatched)\` and \`Interface diff (dispatched)\` statuses. To run them again: \`gh workflow run python.yml --ref $BRANCH\` (and \`typescript.yml\`, \`dco.yml\`, \`mcp-interface-diff.yml\`)." } > "$RUNNER_TEMP/pr-body.md" # A second run on the same day force-updates the branch, and may # stamp a different set of packages; the open PR's body is rewritten @@ -132,6 +132,6 @@ jobs: # The push above starts no workflow (see the header), so CI is # dispatched on the branch explicitly, after a first run and a rerun # alike. - for workflow in typescript.yml python.yml dco.yml everything-mcp-diff.yml; do + for workflow in typescript.yml python.yml dco.yml mcp-interface-diff.yml; do gh workflow run "$workflow" --ref "$BRANCH" done diff --git a/.github/workflows/version-packages.yml b/.github/workflows/version-packages.yml index 937ec2daa0..4805685692 100644 --- a/.github/workflows/version-packages.yml +++ b/.github/workflows/version-packages.yml @@ -91,6 +91,6 @@ jobs: PR: ${{ steps.changesets.outputs.pr-number }} run: | BRANCH=$(gh pr view "$PR" --json headRefName --jq .headRefName) - for workflow in typescript.yml python.yml dco.yml everything-mcp-diff.yml; do + for workflow in typescript.yml python.yml dco.yml mcp-interface-diff.yml; do gh workflow run "$workflow" --ref "$BRANCH" done diff --git a/AGENTS.md b/AGENTS.md index c090e1a5d0..c214179916 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -63,8 +63,7 @@ servers/ │ overview of how the rules, skills, gates and sweeps fit together ├── .github/workflows/ typescript.yml, python.yml (per-package CI), release.yml (publishes on a GitHub Release), │ version-packages.yml (the changesets PR), prepare-python-release.yml (the CalVer PR), -│ everything-mcp-diff.yml (each changed server's interface diff on PRs), -│ mcp-interface-diff.yml (a dispatch-only placeholder for that file's new name, #5463), +│ mcp-interface-diff.yml (each changed server's interface diff on PRs), │ main-source.yml (a PR into main must bring nothing that is not on v2/main), │ and the scheduled sweeps that file issues: dependency-refresh.yml, dependabot-alerts.yml, sdk-watch.yml ├── .github/ISSUE_TEMPLATE/ Bug and feature issue forms; config.yml routes security and new servers away diff --git a/RELEASING.md b/RELEASING.md index c4d16eff93..09dcb783af 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -39,7 +39,7 @@ node scripts/prepare-python-release.mjs # prints one "name: old -> new" line ### PRs opened by these workflows > [!NOTE] -> Both workflows push their PR's branch with the workflow token, and a push made with that token starts no workflow, so each one then dispatches the TypeScript, Python, DCO and MCP interface diff workflows on that branch (`workflow_dispatch` is the one event the token can start). A PR does not list dispatched checks, so each dispatched run also reports itself on the PR's head commit as a status: `TypeScript (dispatched)`, `Python (dispatched)`, `DCO (dispatched)` and `Interface diff (dispatched)`; wait for them to pass before merging. Closing and reopening the PR does not start the CI workflows: that fires `pull_request`, and those run on `push`. The token's `pull_request` events do not run DCO or the diff either: GitHub holds those runs as `action_required` (#5173), so the PR may also list them as pending or failed with no jobs; the `(dispatched)` statuses are the results. To run one again by hand: `gh workflow run typescript.yml --ref ` (or `python.yml`, `dco.yml`, `everything-mcp-diff.yml`). The Version Packages PR's body is rewritten on every push to `v2/main`, so it is linked to the release issue with `addCloseIssueReferences` (which lives outside the body), carries a `Part of #N` comment as its textual record, and gets `Part of #N` as its body's first line only immediately before it is merged. The Prepare Python Release PR keeps its `Closes #N` line and is linked to the release issue with `addCloseIssueReferences` too, as every PR into `v2/main` is. The repository setting **Settings → Actions → General → Allow GitHub Actions to create and approve pull requests** must be on, or the workflows fail at the step that opens the PR. +> Both workflows push their PR's branch with the workflow token, and a push made with that token starts no workflow, so each one then dispatches the TypeScript, Python, DCO and MCP interface diff workflows on that branch (`workflow_dispatch` is the one event the token can start). A PR does not list dispatched checks, so each dispatched run also reports itself on the PR's head commit as a status: `TypeScript (dispatched)`, `Python (dispatched)`, `DCO (dispatched)` and `Interface diff (dispatched)`; wait for them to pass before merging. Closing and reopening the PR does not start the CI workflows: that fires `pull_request`, and those run on `push`. The token's `pull_request` events do not run DCO or the diff either: GitHub holds those runs as `action_required` (#5173), so the PR may also list them as pending or failed with no jobs; the `(dispatched)` statuses are the results. To run one again by hand: `gh workflow run typescript.yml --ref ` (or `python.yml`, `dco.yml`, `mcp-interface-diff.yml`). The Version Packages PR's body is rewritten on every push to `v2/main`, so it is linked to the release issue with `addCloseIssueReferences` (which lives outside the body), carries a `Part of #N` comment as its textual record, and gets `Part of #N` as its body's first line only immediately before it is merged. The Prepare Python Release PR keeps its `Closes #N` line and is linked to the release issue with `addCloseIssueReferences` too, as every PR into `v2/main` is. The repository setting **Settings → Actions → General → Allow GitHub Actions to create and approve pull requests** must be on, or the workflows fail at the step that opens the PR. ## How publishing works diff --git a/docs/quality-gate.md b/docs/quality-gate.md index 9dcee6551c..2e725caefc 100644 --- a/docs/quality-gate.md +++ b/docs/quality-gate.md @@ -13,7 +13,7 @@ out; everything else points here. | --- | --- | --- | --- | | Inner loop | `npm run validate -w src/`, `npm run validate:py -- ` | Your machine | While iterating on one server | | Pre-push gate | `npm run local:gate` | Your machine, under a lease | Before every push | -| CI | `.github/workflows/typescript.yml`, `python.yml`, `everything-mcp-diff.yml`; `dco.yml`; `main-source.yml` | GitHub, on every push and pull request (`everything-mcp-diff.yml` diffs only the servers the change touches); `dco.yml` on pull requests only; `main-source.yml` on pull requests into `main` only, and not mirrored by a gate stage, since no local push targets `main` | Before merge | +| CI | `.github/workflows/typescript.yml`, `python.yml`, `mcp-interface-diff.yml`; `dco.yml`; `main-source.yml` | GitHub, on every push and pull request (`mcp-interface-diff.yml` diffs only the servers the change touches); `dco.yml` on pull requests only; `main-source.yml` on pull requests into `main` only, and not mirrored by a gate stage, since no local push targets `main` | Before merge | **`npm run local:gate` runs every check CI runs.** CI splits the same checks into parallel jobs on a fresh install; the gate runs them in sequence on your @@ -57,7 +57,7 @@ in this order, and the first failure stops the run. | 7 | `coverage:py` | Per Python server: `uv sync --locked`, then `uv run --frozen pytest --cov --cov-report=term-missing --cov-report=json`; then **every file** in `coverage.json` must reach **90% on lines and 90% on branches** | `python.yml` → **Coverage \** (one leg each) | | 8 | `verify:skills:cli` | `claude plugin validate` on `.claude/skills`, at the pinned CLI version | `typescript.yml` → **Root guards** | | 9 | `smoke` | Every server boots over each transport it implements and answers one tool call | `typescript.yml` → **Boot smoke** | -| 10 | `interface-diff` | For each server the change touches, its MCP interface (capabilities, tools, prompts, resources, resource templates) in this checkout's build, diffed against the same server built from the base. It fails only when a diff cannot run; a changed interface is reported, not failed | `everything-mcp-diff.yml` → **Choose the servers to diff**, then **Diff \** (one leg each, and a PR comment each) | +| 10 | `interface-diff` | For each server the change touches, its MCP interface (capabilities, tools, prompts, resources, resource templates) in this checkout's build, diffed against the same server built from the base. It fails only when a diff cannot run; a changed interface is reported, not failed | `mcp-interface-diff.yml` → **Choose the servers to diff**, then **Diff \** (one leg each, and a PR comment each) | Notes on the stages: diff --git a/scripts/interface-diff.mjs b/scripts/interface-diff.mjs index 4b21fd10f3..9624b0968a 100644 --- a/scripts/interface-diff.mjs +++ b/scripts/interface-diff.mjs @@ -24,7 +24,7 @@ // `scripts/lib/workflow-gate.test.mjs` derives that from the npm scripts a // workflow invokes. A check behind an action is invisible to it; a check // behind `npm run interface-diff` is enforced by it. CI -// (`everything-mcp-diff.yml`) and the gate run this same file. +// (`mcp-interface-diff.yml`) and the gate run this same file. // - The tool comes in as an exact-pinned root devDependency, so it is held // by `package-lock.json`'s integrity hash, the way every other npm // dependency here is, and no third-party action runs in CI at all. diff --git a/scripts/lib/interface-diff-servers.mjs b/scripts/lib/interface-diff-servers.mjs index 82596d7fde..a3abe13d51 100644 --- a/scripts/lib/interface-diff-servers.mjs +++ b/scripts/lib/interface-diff-servers.mjs @@ -1,7 +1,7 @@ // The servers the MCP interface diff covers, how each is started for it, and // which of them a change touches (#5428). // -// Two things live here, both shared by CI (`everything-mcp-diff.yml`) and the +// Two things live here, both shared by CI (`mcp-interface-diff.yml`) and the // pre-push gate through `scripts/interface-diff.mjs`, so the two always agree // on what to diff: // @@ -68,7 +68,7 @@ export const TOOLING_PATHS = [ "scripts/interface-diff.mjs", "scripts/lib/interface-diff-servers.mjs", "scripts/lib/win-shell-args.mjs", - ".github/workflows/everything-mcp-diff.yml", + ".github/workflows/mcp-interface-diff.yml", ]; /** Root files every TypeScript server's build reads. */ diff --git a/scripts/version-pr-ci.test.mjs b/scripts/version-pr-ci.test.mjs index 31bd4ed19c..c8667c0f25 100644 --- a/scripts/version-pr-ci.test.mjs +++ b/scripts/version-pr-ci.test.mjs @@ -4,7 +4,7 @@ // The Version Packages and Prepare Python Release workflows push their PR // branches with the workflow token, which starts no workflow (GitHub holds a // `pull_request` run as `action_required`), so they dispatch `typescript.yml`, -// `python.yml`, `dco.yml` and `everything-mcp-diff.yml` on the branch instead. A dispatched run's checks are left out of the +// `python.yml`, `dco.yml` and `mcp-interface-diff.yml` on the branch instead. A dispatched run's checks are left out of the // status rollup a pull request reads, so each dispatched workflow also mirrors // its run onto the commit as a status. Both version workflows run only from `v2/main`, so nothing // exercises this path before a release needs it; if any link here breaks, @@ -17,6 +17,7 @@ import { spawnSync } from "node:child_process"; import { chmodSync, mkdtempSync, + readdirSync, readFileSync, rmSync, writeFileSync, @@ -48,7 +49,7 @@ const CI = [ trigger: "pull_request", }, { - file: "everything-mcp-diff.yml", + file: "mcp-interface-diff.yml", context: "Interface diff (dispatched)", trigger: "pull_request", }, @@ -63,7 +64,7 @@ const VERSION_WORKFLOWS = [ "typescript.yml", "python.yml", "dco.yml", - "everything-mcp-diff.yml", + "mcp-interface-diff.yml", ], }, { @@ -73,7 +74,7 @@ const VERSION_WORKFLOWS = [ "typescript.yml", "python.yml", "dco.yml", - "everything-mcp-diff.yml", + "mcp-interface-diff.yml", ], }, ]; @@ -258,17 +259,34 @@ test("RELEASING.md names the statuses a version PR is merged on", () => { assert.doesNotMatch(releasing, /Close and reopen the PR to run CI/); }); -// #5463 (Step 1 of a staged rename): `mcp-interface-diff.yml` exists so the -// name is on `main` before #5527 (Step 2) points the version workflows at it. -// Until then it must not run beside the real diff on a push or a pull -// request, and nothing may dispatch it yet: the version workflows keep -// dispatching `everything-mcp-diff.yml` (pinned in VERSION_WORKFLOWS above). -test("mcp-interface-diff.yml is a dispatch-only placeholder until Step 2", () => { - const wf = workflow("mcp-interface-diff.yml"); - assert.deepEqual(Object.keys(wf.on), ["workflow_dispatch"]); - for (const { file } of VERSION_WORKFLOWS) +// #5527 (Step 2 of the rename staged in #5463): the interface diff lives in +// `mcp-interface-diff.yml`, and the old `everything-mcp-diff.yml` is gone. A +// leftover copy would run a second diff on every push and pull request, and a +// leftover reference would dispatch, or list the runs of, a workflow that no +// longer exists on `v2/main`: `gh workflow run` fails the version workflow's +// step, and a `gh run list` on a missing workflow reads as "no newer run". +test("the interface diff is mcp-interface-diff.yml, and the old name is gone", () => { + const dir = path.join(repoRoot, ".github/workflows"); + const files = readdirSync(dir); + assert.ok(!files.includes("everything-mcp-diff.yml"), "the old file"); + // Comment lines may name the old file (this workflow's header records the + // rename); nothing a runner executes may. + for (const file of files) { + const live = readFileSync(path.join(dir, file), "utf8") + .split("\n") + .filter((line) => !line.trimStart().startsWith("#")) + .join("\n"); assert.ok( - !read(`.github/workflows/${file}`).includes("mcp-interface-diff.yml"), - `${file} does not dispatch the placeholder yet`, + !live.includes("everything-mcp-diff.yml"), + `${file} names the old file`, ); + } + // The real diff, not the Step 1 placeholder: it runs on every event the + // old file did. + assert.deepEqual(Object.keys(workflow("mcp-interface-diff.yml").on).sort(), [ + "pull_request", + "push", + "release", + "workflow_dispatch", + ]); });