ie-mode-mcp

MCP-Server zur Steuerung von Legacy-Webanwendungen, die im IE-Modus von Microsoft Edge laufen, über MCP (Model Context Protocol) durch KI-Agenten.

AI Agent ──(MCP / stdio)──> ie-mode-mcp ──> BrowserManager ──> selenium-webdriver
                                                                     │
                                                          IEDriverServer.exe
                                                                     │
                                                     Microsoft Edge (IE Mode)
                                                                     │
                                                       Legacy Web Application

• Besteht nur aus Node.js 22 / TypeScript / selenium-webdriver (kein HTTP-Server, keine DB, kein DI, kein Logging-Framework)

• MCP-Transport ist nur stdio

• Es gibt nur eine Browsersitzung, WebDriver-Operationen erfolgen vollständig sequenziell

• Der vollständige HTML-Code wird nicht zurückgegeben; inspect_page gibt eine für LLMs zusammengefasste Bildschirminformation zurück

• Kein Genehmigungsablauf. Die Operation wird ausgeführt, sobald das Tool aufgerufen wird

Inhaltsverzeichnis

1. Schnellstart

2. Voraussetzungen

3. Windows-Vorkonfiguration

4. Installation und Build

5. Umgebungsvariablen

6. Startmethoden

7. Registrierung beim KI-Agenten

8. Tool-Referenz

9. Anwendungsbeispiele

10. Fehler und Behebung

11. Logging

12. Fehlerbehebung

13. Entwicklung

14. Einschränkungen

1. Schnellstart

Führen Sie Folgendes unter Windows aus.

git clone https://github.com/sumikof/iedriver-mcp.git
cd iedriver-mcp
npm install
npm run build

# IEDriverServer.exe のパスと、遷移を許可する Origin を指定して起動
$env:IE_MCP_DRIVER_PATH = "C:\tools\IEDriverServer.exe"
$env:IE_MCP_ALLOWED_ORIGINS = "http://legacy01.local"
node dist/index.js

Wenn {"level":"info","event":"started","transport":"stdio"} auf stderr ausgegeben wird, war der Start erfolgreich. Normalerweise wird der Server nicht manuell gestartet, sondern automatisch über die MCP-Konfiguration des KI-Agenten gestartet.

2. Voraussetzungen

• IEDriverServer.exe wird von der Selenium-Downloadseite heruntergeladen und in einem beliebigen Ordner (z. B. C:\tools\) abgelegt. Da die 64-Bit-Version bekannte Einschränkungen hat, empfiehlt Selenium offiziell die Verwendung der 32-Bit-Version.

• Da IEDriver von der GUI, dem Fensterfokus und nativen Ereignissen beeinflusst wird, wird die Verwendung einer dedizierten Windows-VM oder einer dedizierten Windows-Sitzung empfohlen.

• Ein Betrieb des Browsers in einem Windows-Dienst (Session 0) wird nicht unterstützt.

• Der MCP-Server, IEDriver und Edge laufen in derselben Windows-Umgebung.

3. Windows-Vorkonfiguration

IEDriver wird stark von den Umgebungseinstellungen beeinflusst. Konfigurieren Sie diese zuerst manuell, bevor Sie den MCP-Server starten.

3.1 IE-Modus von Edge verfügbar machen

Überprüfen Sie zuerst durch manuelle Bedienung von Edge, ob die Zielseite im IE-Modus geöffnet werden kann. Der IE-Modus wird über eine der folgenden Richtlinien aktiviert (unter Software\Policies\Microsoft\Edge).

Die genaue Konfiguration hängt von den Richtlinien Ihrer Organisation ab. Für Details konsultieren Sie bitte die Dokumentation von Microsoft zum IE-Modus und Ihren Administrator. Stellen Sie sicher, dass Windows / Edge auf dem neuesten Stand sind.

3.2 Von IEDriver geforderte Einstellungen

Wenn die Einstellungen für den geschützten Modus nicht einheitlich sind, schlägt browser_start fehl. Die Einstellung introduceFlakinessByIgnoringProtectedModeSettings von IEDriver wird nicht verwendet, da sie zu instabilem Verhalten führt.

4. Installation und Build

npm install     # 依存パッケージの取得
npm run build   # TypeScript を dist/ へビルド

