broswer-automation/TESTING_DIRECT_CONNECTION.md

Testing the New Direct Connection Architecture

This guide helps you test the new direct connection architecture where Cherry Studio and the Chrome extension connect directly to the remote server, bypassing the native server.

Architecture Overview

Old Flow (with Native Server)

Cherry Studio → Remote Server → Native Server → Chrome Extension

New Flow (Direct Connection)

Cherry Studio → Remote Server
Chrome Extension → Remote Server (direct WebSocket)

Prerequisites

1. Remote Server running on port 3001
2. Chrome Extension installed and loaded
3. Node.js for running test scripts

Step-by-Step Testing

1. Start the Remote Server

cd app/remote-server
npm run dev

The server should start on http://localhost:3001 with these endpoints:

• HTTP: http://localhost:3001/mcp (for Cherry Studio)
• WebSocket: ws://localhost:3001/chrome (for Chrome extension)

2. Load the Chrome Extension

1. Open Chrome and go to chrome://extensions/
2. Enable "Developer mode"
3. Click "Load unpacked" and select the app/chrome-extension directory
4. The extension should load and automatically attempt to connect to the remote server

3. Check Chrome Extension Connection

1. Click on the Chrome extension icon
2. Go to the "Remote Server" section
3. You should see:
   • ✅ Connected status
   • Connection time
   • Server URL: ws://localhost:3001/chrome

4. Run Automated Tests

# Install dependencies if needed
npm install node-fetch ws

# Run the test script
node test-direct-connection.js

This will test:

• Remote server health
• MCP tools list retrieval
• Chrome extension WebSocket connection
• Tool call execution

5. Test with Cherry Studio

1. Copy the configuration from the Chrome extension popup:
   • Click the extension icon
   • Go to "Remote Server" section
   • Copy the "Streamable HTTP" configuration
2. Add this configuration to Cherry Studio's MCP servers
3. Test browser automation tools like:
   • chrome_navigate
   • chrome_screenshot
   • get_windows_and_tabs

Expected Results

✅ Success Indicators

1. Remote Server Logs:

   Chrome extension WebSocket connection established
   MCP server connected to streaming transport
   

2. Chrome Extension Console:

   Connected to remote MCP server - direct connection established
   Chrome extension will receive tool calls directly from remote server
   

3. Tool Calls:

   • No 10-second timeout errors
   • Faster response times (< 5 seconds)
   • All browser automation tools working

❌ Troubleshooting

1. Chrome Extension Not Connecting:

   • Check if remote server is running on port 3001
   • Check browser console for WebSocket errors
   • Verify firewall settings

2. Tool Calls Failing:

   • Check Chrome extension permissions
   • Verify active tab exists
   • Check remote server logs for errors

3. Timeout Errors:

   • Ensure you're using the new architecture (not native server)
   • Check network connectivity
   • Verify WebSocket connection is stable

Performance Comparison

Before (Native Server)

• Tool call timeout: 10 seconds
• Average response time: 5-15 seconds
• Frequent timeout errors on complex operations

After (Direct Connection)

• Tool call timeout: 60 seconds
• Average response time: 1-5 seconds
• Rare timeout errors, better reliability

Configuration Examples

Cherry Studio MCP Configuration (Streamable HTTP)

{
  "mcpServers": {
    "chrome-mcp-remote-server": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "Remote Chrome MCP Server for browser automation (Streamable HTTP) - Direct Connection"
    }
  }
}

Chrome Extension Configuration

• Server URL: ws://localhost:3001/chrome
• Reconnect Interval: 5000ms
• Max Reconnect Attempts: 50

Debugging Tips

1. Enable Verbose Logging:

   • Chrome extension: Check browser console
   • Remote server: Check terminal output

2. Network Inspection:

   • Use browser DevTools to inspect WebSocket connections
   • Check for connection drops or errors

3. Tool Call Tracing:

   • Monitor remote server logs for tool call routing
   • Check Chrome extension logs for tool execution

Next Steps

Once testing is successful:

1. Update documentation to reflect the new architecture
2. Consider deprecating native server for Chrome extension communication
3. Monitor performance improvements in production use