Debug MCP

An intelligent debugging assistant built on the Model Context Protocol (MCP) that helps automate the debugging process by analyzing bugs, injecting debug logs via HTTP, and iteratively fixing issues based on real-time feedback.

Key Features

🔍 Automated Bug Analysis: Analyzes bug descriptions and suggests possible causes
🌐 Multi-Environment Support: Automatically detects and adapts to different runtime environments
📝 HTTP-Based Logging: Sends debug logs via HTTP POST to a centralized server (NOT console.log)
🔄 Iterative Debugging: Continues debugging based on user feedback until the issue is resolved
🧹 Auto Cleanup: Removes all debug code automatically after the bug is fixed
📊 Project-Scoped Logs: Logs are stored per-project in {projectPath}/.debug/debug.log

How It Works

⚠️ Important: This MCP server does NOT use console.log(). Instead, it injects code that sends logs via HTTP POST to a local debug server. The logs are then stored in your project directory at {projectPath}/.debug/debug.log.

Why HTTP-Based Logging?

Centralized collection: All logs from different parts of your application are collected in one place
Structured data: Logs are stored as JSON with timestamps, levels, and context
AI-friendly: The AI can easily read and analyze logs via the read_debug_logs tool
Project-scoped: Logs are stored in your project directory, not scattered across console outputs

Supported Environments

Environment	Description
Browser	Web applications using fetch API
Node.js	Server-side Node.js (18+) with native fetch
Node.js Legacy	Older Node.js versions using http module
React Native	Mobile apps using React Native
Electron (Main)	Electron main process (direct file write)
Electron (Renderer)	Electron renderer process (IPC)
WeChat Mini Program	WeChat/Alipay mini programs (wx.request)
PHP	Server-side PHP (curl)
Python	Server-side Python (requests library)
Java	Server-side Java using DebugHttpClient utility
Android	Android apps with thread-safe network requests
Kotlin	Kotlin applications with coroutine support
Objective-C	iOS/macOS applications using NSURLSession

Installation

# Clone the repository git clone https://gitee.com/UPUP0326/debug-mcp.git cd debug-mcp # Install dependencies npm install # Build the project npm run build # Start the server npm start

Configuration

Port Configuration (Optional)

Important: The HTTP server port is now automatically assigned by the system. No manual configuration is needed. Each MCP instance automatically gets an available port to avoid port conflicts.

If you need to use a fixed port (not recommended), you can set it in environment variables:

# HTTP Server Port (optional, auto-assigned by default) # If set, this port will be used; if not set, system automatically assigns an available port DEBUG_PORT=37373 # HTTP Server Host (default: localhost) # Use '0.0.0.0' to accept connections from any device on your network # Use your LAN IP (e.g., '192.168.1.100') to allow other devices to send logs DEBUG_HOST=localhost # Examples: # DEBUG_HOST=0.0.0.0 # Accept connections from any device # DEBUG_HOST=192.168.1.100 # Your computer's LAN IP # DEBUG_HOST=localhost # Only local connections (default) # Log file path (relative to project directory) LOG_FILE=.debug/debug.log

Get Actual Port: Use the get_server_port MCP tool to query the currently assigned port and URL.

Quick Start Guide

Step 1: Start the MCP Server

npm start

The server will start:

MCP Server: Listening on stdio for AI communication
HTTP API Server: Automatically assigned an available port for debug logs (port info can be queried via get_server_port tool)

Step 2: Configure MCP Client

Cursor IDE Configuration

In Cursor, MCP server configuration is in settings. Open Cursor settings, find the MCP configuration section, and add:

{ "mcpServers": { "debug-mcp": { "command": "node", "args": ["E:/work/debug-mcp/dist/index.js"], "env": { "DEBUG_HOST": "localhost" } } } }

Note:

Replace E:/work/debug-mcp/dist/index.js with your actual path
Port is automatically assigned, no need to configure DEBUG_PORT
For cross-device debugging, set DEBUG_HOST to 0.0.0.0 or your LAN IP

Claude Desktop Configuration

In Claude Desktop, the config file location:

