tauri-plugin-mcp

Кроссплатформенный плагин для автоматизации тестирования Tauri через MCP (Model Context Protocol).

Позволяет ИИ-ассистентам, таким как Claude, взаимодействовать с вашим десктопным приложением Tauri для тестирования и автоматизации.

Плагин Claude Code

Этот репозиторий также является плагином для Claude Code. Три шага для полноценной настройки:

1. Добавьте маркетплейс и установите плагин

/plugin marketplace add DaveDev42/tauri-plugin-mcp
/plugin install tauri-mcp

Во время установки вас попросят указать:

• Директория приложения Tauri: путь относительно корня проекта (например, . для монорепозиториев с одним приложением, apps/desktop для монорепозиториев).

2. Запустите команду установки

/tauri-mcp:install

Это автоматически изменит ваш проект Tauri: Cargo.toml, src-tauri/src/lib.rs, capabilities, package.json, точку входа фронтенда (main.tsx/main.ts) и .gitignore. Каждое изменение предварительно показывается в виде diff и требует вашего подтверждения.

3. Перезапустите Claude Code

MCP-сервер tauri-mcp регистрируется при перезапуске. Проверьте с помощью /mcp — он должен отображаться как подключенный. Теперь вы можете вызывать start_session, snapshot, click и т.д.

Зачем перезапускать?

MCP-серверы регистрируются при запуске Claude Code. Установка плагина или изменение tauri_app_dir требуют перезапуска для вступления изменений в силу.

Что входит в плагин

MCP-сервер поставляется в виде автономного бандла из одного файла (packages/tauri-mcp/dist/index.js) со всеми встроенными зависимостями — на целевой машине не нужны node_modules, поэтому установка работает одинаково на macOS, Linux и Windows.

Что включено:

Возможности

• Кроссплатформенность: Windows (именованные каналы) + macOS/Linux (Unix-сокеты)

• Без зависимости от CDP: Работает на всех бэкендах WebView, включая macOS WKWebView

• Интеграция с MCP: Прямая интеграция с Claude Code и другими MCP-клиентами

• Поддержка нескольких окон: Управление любым окном по метке; автоматическое внедрение моста

• Единое логирование: Логи сборки, выполнения, консоли и сети с фильтрацией

• Динамическое выделение портов: Автоматическое назначение случайного порта для предотвращения конфликтов

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

• Node.js >= 18

• Tauri v2.x

• pnpm (рекомендуется) или npm

• Rust с cargo

Быстрый старт

1. [ ] Добавьте Rust-плагин в src-tauri/Cargo.toml

2. [ ] Установите npm-пакет: pnpm add github:DaveDev42/tauri-plugin-mcp#main

3. [ ] Зарегистрируйте плагин в src-tauri/src/lib.rs

4. [ ] Добавьте разрешение mcp:default

5. [ ] Инициализируйте мост в main.tsx

6. [ ] Создайте .mcp.json для Claude Code

Установка

1. Rust-плагин (src-tauri/Cargo.toml)

[dependencies]
tauri-plugin-mcp = { git = "https://github.com/DaveDev42/tauri-plugin-mcp" }

2. Frontend API (package.json)

pnpm add github:DaveDev42/tauri-plugin-mcp#main

3. MCP-сервер

Бинарный файл MCP-сервера (tauri-mcp) становится доступен автоматически после установки. Дополнительная настройка не требуется.

Настройка

1. Регистрация плагина (src-tauri/src/lib.rs)

pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_mcp::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

2. Добавление разрешений

