Skip to content

BigSweetPotatoStudio/hyper-mcp-terminal

Repository files navigation

Hyper MCP Terminal

一个基于 MCP (Model Context Protocol) 的 Electron 桌面终端应用,为 AI 助手提供安全的终端执行能力。让AI可以帮你运行远程机器的shell。

使用http协议

    "terminal": {
      "type": "http",
       "url": "http://localhost:13000/mcp"
    }

    "terminal": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:13000/mcp"
      ]
    }
image 395ab63caa6f840b536029016a82083 098e7e54cb2f65ed297fc7b8f4dee67

项目概述

Hyper MCP Terminal 是一个现代化的桌面终端应用,集成了 MCP 协议支持,使 AI 助手能够安全地执行命令行操作。应用基于 Electron + TypeScript 构建,提供多标签页终端界面和实时通信能力。

核心功能

  • 🖥️ Electron 桌面应用: 跨平台桌面终端应用
  • 📑 多标签页终端: 支持多个独立的终端会话
  • 🤖 MCP 协议集成: 符合 Model Context Protocol 标准
  • 🔄 实时通信: 基于 WebSocket 的实时终端交互
  • 🎨 现代化界面: 基于 Ant Design 的美观界面
  • TypeScript: 完整的类型安全支持

技术架构

主要组件

  • electron/main.ts: Electron 主进程入口
  • electron/server.ts: 内置 HTTP/WebSocket 服务器
  • electron/index.mts: MCP 服务器实现
  • electron/window.ts: 窗口管理和 IPC 处理
  • frontend/: React + TypeScript 前端界面

技术栈

  • 桌面框架: Electron
  • 后端: Node.js + TypeScript + Express
  • 前端: React + TypeScript + Ant Design
  • 终端: xterm.js + node-pty
  • 通信: Socket.IO + IPC
  • 构建: Webpack + TypeScript Compiler

开发环境

环境要求

  • Node.js 18+
  • npm 或 pnpm
  • C++ 编译环境(用于 node-pty 依赖)
  • Python (Windows 用户)

安装依赖

npm install

开发命令

# 启动开发服务器(后端)
npm run dev

# 启动前端开发监听
npm run dev:web

# 构建 TypeScript
npm run build

# 构建前端
npm run build:web

# 运行 Electron 应用
npm run electron

# 开发模式运行(启动服务器并打开应用)
npm run electron:dev

# 完整构建并打包
npm run electron:build

# 打包(不分发)
npm run electron:pack

项目结构

hyper-mcp-terminal/
├── electron/                 # 核心逻辑目录
│   ├── main.ts              # Electron 主进程
│   ├── server.ts            # HTTP/WebSocket 服务器
│   ├── index.mts            # MCP 服务器
│   ├── commander.ts         # 命令行参数处理
│   ├── shell.ts             # 终端会话管理
│   ├── window.ts            # 窗口管理
│   ├── preload.ts           # 预加载脚本
│   └── dev.ts               # 开发环境启动
├── frontend/                # React 前端界面
│   ├── index.tsx            # 前端入口
│   ├── index.css            # 样式文件
│   └── index.html           # HTML 模板
├── build/                   # 前端构建输出
├── dist/electron/           # TypeScript 编译输出
└── dist-electron/           # Electron 打包输出

配置说明

应用设置

应用设置自动保存在系统的应用数据目录中:

  • macOS: ~/Library/Application Support/hyper-mcp-terminal/
  • Windows: %APPDATA%/hyper-mcp-terminal/
  • Linux: ~/.config/hyper-mcp-terminal/

默认设置

{
  "server": {
    "port": 13000
  },
  "terminal": {
    "maxOutputTokens": 10000
  },
  "window": {
    "width": 1200,
    "height": 800,
    "maximized": false
  }
}

环境变量

  • NODE_ENV: 运行环境 (development/production)

设置管理

  • 自动保存: 所有设置更改自动保存到本地
  • 窗口记忆: 应用会记住窗口位置、大小和最大化状态
  • IPC 接口: 支持通过 IPC 调用动态修改设置
  • 默认值回退: 无效设置自动回退到默认值

端口配置

  • Web 服务器端口可通过应用设置修改,默认: 3000
  • MCP 服务器使用 stdio 传输

安全特性

  • 终端会话隔离
  • 输出长度限制
  • 超时保护
  • 命令执行监控
  • IPC 安全策略

故障排除

node-pty 安装失败

node-pty 依赖需要 C++ 编译环境,请参考 官方文档 安装相关依赖:

Windows:

npm install --global windows-build-tools

macOS:

xcode-select --install

Linux (Ubuntu/Debian):

sudo apt-get install build-essential

Electron 原生模块兼容性

node-pty 是一个原生模块,需要为 Electron 的 Node.js 版本重新编译。

开发环境解决方案:

# 方法1:使用electron-rebuild
npm run rebuild

# 方法2:重新安装node-pty
npm uninstall node-pty && npm install node-pty

# 方法3:手动重建
npx electron-rebuild

生产环境解决方案:

  • 使用 electron-builder 打包时会自动处理原生模块重建
  • 确保在目标平台上构建应用

注意事项:

  • 开发时的 node-pty 版本问题不影响应用的核心功能(设置管理、窗口状态等)
  • 终端功能需要 node-pty 正常工作
  • 如果无法解决 node-pty 问题,可以考虑使用其他终端实现

使用截图

终端界面

多标签页

MCP 集成

演示视频

YouTube 演示

MCP 集成

在 Claude Desktop 中使用

在 Claude Desktop 的配置文件中添加:

{
  "mcpServers": {
    "hyper-mcp-terminal": {
      "command": "path/to/hyper-mcp-terminal/dist/electron/index.mjs"
    }
  }
}

支持的 MCP 工具

  • execute-command: 在活跃终端中执行命令
  • create-terminal-session: 创建新的终端会话
  • 自动活跃终端检测和切换

构建和分发

开发构建

npm run build
npm run build:web
npm run electron

生产构建

npm run electron:build

构建产物将输出到 dist-electron/ 目录。

贡献指南

  1. Fork 项目
  2. 创建功能分支: git checkout -b feature/amazing-feature
  3. 提交更改: git commit -m 'Add amazing feature'
  4. 推送分支: git push origin feature/amazing-feature
  5. 创建 Pull Request

许可证

MIT License

相关项目

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Packages

No packages published

Contributors 2

  •  
  •