feat!: v3 — drop server.json handling, validate manifest.json instead#5
Merged
Conversation
Stop treating `server.json` as an authoring surface. The MCP registry composes its `ServerDetail` discovery shape from each bundle's `manifest.json` server-side, so the per-bundle `server.json` file (and this action's validate-and-upload step for it) is no longer useful. BREAKING CHANGES: - Removed the "Validate & prepare server.json" step. Bundles that ship a `server.json` are no longer validated against it, and the file is no longer uploaded to the GitHub release. - Removed the `server-json-found` action output. Replaced with: - New "Validate manifest.json" step that checks required mcpb v0.4 fields (manifest_version, name, version, description, server) and, when set, validates the optional reverse-DNS name override at `manifest._meta["dev.mpak/registry"].name` against the upstream pattern `^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$`. README: - Replaced "MCP Registry Discovery (server.json)" with a new section describing how the registry composes ServerDetail from manifest + how to set a branded reverse-DNS name override. - Added a "Migration from server.json (v2 → v3)" section with the one-line `git rm server.json` upgrade path. - Bumped every example to `NimbleBrainInc/mcpb-pack@v3`. Bundles still on `@v2` keep working — the registry already ignores `server.json` files in releases.
QA review surfaced 6 actionable items + 2 info-only confirmations.
This commit addresses all 6:
## Validation runs first (W1)
The "Validate manifest.json" step moved to the very top of
`runs.steps`, before "Setup Node.js" and the vendor / pack steps. A
broken or missing manifest now fails in seconds instead of after a
30s+ Python `uv pip install --target deps/`. v3 is the right time
because manifest is mandatory now (v2's optional `server.json` step
sat in the same spot for path-of-least-resistance reasons).
## Reverse-DNS length bounds enforced (W3)
The upstream MCP registry's `name` constraint is the regex pattern
PLUS `minLength: 3` / `maxLength: 200`. The pattern check was already
there; the length bounds are now too. A 201-char override now fails
locally with a clear error instead of getting bounced by the registry
at announce time with a generic "invalid name" message.
## Defensive jq access for _meta (S3)
`._meta["dev.mpak/registry"].name` errors with a confusing jq message
if `_meta` is set but isn't an object (legal JSON, would happen with
a malformed manifest). Switched to
`.["_meta"]?["dev.mpak/registry"]?.name // empty` for a clean
"missing → empty" path.
## Test coverage for the validation logic (W2)
New `test-manifest-validation` matrix in `.github/workflows/test.yml`
exercises every rejection branch:
- missing-manifest, invalid-json
- missing-manifest-version, missing-name, missing-version,
missing-description, missing-server
- reverse-dns-no-slash, reverse-dns-too-short (< 3 chars),
reverse-dns-too-long (> 200 chars)
Each case sets up a failing manifest, runs the action with
`continue-on-error: true`, and asserts the step's outcome was
`failure`. A future regex/jq tweak that silently breaks validation
will turn the cell green and fail the matrix.
A sibling `test-manifest-validation-accepts-valid-reverse-dns` job
exercises the happy path for the override.
## Manifest version aligned to v0.4 throughout (S1 — adjusted)
QA flagged a comment vs. fixture mismatch (action.yml said "v0.4"
while test fixtures used `manifest_version: "0.3"`). Bumped the test
fixtures to v0.4 (the canonical authoring target — every shipped
bundle in mcp-servers/synapse-apps is on v0.4) and added the missing
`manifest_version` field to the README's Quick Start example.
v0.3 manifests still validate (required field set is identical) —
the action just stops example-by-example confusion about which
version is recommended.
## CLAUDE.md unstaled (S2)
Replaced the literal "v2" reference with a generic example
("vX.Y.Z bumps vX") so this doc doesn't go stale on every major bump.
## Skipped
- S4 (fleet rollout) — already done. The 32 per-bundle migration PRs
filed alongside this PR (same `feat/mcpb-pack-v3-migration` branch
across mcp-servers/* and synapse-apps/*) bump pins from `@v2` to
`@v3` and `git rm server.json`. Linked in mpak#100's PR body.
- S5 (`server-json-found` output safe to drop) — confirmed by
reviewer; output is gone in this PR.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Breaking changes
Compatibility
Migration for bundle authors (one-liner)
```bash
git rm server.json
Optional: add a branded reverse-DNS name override to manifest.json
"_meta": { "dev.mpak/registry": { "name": "com.example/your-server" } }
git add manifest.json
git commit -m "drop server.json (mcpb-pack@v3 composes registry metadata from manifest)"
```
Then bump the action ref in `.github/workflows/release.yml`:
```yaml
```
Test plan