@mweinbach/apple-docs-mcp 1.0.0

package/dist/utils/error-handler.js

@@ -0,0 +1,437 @@
+/**
+ * Unified error handling utilities
+ */
+import { ERROR_MESSAGES } from './constants.js';
+import { ErrorType } from '../types/error.js';
+import { logger } from './logger.js';
+export { ErrorType };
+/**
+ * Create a standardized error response
+ */
+export function createErrorResponse(error) {
+    let message = `Error: ${error.message}`;
+    if (error.suggestions && error.suggestions.length > 0) {
+        message += '\n\nSuggestions:\n' + error.suggestions.map(s => `• ${s}`).join('\n');
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: message,
+            },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Handle fetch errors with specific error types
+ */
+export function handleFetchError(error, url) {
+    if (error instanceof TypeError) {
+        return {
+            type: ErrorType.NETWORK_ERROR,
+            message: ERROR_MESSAGES.NETWORK_ERROR,
+            originalError: error,
+            suggestions: [
+                'Check your internet connection',
+                'Verify the URL is accessible',
+                'Try again in a few moments',
+            ],
+        };
+    }
+    if (error instanceof Error) {
+        if (error.message.includes('timeout')) {
+            return {
+                type: ErrorType.TIMEOUT,
+                message: ERROR_MESSAGES.TIMEOUT,
+                originalError: error,
+                suggestions: [
+                    'Try again with a simpler query',
+                    'Check your network connection',
+                ],
+            };
+        }
+        if (error.message.includes('404')) {
+            return {
+                type: ErrorType.NOT_FOUND,
+                message: ERROR_MESSAGES.NOT_FOUND,
+                originalError: error,
+                suggestions: [
+                    'Search for the topic in Apple Developer Documentation',
+                    'Check if this is an outdated link',
+                    `Visit the original URL directly: ${url}`,
+                ],
+            };
+        }
+        return {
+            type: ErrorType.UNKNOWN,
+            message: error.message,
+            originalError: error,
+        };
+    }
+    return {
+        type: ErrorType.UNKNOWN,
+        message: String(error),
+    };
+}
+/**
+ * Handle JSON parsing errors
+ */
+export function handleParseError(error) {
+    return {
+        type: ErrorType.PARSE_ERROR,
+        message: ERROR_MESSAGES.PARSE_FAILED,
+        originalError: error instanceof Error ? error : undefined,
+        suggestions: [
+            'The API response format may have changed',
+            'Try again later',
+            'Report this issue if it persists',
+        ],
+    };
+}
+/**
+ * Validate input parameters
+ */
+export function validateInput(value, fieldName, minLength = 1) {
+    if (!value || value.trim().length < minLength) {
+        return {
+            type: ErrorType.INVALID_INPUT,
+            message: `${fieldName} is required and must be at least ${minLength} character(s)`,
+            suggestions: [
+                `Provide a valid ${fieldName.toLowerCase()}`,
+                'Check the parameter format',
+            ],
+        };
+    }
+    return null;
+}
+/**
+ * Log error for debugging (only in development)
+ */
+export function logError(error, context) {
+    if (process.env.NODE_ENV === 'development') {
+        logger.error(`[${context ?? 'ERROR'}] ${error.message}`, error.originalError);
+    }
+}
+/**
+ * Handle generic errors and convert them to AppError
+ */
+export function handleGenericError(error, context, fallbackMessage) {
+    logger.error(`Error in ${context}:`, error);
+    if (error instanceof Error) {
+        // Check for specific error types
+        if (error.message.includes('timeout') || error.message.includes('ETIMEDOUT')) {
+            return {
+                type: ErrorType.TIMEOUT,
+                message: ERROR_MESSAGES.TIMEOUT,
+                originalError: error,
+                suggestions: [
+                    'Try again with a simpler query',
+                    'Check your network connection',
+                    'Verify the service is available',
+                ],
+            };
+        }
+        if (error.message.includes('429') || error.message.includes('rate limit')) {
+            return {
+                type: ErrorType.RATE_LIMITED,
+                message: 'Request rate limit exceeded',
+                originalError: error,
+                suggestions: [
+                    'Wait a moment before trying again',
+                    'Consider reducing the frequency of requests',
+                ],
+            };
+        }
+        if (error.message.includes('500') || error.message.includes('502') || error.message.includes('503')) {
+            return {
+                type: ErrorType.SERVICE_UNAVAILABLE,
+                message: 'Apple Developer Documentation service is temporarily unavailable',
+                originalError: error,
+                suggestions: [
+                    'Try again in a few minutes',
+                    'Check Apple Developer status page',
+                    'Verify your internet connection',
+                ],
+            };
+        }
+        if (error.message.includes('JSON') || error.message.includes('parse')) {
+            return handleParseError(error);
+        }
+        return {
+            type: ErrorType.API_ERROR,
+            message: error.message,
+            originalError: error,
+            suggestions: [
+                'Check the request parameters',
+                'Try again later',
+                'Verify the API endpoint is correct',
+            ],
+        };
+    }
+    return {
+        type: ErrorType.UNKNOWN,
+        message: fallbackMessage || `An error occurred in ${context}`,
+        suggestions: [
+            'Try again later',
+            'Check your input parameters',
+            'Contact support if the issue persists',
+        ],
+    };
+}
+/**
+ * Create a standardized error response with consistent formatting
+ */
+export function createStandardErrorResponse(error, operation) {
+    const appError = handleGenericError(error, operation);
+    return createErrorResponse(appError);
+}
+/**
+ * Wrap async functions with error handling
+ */
+export async function withErrorHandling(operation, context, fallbackMessage) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const appError = handleGenericError(error, context, fallbackMessage);
+        logError(appError, context);
+        throw appError;
+    }
+}
+/**
+ * Validate multiple input parameters
+ */
+export function validateInputs(validations) {
+    for (const validation of validations) {
+        const error = validateInput(validation.value, validation.fieldName, validation.minLength);
+        if (error) {
+            return error;
+        }
+    }
+    return null;
+}
+/**
+ * Handle cache-related errors
+ */
+export function handleCacheError(error, operation) {
+    return {
+        type: ErrorType.CACHE_ERROR,
+        message: `Cache operation failed: ${operation}`,
+        originalError: error instanceof Error ? error : undefined,
+        suggestions: [
+            'The operation will continue without cache',
+            'Try clearing the cache if issues persist',
+        ],
+    };
+}
+/**
+ * Tool-specific recovery actions - ready-to-use tool calls for error recovery
+ */
+export const TOOL_RECOVERY_ACTIONS = {
+    search_apple_docs: {
+        [ErrorType.NOT_FOUND]: {
+            tool: 'list_technologies',
+            args: { limit: 20, compact: true },
+            reason: 'Discover available frameworks to search within',
+        },
+        [ErrorType.INVALID_INPUT]: {
+            tool: 'get_tool_guide',
+            args: { task: 'search for Apple documentation' },
+            reason: 'Get guidance on search best practices',
+        },
+    },
+    search_framework_symbols: {
+        [ErrorType.NOT_FOUND]: {
+            tool: 'list_technologies',
+            args: { limit: 25, compact: true },
+            reason: 'Find available framework identifiers',
+        },
+        [ErrorType.INVALID_INPUT]: {
+            tool: 'list_technologies',
+            args: { limit: 25, compact: true },
+            reason: 'Get correct framework identifiers',
+        },
+    },
+    get_apple_doc_content: {
+        [ErrorType.NOT_FOUND]: {
+            tool: 'search_apple_docs',
+            args: { type: 'documentation', compact: true },
+            reason: 'Search for valid documentation URLs',
+        },
+    },
+    get_related_apis: {
+        [ErrorType.NOT_FOUND]: {
+            tool: 'search_apple_docs',
+            args: { type: 'documentation', compact: true },
+            reason: 'Find valid API documentation first',
+        },
+    },
+    find_similar_apis: {
+        [ErrorType.NOT_FOUND]: {
+            tool: 'analyze_api',
+            args: { analysis: 'related', compact: true },
+            reason: 'Try analyzing related APIs instead',
+        },
+    },
+    list_wwdc_videos: {
+        [ErrorType.NOT_FOUND]: {
+            tool: 'wwdc',
+            args: { action: 'years' },
+            reason: 'List available WWDC years',
+        },
+    },
+    get_wwdc_video: {
+        [ErrorType.NOT_FOUND]: {
+            tool: 'wwdc',
+            args: { action: 'list', compact: true },
+            reason: 'Browse available WWDC videos',
+        },
+    },
+};
+/**
+ * Tool-specific error suggestions
+ */
+export const TOOL_ERROR_SUGGESTIONS = {
+    search_apple_docs: {
+        [ErrorType.NOT_FOUND]: [
+            'Try broader search terms (e.g., "UIView" instead of "UIViewAnimationOptions")',
+            'Use framework names like "SwiftUI" or "UIKit"',
+            'Check spelling and avoid special characters',
+            'For WWDC videos, use search_wwdc_content instead',
+        ],
+        [ErrorType.INVALID_INPUT]: [
+            'Provide specific API or framework names',
+            'Avoid generic terms like "how to" or "tutorial"',
+            'Use technical terms like class names or method names',
+        ],
+    },
+    get_apple_doc_content: {
+        [ErrorType.NOT_FOUND]: [
+            'Verify the URL starts with https://developer.apple.com/documentation/',
+            'Use search_apple_docs first to find valid URLs',
+            'Check if the API might have been renamed or moved',
+        ],
+        [ErrorType.INVALID_INPUT]: [
+            'URL must be a complete Apple Developer Documentation URL',
+            'Example: https://developer.apple.com/documentation/uikit/uiview',
+        ],
+    },
+    search_framework_symbols: {
+        [ErrorType.NOT_FOUND]: [
+            'Use list_technologies to find exact framework identifiers',
+            'Framework names should be lowercase (e.g., "uikit" not "UIKit")',
+            'Some frameworks might be part of larger frameworks',
+        ],
+        [ErrorType.INVALID_INPUT]: [
+            'Framework identifier must be in lowercase',
+            'Common identifiers: "uikit", "swiftui", "foundation", "combine"',
+            'Use list_technologies to discover available frameworks',
+        ],
+    },
+    list_wwdc_videos: {
+        [ErrorType.NOT_FOUND]: [
+            'Available years are 2020-2025',
+            'Use "all" to see videos from all years',
+            'Topic searches are case-insensitive partial matches',
+        ],
+        [ErrorType.INVALID_INPUT]: [
+            'Year should be a 4-digit string like "2025"',
+            'Topic can be any keyword like "SwiftUI" or "Performance"',
+        ],
+    },
+    search_wwdc_content: {
+        [ErrorType.NOT_FOUND]: [
+            'Try different search terms or broaden your query',
+            'Search is case-insensitive',
+            'Use technical terms that would appear in transcripts',
+        ],
+        [ErrorType.INVALID_INPUT]: [
+            'Query is required and cannot be empty',
+            'searchIn must be "transcript", "code", or "both"',
+        ],
+    },
+    get_platform_compatibility: {
+        [ErrorType.API_ERROR]: [
+            'Platform data might not be available for all APIs',
+            'Try using the single API mode instead of framework mode',
+            'Some newer APIs might not have compatibility data yet',
+        ],
+    },
+    find_similar_apis: {
+        [ErrorType.NOT_FOUND]: [
+            'Not all APIs have similar alternatives documented',
+            'Try using a broader search depth ("deep" instead of "shallow")',
+            'Consider using get_related_apis for inheritance relationships',
+        ],
+    },
+};
+/**
+ * Get tool-specific error suggestions
+ */
+export function getToolErrorSuggestions(toolName, errorType) {
+    const toolSuggestions = TOOL_ERROR_SUGGESTIONS[toolName]?.[errorType];
+    if (toolSuggestions) {
+        return toolSuggestions;
+    }
+    // Default suggestions based on error type
+    switch (errorType) {
+        case ErrorType.NOT_FOUND:
+            return [
+                'Verify the input parameters are correct',
+                'Try using a search tool first to find valid values',
+                'Check if the resource exists on developer.apple.com',
+            ];
+        case ErrorType.INVALID_INPUT:
+            return [
+                'Check the parameter format and requirements',
+                'Refer to the tool description for examples',
+                'Ensure all required parameters are provided',
+            ];
+        case ErrorType.TIMEOUT:
+            return [
+                'Try with fewer results or simpler queries',
+                'The service might be temporarily slow',
+                'Consider breaking the request into smaller parts',
+            ];
+        default:
+            return [];
+    }
+}
+/**
+ * Get recovery action for a tool error
+ */
+export function getRecoveryAction(toolName, errorType) {
+    return TOOL_RECOVERY_ACTIONS[toolName]?.[errorType] ?? null;
+}
+/**
+ * Create error response with tool-specific suggestions and recovery actions
+ */
+export function createToolErrorResponse(error, toolName) {
+    const toolSuggestions = getToolErrorSuggestions(toolName, error.type);
+    const recoveryAction = getRecoveryAction(toolName, error.type);
+    if (toolSuggestions.length > 0) {
+        error.suggestions = [...(error.suggestions ?? []), ...toolSuggestions];
+    }
+    let message = `Error: ${error.message}`;
+    if (error.suggestions && error.suggestions.length > 0) {
+        message += '\n\nSuggestions:\n' + error.suggestions.map(s => `- ${s}`).join('\n');
+    }
+    // Add recovery action if available
+    if (recoveryAction) {
+        message += '\n\n**Recovery Action:**\n';
+        message += `Tool: \`${recoveryAction.tool}\`\n`;
+        message += `Args: \`${JSON.stringify(recoveryAction.args)}\`\n`;
+        message += `Reason: ${recoveryAction.reason}`;
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: message,
+            },
+        ],
+        isError: true,
+    };
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/utils/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/utils/error-handler.ts"],"names":[],"mappings":"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"}

