tauri-plugin-mcp

通过 MCP (Model Context Protocol) 实现的跨平台 Tauri 测试自动化插件。

使 Claude 等 AI 助手能够与您的 Tauri 桌面应用进行交互，以进行测试和自动化。

Claude Code 插件

本仓库同时也是一个 Claude Code 插件。实现完整配置只需三步：

1. 添加市场并安装插件

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

安装过程中，系统会提示您输入：

Tauri 应用目录：相对于项目根目录的路径（例如，单应用仓库为 .，Monorepo 为 apps/desktop）。

2. 运行安装程序命令

/tauri-mcp:install

此命令会自动编辑您的 Tauri 项目：Cargo.toml、src-tauri/src/lib.rs、capabilities、package.json、前端入口 (main.tsx/main.ts) 以及 .gitignore。每次写入都会先预览差异并要求您确认。

3. 重启 Claude Code

tauri-mcp MCP 服务器会在重启时注册。使用 /mcp 进行验证 — 它应该显示 tauri-mcp 已连接。现在您可以调用 start_session、snapshot、click 等命令。

为什么要重启？

MCP 服务器在 Claude Code 启动时注册。安装插件或更改 tauri_app_dir 都需要重启才能生效。

插件包含的内容

MCP 服务器以自包含的单文件包 (packages/tauri-mcp/dist/index.js) 形式发布，所有依赖项均已内联 — 目标机器上无需 node_modules，因此在 macOS、Linux 和 Windows 上的安装方式完全相同。

包含内容：

组件	描述
MCP 服务器	自包含的 `tauri-mcp` 包（包含 14 个用于应用生命周期、UI 交互、截图、日志记录的工具）
`/tauri-mcp:install` 命令	一键式安装程序，用于编辑您的 Tauri 项目以连接插件
`tauri-qa` 技能	QA 编排 — 准备测试场景、委派给 QA 代理、验证结果
`tauri-debug` 技能	针对常见 MCP 会话问题的诊断决策树
`qa-tester` 代理	使用 MCP 工具执行测试场景的测试代理 (haiku)
QA 验证钩子	验证 QA PASS 结果是否包含实际的工具调用证据

特性

跨平台：Windows (命名管道) + macOS/Linux (Unix 套接字)
无 CDP 依赖：适用于所有 WebView 后端，包括 macOS WKWebView
MCP 集成：与 Claude Code 及其他 MCP 客户端直接集成
多窗口支持：通过标签定位任何窗口；自动桥接注入
统一日志记录：包含过滤功能的构建、运行时、控制台和网络日志
动态端口分配：自动随机分配端口以避免冲突

先决条件

Node.js >= 18
Tauri v2.x
pnpm (推荐) 或 npm
Rust (配合 cargo)

快速开始

[ ] 将 Rust 插件添加到 src-tauri/Cargo.toml
[ ] 安装 npm 包：pnpm add github:DaveDev42/tauri-plugin-mcp#main
[ ] 在 src-tauri/src/lib.rs 中注册插件
[ ] 添加 mcp:default 权限
[ ] 在 main.tsx 中初始化桥接
[ ] 为 Claude Code 创建 .mcp.json

安装

1. Rust 插件 (src-tauri/Cargo.toml)

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

2. 前端 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. 添加权限

选项 A：在 tauri.conf.json 或 config/*.json5 中（推荐）

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

选项 B：单独的文件 (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 分离到其自己的 capability 文件中，以便在构建时进行切换。

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 — 条件 capabilities 管理

当启用该特性时，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。

Monorepo 配置

如果 Tauri 应用位于子目录中（例如 apps/desktop），请设置 TAURI_APP_DIR：

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

多个 Tauri 应用

对于包含多个 Tauri 应用的 Monorepo，请为每个应用运行一个单独的 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 等。

可用工具

会话生命周期

工具	参数	描述
`get_session_status`	`probe_bridge?: boolean`	检查会话（应用）状态；若 `probe_bridge: true`，包含每个窗口的桥接健康状况
`start_session`	`wait_for_ready?: boolean`, `timeout_secs?: number`, `features?: string[]`, `devtools?: boolean`	启动会话（通过 `pnpm tauri dev` 启动 Tauri 应用）
`stop_session`	-	停止会话（终止应用进程树）

窗口管理

工具	参数	描述
`list_windows`	-	列出所有打开的窗口及其标签、标题、焦点状态和桥接状态
`focus_window`	`window: string`	通过标签聚焦特定窗口

交互

所有交互工具都接受一个可选的 window 参数以定位特定窗口（默认为当前焦点窗口）。

工具	参数	描述
`snapshot`	`window?`	获取带有 `click`/`fill` 引用编号的辅助功能树
`click`	`ref?: number`, `selector?: string`, `window?`	通过引用或 CSS 选择器点击元素
`fill`	`ref?: number`, `selector?: string`, `value: string`, `window?`	填充输入字段
`press_key`	`key: string`, `window?`	按下键盘按键（例如 "Enter", "Tab"）
`navigate`	`url: string`, `window?`	导航到 URL
`screenshot`	`window?`	通过原生 OS 捕获进行截图
`evaluate_script`	`script: string`, `window?`	在 webview 中执行 JavaScript

可观测性

工具	参数	描述
`get_logs`	`filter?: string[]`, `limit?: number`, `clear?: boolean`, `window?`	统一日志访问（构建、运行时、控制台、网络），支持源/级别过滤
`get_restart_events`	`limit?: number`, `clear?: boolean`, `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

Rust 插件 创建 IPC 服务器（Unix 套接字或 Windows 命名管道）
MCP 服务器 连接到 IPC 并向 Claude 公开工具
JS 桥接 (initMcpBridge()) 在 WebView 中启用 DOM 操作

套接字路径

Unix: {project_root}/.tauri-mcp.sock
Windows: \.pipe auri-mcp-{hash} (哈希值由项目路径派生)

故障排除

"MCP bridge not initialized"

JS 桥接未运行。请检查：

前端代码中是否调用了 initMcpBridge()
应用是否在开发模式下运行 (import.meta.env.DEV)
检查浏览器控制台是否有初始化错误

套接字连接失败

确保应用正在运行（先执行 start_session）
在 Windows 上，检查日志中的管道路径：[tauri-plugin-mcp] full_path: \.pipe auri-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:...) 无需构建步骤即可工作。预提交钩子会验证 dist/ 是否与 TypeScript 源码保持同步 — 如果钩子阻止了您的提交，请运行：

pnpm build
git add packages/*/dist/

然后重试您的提交。

许可证

MIT OR Apache-2.0