tfbash-mcp

面向 Agent 系统的基础 MCP 工具集合。项目希望为不同 Agent 提供一组稳定、可组合、低心智负担的通用能力，例如命令执行、文件读写与检索；具体能力优先复用成熟实现，只有现有方案无法满足核心约束时才考虑适配或自研。

当前版本：0.2.1。macOS、Linux 与 Windows 11 x64 均提供七个持久 Shell 工具及 stdio MCP Server，并可作为 Python 运行时嵌入 IDE/SDK 宿主。两种入口共享同一套七工具 合同和 Shell Domain。运行时会发现并探测 Bash、Zsh 或 PowerShell，再与 POSIX PTY 或 Windows ConPTY/Job Object 原生后端组合。

为什么做这个项目

Agent 经常需要离开纯文本推理，操作真实工作区或调用本机程序。程序员会把 Shell 作为主要工作界面；产品、运营、研究等通用岗位也会通过 Shell 调用脚本、转换文件、批处理数据或诊断环境。

现有 MCP 工具在能力范围和运行模型上差异很大：有的只支持一次性命令，有的依赖 PTY 或常驻守护进程，有的内置审批和沙箱，有的缺少可靠的长命令、增量输出与受管进程清理。tfbash-mcp 先定义真实场景和可验收的能力合同，再决定直接采用、包装适配还是自研。

设计原则

• 先场景，后选型：不因熟悉某种语言、框架或现有项目而倒推需求。

• 优先复用：选型顺序是 Adopt → Wrap → Build；复用必须以满足关键行为为前提。

• 小而正交：基础工具保持清晰边界，避免把 Agent 编排、业务工作流或 UI 塞进工具层。

• 显式状态：长任务、持久 Shell、输出游标、退出状态和资源生命周期都应可观察；需要保留 cwd/env 的 Shell 必须显式创建和寻址。

• 协议与实现语言无关：工具合同不暴露 Python、pexpect、Computer 或客户端内部概念；V1 使用 Python + pexpect，默认提供 stdio adapter，也支持 Python 宿主进程内注册。

• 信任部署环境：第一阶段不内置 approval、sandbox、命令策略或目录边界。

• 可控资源：内存、磁盘、会话、进程和临时文件必须有明确上限、所有权与清理规则。

持久 Shell 工具

当前实现覆盖 macOS、Linux 和 Windows 的共享 Shell Runtime，并提供独立 stdio MCP Server 与 Python 嵌入入口。目标同时覆盖：

• 程序员的构建、测试、代码检索、服务启动和日志观察；

• 通用岗位通过已安装 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 归属于具体 Runtime 实例，跨工具调用保持，但不承诺跨实例重建恢复；

• 一个 tfrobot-client Computer 对应一个由 SDK 管理的 stdio 进程或嵌入运行时实例，客户端只保留启用开关和运行状态。

第一阶段的持久 Shell 会使用 PTY，但只提供命令导向的文本流，不提供全屏 TUI 屏幕模型、原始终端 Session 或 resize。后续若出现 xterm.js、REPL 或全屏 TUI 的明确集成方，再在同一 Shell 资源模型上增加 Terminal mode。同时不包含命令审批、进程沙箱、跨服务重启恢复，以及与 MCP Tasks 的强绑定。

相关文档：

• 通用 Shell MCP Server 与嵌入运行时需求及架构说明：定义共享 Runtime、stdio/宿主 adapter 边界、工具合同、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

CI、PR 合并与 PyPI 发布

Pull Request 和 main 分支使用同一套 Tests 质量门禁，在 Python 3.10、3.11、3.12 上执行 ruff check、ruff format --check、mypy 和完整测试。为确保检查失败时不能合并， 仓库管理员需要在 GitHub 的 main branch ruleset 中启用 Require a pull request before merging 和 Require status checks to pass，并把 Python 3.10、Python 3.11、 Python 3.12 三个检查设为 required。

