Skip to content

RELOADEROO.md

Latest commit

 

History

History
446 lines (327 loc) · 14.1 KB

RELOADEROO.md

File metadata and controls

446 lines (327 loc) · 14.1 KB

Reloaderoo Integration Guide

This guide explains how to use Reloaderoo v1.1.2+ for testing and developing XcodeBuildMCP with both CLI inspection tools and transparent proxy capabilities.

Overview

Reloaderoo is 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). It provides two distinct operational modes for different development workflows.

Installation

Reloaderoo is available via npm and can be used with npx for universal compatibility.

# Use npx to run reloaderoo (works on any system)
npx reloaderoo@latest --help

# Or install globally if preferred
npm install -g reloaderoo
reloaderoo --help

Two Operational Modes

🔍 CLI Mode (Inspection & Testing)

Direct command-line access to MCP servers without client setup - perfect for testing and debugging:

Key Benefits:

  • ✅ 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
  • ✅ AI agent friendly - Designed for terminal-based AI development workflows

Basic Commands:

# List all available tools
npx reloaderoo@latest inspect list-tools -- node build/index.js

# Call any tool with parameters  
npx reloaderoo@latest inspect call-tool <tool_name> --params '<json>' -- node build/index.js

# Get server information
npx reloaderoo@latest inspect server-info -- node build/index.js

# List available resources
npx reloaderoo@latest inspect list-resources -- node build/index.js

# Read a specific resource
npx reloaderoo@latest inspect read-resource "<uri>" -- node build/index.js

# List available prompts
npx reloaderoo@latest inspect list-prompts -- node build/index.js

# Get a specific prompt
npx reloaderoo@latest inspect get-prompt <name> --args '<json>' -- node build/index.js

# Check server connectivity
npx reloaderoo@latest inspect ping -- node build/index.js

Example Tool Calls:

# List connected devices
npx reloaderoo@latest inspect call-tool list_devices --params '{}' -- node build/index.js

# Get doctor information
npx reloaderoo@latest inspect call-tool doctor --params '{}' -- node build/index.js

# List iOS simulators
npx reloaderoo@latest inspect call-tool list_sims --params '{}' -- node build/index.js

# Read devices resource
npx reloaderoo@latest inspect read-resource "xcodebuildmcp://devices" -- node build/index.js

🔄 Proxy Mode (Hot-Reload Development)

Transparent MCP proxy server that enables seamless hot-reloading during development:

Key Benefits:

  • ✅ 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
  • ✅ Process management - Spawns, monitors, and restarts your server process

Usage:

# Start proxy mode (your AI client connects to this)
npx reloaderoo@latest proxy -- node build/index.js

# With debug logging
npx reloaderoo@latest proxy --log-level debug -- node build/index.js

# Then in your AI session, request:
# "Please restart the MCP server to load my latest changes"

The AI agent will automatically call the restart_server tool, preserving your session while reloading code changes.

MCP Inspection Server Mode

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

# Start reloaderoo in CLI mode as an MCP server
npx reloaderoo@latest inspect mcp -- node build/index.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 information
  • ping - Test server connectivity

Claude Code Compatibility

When running under Claude Code, XcodeBuildMCP automatically detects the environment and consolidates multiple content blocks into single responses with --- separators.

Automatic Detection Methods:

  1. Environment Variables: CLAUDECODE=1 or CLAUDE_CODE_ENTRYPOINT=cli
  2. Parent Process Analysis: Checks if parent process contains 'claude'
  3. Graceful Fallback: Falls back to environment variables if process detection fails

No Configuration Required: The consolidation happens automatically when Claude Code is detected.

Command Reference

Command Structure

npx reloaderoo@latest [options] [command]

Two modes, one tool:
• Proxy MCP server that adds support for hot-reloading MCP servers.
• CLI tool for inspecting MCP servers.

Global Options:
  -V, --version    Output the version number
  -h, --help       Display help for command

Commands:
  proxy [options]  🔄 Run as MCP proxy server (default behavior)
  inspect          🔍 Inspect and debug MCP servers
  info [options]   📊 Display version and configuration information
  help [command]   ❓ Display help for command

🔄 Proxy Mode Commands

npx reloaderoo@latest 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:
  npx reloaderoo proxy -- node build/index.js
  npx reloaderoo -- node build/index.js                    # Same as above (proxy is default)
  npx reloaderoo proxy --log-level debug -- node build/index.js

🔍 CLI Mode Commands

npx reloaderoo@latest 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

Examples:
  npx reloaderoo@latest inspect list-tools -- node build/index.js
  npx reloaderoo@latest inspect call-tool list_devices --params '{}' -- node build/index.js
  npx reloaderoo@latest inspect server-info -- node build/index.js

Info Command

npx reloaderoo@latest info [options]

Options:
  -v, --verbose                    Show detailed information
  -h, --help                       Display help for command
  
Examples:
  npx reloaderoo@latest info              # Show basic system information
  npx reloaderoo@latest info --verbose    # Show detailed system information

