ie-mode-mcp

MCP-сервер для управления устаревшими веб-приложениями, работающими в режиме IE браузера Microsoft Edge, через агента ИИ по протоколу MCP (Model Context Protocol).

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

• Состоит только из Node.js 22 / TypeScript / selenium-webdriver (без HTTP-сервера, БД, DI, фреймворка логирования)

• Транспорт MCP — только stdio

• Только одна сессия браузера, операции WebDriver выполняются полностью последовательно

• Полный HTML не возвращается; inspect_page возвращает сводную информацию об экране, предназначенную для LLM

• Нет потока утверждения. Операция выполняется в момент вызова инструмента

Содержание

1. Быстрый старт

2. Предварительные требования

3. Предварительная настройка на стороне Windows

4. Установка и сборка

5. Переменные окружения

6. Способы запуска

7. Регистрация в AI-агенте

8. Справочник инструментов

9. Примеры использования

10. Ошибки и их устранение

11. Логирование

12. Устранение неполадок

13. Разработка

14. Ограничения

1. Быстрый старт

Выполните следующее в 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

Если в stderr выводится {"level":"info","event":"started","transport":"stdio"}, запуск успешен. Обычно сервер запускается не вручную, а автоматически через конфигурацию MCP на стороне AI-агента.

2. Предварительные требования

• Загрузите IEDriverServer.exe со страницы загрузки Selenium и поместите в любую папку (например, C:\tools\). Из-за известных ограничений 64-битной версии Selenium рекомендует использовать 32-битную версию.

• IEDriver подвержен влиянию графического интерфейса, фокуса окна и нативных событий, поэтому рекомендуется использовать выделенную виртуальную машину Windows или выделенный сеанс Windows.

• Конфигурация с запуском браузера в службе Windows (Сеанс 0) не поддерживается.

• MCP-сервер, IEDriver и Edge должны работать в одной среде Windows.

3. Предварительная настройка на стороне Windows

IEDriver сильно зависит от настроек среды. Перед запуском MCP-сервера сначала выполните настройку вручную.

3.1 Включение режима IE в Edge

Предварительно убедитесь вручную в Edge, что целевой сайт открывается в режиме IE. Режим IE включается одной из следующих политик (в разделе Software\Policies\Microsoft\Edge).

Конкретная конфигурация зависит от политики организации, поэтому обратитесь к документации Microsoft по режиму IE и к администратору вашей организации. Убедитесь, что Windows и Edge обновлены до последних версий.

3.2 Настройки, требуемые IEDriver

Если настройки защищённого режима не унифицированы, browser_start завершится ошибкой. Параметр IEDriver introduceFlakinessByIgnoringProtectedModeSettings не используется, так как он делает работу нестабильной.

4. Установка и сборка

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

Результат сборки — dist/index.js. После сборки можно запустить также через npm start (= node dist/index.js).

5. Переменные окружения

Файлы конфигурации (YAML / JSON) не используются; настройка осуществляется только через переменные окружения.

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

• Начиная с IE Driver 4.5.0, в средах без IE (по умолчанию в Windows 11) он автоматически обнаруживает Edge, поэтому IE_MCP_EDGE_PATH обычно не требуется. Указывайте явно только в случае неудачного автоматического обнаружения.

• Для обеспечения воспроизводимости в работе рекомендуется явно указывать IE_MCP_DRIVER_PATH.

• IE_MCP_ALLOWED_ORIGINS — это простое ограничение для предотвращения случайных операций; проверяется полное совпадение Origin (схема + хост + порт). Ограничение по пути не применяется.

6. Способы запуска

Ручной запуск (для проверки работы)

PowerShell:

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

Командная строка:

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

Ожидает подключения клиента через stdio. Стандартный ввод/вывод используется для протокола MCP, поэтому в этом состоянии ввод с клавиатуры не даёт ответа (нормально). Все логи выводятся в stderr. Выход — Ctrl+C (браузер также автоматически закрывается).

Примечание: Запуск MCP-сервера не запускает браузер. Браузер запускается, когда агент вызывает browser_start.

Обычная эксплуатация

AI-агент (MCP-клиент) запускает данный сервер как дочерний процесс. Ручной запуск не требуется. Выполните настройку, описанную в следующей главе.

7. Регистрация в AI-агенте

Добавьте следующее в файл конфигурации 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"
      }
    }
  }
}

• В JSON экранируйте обратную косую черту в путях (C:\\...).

• В args укажите абсолютный путь к собранному dist/index.js.

• В случае Claude Code также можно зарегистрировать через 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

После регистрации, если на стороне клиента видны 10 инструментов, включая browser_start, подключение успешно.

8. Справочник инструментов

Предоставляется 10 инструментов. Низкоуровневые API WebDriver (например, findElement / executeScript) не предоставляются.

Общее: Селектор

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

В устаревших веб-приложениях часто используются name и xpath, поэтому они поддерживаются.

Общее: frame (только один уровень iframe)

Все инструменты для работы с элементами могут принимать опциональный frame. При указании сначала возвращаются в defaultContent, затем переключаются на фрейм и выполняют поиск элемента внутри него.

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

browser_start

{}

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

reused: true указывает, что используется существующая сессия. Если существующая сессия неактивна, он автоматически запускается заново.

navigate

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

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

inspect_page

Основной инструмент для понимания состояния экрана агентом. Не возвращает полный HTML, а только URL / заголовок / отображаемый текст / интерактивные элементы (a button input textarea select iframe). Скрытые элементы и input с type="hidden" исключаются.

{ "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 указывает, что список элементов обрезан по лимиту (300 записей).

• Если в списке элементов есть iframe, для просмотра его содержимого вызовите повторно с указанием frame.

click

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

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

Ожидает, пока элемент станет видимым и доступным, затем кликает. Автоматический повтор клика не выполняется (чтобы предотвратить повторную обработку, если регистрация, обновление или отправка уже выполнены).

type

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

Если clear (по умолчанию true) равно true, то после clear() вводит текст; если false — добавляет текст.

select

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

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

by может быть text / value / index (index начинается с 0).

wait_for

Не использует фиксированные задержки, а явно ожидает.

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

Если timeoutMs опущен, используется IE_MCP_TIMEOUT_MS.

switch_window

{ "target": "newest" }

{ "index": 1 }

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

newest выполняет кратковременный опрос появления нового дескриптора окна. Если не обнаружено, переключается на последнее существующее окно.

screenshot

{}

Возвращает PNG-изображение (как image content MCP). Используется для проверки макета или экрана ошибки, которые невозможно определить только по DOM.

9. Примеры использования

Основной цикл

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

Повторяйте: inspect_page для понимания экрана → операция → wait_for для ожидания результата → снова inspect_page.

Пример: Поиск клиента «Ямада Таро» и открытие экрана подробностей

Пример: Работа внутри 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" }
}}

Указание frame передаётся при каждой операции (внутри каждая операция сначала возвращается в defaultContent, затем переключается, поэтому состояние не сохраняется).

Пример: Работа с всплывающим окном и возврат в исходное окно

{"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. Ошибки и их устранение

Ошибки возвращаются не в виде Stack Trace Selenium, а в следующем коде (isError: true).

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

Восстановление после DRIVER_LOST

Если браузер или драйвер упал, внутренний WebDriver уничтожается, и последующие операции приводят к BROWSER_NOT_STARTED. Автоматическое восстановление и автоматический повтор последней операции не выполняются (чтобы предотвратить побочные эффекты, такие как двойная регистрация). На стороне агента вызовите browser_start заново, проверьте состояние экрана через inspect_page, затем возобновите операции. Последняя операция могла быть уже выполнена, поэтому не следует повторно выполнять операции регистрации/обновления как есть.

11. Логирование

stdout используется протоколом MCP, поэтому все логи выводятся в stderr одной строкой 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}

Сами входные строки, cookie, учётные данные и полный HTML не записываются (для type записывается только длина текста). Для сохранения в файл перенаправьте stderr.

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

12. Устранение неполадок

screenshot は原因調査に有効。DOM 情報だけでは判断できない状態（モーダル、認証ダイアログ、 レンダリング崩れ）を確認できる。

13. 開発

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 Tool は Selenium を直接触らず、必ず BrowserManager を経由する。

• すべての WebDriver 操作は Promise Chain で逐次化されており、Tool が並列に呼ばれても IEDriver へは 1 件ずつしか送られない。

• 副作用のない操作（要素検索・Window Handle 検出）のみ Retry する。click や送信は Retry しない。

14. 制限事項

初期実装では以下に対応しない。

複数ブラウザセッション / 複数ユーザー / HTTP Transport / REST API / DB / セッション永続化 / 自動ブラウザ復旧 / 複雑な Retry Policy / WebDriver Grid / 汎用 Selenium API / executeScript Tool / 多段 iframe（1 階層のみ）/ Element Cache / Metrics / 承認フロー / 認証・認可