mcproc

Gerencie processos em segundo plano para agentes de IA usando o Model Context Protocol (MCP).

Documentação

mcproc

Um servidor Model Context Protocol (MCP) para gerenciamento confortável de processos em segundo plano para agentes de IA.

English | 日本語

Visão Geral

O mcproc preenche a lacuna entre o desenvolvimento de agentes de IA e os fluxos de trabalho tradicionais de linha de comando. Ele permite que agentes de IA gerenciem processos de desenvolvimento de longa duração (como servidores de desenvolvimento, watchers de build, etc.) enquanto oferece aos desenvolvedores acesso completo via CLI para monitorar e controlar esses mesmos processos.

Por que mcproc?

Processos simples iniciados por agentes de IA não têm estado e não conseguem gerenciar processos de longa duração de forma eficaz. O mcproc resolve isso através de:

Controle Unificado: Sem mais confusão sobre qual agente ou terminal está executando o quê — todos os processos são gerenciados centralmente
Preservação de Contexto: Logs são capturados e armazenados, permitindo que agentes de IA depurem problemas enquanto revisam logs anteriores
Amigável para Desenvolvedores: Acesso completo via CLI significa que você nunca fica bloqueado do seu próprio ambiente de desenvolvimento

Principais Recursos

🔄 Gerenciamento Unificado de Processos: Inicie e gerencie processos em segundo plano a partir de agentes de IA via MCP, depois monitore-os pelo seu terminal
👁️ Visibilidade entre Ambientes: Processos iniciados por agentes de IA são totalmente acessíveis via CLI e por outros agentes, e vice-versa
📝 Gerenciamento Inteligente de Logs: Capture, persista e pesquise logs de processos com padrões regex poderosos
📁 Ciente do Projeto: Agrupa automaticamente processos por contexto de projeto
📊 Monitoramento em Tempo Real: Acompanhe logs em tempo real pelo CLI enquanto agentes de IA gerenciam os processos
🛡️ Compatível com XDG: Segue a especificação XDG Base Directory para organização adequada de arquivos
⚡ Aguardar por Log: Inicie processos e aguarde padrões específicos de log para garantir prontidão
🔍 Busca Avançada: Filtragem por tempo, linhas de contexto e suporte a regex para análise de logs
🧰 Suporte a Toolchains: Execute comandos através de gerenciadores de versão (mise, asdf, nvm, rbenv, etc.)
🧹 Comando Limpo: Pare todos os processos de um projeto com um único comando
🌲 Grupos de Processos: Limpeza automática de processos filhos ao parar processos pais

Instalação

Usando Homebrew (macOS e Linux)

# Add the tap
brew tap neptaco/tap

# Install mcproc
brew install mcproc

Compilar a partir do código-fonte

Pré-requisitos

Toolchain Rust (rustc, cargo)
Compilador 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

Configuração como Servidor MCP

Após instalar o mcproc, você precisa registrá-lo como um servidor MCP no seu assistente de IA.

Para Claude Code

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

Para Outros Clientes MCP

Configure seu cliente MCP adicionando o mcproc à sua configuração:

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

Ferramentas MCP Disponíveis

Uma vez registrado, os agentes de IA podem usar estas ferramentas:

start_process: Iniciar um servidor de desenvolvimento ou processo em segundo plano
stop_process: Parar um processo em execução
restart_process: Reiniciar um processo
list_processes: Listar todos os processos em execução
get_process_logs: Recuperar logs de processos
search_process_logs: Pesquisar nos logs de processos com correspondência de padrões
get_process_status: Obter informações detalhadas do processo

Para Desenvolvedores (CLI)

Enquanto os agentes de IA gerenciam processos em segundo plano, você pode monitorá-los e controlá-los:

Comando recomendado: mcproc logs -f

Comandos CLI

