ci(publish): gate PyPI on server.json registry-schema validation

[cmeans-claude-dev]

Summary

Closes #44.

Adds a validate-server-json job to publish.yml that runs before publish-pypi on every release tag, mirroring the same check that already runs on every PR via ci.yml.

Why

Without this gate, a malformed server.json (new required field in a future registry schema, type change, etc.) would PyPI-publish cleanly and then fail at the registry leg — leaving a discoverable PyPI release that isn't in the MCP registry, with no way to roll back PyPI short of yanking. Re-running the failed registry job can't fix that asymmetry.

v0.5.1 hit the registry-leg-fails-after-PyPI scenario for a different reason (mcp-publisher OIDC audience mismatch, fixed in #79). The failure mode isn't theoretical — it just hasn't yet fired for a schema reason.

What changed

• New validate-server-json job in publish.yml runs ./mcp-publisher validate server.json using the same ./.github/actions/install-mcp-publisher composite that publish-registry uses. Validating publisher version always matches publishing publisher version.
• publish-pypi now lists needs: [build, validate-server-json] so a validation failure stops the entire pipeline before any external side-effect.
• validate-server-json runs in parallel with build — no dep on it — so the gate adds ~10s to the critical path, not a serial round-trip.

Why not the optional manifest artifact

The publish-manifest artifact (record mcp-publisher/uv/Python versions for CI-PR vs release-tag reconciliation) is named as optional in #44. Deferring — it's a debugging aid that's only useful if a CI-PR / release-tag mismatch does fire, and is trivially additive later when there's a concrete failure to investigate.

Test plan

• python -c "import yaml; yaml.safe_load(open('.github/workflows/publish.yml'))" parses
• CI green on this PR (lint/typecheck/test/version-sync/validate-server-json/vdsm)
• After merge: next release tag (v0.5.3 or whichever) shows the new validate-server-json job in the publish.yml run, gating publish-pypi
• Negative test (informal): if you intentionally corrupt server.json on a branch and tag-push, the publish workflow stops at validate-server-json with no PyPI side-effect — won't actually run this since it requires breaking server.json on main; the validate step is the same ./mcp-publisher validate invocation that ci.yml exercises on every PR, so it's already proven to fail loudly on schema errors

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

LGTM

[cmeans]

QA Round 1 — PASS (no findings)

CI-only change on head 3153fdb. 2 files / +23 / -1. Branch is on post-#87 main (merge-base 4e22e35).

Verified

Workflow change (publish.yml):

• New validate-server-json job runs ./mcp-publisher validate server.json using the same ./.github/actions/install-mcp-publisher composite as publish-registry — so the validating publisher version is exact-pinned to the publishing publisher version. Schema-drift detection isn't subject to a CI-vs-release version mismatch.
• publish-pypi now lists needs: [build, validate-server-json] — validation must succeed before any PyPI side-effect; since publish-registry and github-release both needs: publish-pypi, the gate transitively blocks the entire downstream pipeline.
• validate-server-json and build are dep-free, so they run in parallel — gate adds ~10s to the critical path, not a serial round-trip.
• yaml.safe_load parses cleanly. Job graph confirmed via Python: build (no deps) || validate-server-json (no deps) → publish-pypi (needs both) → publish-registry (needs publish-pypi) || github-release (needs publish-pypi).

Same-validator-as-PRs invariant:

• ci.yml:40 runs ./mcp-publisher validate server.json on every PR. The new release-time job runs the byte-identical command via the byte-identical composite action. So a PR that passes CI cannot regress the schema validation at tag-time unless mcp-publisher's pinned version moves between merge and tag-push (the exact scenario #44's body called out as the residual risk).
• Current branch's validate-server-json (in CI) is SUCCESS on 3153fdb, confirming the validation works on the current server.json.

Issue #44 scope:

• AC 1 (validate-server-json before publish-pypi using same pinned mcp-publisher): ✓
• AC 2 (validation failure blocks all jobs): ✓ via the needs: chain
• AC 3 (optional publish-manifest artifact): explicitly deferred in PR body. Issue marks it "Optional"; deferral rationale (debug aid only useful when a mismatch fires; trivially additive later) is honest.

CI

12/12 required checks green incl. vdsm integration tests SUCCESS on this exact head. validate-server-json green confirms the validation logic is functional today on server.json.

Local sanity (workflow-only PR, no code paths touched)

• uv run pytest → 599 passed, 112 deselected, 96.25% coverage. Post-#87 baseline preserved exactly.
• uv run ruff check, ruff format --check, mypy src/ all clean.

CHANGELOG

New ### Added entry under ## Unreleased, correctly placed above the existing #87 entry. Honest framing: notes that v0.5.1 hit the registry-leg-fails-after-PyPI scenario for a different reason (#79's audience mismatch), so the failure mode isn't theoretical.

PR-body checkboxes

Boxes 1–2 flipped (yaml parse + CI green). Box 3 is post-merge (next release-tag run will exercise the new gate). Box 4 is the informal negative test that the PR body itself rules out running on main — accepted as documented.

Disposition

Ready for QA Signoff applied as the final act. With this in, #51's MEDIUM block is fully closed (#41 via #87, #44 via #89). Roadmap state moves to LOW/docs/chore (#42, #43, #45, #46), architectural ADR (#47), post-baggage features (#48–50), and the newer follow-ups (#25, #75, #76).

[cmeans]

Applying Ready for QA Signoff — clean CI-only change. New validate-server-json job uses same install-mcp-publisher composite as publish-registry (publisher-version-pinned consistency); publish-pypi needs both build+validate-server-json so a schema failure stops the pipeline before any external side-effect; downstream publish-registry / github-release transitively gated. yaml parses, current ci.yml validate-server-json job is already SUCCESS on 3153fdb confirming the validation works on today's server.json. Local 599/96.25% (post-#87 baseline preserved), ruff/format/mypy clean, CI 12/12 green incl. vdsm. Boxes 1-2 flipped; #3 post-merge, #4 informal-only per PR body. Closes #44 — fully clears #51's MEDIUM block.