seleniumboot-mcp 0.1.0__py3-none-any.whl

selenium_mcp/server.py

@@ -0,0 +1,78 @@
+"""
+Selenium MCP Server
+A Python-based MCP server for Selenium WebDriver automation.
+Serves both Python and Java test automation users.
+"""
+
+import asyncio
+import logging
+import tempfile
+from pathlib import Path
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent, ImageContent
+
+from selenium_mcp.tools.browser_tools import BrowserTools
+from selenium_mcp.tools.element_tools import ElementTools
+from selenium_mcp.tools.assertion_tools import AssertionTools
+from selenium_mcp.tools.codegen_tools import CodegenTools
+
+_log_path = Path(tempfile.gettempdir()) / "selenium-mcp.log"
+logging.basicConfig(
+    filename=str(_log_path),
+    level=logging.DEBUG,
+    format="%(asctime)s [%(levelname)s] %(message)s"
+)
+log = logging.getLogger(__name__)
+
+app = Server("selenium-mcp")
+
+browser = BrowserTools()
+element = ElementTools(browser)
+assertion = AssertionTools(browser)
+codegen = CodegenTools(browser)
+
+ALL_TOOLS = [
+    *browser.get_tools(),
+    *element.get_tools(),
+    *assertion.get_tools(),
+    *codegen.get_tools(),
+]
+
+TOOL_HANDLERS = {
+    **browser.get_handlers(),
+    **element.get_handlers(),
+    **assertion.get_handlers(),
+    **codegen.get_handlers(),
+}
+
+
+@app.list_tools()
+async def list_tools() -> list[Tool]:
+    return ALL_TOOLS
+
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    log.info(f"Tool called: {name} | args: {arguments}")
+    handler = TOOL_HANDLERS.get(name)
+    if not handler:
+        return [TextContent(type="text", text=f"Unknown tool: {name}")]
+    try:
+        result = await handler(arguments)
+        if isinstance(result, str) and result.startswith("screenshot:base64:"):
+            b64 = result[len("screenshot:base64:"):]
+            return [ImageContent(type="image", data=b64, mimeType="image/png")]
+        return [TextContent(type="text", text=result)]
+    except Exception as e:
+        log.error(f"Tool error [{name}]: {e}")
+        return [TextContent(type="text", text=f"Error: {str(e)}")]
+
+
+async def main():
+    async with stdio_server() as (r, w):
+        await app.run(r, w, app.create_initialization_options())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

selenium_mcp/tools/assertion_tools.py

