Reloaderoo

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.

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.

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.

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.

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.

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.

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.

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.

Orchestrates the complete hot-reload cycle: client sends restart_server tool call → RestartHandler terminates child process → ProcessManager spawns new process → proxy reconnects → client receives restart confirmation → conversation context remains intact. The entire cycle preserves the client's session state, conversation history, and context window, enabling developers to iterate on server code without losing their place in the AI interaction.

Implements structured tool calling for inspection commands (call-tool) with full JSON-RPC error handling, argument validation, and result formatting. Uses SimpleClient to send properly formatted JSON-RPC 2.0 tool call messages to the spawned server, captures responses, and returns structured results with error details. Supports complex argument types (objects, arrays) and preserves error context for debugging.

Implements inspection commands for MCP resources (list-resources, read-resource) and prompts (list-prompts, get-prompt) that query the server's resource and prompt capabilities and retrieve their content. Uses SimpleClient to send MCP protocol messages for resource/prompt discovery and content retrieval, returning structured JSON with metadata and content. Enables developers to verify resource URIs and prompt definitions without manual server inspection.

Implements server-info and ping commands that query the MCP server's metadata (name, version, capabilities) and verify connectivity. Uses SimpleClient to send MCP protocol messages and parse responses, returning structured server information and latency measurements. Enables developers to verify server availability, version, and capability list without full tool enumeration.