# Remote PC MCP Gateway (ChatGPT & Google Gemini)

English | **[简体中文文档 (README.zh-CN.md)](./README.zh-CN.md)**

Turn your Windows 10/11 PC into a secure, OAuth 2.1 authenticated **Model Context Protocol (MCP)** workstation that both **OpenAI ChatGPT Web (`https://chatgpt.com/`)** and **Google Gemini Web (`https://gemini.google.com/`)** can connect to simultaneously — with **zero extra local admin ports**, a **native Windows Bilingual Control Panel + System Tray**, and **flexible public HTTPS ingress** (30-second Serverless Cloudflare Quick/Named Tunnel **or** 1-Click Non-Destructive Linux VPS with zero-domain `sslip.io` Auto-HTTPS).

![Windows Control Panel Dashboard](./docs/assets/gui-dashboard-en.png)

---

## Key Highlights

- **Dual-Client Concurrent Access (`ChatGPT` + `Google Gemini`)**: Connect both ChatGPT Web and Google Gemini Web to the exact same HTTPS MCP URL at the same time. Full **OAuth 2.1 + PKCE (`S256`) + Dynamic Client Registration (`/oauth/register`)** + MCP tool safety annotations (`readOnlyHint` / `destructiveHint`) work out of the box with **zero manual Client IDs or Client Secrets**.
- **Three Flexible Public HTTPS Ingress Options (Switchable Anytime)**:
  - **Mode A1 — Serverless Cloudflare Quick Tunnel (Zero Account / Ready in 30s)**: Spawns `cloudflared` locally, captures your dynamic `https://*.trycloudflare.com` origin, aligns `OAUTH_ISSUER`, and **auto-detects `198.18.0.0/15` Clash/Mihomo/Sing-box TUN Fake-IP environments** to switch to QUIC + Cloudflare Anycast Edge IPs seamlessly (eliminating `Error 1033`).
  - **Mode A2 — Serverless Cloudflare Named Tunnel (Zero VPS / Permanent Domain)**: Paste your Cloudflare hostname and Tunnel Token in Step 1 of the GUI for a permanent HTTPS URL without renting a VPS.
  - **Mode B — 1-Click Non-Destructive Linux VPS (`Ubuntu/Debian`)**: Automated provisioning (`deploy/deploy-to-vps.ps1` + `deploy/install-vps.sh`) using a dedicated `/etc/caddy/conf.d/remote-pc-mcp-gateway.caddy` drop-in + automatic `Caddyfile` backup (**never overwrites pre-existing websites on your server**), supporting custom domains or **zero-domain free `mcp.<ip>.sslip.io` Let's Encrypt TLS**.
- **Zero-Port Native Windows Client + System Tray**: Double-click `Start-GUI.bat` for a clean bilingual (`EN / 中文`) Setup Wizard, live 5-service health strip, auto-generated persistent credentials (masked by default for screen sharing), folder list management, arrow-key wraparound navigation, and a right-click **System Tray (`NotifyIcon`)** menu.
- **5-Layer Defense-in-Depth Windows Sandbox**:
  - **Strict `allowedRoots` Path Sandbox**: Every `fs_*` (with cross-platform `..` traversal normalization and fast `rg --files` pruning) and read-only `git_*` call is strictly confined to your approved workspace folders.
  - **Per-Tab Shared Chrome Isolation (`pageId`)**: Reuses your existing `--remote-debugging-port=9222` Chrome while patching `chrome-devtools-mcp@1.5.0` so cloud sessions must target explicit `pageId` tabs without touching your personal tabs.
  - **Native Job Object Process-Tree Supervision (`WorkbenchJob.exe`) & Auto-Review**: PowerShell 7 commands (`run_command`) execute inside a Win32 Job Object (`KILL_ON_JOB_CLOSE`) with zero orphan child processes on timeout, and cleanly exiting commands auto-review (`review_required: false`).
  - **Mandatory Two-Step Delete Guard Hook (Default ON)**: Built-in `windows/ai-workbench/delete-guard.ps1` pauses destructive commands (`rm -rf`, `Remove-Item -Recurse`, `git reset --hard`, etc.) on the first attempt for verification, allowing a single exact resend within 10 minutes.
  - **Gemini Web Image Bridge Protection & Pluggable `inspect_image`**: Protects Google Gemini Web from stripped `{}` media blocks by requiring `filePath` on screenshots and offering an opt-in `inspect_image` multimodal verifier (`gemini-api`, `openai-api`, or `cli-auto`).

