ie-mode-mcp

Servidor MCP para operar aplicaciones web heredadas que funcionan en el modo IE de Microsoft Edge desde agentes de IA a través de MCP (Model Context Protocol).

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

• Compuesto únicamente por Node.js 22 / TypeScript / selenium-webdriver (sin servidor HTTP, base de datos, DI, ni framework de logging)

• El transporte MCP es únicamente stdio

• Solo hay una sesión de navegador, las operaciones de WebDriver son completamente secuenciales

• No devuelve el HTML completo; inspect_page devuelve información de pantalla resumida para el LLM

• Sin flujo de aprobación. La operación se ejecuta en el momento de llamar a la herramienta

Índice

1. Inicio rápido

2. Requisitos previos

3. Configuración previa en Windows

4. Instalación y compilación

5. Variables de entorno

6. Método de inicio

7. Registro en el agente de IA

8. Referencia de herramientas

9. Ejemplos de uso

10. Errores y soluciones

11. Registros

12. Solución de problemas

13. Desarrollo

14. Limitaciones

1. Inicio rápido

Ejecuta lo siguiente en Windows.

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

Si aparece {"level":"info","event":"started","transport":"stdio"} en stderr, el inicio es correcto. Normalmente no se inicia manualmente, sino que se inicia automáticamente desde la configuración MCP del agente de IA.

2. Requisitos previos

• IEDriverServer.exe se obtiene de la página de descarga de Selenium y se coloca en una carpeta cualquiera (ejemplo: C:\tools\). La versión de 64 bits tiene limitaciones conocidas, por lo que Selenium oficial recomienda usar la versión de 32 bits.

• IEDriver se ve afectado por la GUI, el foco de ventana y los eventos nativos, por lo que se recomienda usarlo en una VM de Windows dedicada o una sesión de Windows dedicada.

• No se contempla una configuración donde el navegador funcione en un servicio de Windows (Sesión 0).

• El servidor MCP, IEDriver y Edge deben ejecutarse en el mismo entorno Windows.

3. Configuración previa en Windows

IEDriver se ve muy afectado por la configuración del entorno. Realiza la configuración manualmente primero antes de iniciar el servidor MCP.

3.1 Habilitar el modo IE de Edge

Verifica manualmente en Edge que el sitio objetivo se pueda abrir en modo IE. El modo IE se habilita mediante una de las siguientes políticas (bajo Software\Policies\Microsoft\Edge).

La configuración concreta depende de la política de la organización; para más detalles, consulta la documentación del modo IE de Microsoft y al administrador de tu organización. Asegúrate de tener las últimas actualizaciones de Windows y Edge.

3.2 Configuración requerida por IEDriver

Si la configuración del modo protegido no está unificada, browser_start fallará. No se utiliza introduceFlakinessByIgnoringProtectedModeSettings de IEDriver porque hace que el comportamiento sea inestable.

4. Instalación y compilación

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

El resultado es dist/index.js. Después de compilar, también se puede iniciar con npm start (= node dist/index.js).

5. Variables de entorno

No se utiliza archivo de configuración (YAML / JSON), solo se configura mediante variables de entorno.

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

• A partir de IE Driver 4.5.0, Edge se detecta automáticamente en entornos sin IE (por defecto en Windows 11), por lo que normalmente no se necesita IE_MCP_EDGE_PATH. Solo especificarlo explícitamente si la detección automática falla.

• Si se prioriza la reproducibilidad de la operación, se recomienda especificar explícitamente IE_MCP_DRIVER_PATH.

• IE_MCP_ALLOWED_ORIGINS es una restricción simple para evitar operaciones incorrectas; se evalúa mediante coincidencia exacta del origen (scheme + host + port). No se restringe por ruta.

6. Método de inicio

Inicio manual (para verificar funcionamiento)

PowerShell:

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

Símbolo del sistema:

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

Espera conexiones del cliente mediante stdio. La entrada/salida estándar se usa para el protocolo MCP, por lo que no hay respuesta si se introduce texto en este estado (es normal). Todos los registros se emiten por stderr. Para salir, pulsa Ctrl+C (el navegador también se cierra automáticamente).

Nota: El inicio del servidor MCP no inicia el navegador. El navegador se inicia cuando el agente llama a browser_start.

Operación normal

El agente de IA (cliente MCP) inicia este servidor como un proceso hijo. No es necesario iniciarlo manualmente. Realiza la configuración del siguiente capítulo.

7. Registro en el agente de IA

Añade lo siguiente al archivo de configuración del cliente MCP.

{
  "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"
      }
    }
  }
}

• Las rutas deben escaparse con barras invertidas dentro del JSON (C:\...).

• En args se especifica la ruta absoluta de dist/index.js después de la compilación.

• En Claude Code, también se puede registrar con claude mcp add.

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

