Major refactor: Multi-user Chrome MCP extension with remote server architecture
This commit is contained in:
nasir@endelospay.com
170
TESTING_DIRECT_CONNECTION.md
Normal file
170
TESTING_DIRECT_CONNECTION.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
```json
|
||||
{
|
||||
"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
|
||||
Reference in New Issue
Block a user