Old pinned versions can crash on startup (ModuleNotFoundError: unifi_mcp_shared.config) — fixed in current releases; broken historical wheels yanked

[sirkirby]

TL;DR

If you pin an old exact version of unifi-network-mcp (or unifi-protect-mcp / unifi-access-mcp) — or you're running a stale plugin install — startup can crash before any login/config step with:

ModuleNotFoundError: No module named 'unifi_mcp_shared.config'

Current releases are not affected. Fix: install with @latest, e.g. uvx unifi-network-mcp@latest, or update the plugin from the marketplace. We've also yanked the broken historical wheels so the failure is now self-explaining instead of cryptic.

What happened

Releases published before late April 2026 declared their dependency on unifi-mcp-shared (and unifi-core) without an upper version bound. On 2026-04-28, an internal refactor moved shared configuration code out of unifi-mcp-shared into a new unifi-core package — the unifi_mcp_shared.config submodule went away, replaced by unifi_core.config.

Because those older releases had no upper bound, uvx/pip resolves them against the newest unifi-mcp-shared, which no longer ships the config submodule the old code imports — so the import fails immediately. These releases worked when published; they were retroactively broken by the later refactor combined with an unpinned internal dependency.

Reported and tracked in #331.

The fix (already shipped)

Current releases pin their internal dependencies with proper bounds, so resolution can no longer drift:

• unifi-network-mcp → 0.19.2
• unifi-protect-mcp → 0.4.7
• unifi-access-mcp → 0.3.3

The Claude Code / marketplace plugins already point at these current versions.

Cleanup: historical wheels yanked

To stop old exact-pins from failing cryptically, we yanked the affected historical releases on PyPI (the ones with unbounded internal deps):

Package	Yanked range
unifi-network-mcp	0.7.0 – 0.14.12
unifi-protect-mcp	0.1.0 – 0.3.4
unifi-access-mcp	0.1.0 – 0.2.3

Yanking does not delete anything. Existing lockfiles that pin these exact versions still resolve (now with a warning), so nothing already working breaks; new and loose installs simply skip them. The yank message points you to @latest.

What you should do

• Recommended — install with @latest:

  uvx unifi-network-mcp@latest

• Using the plugin? Update / reinstall it from the marketplace to pick up the current pin.
• Pinning an exact version? Move to a current release, or drop the pin and use @latest.

If you still hit this after moving to a current version, please open an issue. Thanks to @CamelSprout for the detailed report in #331 that surfaced this.