---

## Which Public HTTPS Ingress Mode Should You Pick?

| Feature | Mode A1: Cloudflare Quick Tunnel (Default) | Mode A2: Cloudflare Named Tunnel | Mode B: Self-Hosted Linux VPS |
| :--- | :--- | :--- | :--- |
| **VPS or Domain Needed?** | **None** (100% free, no account) | No VPS (uses free Cloudflare Tunnel + domain) | Ubuntu/Debian VPS (**No domain needed** — auto `sslip.io` TLS) |
| **Setup Time** | **~30 seconds** | ~2 minutes | **1-Click automated (~1–2 min)** |
| **Permanent URL Across Restarts?** | Rotates random `*.trycloudflare.com` on restart | **Permanent** (bind once, use forever) | **Permanent** (bind once, use forever) |
| **TUN / Fake-IP Proxy Support** | Auto-detects `198.18.0.0/15` & bypasses Fake-IP | Auto-detects `198.18.0.0/15` & bypasses Fake-IP | Auto-reconnecting SSH `-R` reverse tunnel |
| **Best For** | Instant zero-cost testing & demos | Permanent URL without a Linux server | 24/7 daily production across ChatGPT & Gemini |

---

## Architecture Overview

```text
  OpenAI ChatGPT Web ──┐
                       ├──► HTTPS + OAuth 2.1 (PKCE S256 + Dynamic Client Registration)
  Google Gemini Web  ──┘            │
        ┌───────────────────────────┴───────────────────────────┐
        ▼ Mode A: Serverless Cloudflare Tunnel                  ▼ Mode B: 1-Click Linux VPS
 [Quick *.trycloudflare.com / Named Fixed Domain]      [Ubuntu/Debian VPS: Non-Destructive Caddy conf.d]
        │ Encrypted QUIC Tunnel (TUN Fake-IP Safe)              │ Gateway (:8787) + SSH -R Tunnel
        ▼                                                       ▼
 ┌─────────────────────────────────────────────────────────────────────────────────────┐
 │                          Your Windows 10 / 11 Workstation                           │
 │  Start-GUI.bat (Native WinForms Wizard + Dashboard + System Tray · 0 Admin Ports)   │
 │   ├── Filesystem MCP Supervisor + Bearer Proxy  (fs_* / git_* · allowedRoots)       │
 │   ├── Shared Chrome MCP Gateway (1.5.0 Patched) (chrome_* · strict pageId routing)  │
 │   └── AI Workbench + Native WorkbenchJob.exe    (run_command · Win32 Job Object)    │
 └─────────────────────────────────────────────────────────────────────────────────────┘
```

---

## Prerequisites (Windows 10 / 11)

| Component | Requirement | Notes |
| :--- | :--- | :--- |
| **Node.js** | `>= 20.0` (22 LTS recommended) | Runs Gateway, FS MCP, Chrome MCP & AI Workbench |
| **PowerShell 7** | `pwsh.exe` | Executes `run_command` and 1-click deployment scripts |
| **.NET SDK** | `.NET 8.0+` | Compiles `WorkbenchJob.exe` offline in `< 1s` (`npm run build:workbench`) |
| **OpenSSH Client** | Built-in `ssh.exe` | Used only in Mode B (VPS SSH Reverse Tunnel) |
| **Cloudflared** | Optional (Mode A) | Install via `winget install Cloudflare.cloudflared` for instant serverless HTTPS |
| **Google Chrome** | Optional (`chrome_*` tools) | Launch Chrome with `--remote-debugging-port=9222` to share browser access |

---

## Foolproof 3-Step Quick Start (Windows PC)

### Step 1 — Clone & Build Locally