Das Artefakt ist dist/index.js. Nach dem Build kann es auch mit npm start (= node dist/index.js) gestartet werden.

5. Umgebungsvariablen

Es werden keine Konfigurationsdateien (YAML / JSON) verwendet, sondern nur Umgebungsvariablen.

IE_MCP_EDGE_PATH=C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
IE_MCP_DRIVER_PATH=C:\tools\IEDriverServer.exe
IE_MCP_ALLOWED_ORIGINS=http://legacy01.local,http://legacy02.local
IE_MCP_TIMEOUT_MS=10000

• Da IE Driver 4.5.0 und höher Edge in Umgebungen ohne IE (Standard in Windows 11) automatisch erkennt, ist IE_MCP_EDGE_PATH normalerweise nicht erforderlich. Nur angeben, wenn die automatische Erkennung fehlschlägt.

• Für reproduzierbare Abläufe wird empfohlen, IE_MCP_DRIVER_PATH explizit anzugeben.

• IE_MCP_ALLOWED_ORIGINS ist eine einfache Einschränkung zur Vermeidung von Fehlbedienungen und prüft auf exakte Übereinstimmung des Origin (Schema + Host + Port). Es erfolgt keine Einschränkung auf Pfadebene.

6. Startmethoden

Manueller Start (für Funktionstests)

PowerShell:

$env:IE_MCP_DRIVER_PATH = "C:\tools\IEDriverServer.exe"
$env:IE_MCP_ALLOWED_ORIGINS = "http://legacy01.local"
node dist/index.js

Eingabeaufforderung:

set IE_MCP_DRIVER_PATH=C:\tools\IEDriverServer.exe
set IE_MCP_ALLOWED_ORIGINS=http://legacy01.local
node dist\index.js

Wartet über stdio auf Verbindungen vom Client. Da die Standardein-/ausgabe für das MCP-Protokoll verwendet wird, erfolgt keine Reaktion auf Tastatureingaben in diesem Zustand (normal). Alle Logs werden auf stderr ausgegeben. Zum Beenden Strg+C drücken (der Browser wird ebenfalls automatisch geschlossen).

Hinweis: Der Browser wird nicht gestartet, nur weil der MCP-Server gestartet wird. Der Browser wird gestartet, wenn der Agent browser_start aufruft.

Normaler Betrieb

Der KI-Agent (MCP-Client) startet diesen Server als untergeordneten Prozess. Manuelles Starten ist nicht erforderlich. Nehmen Sie die Konfiguration im nächsten Kapitel vor.

7. Registrierung beim KI-Agenten

Fügen Sie Folgendes zur Konfigurationsdatei des MCP-Clients hinzu.

{
  "mcpServers": {
    "ie-mode": {
      "command": "node",
      "args": ["C:\\ie-mode-mcp\\dist\\index.js"],
      "env": {
        "IE_MCP_DRIVER_PATH": "C:\\tools\\IEDriverServer.exe",
        "IE_MCP_EDGE_PATH": "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
        "IE_MCP_ALLOWED_ORIGINS": "http://legacy01.local,http://legacy02.local",
        "IE_MCP_TIMEOUT_MS": "10000"
      }
    }
  }
}

• Escape-Tasten im Pfad innerhalb des JSON (z. B. C:\\...).

• Geben Sie in args den absoluten Pfad zum gebauten dist/index.js an.

• Bei Claude Code kann es auch mit claude mcp add registriert werden.

claude mcp add ie-mode --env IE_MCP_DRIVER_PATH=C:\tools\IEDriverServer.exe --env IE_MCP_ALLOWED_ORIGINS=http://legacy01.local -- node C:\ie-mode-mcp\dist\index.js

Nach der Registrierung ist die Verbindung erfolgreich, wenn auf Client-Seite 10 Tools einschließlich browser_start sichtbar sind.

8. Tool-Referenz

Es werden 10 Tools bereitgestellt. Die Low-Level-API von WebDriver (findElement / executeScript usw.) wird nicht bereitgestellt.

Gemeinsam: Selector

{ "by": "id | name | css | xpath | linkText", "value": "searchButton" }

Da in Legacy-Webanwendungen name und xpath häufig verwendet werden, werden diese unterstützt.

Gemeinsam: frame (iframe ist 1 Ebene)

