[MCP Registry] Version compatibility, pinning & upgrade safety

[TimothyZhang7]

Parent

Part of #6321 — MCP Server Registry

PRD Reference

docs/mcp-registry-prd.md — Section 5.2 (Version Compatibility & Upgrade Safety)

Why this matters

Without version management, hive mcp update can silently break agents. A server author renames a tool or changes its parameters, the user updates, and their agent starts failing with no explanation. Version pinning, dry-run diffs, and breaking-change warnings protect users from surprise breakage — which is especially critical for production deployments where agents run unattended. This directly targets G11: zero undetected tool-signature changes on upgrade.

Scope

Implement version management so server upgrades don't silently break agents.

Version tracking

• Manifest version (semver) for registry entry version (VC-1)
• Manifest mcp_protocol_version for MCP spec version (VC-1)
• hive block min_version / max_version for Hive compatibility (VC-2)
• installed.json records resolved_package_version (actual pip/npm version) (VC-4)

Install with version pinning

• hive mcp install <name> installs latest by default (VC-3)
• hive mcp install <name> --version X pins a specific version (VC-3)
• installed.json records pinned: true when version is specified (FR-25)

Safe updates

• hive mcp update <name> compares old and new tool lists (VC-5)
• Warns if tools were removed or signatures changed
• hive mcp update --dry-run shows what would change without applying (VC-8)
• Tool names and parameter schemas are a compatibility contract; breaking changes require major version bump (VC-9)

Agent version pinning

• mcp_registry.json supports "versions": {"jira": "1.2.0"} (VC-6)
• If pinned version unavailable, agent logs error with rollback instructions (VC-7)

Files to modify

• core/framework/runner/mcp_registry.py — version logic in install/update
• core/framework/runner/mcp_registry_cli.py — --version and --dry-run flags

Acceptance criteria

• install --version X pins the specified version
• update detects and warns about removed/changed tools
• update --dry-run shows diff without applying
• Agent-level version pins are respected
• Pinned version unavailable produces clear error with instructions
• Zero undetected tool-signature changes on upgrade (G11)

Requirements

ID	Requirement
VC-1 – VC-9	Full version compatibility requirements

[Ttian18]

Hi @TimothyZhang7, I'd love to work on this one!

I've read through the PRD §5.2 and the VC-1 through VC-9 requirements. Here's my proposed approach:

Version tracking: Extend the manifest schema to include version (semver), mcp_protocol_version, and hive.min_version/max_version. Store resolved_package_version and pinned flag in installed.json on install.

Install with pinning: Add --version flag to hive mcp install. When specified, record pinned: true in installed.json so update skips it unless explicitly requested.

Safe updates: For hive mcp update, diff old vs new tool lists (names + parameter schemas) before applying. Warn on removed tools or changed signatures. Implement --dry-run that shows the diff and exits without writing. Breaking changes (removed tools, changed params) would surface a clear warning requiring --force to proceed.

Agent-level pins: Read versions from mcp_registry.json at agent load time. If a pinned version isn't available locally, log an actionable error with rollback instructions.

I'll add unit tests for each scenario (pin, unpin, breaking change detection, dry-run output). Let me know if you'd like me to start!