mcproc

Gestiona procesos en segundo plano para agentes de IA utilizando el Protocolo de Contexto de Modelo (MCP).

Documentación

mcproc

Un servidor de Model Context Protocol (MCP) para la gestión cómoda de procesos en segundo plano para agentes de IA.

Resumen

mcproc une la brecha entre el desarrollo de agentes de IA y los flujos de trabajo tradicionales de línea de comandos. Permite a los agentes de IA gestionar procesos de desarrollo de larga duración (como servidores de desarrollo, observadores de compilación, etc.) mientras proporciona a los desarrolladores acceso completo a la CLI para monitorear y controlar estos mismos procesos.

¿Por qué mcproc?

Los procesos simples lanzados por agentes de IA no tienen estado y no pueden gestionar procesos de larga duración de manera efectiva. mcproc resuelve esto mediante:

Control Unificado: Sin más confusión sobre qué agente o terminal está ejecutando qué: todos los procesos se gestionan centralmente
Preservación de Contexto: Los registros se capturan y almacenan, permitiendo a los agentes de IA depurar problemas mientras revisan registros anteriores
Amigable para Desarrolladores: El acceso completo a la CLI significa que nunca estarás bloqueado de tu propio entorno de desarrollo

Características Clave

🔄 Gestión Unificada de Procesos: Inicia y gestiona procesos en segundo plano desde agentes de IA mediante MCP, luego monitorealos desde tu terminal
👁️ Visibilidad entre Entornos: Los procesos iniciados por agentes de IA son totalmente accesibles mediante CLI y otros agentes, y viceversa
📝 Gestión Inteligente de Registros: Captura, persiste y busca registros de procesos con potentes patrones de expresiones regulares
📁 Consciente del Proyecto: Agrupa automáticamente los procesos por contexto de proyecto
📊 Monitoreo en Tiempo Real: Sigue registros en tiempo real desde la CLI mientras los agentes de IA gestionan los procesos
🛡️ Conforme a XDG: Sigue la especificación de Directorio Base XDG para una organización adecuada de archivos
⚡ Esperar-Registro: Inicia procesos y espera patrones de registro específicos para asegurar la preparación
🔍 Búsqueda Avanzada: Filtrado basado en tiempo, líneas de contexto y soporte de expresiones regulares para análisis de registros
🧰 Soporte de Toolchain: Ejecuta comandos a través de gestores de versiones (mise, asdf, nvm, rbenv, etc.)
🧹 Comando Limpiar: Detiene todos los procesos en un proyecto con un solo comando
🌲 Grupos de Procesos: Limpieza automática de procesos hijos al detener procesos padres

Instalación

Usando Homebrew (macOS y Linux)

# Add the tap
brew tap neptaco/tap

# Install mcproc
brew install mcproc

Compilar desde el código fuente

Requisitos previos

Toolchain de Rust (rustc, cargo)
Compilador de protobuf:
- macOS: brew install protobuf
- Linux: apt-get install protobuf-compiler

git clone https://github.com/neptaco/mcproc.git
cd mcproc
cargo build --release

# Install to PATH (optional)
cargo install --path mcproc

Uso

Configuración como Servidor MCP

Después de instalar mcproc, debes registrarlo como servidor MCP con tu asistente de IA.

Para Claude Code

# Register mcproc as an MCP server
claude mcp add mcproc mcproc mcp serve

Para Otros Clientes MCP

Configura tu cliente MCP agregando mcproc a tu configuración:

{
  "mcpServers": {
    "mcproc": {
      "command": "mcproc",
      "args": ["mcp", "serve"]
    }
  }
}

Herramientas MCP Disponibles

Una vez registrado, los agentes de IA pueden usar estas herramientas:

start_process: Inicia un servidor de desarrollo o proceso en segundo plano
stop_process: Detiene un proceso en ejecución
restart_process: Reinicia un proceso
list_processes: Lista todos los procesos en ejecución
get_process_logs: Recupera registros de procesos
search_process_logs: Busca en registros de procesos con coincidencia de patrones
get_process_status: Obtiene información detallada del proceso

Para Desarrolladores (CLI)

Mientras los agentes de IA gestionan procesos en segundo plano, puedes monitorearlos y controlarlos:

Comando recomendado: mcproc logs -f

Comandos CLI

