🤖 Responsive Tester MCP Server (rstest)

Model Context Protocol (MCP) Server for the Responsive Tester Chrome Extension
Connect Responsive Tester to Claude, ChatGPT, Gemini, or IDEs in two simple steps to automate responsive testing, multi-screen navigation, visual QA, and cross-device validation.

💡 Quick Identifier: Named rstest (like agy for Antigravity) so you can simply mention rstest in any prompt to control your multi-screen tests!

🚀 Connect in Two Simple Steps

Step 1: Configure Your AI Assistant

You can set up your AI client in seconds using either the Automated Setup Prompt or Manual Configuration.

Option A: 1-Click Automated Setup Prompt (Recommended)

Copy the prompt for your AI assistant and paste it into its chat interface:

• For Claude Desktop / Claude Code:

  "Set up the Responsive Tester MCP server on this computer. Add a local stdio server named rstest using command npx and args ["-y", "responsive-tester-mcp@latest"]. Preserve all existing MCP servers and settings. Then verify the configuration, tell me which file or command you changed, and ask me to restart the AI app if required. Do not start the MCP server directly in a normal terminal because it communicates over stdio."

• For ChatGPT / Codex:

  "Configure Responsive Tester MCP for my local ChatGPT/Codex client. Add a user-level stdio MCP server named rstest with command npx and args ["-y", "responsive-tester-mcp@latest"]. Preserve my existing ~/.codex/config.toml settings. Use the supported Codex MCP command if available; otherwise update the TOML safely. Verify that the server appears in the MCP list, then tell me whether a restart is required."

• For Gemini CLI:

  "Set up Responsive Tester MCP in Gemini CLI for this user. Add a stdio MCP server named rstest using command npx and args ["-y", "responsive-tester-mcp@latest"]. Preserve every existing setting in ~/.gemini/settings.json and merge the new mcpServers entry safely. Reload MCP servers, verify the server is connected, and report exactly what changed."

Option B: Manual Configuration (JSON / TOML)

1. Claude Desktop (claude_desktop_config.json)

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the server configuration under "mcpServers":

{
  "mcpServers": {
    "rstest": {
      "command": "npx",
      "args": ["-y", "responsive-tester-mcp@latest"]
    }
  }
}

2. ChatGPT / Codex (~/.codex/config.toml)

[mcp_servers.rstest]
command = "npx"
args = ["-y", "responsive-tester-mcp@latest"]

3. Gemini CLI (~/.gemini/settings.json)

{
  "mcpServers": {
    "rstest": {
      "command": "npx",
      "args": ["-y", "responsive-tester-mcp@latest"]
    }
  }
}

4. Cursor / Windsurf / Antigravity IDE

In Settings → MCP Servers, add a new stdio server:

• Name: rstest
• Command: npx
• Args: ["-y", "responsive-tester-mcp@latest"]

Note: Completely restart your AI application after saving the configuration file.

Step 2: Start Testing (Auto-Launch or Open Chrome)

1. Prompt your AI directly — rstest will automatically attempt to open the Chrome Extension viewer tab if it's closed!
2. Or manually launch Google Chrome and click the Responsive Tester extension icon.
3. The toolbar status chip turns green: ● AI Online (ws://127.0.0.1:8765).
4. Keep the tab open and prompt your AI in natural language!

🛠️ Available MCP Tools

| Tool Name | Parameters | Description | | :--- | :--- | :--- | | responsive_open_viewer | url (string, optional) | Automatically launch or focus the Responsive Tester viewer tab in Google Chrome. | | responsive_test_workflow | None | Read authentication prerequisites, account/manual-login handling, retry limits, and test reporting guidance. | | responsive_status | None | Check connection status between AI and the Responsive Tester Chrome tab. | | responsive_navigate | url (string, required) | Navigate all active device viewports to a specified URL (e.g. http://localhost:3000). | | responsive_list_devices | None | List all active viewports and available device presets. | | responsive_set_devices | deviceIds (array of strings) | Configure active devices on the canvas (e.g. ["iphone_15_pro", "ipad_air", "desktop_fhd"]). | | responsive_add_device | name, width, height, type | Add a custom screen resolution/viewport to the testing suite. | | responsive_interact | action (click|type|scroll), selector, value, deviceId, sync | Simulate click, typing, or scrolling on a device and synchronize across all screens. | | responsive_capture_screenshots | deviceId (optional) | Capture high-resolution screenshots (base64 PNG) of active devices for AI visual inspection. | | responsive_get_logs | None | Retrieve JavaScript console errors and warnings logged across all viewports. |

💬 AI Prompt Recipes & Examples (Just say rstest)

Just include rstest in your prompt so your AI assistant knows to invoke the tool suite:

• Basic Responsive Layout Audit:

  "Use rstest to open http://localhost:3000 on iPhone 15 Pro, iPad Air, and Desktop FHD, and check if the navigation bar overflows or breaks."

• Multi-Device Visual Inspection with Screenshots:

  "rstest: Take screenshots of all active devices on the current page and analyze responsive layout issues, especially element overlap on mobile screens."

• Synchronized Form & Interaction Testing:

  "rstest: Type '[email protected]' into the email input, click '#btn-submit', and verify the resulting UI state across all active screens."

• Console Error Audit:

  "rstest: Scroll down to the footer and check if any JavaScript console errors or warnings were triggered."

• Testing Custom Viewports (Foldables & Edge Cases):

  "rstest: Add a custom device named 'Foldable Outer' with 280x653 px, set it as active, and check how our hero section renders."

❓ Troubleshooting

1. "Chrome Extension is not connected via ws://127.0.0.1:8765"

The MCP server is running, but the Responsive Tester viewer tab is not currently open in Google Chrome.
Solution: Open Chrome and click the Responsive Tester extension icon, or ask AI: "rstest open viewer". Keep the tab open, then retry your prompt.

2. Status shows "AI Offline" in Chrome

The AI client hasn't started the MCP server process yet.
Solution: Send any testing prompt mentioning rstest to your AI assistant (e.g. "rstest check status"), or restart your AI desktop application (Claude Desktop, Cursor, etc.).

⚙️ Environment Variables

• RESPONSIVE_WS_PORT: WebSocket bridge port between MCP Server and Chrome Extension (Default: 8765).

📄 License

MIT © Responsive Tester Team

Authentication-aware test workflow

The server supplies testing instructions during MCP initialization and exposes the same instructions through responsive_test_workflow. Restart your MCP client/server after updating to load them. Client adherence is required: this is guidance, not an automatic authentication detector or a runtime enforcement mechanism.

Use this prompt to start:

Test the guest and signed-in flows on this site. First read responsive_test_workflow. Verify prerequisites before each case. Log out through the application for guest cases. If a signed-in case needs an account, use the authorized test account or ask me to sign in manually. Stop dependent cases when prerequisites cannot be met and report PASS, FAIL, or BLOCKED with evidence for each viewport.

| Required state | Observed state | Next step | | --- | --- | --- | | Signed out | Signed in | Use normal logout, then verify the signed-out UI. | | Signed in | Signed out | Use an authorized test account or request manual login; verify the required role. | | Either | Unknown | Inspect fresh evidence; request a missing selector or manual step if necessary. | | Matches the case | Verified | Run the case and collect evidence. |

Login-form cases normally require a signed-out starting state. Protected-feature cases require a signed-in state. Perform authentication actions on one explicit deviceId with sync:false: viewports may share a session. Recheck other viewports after the transition. The extension does not provide separate user sessions per viewport or a DOM inspection tool. Do not guess selectors, erase browser-wide storage, or retry failed credentials in a loop. Keep credentials out of reports.