tfbash-mcp

Agent 시스템을 위한 기반 MCP 도구 모음입니다. 이 프로젝트는 다양한 Agent에 안정적이고, 조합 가능하며, 인지 부담이 낮은 범용 기능(예: 명령 실행, 파일 읽기/쓰기 및 검색)을 제공하는 것을 목표로 합니다. 구체적인 기능은 성숙한 구현을 우선 재사용하며, 기존方案이 핵심 제약을 충족하지 못할 때만适配하거나 자체 개발을 고려합니다.

현재 상태: Python 프로젝트 스켈레톤 및 요구사항/아키텍처 RFC. 저장소는 빈 stdio MCP Server를 시작할 수 있지만, RFC에 정의된 Shell 도구는 아직 제공되지 않습니다.

왜 이 프로젝트를 만드는가

Agent는 종종 순수 텍스트 추론을 벗어나 실제 작업 공간을 조작하거나 로컬 프로그램을 호출해야 합니다. 프로그래머는 Shell을 주요 작업 인터페이스로 사용합니다. 제품, 운영, 연구 등 일반 직무에서도 Shell을 통해 스크립트를 호출하고, 파일을 변환하며, 데이터를 일괄 처리하거나 환경을 진단합니다.

기존 MCP 도구는 기능 범위와 실행 모델에서 차이가 큽니다. 일부는 일회성 명령만 지원하고, 일부는 PTY 또는 상주 데몬에 의존하며, 일부는 승인 및 샌드박스를 내장하고, 일부는 안정적인 장기 명령, 증분 출력 및 관리되는 프로세스 정리를 제공하지 못합니다. tfbash-mcp는 먼저 실제 시나리오와 검증 가능한 기능 계약을 정의한 후, 직접 채택할지, 래핑하여适配할지, 아니면 자체 개발할지를 결정합니다.

Related MCP server: MCP Terminal Tool Server

설계 원칙

• 시나리오 우선, 기술 선택은 그 다음: 특정 언어, 프레임워크 또는 기존 구현에 익숙하다는 이유로 요구사항을 역산출하지 않습니다.

• 재사용 우선: 선택 순서는 Adopt → Wrap → Build입니다. 재사용은 핵심 동작을 충족하는 것을 전제로 합니다.

• 작고 직교적: 기본 도구는 명확한 경계를 유지하며, Agent 오케스트레이션, 업무 워크플로 또는 UI를 도구 계층에 넣지 않습니다.

• 명시적 상태: 장기 작업, 영구 Shell, 출력 커서, 종료 상태 및 리소스 수명 주기는 모두 관찰 가능해야 합니다. cwd/env를 유지해야 하는 Shell은 명시적으로 생성되고 주소 지정이 가능해야 합니다.

• 프로토콜과 구현 언어는 무관: 도구 계약은 Python, pexpect 또는 클라이언트 내부 개념을 노출하지 않습니다. V1은 Python + pexpect 및 stdio 전송을 사용합니다.

• 배포 환경 신뢰: 1단계에서는 approval, sandbox, 명령 정책 또는 디렉터리 경계를 내장하지 않습니다.

• 리소스 제어: 메모리, 디스크, 세션, 프로세스 및 임시 파일에는 명확한 상한, 소유권 및 정리 규칙이 있어야 합니다.

1단계: Bash 도구

1단계는 Unix(Linux, macOS) 환경의 독립형 범용 Bash MCP Server에 집중합니다. 목표는 다음을 동시에 다룹니다:

• 프로그래머의 빌드, 테스트, 코드 검색, 서비스 시작 및 로그 관찰;

• 일반 직무에서 설치된 CLI 또는 스크립트를 통한 파일 처리, 데이터 변환 및 환경 진단;

• 여러 개의 주소 지정 가능한 영구 Command Shell이 각각 cwd, 환경 및 활성화 상태를 유지하고, 각 명령에 대해 정확한 종료 상태를 반환;

• pexpect PTY의 stdout/stderr를 combined output으로 반환하고, 각 실행에 대해 유계 증분 출력을 유지;

• 짧은 명령은 shell_exec로 한 번에 반환하고, 긴 명령이 yield_ms를 초과하면 running을 반환하여 원래 Shell에서 계속 실행;

