director-shell-mcp

director-shell-mcp es un pequeño servidor MCP para agentes en modo director. Utiliza el transporte stdio de MCP para proporcionar una vía de escape controlada para escribir archivos, ejecutar código Python de exploración de datos, ejecutar comandos de shell y supervisar trabajos en segundo plano desacoplados. Los comandos se inician solo cuando un agente llama explícitamente a una herramienta; el servidor no ejecuta un shell por sí mismo.

Instalación

Se requiere Node.js 18 o superior. Desde este directorio:

npm install

Ejecute el servidor directamente con:

node C:/path/to/director-shell-mcp/index.js

Related MCP server: shell-0

Registro en OMP (principal)

El cliente principal es el entorno Oh My Pi (OMP). Añada esta configuración exacta al ~/.omp/agent/mcp.json a nivel de usuario (o al .omp/mcp.json a nivel de proyecto):

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "director-shell": {
      "command": "node",
      "args": ["C:/path/to/director-shell-mcp/index.js"]
    }
  }
}

Para servidores stdio, type puede omitirse. Después de editar la configuración, ejecute /mcp reload y luego /mcp test director-shell en OMP.

Registro genérico de cliente MCP

Otros clientes MCP generalmente aceptan un registro stdio equivalente:

{
  "mcpServers": {
    "director-shell": {
      "command": "node",
      "args": ["C:/path/to/director-shell-mcp/index.js"]
    }
  }
}

Referencia de herramientas

Todas las herramientas devuelven un objeto JSON en el contenido de texto MCP. Los errores se devuelven como errores de herramienta MCP con un campo error en forma de frase.

shell_run

Ejecuta un comando hasta su finalización. Parámetros:

• command (cadena, obligatorio): texto del comando.

• cwd (cadena, opcional): directorio de trabajo.

• timeout_ms (entero, opcional): por defecto 60,000; máximo 600,000.

• shell (powershell, cmd o bash, opcional): por defecto PowerShell en Windows y Bash en otros sistemas.

El resultado contiene exit_code, duration_ms y objetos stdout/stderr. Cada flujo incluye hasta aproximadamente 50 KiB de texto de vista previa. Si un flujo supera ese límite, su objeto también incluye truncated: true y full_output_path que apunta a un archivo temporal que contiene el flujo completo. Un tiempo de espera agotado devuelve un error de herramienta MCP con un mensaje claro y el resultado parcial.

write_file

Escribe texto UTF-8 en una ruta de archivo absoluta. Parámetros:

• path (cadena, obligatorio): ruta de archivo absoluta.

• content (cadena, obligatorio): texto a escribir.

• append (booleano, opcional): añadir en lugar de reemplazar; por defecto false.

• create_dirs (booleano, opcional): crear directorios padre faltantes; por defecto true.

El resultado contiene path, bytes_written, created (si el archivo no existía antes de la llamada) y appended.

edit_file

Reemplaza texto en un archivo UTF-8 en una ruta absoluta. Parámetros:

• path (cadena, obligatorio): ruta de archivo absoluta.

• old_text (cadena, obligatorio): texto no vacío a buscar.

• new_text (cadena, obligatorio): texto de reemplazo.

• replace_all (booleano, opcional): reemplazar cada ocurrencia; por defecto false.

Sin replace_all, old_text debe aparecer exactamente una vez. Cero coincidencias o múltiples coincidencias devuelven un error de herramienta MCP y dejan el archivo sin cambios. El resultado contiene path y replacements.

run_python

Ejecuta código fuente Python hasta su finalización con salida limitada y un tiempo de espera. En Windows, el servidor prueba primero el lanzador py y luego python; en otros sistemas prueba primero python3 y luego python, almacenando en caché el primer ejecutable utilizable. Parámetros:

• code (cadena, obligatorio): código fuente Python.

• cwd (cadena, opcional): directorio de trabajo para el proceso Python.

• timeout_ms (entero, opcional): por defecto 60,000; máximo 600,000.

• args (matriz de cadenas, opcional): valores pasados como sys.argv[1:].

El resultado contiene exit_code, duration_ms, objetos stdout/stderr y python_executable. Los flujos de salida están limitados y se vuelcan a archivos temporales usando el mismo comportamiento que shell_run. Un tiempo de espera agotado devuelve un error de herramienta MCP con un mensaje claro y el resultado parcial.

job_start

Inicia un comando desacoplado que continúa después de que la llamada a la herramienta regrese. Parámetros:

• command (cadena, obligatorio)

• cwd (cadena, opcional)

• shell (powershell, cmd o bash, opcional)

• name (cadena, opcional, etiqueta legible por humanos)

El resultado contiene job_id, pid, log_paths (stdout, stderr y combined) y la ruta exit_marker. Los metadatos se persisten como JSON en %LOCALAPPDATA%/director-shell-mcp/jobs/<jobId>/, por lo que los trabajos permanecen descubribles después de un reinicio del servidor.

job_status

Lee el estado persistido de un trabajo. Parámetros:

• job_id (cadena, obligatorio): un id devuelto por job_start.