Response Format

All CLI commands return structured JSON:

{
  "success": true,
  "data": {
    // Command-specific response data
  },
  "metadata": {
    "command": "call-tool:list_devices",
    "timestamp": "2025-07-25T08:32:47.042Z",
    "duration": 1782
  }
}

Error Handling

When commands fail, you'll receive:

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  },
  "metadata": {
    "command": "failed-command",
    "timestamp": "2025-07-25T08:32:47.042Z",
    "duration": 100
  }
}

Development Workflow

🔍 CLI Mode Workflow (Testing & Debugging)

Perfect for testing individual tools or debugging server issues without MCP client setup:

# 1. Build XcodeBuildMCP
npm run build

# 2. Test your server quickly
npx reloaderoo@latest inspect list-tools -- node build/index.js

# 3. Call specific tools to verify behavior
npx reloaderoo@latest inspect call-tool list_devices --params '{}' -- node build/index.js

# 4. Check server health and resources
npx reloaderoo@latest inspect ping -- node build/index.js
npx reloaderoo@latest inspect list-resources -- node build/index.js

🔄 Proxy Mode Workflow (Hot-Reload Development)

For full development sessions with AI clients that need persistent connections:

1. Start Development Session

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

npx reloaderoo@latest proxy -- node build/index.js
# or with debug logging:
npx reloaderoo@latest proxy --log-level debug -- node build/index.js

2. Develop Your MCP Server

Work on your XcodeBuildMCP code as usual - make changes, add tools, modify functionality.

3. Test Changes Instantly

# Rebuild your changes
npm run build

# Then ask your AI agent to restart the server:
# "Please restart the MCP server to load my latest 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.

🛠️ MCP Inspection Server (Interactive CLI Debugging)

For interactive debugging through MCP clients:

# Start reloaderoo CLI mode as an MCP server
npx reloaderoo@latest inspect mcp -- node build/index.js

# Then connect with an MCP client to access debug tools
# Available tools: list_tools, call_tool, list_resources, etc.

Troubleshooting

🔄 Proxy Mode Issues

Server won't start in proxy mode:

# Check if XcodeBuildMCP runs independently first
node build/index.js

# Then try with reloaderoo proxy to validate configuration
npx reloaderoo@latest proxy -- node build/index.js

Connection problems with MCP clients:

# Enable debug logging to see what's happening
npx reloaderoo@latest proxy --log-level debug -- node build/index.js

# Check system info and configuration
npx reloaderoo@latest info --verbose

Restart failures in proxy mode:

# Increase restart timeout
npx reloaderoo@latest proxy --restart-timeout 60000 -- node build/index.js

# Check restart limits  
npx reloaderoo@latest proxy --max-restarts 5 -- node build/index.js

🔍 CLI Mode Issues

CLI commands failing:

# Test basic connectivity first
npx reloaderoo@latest inspect ping -- node build/index.js

# Enable debug logging for CLI commands (via proxy debug mode)
npx reloaderoo@latest proxy --log-level debug -- node build/index.js

JSON parsing errors:

# Check server information for troubleshooting
npx reloaderoo@latest inspect server-info -- node build/index.js

# Ensure your server outputs valid JSON
node build/index.js | head -10

General Issues

Command not found:

# Ensure npx can find reloaderoo
npx reloaderoo@latest --help

# If that fails, try installing globally
npm install -g reloaderoo

Parameter validation:

# Ensure JSON parameters are properly quoted
npx reloaderoo@latest inspect call-tool list_devices --params '{}' -- node build/index.js

General Debug Mode

# Get detailed information about what's happening
npx reloaderoo@latest proxy --debug -- node build/index.js  # For proxy mode
npx reloaderoo@latest proxy --log-level debug -- node build/index.js  # For detailed proxy logging

# View system information
npx reloaderoo@latest info --verbose

Debug Tips

  1. Always build first: Run npm run build before testing
  2. Check tool names: Use inspect list-tools to see exact tool names
  3. Validate JSON: Ensure parameters are valid JSON strings
  4. Enable debug logging: Use --log-level debug or --debug for verbose output
  5. Test connectivity: Use inspect ping to verify server communication

Advanced Usage

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

Custom Working Directory

npx reloaderoo@latest proxy --working-dir /custom/path -- node build/index.js
npx reloaderoo@latest inspect list-tools --working-dir /custom/path -- node build/index.js

Timeout Configuration

npx reloaderoo@latest proxy --restart-timeout 60000 -- node build/index.js

Integration with XcodeBuildMCP

Reloaderoo is specifically configured to work with XcodeBuildMCP's:

  • 84+ Tools: All workflow groups accessible via CLI
  • 4 Resources: Direct access to devices, simulators, environment, swift-packages
  • Claude Code Detection: Automatic consolidation of multiple content blocks
  • Hot-Reload Support: Seamless development workflow with restart_server

For more information about XcodeBuildMCP's architecture and capabilities, see: