@chinchillaenterprises/mcp-dev-logger 2.0.2 → 2.3.0

package/README.md

@@ -1,19 +1,41 @@
-# MCP Dev Logger
+# MCP Dev Logger v2.3.0
 
-A Model Context Protocol (MCP) server for capturing and streaming development server output. Perfect for monitoring `npm run dev`, `yarn dev`, `pnpm dev`, or any other development server commands across all frameworks (Next.js, Vite, Create React App, etc.).
+A Model Context Protocol (MCP) server for capturing and streaming development server output with browser console logging, enhanced organization, and automatic cleanup. Perfect for monitoring `npm run dev`, `yarn dev`, `pnpm dev`, or any other development server commands across all frameworks (Next.js, Vite, Create React App, etc.).
+
+## 🎉 New in v2.3.0
+
+- **One-Click Student Workflow**: New `dev_start_frontend_with_browser` tool that starts server AND launches browser automatically
+- **Smart Port Detection**: Automatically detects which port your dev server is using
+- **Server Ready Detection**: Waits for server to be fully ready before launching browser
+- **Simplified Teaching**: Reduces student setup from 3 commands to just 1
+
+## Previous Features (v2.2.0)
+
+- **Browser Console Capture**: Capture browser console.log, console.error, and other console outputs alongside server logs
+- **Unified Log Stream**: See both server-side and client-side logs in one place
+- **Student-Friendly Browser**: TEST BROWSER with visual indicators for teaching
+
+## Previous Features (v2.1.0)
+
+- **Organized Log Structure**: Logs are now organized by process type (frontend/backend/amplify/custom)
+- **Automatic Cleanup**: Keeps only the last 3 days of logs to prevent disk space issues
+- **Improved File Naming**: Cleaner log file names without redundant prefixes
 
 ## Features
 
 - **Universal Dev Server Logging**: Works with any development server command
+- **Browser Console Capture**: Capture console.log, console.error, console.warn from the browser
 - **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
+- **Organized Log Storage**: Structured as `logs/YYYY-MM-DD/processType/logfile.log`
+- **Automatic Log Cleanup**: Removes logs older than 3 days automatically
 - **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
+- **Unified Server + Browser Logs**: See both frontend and backend logs in one stream
 
 ## Installation
 
@@ -122,6 +144,86 @@ Clear the log file.
 - `processId` (optional): Process ID to clear logs for (smart fallback for single process)
 - `backup` (optional): Whether to backup logs before clearing (default: false)
 