Alle Element-Operationstools akzeptieren ein optionales frame. Wenn angegeben, wird zuerst zu defaultContent zurückgekehrt, dann in den Frame gewechselt und darin nach dem Element gesucht.

{
  "frame": { "by": "name", "value": "mainFrame" },
  "selector": { "by": "id", "value": "searchButton" }
}

browser_start

{}

{ "status": "ready", "reused": false }

reused: true zeigt an, dass die vorhandene Sitzung unverändert verwendet wurde. Wenn die vorhandene Sitzung abgestorben ist, wird sie automatisch neu gestartet.

navigate

{ "url": "http://legacy01.local/customer" }

{ "url": "http://legacy01.local/customer", "title": "顧客検索" }

inspect_page

Das wichtigste Tool für den Agenten, um den Bildschirm zu verstehen. Es wird nicht der vollständige HTML-Code zurückgegeben, sondern nur URL / Titel / angezeigter Text / bedienbare Elemente (a button input textarea select iframe). Nicht sichtbare Elemente und Inputs mit type="hidden" werden ausgeschlossen.

{ "frame": { "by": "name", "value": "mainFrame" } }

{
  "url": "http://legacy01.local/customer",
  "title": "顧客検索",
  "text": "顧客検索 顧客名 支店 検索",
  "elements": [
    { "tag": "input", "id": "customerName", "name": "customerName", "type": "text" },
    { "tag": "select", "id": "branch", "name": "branch", "text": "東京支店", "optionCount": 12 },
    { "tag": "button", "id": "searchButton", "text": "検索" },
    { "tag": "iframe", "name": "mainFrame" }
  ],
  "truncated": false
}

• truncated: true zeigt an, dass die Elementliste bei der Obergrenze (300 Elemente) abgeschnitten wurde.

• Wenn die Elementliste ein iframe enthält, rufen Sie es erneut mit Angabe von frame auf, um dessen Inhalt zu sehen.

click

{ "selector": { "by": "id", "value": "searchButton" } }

{ "url": "http://legacy01.local/customer", "title": "顧客検索" }

Wartet auf Sichtbarkeit und Aktivierung, dann klicken. click wiederholt sich nicht automatisch (um doppelte Verarbeitung bei bereits erfolgreicher Registrierung, Aktualisierung oder Sendung durch erneutes Klicken zu vermeiden).

type

{
  "selector": { "by": "id", "value": "customerName" },
  "text": "山田太郎",
  "clear": true
}

Wenn clear (Standard true) true ist, wird nach clear() eingegeben, bei false wird angehängt.

select

{
  "selector": { "by": "id", "value": "branch" },
  "by": "text",
  "value": "東京支店"
}

{ "text": "東京支店", "value": "13", "index": 2 }

by ist text / value / index (index beginnt bei 0).

wait_for

Verwendet kein festes Sleep, sondern wartet explizit.

{
  "type": "visible",
  "selector": { "by": "id", "value": "resultTable" },
  "timeoutMs": 10000
}

Wenn timeoutMs weggelassen wird, wird IE_MCP_TIMEOUT_MS verwendet.

switch_window

{ "target": "newest" }

{ "index": 1 }

{ "url": "http://legacy01.local/detail", "title": "顧客詳細", "index": 1, "windowCount": 2 }

newest pollt kurzzeitig, bis ein neuer Window-Handle erscheint. Wenn keiner erkannt wird, wird zum letzten vorhandenen Fenster gewechselt.

screenshot

{}

Gibt ein PNG-Bild (MCP image content) zurück. Nützlich zur Überprüfung von Layouts oder Fehlerbildschirmen, die allein anhand des DOM nicht beurteilt werden können.

9. Anwendungsbeispiele

Grundlegende Schleife

browser_start → navigate → inspect_page → click / type / select → wait_for → inspect_page

Wiederholen: Bildschirm mit inspect_page erfassen → Bedienen → mit wait_for auf Ergebnis warten → erneut inspect_page.

Beispiel: Kunden „Yamada Taro“ suchen und Detailseite öffnen

Beispiel: Bedienung innerhalb eines iframes

{"tool": "inspect_page", "args": {}}
{"tool": "inspect_page", "args": { "frame": { "by": "name", "value": "mainFrame" } }}
{"tool": "click", "args": {
  "frame": { "by": "name", "value": "mainFrame" },
  "selector": { "by": "id", "value": "searchButton" }
}}

