Skip to main content
Glama
ahao0150

Debug MCP

by ahao0150
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

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

Related MCP server: Debugging MCP Server

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?

  1. Centralized collection: All logs from different parts of your application are collected in one place

  2. Structured data: Logs are stored as JSON with timestamps, levels, and context

  3. AI-friendly: The AI can easily read and analyze logs via the read_debug_logs tool

  4. 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:

  1. 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)

  2. Update MCP config:

    {
  "env": {
    "DEBUG_HOST": "192.168.1.100"  // Your LAN IP
    // Note: Port is automatically assigned, no need to configure DEBUG_PORT
  }
}

  3. Get actual port: After starting the MCP server, use the get_server_port tool to query the actual assigned port

  4. Ensure firewall allows that port (port number queried via get_server_port)

  5. 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:

  1. Analyze the bug using analyze_bug tool

  2. Detect the environment of your files using detect_environment

  3. Get debug template using get_debug_template tool

  4. 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:

  1. Always provide projectPath as the absolute path to the project directory

  2. Use get_debug_template to get HTTP-based logging code (NOT console.log)

  3. Manually insert the debug code at the appropriate location

  4. Explain your hypothesis - what you think might be wrong

  5. Provide clear test steps - exact actions the user should take

  6. State expected results - what should happen if your hypothesis is correct

  7. Ask for feedback - specifically request user to report results

  8. Use read_debug_logs after user tests to analyze actual runtime data

  9. Handle unexpected results - ask follow-up questions when results differ from expectations

  10. Iterate - continue debugging based on data until the issue is resolved

  11. 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

  12. 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:

  1. โŒ Use console.log() - always use the provided HTTP POST templates

  2. โŒ Omit projectPath - logs will go to wrong directory

  3. โŒ Skip explaining your reasoning - user needs to understand your hypothesis

  4. โŒ Forget test steps - user needs clear instructions

  5. โŒ Ignore unexpected results - investigate when things don't work as planned

  6. โŒ Ask "Should I clean up?" when user confirms success - just clean up directly

  7. โŒ 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: analyze_bug and detect_environment

"Based on your description, the possible causes are:

  1. Event listener not attached to the submit button

  2. Form validation preventing submission

  3. 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: get_debug_template with projectPath and inserts the code

// 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:

  1. Restart your React development server

  2. Open the login page in your browser

  3. Fill in any required fields

  4. Click the submit button

  5. 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: get_debug_template again and inserts more debug logs

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

๐Ÿ“‹ Test steps:

  1. Refresh the page

  2. Check if you see a "Login component mounted" log

  3. 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:

  1. Restart the server

  2. Try submitting the form again

  3. 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: clear_debug_logs and searches for all debug markers

"โœ… 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:

  1. โœ… AI always explained its hypothesis before adding code

  2. โœ… AI provided clear, numbered test steps

  3. โœ… AI stated expected results clearly

  4. โœ… AI asked for specific feedback from the user

  5. โœ… AI used read_debug_logs to verify what actually happened

  6. โœ… AI investigated unexpected results (the function name error)

  7. โœ… AI iterated based on data until finding the root cause

  8. โœ… 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

  1. Configure server with LAN IP: DEBUG_HOST=192.168.1.100

  2. 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' })
});

  3. Open your web app on mobile device using: http://192.168.1.100:3000

  4. Test the app on your phone - logs are sent to your computer

  5. 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:

  1. Verify devices are on the same network

  2. Use get_server_port tool to query the actual port

  3. Check firewall settings for that port

  4. Confirm the MCP server is running

  5. Test with curl: curl http://YOUR_IP:PORT/health (PORT is the actual port)

Logs not appearing:

  1. Check the generated code uses the correct URL

  2. Verify projectPath is set correctly

  3. Check browser console for network errors

  4. 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

  1. Use get_server_port tool to query the actual port

  2. Verify the HTTP server is running: curl http://localhost:PORT/health (PORT is the actual port)

  3. Check if the application can reach the server URL

  4. Look for [Debug Log Failed] errors in the application console