```powershell
git clone https://github.com/dqIndieGames/remote-pc-mcp-gateway.git
cd remote-pc-mcp-gateway
npm run setup
```

> **Tip**: Even if you skip `npm run setup` and double-click `Start-GUI.bat` directly, clicking **Start** or **⚙ Install & Build** in the GUI automatically runs the setup build in the background!

### Step 2 — Double-Click `Start-GUI.bat`

Double-click `Start-GUI.bat` in Explorer. On first launch, the **Setup Wizard** opens automatically:

![Native Windows Setup Wizard](./docs/assets/gui-wizard-en.png)

1. **1. Ingress & Server**:
   - **30-Second Serverless Start**: Leave **Serverless Cloudflare Tunnel** selected (optionally fill Named Tunnel Hostname & Token below for a permanent URL); **or**
   - **1-Click Self-Hosted VPS**: Select **Self-Hosted Linux VPS Mode**, fill your VPS IPv4 & SSH user, click **Browse** to pick your SSH key (or leave blank to auto-detect/generate `~/.ssh/id_ed25519`), and leave Domain blank to auto-provision free `mcp.<ip>.sslip.io` HTTPS!
2. **2. Folders, Guard & Alerts**: Click **`+ Add Folder`** to approve workspace folders (e.g., `D:\Workspace\MyWebApp`). The **2-Step Delete Guard Hook** is enabled by default; System Tray Alerts and `inspect_image` Vision Backend are opt-in.
3. **3. Check & One-Click Start**:
   - Click **⚡ One-Click Initialize & Start** for Cloudflare mode, **or**
   - Click **🚀 One-Click Deploy to VPS & Start** to provision your Linux VPS, issue TLS certificates, sync generated secrets back to `config/config.local.json`, and bring all 5 local services online!

### Step 3 — Copy Your Masked Credentials from the Dashboard

Once the status pill turns green (**`● Running · Public HTTPS Ready`**) and all 5 service cards are green, click **Copy MCP URL** and **Copy Approval Key**.

---

## Visual Guide 1: Connecting Google Gemini Web (`gemini.google.com`)

![Google Gemini 5-Step Setup Guide](./docs/assets/gemini-setup-en.png)

1. **Open Connected Apps**: Visit `https://gemini.google.com/` on desktop → click **Settings** (bottom-left) → **Connected Apps** (or open `https://gemini.google.com/devmode` directly).
2. **Click `+ Custom`**: Under **Custom apps**, click the blue **`+ Custom`** (**`Add a custom app`**) button.
3. **Paste MCP Server URL (Leave Client ID Blank)**: Paste your full **MCP Server URL** (`https://<your-tunnel-or-domain>/<secret>/mcp`) and click **Next**. **Leave manual OAuth Client ID and Client Secret blank** — Gemini automatically uses OAuth 2.1 Dynamic Client Registration!
4. **Approve with Owner Approval Key**: On your gateway's OAuth 2.1 consent card, paste your **Owner Approval Key** and click **Approve & Connect Google Gemini**:

![OAuth 2.1 Owner Approval Consent Screen](./docs/assets/oauth-consent-en.png)

5. **Critical Step 5 — Switch Composer Mode from `Chat` to `Task`**: Back in the Gemini chat box, **switch the bottom-right mode selector from `Chat` to `Task`**!
   - Why this matters: Gemini Web's default `Chat` mode does **not** load custom MCP tools. Once switched to **`Task`**, type `@` (or ask directly) to read/edit local files, run PowerShell 7 tests, or automate Chrome!

---

## Visual Guide 2: Connecting OpenAI ChatGPT Web (`chatgpt.com`)

![OpenAI ChatGPT 5-Step Setup Guide](./docs/assets/chatgpt-setup-en.png)

1. **Enable Developer Mode**: Open `https://chatgpt.com/` (Plus, Pro, Team, Enterprise, or Edu) → **Settings → Connectors → Advanced** → toggle **Developer Mode** ON.
2. **Click `+ Create` Connector**: Return to **Connectors** and click the blue **`Create`** (Add custom MCP server) button.
3. **Fill MCP URL & Select `OAuth`**:
   - **Name**: `My Windows PC`
   - **MCP Server URL**: Paste the full `https://.../<secret>/mcp` URL from your Windows Control Panel
   - **Authentication**: Select **`OAuth`**
