macos-ui-mcp

Инструмент в стиле Playwright, который позволяет Claude осматривать и управлять интерфейсом нативного macOS-приложения, пока вы его создаёте — без разрешения на запись экрана.

Вместо захвата экрана приложение отрисовывает само себя. Крошечный debug-only Swift-пакет (swift-harness/) предоставляет дерево представлений приложения и внутрипроцессный PNG-рендерер через localhost HTTP; MCP-сервер (src/) превращает это в инструменты, которые может вызывать Claude: list_windows, get_ui_tree, screenshot, click, type, wait_for, invoke_action.

См. IDEA.md с обоснованием дизайна, сравнением архитектур и целями проекта.

Claude Code ──MCP(stdio)──> macos-ui-mcp server ──HTTP──> AppMCPHarness (in your app, DEBUG only)

Структура

Related MCP server: Desktop Pilot MCP

Использование

1. Добавьте harness в ваше macOS-приложение (только DEBUG-сборки)

См. swift-harness/README.md. Одна строка в вашем AppDelegate:

#if DEBUG
AppMCP.start()   // opens http://127.0.0.1:8787
#endif

2. Соберите MCP-сервер

npm install
npm run build

3. Зарегистрируйте его в Claude Code

// .mcp.json
{
  "mcpServers": {
    "macos-ui-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/macos-ui-mcp/dist/index.js"],
      "env": { "MACOS_UI_MCP_HARNESS_URL": "http://127.0.0.1:8787" }
    }
  }
}

Теперь, когда ваше приложение запущено в debug-сборке, попросите Claude вызвать get_ui_tree или screenshot — без запроса на запись экрана.

Разработка

npm test           # 38 unit tests, no real app needed (mock harness); e2e is skipped
npm run typecheck
npm run dev         # run the server against a live harness

npm run test:e2e    # builds showcase/, launches it, runs the real tools against the
                    # real Swift harness. Needs a logged-in macOS GUI session.

npm run test:e2e — доказательство целей: он проверяет, что get_ui_tree видит элементы управления, screenshot возвращает настоящий внутрипроцессный PNG, а click / type изменяют живой интерфейс — без разрешения на запись экрана.

Грамматика селекторов

Используется в click, type, screenshot, wait_for:

click / type отклоняют неоднозначные селекторы (более одного совпадения) и сообщают id кандидатов.

Статус

• v0.1 — macOS / AppKit. Реализованы все 7 инструментов. 38 модульных тестов + end-to-end тест из 5 сценариев, который управляет приложением showcase/ через реальный Swift harness. Проверено: дерево, внутрипроцессный PNG-снимок, нажатие, установка текста, хуки действий — запись экрана выключена.

• Ещё нет — нативное дерево SwiftUI (пока только интроспекция AppKit), адаптер для Windows, инспекция сторонних приложений через Accessibility API.

Лицензия

MIT © 2026 Thang Duong

macos-ui-mcp