> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metabind.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Package versioning
> Semantic versioning for Metabind packages, what each bump signals, and how Types pin to versions
A Metabind project's package is the immutable bundle of components published as a unit. Each publish produces a new version. This guide explains what version numbers mean and how Types stay stable across them.
## Semantic versioning
Metabind packages follow [semantic versioning](https://semver.org/) — `MAJOR.MINOR.PATCH`:
| Part | Bump when | Examples |
| ----- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| MAJOR | A breaking change — a property removed, renamed, or with a new required value | Removing a property; renaming `headline` to `title` |
| MINOR | An additive change — a new component, a new optional property, a new feature | New ProductCard component; new optional `subtitle` property |
| PATCH | A fix that doesn't change the schema — a typo, a layout polish, a logic correction | Adjusting padding; fixing a Data Tool's error message |
MCP App Studio suggests the right bump in the publish dialog based on a diff scan, but the suggestion can be overridden. When in doubt, prefer the higher bump — a misclassified breaking change as a minor version causes silent failures on connected hosts.
## How Types pin to versions
When a Type is published, it pins to the package version that was current at publish time:
After the next publish to `2.5.0`, the production endpoint serves the new package — but a Type unchanged in this publish still functionally references `2.4.0` semantics because its schema and rendering logic are identical in both. Versioning is per-package, not per-Type, so all Types from the same publish share the version.
This means: if a project publishes `2.5.0` and only changes one component, the other tools' behavior doesn't drift. Their bundled code is still byte-for-byte the same — the version label changed, the artifact didn't.
## What's pinned, what's not
| Pinned to package version | Editable independently |
| ------------------------------- | --------------------------------- |
| Component code | Tool descriptions and annotations |
| Property schemas | Project Instructions |
| Component allowlists | Data Tool secrets |
| BindJS layout primitives in use | Data Tool allowed domains |
The right column lists things that connected hosts pick up at request time, not bundle time. You can rotate a secret or sharpen a tool description without republishing.
## When to bump major
A new major version is a signal to consumers that they should re-test against your tools. Major bumps make sense when:
* A required property is removed or renamed.
* An enum value is dropped.
* A component is removed.
* The shape of a Data Tool's `output` changes incompatibly.
* A component's behavior changes in a way that AI prompts may need to adjust to (e.g., a card now expects a `caption` where before it inferred one from `title`).
If the change is genuinely new behavior, prefer adding a *new* component rather than mutating an existing one. `ProductCard` and `ProductCardV2` can coexist; the project palette decides which is in use.
## When minor is enough
Minor is the right call for additive changes:
* New components added to the project palette.
* New optional properties on existing components.
* New Types added to the project.
* Improvements that are backward-compatible by construction.
In practice, most publishes are minor. A long-lived project might sit at `15.4.0` after a year of incremental additions.
## When patch is enough
Patch is for changes that don't touch the schema or shape:
* Layout polish (padding, color, typography).
* Typo fixes in user-visible strings.
* Bug fixes inside Data Tool handlers.
* Performance improvements.
A publish that touches only patches can be promoted to production with low risk.
## Versions and connected hosts
Connected MCP hosts list tools and cache schemas. When a host reconnects after a publish:
* **Patch update:** schemas are byte-identical; the host's cache stays valid (no re-list needed in some hosts).
* **Minor update:** new tools/properties appear; existing ones unchanged. The host re-lists, picks up additions.
* **Major update:** existing tools have changed shape; the host's cached schemas are now wrong until it re-lists.
Because hosts re-list on most conversation starts anyway, the rollout is smooth in practice. The version label is mostly a signal to *humans* — your team, partners, customers — about the magnitude of the change.
## Looking up the current version
In MCP App Studio, the project header shows the currently published version next to the **Publish** button. Click it to see the full publish history.
For programmatic access, the production endpoint exposes the package version in its capabilities response — see [REST API: project info](/rest/projects/overview).
## Pre-release versions
MCP App Studio doesn't expose pre-release labels (`2.5.0-beta.1`) in MVP. Use draft for any pre-release exposure: connect a small group of users to the draft endpoint, gather feedback, then publish.
## Long-term versioning practices
A few patterns from teams that have shipped many versions:
* **Don't bump major casually.** A major bump asks every consumer to re-evaluate. Only do it when something has actually broken.
* **Group related changes into one publish.** Publishing 5 versions in an hour is noisy — group the small changes into one and bump.
* **Write changelog notes that mention impact.** "Renamed `headline` → `title`. AI prompts that referenced the old property name will need to be updated." beats "Renamed property."
* **Keep a public changelog if you have external consumers.** The publish notes are the input to that changelog.
## Related
The action that produces a new version.
Revert to a previously published version.
The component model packages bundle together.
Per-publish audit trail.