<p align="center">
  <img src="docs/assets/banner.png" alt="MCP-ChromeCyber Banner" width="100%" />
</p>

<p align="center">
  <a href="https://bun.sh/"><img src="https://img.shields.io/badge/Runtime-Bun%201.3.14+-fbf0df?style=flat-square&logo=bun&logoColor=black" alt="Bun"></a>
  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.x-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"></a>
  <a href="https://developer.chrome.com/docs/extensions/mv3/intro/"><img src="https://img.shields.io/badge/Chrome-Manifest%20V3-4285F4?style=flat-square&logo=googlechrome&logoColor=white" alt="Chrome MV3"></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Streamable%20HTTP-8B5CF6?style=flat-square" alt="MCP Protocol"></a>
  <a href="https://golang.org/"><img src="https://img.shields.io/badge/Sidecar-Go%201.22+-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go Sidecar"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="MIT License"></a>
</p>

# MCP-ChromeCyber

A Model Context Protocol (MCP) bridge connecting AI agents to a live Chrome browser for automation and authorized security testing. CyberMCP Engine combines a Manifest V3 extension, Bun native host, and Go background worker for DOM inspection, network capture/replay, session-aware browser actions, and bounded background jobs.

This repository starts with a fresh Git history. Required licenses and contributor attribution are retained. Installed dependencies, local environment files, databases, traffic captures, QA reports, rollback copies, build outputs, and optional bulk wordlists are not distributed as source.

<p align="center">
  <a href="#quick-start"><b>Quick Start</b></a> •
  <a href="#capabilities"><b>Capabilities</b></a> •
  <a href="docs/4-architecture/05-codebase-map.md"><b>Architecture</b></a> •
  <a href="docs/3-tool-reference/"><b>Tool Reference</b></a> •
  <a href="docs/1-getting-started/01-installation-and-setup.md"><b>Setup Guide</b></a>
</p>

---

## Capabilities

| Feature                          | Description                                                                                           |
| -------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Parameter Mining**             | Discovery of hidden query, body, or header parameters using binary-search techniques.                 |
| **Intruder Fuzzing**             | Position-based fuzzing engine supporting configurable payload lists.                                  |
| **HTTP/2 Smuggling**             | Scans and test execution for desynchronization issues (CL.TE, TE.CL, H2 downgrade).                   |
| **Out-of-Band (OOB) Detection**  | Integration with OOB lookup services (e.g., Interactsh) to flag blind SSRF, Log4Shell, and blind XSS. |
| **DNS Rebinding**                | Controlled UDP DNS server for testing Cloud metadata and internal-service exposures.                  |
| **Session Macros**               | Automated macro execution with authentication maintenance and CSRF token refresh.                     |
| **Agent-Owned Scope**            | The connecting agent and operator define authorized targets; no MCP scope-manager setup is required.  |
| **Independent Burp Integration** | Call Burp MCP directly for Burp-managed HTTP. Chrome MCP does not configure a proxy.                  |
| **Go Runner Sidecar**            | Async runner for background and high-concurrency attack payloads.                                     |
| **Screenshots & DOM**            | Captures page layout, accessibility trees, and simulates interactions (click, type).                  |
| **DOM Vulnerability Scan**       | Taint tracking, prototype pollution detection, and DOM clobbering audits.                             |
| **Cookie & Storage**             | Manipulates cookies and storage values across tabs.                                                   |
| **Record & Replay**              | Replays recorded browser sequences for automated regression or validation testing.                    |

## Prerequisites

- **Node.js**: Version 20 or newer
- **Bun**: Version 1.3.14 or newer (the host uses built-in `bun:sqlite`)
- **Go**: Version 1.22 or newer to build the background worker
- **Google Chrome** (latest stable release)
- An **MCP-compatible client** (e.g., VS Code, Claude Desktop, Cursor, Windsurf, or Claude Code CLI)

## Quick Start

```bash
# 1. Clone the repository
git clone https://github.com/Hakchandara/MCP-ChromeCyber.git
cd MCP-ChromeCyber

# 2. Copy the environment file (sets a deterministic extension ID)
cp app/chrome-extension/.env.example app/chrome-extension/.env.local

# 3. Install dependencies
bun install --frozen-lockfile

# 4. Build all packages
bun run build

# 5. Register the Native Messaging Host
bun run bridge:register:dev

# 6. Start the local MCP server
bun run bridge:start:http
```

Verify that the server is active:

```bash
curl http://127.0.0.1:12306/ping
# Inspect the actual response; a healthy host alone does not prove Chrome is connected.
```

### Choose a Different Port

`12306` is the default local port. For a shell-managed launch, set the port in
the same environment that starts the bridge:

```bash
CHROME_MCP_PORT=12307 bun run bridge:start:http
curl http://127.0.0.1:12307/ping
```

