mcp-image 0.1.0

package/dist/api/urlContextClient.js

@@ -0,0 +1,320 @@
+"use strict";
+/**
+ * URL Context API client for processing URLs and extracting context
+ * Uses @google/genai SDK for URL context processing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UrlContextClient = void 0;
+const urlExtractor_1 = require("../business/urlExtractor");
+const result_1 = require("../types/result");
+const errors_1 = require("../utils/errors");
+/**
+ * Client for processing URLs and extracting context
+ * Basic implementation for Phase 2 - will be enhanced in later phases
+ */
+class UrlContextClient {
+    constructor(textClient) {
+        this.textClient = textClient;
+        /**
+         * Maximum number of retry attempts
+         */
+        this.MAX_RETRIES = 2;
+        /**
+         * Timeout for URL context processing in milliseconds
+         */
+        this.TIMEOUT_MS = 15000;
+    }
+    /**
+     * Process multiple URLs and extract context for image generation
+     * @param urls Array of URLs to process
+     * @param originalPrompt Original prompt containing URLs
+     * @returns Result containing URL context response with combined prompt or error
+     */
+    async processUrls(urls, originalPrompt) {
+        try {
+            // Handle empty URL array
+            if (urls.length === 0) {
+                return (0, result_1.Ok)({
+                    contextContent: '',
+                    combinedPrompt: `Generate image: ${originalPrompt}`,
+                    extractedInfo: {},
+                    success: true,
+                });
+            }
+            // Limit URLs to maximum allowed
+            const limitedUrls = urls.slice(0, UrlContextClient.MAX_URLS);
+            // Use retry mechanism with timeout
+            const result = await this.processUrlsWithRetry(limitedUrls, originalPrompt);
+            return result;
+        }
+        catch (error) {
+            return (0, result_1.Err)(this.createProcessingError(error));
+        }
+    }
+    /**
+     * Process URLs with retry mechanism and timeout
+     * @param urls Array of URLs to process
+     * @param originalPrompt Original prompt containing URLs
+     * @returns Result containing URL context response with retry information
+     */
+    async processUrlsWithRetry(urls, originalPrompt) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.MAX_RETRIES; attempt++) {
+            try {
+                const result = await this.processUrlsWithTimeout(urls, originalPrompt);
+                if (result.success) {
+                    // Add retry information to extracted info
+                    const enrichedExtractedInfo = {
+                        ...result.data.extractedInfo,
+                        retryCount: attempt,
+                        finalAttempt: attempt + 1,
+                        maxRetries: this.MAX_RETRIES,
+                    };
+                    return (0, result_1.Ok)({
+                        ...result.data,
+                        extractedInfo: enrichedExtractedInfo,
+                    });
+                }
+                lastError = result.error;
+                // Check if error is retryable
+                if (attempt < this.MAX_RETRIES && this.isRetryableError(result.error)) {
+                    await this.delay(1000 * 2 ** attempt); // Exponential backoff
+                    continue;
+                }
+                return (0, result_1.Err)(result.error);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error('Unknown error');
+                if (attempt === this.MAX_RETRIES) {
+                    return (0, result_1.Err)(new errors_1.URLContextError(`Max retries exceeded: ${lastError.message}`, 'Try again later or check your network connection'));
+                }
+                if (this.isRetryableError(lastError)) {
+                    await this.delay(1000 * 2 ** attempt); // Exponential backoff
+                }
+                else {
+                    return (0, result_1.Err)(this.createProcessingError(lastError));
+                }
+            }
+        }
+        return (0, result_1.Err)(new errors_1.URLContextError(`Max retries exceeded: ${lastError?.message || 'Unknown error'}`, 'Check your network connection and try again'));
+    }
+    /**
+     * Process URLs with timeout protection
+     * @param urls Array of URLs to process
+     * @param originalPrompt Original prompt containing URLs
+     * @returns Result with timeout protection
+     */
+    async processUrlsWithTimeout(urls, originalPrompt) {
+        return new Promise((resolve) => {
+            const timeoutId = setTimeout(() => {
+                resolve((0, result_1.Err)(new errors_1.NetworkError('URL context processing timed out', 'Try reducing the number of URLs or check your network connection')));
+            }, this.TIMEOUT_MS);
+            this.processUrlsCore(urls, originalPrompt)
+                .then((result) => {
+                clearTimeout(timeoutId);
+                resolve(result);
+            })
+                .catch((error) => {
+                clearTimeout(timeoutId);
+                resolve((0, result_1.Err)(this.createProcessingError(error)));
+            });
+        });
+    }
+    /**
+     * Core URL processing logic without retry/timeout
+     * @param urls Array of URLs to process
+     * @param originalPrompt Original prompt containing URLs
+     * @returns Result containing URL context response
+     */
+    async processUrlsCore(urls, originalPrompt) {
+        // Process all URLs in a single context extraction request
+        const contextPrompt = this.buildContextPrompt(urls, originalPrompt);
+        const result = await this.textClient.generateText(contextPrompt);
+        if (!result.success) {
+            return (0, result_1.Err)(this.createContextError(result.error));
+        }
+        const contextContent = result.data.text || '';
+        // Combine context with original prompt
+        const combinedPrompt = this.combineContextWithPrompt([contextContent], originalPrompt, urls);
+        const extractedInfo = this.parseExtractedInfo(contextContent, urls.length);
+        return (0, result_1.Ok)({
+            contextContent,
+            combinedPrompt,
+            extractedInfo,
+            success: true,
+        });
+    }
+    /**
+     * Build a context extraction prompt for Gemini API
+     * @param urls Array of URLs to process
+     * @param originalPrompt Original prompt containing URLs
+     * @returns Formatted prompt for context extraction
+     */
+    buildContextPrompt(urls, originalPrompt) {
+        const urlList = urls.map((url, index) => `${index + 1}. ${url}`).join('\n');
+        return `
+Please analyze the following URLs and extract relevant context for image generation:
+
+URLs to analyze:
+${urlList}
+
+Original prompt: ${originalPrompt}
+
+Extract key information that would be relevant for generating an image based on these URLs. Focus on:
+- Visual descriptions
+- Key concepts or themes
+- Relevant details for image creation
+
+Provide a concise summary of the most relevant visual information.
+`.trim();
+    }
+    /**
+     * Combine URL context with original prompt for image generation
+     * @param contextPrompts Array of context content from URLs
+     * @param originalPrompt Original prompt containing URLs
+     * @param urls Array of processed URLs
+     * @returns Combined prompt for image generation
+     */
+    combineContextWithPrompt(contextPrompts, originalPrompt, urls) {
+        const cleanPrompt = this.cleanPromptFromUrls(originalPrompt);
+        const finalPrompt = cleanPrompt || originalPrompt;
+        const contextContent = this.formatContextContent(contextPrompts);
+        return this.formatCombinedPrompt(urls, contextContent, finalPrompt);
+    }
+    /**
+     * Remove URLs and clean up common action words from prompt
+     * @param originalPrompt Original prompt containing URLs
+     * @returns Cleaned prompt suitable for final instruction
+     */
+    cleanPromptFromUrls(originalPrompt) {
+        // Remove URLs from original prompt to get clean instruction
+        let cleanPrompt = urlExtractor_1.URLExtractor.removeUrls(originalPrompt).trim();
+        // Enhanced cleaning: remove common action words that become awkward after URL removal
+        // e.g., "Create image of https://example.com with sunset" -> "with sunset"
+        const actionPatterns = [
+            /^(create|generate|make)\s+(an?\s+)?(image|picture|photo)\s+(of|from|based\s+on)\s*/i,
+            /^(show|display|illustrate)\s*/i,
+        ];
+        for (const pattern of actionPatterns) {
+            cleanPrompt = cleanPrompt.replace(pattern, '').trim();
+        }
+        return cleanPrompt;
+    }
+    /**
+     * Format and clean context content from multiple sources
+     * @param contextPrompts Array of raw context content
+     * @returns Formatted context content
+     */
+    formatContextContent(contextPrompts) {
+        return contextPrompts.filter((p) => p?.trim()).join('\n\n');
+    }
+    /**
+     * Format the final combined prompt with context and instruction sections
+     * @param urls Array of processed URLs
+     * @param contextContent Formatted context content
+     * @param finalPrompt Final instruction prompt
+     * @returns Complete combined prompt
+     */
+    formatCombinedPrompt(urls, contextContent, finalPrompt) {
+        const urlList = urls.join(', ');
+        const displayContext = contextContent || '(No specific context extracted)';
+        return `Context from URLs (${urlList}):\n${displayContext}\n\nGenerate image: ${finalPrompt}`;
+    }
+    /**
+     * Create a standardized context error from API failure
+     * @param originalError The original error from text generation
+     * @returns Formatted URLContextError
+     */
+    createContextError(originalError) {
+        return new errors_1.URLContextError(`URL context processing failed: ${originalError.message}`, 'Check your network connection and try again, or disable URL context processing');
+    }
+    /**
+     * Create appropriate error based on error type
+     * @param error The original error that occurred
+     * @returns Formatted error (NetworkError or URLContextError)
+     */
+    createProcessingError(error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        // Check if it's a network-related error
+        if (this.isNetworkError(error)) {
+            return new errors_1.NetworkError(`Network error during URL context processing: ${errorMessage}`, 'Check your internet connection and try again', error instanceof Error ? error : undefined);
+        }
+        // Generic URL context error
+        return new errors_1.URLContextError(`URL context processing error: ${errorMessage}`, 'Try again with fewer URLs or disable URL context processing');
+    }
+    /**
+     * Parse extracted information from context content
+     * @param contextContent The context content to parse
+     * @param processedUrlCount Number of URLs that were processed
+     * @returns Structured extracted information
+     */
+    parseExtractedInfo(contextContent, processedUrlCount) {
+        // Enhanced implementation with content analysis
+        const wordCount = contextContent.split(/\s+/).filter((word) => word.length > 0).length;
+        const hasVisualDescriptions = /\b(color|image|visual|picture|photo|scene|view|appearance)\b/i.test(contextContent);
+        return {
+            processedUrls: processedUrlCount,
+            contentLength: contextContent.length,
+            wordCount,
+            processedAt: new Date().toISOString(),
+            hasContent: contextContent.length > 0,
+            hasVisualDescriptions,
+            contentPreview: contextContent.substring(0, 100) + (contextContent.length > 100 ? '...' : ''),
+        };
+    }
+    /**
+     * Check if an error is network-related
+     * @param error The error to check
+     * @returns True if it's a network error
+     */
+    isNetworkError(error) {
+        if (error instanceof Error) {
+            const networkErrorCodes = [
+                'ECONNRESET',
+                'ECONNREFUSED',
+                'ETIMEDOUT',
+                'ENOTFOUND',
+                'ENETUNREACH',
+            ];
+            const networkErrorKeywords = ['network', 'connection', 'timeout', 'unreachable', 'dns'];
+            return (networkErrorCodes.some((code) => error.message.includes(code) || error.code === code) || networkErrorKeywords.some((keyword) => error.message.toLowerCase().includes(keyword)));
+        }
+        return false;
+    }
+    /**
+     * Check if an error is retryable
+     * @param error The error to check
+     * @returns True if the error should trigger a retry
+     */
+    isRetryableError(error) {
+        // Network errors are retryable
+        if (this.isNetworkError(error)) {
+            return true;
+        }
+        // Rate limit and temporary errors are retryable
+        const retryableKeywords = [
+            'rate limit',
+            'temporary',
+            'throttle',
+            'service unavailable',
+            '503',
+            '429',
+        ];
+        const errorMessage = error.message.toLowerCase();
+        return retryableKeywords.some((keyword) => errorMessage.includes(keyword));
+    }
+    /**
+     * Add a delay for exponential backoff
+     * @param ms Milliseconds to delay
+     * @returns Promise that resolves after the delay
+     */
+    async delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.UrlContextClient = UrlContextClient;
+/**
+ * Maximum number of URLs to process (performance consideration)
+ */
+UrlContextClient.MAX_URLS = 10;
+//# sourceMappingURL=urlContextClient.js.map

