transparent json-rpc proxy forwarding with session persistence
Implements a transparent MCP protocol proxy (MCPProxy class) that intercepts and forwards all JSON-RPC messages between MCP clients and child servers without protocol modification. Uses ProcessManager for lifecycle management and maintains client connections across server restarts by preserving the proxy socket layer, enabling seamless context retention during development iterations.
Unique: Uses transparent JSON-RPC forwarding at the protocol level rather than wrapping individual tool calls, preserving full MCP semantics while injecting restart capability. Session persistence is achieved by maintaining the proxy socket across child process restarts, not by storing state in external systems.
vs alternatives: Differs from manual restart workflows by eliminating context loss; differs from client-side hot-reload by operating at the protocol layer without requiring client modifications.
capability augmentation via restart_server tool injection
Implements CapabilityAugmenter that intercepts the server's initialize response and injects a synthetic restart_server tool into the capabilities list. When called, this tool triggers RestartHandler to spawn a new child process and seamlessly reconnect the proxy, enabling AI clients to autonomously restart the server without manual intervention or special knowledge of the underlying process management.
Unique: Injects restart capability at the MCP protocol level by modifying the initialize response, making restart a first-class tool rather than a hidden proxy feature. This allows AI clients to discover and invoke restart autonomously without special configuration.
vs alternatives: More elegant than requiring clients to implement restart logic or developers to manually add restart endpoints; more discoverable than hidden CLI commands.
configuration via environment variables and cli arguments
Implements ConfigurationSystem that reads settings from environment variables (MCP_SERVER_COMMAND, MCP_SERVER_ARGS, etc.) and CLI arguments, with environment variables taking precedence. Supports configuration of server command, arguments, working directory, environment variables, and transport settings. Configuration is applied at startup and affects both proxy and inspection modes, enabling flexible deployment without code changes.
Unique: Uses environment variables as primary configuration mechanism, enabling deployment flexibility without code changes. CLI arguments provide override capability for development workflows.
vs alternatives: More flexible than hardcoded configuration; simpler than configuration file management; compatible with standard deployment practices.
message flow interception and augmentation
Implements message interception at the JSON-RPC level to augment capabilities, inject tools, and modify responses without altering protocol semantics. Uses middleware-style pattern where messages flow through CapabilityAugmenter and RestartHandler before forwarding to client or server. Enables non-invasive modifications to server behavior (e.g., adding restart_server tool) without modifying the server implementation or breaking protocol compliance.
Unique: Implements middleware-style message interception at the JSON-RPC level, enabling non-invasive augmentation without breaking protocol compliance. Separates augmentation logic (CapabilityAugmenter) from proxy forwarding logic (MCPProxy).
vs alternatives: More elegant than server-side modifications; more transparent than client-side wrapping; preserves protocol semantics.
process lifecycle management with automatic respawning
Implements ProcessManager that handles spawning, monitoring, and respawning of child MCP server processes. Tracks process state, captures stdout/stderr, manages signal handling, and automatically respawns on crash or explicit restart request. Integrates with RestartHandler to coordinate graceful termination and reconnection, ensuring the proxy can maintain client connections across process boundaries.
Unique: Couples process lifecycle with proxy session persistence — respawned processes automatically reconnect through the same proxy socket, preserving client context. Uses ProcessManager abstraction to decouple lifecycle logic from proxy forwarding logic.
vs alternatives: More integrated than generic process managers (PM2, systemd) because it understands MCP protocol semantics and coordinates with proxy state; more lightweight than full orchestration platforms.
cli-based mcp server inspection with stateless command execution
Implements 8 inspection commands (list-tools, call-tool, list-resources, read-resource, list-prompts, get-prompt, server-info, ping) that spawn a fresh child server process per command, execute the inspection, and return JSON-formatted results. Uses SimpleClient to communicate with the spawned server via stdio, providing a stateless testing interface that requires no persistent client connection or configuration.
Unique: Provides stateless, one-shot inspection without requiring persistent client setup or configuration. Each command spawns a fresh server instance, making it ideal for CI/CD and automated testing. JSON output is designed for machine parsing and automation.
vs alternatives: Simpler than setting up VSCode or Claude Code for testing; more scriptable than interactive clients; faster iteration than manual client configuration.
persistent mcp server mode for cli-based tool exposure
Implements optional persistent mode (inspect mcp command) that runs the inspection CLI as a full MCP server, exposing debug tools (list-tools, call-tool, etc.) as MCP tools themselves. This allows AI clients to introspect and test the child server through the inspection interface, bridging CLI inspection capabilities with full MCP client workflows by wrapping stateless commands in a persistent server wrapper.
Unique: Wraps stateless CLI inspection commands in a persistent MCP server layer, allowing AI clients to access inspection capabilities through standard MCP tool invocation. Bridges the gap between lightweight CLI testing and full client integration.
vs alternatives: More flexible than CLI-only inspection because it integrates with AI clients; more lightweight than proxy mode because it doesn't maintain persistent child server state.
multi-client compatibility with stdio and tcp transport
Supports multiple MCP client transports (stdio for VSCode/Cursor/Windsurf, TCP for remote clients) through configurable transport layer. Proxy mode automatically detects and adapts to the client's transport mechanism, enabling the same reloaderoo instance to work with different AI IDEs without configuration changes. Transport abstraction is handled at the JSON-RPC message level, preserving protocol semantics across transport boundaries.
Unique: Abstracts transport mechanism at the JSON-RPC message layer, allowing the same proxy logic to work with stdio and TCP clients without duplication. Automatic detection for stdio means zero configuration for local development.
vs alternatives: More flexible than client-specific solutions; more transparent than requiring separate proxy instances per client type.
+4 more capabilities