Environment detection fails

  1. Manually specify the environment in add_debug_logs

  2. Check that file content is not empty

  3. Verify the file extension matches the environment

Debug code not removed

  1. Ensure // debug-start and // debug-end markers are present

  2. Check file permissions

  3. 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

Available Tools

8 tools
analyze_bugA

Analyze a bug description and provide intelligent suggestions about possible causes, affected files, and debugging strategies. This helps you understand what might be causing the issue before adding debug logs.

ParametersJSON Schema
NameRequiredDescriptionDefault
bugDescriptionYesDetailed description of the bug - what should happen vs what actually happens
filesNoList of relevant file paths (optional, helps provide more targeted analysis)

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It mentions the tool 'helps you understand' but lacks details on behavioral traits such as whether it's read-only, requires specific permissions, has rate limits, or what the response format looks like. The description is vague about how suggestions are generated or their reliability.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with two sentences that are front-loaded and efficient. Every sentence earns its place by stating the tool's purpose and its utility, with no redundant or unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (analysis with 2 parameters) and lack of annotations/output schema, the description is moderately complete. It covers the purpose and usage context but lacks details on behavioral aspects and output expectations, which are important for an analysis tool without structured output documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds no additional meaning beyond what the schema provides, such as examples or constraints on input values. It mentions 'bug description' and 'files' but only repeats schema info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('analyze', 'provide suggestions') and resources ('bug description'), distinguishing it from sibling tools like clear_debug_logs or read_debug_logs. It explicitly mentions outputs like 'possible causes, affected files, and debugging strategies'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('before adding debug logs'), but does not explicitly state when not to use it or name alternatives among siblings. It implies usage for preliminary analysis rather than direct debugging actions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

clear_debug_logsA

Clear all debug logs from the project log file. Use this before starting a new debugging session to avoid confusion from old logs.

ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project directory

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It indicates a destructive action ('Clear all debug logs'), which is useful context, but lacks details on permissions needed, whether the operation is reversible, or potential side effects (e.g., impact on system performance). The description adds some value but does not fully compensate for the absence of annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences that are front-loaded with the core purpose and followed by usage guidance, with zero wasted words. Each sentence earns its place by providing essential information without redundancy or unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a destructive operation with no annotations and no output schema), the description is moderately complete. It covers the purpose and usage context but lacks details on behavioral aspects like error handling or return values, which would be beneficial for a tool that modifies data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the single parameter 'projectPath' documented in the schema as 'The absolute path to the project directory'. The description does not add any additional meaning or context beyond what the schema provides, such as format examples or constraints, so it meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Clear all debug logs') and resource ('from the project log file'), distinguishing it from sibling tools like 'read_debug_logs' and 'list_debug_blocks' that involve reading rather than deletion. It precisely communicates the tool's function without being vague or tautological.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool ('before starting a new debugging session') and why ('to avoid confusion from old logs'), providing clear context for its application. It distinguishes it from alternatives by implying that other tools (e.g., 'read_debug_logs') are for viewing logs, not clearing them.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

detect_environmentA

Automatically detect the runtime environment (browser, node, python, php, react-native, wechat) of a specific file. Use this to determine which debug code template to use.

ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYesAbsolute or relative path to the file to analyze

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It describes the tool's function (detection) and output (environment type), but lacks details on behavioral traits like error handling (e.g., what happens if the file doesn't exist), performance characteristics, or whether it reads file content vs. metadata. The description doesn't contradict annotations (none provided).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose and followed by the usage context. Every word earns its place, with no redundant or vague phrasing, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (environment detection based on a file), no annotations, and no output schema, the description is reasonably complete. It covers the purpose, usage, and possible environments, but could be more complete by detailing the return format (e.g., string enum) or error cases, which are missing from both description and structured data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the single parameter 'filePath' well-documented in the schema. The description doesn't add any parameter-specific information beyond what the schema provides (e.g., file format expectations or analysis depth), so it meets the baseline for high schema coverage without compensating value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('detect the runtime environment') and resource ('of a specific file'), listing the six possible environments (browser, node, python, php, react-native, wechat). It distinguishes from siblings by focusing on environment detection rather than bug analysis, log management, or template retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for usage ('to determine which debug code template to use'), implying this tool should be used before selecting a debug template. However, it doesn't explicitly state when not to use it or name alternatives among siblings, though the purpose naturally differentiates it from tools like analyze_bug or clear_debug_logs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_debug_templateA

