How angiejones/mcp-selenium works
Project Type and Purpose
• This is a server implementation for the Model Context Protocol (MCP) that leverages Selenium WebDriver to automate browser interactions.
• The README clearly shows that it is intended to serve as a bridge between MCP clients (like Goose Desktop or Claude Desktop) and browser automation tools. The server offers a variety of automation commands (start_browser, navigate, click, hover, etc.) and supports both Chrome and Firefox.
• It’s a Node.js project (using package.json, npm scripts) with a small file structure and is intended to be deployed via npx or Docker.
File Structure Insights
• Top-level files such as Dockerfile, LICENSE, and smithery.yaml indicate deployment and integration options.
• The “bin” directory contains the executable CLI (bin/mcp-selenium.js) which likely serves as the entry point.
• The “src” directory (specifically src/lib/server.js) contains the core server logic.
• Minimal structure suggests a focused design; the server file implements the logic to handle MCP requests and routes them to corresponding Selenium implementations.
Architectural Components to Capture
• CLI/Command Entry Point: bin/mcp-selenium.js that triggers the Node.js process.
• Server Core: src/lib/server.js where MCP commands are handled.
• MCP Client Integration: How external MCP clients (Goose, Claude, etc.) communicate with the server. This includes both the direct command execution (e.g., via NPX) and configuration (as shown in the README JSON examples).
• Selenium/WebDriver Interaction Module: Although not explicitly split as its own folder, the server is responsible for translating MCP tool commands (like start_browser, navigate, click, etc.) into Selenium commands that operate on a browser session.
• Browser Sessions: The layer where browser automation happens. This involves launching browsers, handling session data, and returning results (such as screenshots, webpage text, etc.).
• External Integration Configurations: The smithery.yaml suggests that the project is integrated with tools like Smithery for deployment and automatic installation.
Relationships and Interactions
• The entry point (CLI) initiates the server process.
• MCP clients send requests (commands defined in the README such as start_browser, navigate, etc.) to the server.
• The server (server.js) handles these requests, orchestrates the corresponding Selenium WebDriver calls, and interacts with the browser sessions.
• Results and responses (like screenshots, element texts) flow back via the MCP protocol to the client.
Architectural Patterns and Design Principles
• Separation of Concerns: The CLI (entry point) is kept distinct from the server logic, allowing source code modularity.
• Client-Server Communication: The MCP server abstracts away the direct details of Selenium, exposing a higher-level protocol to clients.
• Modularity/Extensibility: Each tool (e.g., start_browser, navigate, etc.) could be conceptually thought of as service modules that the server exposes.