PyPI 发布由 publish workflow 完成。它只在 GitHub Release 进入 published 状态时触发，并先复用上述完整质量门禁；全部通过后才校验 release tag、 构建并验证 wheel/sdist、安装 wheel 做 smoke test，最后通过 PyPI Trusted Publishing 上传。 发布 Job 使用 GitHub OIDC 短期凭证，仓库不保存 PyPI API Token。

首次发布前需要完成一次配置：

1. 在 GitHub 仓库 Settings → Environments 创建名为 pypi 的 Environment；建议增加 required reviewers，并将 deployment branches/tags 限制为 release tags。

2. tfbash-mcp 尚未存在于 PyPI 时，在 PyPI 的 Publishing 页面创建 pending Trusted Publisher；项目名填写 tfbash-mcp，Owner 填写 A2C-SMCP，Repository 填写 tfbash-mcp，Workflow name 填写 publish.yml，Environment 填写 pypi。首次成功发布 后 pending publisher 会自动成为该项目的正式 publisher。

3. 按上一段配置 GitHub main branch ruleset，确保 PR 不能绕过质量门禁合并。

每次发布都必须先在 PR 中更新 pyproject.toml 的版本并通过 required checks。合并到 main 后创建与版本完全一致的 v<version> GitHub Release，例如：

gh release create v0.2.1 --target main --generate-notes

Release tag 与 pyproject.toml 版本不一致，或 tag 指向的提交不属于 main 时，发布会在 上传 PyPI 前失败。PyPI 上的版本文件不可覆盖，因此每次重发都必须使用新版本号。

启动 stdio Server：

uv run tfbash-mcp

使用 MCP Inspector 2.2 从当前本地源码启动并检查工具 discovery：

npx -y @modelcontextprotocol/inspector@2.2.0 --web \
  uv \
  --directory "$PWD" \
  run tfbash-mcp \
  --runtime-profile auto \
  --host-profile ide \
  --workspace-root "$PWD"

该命令必须在包含最终实现的分支或 worktree 中执行。连接后运行 Tools → List Tools，应恰好显示 shell_open、shell_exec、shell_read、shell_write、 shell_signal、shell_list 和 shell_close。Server 默认使用 stdio，无需再传一个 可能被 Inspector 当成自身选项的 --transport stdio。选择 shell_write 时，Inspector 应只显示必填的 shell_id、exec_id 和 text 三个输入字段。

Server 注册 shell_open、shell_exec、shell_read、shell_write、 shell_signal、shell_list 和 shell_close。默认使用当前目录作为 workspace root 和 default cwd，并按宿主系统自动选择 Runtime Profile。IDE 集成应显式传入工作区：

uv run tfbash-mcp \
  --host-profile ide \
  --workspace-root /absolute/path/to/workspace

IDE4AI 等 Python 宿主也可以不启动子进程，直接创建进程内运行时：

from tfbash_mcp import EmbeddedShellConfig, EmbeddedShellRuntime

config = EmbeddedShellConfig(
    workspace_root="/absolute/path/to/workspace",
    environment=project_environment,
)

async with await EmbeddedShellRuntime.create(config) as runtime:
    tools = runtime.list_tools()
    resources = runtime.list_resources()
    overview = runtime.read_resource(resources[0].uri)
    unsubscribe = runtime.subscribe_resource_updates(on_resource_updated)
    opened = await runtime.call_tool("shell_open")
    unsubscribe()

