fix: Port Discovery Protocol Mismatch

[dsarno]

Problem: The MCP server's port discovery was failing to connect to Unity Editor because of a protocol mismatch. The Python server's _try_probe_unity_mcp() method was sending a "ping" and expecting a JSON response with "message":"pong", but the Unity MCP bridge actually responds with a welcome message format: "WELCOME UNITY-MCP 1 FRAMING=1".

This caused the port discovery to fall back to the default port (6400) instead of finding the actual Unity port (6402), resulting in connection failures and the error "Could not connect to Unity. Ensure the Unity Editor and MCP Bridge are running."

Solution: Updated the port discovery probe to recognize both the Unity bridge's actual welcome message format and maintain backward compatibility with the original JSON pong format. The fix allows the MCP server to successfully discover and connect to Unity Editor on the correct port.

Impact: MCP tools now properly connect to Unity Editor, enabling all MCP functionality including asset management, console reading, and GameObject operations.

Summary by CodeRabbit

• Bug Fixes
  • Enhanced port validation during discovery to recognize multiple valid response formats, improving connection reliability and compatibility across different server configurations.

[coderabbitai]

Walkthrough

The port probe validation logic is updated to accept either the Unity MCP welcome message or the previous pong-based JSON response format. The docstring is updated to reflect this flexibility. No public API changes occur.

Changes

Cohort / File(s)	Change Summary
Port Discovery Validation MCPForUnity/UnityMcpServer~/src/port_discovery.py	Updated port probe to accept either Unity MCP welcome message or previous pong-based JSON response for backward compatibility; docstring updated accordingly

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Two messages, one port to find,
Forward, backward—no port left behind!
The probe now speaks both tongues with grace,
Welcome or pong, they all find their place! 🎯

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title "fix: Port Discovery Protocol Mismatch" directly and accurately describes the main change in the pull request. The changeset updates the port discovery probe to accept both the new Unity MCP welcome message format and the original JSON pong response, which is precisely what fixing a protocol mismatch entails. The title is concise, specific, and uses clear language without vague terms or unnecessary noise, making it immediately understandable to someone reviewing the repository history.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

MCPForUnity/UnityMcpServer~/src/port_discovery.py (2)

59-59: Consider clarifying that both formats are accepted.

The docstring mentions "expects Unity bridge welcome message" but the implementation accepts both the Unity bridge welcome format and the legacy pong JSON format for backward compatibility. Consider updating to reflect this dual acceptance.

Example:

-        Tries a short TCP connect, sends 'ping', expects Unity bridge welcome message.
+        Tries a short TCP connect, sends 'ping', expects Unity bridge welcome message or legacy pong JSON.

---

67-69: LGTM! Fix correctly addresses the protocol mismatch.

The updated logic properly recognizes both the Unity MCP bridge welcome message format (WELCOME UNITY-MCP) and the legacy pong JSON format, resolving the port discovery failure while maintaining backward compatibility. The substring matching approach is appropriate for this protocol handshake scenario.

Optional: Consider extracting the protocol strings as class constants for better maintainability:

class PortDiscovery:
    """Handles port discovery from Unity Bridge registry"""
    REGISTRY_FILE = "unity-mcp-port.json"
    DEFAULT_PORT = 6400
    CONNECT_TIMEOUT = 0.3
    UNITY_WELCOME_MSG = b"WELCOME UNITY-MCP"
    LEGACY_PONG_MSG = b'"message":"pong"'

Then use them in the check:

-                    if data and (b"WELCOME UNITY-MCP" in data or b'"message":"pong"' in data):
+                    if data and (PortDiscovery.UNITY_WELCOME_MSG in data or PortDiscovery.LEGACY_PONG_MSG in data):
                         return True

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 26eafbf and cd0e628.

📒 Files selected for processing (1)

• MCPForUnity/UnityMcpServer~/src/port_discovery.py (1 hunks)