Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/skills/release/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
432 changes: 0 additions & 432 deletions .github/workflows/everything-mcp-diff.yml

This file was deleted.

447 changes: 420 additions & 27 deletions .github/workflows/mcp-interface-diff.yml

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions .github/workflows/prepare-python-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
2 changes: 1 addition & 1 deletion .github/workflows/version-packages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
3 changes: 1 addition & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <branch>` (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 <branch>` (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

Expand Down
4 changes: 2 additions & 2 deletions docs/quality-gate.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ out; everything else points here.
| --- | --- | --- | --- |
| Inner loop | `npm run validate -w src/<server>`, `npm run validate:py -- <server>` | 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
Expand Down Expand Up @@ -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 \<server\>** (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 \<server\>** (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 \<server\>** (one leg each, and a PR comment each) |

Notes on the stages:

Expand Down
2 changes: 1 addition & 1 deletion scripts/interface-diff.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions scripts/lib/interface-diff-servers.mjs
Original file line number Diff line number Diff line change
@@ -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:
//
Expand Down Expand Up @@ -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. */
Expand Down
48 changes: 33 additions & 15 deletions scripts/version-pr-ci.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -17,6 +17,7 @@ import { spawnSync } from "node:child_process";
import {
chmodSync,
mkdtempSync,
readdirSync,
readFileSync,
rmSync,
writeFileSync,
Expand Down Expand Up @@ -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",
},
Expand All @@ -63,7 +64,7 @@ const VERSION_WORKFLOWS = [
"typescript.yml",
"python.yml",
"dco.yml",
"everything-mcp-diff.yml",
"mcp-interface-diff.yml",
],
},
{
Expand All @@ -73,7 +74,7 @@ const VERSION_WORKFLOWS = [
"typescript.yml",
"python.yml",
"dco.yml",
"everything-mcp-diff.yml",
"mcp-interface-diff.yml",
],
},
];
Expand Down Expand Up @@ -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",
]);
});
Loading