Skip to content

feat!: v3 — drop server.json handling, validate manifest.json instead#5

Merged
mgoldsborough merged 2 commits into
mainfrom
feat/v3-drop-server-json
May 9, 2026
Merged

feat!: v3 — drop server.json handling, validate manifest.json instead#5
mgoldsborough merged 2 commits into
mainfrom
feat/v3-drop-server-json

Conversation

@mgoldsborough
Copy link
Copy Markdown
Contributor

Summary

  • Stop treating `server.json` as an authoring surface. The mpak 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.
  • Replace the old "Validate & prepare server.json" step with a new "Validate manifest.json" step that checks the mcpb v0.4 required fields and, when present, validates the optional reverse-DNS name override at `manifest._meta["dev.mpak/registry"].name`.
  • Cut as v3 so bundles upgrade explicitly.

Breaking changes

  • Removed the `Validate & prepare server.json` step.
  • Removed the `server-json-found` action output.
  • The action no longer uploads `server.json` to the GitHub release. Bundles that still ship a `server.json` file in their repo are unaffected at build time but should drop it as part of upgrading to `@v3`.

Compatibility

  • Bundles on `@v2` keep working — the registry already ignores `server.json` files in releases (the `ServerDetail` it serves is composed from `manifest.json`).
  • New bundles or version bumps should adopt `@v3` at their own pace.

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

  • uses: NimbleBrainInc/mcpb-pack@v3
    ```

Test plan

  • Workflow YAML syntactically valid (no `server.json` step references remain in `action.yml`)
  • README examples bumped to `@v3` (10 occurrences updated, 0 `@v2` remaining)
  • Manifest validation step rejects: missing `manifest.json`, invalid JSON, missing required fields (`manifest_version`, `name`, `version`, `description`, `server`), malformed reverse-DNS override
  • Cut `v3.0.0` tag after merge to fire the release workflow + update the `v3` major tag

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.
@mgoldsborough mgoldsborough added the qa-reviewed QA review completed with no critical issues label May 9, 2026
@mgoldsborough mgoldsborough merged commit e74c827 into main May 9, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

qa-reviewed QA review completed with no critical issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant