@chinchillaenterprises/mcp-dev-logger 1.2.0 → 2.0.1

package/README.md

@@ -5,11 +5,15 @@ A Model Context Protocol (MCP) server for capturing and streaming development se
 ## Features
 
 - **Universal Dev Server Logging**: Works with any development server command
+- **Multi-Process Support**: Run multiple dev servers simultaneously (frontend + backend)
 - **Real-time Log Streaming**: Capture build errors, TypeScript errors, hot reload events
 - **Persistent Logs**: All output saved to file for historical debugging
-- **Process Management**: Start, stop, and restart dev servers
+- **Smart Process Management**: Start, stop, and restart individual dev servers by ID
 - **Log Filtering**: Search through logs with grep patterns
 - **Framework Agnostic**: One tool for all development servers
+- **Auto-Generated Process IDs**: Intelligent process ID generation based on command and output file
+- **Process State Persistence**: Maintains process state across server restarts (where possible)
+- **Signal Handling**: Proper cleanup with SIGTERM for graceful shutdowns
 
 ## Installation
 
@@ -40,11 +44,12 @@ claude mcp add dev-logger-local -s user -- node $(pwd)/dist/index.js
 This prefix pattern applies to all MCP servers and helps Claude distinguish between different servers' tools.
 
 ### 1. dev_start_log_streaming
-Start a development server and stream its output to a log file.
+Start a development server and stream its output to a log file. **Supports multiple concurrent processes.**
 
 **Parameters:**
 - `command` (optional): Dev command to run (default: "npm run dev")
 - `outputFile` (optional): File to write logs to (default: "dev-server-logs.txt")
+- `processId` (optional): Custom process ID (auto-generated if not provided)
 - `cwd` (optional): Working directory
 - `env` (optional): Environment variables to pass
 
@@ -61,50 +66,92 @@ Start a development server and stream its output to a log file.
 }
 ```
 
-### 2. dev_stop_log_streaming
-Stop the running development server and logging.
+### 2. dev_list_processes
+List all running development processes with their status and details.
 
 **No parameters required.**
 
-### 3. dev_restart_log_streaming
-Restart the development server (useful when it crashes or hangs).
+### 3. dev_stop_log_streaming
+Stop development server(s) and logging.
 
 **Parameters:**
+- `processId` (optional): Process ID to stop (if not provided, stops all processes)
+
+### 4. dev_restart_log_streaming
+Restart a specific development server (useful when it crashes or hangs).
+
+**Parameters:**
+- `processId` (required): Process ID to restart
 - `clearLogs` (optional): Whether to clear the log file on restart (default: false)
 
-### 4. dev_get_status
-Check if the development server is running and get its status.
+### 5. dev_get_status
+Check if development server(s) are running and get their status.
+
+**Parameters:**
+- `processId` (optional): Process ID to get status for (if not provided, shows all processes)
 
 **Returns:**
 - Running status
-- Process ID (PID)
+- Process ID(s)
+- PID(s)
 - Uptime
-- Current command
-- Log file location
+- Current command(s)
+- Log file location(s)
 
-### 5. dev_tail_logs
+### 6. dev_tail_logs
 Get the last N lines from the log file.
 
 **Parameters:**
+- `processId` (optional): Process ID to tail logs from (smart fallback for single process)
 - `lines` (optional): Number of lines to return (default: 50)
 - `filter` (optional): Grep pattern to filter logs
 
 **Example:**
 ```json
 {
+  "processId": "npm-frontend",
   "lines": 100,
   "filter": "ERROR"
 }
 ```
 
-### 6. dev_clear_logs
+### 7. dev_clear_logs
 Clear the log file.
 
 **Parameters:**
+- `processId` (optional): Process ID to clear logs for (smart fallback for single process)
 - `backup` (optional): Whether to backup logs before clearing (default: false)
 
 ## Usage Examples
 
+### Multi-Process Development (v2.0.0)
+```typescript
+// Start frontend and backend simultaneously
+dev_start_log_streaming({
+  "command": "npm run dev",
+  "outputFile": "frontend.log",
+  "processId": "frontend"
+})
+
+dev_start_log_streaming({
+  "command": "npx ampx sandbox --stream-function-logs",
+  "outputFile": "backend.log", 
+  "processId": "backend"
+})
+
+// List all running processes
+dev_list_processes()
+
+// Stop just the frontend
+dev_stop_log_streaming({ "processId": "frontend" })
+
+// Restart backend with clean logs
+dev_restart_log_streaming({ 
+  "processId": "backend", 
+  "clearLogs": true 
+})
+```
+
 ### Start Next.js Development Server
 ```typescript
 // Start Next.js dev server