Die Frame-Angabe muss bei jeder Operation erneut übergeben werden (da intern jedes Mal zu defaultContent zurückgekehrt und dann in den Frame gewechselt wird, bleibt der Zustand nicht erhalten).

Beispiel: Popup bedienen und zum ursprünglichen Fenster zurückkehren

{"tool": "click",         "args": { "selector": { "by": "id", "value": "openPopup" } }}
{"tool": "switch_window", "args": { "target": "newest" }}
{"tool": "inspect_page",  "args": {}}
{"tool": "switch_window", "args": { "index": 0 }}

10. Fehler und Behebung

Fehler werden nicht als Selenium-Stack-Trace, sondern mit folgendem Code zurückgegeben (isError: true).

{
  "error": "ELEMENT_NOT_FOUND",
  "message": "Element was not found: id=searchButton",
  "selector": { "by": "id", "value": "searchButton" }
}

Wiederherstellung nach DRIVER_LOST

Wenn der Browser oder Treiber abstürzt, wird der interne WebDriver verworfen, und nachfolgende Operationen führen zu BROWSER_NOT_STARTED. Es erfolgt keine automatische Wiederherstellung oder automatische Wiederholung der letzten Operation (um Nebenwirkungen wie doppelte Registrierungen zu vermeiden). Der Agent muss browser_start erneut aufrufen, den Bildschirmzustand mit inspect_page überprüfen und dann die Bedienung fortsetzen. Da die vorherige Operation möglicherweise bereits erfolgreich war, dürfen Registrierungs- und Aktualisierungsoperationen nicht unverändert wiederholt werden.

11. Logging

Da stdout vom MCP-Protokoll verwendet wird, werden alle Logs auf stderr als einzelne JSON-Zeile ausgegeben.

{"level":"info","event":"started","transport":"stdio"}
{"level":"info","tool":"navigate","url":"http://legacy01.local/customer","durationMs":842}
{"level":"info","tool":"type","selector":{"by":"id","value":"password"},"textLength":16,"durationMs":128}
{"level":"error","tool":"click","selector":{"by":"id","value":"x"},"error":"ELEMENT_NOT_FOUND","message":"Element was not found: id=x","durationMs":5012}

Der eingegebene String selbst, Cookies, Authentifizierungsinformationen und der vollständige HTML-Code werden nicht aufgezeichnet (bei type nur die Zeichenanzahl). Zum Speichern in einer Datei stderr umleiten.

node dist/index.js 2>> C:\logs\ie-mode-mcp.log

12. Fehlerbehebung

screenshot ist hilfreich für die Ursachenforschung. Damit können Zustände (Modale, Authentifizierungsdialoge, Rendering-Fehler) überprüft werden, die allein anhand der DOM-Informationen nicht beurteilt werden können.

13. Entwicklung

src/
├─ index.ts      MCP Server のエントリーポイント（stdio）
├─ config.ts     環境変数と stderr ログ
├─ tools.ts      MCP Tool の Schema と Handler
├─ browser.ts    BrowserManager（Selenium / IEDriver 操作の集約）
├─ selectors.ts  Selector → Selenium の By 変換
└─ errors.ts     Selenium Error → MCP Error Code 変換

npm run build   # tsc でビルド
npm start       # node dist/index.js

• MCP-Tools greifen nicht direkt auf Selenium zu, sondern immer über BrowserManager.

• Alle WebDriver-Operationen werden über eine Promise Chain sequenziert, sodass selbst bei parallelem Aufruf von Tools nur jeweils ein Befehl an IEDriver gesendet wird.

• Nur Operationen ohne Nebenwirkungen (Elementsuche, Window-Handle-Erkennung) werden wiederholt. click und Senden werden nicht wiederholt.

14. Einschränkungen

Die erste Implementierung unterstützt Folgendes nicht:

Mehrere Browsersitzungen / Mehrere Benutzer / HTTP-Transport / REST-API / DB / Sitzungspersistenz / Automatische Browserwiederherstellung / Komplexe Wiederholungsrichtlinie / WebDriver Grid / Allgemeine Selenium-API / executeScript-Tool / Mehrstufige iframes (nur eine Ebene) / Element-Cache / Metriken / Genehmigungsablauf / Authentifizierung und Autorisierung