NPCterm: AI 에이전트를 위한 MCP 기반 완전 PTY 터미널 에뮬레이터

NPCterm는 MCP(Model Context Protocol)를 통해 노출되는 AI 에이전트용 헤드리스, 인메모리 완전 PTY 터미널 에뮬레이터입니다. 이는 AI 에이전트에게 bash뿐만 아니라 완전한 터미널 접근을 제공하여 셸을 생성하고, 임의의 명령을 실행하며, 화면 출력을 읽고, 키 입력을 보내고, TUI 애플리케이션과 상호작용할 수 있게 합니다.

주요 기능

• portable-pty를 통한 PTY 생성과 완전한 ANSI/VT100 터미널 에뮬레이션
• JSON-RPC stdio를 통한 완전한 터미널 제어를 위한 15개의 MCP 도구
• 프로세스 상태 감지 – 명령이 실행 중인지, 유휴 상태인지, 입력 대기 중인지, 종료되었는지 인식
• 이벤트 시스템 – 터미널 이벤트(CommandFinished, WaitingForInput, Bell 등)의 링 버퍼
• 정밀한 화면 탐색을 위한 AI 친화적 좌표 오버레이
• TUI 애플리케이션과 상호작용하기 위한 마우스, 선택 및 스크롤 지원
• 짧은 2자 ID를 가진 다중 동시 터미널

MCP 사용 예시

소스는 NPCterm를 사용하여 Vim을 열고 종료하는 구체적인 예시를 제공합니다:

// 1. 터미널 생성
// -> terminal_create {}
// <- {"id": "a0", "cols": 80, "rows": 24}

// 2. vim 열기
// -> terminal_send_keys {"id": "a0", "input": [{"text": "vim"}, {"key": "Enter"}]}
// <- {"success": true}
// 3. 화면을 읽어 vim이 열렸는지 확인
// -> terminal_show_screen {"id": "a0"}
// <- ~ VIM - Vi IMproved
// <- ~ version 9.2.250
// <- ~ by Bram Moolenaar et al.
// <- ~ type :q<Enter> to exit
// <- ...
// 4. vim 종료
// -> terminal_send_keys {"id": "a0", "input": [{"text": ":q"}, {"key": "Enter"}]}
// <- {"success": true}

소스에는 다음과 같은 경고가 포함되어 있습니다: "주의해서 사용하세요. 터미널은 제한 없는 실행 환경입니다." 이 도구는 효과적으로 AI 에이전트에게 컴퓨터 접근 권한을 부여하는 것과 동등합니다.

이 프로젝트는 github.com/alejandroqh/npcterm에서 GitHub에서 이용 가능합니다.