Process management¶

MCP Server Fuzzer supervises local processes used by stdio transports and other runtime integrations. The runtime layer is asynchronous and separates process state, watchdog policy, and signal delivery so each concern can be tested independently.

Responsibilities¶

Component	Responsibility
`ProcessManager`	Starts, stops, waits for, and tracks managed subprocesses.
`ProcessRegistry`	Owns the current process records shared by the manager and watchdog.
`ProcessWatchdog`	Detects stale activity and applies the configured termination policy.
`SignalDispatcher`	Delivers graceful, force, and interrupt signals through the platform strategy.
`ProcessConfig`	Describes the command, environment, working directory, timeout, and activity callback.
`WatchdogConfig`	Sets check interval, timeout thresholds, buffering, and auto-kill behavior.

The AsyncFuzzExecutor is a separate concurrency primitive for fuzz operations. It is not a process supervisor and is documented only on its architecture page.

Runtime wiring¶

ProcessConfig
     |
ProcessManager ---- ProcessRegistry ---- ProcessWatchdog
     |                                      |
     +------------ SignalDispatcher --------+

Use ProcessManager.from_config(...) for the standard runtime wiring. Pass explicit dependencies to ProcessManager when tests or integrations need a custom registry, signal strategy, or watchdog policy.

Process lifecycle¶

State	Meaning
Unregistered	The process is not tracked by the runtime registry.
Registered	An existing process has been added to the registry.
Running	The manager launched the process and recorded its start.
Stopping	A graceful or forced stop has been requested.
Stopped	The process exited or was terminated and its result was recorded.
Shutdown	The manager stopped all tracked processes and the watchdog.

Observers can consume manager events such as started, stopped, signal, stopped_all, and shutdown.

Configuration¶

`ProcessConfig`¶

Field	Default	Description
`command`	required	Executable and arguments as a list.
`cwd`	`None`	Working directory for the child process.
`env`	`None`	Environment mapping for the child process.
`timeout`	`30.0`	Process timeout in seconds.
`auto_kill`	`True`	Whether the watchdog may terminate a stale process.
`name`	`"unknown"`	Human-readable name for logs and events.
`activity_callback`	`None`	Sync or async callback returning the latest activity timestamp.

`WatchdogConfig`¶

Field	Default	Description
`check_interval`	`1.0`	Seconds between watchdog checks.
`process_timeout`	`30.0`	Inactivity threshold before a process is considered stale.
`extra_buffer`	`5.0`	Grace period before termination.
`max_hang_time`	`60.0`	Maximum allowed hang time.
`auto_kill`	`True`	Whether stale processes are terminated automatically.

The CLI exposes these settings as --watchdog-* options. See the CLI reference for defaults and the process management guide for operational choices.

Safety and platform behavior¶

Process management is not a security boundary by itself. Run local targets in a disposable workspace, use --fs-root and --no-network where appropriate, and apply the safety system before starting an untrusted stdio server.

Signal behavior is platform-specific: Unix uses signals such as SIGTERM, SIGINT, and SIGKILL; Windows uses the supported process-group and terminate operations. A graceful stop may be followed by a force stop when the configured maximum hang time is exceeded.

Public API pointers¶

The implementation lives under mcp_fuzzer.fuzz_engine.runtime. The focused guidance page covers startup, timeouts, activity updates, shutdown, and troubleshooting. The API reference should be read alongside the source and tests when building an integration.