🚀 ht-mcp

ht-mcp 是一款為無頭終端 ht 打造的高性能模型上下文協議（MCP）服務器，採用 Rust 語言實現。它具備諸多出色特性，能為用戶提供高效、便捷的終端操作體驗。

🚀 快速開始

你可以通過以下命令啟動 MCP 服務器：

# 啟動 MCP 服務器
ht-mcp

# 開啟調試日誌
ht-mcp --debug

在 MCP 客戶端配置完成後，你可以按以下步驟操作：

1. 創建會話：使用 ht_create_session 命令，該命令會返回會話 ID。
2. 運行命令：使用 ht_execute_command 命令，傳入會話 ID 和具體命令。
3. 交互式輸入：使用 ht_send_keys 命令進行多步驟交互。
4. 檢查狀態：使用 ht_take_snapshot 命令查看當前終端狀態。
5. 清理操作：完成操作後，使用 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 工具

注意：參數使用駝峰命名法（如 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 許可證。

版權所有 (c) 2025 Atlas Futures Inc.

詳情請參閱 LICENSE。

貢獻

歡迎貢獻代碼！請閱讀 CONTRIBUTING.md 瞭解貢獻指南。

使用 Memex 構建✨

修復子模塊提交引用