<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 等)
```json
{
"mcpServers": {
"popup": {
"command": "C:\\\\path\\\\to\\\\popup-mcp.exe",
"args": []
}
}
}
```
> macOS/Linux 示例：`"command": "/abs/path/to/popup-mcp"`。
#### 2. Codex CLI 配置
```toml
[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)** 运行代理服务：
```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：
```toml
[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`。
### 安装与构建
```bash
# 1. 安装前端依赖
pnpm install
# 2. 初始化 Rust 依赖 (Tauri 会自动处理)
# 此时可以检查 src-tauri 目录下的环境
```
### 项目结构概览
- `src/`: 前端源码 (Vue 3)
- `src-tauri/`: 后端源码 (Rust)
- `src/mcp/`: **核心逻辑**，处理 MCP 协议与 Tauri Window 的通信
- `OVERVIEW.md`: 📜 **详细架构说明** (推荐阅读)
### 开发调试
启动开发模式后，支持热重载：
```bash
pnpm tauri dev
```
启动后，焦点可能会聚焦到被隐藏的窗口上。按 `Ctrl + Shift + I` (Windows/Linux) 或 `Cmd + Option + I` (macOS) 打开开发者工具。你可以直接在 Console 中执行以下代码模拟后端发往前端的 `ui:request` 事件，用于预览 UI 样式：
```javascript
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