package/dist/api/urlContextClient.js.map

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

package/dist/business/errorHandler.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Comprehensive Error Handler for complete error management
+ * Provides error classification, recovery mechanisms, and structured response generation
+ */
+import type { McpToolResponse } from '../types/mcp';
+import type { Result } from '../types/result';
+import { BaseError } from '../utils/errors';
+/**
+ * Structured logger interface for error handling
+ */
+interface StructuredLogger {
+    error(context: string, message: string, error: Error, metadata?: Record<string, unknown>): void;
+    warn(context: string, message: string, metadata?: Record<string, unknown>): void;
+    info(context: string, message: string, metadata?: Record<string, unknown>): void;
+}
+/**
+ * Comprehensive error handler with classification and recovery capabilities
+ */
+export declare class ComprehensiveErrorHandler {
+    private logger;
+    constructor(logger?: StructuredLogger);
+    /**
+     * Handle any error and convert it to a structured BaseError Result
+     * @param error Error or unknown value to handle
+     * @param context Context string for logging
+     * @param operation Operation name for logging
+     * @returns Result with structured error
+     */
+    handleError<T>(error: Error | unknown, context: string, operation: string): Result<T, BaseError>;
+    /**
+     * Classify a generic Error into appropriate BaseError subclass
+     * @param error Original error to classify
+     * @param context Context for additional information
+     * @returns Classified BaseError
+     */
+    private classifyError;
+    /**
+     * Check if error is API-related with enhanced pattern matching
+     */
+    private isAPIError;
+    /**
+     * Check if error is network-related with enhanced pattern matching
+     */
+    private isNetworkError;
+    /**
+     * Check if error is file operation related
+     */
+    private isFileError;
+    /**
+     * Check if error is concurrency-related
+     */
+    private isConcurrencyError;
+    /**
+     * Check if error is security-related
+     */
+    private isSecurityError;
+    /**
+     * Check if error is validation-related
+     */
+    private isValidationError;
+    /**
+     * Convert BaseError to MCP tool response format
+     * @param error BaseError to convert
+     * @returns MCP tool response
+     */
+    convertToMcpResponse(error: BaseError): McpToolResponse;
+    /**
+     * Sanitize error context to prevent sensitive information leakage
+     * @param context Original context object
+     * @returns Sanitized context object
+     */
+    private sanitizeContext;
+    /**
+     * Check if an error is retryable with enhanced retry logic
+     * @param error Error to check
+     * @returns True if error should be retried
+     */
+    isRetryableError(error: BaseError): boolean;
+    /**
+     * Get retry delay in milliseconds with adaptive exponential backoff
+     * @param attempt Current attempt number (1-based)
+     * @param error Optional error to adapt delay based on error type
+     * @param baseDelay Base delay in milliseconds (default: 1000)
+     * @returns Delay in milliseconds
+     */
+    getRetryDelay(attempt: number, error?: BaseError, baseDelay?: number): number;
+    /**
+     * Get human-readable retry advice based on error type and attempt
+     * @param error Error that occurred
+     * @param attempt Current attempt number
+     * @param maxAttempts Maximum retry attempts
+     * @returns Human-readable retry advice
+     */
+    getRetryAdvice(error: BaseError, attempt: number, maxAttempts: number): string;
+}
+export {};
+//# sourceMappingURL=errorHandler.d.ts.map

package/dist/business/errorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../../src/business/errorHandler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAE7C,OAAO,EACL,SAAS,EASV,MAAM,iBAAiB,CAAA;AAGxB;;GAEG;AACH,UAAU,gBAAgB;IACxB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC/F,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAChF,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACjF;AAED;;GAEG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,CAAC,EAAE,gBAAgB;IAIrC;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,SAAS,CAAC;IA0BhG;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IA8CrB;;OAEG;IACH,OAAO,CAAC,UAAU;IA2DlB;;OAEG;IACH,OAAO,CAAC,cAAc;IA4EtB;;OAEG;IACH,OAAO,CAAC,WAAW;IAwBnB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAqBvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;;;OAIG;IACH,oBAAoB,CAAC,KAAK,EAAE,SAAS,GAAG,eAAe;IAuBvD;;;;OAIG;IACH,OAAO,CAAC,eAAe;IA+BvB;;;;OAIG;IACH,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAiG3C;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,EAAE,SAAS,SAAO,GAAG,MAAM;IA6C3E;;;;;;OAMG;IACH,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;CAkB/E"}