Reloaderoo

Test and hot-reload MCP servers with CLI inspection tools and transparent proxy capabilities

A dual-mode MCP development toolthat operates as both a CLI inspection tool and a transparent proxy server for the Model Context Protocol (MCP). Works excellently with VSCode MCP, well with Claude Code, and supports other MCP-enabled clients.

reloaderooprovides two distinct operational modes to fit different development workflows:

Direct command-line access to MCP servers without client setup:

- ✅One-shot commands- Test tools, list resources, get server info
- ✅No MCP client required- Perfect for testing and debugging
- ✅Raw JSON output- Ideal for scripts and automation
- ✅8 inspection commands- Complete MCP protocol coverage

Transparent proxy server that enables seamless hot-reloading:

- ✅Hot-reload MCP serverswithout disconnecting your AI client
- ✅Session persistence- Keep your development context intact
- ✅Automaticrestart_servertool- AI agents can restart servers on demand
- ✅Transparent forwarding- Full MCP protocol passthrough

When developing MCP servers, you typically face two problems:
- Testing requires complex MCP client setup→ CLI mode solves this
- Code changes require restarting your entire AI session→ Proxy mode solves this

Both modes work together to create a seamless MCP development experience.

# Install globally for easy access npm install -g reloaderoo # Or use with npx (no installation required) npx reloaderoo --help

Perfect for testing MCP servers without client setup:

# List all tools in your server reloaderoo inspect list-tools -- node my-mcp-server.js # Call a specific tool reloaderoo inspect call-tool echo --params '{"message":"hello"}' -- node my-mcp-server.js # Get server information reloaderoo inspect server-info -- node my-mcp-server.js

For AI client integration with hot-reload capabilities:

# Start proxy server (your AI client connects to this) reloaderoo proxy -- node my-mcp-server.js # With debug logging reloaderoo proxy --log-level debug -- node my-mcp-server.js

Then configure your AI client to connect to reloaderoo instead of directly to your server.

Best Experience:VSCode&Cursor- Full protocol support with automatic capability detectionGood Experience:Claude Code&Windsurf- Works well, may need manual refresh for new tools

🔍CLI Mode Workflow(Testing & Debugging)

Perfect for testing individual tools or debugging server issues:

# 1. Test your server quickly reloaderoo inspect list-tools -- node my-mcp-server.js # 2. Call specific tools to verify behavior reloaderoo inspect call-tool my_tool --params '{"param":"value"}' -- node my-mcp-server.js # 3. Check server health reloaderoo inspect ping -- node my-mcp-server.js

🔄Proxy Mode Workflow(Hot-Reload Development)

For full development sessions with AI clients:

Configure your AI client to connect to reloaderoo proxy instead of your server directly:

reloaderoo proxy -- node my-mcp-server.js # or with debug logging: reloaderoo proxy --log-level debug -- node my-mcp-server.js

// my-mcp-server.js export const server = new Server({ name: "my-awesome-server", version: "1.0.0" }); // Add new tools, modify existing ones, etc. server.addTool("new_feature", / ... /);

Ask your AI agent to restart the server:

"Please restart the MCP server to load my changes"

The agent will call therestart_servertool automatically. Your new capabilities are immediately available!

Your AI session continues with the updated server capabilities. No connection loss, no context reset.

reloaderoo provides two primary modes of operation:

reloaderoo [options] [command] Global Options: -V, --version Output the version number -h, --help Display help for command Commands: proxy [options] -- <command> 🔄 Run as MCP proxy server (hot-reload mode) inspect [subcommand] 🔍 Inspect and debug MCP servers (CLI mode) info [options] 📊 Display version and configuration information help [command] ❓ Display help for command

🔄Proxy Mode Commands(Hot-Reload Development)

reloaderoo proxy [options] -- <child-command> [child-args...] Options: -w, --working-dir <directory> Working directory for the child process -l, --log-level <level> Log level (debug, info, notice, warning, error, critical) -f, --log-file <path> Custom log file path (logs to stderr by default) -t, --restart-timeout <ms> Timeout for restart operations (default: 30000ms) -m, --max-restarts <number> Maximum restart attempts 0-10 (default: 3) -d, --restart-delay <ms> Delay between restart attempts (default: 1000ms) -q, --quiet Suppress non-essential output --no-auto-restart Disable automatic restart on crashes --debug Enable debug mode with verbose logging --dry-run Validate configuration without starting proxy Examples: reloaderoo proxy -- node server.js reloaderoo -- node server.js # Same as above (proxy is default) reloaderoo proxy --log-level debug -- python mcp_server.py --port 8080

🔍CLI Mode Commands(Inspection & Testing)

