# SimScale Edge MCP

An MCP server that navigates the SimScale Workbench through Microsoft Edge and
Playwright. It does not use the enterprise SimScale API.

The recommended mode attaches to your normal, already signed-in Edge profile.
Remote debugging must be enabled from Edge's built-in `edge://inspect` page.
The fallback mode opens a separate MCP-managed profile.

## Requirements

- Node.js 20 or newer
- Microsoft Edge
- A SimScale account

## Install

```powershell
npm install
```

Playwright Core drives the copy of Microsoft Edge already installed on Windows;
it does not download a separate browser.

## Start the host broker

Codex's command sandbox can prevent a stdio MCP child from completing Edge's
DevTools WebSocket upgrade. Start the loopback-only host broker from a normal
PowerShell window before opening Codex:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\start-simscale-host.ps1
```

The broker listens only on `127.0.0.1:43127`. Stop it when finished with:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\stop-simscale-host.ps1
```

## Connect an MCP host

Use the broker's Streamable HTTP endpoint:

```json
{
  "mcpServers": {
    "simscale": {
      "url": "http://127.0.0.1:43127/mcp"
    }
  }
}
```

The launcher sets `SIMSCALE_FILE_ROOT` to this project directory. It restricts
which local files the MCP may upload and is also where result downloads are
saved. Change that assignment in `scripts/start-simscale-host.ps1` if your CAD
files live elsewhere.

Optional environment variables:

| Variable | Default | Purpose |
| --- | --- | --- |
| `SIMSCALE_FILE_ROOT` | MCP working directory | Allowed upload/download root |
| `SIMSCALE_EDGE_USER_DATA_DIR` | unset | Discover a debugging-enabled Edge instance |
| `SIMSCALE_EDGE_CDP_URL` | unset | Advanced fixed-port attachment override |
| `SIMSCALE_EDGE_CONNECT_TIMEOUT_MS` | `30000` | Edge attachment timeout, from 5 to 120 seconds |
| `SIMSCALE_EDGE_PROFILE_DIR` | `%LOCALAPPDATA%\SimScaleMCP\edge-profile` | Persistent Edge profile |
| `SIMSCALE_EDGE_CHANNEL` | `msedge` | Playwright browser channel |
| `SIMSCALE_DASHBOARD_URL` | SimScale My Projects | Initial page |
| `SIMSCALE_ALLOW_CSS_SELECTORS` | unset | Set to enable advanced CSS targets |

## Use your already signed-in Edge profile

Run the helper to open Edge's supported remote-debugging settings:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\start-edge-debug.ps1
```

On the **Remote debugging** page, enable **Allow remote debugging for this
browser instance**. Set `SIMSCALE_EDGE_USER_DATA_DIR` to Edge's user-data
directory (normally `%LOCALAPPDATA%\Microsoft\Edge\User Data`). The MCP reads
only Edge's `DevToolsActivePort` handshake file, attaches to that Edge instance,
and opens or reuses a SimScale tab. It does not read cookies or profile files and
will not close your personal Edge browser.

If an MCP process is forcibly stopped while attached, toggle remote debugging
off and on before reconnecting. Restart the MCP host after changing its server
registration or updating this server's code so it launches a fresh process.

Remote debugging gives local software control over browser tabs. Edge binds its
debugging endpoint locally, and this MCP restricts its navigation to HTTPS
SimScale domains. Turn remote debugging off when finished.

## First MCP use

1. Call `simscale_edge_start`.
2. Call `simscale_edge_status` and verify `connectionMode` is `attached` and
   `signedIn` is `true`.
3. Call `simscale_select_page` with the expected SimScale `project_id`. The MCP
   pins that project and prefers its Workbench tab over Dashboard tabs.
4. Call `simscale_wait_for_workbench_ready`, then `simscale_page_state` before
   each interaction. Use `container`, `text_filter`, `offset`, and `max_items`
   to retrieve the relevant slice of a large Workbench tree.
5. Prefer the returned `element_id`, followed by `test_id`, role/name, or label
   with `simscale_click`, `simscale_fill`, `simscale_select`, and
   `simscale_press`.
6. Pass the pinned project as `expected_project_id` on every navigation or
   UI-changing tool. The MCP rejects missing or mismatched project IDs before
   interacting.

Action tools optionally accept `expect_text`, `expect_url`, `expect_value`, and
`expect_timeout_ms`. Their results include the current project, simulation, and
run identity so callers can verify that the intended Workbench state remained
active.

For CAD uploads, point `SIMSCALE_FILE_ROOT` at the CAD folder and use
`simscale_upload_file` with `confirm_upload: true`. Starting a mesh or simulation
run, saving, creating, deleting, or other state-changing clicks require
`confirm_action: true`.

## Available tools

- `simscale_edge_start`, `simscale_edge_status`, `simscale_edge_close`
- `simscale_edge_diagnostics`
- `simscale_select_page`, `simscale_wait_for_workbench_ready`
- `simscale_page_state`, `simscale_screenshot`, `simscale_navigate`
- `simscale_click`, `simscale_fill`, `simscale_press`, `simscale_select`
- `simscale_upload_file`, `simscale_download`
- `simscale_wait_for_text`

The tools are deliberately semantic instead of hard-coding SimScale's current
DOM structure. The agent reads the live interface and targets visible,
accessible labels, which makes the MCP more resilient to Workbench updates.

## Test

```powershell
npm test
```

Tests do not launch Edge or access SimScale.

## Safety

- Password fields cannot be filled or read through MCP.
- Cookies, browser storage, and saved credentials are never exposed.
- CDP attachment is restricted to explicit HTTP or WebSocket loopback ports.
- Navigation is restricted to HTTPS SimScale domains.
- Project pages can be pinned, and UI-changing tools require a matching
  `expected_project_id`.
- Uploads are restricted to `SIMSCALE_FILE_ROOT` and require confirmation.
- Downloads require confirmation and go to `simscale-downloads`.
- Mutating, destructive, and compute-related clicks require confirmation.
- Attached mode never closes the user's personal Edge browser.