Get a debug code template for a specific environment. โš ๏ธ IMPORTANT INSTRUCTIONS FOR AI: 1) DO NOT use console.log() - the generated code uses HTTP POST to send logs to the debug server, 2) ALWAYS provide the projectPath parameter as the absolute path to the project directory (e.g., /path/to/project or process.cwd()), 3) The debug logs will be stored at {projectPath}/.debug/debug.log in the project directory, NOT in the user home directory. After getting the template, manually insert it into the appropriate location in the user's file. โš ๏ธ AFTER INSERTING DEBUG CODE: You MUST inform the user about: 1) What you suspect might be wrong, 2) What specific test steps they should take, 3) What results to expect, 4) How to report back the results. After user tests, use read_debug_logs to analyze the actual runtime data. โš ๏ธ MARKING TEMPORARY MODIFICATIONS: ANY temporary changes for debugging (including visual markers, test images, placeholder text, button label changes, color highlights, etc.) MUST be wrapped with clear comments: "// TEMPORARY DEBUG MARKER - WILL BE REVERTED" at the start and "// END TEMPORARY DEBUG MARKER" at the end. Keep a list of ALL temporary modifications (both debug code AND visual/test changes) and ensure ALL are reverted during cleanup.

ParametersJSON Schema
NameRequiredDescriptionDefault
environmentYesRuntime environment: browser, node, python, php, react-native, wechat
logMessageYesThe log message to describe what is being logged
variablesNoVariable names to include in the log data
projectPathYesโš ๏ธ REQUIRED: The absolute path to the project directory (e.g., /Users/username/project or D:\projects\myproject). This ensures logs are stored in the project directory at {projectPath}/.debug/debug.log, NOT in the user home directory. Use the current working directory of the project being debugged.
levelNoLog level: info, error, debug, warninfo

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains behavioral traits: it's a read-only operation (no destructive effects), requires specific parameter handling (e.g., absolute path for projectPath), outputs a template for manual insertion, and includes detailed post-usage workflows and cleanup requirements. This covers safety, constraints, and operational context effectively.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is overly verbose and includes extensive procedural instructions (e.g., post-insertion user communication, temporary modification marking) that are not core to the tool's purpose. While informative, this bloats the description with content better suited for external documentation, reducing conciseness and front-loading of key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the tool (5 parameters, no output schema, no annotations), the description is highly complete. It covers purpose, usage guidelines, behavioral traits, parameter nuances, and integration with sibling tools like 'read_debug_logs'. It provides all necessary context for an AI agent to use the tool correctly, despite the lack of structured annotations or output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so the baseline is 3. The description adds value by emphasizing the importance of the 'projectPath' parameter with specific instructions and warnings, and it implicitly clarifies the purpose of 'environment' and 'logMessage' through usage context. However, it doesn't provide additional semantics for all parameters beyond the schema's details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose: 'Get a debug code template for a specific environment.' It specifies the verb ('Get') and resource ('debug code template'), and distinguishes it from sibling tools like 'read_debug_logs' by focusing on template generation rather than log analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage instructions, including when to use it (for generating debug templates), when not to use it (e.g., not for direct logging with console.log()), and alternatives like 'read_debug_logs' for analyzing results. It also outlines prerequisites and post-usage steps, such as manual insertion and user communication.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_server_infoA

