debug

Debug MCP Server

Provides comprehensive debugging tools for troubleshooting MCP server issues.

Usage

/debug [component] [options]

Components

• protocol - Debug protocol messages
• tools - Debug tool execution
• resources - Debug resource access
• transport - Debug transport layer
• all - Enable all debugging (default)

Options

• --verbose - Extra verbose output
• --save - Save debug logs to file
• --inspector - Launch with MCP Inspector

Implementation

import * as fs from 'fs/promises';
import { exec, spawn } from 'child_process';
import * as path from 'path';

async function debugServer(
  component: 'protocol' | 'tools' | 'resources' | 'transport' | 'all' = 'all',
  options: {
    verbose?: boolean;
    save?: boolean;
    inspector?: boolean;
  } = {}
) {
  console.log('🔍 MCP Server Debugger');
  console.log('='.repeat(50));
  
  // Set debug environment variables
  const debugEnv = {
    ...process.env,
    DEBUG: component === 'all' ? 'mcp:*' : `mcp:${component}`,
    LOG_LEVEL: options.verbose ? 'trace' : 'debug',
    MCP_DEBUG: 'true',
  };
  
  // Create debug configuration
  const debugConfig = await createDebugConfig();
  
  // Start debug session
  if (options.inspector) {
    await launchWithInspector(debugEnv);
  } else {
    await runDebugSession(component, debugEnv, options);
  }
}

async function createDebugConfig(): Promise<string> {
  const config = {
    logging: {
      level: 'debug',
      format: 'pretty',
      includeTimestamp: true,
      includeLocation: true,
    },
    debug: {
      protocol: {
        logRequests: true,
        logResponses: true,
        logNotifications: true,
      },
      tools: {
        logCalls: true,
        logValidation: true,
        logErrors: true,
        measurePerformance: true,
      },
      resources: {
        logReads: true,
        logWrites: true,
        trackCache: true,
      },
      transport: {
        logConnections: true,
        logMessages: true,
        logErrors: true,
      },
    },
  };
  
  const configPath = '.debug-config.json';
  await fs.writeFile(configPath, JSON.stringify(config, null, 2));
  return configPath;
}

async function runDebugSession(
  component: string,
  env: NodeJS.ProcessEnv,
  options: { verbose?: boolean; save?: boolean }
) {
  console.log(`\n🔍 Debugging: ${component}`);
  console.log('Press Ctrl+C to stop\n');
  
  // Create debug wrapper
  const debugScript = `
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import debug from 'debug';
import pino from 'pino';

// Enable debug logging
const log = {
  protocol: debug('mcp:protocol'),
  tools: debug('mcp:tools'),
  resources: debug('mcp:resources'),
  transport: debug('mcp:transport'),
};

// Create logger
const logger = pino({
  level: process.env.LOG_LEVEL || 'debug',
  transport: {
    target: 'pino-pretty',
    options: {
      colorize: true,
      translateTime: 'HH:MM:ss.l',
      ignore: 'pid,hostname',
    },
  },
});

// Wrap server methods for debugging
const originalServer = await import('./src/index.js');
const server = originalServer.server;

// Intercept requests
const originalSetRequestHandler = server.setRequestHandler.bind(server);
server.setRequestHandler = (schema, handler) => {
  const wrappedHandler = async (request) => {
    const start = Date.now();
    log.protocol('→ Request: %O', request);
    logger.debug({ request }, 'Incoming request');
    
    try {
      const result = await handler(request);
      const duration = Date.now() - start;
      
      log.protocol('← Response (%dms): %O', duration, result);
      logger.debug({ result, duration }, 'Response sent');
      
      return result;
    } catch (error) {
      log.protocol('✗ Error: %O', error);
      logger.error({ error }, 'Request failed');
      throw error;
    }
  };
  
  return originalSetRequestHandler(schema, wrappedHandler);