tfbash-mcp

Conjunto de herramientas MCP básicas orientado a sistemas de agentes. El proyecto busca proporcionar a diferentes agentes un conjunto de capacidades comunes estables, componibles y de baja carga cognitiva, como ejecución de comandos, lectura/escritura de archivos y búsqueda; para capacidades específicas se prioriza reutilizar implementaciones maduras, y solo se considera adaptar o desarrollar internamente cuando las soluciones existentes no satisfacen las restricciones centrales.

Estado actual: esqueleto de proyecto Python y RFC de requisitos/arquitectura. El repositorio puede iniciar un servidor MCP stdio vacío, pero aún no proporciona las herramientas Shell definidas en el RFC.

Por qué hacer este proyecto

Los agentes a menudo necesitan salir del razonamiento de texto puro para operar en un espacio de trabajo real o invocar programas locales. Los programadores usan Shell como interfaz de trabajo principal; los puestos generales de producto, operaciones, investigación, etc., también usan Shell para invocar scripts, convertir archivos, procesar datos por lotes o diagnosticar el entorno.

Las herramientas MCP existentes difieren mucho en alcance y modelo de ejecución: algunas solo admiten comandos de una sola vez, otras dependen de PTY o procesos daemon residentes, otras incluyen aprobación y sandbox, y a menudo carecen de comandos largos confiable, salida incremental y limpieza de procesos gestionados. tfbash-mcp primero define escenarios reales y contratos de capacidad aceptables, y luego decide si adopta, envuelve o desarrolla internamente.

Related MCP server: MCP Terminal Tool Server

Principios de diseño

• Primero el escenario, luego la selección: no se deduce la necesidad a partir de la familiaridad con un lenguaje, framework o proyecto existente.

• Priorizar la reutilización: el orden de selección es Adopt → Wrap → Build; la reutilización debe basarse en satisfacer los comportamientos clave.

• Pequeño y ortogonal: las herramientas básicas mantienen límites claros, evitando meter orquestación de agentes, flujos de trabajo de negocio o UI en la capa de herramientas.

• Estado explícito: las tareas largas, Shell persistentes, cursores de salida, estados de salida y ciclos de vida de recursos deben ser observables; los Shell que necesitan conservar cwd/env deben crearse y direccionarse explícitamente.

• Independencia del protocolo y del lenguaje de implementación: el contrato de herramientas no expone conceptos internos de Python, pexpect, Computer o cliente; V1 usa Python + pexpect y transporte stdio.

• Confiar en el entorno de despliegue: la primera fase no incluye aprobación, sandbox, políticas de comandos ni límites de directorio.

• Recursos controlados: memoria, disco, sesiones, procesos y archivos temporales deben tener límites claros, propiedad y reglas de limpieza.

Primera fase: herramientas Bash

La primera fase se centra en un servidor MCP Bash genérico e independiente para entornos Unix (Linux, macOS). El objetivo cubre simultáneamente:

• Compilación, pruebas, búsqueda de código, inicio de servicios y observación de logs para programadores;

• Procesamiento de archivos, conversión de datos y diagnóstico de entorno mediante CLI o scripts instalados para puestos generales;

• Múltiples Shell de comandos persistentes direccionables que conservan cwd, entorno y estado de activación, y devuelven el estado de salida exacto para cada comando;

• stdout/stderr del PTY de pexpect se devuelven como salida combinada, y se mantiene salida incremental acotada para cada ejecución;

• Los comandos cortos se devuelven de una vez con shell_exec; los comandos largos devuelven running después de yield_ms y continúan ejecutándose en el mismo Shell;

• Los comandos largos se leen incrementalmente con shell_read, se escribe en stdin con shell_write y se interrumpen o terminan con shell_signal;

• Los Shell de comandos persistentes admiten creación, ejecución, lectura incremental, escritura, señales, listado y cierre, sin exponer grupos de herramientas de Job en segundo plano y Terminal independientes;

• Shell y Execution pertenecen al proceso de servicio MCP, se mantienen entre llamadas de herramientas, pero no se promete recuperación tras reinicio del servicio;

• Un Computer de tfrobot-client corresponde a un proceso MCP gestionado por el SDK, y el cliente solo conserva el interruptor de habilitación y el estado de ejecución.

Los Shell persistentes de la primera fase usarán PTY, pero solo proporcionan flujo de texto orientado a comandos, sin modelo de pantalla TUI de pantalla completa, sesión de Terminal cruda ni resize. Si más adelante aparece un integrador claro de xterm.js, REPL o TUI de pantalla completa, se añadirá el modo Terminal sobre el mismo modelo de recurso Shell. Tampoco se incluyen aprobación de comandos, sandbox de procesos, recuperación tras reinicio del servicio ni acoplamiento fuerte con MCP Tasks.

Documentación relacionada:

• Requisitos y arquitectura del servidor MCP Bash genérico: define el límite MCP independiente, el contrato de herramientas, el alcance de reutilización de ide4ai, las responsabilidades del SDK/cliente y los criterios de aceptación.

Capacidades básicas planificadas

La ruta actual solo expresa el orden de exploración, no representa una decisión de desarrollo interno:

1. Shell persistente y ejecución de comandos largos;

2. Lectura, escritura y modificación por parches de archivos;

3. Descubrimiento de archivos y búsqueda de texto;

4. Otras herramientas básicas pequeñas complementadas según flujos de trabajo reales de agentes.

Cada capacidad debe formar primero requisitos independientes e investigación de candidatos, y registrar la justificación de decisión Adopt, Wrap o Build. Diferentes capacidades pueden provenir de diferentes fuentes, siempre que el modelo de errores, el ciclo de vida y la estructura de resultados expuestos a los agentes sean consistentes.

Estructura del repositorio

.
├── .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/ es un directorio de investigación local, de gran tamaño y que contiene múltiples repositorios Git de terceros, por lo que no se incluirá en el control de versiones ni en el paquete de distribución de tfbash-mcp.

Desarrollo local

El proyecto admite Python 3.10–3.12 y usa uv para gestionar el entorno:

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

Iniciar el esqueleto del servidor stdio actual:

uv run tfbash-mcp

Este proceso actualmente no registra herramientas Shell; solo se usa para verificar el paquete, la entrada y el ciclo de vida de MCP stdio.

Participación en decisiones

El documento de requisitos ya ha definido el modelo de herramientas de múltiples Shell + Execution para V1 y la línea base de implementación Python/pexpect, pero sigue siendo un RFC pendiente de implementación y aceptación. Antes de entrar en desarrollo, se necesita al menos:

1. Alinear los umbrales estrictos y los puntos pendientes del documento;

2. ejecutar un experimento de viabilidad mínimo sobre la línea base de pexpect seleccionada;

3. confirmar la preservación de licencias del código extraído de ide4ai, el costo de adaptación, la superficie de mantenimiento a largo plazo y la estrategia de salida;

4. escribir los resultados del experimento y las desviaciones finales de implementación en el RFC, y luego entrar en codificación y aceptación.