name: mcp-debugging description: Debug MCP server issues and analyze logs for the Orient. Use this skill when investigating tool failures, API errors, slow operations, or troubleshooting MCP tool behavior. Covers log file locations, JSON log format, correlation IDs for request tracing, common debugging commands, and log rotation configuration.

MCP Server Debugging

Log Files

JSON Log Structure

{
  "timestamp": "2024-12-09 14:30:45.123",
  "level": "INFO",
  "message": "Tool completed: ai_first_get_all_issues",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "service": "mcp-server",
  "operation": "tool_call",
  "durationMs": 1234,
  "meta": { ... }
}

Key Fields:

• correlationId - UUID linking all logs for a single tool invocation
• service - Component (mcp-server, jira-service, slides-service, config)
• durationMs - Operation duration in milliseconds
• meta - Context (JQL queries, issue counts, API responses)

Quick Debugging Commands

Check Recent Errors

tail -20 logs/mcp-error.log | jq .

Trace a Request (by correlation ID)

grep "550e8400" logs/mcp-debug.log | jq .

Check Tool Calls

tail -100 logs/mcp-debug.log | grep "tool_call" | jq '{tool: .tool, status: .status}'

Check JQL Queries

grep '"jql"' logs/mcp-debug.log | jq '.meta.jql // .jql' | sort -u

Find Slow Operations (>3s)

grep durationMs logs/mcp-debug.log | jq 'select(.durationMs > 3000)'

Watch Logs Real-Time

tail -f logs/mcp-debug.log | jq .

Filter by Service

tail -f logs/mcp-debug.log | grep '"service":"jira"' | jq .

Common Debugging Scenarios

MCP Tool Not Working

1. Check if tool was invoked:

   grep "Tool invoked: TOOL_NAME" logs/mcp-debug.log | tail -5
   

2. Check completion status:

   grep "TOOL_NAME" logs/mcp-debug.log | grep -E '"status":"(success|error)"' | tail -5 | jq .
   

3. Trace full request using correlation ID

Jira API Issues

# Check Jira errors
grep '"service":"jira' logs/mcp-debug.log | grep '"level":"ERROR"' | jq .

# See JQL queries
grep '"service":"jira' logs/mcp-debug.log | jq 'select(.meta.jql) | {operation: .operation, jql: .meta.jql}'

Google Slides API Issues

# Check initialization
grep '"service":"slides' logs/mcp-debug.log | grep "initialize" | jq .

# Check operations
grep '"service":"slides' logs/mcp-debug.log | jq '{operation: .operation, slideId: .meta.slideId, status: .status}'

Config Loading Issues

grep '"service":"config"' logs/mcp-debug.log | jq .

Log Level Configuration

Set via LOG_LEVEL environment variable:

• error - Only errors
• warn - Errors and warnings
• info - Normal operation (default)
• debug - Verbose debugging

LOG_LEVEL=debug npm run start

Log Rotation

Log files are named: mcp-debug-YYYY-MM-DD.log Old logs are compressed: mcp-debug-YYYY-MM-DD.log.gz

Sensitive Data

Logs automatically redact:

• API tokens
• Passwords
• Secrets
• Authorization headers

[REDACTED] in logs is intentional security behavior.

Debugging Tips

1. Start with correlation ID - Links all related log entries
2. Check timestamps - Look for unusual gaps (hanging operations)
3. Compare durations - Sudden increases indicate API issues
4. Look at meta field - Detailed context (issue counts, JQL, responses)
5. Use jq for filtering - JSON format makes extraction easy
6. Check stderr during startup - Human-readable logs for immediate visibility