Persistproc MCP Server for Controlling Long Running Processes

Overview

Persistproc is an MCP (Model Context Protocol) server and companion CLI designed to manage long-running processes such as web servers, daemons, and background workers. It provides a lightweight control plane that lets agents register processes, report health and status, and accept remote control commands (start, stop, restart, status) from an operator or automation system.

This tool is useful when you need predictable supervision and remote control over services without introducing a heavy orchestration stack. Persistproc is especially handy for self-hosted infrastructure, edge devices, or environments where you want a small, auditable control surface for process lifecycle operations.

Features

• Agent/server architecture for remote process supervision
• CLI for issuing control commands and querying process state
• Process start/stop/restart with graceful shutdown support
• Health and liveness reporting from agents
• Simple configuration (YAML/TOML) and environment-variable overrides
• Optional systemd integration and service files
• Lightweight logging and process event history
• Token-based or file-based authentication for control operations
• Extensible protocol (MCP) for integrating other tooling or UIs

Installation / Configuration

Clone and build from source (Go toolchain required):

# clone
git clone https://github.com/irskep/persistproc.git
cd persistproc

# build (example using Go)
go build ./cmd/persistproc
# or build both server and CLI binaries if split
go build ./cmd/persistproc-server
go build ./cmd/persistproc-cli

Or download a prebuilt binary (replace URL with actual release):

curl -L -o persistproc.tar.gz https://github.com/irskep/persistproc/releases/latest/download/persistproc-linux-amd64.tar.gz
tar xzf persistproc.tar.gz
sudo mv persistproc /usr/local/bin/

Sample YAML configuration (persistproc.yml):

server:
  bind_addr: 0.0.0.0
  port: 9999
  tls: false
  auth_token: "replace-with-secure-token"

agent:
  work_dir: /var/lib/persistproc
  log_dir: /var/log/persistproc
  restart_policy: on-failure
  graceful_shutdown_seconds: 10

Environment variables can override settings:

• PERSISTPROC_BIND_ADDR
• PERSISTPROC_PORT
• PERSISTPROC_AUTH_TOKEN

Systemd unit example to run the server as a service:

[Unit]
Description=Persistproc MCP Server
After=network.target

[Service]
User=persistproc
ExecStart=/usr/local/bin/persistproc server --config /etc/persistproc/persistproc.yml
Restart=on-failure

[Install]
WantedBy=multi-user.target

Available Tools

• persistproc (server) — runs the MCP server and manages agent connections
• persistproc-cli — command line client to query and control processes
• systemd service templates — sample units to run server or agents as services
• Dockerfile — optional container image for running the server in containers
• Example agent scripts — templates to supervise common runtimes (Node, Python, Go)

Use Cases

1. Restart a crashed web server automatically

   • Deploy an agent on the host running your web process. Configure a restart_policy of on-failure. The agent will restart the process if it exits unexpectedly and record the event to the server.

2. Remote, controlled rolling restarts for blue/green deploys

   • Use persistproc-cli to issue sequential restart commands across a fleet. The MCP server coordinates commands and provides status so you can confirm each instance is healthy before continuing.

3. Lightweight process management on edge devices

   • Run a persistproc agent on remote appliances that have intermittent connectivity. Agents buffer health reports and apply control commands when connectivity is available.

4. Integrate with monitoring and alerting

   • Use the MCP API to fetch process health and uptime. Connect this data to your monitoring system to trigger alerts when a service degrades, and optionally run automated remediation via CLI scripts.

5. Safe graceful shutdowns for stateful services

   • Configure graceful_shutdown_seconds to allow a process time to flush in-flight requests before being terminated during restart or stop operations.

Examples

Query process status with the CLI:

persistproc-cli status --server http://mcp.example.com:9999 --token $TOKEN --agent host-01

Restart a process on a specific agent:

persistproc-cli restart --agent host-01 --process my-web-service --graceful

Register and supervise a process via a simple agent config (example in agent.yml):

processes:
  - name: my-web-service
    cmd: /usr/bin/my-web-server --config /etc/my-web/config.yml
    cwd: /var/www
    env:
      PORT: "8080"
    restart: on-failure

Where to Learn More

• Source & releases: https://github.com/irskep/persistproc
• Look in the repo for example configs, systemd units, and CLI documentation
• Use the built-in help commands:
  • persistproc –help
  • persistproc-cli –help

Persistproc is intended as a minimal, auditable control layer for long-running processes — useful when you want more than init/systemd alone but less than a full orchestration platform.