@@ -0,0 +1,245 @@
+"""
+Assertion Tools — validate page state, element state, text, URL, title
+Returns PASS/FAIL with detail — useful for AI-driven test verification.
+"""
+
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+from mcp.types import Tool
+
+BY_MAP = {
+    "css":          By.CSS_SELECTOR,
+    "xpath":        By.XPATH,
+    "id":           By.ID,
+    "name":         By.NAME,
+    "tag":          By.TAG_NAME,
+    "class":        By.CLASS_NAME,
+    "link":         By.LINK_TEXT,
+    "partial_link": By.PARTIAL_LINK_TEXT,
+}
+
+
+class AssertionTools:
+    def __init__(self, browser_tools):
+        self.browser = browser_tools
+
+    def _driver(self):
+        return self.browser.get_driver()
+
+    def _by(self, strategy: str):
+        return BY_MAP.get(strategy, By.CSS_SELECTOR)
+
+    def get_tools(self) -> list[Tool]:
+        return [
+            Tool(
+                name="assert_title",
+                description="Assert the page title equals or contains expected text.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "expected": {"type": "string"},
+                        "exact": {"type": "boolean", "default": False}
+                    },
+                    "required": ["expected"],
+                },
+            ),
+            Tool(
+                name="assert_url",
+                description="Assert the current URL equals or contains expected value.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "expected": {"type": "string"},
+                        "exact": {"type": "boolean", "default": False}
+                    },
+                    "required": ["expected"],
+                },
+            ),
+            Tool(
+                name="assert_text",
+                description="Assert element text equals or contains expected value.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "selector": {"type": "string"},
+                        "by": {"type": "string", "default": "css"},
+                        "expected": {"type": "string"},
+                        "exact": {"type": "boolean", "default": False},
+                        "timeout": {"type": "integer", "default": 10}
+                    },
+                    "required": ["selector", "expected"],
+                },
+            ),
+            Tool(
+                name="assert_element_visible",
+                description="Assert an element is visible on the page.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "selector": {"type": "string"},
+                        "by": {"type": "string", "default": "css"},
+                        "timeout": {"type": "integer", "default": 10}
+                    },
+                    "required": ["selector"],
+                },
+            ),
+            Tool(
+                name="assert_element_not_visible",
+                description="Assert an element is NOT visible (hidden or absent).",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "selector": {"type": "string"},
+                        "by": {"type": "string", "default": "css"},
+                        "timeout": {"type": "integer", "default": 3}
+                    },
+                    "required": ["selector"],
+                },
+            ),
+            Tool(
+                name="assert_attribute",
+                description="Assert an element attribute has the expected value.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "selector": {"type": "string"},
+                        "by": {"type": "string", "default": "css"},
+                        "attribute": {"type": "string"},
+                        "expected": {"type": "string"},
+                        "exact": {"type": "boolean", "default": True},
+                        "timeout": {"type": "integer", "default": 10}
+                    },
+                    "required": ["selector", "attribute", "expected"],
+                },
+            ),
+            Tool(
+                name="assert_page_contains",
+                description="Assert the full page source or visible text contains a string.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "text": {"type": "string"},
+                        "source_only": {
+                            "type": "boolean",
+                            "default": False,
+                            "description": "If true, checks page source; otherwise checks body visible text"
+                        }
+                    },
+                    "required": ["text"],
+                },
+            ),
+            Tool(
+                name="assert_element_count",
+                description="Assert number of elements matching selector equals expected count.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "selector": {"type": "string"},
+                        "by": {"type": "string", "default": "css"},
+                        "expected_count": {"type": "integer"}
+                    },
+                    "required": ["selector", "expected_count"],
+                },
+            ),
+        ]
+
+    def get_handlers(self) -> dict:
+        return {
+            "assert_title":               self._assert_title,
+            "assert_url":                 self._assert_url,
+            "assert_text":                self._assert_text,
+            "assert_element_visible":     self._assert_element_visible,
+            "assert_element_not_visible": self._assert_element_not_visible,
+            "assert_attribute":           self._assert_attribute,
+            "assert_page_contains":       self._assert_page_contains,
+            "assert_element_count":       self._assert_element_count,
+        }
+
+    # ------------------------------------------------------------------ #
+    #  Helpers                                                             #
+    # ------------------------------------------------------------------ #
+    def _pass(self, msg): return f"✅ PASS | {msg}"
+    def _fail(self, msg): return f"❌ FAIL | {msg}"
+
+    # ------------------------------------------------------------------ #
+    #  Handlers                                                            #
+    # ------------------------------------------------------------------ #
+    async def _assert_title(self, args: dict) -> str:
+        actual = self._driver().title
+        exp = args["expected"]
+        ok = (actual == exp) if args.get("exact", False) else (exp.lower() in actual.lower())
+        return self._pass(f"title='{actual}'") if ok else self._fail(f"expected='{exp}' | actual='{actual}'")
+
+    async def _assert_url(self, args: dict) -> str:
+        actual = self._driver().current_url
+        exp = args["expected"]
+        ok = (actual == exp) if args.get("exact", False) else (exp in actual)
+        return self._pass(f"url='{actual}'") if ok else self._fail(f"expected='{exp}' | actual='{actual}'")
+
+    async def _assert_text(self, args: dict) -> str:
+        by = self._by(args.get("by", "css"))
+        timeout = args.get("timeout", 10)
+        try:
+            el = WebDriverWait(self._driver(), timeout).until(
+                EC.visibility_of_element_located((by, args["selector"]))
+            )
+        except Exception:
+            return self._fail(f"element '{args['selector']}' not found within {timeout}s")
+        actual = el.text
+        exp = args["expected"]
+        ok = (actual == exp) if args.get("exact", False) else (exp.lower() in actual.lower())
+        return self._pass(f"text='{actual}'") if ok else self._fail(f"expected='{exp}' | actual='{actual}'")
+
+    async def _assert_element_visible(self, args: dict) -> str:
+        by = self._by(args.get("by", "css"))
+        timeout = args.get("timeout", 10)
+        try:
+            WebDriverWait(self._driver(), timeout).until(
+                EC.visibility_of_element_located((by, args["selector"]))
+            )
+            return self._pass(f"'{args['selector']}' is visible")
+        except Exception:
+            return self._fail(f"'{args['selector']}' is NOT visible")
+
+    async def _assert_element_not_visible(self, args: dict) -> str:
+        by = self._by(args.get("by", "css"))
+        timeout = args.get("timeout", 3)
+        try:
+            WebDriverWait(self._driver(), timeout).until(
+                EC.invisibility_of_element_located((by, args["selector"]))
+            )
+            return self._pass(f"'{args['selector']}' is not visible")
+        except Exception:
+            return self._fail(f"'{args['selector']}' IS visible (expected hidden)")
+
+    async def _assert_attribute(self, args: dict) -> str:
+        by = self._by(args.get("by", "css"))
+        timeout = args.get("timeout", 10)
+        try:
+            el = WebDriverWait(self._driver(), timeout).until(
+                EC.presence_of_element_located((by, args["selector"]))
+            )
+        except Exception:
+            return self._fail(f"element '{args['selector']}' not found within {timeout}s")
+        actual = el.get_attribute(args["attribute"])
+        exp = args["expected"]
+        ok = (actual == exp) if args.get("exact", True) else (exp in (actual or ""))
+        return self._pass(f"{args['attribute']}='{actual}'") if ok else self._fail(f"expected='{exp}' | actual='{actual}'")
+
+    async def _assert_page_contains(self, args: dict) -> str:
+        text = args["text"]
+        if args.get("source_only", False):
+            content = self._driver().page_source
+        else:
+            content = self._driver().find_element(By.TAG_NAME, "body").text
+        ok = text.lower() in content.lower()
+        return self._pass(f"page contains '{text}'") if ok else self._fail(f"'{text}' not found on page")
+
+    async def _assert_element_count(self, args: dict) -> str:
+        by = self._by(args.get("by", "css"))
+        els = self._driver().find_elements(by, args["selector"])
+        actual = len(els)
+        exp = args["expected_count"]
+        ok = actual == exp
+        return self._pass(f"count={actual}") if ok else self._fail(f"expected={exp} | actual={actual}")

