# Chrome MCP Setup

Connect Forge's Claude Code sessions to a running Chrome instance via
**chrome-devtools-mcp**, so the agent can navigate pages, query the
DOM, and execute scripts against the user's real browser session.

This is the development-time path for authoring browser connectors —
the agent writes a connector handler, runs it against a real Mantis /
GitLab / etc. page, sees the actual DOM output, and iterates.

## How it fits

```
Forge Claude Code session
        │
        │  MCP (stdio)
        ▼
chrome-devtools-mcp  ──CDP──▶  Chrome (user's real instance)
                                  │
                                  ▼
                               Mantis / GitLab / any logged-in tab
```

## One-time setup

### 1. Start Chrome with remote debugging enabled

**Easiest path — use the bundled script:**
```bash
./scripts/chrome-mcp.sh restart    # stop + start with debug port 9222
./scripts/chrome-mcp.sh status     # check whether port is up
```
Subcommands: `start`, `stop`, `restart`, `status`. Use `-p PORT` to override.

**Manual path** — quit all Chrome windows first (so the new instance
can take the debug port), then:

**macOS:**
```bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.chrome-mcp-profile"
```

**IMPORTANT — non-default profile required.** Chrome refuses to open
the remote debug port on the default user-data-dir (security guard, so
localhost code can't hijack your real Chrome with all its logins). The
error message reads: `DevTools remote debugging requires a non-default
data directory`.

Use a separate path like `$HOME/.chrome-mcp-profile`. **One-time cost:**
this profile starts empty, so you log in to NAC / Mantis / GitLab once
inside it. Cookies persist across restarts — wipe with
`rm -rf "$HOME/.chrome-mcp-profile"` if you want a fresh start.

**Linux:**
```bash
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-mcp-profile"
```

**Windows:**
```powershell
"C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 `
  --user-data-dir="$env:USERPROFILE\.chrome-mcp-profile"
```

Verify it worked: open `http://localhost:9222/json/version` in the new
Chrome — you should see a JSON page with `Browser`, `Protocol-Version`, etc.

### 2. Add the MCP server to Forge settings

Settings → MCP Servers → Add. Fill in:

| Field | Value |
|---|---|
| Name | `chrome` |
| Type | `stdio` |
| Command | `npx` |
| Args | `["-y", "chrome-devtools-mcp"]` |
| Env | (leave empty — defaults to localhost:9222) |

Save. Forge will now merge this into every project's `.mcp.json` next
time a session is created or refreshed.

Equivalent `settings.yaml` snippet:

```yaml
mcpServers:
  chrome:
    type: stdio
    command: npx
    args:
      - "-y"
      - "chrome-devtools-mcp"
```

### 3. Open a Forge project / workspace

When Claude Code launches in the project, it'll auto-discover the new
MCP server (the `.mcp.json` Forge writes now has both `forge` and
`chrome` entries). The agent will see browser tools like
`chrome_navigate`, `chrome_query_selector`, `chrome_evaluate`, etc.

Verify in a session: ask the agent "what MCP tools do you have?" — it
should list chrome_* tools alongside Forge tools.

## Using it for connector development

Workflow inside a Forge workspace:

1. Ask the agent: *"Develop a Mantis list_my_bugs connector. Target
   page is https://mantis.forge.com/view_all_bug_page.php."*
2. Agent navigates the Chrome tab there via `chrome_navigate`.
3. Agent queries the DOM via `chrome_query_selector` /
   `chrome_evaluate` to understand the page structure.
4. Agent writes the handler code (`lib/builtin-plugins/mantis.handler.js`
   or wherever your code-publishing scheme lands).
5. Agent runs the candidate code in the page via `chrome_evaluate`,
   sees real output, iterates.
6. When done, agent commits the connector via normal git flow / publishes
   per the connector marketplace flow.

No copy-paste loop. No probe scripts. Real DOM at every step.

## Cleanup

To stop using Chrome MCP:

1. Remove the `chrome` entry from Settings → MCP Servers.
2. Forge regenerates `.mcp.json` on the next session creation.
3. Optionally close the debug-enabled Chrome and restart normally.

## Troubleshooting

| Symptom | Cause + fix |
|---|---|
| Agent says it has no chrome_* tools | Forge hasn't written the new `.mcp.json` yet — open the project tab in Forge to trigger `ensureMcpConfig`. Or just delete the project's `.mcp.json` and reopen. |
| `chrome_navigate` errors with "no debug target" | Chrome isn't running with `--remote-debugging-port=9222`. Verify `curl localhost:9222/json/version`. |
| Multiple Chrome processes | Quit all Chrome windows first, then start with the debug flag. macOS app launches and bare-binary launches don't share the port. |
| Login redirect on every nav | You're using `--user-data-dir=/tmp` or a fresh profile — point it at your real one to reuse cookies. |
| Enterprise / SSO restrictions | Some corporate MDM disables CDP. There's no workaround in those environments — fall back to the in-extension probe loop. |

## Security note

Connecting to Chrome via CDP means anything able to reach
`localhost:9222` can drive your browser. Only enable on machines where
you trust everything local. Don't expose the debug port over the
network.
