@wdio/mcp 2.5.3 → 3.1.0

package/README.md

@@ -1,56 +1,198 @@
 # WebDriverIO MCP Server
 
-A Model Context Protocol (MCP) server that enables Claude Desktop to interact with web browsers and mobile applications
+A Model Context Protocol (MCP) server that enables AI assistants to interact with web browsers and mobile applications
 using WebDriverIO. Automate Chrome, Firefox, Edge, and Safari browsers plus iOS and Android apps—all through a unified interface.
 
 ## Installation
 
-### Setup
+[![mcp MCP server](https://glama.ai/mcp/servers/webdriverio/mcp/badges/score.svg)](https://glama.ai/mcp/servers/webdriverio/mcp)
 
-**Option 1: Configure Claude Desktop or Claude Code (Recommended)**
+Add the following configuration to your MCP client settings:
 
-Add the following configuration to your Claude MCP settings:
+**Standard config** (works in most clients):
 
 ```json
 {
   "mcpServers": {
     "wdio-mcp": {
       "command": "npx",
-      "args": [
-        "-y",
-        "@wdio/mcp"
-      ]
+      "args": ["-y", "@wdio/mcp@latest"]
     }
   }
 }
 ```
 
-**Option 2: Global Installation**
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install%20Server-0098FF?style=flat-square)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522wdio-mcp%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540wdio%252Fmcp%2540latest%2522%255D%257D)
+[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install%20Server-24bfa5?style=flat-square)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522wdio-mcp%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540wdio%252Fmcp%2540latest%2522%255D%257D)
+[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=WebDriverIO&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB3ZGlvL21jcEBsYXRlc3QiXX0%3D)
+
+<details>
+<summary>Claude Desktop</summary>
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%\Claude\claude_desktop_config.json` (Windows), or `~/.config/Claude/claude_desktop_config.json` (Linux):
+
+```json
+{
+  "mcpServers": {
+    "wdio-mcp": {
+      "command": "npx",
+      "args": ["-y", "@wdio/mcp@latest"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Claude Code</summary>
 
 ```bash
-npm i -g @wdio/mcp
+claude mcp add wdio-mcp -- npx -y @wdio/mcp@latest
 ```
+</details>
 
-Then configure MCP:
+<details>
+<summary>Cline</summary>
+
+Add to your VS Code `settings.json` or `cline_mcp_settings.json` file:
 
 ```json
 {
   "mcpServers": {
     "wdio-mcp": {
-      "command": "wdio-mcp"
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@wdio/mcp@latest"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+Go to `Cursor Settings` → `MCP` → `Add new MCP Server`, or create `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "wdio-mcp": {
+      "command": "npx",
+      "args": ["-y", "@wdio/mcp@latest"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Codex</summary>
+
+Use the Codex CLI:
+
+```bash
+codex mcp add wdio-mcp npx "@wdio/mcp@latest"
+```
+
+Or edit `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.wdio-mcp]
+command = "npx"
+args = ["@wdio/mcp@latest"]
+```
+</details>
+
+<details>
+<summary>Goose</summary>
+
+Go to `Advanced settings` → `Extensions` → `Add custom extension`, or run:
+
+```bash
+goose configure
+```
+
+Or edit `~/.config/goose/config.yaml`:
+
+```yaml
+extensions:
+  wdio-mcp:
+    name: WebDriverIO MCP
+    cmd: npx
+    args: [-y, "@wdio/mcp@latest"]
+    enabled: true
+    type: stdio
+```
+</details>
+
+<details>
+<summary>Windsurf</summary>
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "wdio-mcp": {
+      "command": "npx",
+      "args": ["-y", "@wdio/mcp@latest"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Zed</summary>
+
+Edit Zed settings (`~/.config/zed/settings.json`):
+
+```json
+{
+  "context_servers": {
+    "wdio-mcp": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "@wdio/mcp@latest"]
     }
   }
 }
 ```
+</details>
 
-> **Note:** The npm package is `@wdio/mcp`, but the executable binary is `wdio-mcp`.
+<details>
+<summary>VS Code (Copilot)</summary>
 
-**Restart Claude Desktop**
+```bash
+code --add-mcp '{"name":"wdio-mcp","command":"npx","args":["-y","@wdio/mcp@latest"]}'
+```
+</details>
 
-⚠️ You may need to fully restart Claude Desktop. On Windows, use Task Manager to ensure it's completely closed before
-restarting.
+----
+> ⚠️ **Restart Required**: After adding the configuration, fully restart your MCP client to apply the changes.
 
-📖 **Need help?** Read the [official MCP configuration guide](https://modelcontextprotocol.io/quickstart/user)
+### Option 2: Global Installation
+
+If you prefer to install globally:
+
+```bash
+npm install -g @wdio/mcp
+```
+
+Then use `wdio-mcp` as the command:
+
+```json
+{
+  "mcpServers": {
+    "wdio-mcp": {
+      "command": "wdio-mcp"
+    }
+  }
+}
+```
+
+📖 **Need help?** Follow the [MCP install guide](https://modelcontextprotocol.io/quickstart/user).
 
 ### Prerequisites For Mobile App Automation
 
@@ -74,6 +216,117 @@ appium
 # Server runs at http://127.0.0.1:4723 by default
 ```
 
+## BrowserStack
+
+Run browser and mobile app tests on [BrowserStack](https://www.browserstack.com/) real devices and browsers without any local setup.
+
+### Prerequisites
+
+Set your credentials as environment variables:
+
+```bash
+export BROWSERSTACK_USERNAME=your_username
+export BROWSERSTACK_ACCESS_KEY=your_access_key
+```
+
+Or add them to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "wdio-mcp": {
+      "command": "npx",
+      "args": ["-y", "@wdio/mcp@latest"],
+      "env": {
+        "BROWSERSTACK_USERNAME": "your_username",
+        "BROWSERSTACK_ACCESS_KEY": "your_access_key"
+      }
+    }
+  }
+}
+```
+
+### Browser Sessions
+
+Run a browser on a specific OS/version combination:
+
+```javascript
+start_session({
+  provider: 'browserstack',
+  platform: 'browser',
+  browser: 'chrome',           // chrome | firefox | edge | safari
+  browserVersion: 'latest',    // default: latest
+  os: 'Windows',               // e.g. "Windows", "OS X"
+  osVersion: '11',             // e.g. "11", "Sequoia"
+  reporting: {
+    project: 'My Project',
+    build: 'v1.2.0',
+    session: 'Login flow'
+  }
+})
+```
+
+### Mobile App Sessions
+
+Test on BrowserStack real devices. First upload your app (or use an existing `bs://` URL):
+
+```javascript
+// Upload a local .apk or .ipa (returns a bs:// URL)
+upload_app({ path: '/path/to/app.apk' })
+
+// Start a session with the returned URL
+start_session({
+  provider: 'browserstack',
+  platform: 'android',         // android | ios
+  app: 'bs://abc123...',       // bs:// URL or custom_id from upload
+  deviceName: 'Samsung Galaxy S23',
+  platformVersion: '13.0',
+  reporting: {
+    project: 'My Project',
+    build: 'v1.2.0',
+    session: 'Checkout flow'
+  }
+})
+```
+
+Use `list_apps` to see previously uploaded apps:
+
+```javascript
+list_apps()                               // own uploads, sorted by date
+list_apps({ sortBy: 'app_name' })
+list_apps({ organizationWide: true })     // all uploads in your org
+```
+
+### BrowserStack Local
+
+To test against URLs that are only accessible on your local machine or internal network, enable the BrowserStack Local tunnel:
+
+```javascript
+start_session({
+  provider: 'browserstack',
+  platform: 'browser',
+  browser: 'chrome',
+  browserstackLocal: true      // starts tunnel automatically
+})
+```
+
+### Reporting Labels
+
+All session types support `reporting` labels that appear in the BrowserStack Automate dashboard:
+
+| Field                     | Description                                |
+|---------------------------|--------------------------------------------|
+| `reporting.project`       | Group sessions under a project name        |
+| `reporting.build`         | Tag sessions with a build/version label    |
+| `reporting.session`       | Name for the individual test session       |
+
+### BrowserStack Tools
+
+| Tool          | Description                                                                      |
+|---------------|----------------------------------------------------------------------------------|
+| `upload_app`  | Upload a local `.apk` or `.ipa` to BrowserStack; returns a `bs://` URL          |
+| `list_apps`   | List apps previously uploaded to your BrowserStack account                       |
+
 ## Features
 
 ### Browser Automation