article

README

🚀 ht-mcp

ht-mcp 是一款为无头终端 ht 打造的高性能模型上下文协议（MCP）服务器，采用 Rust 语言实现。它具备诸多出色特性，能为用户提供高效、便捷的终端操作体验。

🚀 快速开始

你可以通过以下命令启动 MCP 服务器：

# 启动 MCP 服务器
ht-mcp

# 开启调试日志
ht-mcp --debug

在 MCP 客户端配置完成后，你可以按以下步骤操作：

创建会话：使用 ht_create_session 命令，该命令会返回会话 ID。
运行命令：使用 ht_execute_command 命令，传入会话 ID 和具体命令。
交互式输入：使用 ht_send_keys 命令进行多步骤交互。
检查状态：使用 ht_take_snapshot 命令查看当前终端状态。
清理操作：完成操作后，使用 ht_close_session 命令关闭会话。

✨ 主要特性

🚀 纯 Rust 实现：单二进制文件的 MCP 服务器，无需外部依赖。
🔗 直接集成：嵌入优秀的 ht 无头终端库，实现最佳性能。
🖥️ 多会话管理：支持并发终端会话管理。
🌐 Web 界面：可选择使用实时终端预览功能。

📦 安装指南

🍺 Homebrew（推荐）

brew tap memextech/tap
brew install ht-mcp

📦 预构建二进制文件

从 releases 下载：

# macOS Intel
curl -L https://github.com/memextech/ht-mcp/releases/latest/download/ht-mcp-x86_64-apple-darwin -o ht-mcp

# macOS Apple Silicon
curl -L https://github.com/memextech/ht-mcp/releases/latest/download/ht-mcp-aarch64-apple-darwin -o ht-mcp

# Linux
curl -L https://github.com/memextech/ht-mcp/releases/latest/download/ht-mcp-x86_64-unknown-linux-gnu -o ht-mcp

# Windows (PowerShell)
curl.exe -L https://github.com/memextech/ht-mcp/releases/latest/download/ht-mcp-x86_64-pc-windows-msvc -o ht-mcp.exe

# 赋予可执行权限并安装
chmod +x ht-mcp && sudo mv ht-mcp /usr/local/bin/

🦀 Cargo

# 从 crates.io 安装（稳定版）
cargo install ht-mcp

# 从 git 安装（最新版）
cargo install --git https://github.com/memextech/ht-mcp

🔧 从源代码构建

git clone https://github.com/memextech/ht-mcp.git
cd ht-mcp
git submodule update --init --recursive
cargo install --path .

详细的安装选项请参考 docs/INSTALLATION.md。

📚 详细文档

MCP 工具

| 工具 | 描述 | 参数 | |------|-------------|------------| | ht_create_session | 创建新的终端会话 | command?, enableWebServer? | | ht_send_keys | 向会话发送按键输入 | sessionId, keys[] | | ht_take_snapshot | 捕获终端状态 | sessionId | | ht_execute_command | 执行命令并获取输出 | sessionId, command | | ht_list_sessions | 列出所有活动会话 | 无 | | ht_close_session | 关闭终端会话 | sessionId |

注意：参数使用驼峰命名法（如 sessionId, enableWebServer）以兼容 MCP。

配置

将以下内容添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "ht-mcp": {
      "command": "ht-mcp",
      "args": ["--debug"]
    }
  }
}

对于自定义安装路径：

{
  "mcpServers": {
    "ht-mcp": {
      "command": "/path/to/ht-mcp",
      "args": []
    }
  }
}

响应格式

此服务器返回人类可读的文本响应（非 JSON），专为自然语言交互设计：

# 创建会话响应
HT session created successfully!

Session ID: abc123-def456-789...

🌐 Web server enabled! View live terminal at: http://127.0.0.1:3618

# 终端快照响应
Terminal Snapshot (Session: abc123...)

bash-3.2$ ls -la
total 16
drwxr-xr-x  4 user staff  128 Jun 13 10:30 .
-rw-r--r--  1 user staff   45 Jun 13 10:30 file.txt
bash-3.2$

要求

Rust：1.75+（通过 rustup 安装）
支持的操作系统：Linux、macOS、Windows（实验性支持）

开发

# 克隆项目并包含子模块
git clone --recursive https://github.com/memextech/ht-mcp.git
cd ht-mcp

# 构建项目
cargo build

# 运行项目
cargo run

# 运行测试
cargo test

故障排除

安装问题：

确保已安装 Rust 1.75+。
检查 git 子模块的网络连接。
验证 ~/.cargo/bin 是否在 PATH 中。

运行时问题：

使用 ht-mcp --debug 命令开启详细日志。
检查 MCP 客户端配置语法。
使用 which ht-mcp 验证二进制文件路径。

性能

与原始的 TypeScript 实现相比：

启动速度快 40 倍（约 50ms 对比约 2s）。
内存占用减少 70%（约 15MB 对比约 50MB）。
单二进制文件（4.7MB 对比约 200MB Node.js）。
零子进程开销。

📄 许可证

本项目采用 Apache 2.0 许可证。

详情请参阅 LICENSE。

贡献

欢迎贡献代码！请阅读 CONTRIBUTING.md 了解贡献指南。

使用 Memex 构建✨

ht-mcp