<p align="center"> <img src="./icon.svg" alt="Popup MCP Logo" width="200"/> </p>

<br/>

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 上构建发布产物，但不代表已在对应系统完成完整运行验证。

安装（二进制）

1. 从 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
2. 解压后得到可执行文件：
   • Windows（PowerShell）：Expand-Archive popup-mcp-v<版本>-windows-x86_64.zip -DestinationPath .
   • macOS/Linux：tar -xzf popup-mcp-v<版本>-macos-x64.tar.gz（按需替换为对应文件名）
3. 将可执行文件放到你希望的位置（任意目录均可），并记住它的绝对路径。
4. 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 进行转发。

1. 在 Windows 端 (PowerShell) 运行代理服务：

   npx -y mcp-proxy --port 3333 "C:\\path\\to\\popup-mcp.exe" -- --header-text Codex
   

   提示：当 mcp-proxy 退出（例如 Ctrl+C）或连接断开时，popup-mcp 会随 stdio 连接结束而自动退出，避免残留后台进程。

2. 在 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