# ChromePlayMCP

> A policy-aware security Meta-MCP server integrating Playwright MCP and Chrome DevTools MCP for AI coding assistants, security research agents, and automated web workflows.

[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP Specification](https://img.shields.io/badge/MCP-1.30%2B-informational.svg)](https://modelcontextprotocol.io/)

---

## Overview

**ChromePlayMCP** is a security-conscious Meta-MCP server designed to bridge [Playwright MCP](https://github.com/microsoft/playwright) and [Chrome DevTools MCP](https://github.com/ChromeDevTools/devtools-mcp). Rather than exposing dozens of granular, low-level browser automation commands that pollute LLM context windows and risk policy violations, ChromePlayMCP presents a high-level, semantic tool surface.

It manages a single, shared Chrome instance over the Chrome DevTools Protocol (CDP), enforcing strict target origin boundaries, redacting credential materials, and compiling structured JSON evidence bundles.

---

## Key Features

- **Unified CDP Execution**: Operates Playwright and Chrome DevTools over a single shared browser instance, ensuring full correlation between user actions, network traffic, DOM updates, and storage states.
- **Context-Efficient Tool Surface**: Exposes 5 high-level meta-tools instead of 50+ individual primitive browser calls, preserving model context budgets.
- **Strict Scope Enforcement**: Enforces an explicit origin whitelist policy, rejecting out-of-scope navigation attempts automatically.
- **Automated Secret Isolation & Redaction**: Reads credentials strictly from system environment variables and redacts passwords, session tokens, authorization headers, and JWT secrets before returning observations.
- **Non-Destructive Guarantee**: Disallows arbitrary script injection (`eval()`) and limits browser interaction to policy-reviewed actions.

---

## Feature Comparison

| Capability | Raw Upstream MCP Servers | ChromePlayMCP Orchestrator |
| :--- | :--- | :--- |
| **Tool Count** | 50+ low-level primitive tools | 5 domain-specific meta-tools |
| **Browser Instance** | Independent, disconnected contexts | Single shared Chrome CDP session (port 9222) |
| **Scope Control** | Unrestricted origin navigation | Configurable origin whitelist & subdomain policy |
| **Secret Protection** | Raw credential passing in prompts | Environment variable references & automated redaction |
| **Output Format** | Unstructured DOM snapshots | Structured JSON observations & artifact store |

---

## Architecture

```text
       AI Assistant (Claude Desktop / Claude Code / OpenCode / Antigravity / Cursor)
                                        |
                                        v
                               [ ChromePlayMCP ]
            (Scope Guard | Policy Engine | Secret Redactor | Artifact Store)
                                        |
                 +----------------------+----------------------+
                 |                                             |
                 v                                             v
       [ @playwright/mcp ]                          [ chrome-devtools-mcp ]
   (Navigation, Form Submits,                     (Network Tracing, Console,
   Authenticated Journeys)                       DOM Mutations, Storage)
                 |                                             |
                 +----------------------+----------------------+
                                        |
                                        v
                     Chrome Instance (CDP: 127.0.0.1:9222)
```

---

## Prerequisites

- **Node.js**: Version 20 LTS or higher.
- **Google Chrome**: Chrome 144+ recommended, with remote debugging enabled.
- **Operating System**: Linux, macOS, or Windows (PowerShell).

---

## Quick Start

### 1. Repository Setup

```bash
git clone https://github.com/MauricioDuarte100/ChromePlayMCP.git
cd ChromePlayMCP
npm install
npm run build
cp config/orchestrator.example.json config/orchestrator.json
```

### 2. Start Shared Chrome Profile

Launch a dedicated Chrome instance bound to loopback remote debugging on port `9222`:

**Linux / macOS:**
```bash
./scripts/start-chrome.sh 9222
export CDP_URL="http://127.0.0.1:9222"
```

**Windows (PowerShell):**
```powershell
.\scripts\start-chrome.ps1 -Port 9222
$env:CDP_URL = "http://127.0.0.1:9222"
```

### 3. Configure Authorized Target Scope

Edit `config/orchestrator.json` to define authorized target origins:

```json
{
  "targets": [
    {
      "id": "target-app",
      "allowedOrigins": ["https://example.com"],
      "allowSubdomains": false
    }
  ]
}
```

---

## Client Integration Setup

### Claude Code (CLI)

Register ChromePlayMCP in **Claude Code** using the `claude mcp add` command:

```bash
claude mcp add chrome-play-mcp \
  -e ORCHESTRATOR_CONFIG="/absolute/path/to/ChromePlayMCP/config/orchestrator.json" \
  -e CDP_URL="http://127.0.0.1:9222" \
  -- node /absolute/path/to/ChromePlayMCP/dist/index.js
```

Or reference [`config/claude-code.mcp.json`](config/claude-code.mcp.json).

---

### OpenCode Interpreter

Add to `.opencode/mcp.json` or `~/.config/opencode/mcp.json`:

```json
{
  "mcpServers": {
    "chrome-play-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ChromePlayMCP/dist/index.js"],
      "env": {
        "ORCHESTRATOR_CONFIG": "/absolute/path/to/ChromePlayMCP/config/orchestrator.json",
        "CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}
```

Or via OpenCode CLI:

```bash
opencode mcp add chrome-play-mcp -- node /absolute/path/to/ChromePlayMCP/dist/index.js
```

---

### Claude Desktop

Add to `~/.config/Claude/claude_desktop_config.json` (macOS/Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "chrome-play-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ChromePlayMCP/dist/index.js"],
      "env": {
        "ORCHESTRATOR_CONFIG": "/absolute/path/to/ChromePlayMCP/config/orchestrator.json",
        "CDP_URL": "http://127.0.0.1:9222",
        "BB_USERNAME": "research-user",
        "BB_PASSWORD": "research-password"
      }
    }
  }
}
```

---

### Antigravity / Kimi Code / Codex / AGY CLI

Copy [`config/kimi.mcp.json`](config/kimi.mcp.json) to `.kimi-code/mcp.json` or register via CLI:

```bash
kimi mcp add --transport stdio chrome_play_mcp -- node /absolute/path/to/ChromePlayMCP/dist/index.js
```

For **Codex**:

```bash
codex mcp add chrome_play_mcp --env ORCHESTRATOR_CONFIG=/absolute/path/to/ChromePlayMCP/config/orchestrator.json -- node /absolute/path/to/ChromePlayMCP/dist/index.js
```

---

### Cursor / VS Code / Windsurf

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

```json
{
  "mcpServers": {
    "chrome-play-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ChromePlayMCP/dist/index.js"],
      "env": {
        "ORCHESTRATOR_CONFIG": "${workspaceFolder}/config/orchestrator.json",
        "CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}
```

---

## Meta-Tools Reference

| Meta-Tool | Description |
| :--- | :--- |
| `login_and_capture_session` | Performs automated authentication via Playwright using environment variables, capturing tokens, cookies, and correlating storage/network signals via DevTools. |
| `map_frontend_attack_surface` | Maps forms, scripts, links, storage key names, console signals, and API endpoints for an in-scope page without body downloads or payload generation. |
| `trace_authenticated_user_flow` | Executes a bounded, multi-step Playwright user flow inside an active session while DevTools captures newly observed network endpoints. |
| `compare_anonymous_vs_authenticated_behavior` | Evaluates the same URL across authenticated and isolated anonymous contexts to identify access control deltas. |
| `export_browser_observations` | Compiles a redacted, structured JSON evidence package containing all observations and artifact references. |

---

## Security Model & Policy Engine

1. **Origin Filtering**: All requested URLs are validated against `allowedOrigins`. Out-of-scope targets trigger an immediate policy exception.
2. **Credential Protection**: Passwords and secrets are passed exclusively via named environment variable references (`usernameEnv`, `passwordEnv`). Raw secrets are scrubbed before logging or returning outputs.
3. **Non-Destructive Bounds**: Disallows execution of arbitrary JavaScript strings or unsafe browser evaluation modes.
4. **Local Binding**: Chrome remote debugging interfaces are bound exclusively to loopback (`127.0.0.1`).

---

## Verification & Testing

Verify system integrity using the included TypeScript checks and test suite:

```bash
# Perform TypeScript static type checking
npm run check

# Run unit tests
npm test
```

---

## Documentation Index

- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): System design, provider execution matrix, and policy engine specifications.
- [`docs/META_TOOLS.md`](docs/META_TOOLS.md): Detailed API contracts for meta-tools.
- [`docs/WORKFLOWS.md`](docs/WORKFLOWS.md): Comprehensive operational workflow examples.
- [`docs/HARDENING.md`](docs/HARDENING.md): Security hardening and isolation recommendations.

---

## License

Distributed under the MIT License. See [`LICENSE`](LICENSE) for details.