MCP Rewatch

# MCP Rewatch A Model Context Protocol (MCP) server that enables AI coding assistants like Claude Code to manage long-running development processes. Without this tool, Claude Code cannot run commands like `npm run dev` because it will block waiting for the process to complete and eventually timeout without seeing any output. ## The Problem When using Claude Code for development, you hit a fundamental limitation: ```bash # What happens when Claude Code tries to run a dev server: $ npm run dev > my-app@1.0.0 dev > next dev ▲ Next.js 14.0.0 - Local: http://localhost:3000 [Claude Code is now stuck here, waiting for the process to exit] [After ~2 minutes, it times out without seeing any output] [Claude Code never sees compilation errors, success messages, or any logs] ``` **Claude Code cannot:** - ❌ See any output from long-running processes - ❌ Know if a dev server started successfully - ❌ Check for compilation errors - ❌ Restart servers after making changes - ❌ Run multiple dev processes simultaneously This makes it nearly impossible to develop effectively with Claude Code, as you need to manually run all dev servers and restart them after changes. ## The Solution MCP Rewatch acts as a bridge between Claude Code and your development processes: - **Runs processes in the background** - Claude Code doesn't block - **Captures all output** - stdout/stderr saved in memory buffers - **Provides async access** - Claude Code can check logs anytime - **Enables restarts** - Claude Code can restart servers after making changes - **Manages multiple processes** - Run frontend, backend, database servers together ## How It Works MCP Rewatch acts as an intermediary between Claude Code and your development processes: 1. **Runs as a separate service** that Claude Code can communicate with via MCP 2. **Manages processes independently** - starts your dev servers as child processes 3. **Non-blocking operations** - Claude Code can start/restart processes and immediately continue 4. **Async log retrieval** - Claude Code can check logs later without blocking 5. **Handles lifecycle properly** - graceful shutdown, no orphaned processes This architecture allows Claude Code to effectively manage long-running processes despite its inherent limitation of not being able to run them directly. ## Installation Install globally via npm: ```bash npm install -g mcp-rewatch ``` Or use directly with npx (no installation needed): ```bash npx mcp-rewatch ``` ## Configuration Create a `rewatch.config.json` file in your project root (where you'll be running Claude Code): The `startupDelay` should be tuned based on your specific processes: - Fast tools (scripts, small servers): 1000-2000ms - Next.js/React dev servers: 3000-5000ms - Heavy build processes: 5000-10000ms - Services with dependencies: 8000-15000ms ```json { "processes": { "convex": { "command": "pnpm", "args": ["dlx", "convex", "dev"], "cwd": "./", "startupDelay": 5000 }, "nextjs": { "command": "pnpm", "args": ["dev"], "cwd": "./", "env": { "PORT": "3000" }, "startupDelay": 4000 }, "backend": { "command": "npm", "args": ["run", "dev"], "cwd": "./backend", "env": { "NODE_ENV": "development", "PORT": "8080" }, "startupDelay": 2000 } } } ``` ### Configuration Options - **command**: The executable to run (e.g., `npm`, `pnpm`, `node`) - **args**: Array of command arguments - **cwd**: Working directory for the process (relative to where MCP server runs, i.e., your project root) - **env**: Additional environment variables (optional) - **startupDelay**: Time in milliseconds to wait after starting before checking status (default: 3000) - **readyPattern**: (Not implemented yet - see roadmap) ## Usage with Claude Code ### Quick Start (Single Project) 1. Add MCP Rewatch to Claude Code: ```bash # Using npx (no installation needed) claude mcp add rewatch npx -- mcp-rewatch # Or if installed globally claude mcp add rewatch mcp-rewatch # Or for local development claude mcp add rewatch node -- /path/to/mcp-rewatch/dist/index.js ``` 2. Create `rewatch.config.json` in your project root 3. Start Claude Code from your project directory - MCP Rewatch will look for the config in the current working directory ### User-Scoped Setup (Global Access) To make MCP Rewatch available in all Claude Code sessions: ```bash claude mcp add -s user rewatch npx -- mcp-rewatch ``` **Important**: The server looks for `rewatch.config.json` in the current working directory where Claude Code is running. Each project needs its own config file. ### Managing Multiple Projects **How it works**: MCP Rewatch looks for `rewatch.config.json` in the current working directory where Claude Code is running. **Best practices**: 1. **Keep configs project-specific**: Each project should have its own `rewatch.config.json` 2. **Use relative paths**: In your config, use relative `cwd` paths like `"./backend"` or `"./frontend"` 3. **Launch Claude Code from project root**: Always start Claude Code from your project directory **Example multi-service config**: ```json { "processes": { "frontend": { "command": "npm", "args": ["run", "dev"], "cwd": "./frontend" }, "backend": { "command": "npm", "args": ["run", "dev"], "cwd": "./backend" }, "database": { "command": "docker", "args": ["compose", "up", "postgres"], "cwd": "./" } } } ``` ## Available Tools Once configured, Claude Code can use these tools: ### `restart_process` Stop and restart a development process by name. Waits for the configured `startupDelay` (or 3 seconds by default), then returns initial logs. ```typescript await restart_process({ name: "nextjs" }) // Output: // Process 'nextjs' started successfully // // Initial logs: // [2024-01-07T10:00:01.123Z] [stdout] > my-app@1.0.0 dev // [2024-01-07T10:00:01.456Z] [stdout] > next dev // [2024-01-07T10:00:02.789Z] [stdout] ▲ Next.js 14.0.0 // [2024-01-07T10:00:03.012Z] [stdout] - Local: http://localhost:3000 ``` ### `get_process_logs` Retrieve logs from a process, optionally limiting the number of lines. ```typescript await get_process_logs({ name: "nextjs", lines: 50 }) // Returns last 50 lines of logs from the Next.js process await get_process_logs({ name: "convex" }) // Returns all available logs from the Convex process ``` ### `list_processes` List all configured processes and their current status. ```typescript await list_processes() // Output: // nextjs: running (PID: 12345) // convex: stopped ``` ### `stop_all` Stop all running processes gracefully. ```typescript await stop_all() // Output: "All processes stopped" ``` ## Typical Workflow Here's how Claude Code uses MCP Rewatch during development: 1. **Initial setup** (done once by you): - Create `rewatch.config.json` in your project - Start Claude Code - servers can be started on demand 2. **During development** Claude Code will: - Make code changes to your files - Call `restart_process({ name: "nextjs" })` to restart the server - **Automatically receive initial logs** after a 3-second startup delay - Check the logs for success indicators or errors - Continue with more changes based on the results - Call `get_process_logs({ name: "nextjs" })` later if needed 3. **Key benefits**: - Claude Code never gets blocked by long-running processes - You don't need to manually restart servers after every change - Claude Code can verify changes worked by checking logs - Multiple servers can be managed in parallel ### How It Works When `restart_process` is called: 1. **Stops** any existing process with that name 2. **Starts** the new process 3. **Waits** for the configured `startupDelay` (default: 3 seconds) 4. **Returns** the startup status and initial logs This gives Claude Code immediate feedback about whether: - The process started successfully - There were immediate errors (port conflicts, missing deps) - The server is beginning to compile/build For ongoing monitoring, Claude Code can use `get_process_logs` to check progress later. ## Why This Matters Without MCP Rewatch, the development flow with Claude Code is frustrating: - ❌ Claude Code tries `npm run dev` → blocks and times out - ❌ You make changes → servers break → manual restart needed - ❌ No way to check if changes compiled successfully With MCP Rewatch: - ✅ Claude Code uses `restart_process` → returns immediately - ✅ Servers restart automatically after changes - ✅ Claude Code can check logs to verify success ## Troubleshooting - **Processes not starting**: Check that `rewatch.config.json` exists in your project root - **Permission errors**: Ensure the commands in your config have proper execution permissions - **Can't find tools**: Verify MCP Rewatch appears in Claude Code's MCP menu - **Logs not appearing**: Processes might be buffering output; some servers need specific flags to disable buffering ## Development To contribute to MCP Rewatch: ```bash git clone https://github.com/brennancheung/mcp-rewatch.git cd mcp-rewatch pnpm install pnpm build ``` For development, you can point Claude Code directly to the built output: ```bash # Build the project pnpm build # Add to Claude Code claude mcp add rewatch-dev node -- /path/to/mcp-rewatch/dist/index.js ``` Then create a `rewatch.config.json` in whatever directory you're testing from.