ht-mcp

headless terminal ht를 위한 고성능 Rust 구현체인 Model Context Protocol (MCP) 서버입니다.

주요 기능 (Features)

• 🚀 Pure Rust: 외부 의존성이 없는 단일 바이너리 MCP 서버
• 🔗 직접 통합 (Direct Integration): 최적의 성능을 위해 우수한 ht headless terminal 라이브러리를 내장
• 🖥️ 멀티 세션 (Multi-Session): 동시 터미널 세션 관리
• 🌐 웹 인터페이스 (Web Interface): 선택 가능한 실시간 터미널 미리보기

데모 (Demo)

Memex에서의 ht-mcp

Claude Code에서의 ht-mcp

설치 (Installation)

🍺 Homebrew (권장)

brew tap memextech/tap
brew install ht-mcp

📦 사전 빌드된 바이너리 (Pre-built Binaries)

releases에서 다운로드하세요:

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

...

🦀 Cargo

# crates.io (stable)로부터 설치
cargo install ht-mcp

...

🔧 소스에서 빌드 (Build from Source)

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

자세한 설치 옵션은 docs/INSTALLATION.md를 참조하세요.

MCP 도구 (MCP Tools)

도구 (Tool)	설명 (Description)	파라미터 (Parameters)
ht_create_session	새로운 터미널 세션 생성	command?, enableWebServer?
...

참고: MCP 호환성을 위해 파라미터는 camelCase (예: sessionId, enableWebServer)를 사용합니다.

설정 (Configuration)

MCP 클라이언트 설정에 다음을 추가하세요:

{
  "mcpServers": {
    "ht-mcp": {
...

사용자 정의 설치 경로의 경우:

{
  "mcpServers": {
    "ht-mcp": {
...

사용 예시 (Usage Example)

# MCP 서버 시작
ht-mcp

...

MCP 클라이언트에 설정이 완료되면:

1. 세션 생성 (Create session): ht_create_session → 세션 ID (session ID) 반환
2. 명령어 실행 (Run commands): 세션 ID와 명령어를 사용하여 ht_execute_command 실행
3. 대화형 입력 (Interactive input): 다단계 상호작용을 위한 ht_send_keys 사용
4. 상태 확인 (Check state): 현재 터미널을 확인하기 위한 ht_take_snapshot 사용
5. 정리 (Clean up): 완료 시 ht_close_session 호출

응답 형식 (Response Format)

이 서버는 자연어 상호작용을 위해 설계된 사람이 읽을 수 있는 텍스트 응답 (human-readable text responses) (JSON 아님)을 반환합니다:

# 세션 생성 응답 (Create session response)
HT session created successfully!

...

# 터미널 스냅샷 응답 (Terminal snapshot response)
Terminal Snapshot (Session: abc123...)

...

요구 사항 (Requirements)

• Rust: 1.75 이상 (rustup을 통해 설치)
• 지원 운영체제 (Supported OS): Linux, macOS, Windows (실험적 단계)

개발 (Development)

# 서브모듈과 함께 클론 (Clone with submodules)
git clone --recursive https://github.com/memextech/ht-mcp.git
cd ht-mcp
...

문제 해결 (Troubleshooting)

설치 문제 (Installation Issues):

• Rust 1.75 이상이 설치되어 있는지 확인하십시오.
• git 서브모듈을 위한 인터넷 연결을 확인하십시오.
• ~/.cargo/bin이 PATH에 포함되어 있는지 확인하십시오.

런타임 문제 (Runtime Issues):

• 상세 로그를 위해 ht-mcp --debug를 사용하십시오.
• MCP 클라이언트 설정 구문을 확인하십시오.
• 바이너리 경로를 확인하십시오: which ht-mcp

성능 (Performance)

기존의 TypeScript 구현체와 비교했을 때:

• 40배 빠른 시작 속도 (~50ms vs ~2s)
• 70% 적은 메모리 사용량 (~15MB vs ~50MB)
• 단일 바이너리 (4.7MB vs ~200MB Node.js)
• 서브프로세스 오버헤드 없음 (Zero subprocess overhead)

라이선스 (License)

Apache 2.0 License

Copyright (c) 2025 Atlas Futures Inc.

자세한 내용은 LICENSE를 참조하십시오.

기여하기 (Contributing)

기여를 환영합니다! 가이드라인은 CONTRIBUTING.md를 읽어주세요.

---

Memex로 제작되었습니다✨

서브모듈 커밋 참조 수정