For an extension-managed bridge, choose the port in the popup before clicking
Connect. The value is saved only once the bridge confirms it started. See
[Port Configuration](docs/1-getting-started/04-port-configuration.md).

### Loading the Chrome Extension

1. Build a candidate without modifying the extension directory Chrome may have open:
   `bun run build:extension:staged`.
2. Navigate to `chrome://extensions/` in Google Chrome.
3. Enable **Developer mode** in the top-right corner.
4. Click **Load unpacked** → select
   `app/chrome-extension/.output/browser-mcp-staged/chrome-mv3/`.
5. Ensure the Extension ID matches `bdmhjbdmgecbjalpefbpmogmnipbnfhf`.
6. Open the extension popup or dashboard and verify the bridge status is active.

The staged build keeps a complete, previously-loaded extension intact if Chrome
locks a live asset while WXT builds. It is the recommended release workflow on
Windows.

## Client Configuration

Start browser work with `chrome_get_session_context` and reuse the task-owned primary tab. Use exact tab/origin context, keep recovery tokens private, and clean up owned observers and helpers explicitly. Do not create new windows or resend uncertain operations to escape a timeout. Live tool schemas and availability metadata are authoritative; visual diff is currently registered but unavailable. See the [agent runbook](.agents/skills/chrome-cyber-mcp/SKILL.md).

This repository includes pre-configured settings for VS Code and GitHub Copilot. For other environments, refer to the configs below.

### VS Code

The `.vscode/mcp.json` file is included in this workspace:

```json
{
  "servers": {
    "chromeMcp": {
      "type": "http",
      "url": "http://127.0.0.1:12306/mcp"
    }
  }
}
```

### GitHub Copilot CLI

A `.mcp.json` configuration is included:

```json
{
  "mcpServers": {
    "chromeMcp": {
      "type": "http",
      "url": "http://127.0.0.1:12306/mcp",
      "tools": ["*"]
    }
  }
}
```

### Claude Desktop

Add the following to your configuration file (located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "chromeMcp": {
      "command": "mcp-chrome-stdio"
    }
  }
}
```

### Claude Code CLI

```bash
claude mcp add chromeMcp --transport http http://127.0.0.1:12306/mcp
```

### Cursor / Windsurf

Add a new HTTP server in your IDE's MCP settings:

- **Name**: `chromeMcp`
- **URL**: `http://127.0.0.1:12306/mcp`

For detailed setup instructions, see [docs/1-getting-started/02-mcp-client-config.md](docs/1-getting-started/02-mcp-client-config.md).

## Architecture

```mermaid
flowchart TD
    A[AI Agent]
    B[Native Server]
    C[Chrome Extension]
    D[Go Runner Sidecar]
    E[Job Result Store]

    A -->|HTTP/MCP| B
    B -->|Native Messaging| C
    B -->|HTTP/REST| D
    D -->|jobId| E
    E -.->|Poll status| A
```

The native server listens on loopback (`127.0.0.1`) and defaults to port `12306`.
It supports the following transport options:

- **HTTP**: `POST /mcp` + `GET /mcp` (Standard MCP 2024 transport)
- **SSE**: `GET /sse` + `POST /messages`
- **stdio**: via the `mcp-chrome-stdio` binary proxy

## Documentation

### Optional wordlists and runtime assets

Large SecLists, PortSwigger and custom fuzzing datasets are optional local resources, not bundled repository content. Built-in fallback lists remain available; extended payload-source selections require the corresponding dataset. See [local resource setup](Third-Party/README.md) and review each upstream license before downloading or redistributing it.

The ONNX browser runtime files under `app/chrome-extension/workers/` and `public/libs/` are required by the similarity worker and are intentionally retained. They are not stale build output. See [third-party notices](THIRD-PARTY-LICENSES.md).

| Document                                                                    | Description                                                             |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [Installation & Setup](docs/1-getting-started/01-installation-and-setup.md) | Standard build process, local registration, and extension loading.      |
| [MCP Client Configuration](docs/1-getting-started/02-mcp-client-config.md)  | Client-specific configurations and connection details.                  |
| [Troubleshooting & FAQ](docs/1-getting-started/03-troubleshooting-faq.md)   | Port conflicts, Native Messaging host manifests, and module resolution. |
| [Port Configuration](docs/1-getting-started/04-port-configuration.md)       | Choose, verify, and use a custom loopback port.                         |
| [Agent Playbooks](docs/2-agent-playbooks/README.md)                         | Playbooks and execution guidelines for target analyses.                 |
| [Tool Reference](docs/3-tool-reference/12-complete-reference.md)            | List of MCP-exposed tools and schemas.                                  |
| [Architecture](docs/4-architecture/01-system-architecture.md)               | Detailed layout of data flows and subsystems.                           |
| [Developer Guide](docs/5-internal/DEVELOPER-GUIDE.md)                       | Contributing guidelines, test setups, and styling conventions.          |