reloaderoo inspect [subcommand] [options] -- <child-command> [child-args...] Subcommands: server-info [options] Get server information and capabilities list-tools [options] List all available tools call-tool [options] <name> Call a specific tool list-resources [options] List all available resources read-resource [options] <uri> Read a specific resource list-prompts [options] List all available prompts get-prompt [options] <name> Get a specific prompt ping [options] Check server connectivity mcp [options] Start MCP inspection server (exposes debug tools as MCP server) Common Options (available for all subcommands): -w, --working-dir <dir> Working directory for the child process -t, --timeout <ms> Operation timeout in milliseconds (default: 30000) -q, --quiet Suppress child process stderr output (get clean JSON) Examples: reloaderoo inspect list-tools -- node server.js reloaderoo inspect call-tool get_weather --params '{"location": "London"}' -- node server.js reloaderoo inspect server-info -- node server.js reloaderoo inspect mcp -- node server.js # Start MCP inspection server # Get clean JSON output without server logs reloaderoo inspect list-tools --quiet -- node server.js reloaderoo inspect call-tool echo --quiet --params '{"message":"test"}' -- node server.js

reloaderoo info [options] Options: --verbose Show detailed system information Examples: reloaderoo info # Show basic system information reloaderoo info --verbose # Show detailed diagnostics

🔍 CLI Mode Deep Dive (Inspection & Testing)

CLI mode provides direct command-line access to MCP servers without requiring client setup - perfect for testing and debugging.

🤖AI Agent Use Case- The Primary Design Goal

CLI mode is specifically designed for AI agents(like Claude Code, Cursor, etc.) that have terminal access but don't have MCP server configuration capabilities. This solves a critical development workflow problem:

The Problem:When an AI agent is helping you develop an MCP server, it needs to test changes, but:

- ❌ The agent can't configure itself to use your MCP server directly
- ❌ Asking users to manually configure MCP clients breaks the development flow
- ❌ Using resource tools or web fetching is indirect and limited

The Solution:CLI mode gives AI agents direct, terminal-based access to your MCP server:

- ✅No Client Configuration: Agent uses terminal commands, not MCP client setup
- ✅Stateless & Reliable: Each command runs independently - no persistent connections to fail
- ✅Raw Protocol Access: Agent sees exact MCP inputs/outputs for transparent debugging
- ✅Immediate Testing: Agent can validate changes instantly without user intervention

- Each CLI command spawns the server, executes the request, and terminates
- Perfect reliability - no persistent state to get corrupted
- No connection management or session handling complexity

- Servers with in-memory state machines won't work properly in CLI mode
- Each command is isolated - no shared state between calls
- For stateful servers, use Proxy mode instead

- Raw JSON output shows exact MCP protocol requests/responses
- No proxy layer or client interpretation
- Perfect for understanding what's actually happening at the protocol level
- Use--quietflag to suppress server logs and get clean JSON for scripting

📝Direct CLI Commands(One-shot execution)

Execute single commands and get immediate results:

# List all tools in your server reloaderoo inspect list-tools -- node my-server.js # Call a specific tool reloaderoo inspect call-tool echo --params '{"message":"hello"}' -- node my-server.js # Get server information reloaderoo inspect server-info -- node my-server.js # Check server connectivity reloaderoo inspect ping -- node my-server.js # Get clean JSON output without server logs (perfect for scripting) reloaderoo inspect list-tools --quiet -- node my-server.js reloaderoo inspect call-tool echo --quiet --params '{"message":"hello"}' -- node my-server.js

🔧MCP Inspection Server(Persistent CLI mode for MCP clients)

Start CLI mode as a persistent MCP server for interactive debugging:

# Start reloaderoo in CLI mode as an MCP server reloaderoo inspect mcp -- node my-server.js

This runs CLI mode as a persistent MCP server, exposing 8 debug tools through the MCP protocol:

- list_tools- List all server tools
- call_tool- Call any server tool
- list_resources- List all server resources
- read_resource- Read any server resource
- list_prompts- List all server prompts
- get_prompt- Get any server prompt
- get_server_info- Get comprehensive server info
- ping- Test server connectivity

🔄Proxy Mode Architecture(Hot-Reload Development)

graph LR A[AI Client] -->|MCP Protocol| B[reloaderoo proxy] B -->|Forwards Messages| C[Your MCP Server] B -->|Manages Lifecycle| C B -->|Adds restart_server Tool| A style A fill:#e1f5fe style B fill:#f3e5f5 style C fill:#e8f5e8

