runtime-bridge-conflict-resolver

name	runtime-bridge-conflict-resolver
description	Detect and resolve MCP bridge conflicts (Path 1 Lab MCP + Path 2 ahujasid running together, port 9876 collisions, host mismatch). Use when readiness checker reports inconsistent signals.

runtime-bridge-conflict-resolver

Purpose

Resolve the single-bridge constraint when more than one MCP runtime path is configured against the same Blender instance (or when ports collide). BlendOps documents that Blender accepts only one MCP bridge session per instance — but both Path 1 (Blender Lab MCP bpype/blender_mcp) and Path 2 (community ahujasid/blender-mcp) commonly bind to a localhost:9876 range. If both are configured concurrently, the second connection silently fails and downstream planners get inconsistent signals.

This skill diagnoses the conflict, names the cheapest resolution, and hands off to the readiness checker for re-verification.

This skill is BlendOps-specific (no direct analog in Anthropic Superpowers or BMad), driven by the Single-bridge constraint described in docs/runtime-stack-strategy.md.

Quick start

• list every active / configured bridge for the target Blender session
• check for port collision (commonly localhost:9876)
• identify which path is intended; which is residual
• propose the cheapest disable / port-isolation step
• hand off to official-runtime-readiness-checker to re-verify

When to use

• official-runtime-readiness-checker reports inconsistent signals (e.g. "MCP host says connected" but tool calls return wrong tool surface)
• you see Lab MCP add-on AND ahujasid/blender-mcp addon.py both installed in Blender
• two MCP clients are pointing at the same Blender (e.g. Claude Desktop with Connector + Cursor with manual MCP)
• a recipe smoke test fails despite a recent successful read-only smoke
• log shows port collision around localhost:9876

When not to use

• no readiness signal yet (run readiness checker first)
• only one path is configured and working (no conflict to resolve)
• the user explicitly wants both paths configured for separate Blender instances on different ports (note: still requires explicit port isolation)

Trigger phrases

• "tool surface looks wrong"
• "smoke test passed yesterday but recipe fails today"
• "Lab MCP and ahujasid both installed"
• "Claude Desktop and Cursor both pointing at Blender"
• "port 9876 already in use"
• "single-bridge constraint violation"

Prerequisites / readiness

• list of configured MCP servers per client (mcpServers in client config files)
• list of installed Blender add-ons inside Blender (Lab MCP add-on + ahujasid/blender-mcp addon.py)
• log / port output if available (netstat -ano | grep 9876 or equivalent)
• no Blender execution required from this skill

Input schema

Required inputs

• target Blender instance (path to blender binary or "the running session")
• list of MCP clients that are currently configured to talk to that Blender
• list of Blender-side add-ons currently enabled (Lab MCP / ahujasid/blender-mcp addon.py)

Optional inputs

• recent readiness checker report
• recent smoke test record
• port usage output

Assumptions to confirm

• the operator can disable one path or change ports
• only one path is intended at a time (or explicit port isolation)
• runtime status is one of Not Run / Attempted / Blocked

Output schema

Primary output

• conflict diagnosis: which paths are present, which is intended, what's residual
• cheapest resolution step (disable add-on / unregister MCP client / change port)
• post-resolution verification handoff

Secondary output

• per-bridge state matrix
• explicit "do not run X concurrently with Y" reminders

Evidence / caveat output

• runtime status: unchanged by this skill (only readiness checker can update)
• artifact status: unchanged
• explicit note that resolution requires operator action; this skill plans, doesn't execute

Required laws

• ../../laws/official-runtime-only.md
• ../../laws/evidence-before-done.md
• ../../laws/no-arbitrary-python-interface.md
• ../../laws/non-blender-user-language.md

Official runtime boundary

This skill does not disable add-ons, edit MCP client configs, change ports, kill processes, or run Blender. It diagnoses and proposes a resolution. The operator (or another skill) executes.

Operating procedure

1. Build the bridge state matrix:
   • For each MCP client (Claude Desktop with Connector, Claude Desktop manual MCP, Claude Code, Cursor, Codex, OpenCode, Cline, Continue, Zed, goose, LM Studio, Open WebUI, Ollama, etc.) record whether it is currently registered for this Blender.
   • For Blender-side: record whether Lab MCP add-on is enabled, and whether ahujasid/blender-mcp addon.py is enabled.
   • Record ports if known.
2. Identify the intended path from the user / brief / readiness checker.
3. Identify residual / unintended bridges:
   • Both Path 1 add-on AND Path 2 addon.py enabled → conflict.
   • Two MCP clients pointing at the same Blender → conflict.
   • Two servers binding the same port → conflict.
4. Propose the cheapest fix:
   • If only Path 1 intended: disable ahujasid/blender-mcp addon.py inside Blender; unregister uvx blender-mcp from MCP client config; restart MCP client.
   • If only Path 2 intended: disable Lab MCP add-on inside Blender; if Anthropic Connector is on, also disable that toggle; restart Claude Desktop.
   • If both wanted on different Blender instances: explicit port isolation, separate Blender processes, separate workspaces.
