Popup MCP
让 AI Agent 能够“看见”你 —— 一个赋予 LLM 弹窗交互能力的 MCP Server。
popup-mcp 是一个基于 Tauri + Vue 构建的 MCP (Model Context Protocol) Server。它弥补了 Agent 在本地运行时缺乏即时用户反馈机制的短板，以原生窗口的形式提供类似于 Claude Code 的交互体验。
当你的 Agent 需要人类确认敏感操作、从用户处获取具体参数时，popup-mcp 能够优雅地唤起弹窗并等待用户输入。
✨ 核心特性
- 交互式问卷 (
ask_user_question)：- 支持单选、多选列表。
- 支持开放式文本输入。
- 支持取消操作，并允许用户在提交时附带额外上下文信息。
- 安全确认 (
confirm)：- 适用于敏感操作（如文件删除、代码执行）前的二次确认。
- 支持自定义确认/取消文案及默认选项。
- 危险操作警示样式。
- 原生体验：
- 支持键盘快捷键操作，效率至上。
- 跨平台支持（Windows/macOS/Linux）。
- 界面语言支持中/英切换。
📸 效果展示
1. 交互式问卷 (Questionnaire)
Agent 可以通过问卷收集用户的意图或配置信息。
| 场景 | 截图 |
|---|---|
| 基础提问 |  |
| 多选模式 |  |
| 提交界面 |  |
| 取消窗口 |  |
2. 操作确认 (Confirmation)
🚀 快速开始
系统要求
- 操作系统:
- Windows 11 x64 (其他 Windows 版本未充分验证)
- macOS x64/arm64 (实验性)
- Linux x64 (实验性)
- 网络: 首次下载二进制文件需要访问 GitHub Releases。
说明：CI 会在 macOS/Linux/Windows 上构建发布产物，但不代表已在对应系统完成完整运行验证。
安装（二进制）
- 从 GitHub Releases 下载与你平台匹配的发布包（推荐下载压缩包）：
- Windows:
popup-mcp-v<版本>-windows-x86_64.zip - macOS:
popup-mcp-v<版本>-macos-x64.tar.gz/popup-mcp-v<版本>-macos-arm64.tar.gz - Linux:
popup-mcp-v<版本>-linux-x86_64.tar.gz
- Windows:
- 解压后得到可执行文件：
- Windows（PowerShell）：
Expand-Archive popup-mcp-v<版本>-windows-x86_64.zip -DestinationPath . - macOS/Linux：
tar -xzf popup-mcp-v<版本>-macos-x64.tar.gz（按需替换为对应文件名）
- Windows（PowerShell）：
- 将可执行文件放到你希望的位置（任意目录均可），并记住它的绝对路径。
- macOS/Linux 如遇到权限问题，赋予可执行权限：
chmod +x popup-mcp
说明：Release 同时提供“裸二进制”（例如
popup-mcp-v<版本>-macos-x64/popup-mcp-v<版本>-windows-x86_64.exe）和压缩包；无需放入固定目录，直接在 MCP 配置里把command设置为该可执行文件的完整路径即可。
MCP 客户端配置
请将以下配置添加到你使用的 MCP Client (如 Claude Desktop, Codex CLI 等) 的配置文件中。
1. 通用配置 (Claude Desktop 等)
{
"mcpServers": {
"popup": {
"command": "C:\\\\path\\\\to\\\\popup-mcp.exe",
"args": []
}
}
}
macOS/Linux 示例：
"command": "/abs/path/to/popup-mcp"。
2. Codex CLI 配置
[mcp_servers.popup-mcp]
command = "C:\\path\\to\\popup-mcp.exe"
type = "stdio"
args = []
# 建议设置较长的超时时间，防止用户思考或输入时连接断开
tool_timeout_sec = 3600
macOS/Linux 示例：
command = "/abs/path/to/popup-mcp"。
3. WSL 环境配置
由于 WSL 无法直接调用 Windows 的 GUI 窗口，需要通过 mcp-proxy 进行转发。
-
在 Windows 端 (PowerShell) 运行代理服务：
npx -y mcp-proxy --port 3333 "C:\\path\\to\\popup-mcp.exe" -- --header-text Codex提示：当
mcp-proxy退出（例如 Ctrl+C）或连接断开时，popup-mcp会随 stdio 连接结束而自动退出，避免残留后台进程。 -
在 WSL 端 配置 MCP Client：
[mcp_servers.popup-mcp] # 尝试连接宿主机代理 url = "http://localhost:3333/mcp" # 部分客户端可能需要使用 "/sse" 后缀 tool_timeout_sec = 3600
⚙️ 启动参数
你可以通过 args 传递以下参数来自定义行为：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--ui-lang | zh | en | 系统语言 | 强制指定界面语言 |
--ui-timeout-seconds | number | 0 (无超时) | UI 等待用户操作的最大时长（秒） |
--header-text | string | 空字符串 | 覆盖顶部栏工具名；空或仅空格时回退默认值 |
💡 Prompt 最佳实践
虽然工具定义了参数结构，但 LLM 并不总是知道何时该调用此工具。建议在 System Prompt 中显式加入如下类似的指引：
## 交互工具与使用优先级
- 交互优先原则：除非需求已完全清晰且风险极低，一旦出现不确定性、重要权衡或多方案选择，应优先调用交互工具，而不是直接假设用户意图。
- `ask_user_question`
- 用途：进行结构化提问，收集用户决策和反馈。
- 场景：在设计模式中收集方案偏好，在规划模式中确认实施细节，在执行模式中澄清不确定需求或边界。
- 要求：采用多轮提问，逐步收敛需求。
- **必须使用场景：存在模糊需求和隐含假设，或需要向用户提问、确认**
- **使用方式：循环提问，直到需求完全明确**
- `confirm_action`
- 用途：获取用户明确的确认或拒绝。
- 场景：要进行潜在高风险操作（如大规模重构、批量重命名/删除文件）之前，向用户进行确认。
在多 Agent 并行调用或多个工具共用同一 popup-mcp 实例的场景下，推荐在提示词中同时约定好 topic 参数的使用，用于区分窗口主题/来源：
ask-user-question/confirm-action的参数中都支持必填字段topic: string，会显示在弹窗顶部标题栏中（例如Popup MCP • Code Review Agent）。
这样，即使多个 Agent 同时使用本 MCP，用户也能从窗口顶栏一眼看出当前弹窗是由哪一个 Agent 发起的。
🛠️ 贡献指南
欢迎提交 Issue 和 PR！如果你想参与开发，请参考以下步骤。
环境准备
确保本地已安装：
- Node.js >= 18 & pnpm
- Rust (最新稳定版)
- Tauri CLI（本项目使用
@tauri-apps/cli，随pnpm install安装；通常无需额外全局安装）
Linux 开发/构建时，可能还需要系统依赖（与 CI 一致），例如：
libwebkit2gtk-4.1-dev、libappindicator3-dev、librsvg2-dev、patchelf、libssl-dev。
安装与构建
# 1. 安装前端依赖
pnpm install
# 2. 初始化 Rust 依赖 (Tauri 会自动处理)
# 此时可以检查 src-tauri 目录下的环境
项目结构概览
src/: 前端源码 (Vue 3)src-tauri/: 后端源码 (Rust)src/mcp/: 核心逻辑，处理 MCP 协议与 Tauri Window 的通信
OVERVIEW.md: 📜 详细架构说明 (推荐阅读)
开发调试
启动开发模式后，支持热重载：
pnpm tauri dev
启动后，焦点可能会聚焦到被隐藏的窗口上。按 Ctrl + Shift + I (Windows/Linux) 或 Cmd + Option + I (macOS) 打开开发者工具。你可以直接在 Console 中执行以下代码模拟后端发往前端的 ui:request 事件，用于预览 UI 样式：
const { window: tauriWin, event: tauriEvent } = window.__TAURI__;
const win = tauriWin.getCurrentWindow();
// 显示窗口
await win.show();
// 统一事件通道：ui:request
await tauriEvent.emit("ui:request", {
id: "dev-question",
kind: "ask-user-question",
request: {
topic: "开发调试",
questions: [
{
question: "Detect environment?",
header: "Env Check",
multiSelect: false,
options: [
{ label: "Production", description: "Live environment" },
{ label: "Development", description: "Local testing" },
],
},
],
},
});
await tauriEvent.emit("ui:request", {
id: "dev-confirm",
kind: "confirm-action",
request: {
title: "确认示例",
message: "用来检查 confirm 卡片样式",
confirmLabel: "OK",
cancelLabel: "再看看",
danger: false,
defaultConfirm: true,
topic: "开发调试",
},
});
说明：上述方式仅用于前端样式调试；因为没有对应的后端等待队列，点击按钮后产生的结果不会返回到 MCP 调用方。
📄 许可证
MIT License