browser-devtools-mcp 0.2.2 → 0.2.4

package/README.md

@@ -10,14 +10,34 @@
 </p>
 
 <p align="center">
-A powerful <a href="https://modelcontextprotocol.io">Model Context Protocol (MCP)</a> server that provides AI coding assistants with comprehensive browser automation and debugging capabilities using Playwright. This server enables both <strong>execution-level debugging</strong> (logs, network requests) and <strong>visual debugging</strong> (screenshots, ARIA snapshots) to help AI assistants understand and interact with web pages effectively.
+A powerful <a href="https://modelcontextprotocol.io">Model Context Protocol (MCP)</a> server that provides AI coding assistants with comprehensive automation and debugging capabilities across multiple platforms. This server enables both <strong>execution-level debugging</strong> (logs, network requests) and <strong>visual debugging</strong> (screenshots, accessibility snapshots) to help AI assistants understand and interact with applications effectively.
 </p>
 
 ## Overview
 
-Browser DevTools MCP exposes a Playwright-powered browser runtime to AI agents, enabling deep, bidirectional debugging and interaction with live web pages. It supports both visual understanding and code-level inspection of browser state, making it ideal for AI-driven exploration, diagnosis, and automation.
+Browser DevTools MCP is a platform-extensible MCP server designed to give AI agents deep inspection and control over application runtimes. The architecture supports multiple platforms through a unified interface, with each platform providing specialized tools for its environment.
 
-### Key Capabilities
+### Supported Platforms
+
+| Platform | Description | Status |
+|----------|-------------|--------|
+| **Browser** | Playwright-powered browser automation with full DevTools integration | ✅ Available |
+| **Node** | Non-blocking debugging for Node.js backend processes via Inspector Protocol | ✅ Available |
+
+The **Browser Platform** exposes a Playwright-powered browser runtime to AI agents, enabling deep, bidirectional debugging and interaction with live web pages. It supports both visual understanding and code-level inspection of browser state, making it ideal for AI-driven exploration, diagnosis, and automation.
+
+The **Node Platform** provides non-blocking debugging for Node.js backend processes. It connects to running Node.js processes via the Inspector Protocol (Chrome DevTools Protocol over WebSocket) and offers tracepoints, logpoints, exceptionpoints, watch expressions, and source map support—ideal for debugging APIs, workers, and server-side code.
+
+### Platform Selection
+
+Choose the platform by running the appropriate MCP server or CLI:
+
+| Use Case | MCP Server | CLI |
+|----------|------------|-----|
+| Browser automation & debugging | `browser-devtools-mcp` | `browser-devtools-cli` |
+| Node.js backend debugging | `node-devtools-mcp` | `node-devtools-cli` |
+
+### Browser Platform Capabilities
 
 - **Visual Inspection**: Screenshots, ARIA snapshots, HTML/text extraction, PDF generation
 - **Design Comparison**: Compare live page UI against Figma designs with similarity scoring
@@ -29,7 +49,16 @@ Browser DevTools MCP exposes a Playwright-powered browser runtime to AI agents,
 - **Session Management**: Long-lived, session-based debugging with automatic cleanup
 - **Multiple Transport Modes**: Supports both stdio and HTTP transports
 
-## Features
+### Node Platform Capabilities
+
+- **Connection**: Connect to Node.js processes by PID, process name, port, WebSocket URL, or Docker container
+- **Non-Blocking Debugging**: Tracepoints, logpoints, exceptionpoints without pausing execution
+- **JavaScript Execution**: Run arbitrary JavaScript in the connected Node process via `run_js-in-node` (CDP Runtime.evaluate)—inspect `process.memoryUsage()`, call `require()` modules, read globals
+- **Source Map Support**: Resolves bundled/minified code to original source locations; `debug_resolve-source-location` translates stack traces and bundle locations to original source
+- **OpenTelemetry Integration**: When the Node process uses `@opentelemetry/api`, tracepoint/logpoint snapshots automatically include `traceContext` (traceId, spanId) for correlating backend traces with browser traces
+- **Docker Support**: Connect to Node.js processes running inside Docker containers (`containerId` / `containerName`)
+
+## Browser Platform Features
 
 ### Content Tools
 - **Screenshots**: Capture full page or specific elements (PNG/JPEG) with image data
