debugging-troubleshooting

Debugging and Troubleshooting Guide

General Debugging Strategies

Logging and Console Output

• Development Mode: Output debugging information using console.log
• Structured Logging: Structured log messages in JSON format
• Error Stack Tracing: Include detailed error information and stack traces

TypeScript Type Errors

• Type Checking: Check entire project types with npm run type-check
• Gradual Type Application: Minimize any type usage and define specific types
• Type Guards: Ensure type safety at runtime

MCP Server Debugging

MCP Server Inspection Tools

# Inspect MCP server under development
npm run inspect

# Inspect built MCP server
npm run inspect:built

Common MCP Issues

1. Tool Registration Failure

// Incorrect example
server.tool('invalid-tool', {
  // Missing parameter schema
}, handler);

// Correct example
server.tool('valid-tool', {
  description: 'Clear description',
  parameters: z.object({
    param: z.string().describe('Parameter description')
  })
}, handler);

2. Type Mismatch Issues

• Zod Schema Validation: Type validation of input parameters
• TypeScript Type Definitions: Compile-time type safety

3. Asynchronous Processing Errors

// Properly handle Promise chains
server.tool('async-tool', schema, async (params) => {
  try {
    const result = await someAsyncOperation(params);
    return { result };
  } catch (error) {
    throw new Error(`Operation failed: ${error.message}`);
  }
});

CLI Debugging

CLI Command Testing

# Run CLI in local development mode
npm run context-compose -- --help

# Debug specific commands
npm run context-compose -- get-context default --verbose

Common CLI Issues

1. Command Parsing Errors

• Commander.js Configuration Check: Review command definitions in src/cli/index.ts
• Argument Validation: Distinguish between required and optional arguments