selenium_mcp/tools/browser_tools.py

@@ -0,0 +1,240 @@
+"""
+Browser Tools — start, stop, navigate, screenshot, window management
+"""
+
+import base64
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options as ChromeOptions
+from selenium.webdriver.firefox.options import Options as FirefoxOptions
+from mcp.types import Tool
+
+
+class BrowserTools:
+    def __init__(self):
+        self.driver = None
+        self._session_log = []  # records all actions for codegen
+
+    # ------------------------------------------------------------------ #
+    #  Session helpers                                                     #
+    # ------------------------------------------------------------------ #
+    def record(self, action: str, **kwargs):
+        """Append an action to the session log for code generation."""
+        self._session_log.append({"action": action, **kwargs})
+
+    def get_driver(self):
+        if not self.driver:
+            raise RuntimeError("No browser session. Call start_browser first.")
+        return self.driver
+
+    # ------------------------------------------------------------------ #
+    #  MCP tool definitions                                                #
+    # ------------------------------------------------------------------ #
+    def get_tools(self) -> list[Tool]:
+        return [
+            Tool(
+                name="start_browser",
+                description="Start a browser session. Supports chrome and firefox.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "browser": {
+                            "type": "string",
+                            "enum": ["chrome", "firefox"],
+                            "default": "chrome"
+                        },
+                        "headless": {
+                            "type": "boolean",
+                            "default": False
+                        },
+                        "window_size": {
+                            "type": "string",
+                            "description": "e.g. 1920x1080",
+                            "default": "1920x1080"
+                        }
+                    },
+                },
+            ),
+            Tool(
+                name="navigate",
+                description="Navigate the browser to a URL.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "url": {"type": "string", "description": "Full URL including https://"}
+                    },
+                    "required": ["url"],
+                },
+            ),
+            Tool(
+                name="take_screenshot",
+                description="Take a screenshot and return it as base64.",
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="get_page_source",
+                description="Return the current page HTML source.",
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="get_page_title",
+                description="Return the current page title.",
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="get_current_url",
+                description="Return the current URL.",
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="close_browser",
+                description="Close and quit the browser session.",
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="switch_to_window",
+                description="Switch to a browser window/tab by index.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "index": {"type": "integer", "default": 0}
+                    },
+                },
+            ),
+            Tool(
+                name="go_back",
+                description="Navigate back in browser history.",
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="go_forward",
+                description="Navigate forward in browser history.",
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="refresh",
+                description="Refresh the current page.",
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="execute_script",
+                description="Execute JavaScript in the browser.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "script": {"type": "string"},
+                        "args": {"type": "array", "default": []}
+                    },
+                    "required": ["script"],
+                },
+            ),
+        ]
+
+    # ------------------------------------------------------------------ #
+    #  Handlers                                                            #
+    # ------------------------------------------------------------------ #
+    def get_handlers(self) -> dict:
+        return {
+            "start_browser":    self._start_browser,
+            "navigate":         self._navigate,
+            "take_screenshot":  self._take_screenshot,
+            "get_page_source":  self._get_page_source,
+            "get_page_title":   self._get_page_title,
+            "get_current_url":  self._get_current_url,
+            "close_browser":    self._close_browser,
+            "switch_to_window": self._switch_to_window,
+            "go_back":          self._go_back,
+            "go_forward":       self._go_forward,
+            "refresh":          self._refresh,
+            "execute_script":   self._execute_script,
+        }
+
+    async def _start_browser(self, args: dict) -> str:
+        if self.driver:
+            try:
+                self.driver.quit()
+            except Exception:
+                pass
+            self.driver = None
+
+        browser = args.get("browser", "chrome")
+        headless = args.get("headless", False)
+        try:
+            w, h = args.get("window_size", "1920x1080").lower().replace(" ", "").split("x")
+            int(w), int(h)
+        except (ValueError, AttributeError):
+            w, h = "1920", "1080"
+
+        if browser == "chrome":
+            opts = ChromeOptions()
+            if headless:
+                opts.add_argument("--headless=new")
+            opts.add_argument(f"--window-size={w},{h}")
+            opts.add_argument("--no-sandbox")
+            opts.add_argument("--disable-dev-shm-usage")
+            self.driver = webdriver.Chrome(options=opts)
+        elif browser == "firefox":
+            opts = FirefoxOptions()
+            if headless:
+                opts.add_argument("--headless")
+            self.driver = webdriver.Firefox(options=opts)
+            self.driver.set_window_size(int(w), int(h))
+        else:
+            return f"Unsupported browser: {browser}"
+
+        self._session_log = []
+        self.record("start_browser", browser=browser, headless=headless)
+        return f"✅ {browser.capitalize()} started ({w}x{h}, headless={headless})"
+
+    async def _navigate(self, args: dict) -> str:
+        url = args["url"]
+        self.get_driver().get(url)
+        self.record("navigate", url=url)
+        return f"✅ Navigated to {url}"
+
+    async def _take_screenshot(self, args: dict) -> str:
+        png = self.get_driver().get_screenshot_as_png()
+        b64 = base64.b64encode(png).decode()
+        return f"screenshot:base64:{b64}"
+
+    async def _get_page_source(self, args: dict) -> str:
+        return self.get_driver().page_source
+
+    async def _get_page_title(self, args: dict) -> str:
+        return self.get_driver().title
+
+    async def _get_current_url(self, args: dict) -> str:
+        return self.get_driver().current_url
+
+    async def _close_browser(self, args: dict) -> str:
+        if self.driver:
+            self.driver.quit()
+            self.driver = None
+        return "✅ Browser closed"
+
+    async def _switch_to_window(self, args: dict) -> str:
+        idx = args.get("index", 0)
+        handles = self.get_driver().window_handles
+        if idx >= len(handles):
+            return f"No window at index {idx}. Available: {len(handles)}"
+        self.get_driver().switch_to.window(handles[idx])
+        return f"✅ Switched to window {idx}"
+
+    async def _go_back(self, args: dict) -> str:
+        self.get_driver().back()
+        self.record("go_back")
+        return "✅ Navigated back"
+
+    async def _go_forward(self, args: dict) -> str:
+        self.get_driver().forward()
+        self.record("go_forward")
+        return "✅ Navigated forward"
+
+    async def _refresh(self, args: dict) -> str:
+        self.get_driver().refresh()
+        self.record("refresh")
+        return "✅ Page refreshed"
+
+    async def _execute_script(self, args: dict) -> str:
+        result = self.get_driver().execute_script(args["script"], *args.get("args", []))
+        self.record("execute_script", script=args["script"])
+        return str(result)