• tail_lines (entero, opcional): por defecto 40; máximo 1,000.

El resultado contiene running, exit_code (cuando esté disponible), runtime_ms, started_at y output_tail del registro combinado. El envoltorio desacoplado escribe exit_code.txt cuando el comando sale, preservando el código de salida a través de reinicios del servidor.

job_kill

Termina un trabajo iniciado por este servidor. Acepta job_id. En Windows usa taskkill /T /F para terminar el árbol de procesos del envoltorio. Los trabajos que ya se completaron se dejan sin cambios.

job_list

Lista todos los trabajos persistidos válidos con su job_id, name opcional, pid, estado running, código de salida y hora de inicio.

grep_files

Busca recursivamente en un archivo o directorio absoluto usando una expresión regular de JavaScript sin requerir ripgrep. La búsqueda omite node_modules, .git, bin, obj, dist y target, ignora archivos mayores de 5 MiB y archivos binarios, y se detiene en el límite de resultados. Parámetros:

• pattern (cadena, obligatorio): fuente de expresión regular de JavaScript.

• path (cadena, obligatorio): ruta absoluta de archivo o directorio.

• glob (cadena, opcional): filtro simple de nombre de archivo usando * y ?.

• case_sensitive (booleano, opcional): por defecto false.

• max_results (entero, opcional): por defecto 200; máximo 1,000.

• context_lines (entero, opcional): líneas antes y después de cada coincidencia; por defecto 0; máximo 5.

El resultado contiene matches con file, line_number, line, before y after, además de files_scanned y truncated. Las expresiones regulares inválidas devuelven un error de herramienta MCP.

job_wait

Espera a que un trabajo desacoplado existente salga, sondeando su marcador de salida persistido cada 500 ms. Parámetros:

• job_id (cadena, obligatorio): id devuelto por job_start.

• timeout_ms (entero, opcional): por defecto 60,000; máximo 600,000.

• tail_lines (entero, opcional): por defecto 40; máximo 1,000.

El resultado tiene los mismos campos que job_status y añade timed_out. Un plazo vencido mientras el trabajo aún se está ejecutando es un resultado normal con timed_out: true, no un error MCP.

lock_acquire y lock_release

Proporcionan un mutex nombrado entre agentes persistido en %LOCALAPPDATA%/director-shell-mcp/locks/. Los nombres contienen solo letras, dígitos, _, . y - y tienen como máximo 64 caracteres. lock_acquire acepta name (obligatorio), wait_ms (opcional, por defecto 0, máximo 600,000) y una note opcional; devuelve name, un token UUID y acquired_at. La adquisición usa una creación atómica de directorio y recupera bloqueos cuyo proceso propietario registrado ya no está vivo. Un error de bloqueo mantenido identifica su pid, nota cuando esté presente y duración. lock_release acepta name y el token del propietario; tokens incorrectos y bloqueos libres son errores y no cambian el bloqueo.

screenshot

Captura la pantalla virtual completa, o una ventana de nivel superior visible, a un PNG en Windows usando System.Drawing y las API de Windows. Parámetros:

• target (screen o window, opcional): por defecto screen.

• window_title (cadena, obligatoria para window): subcadena del título de ventana visible, sin distinción de mayúsculas.

• output_path (.png absoluto, opcional): por defecto un archivo con marca de tiempo en el directorio de salida temporal.

El resultado contiene path, width, height, target y el window_title coincidente para capturas de ventana. Devuelve un error claro de no soportado en sistemas que no son Windows y un error claro de no coincidencia cuando no se puede encontrar la ventana solicitada.

process_list

Devuelve un listado de procesos de solo lectura en Windows. Parámetros:

• name_filter (cadena, opcional): subcadena sin distinción de mayúsculas de un nombre de proceso o ruta de ejecutable.

• max_results (entero, opcional): por defecto 100; máximo 1,000.

Cada proceso contiene pid y name, e incluye path, started_at y working_set_bytes cuando estén disponibles. El resultado también contiene truncated.

file_lockers

Informa sobre procesos que mantienen abierto un archivo existente en Windows mediante la API Restart Manager. Acepta path (obligatorio), que debe ser una ruta absoluta a un archivo existente, y devuelve { path, lockers }. Cada bloqueador contiene pid, app_name y app_type; un archivo desbloqueado es un resultado exitoso con una matriz lockers vacía. Los sistemas que no son Windows devuelven un error claro de no soportado.

Verificación

Ejecute la prueba de humo ligera de extremo a extremo (usa solo echo y sleep de PowerShell):

npm run smoke

La prueba de humo inicia un nuevo servidor MCP sobre stdio, realiza la inicialización, lista las quince herramientas, ejercita la escritura de archivos, la edición de texto exacta, la ejecución de Python y el paso de argumentos, la finalización de comandos y la captura de salida, verifica trabajos desacoplados mientras se ejecutan y después de que salen, ejercita grep, wait, bloqueos, capturas de pantalla, listado de procesos y detección de bloqueadores de archivos de Restart Manager, comprueba la persistencia a través de job_list y verifica el manejo de tiempo de espera de comandos.

Licencia

MIT