Después del registro, si el cliente ve las 10 herramientas, incluyendo browser_start, la conexión es correcta.

8. Referencia de herramientas

Se publican 10 herramientas. No se exponen las API de bajo nivel de WebDriver (como findElement / executeScript).

Común: Selector

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

En las aplicaciones web heredadas, name y xpath se usan con frecuencia, por lo que se admiten.

Común: frame (iframe de 1 nivel)

Todas las herramientas de manipulación de elementos aceptan un frame opcional. Si se especifica, se vuelve a defaultContent y luego se cambia al frame, y se busca el elemento dentro de él.

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

browser_start

{}

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

reused: true indica que se ha reutilizado la sesión existente. Si la sesión existente está muerta, se reinicia automáticamente.

navigate

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

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

inspect_page

Es la herramienta principal para que el agente entienda la pantalla. No devuelve el HTML completo, solo la URL / título / texto visible / elementos operables (a, button, input, textarea, select, iframe). Los elementos ocultos y los input con type="hidden" se excluyen.

{ "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 indica que el número de elementos ha alcanzado el límite (300) y se ha truncado.

• Si la lista de elementos incluye un iframe, para ver su contenido se debe llamar de nuevo especificando el frame.

click

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

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

Espera a que el elemento esté visible y habilitado, luego hace clic. click no reintenta automáticamente (para evitar procesamiento duplicado si el registro, actualización o envío ya se ha completado y se vuelve a hacer clic).

type

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

Si clear (por defecto true) es true, se ejecuta clear() antes de introducir el texto; si es false, se añade al texto existente.

select

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

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

by puede ser text / value / index (index empieza en 0).

wait_for

No utiliza sleep fijo, sino que espera explícitamente.

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

Si se omite timeoutMs, se usa IE_MCP_TIMEOUT_MS.

switch_window

{ "target": "newest" }

{ "index": 1 }

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

newest sondea brevemente hasta que aparezca un nuevo identificador de ventana. Si no se detecta, cambia a la última ventana existente.

screenshot

{}

Devuelve una imagen PNG (contenido de imagen de MCP). Se usa para confirmar el diseño o las pantallas de error que no se pueden determinar solo con el DOM.

9. Ejemplos de uso

Bucle básico

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

Repite: inspect_page para entender la pantalla → operar → wait_for para esperar el resultado → inspect_page de nuevo.

Ejemplo: Buscar al cliente «Yamada Tarō» y abrir la pantalla de detalle

Ejemplo: Operar dentro de un iframe

{"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" }
}}

La especificación del frame se debe pasar en cada operación (porque internamente se vuelve a defaultContent y luego se cambia al frame, el estado no se mantiene entre operaciones).

Ejemplo: Operar una ventana emergente y volver a la ventana original

{"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. Errores y soluciones

Los errores no devuelven el stack trace de Selenium, sino que se devuelven con el siguiente código (isError: true).

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

Recuperación de DRIVER_LOST

Si el navegador o el driver se bloquean, el WebDriver interno se destruye y las operaciones posteriores devolverán BROWSER_NOT_STARTED. No se realiza recuperación automática ni reejecución automática de la operación anterior (para evitar efectos secundarios como registros duplicados). El agente debe volver a llamar a browser_start, verificar el estado de la pantalla con inspect_page y reanudar las operaciones. No se debe reejecutar directamente la operación anterior, ya que podría haberse completado.

11. Registros

stdout lo utiliza el protocolo MCP, por lo que todos los registros se emiten a stderr en una línea JSON.

{"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}

No se registra la cadena de entrada en sí, las cookies, la información de autenticación ni el HTML completo (de type solo se registra el número de caracteres). Si se desea guardar en un archivo, redirigir stderr.

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

12. Solución de problemas

screenshot es útil para investigar causas. Permite verificar estados que no se pueden determinar solo con información del DOM (modales, diálogos de autenticación, errores de renderizado).

13. Desarrollo

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

• La herramienta MCP no toca directamente Selenium, siempre pasa por BrowserManager.

• Todas las operaciones de WebDriver están serializadas mediante una Promise Chain; incluso si la herramienta se llama en paralelo, solo se envía una solicitud a la vez a IEDriver.

• Solo se reintentan operaciones sin efectos secundarios (búsqueda de elementos, detección de manejadores de ventana). No se reintentan click ni envíos.

14. Limitaciones

La implementación inicial no admite lo siguiente:

Múltiples sesiones de navegador / Múltiples usuarios / Transporte HTTP / API REST / DB / Persistencia de sesión / Recuperación automática del navegador / Política de reintentos compleja / WebDriver Grid / API genérica de Selenium / Herramienta executeScript / iframes anidados (solo un nivel) / Caché de elementos / Métricas / Flujo de aprobación / Autenticación y autorización