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

A dual-mode MCP development tool that 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.

🔄 Two Modes, One Tool

reloaderoo provides two distinct operational modes to fit different development workflows:

🔍 CLI Mode (Inspection & Testing)

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

🔄 Proxy Mode (Hot-Reload Development)

Transparent proxy server that enables seamless hot-reloading:

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

🎯 Why reloaderoo?

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.

🚀 Quick Start

Installation

# Install globally for easy access
npm install -g reloaderoo

# Or use with npx (no installation required)
npx reloaderoo --help

Choose Your Mode

🔍 CLI Mode - Testing & Debugging

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

🔄 Proxy Mode - Hot-Reload Development

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.

🎯 Recommended Clients

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

🛠️ Development Workflow

🔍 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:

1. Start Development Session

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

2. Develop Your MCP Server

Work on your server code as usual:

// 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", /* ... */);

3. Test Changes Instantly

Ask your AI agent to restart the server:

"Please restart the MCP server to load my changes"

The agent will call the restart_server tool automatically. Your new capabilities are immediately available!

4. Continue Development

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

📋 Command Line Interface

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)

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

Info Command (Diagnostics)

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

🔧 Technical Benefits

Stateless Execution:

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

⚠️ Important Limitation:

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

Transparent Debugging:

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

📝 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

🔧 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

🏗️ How Both Modes Work

🔄 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

Proxy Mode Magic:

Transparent Forwarding - All MCP messages pass through seamlessly
Capability Augmentation - Adds restart_server tool 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

CLI Mode Magic:

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

🔧 Configuration

Environment Variables

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

🎨 Integration Examples

🔄 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
if reloaderoo inspect ping -- node my-server.js; then
  echo "✅ Server is healthy"
else
  echo "❌ Server health check failed"
  exit 1
fi

# Test specific functionality
echo "Testing echo tool..."
result=$(reloaderoo inspect call-tool echo --params '{"message":"test"}' -- node my-server.js)

# Parse and validate JSON response
if echo "$result" | jq -e '.success' >/dev/null; then
  echo "✅ Echo tool test passed"
else
  echo "❌ Echo tool test failed"
  exit 1
fi

🚨 Troubleshooting

🔄 Proxy Mode Issues

Server won't start in proxy mode:

# 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

Connection problems with MCP clients:

# 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

Restart failures in proxy mode:

# Increase restart timeout
reloaderoo proxy --restart-timeout 60000 -- node my-server.js

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

🔍 CLI Mode Issues

CLI commands failing:

# 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

JSON parsing errors:

# 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

General Debug Mode

# 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

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

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

Running Tests

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: See docs/TESTING_GUIDELINES.md for comprehensive testing standards and best practices.

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

XcodeBuildMCP - MCP server for Xcode development workflow automation

Package detail

readme