@@ -109,6 +138,7 @@ Non-blocking debugging tools that capture snapshots without pausing execution. I
 - `clear-*-snapshots`: Clear captured snapshots
 
 **Additional Tools:**
+- **Resolve Source Location**: Resolve a generated/bundle location (URL + line + column) to original source via source maps—useful for translating minified stack traces
 - **Watch Expressions**: Add expressions to evaluate at every tracepoint/exceptionpoint hit
 - **Status**: Get current debugging status (enabled, probe counts, snapshot stats)
 
@@ -117,6 +147,7 @@ Non-blocking debugging tools that capture snapshots without pausing execution. I
 - Automatic debugging enablement on first tool use
 - Configurable limits (max snapshots, call stack depth, async segments)
 - Sequence numbers for efficient snapshot polling
+- OpenTelemetry trace context in Node snapshots (traceId, spanId when process uses @opentelemetry/api)
 
 ## Prerequisites
 
@@ -148,12 +179,29 @@ This installs the CLI skill that enables AI agents to automate browsers for web
 
 ## MCP Client Configuration
 
-### Claude Desktop
+To use the **Node platform** (Node.js backend debugging), use `node-devtools-mcp` instead of `browser-devtools-mcp`:
+
+```json
+{
+  "mcpServers": {
+    "node-devtools": {
+      "command": "npx",
+      "args": ["-y", "-p", "browser-devtools-mcp", "node-devtools-mcp"]
+    }
+  }
+}
+```
+
+Alternatively, set `PLATFORM=node` when running `browser-devtools-mcp`.
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
 
 #### Local Server
 Add the following configuration into the `claude_desktop_config.json` file.
 See the [Claude Desktop MCP docs](https://modelcontextprotocol.io/docs/develop/connect-local-servers) for more info.
 
+**Browser platform (default):**
 ```json
 {
   "mcpServers": {
@@ -165,6 +213,18 @@ See the [Claude Desktop MCP docs](https://modelcontextprotocol.io/docs/develop/c
 }
 ```
 
+**Node platform:**
+```json
+{
+  "mcpServers": {
+    "node-devtools": {
+      "command": "npx",
+      "args": ["-y", "-p", "browser-devtools-mcp", "node-devtools-mcp"]
+    }
+  }
+}
+```
+
 #### Remote Server (HTTP Transport)
 First, start the server with HTTP transport:
 ```bash
@@ -175,7 +235,10 @@ Then, go to `Settings` > `Connectors` > `Add Custom Connector` in Claude Desktop
 - Name: `Browser DevTools`
 - Remote MCP server URL: Point to where your server is hosted (e.g., `http://localhost:3000/mcp` if running locally, or `https://your-server.com/mcp` if hosted remotely)
 
-### Claude Code
+</details>
+
+<details>
+<summary><strong>Claude Code</strong></summary>
 
 Run the following command.
 See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info.
@@ -198,7 +261,10 @@ claude mcp add --transport http browser-devtools <SERVER_URL>
 
 Replace `<SERVER_URL>` with your server URL (e.g., `http://localhost:3000/mcp` if running locally, or `https://your-server.com/mcp` if hosted remotely).
 
-### Cursor
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
 
 Add the following configuration into the `~/.cursor/mcp.json` file (or `.cursor/mcp.json` in your project folder).
 See the [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.
@@ -234,7 +300,10 @@ Then add the configuration:
 
 Replace `<SERVER_URL>` with your server URL (e.g., `http://localhost:3000/mcp` if running locally, or `https://your-server.com/mcp` if hosted remotely).
 
-### VS Code
+</details>
+
+<details>
+<summary><strong>VS Code</strong></summary>
 
 Add the following configuration into the `.vscode/mcp.json` file.
 See the [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.
@@ -276,7 +345,10 @@ Then add the configuration:
 
 Replace `<SERVER_URL>` with your server URL (e.g., `http://localhost:3000/mcp` if running locally, or `https://your-server.com/mcp` if hosted remotely).
 
-### Windsurf
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
 
 Add the following configuration into the `~/.codeium/windsurf/mcp_config.json` file. 
 See the [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp) for more info.
@@ -312,7 +384,10 @@ Then add the configuration:
 
 Replace `<SERVER_URL>` with your server URL (e.g., `http://localhost:3000/mcp` if running locally, or `https://your-server.com/mcp` if hosted remotely).
 
-### Copilot Coding Agent
+</details>
+
+<details>
+<summary><strong>Copilot Coding Agent</strong></summary>
 
 Add the following configuration to the `mcpServers` section of your Copilot Coding Agent configuration through 
 `Repository` > `Settings` > `Copilot` > `Coding agent` > `MCP configuration`.
@@ -351,7 +426,10 @@ Then add the configuration:
 
 Replace `<SERVER_URL>` with your server URL (e.g., `http://localhost:3000/mcp` if running locally, or `https://your-server.com/mcp` if hosted remotely).
 
-### Gemini CLI
+</details>
+
+<details>
+<summary><strong>Gemini CLI</strong></summary>
 
 Add the following configuration into the `~/.gemini/settings.json` file.
 See the [Gemini CLI MCP docs](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) for more info.
@@ -387,7 +465,10 @@ Then add the configuration:
 
 Replace `<SERVER_URL>` with your server URL (e.g., `http://localhost:3000/mcp` if running locally, or `https://your-server.com/mcp` if hosted remotely).
 
-### Smithery
+</details>
+
+<details>
+<summary><strong>Smithery</strong></summary>
 
 Run the following command.
 You can find your Smithery API key [here](https://smithery.ai/account/api-keys).
@@ -397,6 +478,8 @@ See the [Smithery CLI docs](https://smithery.ai/docs/concepts/cli) for more info
 npx -y @smithery/cli install serkan-ozal/browser-devtools-mcp --client <SMITHERY-CLIENT-NAME> --key <SMITHERY-API-KEY>
 ```
 
+</details>
+
 ## HTTP Transport
 
 To use HTTP transport, start the server with:
@@ -430,9 +513,14 @@ npx -y browser-devtools-mcp --transport=streamable-http --port=3000
 npx -y @modelcontextprotocol/inspector http://localhost:3000/mcp --transport http
 ```
 
-## CLI Tool
+## CLI Tools
+
+Browser DevTools MCP includes standalone CLI tools for both platforms:
+
+- **`browser-devtools-cli`**: Browser platform—navigation, screenshots, interaction, a11y, debugging, etc.
+- **`node-devtools-cli`**: Node platform—connect to Node.js processes, tracepoints, logpoints, exceptionpoints
 
-Browser DevTools MCP includes a standalone CLI tool (`browser-devtools-cli`) for direct command-line access to browser automation capabilities. This is particularly useful for:
+This is particularly useful for:
 
 - **Scripting and automation**: Use in shell scripts, CI/CD pipelines, or automated workflows
 - **Session-based testing**: Maintain browser state across multiple commands with session IDs
@@ -440,15 +528,17 @@ Browser DevTools MCP includes a standalone CLI tool (`browser-devtools-cli`) for
 
 ### Installation
 
-The CLI is included with the npm package:
+The CLIs are included with the npm package:
 
 ```bash
 # Run directly with npx
-npx -y browser-devtools-mcp browser-devtools-cli --help
+npx -y browser-devtools-cli --help
+npx -y node-devtools-cli --help
 
 # Or install globally
 npm install -g browser-devtools-mcp
 browser-devtools-cli --help
+node-devtools-cli --help
 ```
 
 ### Global Options
@@ -474,9 +564,34 @@ browser-devtools-cli --help
 
 **Note:** Browser options are applied when the daemon server starts. If the daemon is already running, stop it first (`daemon stop`) then start with new options.
 
-### Commands
+### Node CLI Commands
+
+`node-devtools-cli` provides Node.js backend debugging:
+
+```
+node-devtools-cli
+├── daemon                    # Manage the daemon server
+├── session                   # Manage Node.js debugging sessions
+├── tools                     # List and inspect available tools
+├── config                    # Show current configuration
+├── completion                # Generate shell completion scripts
+├── interactive (repl)        # Start interactive REPL mode
+├── update                    # Check for updates
+├── run                       # Script execution commands
+│   └── js-in-node            # Run JavaScript in the connected Node process
+└── debug                     # Debug commands
+    ├── connect               # Connect to Node.js process (pid, processName, port, containerId, etc.)
+    ├── disconnect            # Disconnect from current process
+    ├── status                # Show connection status
+    ├── put-tracepoint        # Set a tracepoint
+    ├── put-logpoint          # Set a logpoint
+    ├── put-exceptionpoint    # Configure exception catching
+    └── ...                   # Watch, snapshots, probes management
+```
+
+### Browser CLI Commands
 
-The CLI organizes tools into domain-based subcommands:
+`browser-devtools-cli` organizes tools into domain-based subcommands:
 
 ```
 browser-devtools-cli
@@ -997,7 +1112,9 @@ For the full list of available skills and documentation, see the [browser-devtoo
 
 ## Configuration
 
-The server can be configured using environment variables:
+The server can be configured using environment variables. Configuration is divided into server-level settings and platform-specific settings.
+
+### Server Configuration
 
 | Variable | Description | Default |
 |----------|-------------|---------|
@@ -1005,6 +1122,18 @@ The server can be configured using environment variables:
 | `SESSION_IDLE_SECONDS` | Idle session timeout (seconds) | `300` |
 | `SESSION_IDLE_CHECK_SECONDS` | Interval for checking idle sessions (seconds) | `30` |
 | `SESSION_CLOSE_ON_SOCKET_CLOSE` | Close session when socket closes | `false` |
+
+### Node Platform Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NODE_CONSOLE_MESSAGES_BUFFER_SIZE` | Maximum console messages to buffer from Node.js process | `1000` |
+| `PLATFORM` | Platform to use: `browser` or `node` | `browser` |
+
+### Browser Platform Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
 | `CONSOLE_MESSAGES_BUFFER_SIZE` | Maximum console messages to buffer | `1000` |
 | `HTTP_REQUESTS_BUFFER_SIZE` | Maximum HTTP requests to buffer | `1000` |
 | `BROWSER_HEADLESS_ENABLE` | Run browser in headless mode | `true` |
@@ -1023,7 +1152,7 @@ The server can be configured using environment variables:
 | `FIGMA_ACCESS_TOKEN` | Figma API access token for design comparison | (none) |
 | `FIGMA_API_BASE_URL` | Figma API base URL | `https://api.figma.com/v1` |
 
-## Available Tools
+## Browser Platform Tools
 
 ### Content Tools
 
@@ -1321,6 +1450,33 @@ The server can be configured using environment variables:
 - The timeoutMs parameter limits synchronous execution time, but does not automatically time out awaited Promises
 </details>
 
+<details>
+<summary><code>run_js-in-node</code> - Runs custom JavaScript INSIDE the connected Node.js process (Node platform only).</summary>
+
+**Parameters:**
+- `script` (string, required): JavaScript code to execute in the Node process
+- `timeoutMs` (number, optional): Max evaluation time in milliseconds (default: 5000, max: 30000)
+
+**Returns:**
+- `result` (any): The result of the evaluation. Can be primitives, arrays, or objects. Must be serializable (JSON-compatible).
+
+**Notes:**
+- Requires `debug_connect` first—must be connected to a Node.js process
+- Executes in the NODE PROCESS CONTEXT (real Node.js environment):
+  - Has access to process, require, global, and all loaded modules
+  - Can read/modify process state
+  - Full Node.js APIs (fs, http, etc.)
+- Execution blocks the Node event loop until the script completes
+- Long-running scripts will block the process; use short expressions
+- Return value must be serializable
+
+**Typical use cases:**
+- Inspect process state: `process.memoryUsage()`, `process.uptime()`
+- Call loaded modules: `require('os').loadavg()`
+- Read globals or cached data
+- One-off diagnostic commands
+</details>
+
 ### Observability (O11Y) Tools
 
 <details>
@@ -1693,17 +1849,27 @@ The server can be configured using environment variables:
 
 ## Architecture
 
+### Platform Architecture
+
+Browser DevTools MCP is built on a platform-extensible architecture that allows for supporting multiple runtime environments through a unified MCP interface. Each platform provides:
+
+- **Platform-specific tools**: Specialized tools optimized for the target environment
+- **Unified session management**: Consistent session handling across platforms
+- **Shared infrastructure**: Common transport, configuration, and plugin systems
+
+The **Browser Platform** is powered by Playwright for comprehensive browser automation and DevTools integration. The **Node Platform** provides non-blocking debugging for Node.js backend processes via the Chrome DevTools Protocol over WebSocket.
+
 ### Session Management
 
-The server uses session-based architecture where each MCP client connection gets its own browser context and page. Sessions are automatically cleaned up when:
+The server uses session-based architecture where each MCP client connection gets its own isolated runtime context. For the Browser platform, this means each session gets its own browser context and page. Sessions are automatically cleaned up when:
 
 - The client disconnects
 - The session becomes idle (configurable timeout)
 - The session is explicitly closed
 
-### Browser Support
+### Browser Platform Details
 
-The server supports multiple browser engines:
+The Browser platform supports multiple browser engines:
 - **Chromium** (default)
 - **Firefox**
 - **WebKit**
@@ -1809,9 +1975,18 @@ npm run build
 
 ## Use Cases
 
-### For AI Coding Assistants
+### Node Platform Use Cases
+
+The Node platform enables AI assistants to:
+
+1. **Debug Node.js APIs**: Connect to a running server, set tracepoints at API handlers, capture request/response context
+2. **Inspect Backend State**: Use watch expressions and tracepoints to understand variable values, call stacks
+3. **Catch Exceptions**: Enable exception breakpoints to capture uncaught errors with full stack traces
+4. **Docker Debugging**: Connect to Node.js processes running inside Docker containers
+
+### Browser Platform Use Cases
 
-This server enables AI assistants to:
+The Browser platform enables AI assistants to:
 
 1. **Debug Web Applications**: Capture screenshots, inspect DOM, check console errors
 2. **Monitor Network Activity**: Track API calls, analyze request/response patterns
@@ -1842,13 +2017,13 @@ Browser DevTools MCP is available as a plugin for various AI coding assistants.
 
 ### Claude Code
 
-A dedicated Claude Code plugin is available with slash commands, skills, and agents for browser automation and testing.
+A dedicated Claude Code plugin is available with slash commands, skills, and agents for browser automation and testing. The plugin lives in a [separate repository](https://github.com/serkan-ozal/browser-devtools-claude).
 
 #### Installation
 
 ```bash
 # Add the marketplace
-/plugin marketplace add https://github.com/serkan-ozal/browser-devtools-mcp
+/plugin marketplace add https://github.com/serkan-ozal/browser-devtools-claude
 
 # Install the plugin
 /plugin install browser-devtools-mcp@browser-devtools
@@ -1867,9 +2042,10 @@ A dedicated Claude Code plugin is available with slash commands, skills, and age
 - Design: `/figma`
 - Execution: `/run-js`, `/sandbox`
 
-**Skills (5 skills):**
+**Skills (6 skills):**
 - `browser-testing` - General browser test capabilities
 - `web-debugging` - Console, network, JS debugging
+- `node-debugging` - Node.js backend debugging (tracepoints, logpoints, run_js-in-node)
 - `performance-audit` - Web Vitals and performance analysis
 - `visual-testing` - Visual testing and responsive design
 - `observability` - Distributed tracing and monitoring
@@ -1883,7 +2059,7 @@ A dedicated Claude Code plugin is available with slash commands, skills, and age
 
 #### Configuration
 
-The plugin can be configured via environment variables. See [CONFIG.md](plugins/claude/CONFIG.md) for all available options.
+The plugin can be configured via environment variables. See [CONFIG.md](https://github.com/serkan-ozal/browser-devtools-claude/blob/master/CONFIG.md) for all available options.
 
 Example configuration in `~/.claude/settings.json`:
 
@@ -1894,6 +2070,7 @@ Example configuration in `~/.claude/settings.json`:
       "command": "npx",
       "args": ["-y", "browser-devtools-mcp@latest"],
       "env": {
+        "PLATFORM": "browser",
         "BROWSER_HEADLESS_ENABLE": "false"
       }
     }

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export * from './provider';