refactor(sdk): centralize MCP config merge utilities

Move MCP config merge logic into sdk.mcp.merge and align project config
helpers with clearer naming and constants.

Co-authored-by: openhands <openhands@all-hands.dev>

Author: nehaaprasad

openhands-sdk/openhands/sdk/mcp/__init__.py

@@ -7,12 +7,14 @@
     MCPToolDefinition,
     MCPToolExecutor,
 )
+from openhands.sdk.mcp.merge import merge_mcp_configs
 from openhands.sdk.mcp.utils import (
     create_mcp_tools,
 )
 
 
 __all__ = [
+    "merge_mcp_configs",
     "MCPClient",
     "MCPToolDefinition",
     "MCPToolAction",

openhands-sdk/openhands/sdk/mcp/merge.py

@@ -0,0 +1,26 @@
+"""Merge MCP configuration dictionaries."""
+
+from typing import Any
+
+
+def merge_mcp_configs(
+    base: dict[str, Any] | None,
+    overlay: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Merge two MCP config dicts; overlay wins on key conflicts.
+
+    ``mcpServers`` entries are merged by server name; other top-level keys use
+    shallow overlay semantics (overlay wins).
+    """
+    match (base, overlay):
+        case (None, None):
+            return {}
+        case (None, _):
+            return dict(overlay)
+        case (_, None):
+            return dict(base)
+
+    result = {**base, **overlay}
+    if "mcpServers" in base and "mcpServers" in overlay:
+        result["mcpServers"] = {**base["mcpServers"], **overlay["mcpServers"]}
+    return result

openhands-sdk/openhands/sdk/mcp/project_config.py

@@ -1,34 +1,40 @@
 """Project-level .mcp.json discovery and loading."""
 
-from __future__ import annotations
-
 from pathlib import Path
-from typing import Any
+from typing import Any, Final
 
 from openhands.sdk.context.skills.exceptions import SkillValidationError
 from openhands.sdk.context.skills.utils import load_mcp_config
 from openhands.sdk.logger import get_logger
 
 logger = get_logger(__name__)
 
+_PROJECT_MCP_CANDIDATES: Final[tuple[str, ...]] = (
+    ".openhands/.mcp.json",
+    ".mcp.json",
+)
+
 
-def find_project_mcp_json(project_dir: Path) -> Path | None:
+def _find_project_mcp_json(project_dir: Path) -> Path | None:
     """Return the first project MCP config path if present.
 
-    Preference order: ``.openhands/.mcp.json``, then root ``.mcp.json``.
+    Preference order follows ``_PROJECT_MCP_CANDIDATES``.
     """
-    for candidate in (
-        project_dir / ".openhands" / ".mcp.json",
-        project_dir / ".mcp.json",
-    ):
+    for rel in _PROJECT_MCP_CANDIDATES:
+        candidate = project_dir / rel
         if candidate.is_file():
             return candidate
     return None
 
 
-def try_load_project_mcp_config(project_dir: Path) -> dict[str, Any] | None:
-    """Load and validate project ``.mcp.json``, or return None if missing or invalid."""
-    path = find_project_mcp_json(project_dir)
+def load_project_mcp_config(project_dir: Path) -> dict[str, Any] | None:
+    """Load and validate project ``.mcp.json``.
+
+    Uses ``load_mcp_config`` from skills (variable expansion, ``MCPConfig``
+    validation). Returns ``None`` if no file exists, or if the file is
+    invalid (logged and ignored).
+    """
+    path = _find_project_mcp_json(project_dir)
     if path is None:
         return None
     try:

openhands-sdk/openhands/sdk/plugin/__init__.py

@@ -28,7 +28,8 @@
     update_plugin,
 )
 from openhands.sdk.plugin.loader import load_plugins
-from openhands.sdk.plugin.plugin import Plugin, merge_mcp_configs
+from openhands.sdk.mcp.merge import merge_mcp_configs
+from openhands.sdk.plugin.plugin import Plugin
 from openhands.sdk.plugin.source import (
     GitHubURLComponents,
     is_local_path,

openhands-sdk/openhands/sdk/plugin/plugin.py

@@ -22,6 +22,7 @@
     PluginAuthor,
     PluginManifest,
 )
+from openhands.sdk.mcp.merge import merge_mcp_configs
 from openhands.sdk.subagent.schema import AgentDefinition
 
 
@@ -30,32 +31,6 @@
 
 logger = get_logger(__name__)
 
-
-def merge_mcp_configs(
-    base: dict[str, Any] | None,
-    overlay: dict[str, Any] | None,
-) -> dict[str, Any]:
-    """Merge two MCP config dicts; overlay wins on key conflicts."""
-    if base is None and overlay is None:
-        return {}
-    if base is None:
-        return dict(overlay) if overlay is not None else {}
-    if overlay is None:
-        return dict(base)
-
-    result = dict(base)
-    if "mcpServers" in overlay:
-        existing_servers = result.get("mcpServers", {})
-        result["mcpServers"] = {
-            **existing_servers,
-            **overlay["mcpServers"],
-        }
-    for key, value in overlay.items():
-        if key != "mcpServers":
-            result[key] = value
-    return result
-
-
 # Directories to check for plugin manifest
 PLUGIN_MANIFEST_DIRS = [".plugin", ".claude-plugin"]
 PLUGIN_MANIFEST_FILE = "plugin.json"