Вариант А: В tauri.conf.json или config/*.json5 (рекомендуется)

{
  "security": {
    "capabilities": [{
      "identifier": "main-capability",
      "windows": ["main"],
      "permissions": ["core:default", "mcp:default"]
    }]
  }
}

Вариант Б: Отдельный файл (src-tauri/capabilities/default.json)

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "windows": ["main"],
  "permissions": ["core:default", "mcp:default"]
}

3. Инициализация моста (main.tsx)

// Initialize MCP bridge for E2E testing (dev mode only)
if (import.meta.env.DEV) {
  import('tauri-plugin-mcp').then(({ initMcpBridge }) => {
    initMcpBridge().catch(err => {
      console.warn('[MCP] Bridge initialization failed:', err);
    });
  });
}

Безопасная настройка для продакшена (опциональная зависимость)

Базовая настройка выше включает MCP во всех сборках. Для продакшн-приложений вам, вероятно, нужно, чтобы MCP был только в режиме разработки и полностью удалялся из релизных бинарных файлов.

Этот подход использует функцию опциональных зависимостей Cargo, поэтому плагин компилируется только тогда, когда это явно запрошено.

1. Опциональная зависимость Cargo (src-tauri/Cargo.toml)

[features]
default = []
dev-tools = ["dep:tauri-plugin-mcp"]

[dependencies]
tauri-plugin-mcp = { git = "https://github.com/DaveDev42/tauri-plugin-mcp", optional = true }

2. Условная регистрация плагина (src-tauri/src/lib.rs)

pub fn run() {
    let mut builder = tauri::Builder::default();

    #[cfg(feature = "dev-tools")]
    {
        builder = builder.plugin(tauri_plugin_mcp::init());
    }

    builder
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

3. Разделение файла capabilities

Вынесите mcp:default в отдельный файл возможностей, чтобы его можно было переключать во время сборки.

capabilities/default.json — всегда активен, без разрешения MCP:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "windows": ["main"],
  "permissions": ["core:default"]
}

capabilities/.dev-tools.json.disabled — шаблон разрешения MCP (отслеживается git):

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "dev-tools",
  "windows": ["main"],
  "permissions": ["mcp:default"]
}

capabilities/dev-tools.json — добавьте в .gitignore (генерируется во время сборки):

# Dev-tools capability (generated from .disabled at build time)
src-tauri/capabilities/dev-tools.json

4. build.rs — условное управление возможностями

build.rs копирует шаблон на место, когда функция включена, и удаляет его в противном случае:

fn main() {
    let dev_tools_cap = std::path::Path::new("capabilities/dev-tools.json");
    let source_path = std::path::Path::new("capabilities/.dev-tools.json.disabled");

    if std::env::var("CARGO_FEATURE_DEV_TOOLS").is_ok() {
        // Copy .disabled → active (skip if already identical to avoid rebuild churn)
        let should_copy = if dev_tools_cap.exists() {
            std::fs::read(source_path).ok() != std::fs::read(dev_tools_cap).ok()
        } else {
            true
        };
        if should_copy {
            std::fs::copy(source_path, dev_tools_cap)
                .expect("Failed to copy dev-tools capability file");
        }
    } else if dev_tools_cap.exists() {
        std::fs::remove_file(dev_tools_cap).ok();
    }

    tauri_build::try_build(
        tauri_build::Attributes::default()
    ).expect("Failed to build tauri");
}

5. Скрипт разработки (package.json)

{
  "scripts": {
    "dev": "tauri dev --features dev-tools"
  }
}

Теперь pnpm dev включает MCP, а tauri build (без этой функции) создает чистый релиз без кода MCP.

Примечание: Защита моста фронтенда (import.meta.env.DEV) из базовой настройки по-прежнему применяется — она предотвращает инициализацию моста, даже если плагин каким-то образом присутствует во время выполнения.

Конфигурация MCP-сервера

Примечание: Если вы установили плагин Claude Code, MCP-сервер уже настроен автоматически. Плагин запрашивает директорию приложения Tauri во время установки. Этот раздел предназначен для ручной настройки без плагина.

Добавьте в .mcp.json в корне вашего проекта:

{
  "mcpServers": {
    "tauri-mcp": {
      "command": "npx",
      "args": ["tauri-mcp"],
      "env": {
        "TAURI_APP_DIR": "."
      }
    }
  }
}

Примечание: Пользователи pnpm также могут использовать pnpx tauri-mcp или pnpm exec tauri-mcp.

Конфигурация монорепозитория

Если приложение Tauri находится в поддиректории (например, apps/desktop), установите TAURI_APP_DIR:

{
  "mcpServers": {
    "tauri-mcp": {
      "command": "npx",
      "args": ["tauri-mcp"],
      "env": {
        "TAURI_APP_DIR": "./apps/desktop"
      }
    }
  }
}

Несколько приложений Tauri

Для монорепозиториев с несколькими приложениями Tauri запускайте отдельный экземпляр MCP-сервера для каждого приложения:

{
  "mcpServers": {
    "tauri-desktop": {
      "command": "npx",
      "args": ["tauri-mcp"],
      "env": { "TAURI_APP_DIR": "./apps/desktop" }
    },
    "tauri-kiosk": {
      "command": "npx",
      "args": ["tauri-mcp"],
      "env": { "TAURI_APP_DIR": "./apps/kiosk" }
    }
  }
}

Инструменты имеют пространство имен по имени сервера: mcp__tauri-desktop__snapshot, mcp__tauri-kiosk__snapshot и т.д.

Доступные инструменты

Жизненный цикл сессии

Управление окнами

Взаимодействие

Все инструменты взаимодействия принимают опциональный параметр window для выбора конкретного окна (по умолчанию используется сфокусированное окно).

Наблюдаемость

Использование параметра features

Для запуска с функциями Cargo:

start_session({ features: ["my_feature"] })

Это выполняет: pnpm tauri dev --features my_feature

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

Типичный рабочий процесс тестирования:

1. start_session({ timeout_secs: 120 })
2. snapshot()           # Get element refs
3. click({ ref: 5 })    # Click button by ref
4. fill({ selector: "input[name='email']", value: "test@example.com" })
5. screenshot()         # Verify result
6. stop_session()

Как это работает

Claude Code <-> MCP Server <-> Socket <-> Tauri Plugin <-> JS Bridge <-> Your App

1. Rust-плагин создает IPC-сервер (Unix-сокет или именованный канал Windows)

2. MCP-сервер подключается к IPC и предоставляет инструменты для Claude

3. JS-мост (initMcpBridge()) включает операции DOM в WebView

Пути к сокетам

• Unix: {project_root}/.tauri-mcp.sock

• Windows: \\.\pipe\tauri-mcp-{hash} (хэш вычисляется из пути к проекту)

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

"MCP bridge not initialized"

JS-мост не запущен. Проверьте:

• initMcpBridge() вызывается в коде вашего фронтенда

• Приложение запущено в режиме разработки (import.meta.env.DEV)

• Проверьте консоль браузера на наличие ошибок инициализации

Ошибка подключения к сокету

• Убедитесь, что приложение запущено (сначала start_session)

• В Windows проверьте путь к каналу в логах: [tauri-plugin-mcp] full_path: \\.\pipe\tauri-mcp-XXXXX

• В Unix проверьте, существует ли .tauri-mcp.sock в корне проекта

Тайм-аут запуска приложения

• Увеличьте timeout_secs (по умолчанию: 60)

• Проверьте, работает ли pnpm tauri dev вручную

• Ищите ошибки сборки в выводе терминала

snapshot возвращает пустоту

• Дождитесь полной загрузки приложения (используйте wait_for_ready: true)

• Проверьте, инициализирован ли мост (ищите логи [MCP] в консоли)

Разработка

После клонирования pnpm install автоматически настраивает git-хуки и собирает проект.

Директории dist/ фиксируются в репозитории, чтобы установки через git (pnpm add github:...) работали без этапа сборки. Pre-commit хук проверяет, что dist/ остается синхронизированным с исходниками TypeScript — если хук блокирует ваш коммит, выполните:

pnpm build
git add packages/*/dist/

Затем повторите коммит.

Лицензия

MIT OR Apache-2.0