broswer-automation/app/remote-server

MCP Chrome Remote Server

A remote server implementation for the MCP Chrome Bridge that allows external applications to control Chrome through direct WebSocket connections.

🚀 New Direct Connection Architecture

This server now supports direct connections from Chrome extensions, eliminating the need for native messaging hosts as intermediaries:

• Cherry Studio → Remote Server (via Streamable HTTP)
• Chrome Extension → Remote Server (via WebSocket)
• No Native Server Required for Chrome extension communication

Benefits

• ✅ Eliminates 10-second timeout errors
• ✅ Faster response times
• ✅ Simplified architecture
• ✅ Better reliability
• ✅ Easier debugging

Features

• Remote Control: Control Chrome browser remotely via WebSocket API
• MCP Protocol: Implements Model Context Protocol for tool-based interactions
• HTTP Streaming: Full support for MCP Streamable HTTP and SSE (Server-Sent Events)
• Real-time Communication: WebSocket-based real-time communication with Chrome extensions
• RESTful Health Checks: HTTP endpoints for monitoring server health
• Extensible Architecture: Easy to add new Chrome automation tools
• Session Management: Robust session handling for streaming connections

Quick Start

1. Install Dependencies (from project root)

# Install all workspace dependencies
pnpm install

2. Build the Server

# From project root
npm run build:remote

# Or from this directory
npm run build

3. Start the Server

# From project root (recommended)
npm run start:server

# Or from this directory
npm run start:server

The server will start on http://localhost:3001 by default.

4. Verify Server is Running

You should see output like:

🚀 MCP Remote Server started successfully!
📡 Server running at: http://0.0.0.0:3001
🔌 WebSocket endpoint: ws://0.0.0.0:3001/ws/mcp
🔌 Chrome extension endpoint: ws://0.0.0.0:3001/chrome
🌊 Streaming HTTP endpoint: http://0.0.0.0:3001/mcp
📡 SSE endpoint: http://0.0.0.0:3001/sse

5. Test the Connection

# Test WebSocket connection
node test-client.js

# Test streaming HTTP connection
node test-tools-list.js

# Test SSE connection
node test-sse-client.js

# Test simple health check
node test-health.js

Available Scripts

• npm run start:server - Build and start the production server
• npm run start - Start the server (requires pre-built dist/)
• npm run dev - Start development server with auto-reload
• npm run build - Build TypeScript to JavaScript
• npm run test - Run tests
• npm run lint - Run ESLint
• npm run format - Format code with Prettier

Environment Variables

• PORT - Server port (default: 3001)
• HOST - Server host (default: 0.0.0.0)

API Endpoints

HTTP Endpoints

• GET /health - Health check endpoint

Streaming HTTP Endpoints (MCP Protocol)

• POST /mcp - Send MCP messages (initialization, tool calls, etc.)
• GET /mcp - Establish SSE stream for receiving responses (requires MCP-Session-ID header)
• DELETE /mcp - Terminate MCP session (requires MCP-Session-ID header)

SSE Endpoints

• GET /sse - Server-Sent Events endpoint for MCP communication
• POST /messages - Send messages to SSE session (requires X-Session-ID header)

WebSocket Endpoints

• WS /ws/mcp - MCP protocol WebSocket endpoint for Chrome control
• WS /chrome - Chrome extension WebSocket endpoint

Available Tools

The server provides the following Chrome automation tools:

1. navigate_to_url - Navigate to a specific URL
2. get_page_content - Get page text content
3. click_element - Click on elements using CSS selectors
4. fill_input - Fill input fields with text
5. take_screenshot - Capture page screenshots

Usage Examples

Streamable HTTP Connection (Recommended)

import fetch from 'node-fetch';

const SERVER_URL = 'http://localhost:3001';
const MCP_URL = `${SERVER_URL}/mcp`;

// Step 1: Initialize session
const initResponse = await fetch(MCP_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Accept: 'application/json, text/event-stream',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'initialize',
    params: {
      protocolVersion: '2024-11-05',
      capabilities: { tools: {} },
      clientInfo: { name: 'my-client', version: '1.0.0' },
    },
  }),
});

const sessionId = initResponse.headers.get('mcp-session-id');

// Step 2: Call tools
const toolResponse = await fetch(MCP_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Accept: 'application/json, text/event-stream',
    'MCP-Session-ID': sessionId,
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 2,
    method: 'tools/call',
    params: {
      name: 'navigate_to_url',
      arguments: { url: 'https://example.com' },
    },
  }),
});

const result = await toolResponse.text(); // SSE format

WebSocket Connection

const ws = new WebSocket('ws://localhost:3001/ws/mcp');

// Navigate to a URL
ws.send(
  JSON.stringify({
    method: 'tools/call',
    params: {
      name: 'navigate_to_url',
      arguments: { url: 'https://example.com' },
    },
  }),
);

// Get page content
ws.send(
  JSON.stringify({
    method: 'tools/call',
    params: {
      name: 'get_page_content',
      arguments: {},
    },
  }),
);

Streaming Capabilities

The MCP Remote Server now supports multiple connection types:

1. Streamable HTTP (Recommended)

• Full MCP protocol compliance
• Session-based communication
• Server-Sent Events for real-time responses
• Stateful connections with session management
• Compatible with MCP clients like CherryStudio

2. Server-Sent Events (SSE)

• Real-time streaming communication
• Lightweight alternative to WebSockets
• HTTP-based with automatic reconnection

3. WebSocket (Legacy)

• Real-time bidirectional communication
• Backward compatibility with existing clients

Architecture

┌─────────────────┐    HTTP/SSE     ┌──────────────────┐    WebSocket       ┌─────────────────┐
│   MCP Client    │ ◄──────────────► │  Remote Server   │ ◄─────────────────► │ Chrome Extension │
│  (External App) │    WebSocket    │   (This Server)  │                    │                 │
└─────────────────┘                 └──────────────────┘                    └─────────────────┘

Development

Project Structure

src/
├── index.ts              # Main server entry point
├── server/
│   ├── mcp-remote-server.ts  # MCP protocol implementation
│   └── chrome-tools.ts       # Chrome automation tools
└── types/                # TypeScript type definitions

Adding New Tools

1. Add the tool definition in mcp-remote-server.ts
2. Implement the tool logic in chrome-tools.ts
3. Update the Chrome extension to handle new actions

Troubleshooting

Common Issues

1. Server won't start: Check if port 3000 is available
2. Chrome extension not connecting: Ensure the extension is installed and enabled
3. WebSocket connection fails: Check firewall settings and CORS configuration

Logs

The server uses structured logging with Pino. Check console output for detailed error messages and debugging information.

License

MIT License - see LICENSE file for details.