Comando	Descripción	Banderas	Ejemplo
🗒️ `ps`	Lista todos los procesos en ejecución	`-s, --status <STATUS>` Filtrar por estado	`mcproc ps --status running`
🚀 `start <NAME>`	Inicia un nuevo proceso	`-c, --cmd <CMD>` Comando a ejecutar `-d, --cwd <DIR>` Directorio de trabajo `-e, --env <KEY=VAL>` Variables de entorno `-p, --project <NAME>` Nombre del proyecto `--wait-for-log <PATTERN>` Esperar patrón de registro `--wait-timeout <SECS>` Tiempo de espera `--toolchain <TOOL>` Gestor de versiones a usar	`mcproc start web -c "npm run dev" -d ./app`
🛑 `stop <NAME>`	Detiene un proceso en ejecución	`-p, --project <NAME>` Nombre del proyecto `-f, --force` Forzar terminación (SIGKILL)	`mcproc stop web -p myapp`
🔄 `restart <NAME>`	Reinicia un proceso	`-p, --project <NAME>` Nombre del proyecto	`mcproc restart web`
📜 `logs <NAME>`	Ver registros de procesos	`-p, --project <NAME>` Nombre del proyecto `-f, --follow` Seguir salida de registros `-t, --tail <NUM>` Número de líneas a mostrar	`mcproc logs web -f -t 100`
🔍 `grep <NAME> <PATTERN>`	Buscar registros con expresiones regulares	`-p, --project <NAME>` Nombre del proyecto `-C, --context <NUM>` Líneas de contexto `-B, --before <NUM>` Líneas antes de la coincidencia `-A, --after <NUM>` Líneas después de la coincidencia `--since <TIME>` Buscar desde tiempo `--until <TIME>` Buscar hasta tiempo `--last <DURATION>` Buscar última duración	`mcproc grep web "error" -C 3`
🧹 `clean`	Detiene todos los procesos en el proyecto	`-p, --project <NAME>` Nombre del proyecto `-f, --force` Forzar terminación	`mcproc clean -p myapp`
🎛️ `daemon start`	Inicia el daemon de mcproc	Ninguna	`mcproc daemon start`
🎛️ `daemon stop`	Detiene el daemon de mcproc	Ninguna	`mcproc daemon stop`
🎛️ `daemon status`	Verifica el estado del daemon	Ninguna	`mcproc daemon status`
🔌 `mcp serve`	Ejecutar como servidor MCP	Ninguna	`mcproc mcp serve`
ℹ️ `--version`	Muestra información de versión	Ninguna	`mcproc --version`
❓ `--help`	Muestra mensaje de ayuda	Ninguna	`mcproc --help`

Ejemplos

# Start the daemon (if not already running)
mcproc daemon start

# View all processes (including those started by AI agents)
mcproc ps

# Follow logs in real-time
mcproc logs frontend -f

# Multi-process log streaming per project
mcproc logs -f

# Search through logs
mcproc grep backend "error" -C 5

# Stop a process
mcproc stop frontend

Flujo de Trabajo de Ejemplo

El agente de IA inicia tu servidor de desarrollo:

Agent: "I'll start the frontend dev server for you"
→ Uses MCP tool: start_process(name: "frontend", cmd: "npm run dev", wait_for_log: "Server running")

Tú lo monitoreas desde la terminal:

mcproc logs -f
# See real-time logs as the server runs

El agente de IA detecta un error y busca en los registros:

Agent: "Let me check what's causing that error"
→ Uses MCP tool: search_process_logs(name: "frontend", pattern: "ERROR|WARN", last: "5m")

Tú puedes ver la misma información:

mcproc grep frontend "ERROR|WARN" -C 3 --last 5m

Ejemplos Avanzados

# Start a process with environment variables
mcproc start api --cmd "python app.py" --env PORT=8000 --env DEBUG=true

# Wait for a specific log pattern before considering the process ready
mcproc start web --cmd "npm run dev" --wait-for-log "Server running on" --wait-timeout 60

# Search logs with time filters
mcproc grep api "database.*connection" --since "14:30" --until "15:00"

# View logs from multiple processes in the same project
mcproc ps
mcproc logs web --project myapp -t 100

# Use version managers for Node.js projects
mcproc start web --cmd "npm run dev" --toolchain nvm
mcproc start api --cmd "yarn start" --toolchain mise

# Clean up all processes in a project
mcproc clean --project myapp

# Force stop all processes in current project
mcproc clean --force

Arquitectura

mcproc consta de tres componentes principales:

Daemon de mcproc: Un daemon ligero que gestiona procesos y maneja la persistencia de registros
CLI de mcproc: Interfaz de línea de comandos para que los desarrolladores interactúen con el daemon
Servidor MCP: Expone capacidades de gestión de procesos a agentes de IA mediante el Model Context Protocol

Ubicaciones de Archivos (Conforme a XDG)

Configuración: $XDG_CONFIG_HOME/mcproc/config.toml (por defecto en ~/.config/mcproc/)
Registros: $XDG_STATE_HOME/mcproc/log/ (por defecto en ~/.local/state/mcproc/log/)
Runtime: $XDG_RUNTIME_DIR/mcproc/ (por defecto en /tmp/mcproc-$UID/)

Desarrollo

Compilación desde el Código Fuente

# Clone the repository
git clone https://github.com/neptaco/mcproc.git
cd mcproc

# Build all components
cargo build --release

# Run tests
cargo test

# Run with verbose logging
RUST_LOG=mcproc=debug cargo run -- daemon start

Estructura del Proyecto

mcproc/
├── mcproc/         # CLI and daemon implementation
├── mcp-rs/         # Reusable MCP server library
├── proto/          # Protocol buffer definitions
└── docs/           # Architecture and design documentation

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).

Licencia

Licencia MIT

Se otorga permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados (el "Software"), para tratar en el Software sin restricción, incluidos, sin limitación, los derechos de usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y para permitir a las personas a quienes el Software sea proporcionado para hacerlo, sujeto a las siguientes condiciones:

El aviso de copyright anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO PERO NO LIMITADO A LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN PROPÓSITO PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE DERECHOS DE AUTOR SERÁN RESPONSABLES DE CUALQUIER RECLAMO, DAÑOS U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRO MODO, QUE SURJA DE, FUERA DE O EN CONEXIÓN CON EL SOFTWARE O EL USO U OTROS TRATOS EN EL SOFTWARE.