tfbash-mcp

Базовый набор MCP-инструментов для агентных систем. Проект стремится предоставить разным агентам набор стабильных, компонуемых универсальных возможностей с низкой когнитивной нагрузкой, таких как выполнение команд, чтение/запись файлов и поиск; конкретные возможности предпочтительно переиспользуют зрелые реализации, и только когда существующие решения не удовлетворяют ключевым ограничениям, рассматривается адаптация или собственная разработка.

Текущий статус: скелет Python-проекта и RFC по требованиям/архитектуре. Репозиторий может запустить пустой stdio MCP Server, но инструменты Shell, определённые в RFC, пока не предоставлены.

Зачем нужен этот проект

Агентам часто приходится выходить за рамки чисто текстовых рассуждений и работать с реальным рабочим пространством или вызывать локальные программы. Программисты используют Shell как основной рабочий интерфейс; специалисты по продукту, операционной деятельности, исследованиям и другим общим направлениям также вызывают через Shell скрипты, конвертируют файлы, пакетно обрабатывают данные или диагностируют окружение.

Существующие MCP-инструменты сильно различаются по охвату возможностей и модели выполнения: одни поддерживают только разовые команды, другие зависят от PTY или постоянно работающего демона, третьи имеют встроенные approval и песочницу, четвёртым не хватает надёжной работы с длинными командами, инкрементальным выводом и управляемой очисткой процессов. tfbash-mcp сначала определяет реальные сценарии и проверяемые контракты возможностей, а затем решает, использовать ли готовое решение напрямую, адаптировать его или разрабатывать самостоятельно.

Related MCP server: MCP Terminal Tool Server

Принципы проектирования

• Сначала сценарии, потом выбор технологий: не выводить требования задним числом из знакомства с каким-либо языком, фреймворком или существующим проектом.

• Приоритет переиспользованию: порядок выбора — Adopt → Wrap → Build; переиспользование допустимо только при условии удовлетворения ключевого поведения.

• Малый объём и ортогональность: базовые инструменты сохраняют чёткие границы, не допуская включения оркестрации агентов, бизнес-процессов или UI в инструментальный слой.

• Явное состояние: длительные задачи, постоянные Shell, курсоры вывода, коды выхода и жизненный цикл ресурсов должны быть наблюдаемы; Shell, которым нужно сохранять cwd/env, должны явно создаваться и адресоваться.

• Протокол не зависит от языка реализации: контракты инструментов не раскрывают внутренние концепции Python, pexpect, Computer или клиента; в V1 используются Python + pexpect и транспорт stdio.

• Доверие к среде развёртывания: на первом этапе не встроены approval, песочница, политики команд или границы каталогов.

• Контролируемые ресурсы: память, диск, сеансы, процессы и временные файлы должны иметь явные лимиты, владельца и правила очистки.

Первый этап: инструменты Bash

Первый этап фокусируется на автономном универсальном Bash MCP Server для Unix-сред (Linux, macOS). Цели охватывают одновременно:

• сборку, тестирование, поиск по коду, запуск сервисов и наблюдение за логами для программистов;

• обработку файлов, преобразование данных и диагностику окружения через установленные CLI или скрипты для специалистов общих направлений;

• несколько адресуемых постоянных Command Shell, которые отдельно сохраняют cwd, окружение и состояние активации, а для каждой команды возвращают точный код выхода;

• stdout/stderr PTY pexpect возвращаются как combined output, а для каждого выполнения поддерживается ограниченный инкрементальный вывод;

• короткие команды возвращаются одним вызовом shell_exec; длинные команды после превышения yield_ms возвращают running и продолжают выполняться в исходном Shell;

• длинные команды читаются инкрементально через shell_read, записываются в stdin через shell_write, прерываются или завершаются через shell_signal;

• постоянные Command Shell поддерживают создание, выполнение, инкрементальное чтение, запись, сигналы, перечисление и закрытие; отдельные группы инструментов фоновых Job и Terminal больше не раскрываются;

• Shell и Execution принадлежат процессу MCP-сервиса и сохраняются между вызовами инструментов, но восстановление после перезапуска сервиса не гарантируется;

• одному Computer клиента tfrobot-client соответствует один процесс MCP, управляемый SDK; клиент хранит только переключатель включения и статус выполнения.

Постоянные Shell первого этапа используют PTY, но предоставляют только командно-ориентированный текстовый поток, без полноэкранной модели экрана TUI, сырых терминальных Session или resize. Если в дальнейшем появятся явные интеграторы xterm.js, REPL или полноэкранного TUI, на той же модели ресурсов Shell будет добавлен режим Terminal. Также не включаются approval команд, песочница процессов, восстановление после перезапуска сервиса и жёсткая привязка к MCP Tasks.

Связанные документы:

• Требования и архитектура универсального Bash MCP Server: определяет границы автономного MCP, контракты инструментов, область переиспользования ide4ai, обязанности SDK/клиента и критерии приёмки.

Планируемые базовые возможности

Текущая дорожная карта выражает только порядок исследования и не означает решения о самостоятельной разработке:

1. постоянные Shell и Execution длинных команд;

2. чтение, запись и изменение файлов в виде патчей;

3. обнаружение файлов и текстовый поиск;

4. другие небольшие базовые инструменты, дополняемые на основе реальных рабочих процессов агентов.

Каждая возможность должна сначала получить отдельные требования и исследование кандидатов, а также зафиксировать обоснование решения Adopt, Wrap или Build. Разные возможности могут использовать разные источники, при условии что модель ошибок, жизненный цикл и структура результатов, видимые агенту, остаются согласованными.

Структура репозитория

.
├── .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/ — локальный каталог для исследовательских checkout-копий; он объёмный и содержит несколько сторонних 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 модель инструментов Multi-Shell + Execution и базовую реализацию Python/pexpect, но это всё ещё RFC, ожидающий реализации и приёмки. Перед началом разработки необходимо как минимум:

1. согласовать жёсткие пороги и открытые вопросы из документа;

2. провести минимальный эксперимент по проверке жизнеспособности выбранного базиса pexpect;

3. подтвердить способ сохранения лицензии при извлечении кода ide4ai, стоимость адаптации, долгосрочную поверхность сопровождения и стратегию выхода;

4. записать результаты экспериментов и итоговые отклонения реализации обратно в RFC, затем переходить к кодированию и приёмке.