4. **Approve with Owner Approval Key**: Click **Create**, then paste your **Owner Approval Key** on the gateway consent page.
5. **Enable in Any Chat**: In a new conversation, click **`+`** (bottom-left of the composer) to enable **`My Windows PC`** — works concurrently alongside Google Gemini!

---

## Mode B: CLI One-Click Linux VPS Deployment & Management

Prefer deploying onto a fresh or existing Ubuntu/Debian VPS directly from PowerShell?

```powershell
pwsh -File .\deploy\deploy-to-vps.ps1 `
  -VpsHost 203.0.113.10 `
  -VpsUser root `
  -AllowedRoot "D:\Workspace\MyWebApp"
```

- **Smart SSH Key Auto-Detection & Provisioning**: Automatically uses `-SshKeyPath` or `~/.ssh/id_ed25519` (or generates an ED25519 keypair with hardened Windows `icacls` ACLs if none exists) and connects seamlessly via standard OpenSSH (`StrictHostKeyChecking=accept-new`).
- **100% Non-Destructive Caddy Integration**: Backs up any existing `/etc/caddy/Caddyfile` and mounts a dedicated drop-in `/etc/caddy/conf.d/remote-pc-mcp-gateway.caddy` so **pre-existing websites on your VPS remain completely untouched**.
- **Built-In Remote Server Helpers** (run on your VPS via SSH):
  - Check gateway & TLS health: `sudo mcp-gateway-status`
  - Cleanly uninstall gateway while keeping existing Caddy sites intact: `sudo mcp-gateway-uninstall`

---

## Shared Chrome Tab Mover Extension (Optional)

To allow `chrome_move_pages_to_new_window` to move AI-created test tabs into an unfocused background Chrome window without stealing focus:

1. Open `chrome://extensions` in your `--remote-debugging-port=9222` Chrome.
2. Enable **Developer mode** → click **Load unpacked** → select `windows/chrome-mcp/chrome-tab-mover-extension`.

---

## Troubleshooting & FAQ

| Symptom / Question | Root Cause | 1-Step Fix |
| :--- | :--- | :--- |
| **Gemini shows Connected, why won't it call my PC tools?** | Gemini defaults to `Chat` mode, which does not load custom MCP servers | Switch the bottom-right mode selector in the Gemini composer from **`Chat`** to **`Task`** |
| **Clash / Mihomo / Sing-box TUN mode causes Cloudflare `Error 1033`?** | TUN Fake-IP (`198.18.0.0/15`) intercepts default UDP/HTTP2 tunnel DNS | Launch via `Start-GUI.bat` or `stack-manager.mjs` — it auto-detects Fake-IP and forces QUIC + Cloudflare Anycast Edge IPs |
| **Quick Tunnel URL stopped working after restarting my PC?** | Free Quick Tunnels assign a new random `*.trycloudflare.com` hostname each run | Copy the new MCP URL from the Dashboard, or switch to **Cloudflare Named Tunnel** / **1-Click Linux VPS (`sslip.io`)** for a permanent URL |
| **Why did `rm -rf` or `Remove-Item -Recurse` pause on the first try?** | The built-in 2-Step Delete Guard (`delete-guard.ps1`) paused a destructive command | Verify the command is safe, then resend the exact same command within 10 minutes to approve once |
| **How can Gemini Web inspect local screenshots (`inspect_image`)?** | Google's cloud bridge strips raw MCP image blocks to `{}` | Set **Gemini Vision** in Wizard Step 2 to `gemini-api`, `openai-api`, or `cli-auto` and call `inspect_image` on saved screenshots |

---

## Automated Tests & Secret Scanning

```powershell
# Run OAuth 2.1 dual-platform, tool annotations, Fake-IP tunnel, Workbench & VPS dry-run unit tests
npm test

# Scan the entire repository for leaked IPs, private keys, emails, tokens, or personal paths (0 hits)
npm run scan:secrets
```

---

## License

Released under the [MIT License](./LICENSE).