• 긴 명령은 shell_read로 증분 출력을 읽고, shell_write로 stdin에 쓰며, shell_signal로 중단 또는 종료;

• 영구 Command Shell은 생성, 실행, 증분 읽기, 쓰기, 시그널, 열거 및 종료를 지원하며, 더 이상 독립적인 백그라운드 Job 및 Terminal 도구 그룹을 노출하지 않습니다;

• Shell과 Execution은 MCP 서비스 프로세스에 속하며, 도구 호출 간에 유지되지만 서비스 재시작 간에는 유지되지 않습니다;

• 하나의 tfrobot-client는 SDK가 관리하는 하나의 MCP 프로세스에 대응하며, 클라이언트는 활성화 스위치와 실행 상태만 유지합니다.

1단계의 영구 Shell은 PTY를 사용하지만, 명령 지향 텍스트 스트림만 제공하며 전체 화면 TUI 화면 모델, 원시 터미널 Session 또는 resize는 제공하지 않습니다. 이후 xterm.js, REPL 또는 전체 화면 TUI의 명확한 통합 요구가 나타나면 동일한 Shell 리소스 모델 위에 Terminal 모드를 추가합니다. 또한 명령 승인, 프로세스 샌드박스, 서비스 재시작 간 복구 및 MCP Tasks와의 강한 결합은 포함하지 않습니다.

관련 문서:

• 범용 Bash MCP Server 요구사항 및 아키텍처 설명: 독립형 MCP 경계, 도구 계약, ide4ai 재사용 범위, SDK/클라이언트 책임 및 승인 기준을 정의합니다.

계획 중인 기반 기능

현재 로드맵은 탐색 순서를 표현할 뿐, 자체 개발을 결정한 것은 아닙니다:

1. 영구 Shell 및 장기 명령 Execution;

2. 파일 읽기, 쓰기 및 패치 방식 수정;

3. 파일 검색 및 텍스트 검색;

4. 실제 Agent 워크플로를 기반으로 보완되는 기타 소형 기본 도구.

각 기능은 먼저 독립적인 요구사항과 후보 구현 조사를 구성하고, Adopt, Wrap 또는 Build 결정의 근거를 기록해야 합니다. 서로 다른 기능은 서로 다른 출처를 사용할 수 있지만, Agent에 노출되는 오류 모델, 수명 주기 및 결과 구조는 일관성을 유지해야 합니다.

저장소 구조

.
├── .github/workflows/tests.yml  # Python 3.10–3.12 CI
├── pyproject.toml               # 包元数据、依赖与工具配置
├── src/tfbash_mcp/              # MCP Server 包与入口
├── tests/                       # 自动化测试
├── README.md
├── docs/
│   └── bash-tool-requirements.md
└── reference/
    ├── ide4ai/                   # pexpect 持久 Shell 基线
    ├── codex/                    # 进程生命周期参考
    ├── pi/                       # Agent Shell 参考
    └── deepseek-harness/         # Agent Runtime 参考

reference/는 로컬 조사 및 체크아웃 디렉터리로, 규모가 크고 여러 서드파티 Git 저장소를 포함하므로 tfbash-mcp의 버전 관리나 배포 패키지에는 포함되지 않습니다.

로컬 개발

프로젝트는 Python 3.10–3.12을 지원하며 uv로 환경을 관리합니다:

uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest --cov

현재 stdio Server 스켈레톤을 시작합니다:

uv run tfbash-mcp

이 프로세스는 현재 Shell 도구를 등록하지 않으며, 패키지, 진입점 및 MCP stdio 수명 주기 검증에만 사용됩니다.

의사 결정 참여

요구사항 문서는 현재 V1의 다중 Shell + Execution 도구 모델과 Python/pexpect 구현 베이스라인을 확정했지만, 여전히 구현 및 승인 대기 중인 RFC입니다. 개발에 들어가기 전에 최소한 다음이 필요합니다:

1. 문서의 하드 요구사항과 미결 항목을 정렬;

2. 선택된 pexpect 베이스라인에 대해 최소 실행 가능 실험을 수행;

3. ide4ai 코드 추출의 라이선스 보존 방식,适配 비용, 장기 유지 관리 부담 및 종료 전략을 확인;

4. 실험 결과와 최종 구현 편차를 RFC에 다시 반영한 후, 코딩 및 승인 단계로 진행합니다.