tfbash-mcp

A foundational MCP tool collection for Agent systems. The project aims to provide a set of stable, composable, low-cognitive-load general capabilities for different Agents, such as command execution, file read/write, and search; specific capabilities prioritize reusing mature implementations, only considering adaptation or in-house development when existing solutions cannot meet core constraints.

Current status: Python project skeleton with requirements/architecture RFC. The repository can start an empty stdio MCP Server, but does not yet provide the Shell tools defined in the RFC.

Why this project

Agents often need to leave pure text reasoning and operate on real workspaces or invoke local programs. Programmers use Shell as their primary work interface; general roles such as product, operations, and research also use Shell to call scripts, convert files, batch-process data, or diagnose environments.

Existing MCP tools vary greatly in capability scope and execution model: some only support one-shot commands, some depend on PTY or resident daemon processes, some have built-in approval and sandboxing, and some lack reliable long-command, incremental output, and managed process cleanup. tfbash-mcp first defines real scenarios and verifiable capability contracts, then decides whether to adopt directly, wrap/adapt, or build in-house.

Related MCP server: MCP Terminal Tool Server

Design Principles

• Scenarios first, then technology selection: Don't reverse-engineer requirements from familiarity with a language, framework, or existing project.

• Reuse first: Selection order is Adopt → Wrap → Build; reuse must be premised on meeting key behaviors.

• Small and orthogonal: Keep clear boundaries for foundational tools, avoiding pushing Agent orchestration, business workflows, or UI into the tool layer.

• Explicit state: Long-running tasks, persistent Shells, output cursors, exit status, and resource lifecycles should all be observable; Shells that need to preserve cwd/env must be explicitly created and addressed.

• Protocol and implementation language agnostic: Tool contracts do not expose Python, pexpect, Computer, or client internals; V1 uses Python + pexpect and stdio transport.

• Trust the deployment environment: Phase 1 does not include built-in approval, sandbox, command policy, or directory boundaries.

• Controllable resources: Memory, disk, sessions, processes, and temporary files must have clear limits, ownership, and cleanup rules.

Phase 1: Bash Tools

Phase 1 focuses on a standalone general-purpose Bash MCP Server for Unix environments (Linux, macOS). The goal covers simultaneously:

• Programmers' build, test, code search, service startup, and log observation;

• General roles using installed CLIs or scripts for file processing, data transformation, and environment diagnostics;

• Multiple addressable persistent Command Shells that each preserve cwd, environment, and activation state, and return accurate exit status for each command;

• pexpect PTY's stdout/stderr returned as combined output, with bounded incremental output maintained for each execution;

• Short commands returned once by shell_exec; long commands exceeding yield_ms return running and continue executing in the original Shell;

• Long commands read incrementally via shell_read, write to stdin via shell_write, and interrupt or terminate via shell_signal;

• Persistent Command Shells support create, execute, incremental read, write, signal, list, and close, no longer exposing separate background Job and Terminal tool groups;

• Shells and Executions belong to the MCP service process and persist across tool calls, but recovery across service restarts is not promised;

• One tfrobot-client Computer corresponds to one SDK-managed MCP process; the client only keeps the enable toggle and running state.

Phase 1 persistent Shells will use PTY, but only provide command-oriented text streams, not full-screen TUI screen models, raw terminal Sessions, or resize. If a clear integration party for xterm.js, REPL, or full-screen TUI emerges later, Terminal mode will be added on the same Shell resource model. Also not included: command approval, process sandboxing, cross-service restart recovery, and strong coupling with MCP Tasks.

Related documentation:

• General Bash MCP Server Requirements and Architecture: defines standalone MCP boundaries, tool contracts, ide4ai reuse scope, SDK/client responsibilities, and acceptance criteria.

Planned Foundational Capabilities

The current roadmap only expresses exploration order, not a decision to build in-house:

1. Persistent Shell and long-command Execution;

2. File read, write, and patch-style modification;

3. File discovery and text search;

4. Other small foundational tools added based on real Agent workflows.

Each capability should first form independent requirements and candidate research, and record the Adopt, Wrap, or Build decision rationale. Different capabilities can use different sources, as long as the error model, lifecycle, and result structure exposed to Agents remain consistent.

Repository Structure

.
├── .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/ is a local research checkout directory, large in size and containing multiple third-party Git repositories, so it will not be included in tfbash-mcp's version control or distribution packages.

Local Development

The project supports Python 3.10–3.12 and uses uv to manage the environment:

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

Start the current stdio Server skeleton:

uv run tfbash-mcp

This process does not register Shell tools yet; it is only used to verify the package, entry point, and MCP stdio lifecycle.

Participation Decisions

The requirements document has already determined the V1 multi-Shell + Execution tool model and the Python/pexpect implementation baseline, but it is still an unimplemented, unaccepted RFC. Before entering development, at least the following is needed:

1. Align on the hard thresholds and open items in the document;

2. Run minimal feasibility experiments on the selected pexpect baseline;

3. Confirm the license retention method, adaptation cost, long-term maintenance surface, and exit strategy for ide4ai code extraction;

4. Write back the experiment results and final implementation deviations to the RFC, then enter coding and acceptance.