Comando	Descrição	Flags	Exemplo
🗒️ `ps`	Listar todos os processos em execução	`-s, --status <STATUS>` Filtrar por status	`mcproc ps --status running`
🚀 `start <NAME>`	Iniciar um novo processo	`-c, --cmd <CMD>` Comando a executar `-d, --cwd <DIR>` Diretório de trabalho `-e, --env <KEY=VAL>` Variáveis de ambiente `-p, --project <NAME>` Nome do projeto `--wait-for-log <PATTERN>` Aguardar padrão de log `--wait-timeout <SECS>` Tempo limite de espera `--toolchain <TOOL>` Gerenciador de versão a usar	`mcproc start web -c "npm run dev" -d ./app`
🛑 `stop <NAME>`	Parar um processo em execução	`-p, --project <NAME>` Nome do projeto `-f, --force` Forçar encerramento (SIGKILL)	`mcproc stop web -p myapp`
🔄 `restart <NAME>`	Reiniciar um processo	`-p, --project <NAME>` Nome do projeto	`mcproc restart web`
📜 `logs <NAME>`	Visualizar logs do processo	`-p, --project <NAME>` Nome do projeto `-f, --follow` Acompanhar saída do log `-t, --tail <NUM>` Número de linhas a exibir	`mcproc logs web -f -t 100`
🔍 `grep <NAME> <PATTERN>`	Pesquisar logs com regex	`-p, --project <NAME>` Nome do projeto `-C, --context <NUM>` Linhas de contexto `-B, --before <NUM>` Linhas antes da correspondência `-A, --after <NUM>` Linhas após a correspondência `--since <TIME>` Pesquisar desde o horário `--until <TIME>` Pesquisar até o horário `--last <DURATION>` Pesquisar última duração	`mcproc grep web "error" -C 3`
🧹 `clean`	Parar todos os processos do projeto	`-p, --project <NAME>` Nome do projeto `-f, --force` Forçar encerramento	`mcproc clean -p myapp`
🎛️ `daemon start`	Iniciar o daemon mcproc	Nenhum	`mcproc daemon start`
🎛️ `daemon stop`	Parar o daemon mcproc	Nenhum	`mcproc daemon stop`
🎛️ `daemon status`	Verificar status do daemon	Nenhum	`mcproc daemon status`
🔌 `mcp serve`	Executar como servidor MCP	Nenhum	`mcproc mcp serve`
ℹ️ `--version`	Exibir informações de versão	Nenhum	`mcproc --version`
❓ `--help`	Exibir mensagem de ajuda	Nenhum	`mcproc --help`

Exemplos

# 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

Fluxo de Trabalho de Exemplo

O agente de IA inicia seu servidor de desenvolvimento:

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")

Você o monitora pelo terminal:

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

O agente de IA detecta um erro e pesquisa nos logs:

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

Você pode ver as mesmas informações:

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

Exemplos Avançados

# 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

Arquitetura

O mcproc consiste em três componentes principais:

Daemon mcproc: Um daemon leve que gerencia processos e lida com a persistência de logs
CLI mcproc: Interface de linha de comando para desenvolvedores interagirem com o daemon
Servidor MCP: Expõe capacidades de gerenciamento de processos para agentes de IA via Model Context Protocol

Locais de Arquivos (Compatível com XDG)

Configuração: $XDG_CONFIG_HOME/mcproc/config.toml (padrão: ~/.config/mcproc/)
Logs: $XDG_STATE_HOME/mcproc/log/ (padrão: ~/.local/state/mcproc/log/)
Runtime: $XDG_RUNTIME_DIR/mcproc/ (padrão: /tmp/mcproc-$UID/)

Desenvolvimento

Compilando a partir do Código-Fonte

# 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

Estrutura do Projeto

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

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Licença MIT

A permissão é concedida, gratuitamente, a qualquer pessoa que obtenha uma cópia deste software e dos arquivos de documentação associados (o "Software"), para lidar com o Software sem restrições, incluindo, sem limitação, os direitos de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do Software, e permitir que as pessoas às quais o Software é fornecido o façam, sujeito às seguintes condições:

O aviso de copyright acima e este aviso de permissão devem ser incluídos em todas as cópias ou partes substanciais do Software.

O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM DETERMINADO FIM E NÃO VIOLAÇÃO. EM NENHUM CASO OS AUTORES OU DETENTORES DE DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER RECLAMAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM AÇÃO DE CONTRATO, ATO ILÍCITO OU OUTRA FORMA, DECORRENTE DE, FORA OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.