Skip to content

DEBUG.md

Latest commit

 

History

History
155 lines (108 loc) · 4.11 KB

DEBUG.md

File metadata and controls

155 lines (108 loc) · 4.11 KB

SpecPilot Debug and Logging

SpecPilot MCP Server provides safe debugging capabilities that don't interfere with the MCP protocol.

The MCP Logging Problem

MCP servers communicate via stdin/stdout using JSON messages. Any console.log() or console.error() output disrupts this communication and causes "Failed to parse message" warnings in AI tools like Claude Code.

Safe Debugging Solutions

1. File-Based Debug Logging (Recommended)

Enable file-based logging that doesn't interfere with MCP protocol:

# Enable debug logging to file
SPECPILOT_DEBUG=true SPECROOT=/your/project/path npx specpilot-mcp-server

# Custom log file location
SPECPILOT_DEBUG=true SPECPILOT_DEBUG_FILE=/path/to/debug.log SPECROOT=/your/project/path npx specpilot-mcp-server

# Set log level (0=DEBUG, 1=INFO, 2=WARN, 3=ERROR)
SPECPILOT_DEBUG=true SPECPILOT_LOG_LEVEL=1 SPECROOT=/your/project/path npx specpilot-mcp-server

2. Monitoring Debug Logs

Watch the debug log in real-time:

# Default log location
tail -f .specpilot-debug.log

# Custom log location
tail -f /path/to/your/debug.log

3. Environment Variables

Variable Default Description
SPECPILOT_DEBUG false Enable/disable debug logging
SPECPILOT_DEBUG_FILE .specpilot-debug.log Debug log file path
SPECPILOT_LOG_LEVEL 0 (DEBUG) Minimum log level (0-3)

Debug Log Format

When enabled, the debug log contains structured information:

[2025-01-15T10:30:45.123Z] DEBUG: 🔧 [TSD-GENERATE] Tool called with parameters: {
  "tool": "tsd-generate",
  "parameters": {
    "source": "specs/prd/prd-2025-0001.md",
    "text": "1245 chars",
    "vars": {}
  },
  "timestamp": "2025-01-15T10:30:45.123Z"
}

[2025-01-15T10:30:45.856Z] DEBUG: ✅ [TSD-GENERATE] Tool completed: {
  "tool": "tsd-generate",
  "result": {
    "ok": true,
    "path": "/tmp/test/specs/tsd/tsd-001.md",
    "id": "tsd-001"
  },
  "timestamp": "2025-01-15T10:30:45.856Z"
}

Normal Mode (Production)

By default, debug mode is disabled. The server only outputs to stderr:

SpecPilot MCP Server started successfully

This ensures clean MCP protocol communication with AI tools.

Troubleshooting

Claude Code Warning Messages

If you see warnings like:

[warning] Failed to parse message: "🔍 [TSD-GENERATE] Tool called with parameters:"

Solution: Ensure debug mode is disabled (don't set SPECPILOT_DEBUG=true).

Missing Debug Information

If debug logs aren't appearing:

  1. Verify SPECPILOT_DEBUG=true is set
  2. Check file permissions for the log file location
  3. Ensure the directory exists for custom log file paths
  4. Try the default log location first

Log File Too Large

Clear debug logs periodically:

# Clear the default log file
> .specpilot-debug.log

# Or delete it
rm .specpilot-debug.log

Development Best Practices

  1. Never use console.log() in MCP tools - it breaks protocol communication
  2. Use the logger utility for debug information: logger.debug(), logger.toolCall(), etc.
  3. Test with debug disabled to ensure clean MCP communication
  4. Monitor log files during development to track tool behavior
  5. Set appropriate log levels to avoid log spam

Advanced Usage

Custom Logger Integration

import { logger } from "./src/utils/logger.js";

// Tool-specific logging
logger.toolCall("my-tool", { param1: "value" });
logger.toolResult("my-tool", { success: true });
logger.validationError("my-tool", { error: "Invalid input" });

// General logging
logger.debug("Debug information");
logger.info("General information");
logger.warn("Warning message");
logger.error("Error occurred");

Log Analysis

Since logs are JSON-formatted, you can analyze them:

# Extract all tool calls
grep "Tool called" specpilot-debug.log | jq .

# Find errors
grep "ERROR" specpilot-debug.log

# Count tool usage
grep "Tool called" specpilot-debug.log | grep -o '"tool":"[^"]*"' | sort | uniq -c