Metadata-Version: 2.4
Name: seleniumboot-mcp
Version: 0.1.2
Summary: A Python MCP server for Selenium WebDriver — browser automation and Java TestNG/JUnit5 codegen
Author-email: Panjatan <panjatan.tech@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/seleniumboot/selenium-mcp
Project-URL: Repository, https://github.com/seleniumboot/selenium-mcp
Project-URL: Issues, https://github.com/seleniumboot/selenium-mcp/issues
Keywords: selenium,mcp,test-automation,webdriver,testng,junit,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: selenium>=4.6.0

# seleniumboot-mcp

A Python **Model Context Protocol (MCP)** server for Selenium WebDriver automation.
Let Claude or GitHub Copilot control a real browser — navigate pages, interact with elements,
run assertions, and generate ready-to-run **Java TestNG / JUnit 5 / pytest** test code from recorded sessions.

[![PyPI](https://img.shields.io/pypi/v/seleniumboot-mcp)](https://pypi.org/project/seleniumboot-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/seleniumboot-mcp)](https://pypi.org/project/seleniumboot-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## Installation

```bash
pip install seleniumboot-mcp
```

> Requires Python 3.10+ and Chrome. No separate ChromeDriver needed — Selenium Manager handles it automatically.

---

## Setup

### VS Code (Claude / Copilot)

Add `.vscode/mcp.json` to your project root:

```json
{
  "servers": {
    "selenium": {
      "type": "stdio",
      "command": "seleniumboot-mcp"
    }
  }
}
```

Open the project in VS Code → click the **Start** button that appears above the config → done.

### Claude Desktop

Edit your Claude Desktop config:

- **Windows:** `%APPDATA%\claude-desktop\config.json`
- **macOS:** `~/.config/claude-desktop/config.json`

```json
{
  "mcpServers": {
    "selenium": {
      "command": "seleniumboot-mcp"
    }
  }
}
```

Restart Claude Desktop.

---

## How to use

Once the server is running, talk to Claude naturally:

```
Go to https://myapp.com and fill the login form with admin/password, then click Login
```

```
Assert the dashboard heading is visible
```

```
Generate a Java TestNG test class for everything we just did
```

Claude controls the real browser, records every action, and on request generates
a complete test class with `WebDriverWait`, `@BeforeMethod`, `@Test`, `@AfterMethod` —
ready to paste into your Maven or Gradle project.

---

## Tools (37 total)

### Browser
| Tool | Description |
|---|---|
| `start_browser` | Start Chrome or Firefox (headless, window size) |
| `navigate` | Go to a URL |
| `take_screenshot` | Capture page as an image |
| `get_page_title` | Return page title |
| `get_current_url` | Return current URL |
| `get_page_source` | Return full HTML source |
| `execute_script` | Run JavaScript |
| `go_back` / `go_forward` | Browser history |
| `refresh` | Reload page |
| `switch_to_window` | Switch between tabs by index |
| `close_browser` | Quit the browser |

### Elements
| Tool | Description |
|---|---|
| `find_element` | Find element, return tag/text/state |
| `find_elements` | Find all matching elements |
| `click` | Click with explicit wait |
| `type_text` | Clear + type into input |
| `get_text` | Get visible text |
| `get_attribute` | Get any attribute value |
| `select_option` | Select from `<select>` by text, value, or index |
| `hover` | Mouse hover |
| `double_click` | Double click |
| `right_click` | Context menu click |
| `drag_and_drop` | Drag source → target |
| `is_displayed` | Check visibility |
| `is_enabled` | Check enabled state |
| `wait_for_element` | Wait: visible / clickable / present / invisible |
| `scroll_to_element` | Scroll element into view |
| `clear_field` | Clear input field |

### Assertions
| Tool | Description |
|---|---|
| `assert_title` | Page title equals/contains |
| `assert_url` | URL equals/contains |
| `assert_text` | Element text equals/contains |
| `assert_element_visible` | Element is visible |
| `assert_element_not_visible` | Element is hidden or absent |
| `assert_attribute` | Element attribute has expected value |
| `assert_page_contains` | Page body contains a string |
| `assert_element_count` | Count of matching elements equals expected |

### Codegen
| Tool | Description |
|---|---|
| `generate_java_testng` | Generate Java TestNG class from session |
| `generate_java_junit5` | Generate Java JUnit 5 class from session |
| `generate_python_test` | Generate pytest class from session |
| `get_session_log` | View recorded actions |
| `clear_session_log` | Reset the session recording |

---

## Generated Java Example

After: navigate → fill form → click submit

```java
package com.tests.selenium;

import org.openqa.selenium.*;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.interactions.Actions;
import org.openqa.selenium.support.ui.*;
import org.testng.annotations.*;
import java.time.Duration;

public class LoginTest {

    private WebDriver driver;
    private WebDriverWait wait;

    @BeforeMethod
    public void setUp() {
        driver = new ChromeDriver();
        driver.manage().window().maximize();
        wait = new WebDriverWait(driver, Duration.ofSeconds(10));
    }

    @AfterMethod
    public void tearDown() {
        if (driver != null) driver.quit();
    }

    @Test
    public void recordedFlowTest() {
        driver.get("https://app.example.com/login");
        WebElement field = wait.until(ExpectedConditions.visibilityOfElementLocated(By.cssSelector("#username")));
        field.clear();
        field.sendKeys("admin");
        WebElement pwd = wait.until(ExpectedConditions.visibilityOfElementLocated(By.cssSelector("#password")));
        pwd.clear();
        pwd.sendKeys("password");
        wait.until(ExpectedConditions.elementToBeClickable(By.cssSelector("button[type='submit']"))).click();
    }
}
```

---

## Links

- **GitHub:** [github.com/seleniumboot/selenium-mcp](https://github.com/seleniumboot/selenium-mcp)
- **PyPI:** [pypi.org/project/seleniumboot-mcp](https://pypi.org/project/seleniumboot-mcp/)

---

## Roadmap

- [x] Java TestNG / JUnit 5 / Python pytest code generation
- [x] Screenshot returned as `ImageContent` (renders inline in Claude)
- [x] Full session recording — hover, double_click, right_click, scroll, select_option
- [x] Codegen for hover, drag-and-drop, select, scroll in Java and Python templates
- [ ] Auto-start browser on first use (no explicit `start_browser` needed)
- [ ] Page Object Model generation
- [ ] Cucumber / Gherkin step generation
- [ ] CI/CD config generator (GitHub Actions, Jenkins)
- [ ] Self-healing locators

---

## License

MIT