- Transparent Forwarding- All MCP messages pass through seamlessly
- Capability Augmentation- Addsrestart_servertool to your server's capabilities
- Process Management- Spawns, monitors, and restarts your server process
- Session Persistence- Client connection remains active during server restarts
- Protocol Compliance- Full MCP v2025-03-26 support with intelligent fallbacks

🔍CLI Mode Architecture(Direct Testing)

graph LR A[Your Terminal] -->|Direct Commands| B[reloaderoo inspect] B -->|Spawns & Queries| C[Your MCP Server] B -->|Returns JSON| A style A fill:#e8f5e8 style B fill:#f3e5f5 style C fill:#e1f5fe

- Direct Execution- No proxy layer, direct command execution
- One-Shot Queries- Each command spawns server, executes, and returns results
- Raw JSON Output- Perfect for automation and scripting
- No Client Setup- Test MCP servers without configuring MCP clients
- 8 Inspection Commands- Complete MCP protocol coverage for testing

Configure reloaderoo behavior via environment variables:

# Logging Configuration export MCPDEV_PROXY_LOG_LEVEL=debug # Log level (debug, info, notice, warning, error, critical) export MCPDEV_PROXY_LOG_FILE=/path/to/log # Custom log file path (default: stderr) export MCPDEV_PROXY_DEBUG_MODE=true # Enable debug mode (true/false) # Process Management export MCPDEV_PROXY_RESTART_LIMIT=5 # Maximum restart attempts (0-10, default: 3) export MCPDEV_PROXY_AUTO_RESTART=true # Enable/disable auto-restart (true/false) export MCPDEV_PROXY_TIMEOUT=30000 # Operation timeout in milliseconds export MCPDEV_PROXY_RESTART_DELAY=1000 # Delay between restart attempts in milliseconds export MCPDEV_PROXY_CWD=/path/to/directory # Default working directory

🔄Proxy Mode Integration(MCP Client Setup)

Configure your MCP client to connect to reloaderoo proxy instead of your server directly:

{ "mcpServers": { "my-dev-server": { "command": "reloaderoo", "args": [ "proxy", "--", "node", "my-dev-server.js" ] } } }

🔍CLI Mode Integration(Automation & Testing)

Perfect for CI/CD, testing scripts, and automation workflows:

#!/bin/bash # Example: Test script for your MCP server # Check if server is healthy (use --quiet for clean output) if reloaderoo inspect ping --quiet -- node my-server.js >/dev/null 2>&1; then echo "✅ Server is healthy" else echo "❌ Server health check failed" exit 1 fi # Test specific functionality with clean JSON output echo "Testing echo tool..." result=$(reloaderoo inspect call-tool echo --quiet --params '{"message":"test"}' -- node my-server.js) # Parse and validate JSON response (no server logs to interfere) if echo "$result" | jq -e '.content[0].text' >/dev/null; then echo "✅ Echo tool test passed" echo "Response: $(echo "$result" | jq -r '.content[0].text')" else echo "❌ Echo tool test failed" echo "Raw response: $result" exit 1 fi # List tools and count them echo "Checking available tools..." tools_count=$(reloaderoo inspect list-tools --quiet -- node my-server.js | jq '.tools | length') echo "✅ Found $tools_count tools available"

# Check if your server runs independently first node my-dev-server.js # Then try with reloaderoo proxy to validate configuration reloaderoo proxy -- node my-dev-server.js

# Enable debug logging to see what's happening reloaderoo proxy --log-level debug -- node my-server.js # Check system info and configuration reloaderoo info --verbose

# Increase restart timeout reloaderoo proxy --restart-timeout 60000 -- node my-server.js # Check restart limits reloaderoo proxy --max-restarts 5 -- node my-server.js

# Test basic connectivity first reloaderoo inspect ping -- node my-server.js # Enable debug logging for CLI commands reloaderoo inspect list-tools --log-level debug -- node my-server.js

# Use --raw flag to see unformatted output reloaderoo inspect server-info --raw -- node my-server.js # Ensure your server outputs valid JSON node my-server.js | head -10

# Get detailed information about what's happening reloaderoo proxy --debug -- node my-server.js # For proxy mode reloaderoo inspect list-tools --log-level debug -- node my-server.js # For CLI mode # View system diagnostics reloaderoo info --verbose

We welcome contributions! Please seeCONTRIBUTING.mdfor guidelines.

git clone https://github.com/cameroncooke/reloaderoo.git cd reloaderoo npm install npm run build npm test

npm run test # All tests (unit, integration, E2E) npm run test:unit # Unit tests only npm run test:integration # Integration tests only npm run test:e2e # End-to-end tests only npm run test:coverage # Test coverage report

Testing Guidelines:Seedocs/TESTING_GUIDELINES.mdfor comprehensive testing standards and best practices.