package/dist/utils/framework-mapper.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Unified framework name mapping system for Apple Docs MCP
+ *
+ * This module provides consistent framework name normalization across all tools.
+ * It handles common variations, typos, and alternative names for Apple frameworks.
+ */
+/**
+ * Comprehensive framework name mappings
+ * Maps lowercase/alternative names to canonical Apple framework names
+ */
+export declare const FRAMEWORK_MAPPINGS: Record<string, string>;
+/**
+ * Alternative framework names and common aliases
+ */
+export declare const FRAMEWORK_ALIASES: Record<string, string[]>;
+/**
+ * Framework categories for organization
+ */
+export declare const FRAMEWORK_CATEGORIES: {
+    readonly UI: readonly ["SwiftUI", "UIKit", "AppKit", "WidgetKit", "WatchKit"];
+    readonly Graphics: readonly ["Core Graphics", "Core Image", "Core Animation", "Metal"];
+    readonly Games: readonly ["ARKit", "RealityKit", "SceneKit", "SpriteKit", "GameKit"];
+    readonly Media: readonly ["AVFoundation", "Core Audio", "PhotoKit", "MusicKit"];
+    readonly Data: readonly ["Core Data", "CloudKit", "UserDefaults", "Keychain Services"];
+    readonly ML: readonly ["Core ML", "Create ML", "Natural Language", "Vision", "Speech"];
+    readonly Services: readonly ["HealthKit", "HomeKit", "MapKit", "StoreKit", "AlarmKit"];
+    readonly System: readonly ["Core Bluetooth", "Core Motion", "Core Location"];
+    readonly Foundation: readonly ["Foundation", "Combine", "Swift"];
+};
+/**
+ * Normalize a framework name to its canonical Apple form
+ *
+ * @param framework - The framework name to normalize (case-insensitive)
+ * @returns The canonical framework name, or the original if no mapping exists
+ */
+export declare function normalizeFrameworkName(framework: string): string;
+/**
+ * Get all possible aliases for a framework
+ *
+ * @param framework - The canonical framework name
+ * @returns Array of all known aliases for the framework
+ */
+export declare function getFrameworkAliases(framework: string): string[];
+/**
+ * Check if a framework name is valid (has a known mapping)
+ *
+ * @param framework - The framework name to check
+ * @returns True if the framework is recognized
+ */
+export declare function isValidFramework(framework: string): boolean;
+/**
+ * Get frameworks by category
+ *
+ * @param category - The category name
+ * @returns Array of framework names in the category
+ */
+export declare function getFrameworksByCategory(category: keyof typeof FRAMEWORK_CATEGORIES): string[];
+/**
+ * Find the category of a framework
+ *
+ * @param framework - The framework name
+ * @returns The category name or null if not found
+ */
+export declare function getFrameworkCategory(framework: string): keyof typeof FRAMEWORK_CATEGORIES | null;
+/**
+ * Search for frameworks by partial name or description
+ *
+ * @param query - The search query
+ * @returns Array of matching framework names
+ */
+export declare function searchFrameworks(query: string): string[];
+/**
+ * Get comprehensive framework information
+ *
+ * @param framework - The framework name
+ * @returns Object with framework details
+ */
+export declare function getFrameworkInfo(framework: string): {
+    canonical: string;
+    aliases: string[];
+    category: string | null;
+    isValid: boolean;
+};
+//# sourceMappingURL=framework-mapper.d.ts.map

package/dist/utils/framework-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-mapper.d.ts","sourceRoot":"","sources":["../../src/utils/framework-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAsX5C,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAwB7C,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;CAUvB,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CA2BhE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAG/D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAU3D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,OAAO,oBAAoB,GAAG,MAAM,EAAE,CAE7F;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,OAAO,oBAAoB,GAAG,IAAI,CAUhG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAuBxD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;CAClB,CAYA"}