Windows: %APPDATA%\Claude\claude_desktop_config.json
Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Add the following configuration:

{ "mcpServers": { "debug-mcp": { "command": "node", "args": ["E:/work/debug-mcp/dist/index.js"], "env": { "DEBUG_HOST": "localhost" } } } }

Note:

Replace E:/work/debug-mcp/dist/index.js with your actual path
Port is automatically assigned, no need to configure DEBUG_PORT
For cross-device debugging, set DEBUG_HOST to 0.0.0.0 or your LAN IP

Cross-Device Debugging Setup:

To enable debugging from mobile devices or other computers on your network:

Find your LAN IP:
- Windows: ipconfig → look for "IPv4 Address" (e.g., 192.168.1.100)
- Mac/Linux: ifconfig or ip addr → look for "inet" (e.g., 192.168.1.100)
Update MCP config:
{ "env": { "DEBUG_HOST": "192.168.1.100" // Your LAN IP // Note: Port is automatically assigned, no need to configure DEBUG_PORT } }
Get actual port: After starting the MCP server, use the get_server_port tool to query the actual assigned port
Ensure firewall allows that port (port number queried via get_server_port)
Devices can now send logs to http://192.168.1.100:PORT/api/log (PORT is the actual assigned port)

Step 3: Use with AI

When debugging, simply describe the bug to the AI. The AI will:

Analyze the bug using analyze_bug tool
Detect the environment of your files using detect_environment
Get debug template using get_debug_template tool
Manually insert the debug code into your files

Important for AI:

⚠️ DO NOT use console.log() - use the template code which sends logs via HTTP POST
⚠️ ALWAYS provide projectPath as the absolute path to the project directory
The debug code sends logs to the dynamically assigned server URL (use get_server_port tool to get the actual URL)
For cross-device debugging, the URL will use the configured DEBUG_HOST and automatically assigned port
Logs are stored at {projectPath}/.debug/debug.log

Example Workflow

User: "My login button doesn't work when I click it" AI Process: 1. analyze_bug("Login button doesn't work") → Returns: Possible causes (event listener, API error, validation) 2. detect_environment("src/components/Login.js") → Returns: "browser" 3. get_debug_template( environment="browser", logMessage="Login button clicked", variables=["username", "password"], projectPath="/path/to/project" ) → Returns: HTTP-based debug code (NOT console.log) 4. AI inserts the debug code into Login.js manually ⚠️ CRITICAL STEP - AI informs the user: 💭 My hypothesis: The button's click event listener might not be attached properly. 📋 Test steps: 1. Restart your application 2. Navigate to the login page 3. Click the login button 4. Check if anything happens ✅ Expected results: You should see the button click logged in the debug system 📢 Please report back: Did the button respond? Any error messages in console? 5. User tests and reports: "Nothing happened when I clicked" 6. read_debug_logs(projectPath="/path/to/project") → Returns: No log entries for button click 7. AI analyzes: "Since we don't see the button click log, the event listener isn't firing. Let me add more logs to check if the component mounted..." 8. [Repeat debugging cycle with targeted hypotheses] 9. User reports: "Now I see the log! But getting 401 error" 10. AI analyzes logs and suggests: "The 401 error indicates authentication failed. Let me check the API request format..." 11. [Continue until bug is fixed]

Key AI Behaviors

When using this MCP server, the AI should follow this pattern:

✅ DO:

Always provide projectPath as the absolute path to the project directory
Use get_debug_template to get HTTP-based logging code (NOT console.log)
Manually insert the debug code at the appropriate location
Explain your hypothesis - what you think might be wrong
Provide clear test steps - exact actions the user should take
State expected results - what should happen if your hypothesis is correct
Ask for feedback - specifically request user to report results
Use read_debug_logs after user tests to analyze actual runtime data
Handle unexpected results - ask follow-up questions when results differ from expectations
Iterate - continue debugging based on data until the issue is resolved
Auto-cleanup on success - When user says "It works!", "Fixed!", "Success!", etc., IMMEDIATELY:
- Use clear_debug_logs to wipe the log file
- Remove all debug code blocks (search for DEBUG CODE START/END markers)
- Revert ALL temporary visual/test markers (search for TEMPORARY DEBUG MARKER comments)
- Restore original code (button labels, images, styles, colors, etc.)
- DO NOT ask "Should I clean up?" - just do it directly
Track ALL modifications - Keep a list of every change:
- Debug code blocks (HTTP POST logs)
- Visual markers (test images, button text changes, color highlights)
- Style modifications (CSS changes for testing)
- Any other temporary changes

❌ DON'T:

❌ Use console.log() - always use the provided HTTP POST templates
❌ Omit projectPath - logs will go to wrong directory
❌ Skip explaining your reasoning - user needs to understand your hypothesis
❌ Forget test steps - user needs clear instructions
❌ Ignore unexpected results - investigate when things don't work as planned
❌ Ask "Should I clean up?" when user confirms success - just clean up directly
❌ Forget temporary visual markers - ALL test changes must be reverted

Available MCP Tools

get_server_info

Get server configuration, HTTP endpoints, and supported environments.

{}

get_server_port

Get the current HTTP server port and URL information. The port is automatically assigned by the system. Use this tool to query the actual assigned port number and complete server URL.

{}

Returns:

port: Currently assigned port number
host: Server host address
url: Complete log endpoint URL
baseUrl: Server base URL
endpoints: All available API endpoints

Use Cases:

When you need to know the actual port number
For cross-device debugging, need to inform other devices of the URL
To verify the server has started correctly

analyze_bug

Analyze a bug description and get intelligent suggestions about possible causes.

{ "bugDescription": "Login button doesn't respond when clicked", "files": ["login.js", "auth.js"] }

detect_environment

Automatically detect the runtime environment of a file.

{ "filePath": "src/components/Login.js" }

Returns: Environment type (browser, node, python, etc.) with confidence level

get_debug_template

Get debug code template for a specific environment. This is the main tool for adding debug logs.

{ "environment": "browser", "logMessage": "Login button clicked", "variables": ["username", "password"], "projectPath": "/Users/username/my-project", "level": "info" }

⚠️ IMPORTANT:

The returned code uses HTTP POST, NOT console.log()
projectPath is REQUIRED - use the absolute path to your project directory
DO NOT modify the generated code to use console.log()
Manually insert the code into your file at the appropriate location

Example returned code:

// ==================== DEBUG CODE START ==================== // ⚠️ DO NOT REPLACE WITH console.log() // This code sends logs via HTTP POST to the debug server // ==================== DEBUG CODE START ==================== fetch('http://localhost:PORT/api/log', { // PORT is auto-assigned, use get_server_port tool to query method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ projectPath: '/Users/username/my-project', timestamp: new Date().toISOString(), level: 'info', message: 'Login button clicked', data: { username, password } }) }).catch(err => console.error('[Debug Log Failed]', err)); // ==================== DEBUG CODE END ====================

read_debug_logs

Read debug logs from the project.

{ "projectPath": "/Users/username/my-project", "lastLines": 100 }

Returns: Array of log entries with timestamps, levels, messages, and data

list_debug_blocks

List all debug blocks (code between debug-start and debug-end markers) in project files.

{ "projectPath": "/Users/username/my-project" }

clear_debug_logs

Clear all debug logs from the project log file.

{ "projectPath": "/Users/username/my-project" }

Complete Debugging Session Example

Here's a complete example of how a debugging session should flow:

Initial Problem Report

User: "My React app's login form isn't submitting. When I click the submit button, nothing happens."

Step 1: Analysis Phase

AI: Let me analyze this issue and check your environment.

Uses:

"Based on your description, the possible causes are:

Event listener not attached to the submit button
Form validation preventing submission
Submit handler function has an error

I've detected you're using a Browser environment with React."

Step 2: First Debug Code Injection

AI: I'll add a log to check if the button click event is firing.

Uses:

// AI inserts this into handleSubmit function fetch('http://localhost:PORT/api/log', { // PORT is auto-assigned, use get_server_port tool to query method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ projectPath: '/Users/john/my-app', timestamp: new Date().toISOString(), level: 'info', message: 'Submit button clicked', data: { formData, isValid } }) }).catch(err => console.error('[Debug Log Failed]', err));

Step 3: AI Provides Test Instructions

AI: 💭 My hypothesis: The submit button's click handler might not be attached, or there's an early return preventing the handler from executing.

📋 Test steps:

Restart your React development server
Open the login page in your browser
Fill in any required fields
Click the submit button
Check the browser console for any errors

✅ Expected results: If the handler is working, you should see a debug log entry indicating the button was clicked.

📢 Please report back: What happened when you clicked? Did you see any console errors?

Step 4: User Reports Back

User: "I clicked the button but nothing happened. No errors in console though."

Step 5: AI Analyzes Logs

AI: Let me check the debug logs to see what was captured.

Uses: `read_debug_logs(projectPath="/Users/john/my-app")

"I don't see any log entries for the button click. This confirms the click handler isn't being called at all."

Step 6: Second Iteration

AI: The event listener isn't firing. Let me add a log to check if the component is mounting correctly, and also verify the event handler is attached.

Uses:

AI: 💭 New hypothesis: The component might not be mounting, or the JSX might have an error with the event handler binding.

📋 Test steps:

Refresh the page
Check if you see a "Login component mounted" log
Try clicking submit again

✅ Expected results: You should see the component mount log, which will tell us if the component loaded.

Step 7: User Provides Unexpected Results

User: "I see the mount log! But when I click submit, I get 'handleSubmit is not defined' in the console."

Step 8: AI Investigates Unexpected Result

AI: Ah! That's very helpful. The error "handleSubmit is not defined" means the function isn't being properly bound or imported. Let me check your component code...

[AI reads the file and identifies the issue]

"I found the problem! You have onClick={handleSubmit} but the function is defined as const handleLoginSubmit = (...). The names don't match. Let me fix that."

Step 9: Resolution

AI: I'll correct the function name in your JSX.

[AI fixes the code]

💡 Root cause: Function name mismatch - JSX references handleSubmit but the actual function is named handleLoginSubmit

📋 Final test steps:

Restart the server
Try submitting the form again
Verify it works correctly

✅ Expected results: The form should now submit successfully!

Step 10: Auto-Cleanup (Including Visual Markers)

User: "It works! Thanks!"

AI: [Detects success confirmation and reviews all modifications]

Great! Let me clean up all debug code and temporary changes right away.

Uses:

"✅ All debug logs have been cleared

✅ Debug code removed from:

src/components/Login.js (lines 15-25) - HTTP POST logs
src/api/auth.js (lines 42-50) - HTTP POST logs

✅ Temporary visual markers reverted:

src/components/Login.js - Button label changed from 'TEST-LOGIN' back to 'Login'
src/styles/button.css - Background color changed from 'red' back to 'blue'
src/assets/test-image.png - Removed test image reference

Your app is now clean and ready to go!"

Key Improvements in This Example:

✅ AI always explained its hypothesis before adding code
✅ AI provided clear, numbered test steps
✅ AI stated expected results clearly
✅ AI asked for specific feedback from the user
✅ AI used read_debug_logs to verify what actually happened
✅ AI investigated unexpected results (the function name error)
✅ AI iterated based on data until finding the root cause
✅ AI auto-cleaned immediately when user confirmed success - NO asking "Should I clean up?"

Success Detection Triggers

AI should auto-cleanup when user says:

✅ "It works!"
✅ "Fixed!"
✅ "Success!"
✅ "Great!"
✅ "Thanks!"
✅ "Perfect!"
✅ "That solved it"
✅ "Working now"

AI should continue debugging when user says:

❌ "Still not working"
❌ "Same error"
❌ "Didn't help"
❌ "Nothing changed"
❌ "Getting a different error"

Temporary Modification Marking

When making ANY temporary changes for debugging purposes, you MUST mark them clearly for cleanup:

Types of Temporary Changes

1. Debug Code (Automatic)

Already wrapped in DEBUG CODE START/END markers:

// ==================== DEBUG CODE START ==================== fetch('http://localhost:PORT/api/log', { // PORT is auto-assigned, use get_server_port tool to query ... }); // ==================== DEBUG CODE END ====================

2. Visual/Test Markers (Manual - MUST ADD)

Button text changes:

// TEMPORARY DEBUG MARKER - WILL BE REVERTED <button>TEST-LOGIN</button> // Changed from "Login" // END TEMPORARY DEBUG MARKER

Test images:

// TEMPORARY DEBUG MARKER - WILL BE REVERTED <img src="/test-debug-image.png" alt="Testing visibility" /> // END TEMPORARY DEBUG MARKER

Color highlights:

/* TEMPORARY DEBUG MARKER - WILL BE REVERTED */ .button { background-color: red; } /* Changed from blue */ /* END TEMPORARY DEBUG MARKER */

Placeholder text:

// TEMPORARY DEBUG MARKER - WILL BE REVERTED const label = "DEBUG MODE - Button at top"; // Changed from "Submit" // END TEMPORARY DEBUG MARKER

Test flags:

// TEMPORARY DEBUG MARKER - WILL BE REVERTED const isDebugging = true; // Will be removed // END TEMPORARY DEBUG MARKER

Cleanup Checklist

When user confirms success, check and revert:

✅ Debug Code:

Search for DEBUG CODE START and remove all blocks
Clear debug logs using clear_debug_logs

✅ Visual Markers:

Search for TEMPORARY DEBUG MARKER comments
Revert button labels to original
Remove test images
Restore original colors/styles
Remove placeholder text
Delete test flags/variables

✅ Verify:

App looks and behaves exactly as before debugging
No debug-related comments left
No test assets referenced

Cross-Device Debugging

Debug mobile apps and other devices on your network by configuring the server host.

When to Use Cross-Device Debugging

📱 Mobile Web Apps: Debug mobile browsers from your development machine
📲 React Native Apps: Test on physical devices while capturing logs
🌐 Multiple Devices: Test your web app on phones, tablets, and computers simultaneously
🏠 Local Network Testing: Test on devices without deploying to production

Setup Guide

1. Find Your Computer's LAN IP

Windows:

ipconfig

Look for "IPv4 Address" → e.g., 192.168.1.100

Mac/Linux:

ifconfig | grep "inet " | grep -v 127.0.0.1 # or ip addr show | grep "inet " | grep -v 127.0.0.1

Look for "inet" → e.g., 192.168.1.100

2. Configure MCP Server

Update your MCP client config:

{ "mcpServers": { "debug-mcp": { "command": "node", "args": ["D:/work/debug-mcp/dist/index.js"], "env": { "DEBUG_HOST": "192.168.1.100" // Your LAN IP // Note: Port is automatically assigned, no need to configure DEBUG_PORT } } } }

Or use 0.0.0.0 to accept connections from any device:

{ "env": { "DEBUG_HOST": "0.0.0.0" // Note: Port is automatically assigned, no need to configure DEBUG_PORT } }

3. Configure Firewall (if needed)

Windows:

# Use get_server_port tool to get actual port, then replace PORT netsh advfirewall firewall add rule name="Debug MCP" dir=in action=allow protocol=TCP localport=PORT

Mac/Linux:

# Usually not needed, but if you have a firewall: # Use get_server_port tool to get actual port, then replace PORT sudo ufw allow PORT/tcp

4. Test Connection

From another device on your network:

# Use get_server_port tool to get actual port, then replace PORT curl http://192.168.1.100:PORT/health

Should return: {"status":"ok"}

Usage Example

Scenario: Debugging a mobile web app

Configure server with LAN IP: DEBUG_HOST=192.168.1.100
AI generates debug code with the correct URL:
// Use get_server_port tool to get actual port, then replace PORT fetch('http://192.168.1.100:PORT/api/log', { method: 'POST', body: JSON.stringify({ message: 'Button clicked' }) });
Open your web app on mobile device using: http://192.168.1.100:3000
Test the app on your phone - logs are sent to your computer
AI reads logs from your computer: read_debug_logs(projectPath="/path/to/project")

Host Configuration Options

DEBUG_HOST Value	Description	Use Case
`localhost`	Only local connections	Default, local debugging
`0.0.0.0`	Accept from any device	Flexible testing
`192.168.1.100`	Your specific LAN IP	Explicit, recommended for mobile
`127.0.0.1`	Localhost only	Same as localhost

Troubleshooting

Cannot connect from mobile device:

Verify devices are on the same network
Use get_server_port tool to query the actual port
Check firewall settings for that port
Confirm the MCP server is running
Test with curl: curl http://YOUR_IP:PORT/health (PORT is the actual port)

Logs not appearing:

Check the generated code uses the correct URL
Verify projectPath is set correctly
Check browser console for network errors
Ensure the device can reach your computer

HTTP API Endpoints

The debug server runs an HTTP API server on an automatically assigned port. Use the get_server_port MCP tool to query the actual port and URL.

POST /api/log

Receives debug log entries from running applications.

Example:

# Use get_server_port tool to query actual port, then replace PORT curl -X POST http://localhost:PORT/api/log \ -H "Content-Type: application/json" \ -d '{ "projectPath": "/path/to/project", "timestamp": "2025-01-03T10:30:00Z", "level": "info", "message": "Login button clicked", "data": { "username": "test", "isLoggedIn": false } }'

GET /api/log

Retrieves debug logs.

# Use get_server_port tool to query actual port, then replace PORT curl http://localhost:PORT/api/log?last=100&projectPath=/path/to/project

DELETE /api/log

Clears all debug logs.

# Use get_server_port tool to query actual port, then replace PORT curl -X DELETE http://localhost:PORT/api/log?projectPath=/path/to/project

GET /api/stats

Gets log statistics.

# Use get_server_port tool to query actual port, then replace PORT curl http://localhost:PORT/api/stats?projectPath=/path/to/project

GET /health

Health check endpoint.

# Use get_server_port tool to query actual port, then replace PORT curl http://localhost:PORT/health

Environment-Specific Examples

Browser / Node.js (18+)

// Uses fetch API fetch('http://localhost:PORT/api/log', { // PORT is auto-assigned, use get_server_port tool to query method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ projectPath: '/path/to/project', timestamp: new Date().toISOString(), level: 'info', message: 'Debug message', data: { variable1, variable2 } }) }).catch(err => console.error('[Debug Log Failed]', err));

Node.js Legacy (v14-17)

// Uses http module const http = require('http'); const data = JSON.stringify({ projectPath: '/path/to/project', timestamp: new Date().toISOString(), level: 'info', message: 'Debug message', data: { variable1, variable2 } }); // Use get_server_port tool to get actual port, then replace PORT const req = http.request('http://localhost:PORT/api/log', { method: 'POST', headers: { 'Content-Type': 'application/json' } }); req.write(data); req.end();

Python

import requests from datetime import datetime try: requests.post( 'http://localhost:PORT/api/log', # PORT is auto-assigned, use get_server_port tool json={ 'projectPath': '/path/to/project', 'timestamp': datetime.now().isoformat(), 'level': 'info', 'message': 'Debug message', 'data': {'variable1': variable1, 'variable2': variable2} }, timeout=0.1 ) except Exception: pass # Silent fail to not break main logic

PHP

$logData = json_encode([ 'projectPath' => '/path/to/project', 'timestamp' => date('c'), 'level' => 'info', 'message' => 'Debug message', 'data' => ['variable1' => $variable1, 'variable2' => $variable2] ]); // Use get_server_port tool to get actual port, then replace PORT $ch = curl_init('http://localhost:PORT/api/log'); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $logData); curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']); curl_setopt($ch, CURLOPT_TIMEOUT_MS, 100); curl_exec($ch); curl_close($ch);

WeChat Mini Program

wx.request({ url: 'http://localhost:PORT/api/log', // PORT is auto-assigned, use get_server_port tool method: 'POST', data: { projectPath: '/path/to/project', timestamp: new Date().toISOString(), level: 'info', message: 'Debug message', data: { variable1, variable2 } }, fail: (err) => console.error('[Debug Log Failed]', err) });

Java

// Requires DebugHttpClient.java utility class // The tool will automatically detect if the utility exists and guide you to add it try { DebugHttpClient.sendLog( "http://localhost:PORT/api/log", // PORT is auto-assigned, use get_server_port tool "Debug message", new java.util.HashMap<String, Object>() {{ put("variable1", variable1); put("variable2", variable2); }}, "info" ); } catch (Exception e) { // Silent fail - do not interrupt main logic }

Android

// Android: Network requests must be executed in a background thread if (android.os.Looper.getMainLooper().getThread() == Thread.currentThread()) { // We are on the main thread, execute in background thread new Thread(() -> { try { DebugHttpClient.sendLog( "http://localhost:PORT/api/log", // PORT is auto-assigned, use get_server_port tool "Debug message", new java.util.HashMap<String, Object>() {{ put("variable1", variable1); put("variable2", variable2); }}, "info" ); } catch (Exception e) { // Silent fail } }).start(); } else { // Already in background thread, execute directly try { DebugHttpClient.sendLog( "http://localhost:PORT/api/log", // PORT is auto-assigned, use get_server_port tool "Debug message", new java.util.HashMap<String, Object>() {{ put("variable1", variable1); put("variable2", variable2); }}, "info" ); } catch (Exception e) { // Silent fail } }

Kotlin

// Kotlin: Use coroutines for async network requests (Android) or direct call (Java) try { // For Android: Use coroutine scope // CoroutineScope(Dispatchers.IO).launch { // DebugHttpClient.sendLog(...) // } // For standard Java: Direct call DebugHttpClient.sendLog( "http://localhost:PORT/api/log", // PORT is auto-assigned, use get_server_port tool "Debug message", mapOf("variable1" to variable1, "variable2" to variable2), "info" ) } catch (e: Exception) { // Silent fail - do not interrupt main logic }

Objective-C (iOS/macOS)

// Use get_server_port tool to get actual port, then replace PORT NSURL *url = [NSURL URLWithString:@"http://localhost:PORT/api/log"]; NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url]; [request setHTTPMethod:@"POST"]; [request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"]; [request setTimeoutInterval:0.1]; NSDateFormatter *formatter = [[NSDateFormatter alloc] init]; [formatter setDateFormat:@"yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"]; [formatter setTimeZone:[NSTimeZone timeZoneWithName:@"UTC"]]; NSString *timestamp = [formatter stringFromDate:[NSDate date]]; NSDictionary *logData = @{ @"timestamp": timestamp, @"level": @"info", @"message": @"Debug message", @"data": @{@"variable1": variable1, @"variable2": variable2} }; NSError *error; NSData *jsonData = [NSJSONSerialization dataWithJSONObject:logData options:0 error:&error]; if (jsonData) { [request setHTTPBody:jsonData]; NSURLSessionDataTask *task = [[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) { // Silent fail - do not interrupt main logic }]; [task resume]; }

Backup Files

Before modifying any file, the tool creates a backup:

original.js.backup.1704288000000

These backups can be used to restore files if needed.

Troubleshooting

Debug logs not appearing

Use get_server_port tool to query the actual port
Verify the HTTP server is running: curl http://localhost:PORT/health (PORT is the actual port)
Check if the application can reach the server URL
Look for [Debug Log Failed] errors in the application console

Environment detection fails

Manually specify the environment in add_debug_logs
Check that file content is not empty
Verify the file extension matches the environment

Debug code not removed

Ensure // debug-start and // debug-end markers are present
Check file permissions
Use list_debug_blocks to see what will be removed

Architecture

src/ ├── index.ts # Entry point (MCP + HTTP servers) ├── mcp/ │ └── tools.ts # MCP tool implementations ├── http/ │ ├── server.ts # HTTP API server │ └── log-handler.ts # Log file management ├── tools/ │ ├── analyze.ts # Bug analysis │ ├── injector.ts # Debug code injection │ ├── cleanup.ts # Debug code removal │ └── test-steps.ts # Test step generation ├── adapters/ │ ├── index.ts # Environment adapters │ └── detector.ts # Environment detection └── utils/ ├── parser.ts # Code parsing (AST) └── file.ts # File operations

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT