CTS MCP Server

# Task 2C.2: Enhanced Error Handling - COMPLETE ✅ **Completion Date**: 2025-06-XX **Duration**: ~2 hours **Task Reference**: Tier 2C Improvements, Task 2C.2 --- ## Overview Enhanced the CTS MCP Server's error handling system with categorized errors, recovery suggestions, and comprehensive schema validation. This improvement provides users with actionable error messages and ensures type-safe tool responses. --- ## Deliverables ### 1. Enhanced Error System (`src/enhanced_errors.ts`) **Purpose**: Provide categorized errors with recovery suggestions for better user experience. **Key Features**: - **Error Categories**: 8 distinct categories (Validation, Parsing, FileSystem, TreeSitter, Permissions, Configuration, Timeout, Unknown) - **Error Severity Levels**: Low, Medium, High - **Recovery Suggestions**: Structured guidance with actions and references - **Common Suggestions**: Pre-built suggestion templates for each error category - **Factory Functions**: `createValidationError`, `createParsingError`, `createFilesystemError` - **Formatted Output**: Human-readable error messages with numbered suggestions **Implementation**: ```typescript export enum ErrorCategory { VALIDATION = 'validation', PARSING = 'parsing', FILE_SYSTEM = 'filesystem', TREE_SITTER = 'tree_sitter', PERMISSIONS = 'permissions', CONFIGURATION = 'configuration', TIMEOUT = 'timeout', UNKNOWN = 'unknown', } export enum ErrorSeverity { LOW = 'low', MEDIUM = 'medium', HIGH = 'high', } export interface RecoverySuggestion { action: string; reference?: string; } export interface EnhancedErrorInfo { category: ErrorCategory; severity: ErrorSeverity; suggestions: RecoverySuggestion[]; context?: Record<string, unknown>; } ``` **Example Usage**: ```typescript const error = createValidationError('Missing parameter', 'projectPath', 'string'); // error.suggestions contains: // - Check tool parameter documentation // - Verify required fields are provided // - Review example usage in docs/ console.log(formatEnhancedError(error)); // Output: // [VALIDATION - MEDIUM] Missing parameter // Recovery Suggestions: // 1. Check tool parameter documentation // 2. Verify required fields are provided // 3. Review example usage in docs/ ``` --- ### 2. Schema Validation System (`src/schemas.ts`) **Purpose**: Type-safe validation of all 8 tool response structures using Zod. **Schemas Implemented**: 1. **BaseToolResponseSchema**: Common fields (success, timestamp, toolName, duration, metadata) 2. **ErrorResponseSchema**: Error response format 3. **ReasoningResponseSchema**: CTS_Reasoning tool 4. **ScanSignalsResponseSchema**: CTS_Scan_Project_Signals tool 5. **BughunterResponseSchema**: CTS_Bughunter tool 6. **AuditResponseSchema**: cts_audit tool 7. **AnalyzeProjectResponseSchema**: CTS_Analyze_Project tool 8. **SuggestRefactoringResponseSchema**: CTS_Suggest_Refactoring tool 9. **RenderArtifactResponseSchema**: CTS_Render_Artifact tool 10. **ExportToShrimpResponseSchema**: CTS_Export_to_Shrimp tool **Key Features**: - **Strict Validation**: Enforces required fields, data types, enum values, number ranges - **Type Exports**: TypeScript types inferred from Zod schemas - **Validation Function**: `validateToolResponse(toolName, response)` returns `{valid, errors?}` - **Schema Registry**: Centralized `ToolSchemas` object for all tools **Example Schema**: ```typescript export const BughunterResponseSchema = BaseToolResponseSchema.extend({ success: z.literal(true), result: z.object({ bugs: z.array(z.object({ file: z.string(), line: z.number(), severity: z.enum(['low', 'medium', 'high', 'critical']), message: z.string(), category: z.string(), suggestion: z.string().optional(), })), summary: z.object({ totalBugs: z.number(), bySeverity: z.record(z.number()), byCategory: z.record(z.number()), }), }), }); ``` **Validation Usage**: ```typescript import { validateToolResponse } from './schemas.js'; const response = await executeTool('CTS_Bughunter', params); const { valid, errors } = validateToolResponse('CTS_Bughunter', response); if (!valid) { console.error('Invalid response:', errors); throw Errors.validationError('response', 'BughunterResponse', response); } ``` --- ### 3. Error Integration (`src/errors.ts`) **Changes**: - **Added EnhancedErrorInfo** to `MCPError` class constructor - **Enhanced toJSON()**: Includes `enhanced` field with category, severity, suggestions - **New Method**: `getFormattedMessage()` returns human-readable error with recovery actions - **Factory Functions Updated**: - `validationError`: Includes validation suggestions (check docs, verify fields, review examples) - `treeSitterError`: Includes parser suggestions (check GDScript syntax, review file, upgrade tree-sitter) - `fileSystemError`: Includes file suggestions (verify path, check permissions, ensure file exists) **Enhanced JSON-RPC Error Response**: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid parameter 'projectPath'", "data": { "enhanced": { "category": "validation", "severity": "medium", "suggestions": [ { "action": "Check tool parameter documentation", "reference": "docs/TOOLS.md" }, { "action": "Verify required fields are provided", "reference": "https://spec.modelcontextprotocol.io/specification/server/tools/" } ], "context": { "parameter": "projectPath", "expected": "string", "received": 123 } } } } } ``` --- ### 4. Test Coverage **Enhanced Error Tests** (`src/__tests__/enhanced_errors.test.ts`): - ✅ Error creation with suggestions (validation, parsing, filesystem) - ✅ Error formatting for display - ✅ MCP error integration with enhanced info - ✅ JSON serialization with suggestions - ✅ Formatted error messages **Schema Validation Tests** (`src/__tests__/schemas.test.ts`): - ✅ CTS_Scan_Project_Signals schema validation - ✅ CTS_Bughunter schema validation - ✅ cts_audit schema validation - ✅ Base response field validation - ✅ Invalid structure rejection - ✅ Score range enforcement - ✅ Timestamp format validation **Test Results**: ``` Test Suites: 2 passed, 2 total Tests: 19 passed, 19 total Time: 3.679s ``` --- ## Integration Points ### 1. Tool Handlers - **Before**: Tools returned unvalidated JSON responses - **After**: Tools should validate responses using `validateToolResponse()` - **Impact**: Type-safe tool responses, early error detection ### 2. Error Responses - **Before**: Generic error messages without recovery guidance - **After**: Categorized errors with actionable suggestions - **Impact**: Better user experience, faster debugging ### 3. VS Code Extension - **Before**: Error messages displayed as-is - **After**: Can parse `enhanced` field for rich error UI - **Impact**: Suggestion cards, quick-fix actions, documentation links --- ## Technical Details ### Error Categories Mapping | Category | Use Case | Severity | Common Suggestions | |----------|----------|----------|-------------------| | VALIDATION | Invalid parameters, missing required fields | MEDIUM | Check docs, verify fields, review examples | | PARSING | GDScript syntax errors, JSON parse failures | HIGH | Check syntax, review file, validate format | | FILE_SYSTEM | Missing files, permission errors, path issues | MEDIUM | Verify path, check permissions, ensure file exists | | TREE_SITTER | Parser errors, unsupported syntax | HIGH | Check GDScript syntax, review file, upgrade parser | | PERMISSIONS | Read/write permission errors | HIGH | Check file permissions, verify user access | | CONFIGURATION | Invalid configuration, missing env vars | MEDIUM | Review config, check env vars, validate settings | | TIMEOUT | Long-running operations, network timeouts | LOW | Increase timeout, optimize query, reduce scope | | UNKNOWN | Unclassified errors | LOW | Review logs, check system state, report issue | ### Schema Validation Flow ``` Tool Execution → Raw Response → validateToolResponse() → {valid, errors?} ↓ If invalid: Create MCPError with enhanced info If valid: Return typed response ``` ### TypeScript Strict Mode Compliance All code passes TypeScript strict mode checks: - ✅ Explicit type annotations for lambda parameters - ✅ Type guards for spread operators (`typeof x === 'object' && x !== null`) - ✅ ES module imports with `.js` extensions - ✅ No implicit `any` types --- ## Future Enhancements (Post-Task 2C.2) 1. **Tool Response Validation Integration** (Task 2C.3+) - Add `validateToolResponse()` to all tool handlers - Return enhanced errors for invalid responses - Log validation errors for monitoring 2. **VS Code Quick Fixes** (Task 3+) - Parse `suggestions` for CodeAction providers - Implement quick-fix UI for common errors - Add "Open Documentation" links 3. **Error Analytics** (Task 3+) - Track error categories and frequencies - Identify common user mistakes - Generate error reports for documentation improvements 4. **Suggestion Templating** (Task 3+) - Variable substitution in suggestions (e.g., `{file_path}`, `{expected_type}`) - Context-aware suggestions based on error data - Multi-language suggestion support --- ## Dependencies ### New Dependencies - `zod@^3.22.4` - Schema validation (already in dependencies) ### Modified Files - `src/enhanced_errors.ts` - **NEW** (280 lines) - `src/schemas.ts` - **NEW** (285 lines) - `src/errors.ts` - **MODIFIED** (added enhanced info integration) - `src/__tests__/enhanced_errors.test.ts` - **NEW** (120 lines) - `src/__tests__/schemas.test.ts` - **NEW** (200 lines) --- ## Verification ### Build Verification ```bash npm run build # ✅ Compiled successfully with no errors ``` ### Test Verification ```bash npm test -- --testPathPattern="enhanced_errors|schemas" # ✅ 19/19 tests passed ``` ### TypeScript Strict Mode ```bash tsc --noEmit --strict # ✅ No errors found ``` --- ## Lessons Learned 1. **TypeScript Strict Mode**: Lambda parameters need explicit types in callbacks 2. **ES Modules**: Import paths require `.js` extensions in TypeScript+ESM projects 3. **Type Guards**: Spread operators on `unknown` types require runtime validation 4. **Schema Design**: Zod schemas provide both validation and TypeScript type inference 5. **Error UX**: Recovery suggestions significantly improve debugging experience --- ## Next Steps **Immediate** (Task 2C.3): - Integrate `validateToolResponse()` into tool handlers - Update tool implementations to return BaseToolResponse format - Add schema validation tests for remaining 5 tools **Short-term** (Task 2C.4-2C.8): - Task 2C.3: MCP Sampling Protocol integration - Task 2C.4: Configuration management (extend config.ts) - Task 2C.5: Result caching implementation - Task 2C.6: Parallel execution optimization (fix Worker ES modules) - Task 2C.7: CI/CD integration (GitHub Actions) - Task 2C.8: Tier 2C tests & documentation **Long-term** (Task 3+): - VS Code quick-fix integration - Error analytics and reporting - Multi-language suggestion support --- ## References - **MCP Error Codes**: https://spec.modelcontextprotocol.io/specification/basic/errors/ - **Zod Documentation**: https://zod.dev/ - **TypeScript Strict Mode**: https://www.typescriptlang.org/tsconfig#strict - **Task Plan**: `cts_mcp/docs/TIER_2C_IMPROVEMENTS.md` --- **Task Status**: ✅ **COMPLETE** **Test Coverage**: 19/19 tests passing **Build Status**: ✅ Clean TypeScript compilation **Ready for Integration**: Yes - all validation functions and schemas ready to use