5. State explicit do-not reminders for the operator.
6. Hand off to official-runtime-readiness-checker to re-verify the single intended path is the only active one.

Decision tree

• both Path 1 and Path 2 add-ons enabled → ask user which is intended; disable the other.
• two MCP clients configured for the same Blender → ask which is the working session; unregister the other.
• two servers on localhost:9876 → change one to a different port (e.g. 9877) AND update its MCP client config to match.
• Anthropic Connector toggle ON + manual mcpServers JSON entry for Lab MCP → these are both Path 1 host options targeting the same Lab stack. Pick one host option per session (per runtime-stack-strategy.md).
• everything looks clean but smoke still fails → route to blender-troubleshooting.

Playbooks

• Playbook A: "Path 1 + Path 2 both installed" — disable the unintended path's Blender-side add-on first, then unregister its MCP server.
• Playbook B: "Two MCP clients" — pick one client per Blender session; unregister the other from this Blender (its config can stay for other Blender instances).
• Playbook C: "Port collision" — change one server's port; update that client's config to match.
• Playbook D: "Path 1 host (a) Anthropic Connector + Path 1 host (b) manual MCP both ON" — pick one host per session per docs/runtime-stack-strategy.md.

Mode handling

Text-only mode

• diagnosis only, no execution
• runtime status unchanged
• artifact status unchanged

Runtime-ready mode

• diagnose + propose + hand off; this skill never executes the resolution

Blocked runtime mode

• still useful: even when blocked, the conflict can be diagnosed from configs
• mark resolution proposal as text-only

Validation checklist

• bridge state matrix built (all clients + both Blender-side add-ons)
• intended path identified explicitly
• residual / unintended bridges named
• port collisions checked (or marked unknown if no log access)
• cheapest resolution proposed
• explicit "do-not" reminders for the operator
• no execution claimed by this skill
• handoff to readiness checker named

Pass / Warn / Fail rubric

Category	Pass	Warn	Fail
State matrix	Complete	Partial with note	Missing
Intended path	Explicit	Inferred without confirmation	Not identified
Residual identified	Named with reason	Named without reason	Not named
Port check	Done or marked unknown	Done partially	Skipped
Resolution proposal	Cheapest step + rationale	Step without rationale	None
Execution claim	None	None	Claimed disabled / changed config from this skill

Failure handling

• operator can't access Blender's add-on list: ask them to check Edit → Preferences → Add-ons; meanwhile mark Blender-side state Unknown.
• operator can't access MCP client configs: ask for paths (Settings → Developer → Edit Config in Claude Desktop, etc.); meanwhile mark client-side state Unknown.
• operator unsure which path is intended: route to readiness checker to gather one passing read-only smoke first.

Troubleshooting

• if matrix says only Path 1 active but tool surface is Path 2 (get_scene_info) → readiness signal is wrong; re-run smoke with explicit tool name list before any resolution.
• if matrix is clean but smoke still fails → route to blender-troubleshooting.

Best practices

• diagnose before proposing
• explicit do-not reminders prevent re-introduction
• hand off to readiness checker; never claim resolution worked from this skill

Good examples

• "Bridge matrix: Lab MCP add-on enabled (Blender), ahujasid/blender-mcp addon.py also enabled (Blender), Claude Desktop has Anthropic Connector ON, Claude Desktop also has mcpServers.blender = uvx blender-mcp. Conflict: 2 Blender-side bridges + 2 host options (a) and (b) both targeting Path 1 + Path 2 mixed. Intended (per brief): Path 1 host (a) Anthropic Connector. Cheapest fix: disable ahujasid/blender-mcp addon.py inside Blender; remove the manual mcpServers.blender entry; restart Claude Desktop. Do-not: keep both Blender-side add-ons enabled at once. Handoff: official-runtime-readiness-checker."

Bad examples

• "Both look configured, just try restarting" (no matrix, no intended path, no resolution rationale, no do-not reminder, no handoff).

User-facing response template

• Bridge state matrix (markdown table)
• Intended path (explicit)
• Conflicts found
• Cheapest resolution step
• Do-not reminders
• Handoff: official-runtime-readiness-checker

Anti-patterns

• proposing a fix without building the matrix
• executing the fix from this skill
• ignoring port collisions
• treating Anthropic Connector and manual MCP as if they were independent paths (they are both Path 1 host options; pick one)

Cross-skill handoff

• After resolution proposal: official-runtime-readiness-checker to re-verify
• If matrix is clean but smoke still fails: blender-troubleshooting
• If user wants to change paths entirely: official-runtime-setup-guide

Non-goals

• executing the resolution (operator does that)
• running Blender
• editing MCP client configs from this skill
• replacing readiness checker

References

• BlendOps doc: ../../docs/runtime-stack-strategy.md (Single-bridge constraint)
• BlendOps doc: ../../docs/external-runtime-setup.md
• BlendOps doc: ../../docs/unofficial-runtime-bridges.md
• Skill system: ../../docs/skill-system.md