Fix malformed mcp.json error handling in ACP

[neubig]

Description

This PR fixes issue #151 where malformed mcp.json configuration file errors were silently swallowed in ACP (Agent Client Protocol), providing no feedback to users.

Problem

When users had a malformed mcp.json file:

• CLI TUI: ✅ Displayed clear error messages
• ACP Server: ❌ Silently returned empty config, no error shown

This created a poor user experience for editor/IDE users (VS Code, Cursor, etc.) who wouldn't know why their MCP servers weren't loading.

Solution

Changes Made

1. Created custom exception (MCPConfigurationError in store.py)

   • Provides clear semantic meaning for MCP configuration errors
   • Allows specific error handling in ACP layer

2. Updated AgentStore.load_mcp_configuration() (in store.py)

   • Now raises MCPConfigurationError instead of silently returning {}
   • Preserves error details for debugging
   • Only returns {} when file doesn't exist (valid case)

3. Updated agent.py::_setup_acp_conversation()

   • Catches MCPConfigurationError
   • Converts to ACP RequestError.invalid_params with helpful message
   • Provides clear error details including:
     • Reason: "Invalid MCP configuration file"
     • Details: Validation error message
     • Help: Path to mcp.json file and suggestion to check syntax

4. Added comprehensive test coverage (in test_agent.py)

   • Unit test: Verifies error conversion with mocking
   • Integration test: Tests end-to-end error handling flow
   • Both tests verify error code (-32602) and helpful error messages

User Impact

Before ❌

User creates malformed mcp.json
  ↓
Opens editor and starts session via ACP
  ↓
Session starts normally
  ↓
MCP servers don't work
  ↓
❌ No error message anywhere
  ↓
User doesn't know what's wrong

After ✅

User creates malformed mcp.json
  ↓
Opens editor and starts session via ACP
  ↓
Gets clear error: "Invalid MCP configuration file: ..."
  ↓
Can fix the JSON syntax
  ↓
✅ Problem solved

Testing

All tests pass:

• ✅ Existing MCP config validation tests (test_mcp_config_validation.py)
• ✅ New ACP error handling tests (test_agent.py)
• ✅ All ACP tests (65 tests total)
• ✅ Linting with ruff, pycodestyle, and pyright

Test Coverage

# Unit test - verifies error conversion
async def test_new_session_with_malformed_mcp_json(...)

# Integration test - verifies end-to-end flow  
async def test_new_session_with_malformed_mcp_json_integration(...)

Example Error Message

When a user has malformed mcp.json, they now see:

{
  "code": -32602,
  "message": "Invalid params",
  "data": {
    "reason": "Invalid MCP configuration file",
    "details": "Invalid JSON: trailing characters at line 20 column 1",
    "help": "Please check ~/.openhands/mcp.json for JSON syntax errors"
  }
}

Benefits

• ✅ Consistent error handling between CLI TUI and ACP server
• ✅ Clear error messages for editor/IDE users
• ✅ Users can quickly identify and fix JSON syntax errors
• ✅ Reduced support burden and user frustration
• ✅ Better alignment with ACP error reporting patterns

Checklist

• Added appropriate test coverage
• All tests pass
• Linting passes (ruff, pycodestyle, pyright)
• Error messages are clear and helpful
• Follows ACP error reporting conventions
• Maintains backward compatibility

Fixes #151

@neubig can click here to continue refining the PR

---

🚀 Try this PR

uvx --python 3.12 git+https://github.com/OpenHands/OpenHands-CLI.git@openhands/fix-mcp-config-error-handling

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands_cli/acp_impl
agent.py	174	31	82%	167, 177, 293–295, 311, 334, 355–358, 362–369, 388, 392, 395, 456–458, 488, 490, 492–493, 495, 498
openhands_cli/tui/settings
store.py	67	11	83%	51, 53–54, 56, 80–81, 107, 120, 147–148, 151
TOTAL	1569	259	83%