@@ -146,17 +193,27 @@ Clear the log file.
 
 ## Log Format
 
-Logs are written with timestamps and error markers:
+Logs are written with timestamps, process IDs, and error markers:
 
 ```
-[2024-01-15T10:30:45.123Z] Starting: npm run dev
-[2024-01-15T10:30:46.456Z] > my-app@1.0.0 dev
-[2024-01-15T10:30:46.457Z] > next dev
-[2024-01-15T10:30:47.123Z] ▲ Next.js 14.0.0
-[2024-01-15T10:30:47.124Z] - Local: http://localhost:3000
-[2024-01-15T10:30:48.789Z] [ERROR] Error: Cannot find module './components/Header'
+[2024-01-15T10:30:45.123Z] Starting: npm run dev (Process ID: npm-frontend)
+[2024-01-15T10:30:46.456Z] [npm-frontend] > my-app@1.0.0 dev
+[2024-01-15T10:30:46.457Z] [npm-frontend] > next dev
+[2024-01-15T10:30:47.123Z] [npm-frontend] ▲ Next.js 14.0.0
+[2024-01-15T10:30:47.124Z] [npm-frontend] - Local: http://localhost:3000
+[2024-01-15T10:30:48.789Z] [npm-frontend] [ERROR] Error: Cannot find module './components/Header'
+
+[2024-01-15T10:30:50.123Z] Starting: npx ampx sandbox --stream-function-logs (Process ID: npx-backend)
+[2024-01-15T10:30:51.456Z] [npx-backend] [INFO] Amplify sandbox starting...
+[2024-01-15T10:30:52.123Z] [npx-backend] Process exited with code 0 and signal null
 ```
 
+### Process ID Generation
+The server automatically generates intelligent process IDs based on the command and output file:
+- Command: `npm run dev` + Output: `frontend.log` → Process ID: `npm-frontend`
+- Command: `npx ampx sandbox --stream-function-logs` + Output: `backend.log` → Process ID: `npx-backend`
+- Duplicate IDs are automatically suffixed with `-1`, `-2`, etc.
+
 ## Common Use Cases
 
 ### 1. Debugging Build Failures
@@ -192,6 +249,19 @@ dev_start_log_streaming {
 dev_restart_log_streaming { "clearLogs": true }
 ```
 
+### 5. Amplify Development Workflow
+```bash
+# Start Amplify backend logging
+dev_start_log_streaming {
+  "command": "npx ampx sandbox --stream-function-logs",
+  "outputFile": "backend-logs.txt",
+  "processId": "amplify-backend"
+}
+
+# Monitor Lambda function logs
+dev_tail_logs { "processId": "amplify-backend", "filter": "ERROR|WARN", "lines": 100 }
+```
+
 ## Troubleshooting
 
 ### Dev Server Not Starting
@@ -210,12 +280,31 @@ dev_restart_log_streaming { "clearLogs": true }
 2. If that fails, the process may have crashed - check system process manager
 3. Restart Claude Code to clean up orphaned processes
 
+## Implementation Details
+
+### Process Management
+- Uses Node.js `spawn` with `detached: true` for proper process isolation
+- Implements graceful shutdown with SIGTERM signals
+- Automatically removes event listeners on process termination to prevent memory leaks
+- Attempts to kill process groups (`-pid`) to handle child processes
+
+### State Persistence
+- Saves process state to `${tmpdir}/mcp-dev-logger.json`
+- Restores process information on server restart (where possible)
+- Handles process cleanup on server shutdown
+
+### Log Streaming
+- Real-time streaming of both stdout and stderr
+- Timestamped log entries with process ID tagging
+- Error entries are clearly marked with `[ERROR]` prefix
+- Supports concurrent logging from multiple processes to different files
+
 ## Limitations
 
-- Only one dev server can be managed at a time (default instance)
 - Process management is best-effort - some processes may not respond to signals
 - Very large log files may impact performance of `dev_tail_logs`
-- Only captures server-side console output (not browser console logs) - for browser logs, use the Playwright MCP server
+- Only captures server-side console output (not browser console logs)
+- Process state restoration is limited after server restarts (PIDs become invalid)
 
 ## Development