+### 8. dev_launch_test_browser
+Launch a TEST BROWSER for students to interact with. All console logs from this browser are captured automatically. Students should use THIS browser (not their regular browser) to test their app.
+
+**Parameters:**
+- `processId` (optional): Process ID to attach browser console to
+- `browserUrl` (optional): URL to open in test browser (default: http://localhost:3000)
+- `teachingMode` (optional): Enable teaching mode with DevTools open and slower actions (default: true)
+- `viewport` (optional): Browser window size (default: { width: 1280, height: 800 })
+- `highlightErrors` (optional): Add visual indicator when console errors occur (default: true)
+
+**Key Features:**
+- 🪟 Always visible browser window (not headless)
+- 🔍 DevTools automatically open in teaching mode
+- 🐌 Slower actions for easier teaching/learning
+- ⚡ Red flash on console errors
+- 📝 Green banner showing "TEST BROWSER" status
+- 🎯 All console logs captured to the same log file as server logs
+
+**Example:**
+```json
+{
+  "processId": "npm-frontend",
+  "browserUrl": "http://localhost:3000",
+  "teachingMode": true,
+  "highlightErrors": true
+}
+```
+
+### 9. dev_stop_browser_console
+Stop browser console capture for a specific process.
+
+**Parameters:**
+- `processId` (optional): Process ID to stop browser console capture for
+
+### 10. dev_start_frontend_with_browser 🚀 NEW in v2.3.0!
+**ONE-CLICK STUDENT WORKFLOW**: Start frontend server AND automatically launch test browser when ready. Perfect for teaching environments - reduces setup from 3 commands to 1!
+
+**Parameters:**
+- `command` (optional): Dev command to run (default: "npm run dev")
+- `port` (optional): Port to wait for (default: auto-detect from output)
+- `waitTimeout` (optional): Max time to wait for server in ms (default: 30000)
+- `browserDelay` (optional): Delay after server ready in ms (default: 1000)
+- `teachingMode` (optional): Enable teaching features (default: true)
+- `processId` (optional): Custom process ID (default: "frontend-with-browser")
+- `env` (optional): Environment variables
+- `cwd` (optional): Working directory
+
+**Key Features:**
+- 🎯 Automatically detects when server is ready
+- 🪟 Launches test browser with DevTools open
+- 📝 Captures both server AND browser console logs
+- ⚡ Red flash on browser errors
+- 🧪 Green "TEST BROWSER" banner
+- ⏱️ Single command instead of multiple steps
+
+**Example:**
+```json
+{
+  "command": "npm run dev",
+  "teachingMode": true,
+  "processId": "student-project"
+}
+```
+
+**Success Output:**
+```
+✅ Starting development server...
+✅ Server ready on http://localhost:3000
+✅ Launching test browser...
+
+🎯 TEST BROWSER LAUNCHED!
+
+👉 Use the browser window that just opened (with green banner)
+📝 All console logs are being saved
+🔍 DevTools is open for debugging
+⚠️  Errors will flash red on screen
+
+Happy debugging! 🚀
+```
+
 ## Usage Examples
 
 ### Multi-Process Development (v2.0.0)
@@ -191,9 +293,28 @@ dev_restart_log_streaming({
 }
 ```
 
+## Log Organization (v2.1.0+)
+
+Logs are organized in a structured directory hierarchy:
+
+```
+logs/
+├── 2025-07-10/              # Date folder (YYYY-MM-DD)
+│   ├── frontend/            # Process type folder
+│   │   ├── nextjs-14-32-15.log
+│   │   └── vite-16-45-22.log
+│   ├── backend/
+│   │   ├── express-14-33-01.log
+│   │   └── api-15-22-11.log
+│   └── amplify/
+│       └── sandbox-14-35-22.log
+└── 2025-07-09/              # Older logs (auto-removed after 3 days)
+    └── ...
+```
+
 ## Log Format
 
-Logs are written with timestamps, process IDs, and error markers:
+Logs are written with timestamps, process IDs, and error markers. Browser console logs are prefixed with [BROWSER]:
 
 ```
 [2024-01-15T10:30:45.123Z] Starting: npm run dev (Process ID: npm-frontend)
@@ -202,6 +323,11 @@ Logs are written with timestamps, process IDs, and error markers:
 [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:49.123Z] [npm-frontend] [BROWSER] Console capture started for http://localhost:3000
+[2024-01-15T10:30:49.456Z] [npm-frontend] [BROWSER] [LOG] React DevTools detected
+[2024-01-15T10:30:49.789Z] [npm-frontend] [BROWSER] [WARN] React: Each child should have a unique key prop
+[2024-01-15T10:30:50.123Z] [npm-frontend] [BROWSER] [ERROR] Failed to fetch /api/user: 404 Not Found
+[2024-01-15T10:30:50.456Z] [npm-frontend] [BROWSER] [LOG] { user: null, loading: false }
 
 [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...
@@ -262,6 +388,108 @@ dev_start_log_streaming {
 dev_tail_logs { "processId": "amplify-backend", "filter": "ERROR|WARN", "lines": 100 }
 ```
 
+### 6. Student Testing Workflow (v2.2.0)
+```typescript
+// Step 1: Start the student's dev server
+dev_start_log_streaming({
+  "command": "npm run dev",
+  "processId": "student-app"
+})
+
+// Step 2: Launch the TEST BROWSER for the student
+dev_launch_test_browser({
+  "processId": "student-app",
+  "browserUrl": "http://localhost:3000",
+  "teachingMode": true  // DevTools open, slower actions
+})
+
+// Step 3: Tell student: "Use the TEST BROWSER window that just opened!"
+// They click buttons, fill forms, trigger errors - ALL console logs are captured
+
+// Step 4: When student says "I clicked submit and nothing happened"
+dev_tail_logs({ 
+  "processId": "student-app", 
+  "filter": "\\[BROWSER\\].*\\[ERROR\\]", 
+  "lines": 20 
+})
+// Shows: [BROWSER] [ERROR] Cannot read property 'name' of undefined
+
+// Step 5: Show all browser activity
+dev_tail_logs({ 
+  "processId": "student-app", 
+  "filter": "\\[BROWSER\\]", 
+  "lines": 50 
+})
+
+// Step 6: When done testing
+dev_stop_browser_console({ "processId": "student-app" })
+```
+
+**What Students See:**
+- A browser window opens with "🧪 TEST BROWSER" banner
+- DevTools is already open to the Console tab
+- When errors occur, the browser flashes red
+- All their console.log() statements are captured
+- They can debug using the actual browser they're testing in
+
+### Tips for Instructors/TAs:
+1. **Always emphasize**: Students must use the TEST BROWSER, not their regular browser
+2. **Common mistake**: Students open localhost:3000 in their regular Chrome - no logs captured!
+3. **Quick check**: Look for [BROWSER] prefix in logs to confirm they're using test browser
+4. **Teaching moment**: Show how server errors appear without [BROWSER] prefix
+5. **Debugging together**: The red flash makes it easy to spot when errors occur
+
+### 7. Simplified One-Click Workflow (v2.3.0) 🎯
+The new `dev_start_frontend_with_browser` combines steps 1 and 2 above into a single command:
+
+```typescript
+// BEFORE (v2.2.0): Two separate commands
+dev_start_log_streaming({ "command": "npm run dev", "processId": "student-app" })
+// Wait for server to start...
+dev_launch_test_browser({ "processId": "student-app" })
+
+// NOW (v2.3.0): Single command does everything!
+dev_start_frontend_with_browser({
+  "command": "npm run dev",
+  "processId": "student-project",
+  "teachingMode": true
+})
+// Server starts, waits for ready, then browser launches automatically!
+```
+
+**Benefits for Students:**
+- 🚀 One command instead of two
+- ⏱️ No need to wait and guess when server is ready
+- 🎯 Browser launches at the perfect time
+- 📝 All logs in one place from the start
+- 🔧 Less chance for mistakes
+
+**Common Student Scenarios:**
+
+```typescript
+// Scenario 1: React app on default port
+dev_start_frontend_with_browser()
+// That's it! Uses all smart defaults
+
+// Scenario 2: Vite app with custom command
+dev_start_frontend_with_browser({
+  "command": "npm run dev -- --host",
+  "processId": "vite-project"
+})
+
+// Scenario 3: Next.js on different port
+dev_start_frontend_with_browser({
+  "command": "npm run dev",
+  "port": 3001,  // If auto-detect fails
+  "env": { "PORT": "3001" }
+})
+
+// Scenario 4: Quick demo mode (no DevTools)
+dev_start_frontend_with_browser({
+  "teachingMode": false  // Faster, no DevTools
+})
+```
+
 ## Troubleshooting
 
 ### Dev Server Not Starting