EmbeddedShellConfig 会复制环境映射；修改原字典不会改变已经创建的配置。初始化、工具调用 和关闭均通过异步 API 执行，不阻塞宿主事件循环。每个 EmbeddedShellRuntime 拥有独立的 Shell/Execution Registry；IDE4AI 负责先按项目选择对应实例，再注册 list_tools() 返回的 工具。宿主可将 list_resources() 返回的定义、read_resource() 的结果及 subscribe_resource_updates() 收到的 URI 桥接到自己的 MCP Server；嵌入 API 本身不创建 第二个 MCP Server，也不自行注册 Resource。更新回调同步运行在产生 Shell/Execution 变化的 Domain/worker 线程上，必须快速返回且线程安全；需要执行异步工作时，由宿主投递到自己的事件 循环。取消订阅函数可幂等调用，aclose() 会清理全部遗留订阅；Runtime 进入 closing 后不再 调用回调，Resource 枚举、读取和新增订阅与工具调用一样会被拒绝。需要跨实例 限制线程数时，宿主可以把同一个 ToolConcurrencyBudget 传给多个 create() 调用；这些 实例必须运行在同一个 AnyIO backend 和宿主事件循环中，budget 不支持跨线程、跨事件循环 或跨 asyncio/Trio backend 共享。

aclose() 可并发、幂等调用；清理失败会向调用方报错并允许重试。运行时进入关闭状态后拒绝 新工具调用。工具调用被取消时等待方立即返回，底层工作线程按既有 abandon_on_cancel=True 语义退出等待，并由 Shell 生命周期/关闭流程完成资源回收。

Server 同时暴露 window://io.github.a2c-smcp.tfbash/shell-overview Markdown Resource， 供 A2C-SMCP Desktop 展示当前所有 Shell 的 ID、状态、cwd、最近 Execution 状态和末尾 500 个 Unicode 字符输出。该 Resource 支持订阅，并在 Shell 生命周期、Execution 状态或 输出变化时通过事件驱动的 ResourceUpdatedNotification 刷新；它是上下文补充，不替代 shell_list。七个工具还通过 Tool._meta.a2c_tool_meta.tags 声明 BuildIn 和对应 CRUD 能力标签，Computer 的更高优先级配置仍可按 A2C-SMCP v0.4.0 合并规则覆盖。

运行参数可通过 uv run tfbash-mcp --help 查看。--runtime-profile 仅接受 auto|bash|zsh|pwsh。--shell 是 stdio Runtime 实例级严格覆盖：只探测该程序，不成功时不回退； shell_open 不再接受 shell 字段，因此一个 Runtime 实例内所有 Shell 始终使用同一版本。 继承的环境变量只用于启动 Shell； shell_list 仅返回 Runtime、Host 和 Shell 状态，不返回环境变量名、值、启动命令或其他密钥材料。

服务在 stdin EOF、客户端断开或取消时走同一个有界 shutdown 路径，关闭全部 Shell 及其 受管进程。auto 的候选顺序为：macOS 系统 zsh → 其他 zsh → 系统 Bash → 其他 Bash；Linux 系统 Bash → 其他 Bash → 系统 zsh → 其他 zsh；Windows 稳定版 PowerShell Core → Windows PowerShell 5.1 → Git Bash。显式 zsh 仅支持 POSIX；Windows 支持显式 bash|pwsh。Windows Git Bash 使用 MSYS 路径语义执行命令，但 MCP cwd 字段仍返回 C:/... Windows 路径。WSL 不在 0.2.0 范围内，传入 WSL 程序会得到明确错误。

Zsh 不引入新的 Python 包；Bash、Zsh、PowerShell 与 Git Bash 都是可选的系统 程序。使用 uvx 时仍只需满足项目声明的 Python/uv 与对应平台依赖；Windows 的 ConPTY 实现继续由条件依赖 pywinpty 提供。

参与决策

0.2.0 的多 Shell + Execution 工具模型和跨平台方言/后端组合已实现。后续协议或 Runtime 变更仍须：

1. 对齐文档中的硬性门槛和未决项；

2. 对受影响的真实 PTY/ConPTY 路径执行可复现实验；

3. 确认 ide4ai 代码抽取的许可证保留方式、适配成本、长期维护面和退出策略；

4. 把实验结果和最终实现偏差回写到 RFC，再进入编码与验收。