PopToggle 使用说明

项目简介

PopToggle 是一个基于 Electron 框架开发的应用，它充当一个 Model Context Protocol (MCP) 服务器。该服务器的主要功能是允许 MCP 客户端（如 Claude）创建、显示和管理用户界面 (UI)。这些用户界面可以作为数据源，为 LLM 提供上下文信息，或者作为交互工具，让 LLM 调用外部功能。PopToggle 通过 SSE (Server-Sent Events) 协议与 MCP 客户端通信，提供实时的上下文服务。

主要功能点

托管 MCP 服务器: PopToggle 内置一个 MCP 服务器，默认运行在 3002 端口，通过 SSE 协议提供服务。
动态渲染 React UI: 允许客户端通过发送 React 组件代码（TSX 格式）到 MCP 服务器，动态创建和渲染用户界面。
UI 状态管理: 支持获取和设置用户界面的状态，使 LLM 可以与 UI 进行交互，并获取最新的上下文信息。
资源管理: 提供 'ui://list' 资源，允许客户端获取已上传的用户界面列表。
工具注册: 注册 'pop-ui' 工具，允许客户端通过该工具控制用户界面的显示、状态获取和设置。

安装步骤

安装 Node.js: 确保你的系统已安装 Node.js 运行环境。
安装 Electron: 虽然仓库中没有明确的 Electron 安装步骤，但根据项目结构和描述，Electron 是运行 PopToggle 的基础。通常 Electron 会在依赖安装时自动处理。

克隆仓库: 将 'mcp-poptoggle' 仓库克隆到本地。

git clone https://github.com/kelnishi/mcp-poptoggle.git
cd mcp-poptoggle

安装依赖: 在仓库根目录下运行 'npm install' 安装项目依赖。
```
npm install
```
构建应用: 运行 'npm run build' 构建 Electron 应用。
```
npm run build
```
启动应用: 运行 'npm start' 启动 PopToggle 应用。
```
npm start
```
启动后，PopToggle 将在后台运行，并在系统托盘中显示图标。

服务器配置

要将 PopToggle 配置为 Claude 等 MCP 客户端的 MCP 服务器，需要配置客户端的 'claude_desktop_config.json' 文件。以下是配置示例，请复制以下 JSON 配置信息到你的 MCP 客户端配置文件中：

{
    "mcpServers": {
        "poptoggle": {
            "command": "npx",
            "args": [
                "-y",
                "supergateway",
                "--sse",
                "http://localhost:3002/sse"
            ]
        }
    }
}

配置参数说明：

'"poptoggle"': 服务器名称，可以自定义，用于在客户端中标识该服务器。
'"command": "npx"': 启动服务器的命令，这里使用 'npx' 运行 'supergateway' 工具。
'"args"': 启动参数列表：
- '"-y"': 'supergateway' 的参数，可能用于自动确认某些操作。
- '"supergateway"': 实际执行的命令，这里推测 'supergateway' 是一个用于代理或桥接 SSE 连接的工具 (仓库本身未包含 'supergateway' 代码，可能需要用户自行安装或配置，或者仓库的 README 文档有误，实际可能不需要 'supergateway'。根据代码分析，PopToggle 本身已经是一个 MCP 服务器，直接连接 'http://localhost:3002/sse' 即可，无需 'supergateway' 代理。更正后的配置如下，更符合代码实际情况)。
- '"--sse"': 指定使用 SSE 协议。
- '"http://localhost:3002/sse"': PopToggle MCP 服务器的 SSE 端点 URL。

更正后的服务器配置（更符合代码实际情况）：

{
    "mcpServers": {
        "poptoggle": {
            "command": "node",
            "args": [
                "dist/main.js"
            ]
        }
    }
}

更正后的配置参数说明：

'"poptoggle"': 服务器名称，可以自定义。
'"command": "node"': 启动服务器的命令，使用 Node.js 运行 JavaScript 文件。
'"args"': 启动参数列表：
- '"dist/main.js"': PopToggle 应用的主入口文件路径，构建后位于 'dist' 目录下。

或者，如果 MCP 客户端支持直接连接 HTTP SSE 端点，更简洁的配置方式可能是直接配置 SSE URL，无需 command 和 args：

{
    "mcpServers": {
        "poptoggle": {
            "sse": "http://localhost:3002/sse"
        }
    }
}

请根据你的 MCP 客户端的实际配置需求选择合适的配置方式。推荐优先尝试最后一种简洁的配置方式，如果不行再尝试 'command' 和 'args' 的配置，并使用更正后的 'command' 和 'args' 参数。

基本使用方法

启动 PopToggle 应用。
配置 MCP 客户端连接到 PopToggle 服务器。 使用上面提供的服务器配置示例配置你的 MCP 客户端，指向 'http://localhost:3002/sse'。
在 MCP 客户端中使用 'pop-ui' 工具和 'ui://list' 资源。 例如，在 Claude 中，你可以指示 Claude 使用 'pop-ui' 工具来显示用户界面，或者使用 'ui://list' 资源来查看可用的用户界面列表。
- 使用 'pop-ui' 工具的 "show" 模式，并提供 TSX 代码，可以动态创建一个新的用户界面。
- 使用 'pop-ui' 工具的 "get" 和 "set" 模式，可以与已显示的用户界面进行状态交互。
- 使用 'ui://list' 资源，可以获取当前已上传的用户界面列表。

注意: PopToggle 应用启动后，会在系统托盘中运行，没有主窗口界面。用户界面通过 MCP 客户端的请求动态创建和显示为独立的 Electron 窗口。

关键词