# Microsoft Edge MCP Server (microsoft-edge-mcp)

A native TypeScript/Node.js Model Context Protocol (MCP) server that provides low-level, high-performance control over the Microsoft Edge browser. Built using raw WebSockets (`ws`) to talk directly to Edge's Chrome DevTools Protocol (CDP) port, bypassing heavy automation layers like Playwright or Puppeteer.

---

## Features

### 🌟 Core CDP Capabilities
Full parity with `chrome-devtools-mcp` but optimized for Edge:
- **Navigation:** `navigate_page` (url, back, forward, reload)
- **Interaction:** `click`, `fill`, `fill_form` (multi-field), `hover`, `drag`, `press_key`, `type_text`
- **Page Management:** `list_pages`, `new_page`, `select_page` (reconnects active target), `close_page`
- **Observation:** `take_screenshot` (viewport/full page/element clip), `take_snapshot` (Accessibility Tree + lightweight DOM outline fallback)
- **Execution:** `evaluate_script` (JS execution in page context)
- **Console & Network:** `list_console_messages`, `get_console_message`, `list_network_requests`, `get_network_request` (captures response bodies)
- **Tracing & Performance:** `performance_start_trace`, `performance_stop_trace`, `performance_analyze_insight`

### 🌀 Edge-Exclusive Capabilities
Dedicated integration hooks exploiting Microsoft Edge's unique feature set:
- `edge_open_sidebar` — Opens specific sidebar panels (e.g., Copilot, Tools, Shopping) using internal Edge hooks or keyboard shortcuts.
- `edge_toggle_ie_mode` — Toggles Internet Explorer mode for legacy compatibility testing.
- `edge_list_sleeping_tabs` / `edge_wake_tab` — Exposes Edge's sleeping/discarded tab management states.
- `edge_add_to_collections` — Adds the current page to the user's Edge Collections.
- `edge_add_to_reading_list` — Integrates with Edge's reading list.
- `edge_web_capture` — Triggers Edge's native web clipping tool (`Ctrl+Shift+S`).
- `edge_open_settings` — Direct deep-links to browser internal settings page (`edge://settings/<path>`).
- `edge_check_compat` — Inspects the active document for IE/EdgeHTML compatibility meta tags and rendering modes.

---

## Enforced Design Principles (Ponytail senior dev style)
- **Zero Automation Wrappers:** No Puppeteer, Playwright, or Selenium. Automation goes through raw CDP JSON-RPC over WebSockets.
- **Binary Search Sequence:** Finds Edge by searching `EDGE_PATH` env var ➡️ OS Registry (Windows) ➡️ OS-specific default paths ➡️ `which msedge`.
- **Dynamic Port Allocation:** Launches debugging on port `9222`. If busy, it automatically increments to `9223`, using isolated port-specific user-data profiles to avoid locking conflicts.
- **Best-Effort Edge Tools:** Where Edge lacks native CDP hooks for UI features, fallback keyboard shortcut injections (`Input.dispatchKeyEvent`) or `Runtime.evaluate` scripts are used, marked cleanly with `ponytail:` comments mapping ceilings and upgrade paths.

---

## File Structure

```
microsoft-edge-mcp/
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── index.ts           # MCP server entry, stdio transport, tool registrations
│   ├── edge.ts            # Binary detection + auto-launch + port scanning
│   ├── cdp.ts             # Raw WebSocket CDP client & connection utilities
│   └── tools/
│       ├── navigation.ts  # navigate_page
│       ├── interaction.ts # click, hover, drag, press_key, type_text
│       ├── capture.ts     # take_screenshot, take_snapshot
│       ├── evaluate.ts    # evaluate_script
│       ├── network.ts     # list_network_requests, get_network_request
│       ├── console.ts     # list_console_messages, get_console_message
│       ├── pages.ts       # list_pages, new_page, select_page, close_page
│       ├── forms.ts       # fill, fill_form
│       ├── perf.ts        # performance_*
│       └── edge/          # Edge-exclusive tool handlers
│           ├── sidebar.ts
│           ├── ie_mode.ts
│           ├── sleeping_tabs.ts
│           ├── collections.ts
│           ├── reading_list.ts
│           ├── web_capture.ts
│           ├── settings.ts
│           └── compat.ts
└── self-check.ts          # Dependency-free integration tests
```

