MCP Operator

# MCP Browser Operator A Model Control Protocol (MCP) server for browser automation that enables LLMs to control a web browser, interact with web pages, and analyze web content through a standardized JSON-RPC interface. ## Features - **Browser Management**: Create, navigate, operate, and close browser instances - **Job Management**: Track status of browser operations with job IDs - **Web Interaction**: Execute natural language instructions using OpenAI's Computer Use API - **Browser Tools**: Access console logs, network activity, screenshots, and more - **Auditing**: Run accessibility, performance, SEO, and other web page audits ## Requirements - Python 3.11+ - Playwright - OpenAI API key (for the Computer Use API) ## Installation 1. Clone this repository: ``` git clone https://github.com/yourusername/operator-mcp.git cd operator-mcp ``` 2. Install dependencies: ``` pip install -e . ``` 3. Install Playwright browsers: ``` playwright install chromium ``` 4. Set your OpenAI API key: ``` export OPENAI_API_KEY=your-api-key ``` ## Usage Start the MCP server: ``` ./run-server ``` The server listens for JSON-RPC requests on stdin and responds on stdout, following the MCP protocol. ### Executable Scripts - `run-server` - Runs the MCP server (main entry point) ```bash # Run the MCP server ./run-server # Run with specific log directory ./run-server --log-dir /path/to/logs # Run in debug mode ./run-server --debug ``` - `run-tests` - Runs all tests (with options for unit or integration only) ```bash # Run all tests ./run-tests # Run only unit tests (faster) ./run-tests --unit-only # Run only integration tests ./run-tests --integration-only # Run with verbose output ./run-tests --verbose # Run a specific test ./run-tests --test TestBrowserOperatorMethods ``` - `run-test-harness` - Runs the server with MCP Inspector for interactive testing ```bash # Run with the MCP Inspector for interactive testing ./run-test-harness ``` ### Core Methods #### Browser Management - **Create Browser**: Initialize a new browser instance ```json { "jsonrpc": "2.0", "id": 1, "method": "mcp__browser-operator__create-browser", "params": { "project_name": "my-project" } } ``` - **Navigate Browser**: Direct the browser to a specified URL ```json { "jsonrpc": "2.0", "id": 2, "method": "mcp__browser-operator__navigate-browser", "params": { "project_name": "my-project", "url": "https://example.com" } } ``` - **Operate Browser**: Execute natural language instructions for browser interaction ```json { "jsonrpc": "2.0", "id": 3, "method": "mcp__browser-operator__operate-browser", "params": { "project_name": "my-project", "instruction": "Find the heading on this page and tell me what it says." } } ``` - **Close Browser**: Terminate a browser instance ```json { "jsonrpc": "2.0", "id": 4, "method": "mcp__browser-operator__close-browser", "params": { "project_name": "my-project" } } ``` #### Job Management - **Get Job Status**: Retrieve the status and result of an operation by job ID ```json { "jsonrpc": "2.0", "id": 5, "method": "mcp__browser-operator__get-job-status", "params": { "job_id": "job-12345" } } ``` - **List Jobs**: View recent browser operation jobs ```json { "jsonrpc": "2.0", "id": 6, "method": "mcp__browser-operator__list-jobs", "params": { "limit": 10 } } ``` #### User Notes - **Add Note**: Create and store notes related to browser operations ```json { "jsonrpc": "2.0", "id": 7, "method": "mcp__browser-operator__add-note", "params": { "name": "My Note", "content": "Important information about this browser session" } } ``` ### Additional Methods #### Browser Debugging Tools - **Get Console Logs**: `mcp__browser-tools__getConsoleLogs` - **Get Console Errors**: `mcp__browser-tools__getConsoleErrors` - **Get Network Logs**: `mcp__browser-tools__getNetworkLogs` - **Get Network Errors**: `mcp__browser-tools__getNetworkErrors` - **Take Screenshot**: `mcp__browser-tools__takeScreenshot` - **Get Selected Element**: `mcp__browser-tools__getSelectedElement` - **Wipe Logs**: `mcp__browser-tools__wipeLogs` #### Audit Tools - **Run Accessibility Audit**: `mcp__browser-tools__runAccessibilityAudit` - **Run Performance Audit**: `mcp__browser-tools__runPerformanceAudit` - **Run SEO Audit**: `mcp__browser-tools__runSEOAudit` - **Run NextJS Audit**: `mcp__browser-tools__runNextJSAudit` - **Run Best Practices Audit**: `mcp__browser-tools__runBestPracticesAudit` - **Run Debugger Mode**: `mcp__browser-tools__runDebuggerMode` - **Run Audit Mode**: `mcp__browser-tools__runAuditMode` ## Asynchronous Workflow Pattern Browser operations are asynchronous and use a job-based approach: 1. **Start Operation**: Call a browser method which returns a job_id 2. **Poll for Completion**: Use get-job-status until job is completed 3. **Process Results**: When job completes, access results from the job status This approach prevents client timeouts while allowing complex browser operations to complete. ## Persistent Browser State The MCP Operator maintains persistent state when browsers are created with a project name: - Browser state (cookies, local storage, session storage) is preserved between sessions - Multiple projects can maintain independent browser states - Useful for maintaining login sessions, shopping carts, or other personalized state ## Project Structure - `src/mcp_operator/`: Main package - `__init__.py`: Package initialization - `__main__.py`: Entry point for package - `server.py`: MCP server implementation - `browser.py`: Browser operator implementation - `cua/`: Computer Use API components - `agent.py`: Agent implementation - `computer.py`: Computer interface - `utils.py`: Utility functions - `run-server`: Script to run the MCP server - `run-tests`: Script to run unit and integration tests - `run-test-harness`: Script to run with MCP Inspector ## Development ### Using MCP Inspector For debugging, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector): ```bash # Use the included run-test-harness script ./run-test-harness # Or directly: npx @modelcontextprotocol/inspector ./run-server ``` This provides a web interface to test your MCP server. ## Security - Domain blocking for potentially harmful sites - URL validation before navigation - Session isolation between different browser instances - File-based logging (no stdout to preserve MCP protocol)