☁️
Nexusgui
AI-generated GUI interfaces through MCP protocol with desktop rendering 通过 MCP 传递 GUI 定义,实现“AI 生成界面,桌面端渲染“
0 installs
6 stars
Trust: 54 — Fair
Cloud
Installation
npx nexusguiAsk AI about Nexusgui
Powered by Claude · Grounded in docs
I know everything about Nexusgui. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Loading tools...
Reviews
Documentation
NexusGUI
English | 中文
通过 MCP 传递 GUI 定义,实现 AI 生成界面,桌面端渲染
🎥 演示视频
观看完整功能演示:NexusGUI Demo Video
🚀 快速开始
安装依赖
npm install
启动应用
# 系统托盘模式启动(推荐)
npm start
# 或带主窗口启动
npm run start-with-window
使用 MCP 工具
启动后,应用会在 http://localhost:3001 启动 MCP 服务器,你可以通过以下方式使用:
- 连接到 MCP 服务器:
http://localhost:3001/mcp - 调用 render-gui 工具:
{
"title": "我的第一个界面",
"width": 600,
"height": 400,
"type": "html",
"content": "<div style='padding: 20px; text-align: center;'><h1>Hello NexusGUI!</h1><p>这是我的第一个动态界面</p></div>"
}
🆕 最新功能
系统托盘增强 🆕
- ✅ 支持系统托盘模式运行,无需保持主窗口
- ✅ 右击托盘图标访问MCP服务器控制台和调试功能
- ✅ 实时显示服务器状态、端口和活动会话信息
- ✅ 集成健康检查、调试信息、会话管理等工具
- ✅ 支持服务器设置和配置管理
- ✅ 跨平台支持(macOS、Windows、Linux)
- ✅ 增加最近渲染的界面历史记录,支持快速重新渲染
- ✅ 提供"快速测试"功能,渲染预定义的测试界面
- ✅ 增加网络状态指示,显示与 AI 工具的连接状态
HTML 直接渲染模式 🆕
- ✅ 支持直接传入 HTML 字符串进行界面渲染
- ✅ 支持 HTML 文件路径渲染(优先使用 HTML 字符串)
- ✅ 完全自定义的界面布局和样式
- ✅ 支持 JavaScript 事件处理和交互
- ✅ 内置
electronAPI.sendResult()函数用于同步等待结果
HTML 转 Markdown 文档缓存 🆕
- ✅ 自动将 HTML 内容转换为高质量的 Markdown 格式
- ✅ 智能保存 Markdown 文件到系统临时目录
- ✅ 支持获取 Markdown 文件路径和直接读取内容
- ✅ 提供灵活的缓存获取方式(HTML、Markdown 或两者兼有)
- ✅ 实现完整的文档缓存和读取功能,便于 AI 处理和版本管理
窗口复用功能 🆕
- ✅ 支持复用现有窗口而不是销毁重建
- ✅ 通过
reuseWindow参数控制窗口复用行为 - ✅ 保持窗口状态和位置,提升用户体验
- ✅ 减少资源消耗,提高性能
同步等待结果 🆕
- ✅ 支持
waitForResult参数同步等待窗口操作结果 - ✅ 窗口关闭或提交结果时返回数据
- ✅ 适用于需要用户输入确认的场景
窗口属性设置
- ✅ 支持丰富的窗口属性配置(菜单栏、边框、透明度、全屏等)
- ✅ 支持窗口尺寸限制(最小/最大宽高)
- ✅ 支持窗口行为控制(置顶、任务栏显示、可调整大小等)
- ✅ 支持窗口外观设置(透明度、缩放因子、全屏模式)
调试功能增强
- ✅ 提供统一的调试控制台,集中显示所有日志和调试信息
- ✅ 增加实时监控面板,显示服务器状态、会话数量、资源使用等
- ✅ 提供 API 测试工具,方便开发者测试 MCP 工具调用
🆕 重构后的架构
模块化工具系统 🆕
- ✅ 面向对象设计: 采用基于类的工具架构,提高代码可维护性
- ✅ 工具注册器: 统一管理所有MCP工具的注册、查找和执行
- ✅ 插件化扩展: 新工具只需继承基类并注册,支持热插拔
- ✅ Schema分离: 工具定义与实现分离,便于维护和扩展
- ✅ 单元测试: 每个工具可以独立测试,提高代码质量
- ✅ 错误隔离: 单个工具错误不影响其他工具运行
项目结构
NexusGUI/
├── src/ # 源代码目录
│ ├── main/ # 主进程代码
│ │ ├── main.js # Electron 主进程
│ │ └── preload.js # 预加载脚本
│ ├── renderer/ # 渲染进程代码
│ │ ├── renderer.js # 动态界面渲染器
│ │ ├── index.html # 主界面 HTML
│ │ └── styles.css # 样式文件
│ └── mcp/ # MCP 服务器代码
│ ├── sse/ # SSE 传输相关
│ │ ├── server.js # 重构后的 SSE MCP 服务器
│ │ ├── wrapper.js # SSE 服务器包装器
│ │ ├── transport.js # SSE 传输层
│ │ ├── tools/ # 🆕 工具模块目录
│ │ │ ├── BaseToolHandler.js # 基础工具处理器
│ │ │ ├── ToolRegistry.js # 工具注册器
│ │ │ ├── RenderGUITool.js # GUI渲染工具
│ │ │ ├── InjectJSTool.js # JS注入工具
│ │ │ ├── NotificationTool.js # 通知工具
│ │ │ ├── index.js # 统一导出
│ │ │ ├── test.js # 工具测试
│ │ │ └── README.md # 架构说明
│ │ ├── schemas/ # 🆕 Schema定义目录
│ │ │ ├── renderGUISchema.js # GUI工具Schema
│ │ │ ├── injectJSSchema.js # JS注入工具Schema
│ │ │ └── notificationSchema.js # 通知工具Schema
│ │ ├── utils/ # 🆕 工具类目录
│ │ │ └── htmlUtils.js # HTML处理工具类
│ │ ├── validators/ # 🆕 验证器目录
│ │ └── MIGRATION.md # 🆕 重构迁移指南
│ └── stdio/ # 标准传输相关(备用)
│ ├── server.mjs # 标准 MCP 服务器
│ └── wrapper.js # 标准服务器包装器
├── test/ # 测试文件
│ ├── setup.js # 测试环境设置
│ └── renderer.test.js # 渲染器测试
├── tools/ # 工具和调试
│ ├── diagnose.js # 诊断工具
│ └── test-debug.js # 测试调试脚本
├── package.json # 项目配置
├── jest.config.js # Jest 测试配置
└── README.md # 项目说明
文件说明
核心文件
src/main/main.js: Electron 主进程,负责窗口管理和 MCP 服务器集成src/main/preload.js: 预加载脚本,提供安全的 IPC 通信接口src/renderer/renderer.js: 动态界面渲染器,接收 GUI 定义并创建界面src/renderer/index.html: 主界面 HTML 模板src/renderer/styles.css: 界面样式文件
MCP 服务器(重构后)
src/mcp/sse/server.js: 重构后的 SSE MCP 服务器(采用模块化架构)src/mcp/sse/wrapper.js: SSE 服务器包装器src/mcp/sse/transport.js: SSE 传输层实现
🆕 工具系统架构
src/mcp/sse/tools/BaseToolHandler.js: 基础工具处理器(抽象基类)src/mcp/sse/tools/ToolRegistry.js: 工具注册器(统一管理)src/mcp/sse/tools/RenderGUITool.js: GUI渲染工具实现src/mcp/sse/tools/InjectJSTool.js: JavaScript注入工具实现src/mcp/sse/tools/NotificationTool.js: 通知工具实现src/mcp/sse/tools/index.js: 工具模块统一导出src/mcp/sse/tools/test.js: 工具系统测试文件src/mcp/sse/tools/README.md: 详细架构说明文档
🆕 Schema定义
src/mcp/sse/schemas/renderGUISchema.js: GUI渲染工具的Schema定义src/mcp/sse/schemas/injectJSSchema.js: JS注入工具的Schema定义src/mcp/sse/schemas/notificationSchema.js: 通知工具的Schema定义
🆕 工具类和验证器
src/mcp/sse/utils/htmlUtils.js: HTML处理和窗口配置验证工具类src/mcp/sse/validators/: 验证器目录(预留扩展)src/mcp/sse/MIGRATION.md: 重构迁移指南和最佳实践
备用服务器
src/mcp/stdio/server.mjs: 标准传输的 MCP 服务器(备用)src/mcp/stdio/wrapper.js: 标准服务器包装器
测试和工具
test/: Jest 测试文件tools/diagnose.js: 系统诊断工具tools/test-debug.js: 服务器测试调试脚本
启动方式
系统托盘模式(推荐)
# 托盘模式启动(默认)
npm start
# 带主窗口启动
npm run start-with-window
# 开发模式
npm run dev
其他启动选项
# 运行测试
npm test
# 构建应用
npm run build
MCP 服务器端点
启动后,MCP 服务器将在以下端点提供服务:
- SSE 连接:
http://localhost:3001/mcp - 消息处理:
http://localhost:3001/messages - 健康检查:
http://localhost:3001/health - 调试信息:
http://localhost:3001/debug/sessions
窗口复用功能
基本用法
// 复用现有窗口
{
"title": "复用的窗口",
"width": 800,
"height": 600,
"reuseWindow": true, // 关键参数:启用窗口复用
"components": [
{ "type": "heading", "text": "复用的窗口", "level": 1 },
{ "type": "text", "text": "这个窗口复用了之前的窗口" },
{ "type": "button", "text": "点击我", "onClick": "handleClick" }
],
"callbacks": {
"handleClick": "alert('复用窗口的按钮被点击了!');"
}
}
窗口复用 vs 新建窗口
// 方式 1: 创建新窗口(默认行为)
{
"title": "新窗口",
"reuseWindow": false, // 或不设置此参数
"components": [...]
}
// 方式 2: 复用现有窗口
{
"title": "复用窗口",
"reuseWindow": true, // 启用复用
"components": [...]
}
复用窗口的优势
- 保持窗口位置: 窗口不会重新定位到屏幕中央
- 保持窗口大小: 如果新配置没有指定尺寸,保持原有尺寸
- 减少闪烁: 避免窗口关闭和重新创建的过程
- 提升性能: 减少资源消耗和初始化时间
- 更好的用户体验: 窗口状态保持连续
HTML 模式使用
基本用法
// 通过 MCP 调用 render-gui 工具
{
"title": "HTML 界面示例",
"width": 800,
"height": 600,
"type": "html",
"content": `
<div style="padding: 20px;">
<h1>Hello World</h1>
<p>这是一个 HTML 界面</p>
<button onclick="alert('点击了按钮')">点击我</button>
</div>
`
}
HTML 到 Markdown 功能使用
自动转换和缓存
当使用 render-gui 工具渲染 HTML 界面时,系统会自动:
- 将 HTML 内容转换为高质量的 Markdown 格式
- 保存 Markdown 文件到系统临时目录
- 在全局缓存中记录 Markdown 文件信息
获取 Markdown 文件路径
// 使用 get-gui 工具,只获取 Markdown 文件路径(快速)
{
"markdownOnly": true
}
// 返回结果:
// ✅ Markdown文件路径
// 📁 文件路径: /tmp/nexusgui-cache/界面标题-2025-08-03T14-51-39-788Z.md
// 📁 最新文件: /tmp/nexusgui-cache/界面标题-latest.md
// 📄 文件大小: 1232 字节
// ⏰ 创建时间: 2025/8/3 14:51:39
在文件管理器中显示文件
// 使用 show-in-file-manager 工具在文件管理器中显示 Markdown 文件
{
"filePath": "/tmp/nexusgui-cache/界面标题-2025-08-03T14-51-39-788Z.md"
}
// 返回结果:
// ✅ 已在文件管理器中显示文件:
// 📁 /tmp/nexusgui-cache/界面标题-2025-08-03T14-51-39-788Z.md
读取 Markdown 内容
// 读取并返回 Markdown 文件内容
{
"returnType": "markdown",
"readMarkdown": true
}
// 返回完整的 Markdown 文本内容(如果内容较长,会显示前1000个字符的预览)
同时获取 HTML 和 Markdown
// 同时返回 HTML 和 Markdown 内容
{
"returnType": "both",
"showHtml": true,
"readMarkdown": true
}
获取缓存摘要信息
// 获取包含 Markdown 信息的摘要
{
"format": "summary",
"returnType": "both"
}
// 返回结果包含:
// - HTML 长度和预览
// - Markdown 长度和文件信息
// - 缓存时间等元信息
Markdown 转换特性
- 高质量转换: 使用
turndown库进行专业的 HTML 到 Markdown 转换 - 智能清理: 自动移除样式、脚本等不必要的 HTML 内容
- 格式保持: 保留标题、列表、表格、代码块、链接、引用等结构
- 文件管理: 自动创建时间戳文件名和最新文件链接
- 系统集成: 保存到标准系统临时目录,支持跨平台访问
文件存储结构
系统临时目录/nexusgui-cache/
├── 测试界面-2025-08-03T14-51-39-788Z.md
├── 测试界面-latest.md -> 测试界面-2025-08-03T14-51-39-788Z.md
├── 用户表单-2025-08-03T15-20-15-456Z.md
└── 用户表单-latest.md -> 用户表单-2025-08-03T15-20-15-456Z.md
使用场景
- 文档生成: 将动态 HTML 界面转换为可编辑的 Markdown 文档
- 版本管理: 便于将界面内容纳入版本控制系统
- AI 处理: Markdown 格式更适合 AI 模型理解和处理
- 跨平台兼容: Markdown 在各种工具和平台中都有良好支持
- 内容备份: 自动备份界面内容为可读格式
同步等待结果
{
"title": "用户确认对话框",
"width": 400,
"height": 300,
"waitForResult": true, // 同步等待结果
"type": "html",
"content": `
<div style="padding: 20px; text-align: center;">
<h2>确认操作</h2>
<p>您确定要执行此操作吗?</p>
<button onclick="electronAPI.sendResult({action: 'confirm', result: true})">
确认
</button>
<button onclick="electronAPI.sendResult({action: 'cancel', result: false})">
取消
</button>
</div>
`
}
窗口复用功能
{
"title": "复用窗口示例",
"reuseWindow": true, // 复用现有窗口
"type": "html",
"content": `
<div style="padding: 20px;">
<h1>窗口已更新</h1>
<p>这个内容替换了之前的窗口内容</p>
</div>
`
}
高级功能
{
"title": "复杂 HTML 界面",
"width": 600,
"height": 500,
"data": {
"userName": "张三",
"userAge": 25
},
"type": "html",
"content": `
<div style="padding: 20px; font-family: Arial, sans-serif;">
<h1 style="color: #333;">用户信息表单</h1>
<form id="userForm">
<div style="margin-bottom: 15px;">
<label>姓名:</label>
<input type="text" name="userName" value="{{userName}}" style="width: 200px; padding: 5px;">
</div>
<div style="margin-bottom: 15px;">
<label>年龄:</label>
<input type="number" name="userAge" value="{{userAge}}" style="width: 200px; padding: 5px;">
</div>
<button type="button" onclick="handleSubmit()">提交</button>
</form>
<div id="result"></div>
</div>
`,
"callbacks": {
"handleSubmit": `
const formData = getFormData('#userForm');
electronAPI.sendResult({ action: 'submit', data: formData });
`
}
}
功能特点
- 完整 HTML 支持: 支持所有 HTML 标签和属性
- CSS 样式: 支持内联样式和外部 CSS
- JavaScript 交互: 支持事件处理和动态交互
- 同步等待: 通过
waitForResult参数同步等待用户操作结果 - 窗口复用: 通过
reuseWindow参数复用现有窗口 - 数据绑定: 支持初始数据注入和模板变量替换
- 回调函数: 支持自定义回调函数注入
- 内置API: 提供
electronAPI.sendResult()和getFormData()函数
技术栈
- Electron: 桌面应用框架 (v27.0.0)
- Model Context Protocol (MCP): AI 通信协议 (@modelcontextprotocol/sdk v0.4.0)
- Express: Web 服务器框架 (v4.18.2)
- Server-Sent Events (SSE): 实时通信传输层
- CORS: 跨域资源共享支持
- Zod: 数据验证和类型安全
- Jest: 测试框架 (v29.7.0)
核心特性
- 🎨 动态界面渲染: 支持 HTML 字符串和文件路径两种渲染模式
- 🔄 窗口复用: 智能窗口管理,减少资源消耗
- ⏱️ 同步等待: 支持同步等待用户操作结果
- 🎛️ 丰富窗口属性: 支持透明度、置顶、全屏等多种窗口设置
- 🌐 跨域支持: 内置 CORS 支持,方便集成
- 🔍 实时调试: 提供健康检查和会话调试端点
- 📱 系统托盘: 支持后台运行和托盘管理