Get debug MCP server configuration, HTTP endpoints, and supported environments. Use this first to verify the server is running correctly.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It implies a read-only operation ('Get') but doesn't disclose behavioral traits like authentication needs, rate limits, or response format. However, it adds context about verifying server status, which is useful but not comprehensive for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with two sentences that efficiently convey the tool's function and recommended usage without any wasted words, making it easy for an agent to quickly understand its role.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (0 parameters, no annotations, no output schema), the description is complete enough for a diagnostic tool. It explains what the tool does and when to use it, though it could benefit from more behavioral details like response format, but this is mitigated by the simple nature of the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0 parameters and 100% schema description coverage, the baseline is 4. The description adds value by explaining the tool's purpose and usage context, which compensates for the lack of parameters, making it clear that no inputs are required for this diagnostic check.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('Get') and resources ('debug MCP server configuration, HTTP endpoints, and supported environments'), distinguishing it from siblings like 'analyze_bug' or 'clear_debug_logs' by focusing on server-level diagnostic information rather than bug analysis or log management.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit guidance on when to use this tool ('Use this first to verify the server is running correctly'), suggesting it as an initial diagnostic step, which helps differentiate it from alternatives like 'detect_environment' or 'get_server_port' that might serve more specific purposes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_server_portA

Get the current HTTP server port and URL information. The port is dynamically assigned by the system to avoid conflicts. Use this to get the actual port number and endpoints for sending debug logs.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it explains that the port is 'dynamically assigned by the system to avoid conflicts,' which is crucial operational context not inferable from the schema alone. However, it lacks details on response format or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by behavioral context and usage guidance in just two sentences, with zero wasted words. Every sentence earns its place by adding essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (0 parameters, no output schema), the description is nearly complete: it covers purpose, behavioral traits, and usage context effectively. A minor gap is the lack of output details, but this is acceptable without an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage, so the baseline is high. The description adds value by explaining why parameters are unnecessary (port is dynamically assigned) and the tool's purpose, compensating for the lack of parameter documentation needs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('Get') and resources ('current HTTP server port and URL information'), and distinguishes it from siblings by focusing on port/URL retrieval rather than debugging analysis or log management.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use this tool ('to get the actual port number and endpoints for sending debug logs'), providing clear context for its application in debugging workflows, which differentiates it from sibling tools like get_server_info or list_debug_blocks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_debug_blocksA

List all debug blocks (code between debug-start and debug-end markers) in project files. Use this to see what debug code has been injected.

ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project directory to scan

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states what the tool does but doesn't describe important behavioral traits like whether it's read-only, what format the output returns, whether it scans recursively, error handling, or performance characteristics. For a tool with zero annotation coverage, this leaves significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise with two sentences that each earn their place: the first defines the tool's purpose and scope, the second provides usage guidance. No wasted words, front-loaded with the core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (scanning project files for specific markers), no annotations, and no output schema, the description is adequate but incomplete. It explains what the tool does but lacks details about output format, scanning behavior, or error conditions that would be needed for full contextual understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the single parameter 'projectPath' well-documented in the schema. The description doesn't add any parameter-specific information beyond what the schema provides, so it meets the baseline of 3 where schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('List all debug blocks') and resource ('in project files'), with explicit definition of what debug blocks are ('code between debug-start and debug-end markers'). It distinguishes from siblings by focusing on listing injected debug code rather than analysis, clearing, reading logs, or other operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('to see what debug code has been injected'), which implicitly differentiates it from siblings like clear_debug_logs or read_debug_logs. However, it doesn't explicitly state when NOT to use it or name specific alternatives, keeping it from a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_debug_logsA