---

## Installation & Setup

### Prerequisites
- Node.js (Latest LTS recommended)
- Microsoft Edge installed on the host machine

### One-Line Auto-Install (Via GitHub)
To automatically download, compile, and configure this MCP server inside your **Antigravity** and **Claude Desktop** config files in a single command, run:
```bash
npx -y github:RawKnuck/microsoft-edge-mcp --install
```

### Local Installation & Registration (Cloned)
If you have cloned the repository locally, you can build the project and auto-register it with both Antigravity and Claude Desktop by running:
```bash
npm run configure
```

Alternatively, to manually build and test:
1. Install dependencies:
   ```bash
   npm install
   ```
2. Compile TypeScript:
   ```bash
   npm run build
   ```
3. Run Automated Self-Checks:
   ```bash
   node build/self-check.js
   ```

---

## Agent Setup & Compatibility

This MCP server is built using standard Model Context Protocol `stdio` transport, ensuring compatibility with all major agentic platforms.

### 1. Antigravity (Google DeepMind Agentic IDE)
- **Automatic Configuration:** Run the one-line install command above. It automatically registers the server in `~/.gemini/config/mcp_config.json`.
- **Manual Configuration:** Open your `~/.gemini/config/mcp_config.json` (or select "Manage MCP Servers" -> "View raw config" in the agent panel) and add:
  ```json
  {
    "servers": {
      "microsoft-edge-mcp": {
        "command": "npx",
        "args": ["-y", "github:RawKnuck/microsoft-edge-mcp"]
      }
    }
  }
  ```

### 2. Claude Desktop
- **Automatic Configuration:** Run the one-line install command above. It automatically registers the server in your `claude_desktop_config.json`.
- **Manual Configuration:** Add the following to your `claude_desktop_config.json`:
  ```json
  {
    "mcpServers": {
      "microsoft-edge-mcp": {
        "command": "npx",
        "args": ["-y", "github:RawKnuck/microsoft-edge-mcp"]
      }
    }
  }
  ```

### 3. Cursor
1. Go to **Settings > Features > MCP**.
2. Click **+ Add New MCP Server**.
3. Fill in the following fields:
   - **Name:** `microsoft-edge-mcp`
   - **Type:** `command`
   - **Command:** `npx -y github:RawKnuck/microsoft-edge-mcp`
4. Click **Save**.

### 4. Windsurf
1. Go to **Settings > Advanced > MCP**.
2. Click **Add Server**.
3. Fill in the following fields:
   - **Name:** `microsoft-edge-mcp`
   - **Type:** `command`
   - **Command:** `npx -y github:RawKnuck/microsoft-edge-mcp`
4. Click **Save**.

### 5. Cline / Roo Code (VS Code Extensions)
Open your extension settings file (e.g., `cline_mcp_settings.json` or `roo_code_mcp_settings.json`) and append:
```json
{
  "mcpServers": {
    "microsoft-edge-mcp": {
      "command": "npx",
      "args": ["-y", "github:RawKnuck/microsoft-edge-mcp"]
    }
  }
}
```

### 6. Aider
Create or update your `.aider.conf.yml` file to include:
```yaml
mcp-servers:
  microsoft-edge-mcp:
    command: npx
    args: ["-y", "github:RawKnuck/microsoft-edge-mcp"]
```

### 7. Claude Code (CLI Agent)
Run the following command in your terminal to register the server:
```bash
/plugin add github:RawKnuck/microsoft-edge-mcp
```