Read debug logs from the project. Logs are stored in {projectPath}/.debug/debug.log. Use this to analyze what happened during runtime execution after the user has tested the code with injected debug logs. โš ๏ธ IMPORTANT: If the user confirms the bug is FIXED (e.g., says "It works!", "Fixed!", "Success!", "Thanks!"), you should immediately: 1) Use clear_debug_logs to clear the log file, 2) Remove ALL debug code blocks (search for DEBUG CODE START/END markers), 3) Revert ALL temporary visual/test markers (search for "TEMPORARY DEBUG MARKER" comments), 4) Restore original code (button labels, images, styles, colors, etc.), 5) Confirm cleanup is complete. Do NOT ask for confirmation - just clean up directly when user confirms success.

ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesThe absolute path to the project directory where logs are stored
lastLinesNoNumber of most recent log lines to retrieve (default: 100)

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It effectively describes the tool's behavior: reading from a specific file path, being used for post-test analysis, and triggering cleanup workflows. It mentions important constraints (user confirmation triggers cleanup) and integration with other tools. However, it doesn't address potential error conditions or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is poorly structured and overly verbose. The first two sentences describe the tool's purpose appropriately, but the remaining 80% consists of cleanup instructions that belong in usage guidelines rather than tool description. This creates information overload and buries the core purpose. The cleanup section should be more concise or separated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read operation with 2 parameters and 100% schema coverage but no output schema, the description is moderately complete. It explains the tool's purpose and usage context well, but lacks information about return format (log structure, error responses). The extensive cleanup instructions somewhat compensate for missing output schema, but create focus issues.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters completely. The description mentions the projectPath parameter in context ('Logs are stored in {projectPath}/.debug/debug.log') but adds no additional semantic meaning beyond what the schema provides. The baseline of 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Read debug logs from the project' with specific resource location '{projectPath}/.debug/debug.log'. It distinguishes from siblings like 'clear_debug_logs' by focusing on reading rather than clearing. However, it doesn't explicitly differentiate from 'list_debug_blocks' or 'analyze_bug' which might also involve log analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidelines: 'Use this to analyze what happened during runtime execution after the user has tested the code with injected debug logs.' It also specifies when NOT to use it (when bugs are fixed) and names an alternative tool ('clear_debug_logs') for cleanup operations. The detailed cleanup instructions create clear boundaries for when this tool's purpose ends.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 8 tool updates
    • First observedanalyze_bug
    • First observedclear_debug_logs
    • First observeddetect_environment
    • First observedget_debug_template
    • First observedget_server_info
    • First observedget_server_port
    • First observedlist_debug_blocks
    • First observedread_debug_logs
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: analyze_bug for bug analysis, clear_debug_logs for log cleanup, detect_environment for environment detection, get_debug_template for code templates, get_server_info for server configuration, get_server_port for port details, list_debug_blocks for listing debug code, and read_debug_logs for log analysis. The descriptions reinforce unique functions, preventing misselection.

Naming Consistency5/5

All tools follow a consistent verb_noun naming pattern (e.g., analyze_bug, clear_debug_logs, detect_environment), using snake_case throughout. This predictability makes the tool set easy to navigate and understand, with no deviations in style or convention.

Tool Count5/5

With 8 tools, the server is well-scoped for debugging support, covering essential aspects like analysis, environment detection, template generation, log management, and server configuration. Each tool serves a specific role, avoiding bloat while providing comprehensive coverage for the domain.

Completeness5/5

The tool set offers complete coverage for a debugging workflow: from initial bug analysis and environment detection to injecting debug code, managing logs, and cleaning up. It includes both proactive (e.g., get_debug_template) and reactive (e.g., read_debug_logs) tools, with no obvious gaps that would hinder an agent's ability to debug effectively.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Error Debugging MCP Server

    firozanam
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides intelligent error detection and debugging capabilities across multiple programming languages with real-time monitoring of build, lint, runtime, console, and test errors. Offers AI-enhanced error analysis with automated resolution suggestions and context-aware debugging.
    MIT

  • Debugging MCP Server

    luischang07
    F
    license
    A
    quality
    D
    maintenance
    Enables LLMs to automatically diagnose coding errors through codebase search, test execution, and live debugger integration (DAP/V8 CDP). Provides a secure, policy-gated environment for investigating failures while preventing destructive operations.
    9
    -

  • Log Diagnosis MCP Server

    suxiao1228
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI to automatically diagnose bugs by querying logs, tracing call chains, and analyzing code across multiple log platforms like Elasticsearch and Loki.
    MIT

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ahao0150/debug-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server