cache-overflow-mcp 0.3.7 → 0.3.8

package/src/client.ts

@@ -5,10 +5,32 @@ import { logger } from './logger.js';
 export class CacheOverflowClient {
   private apiUrl: string;
   private authToken: string | undefined;
+  private timeout: number;
 
-  constructor(apiUrl?: string) {
+  constructor(apiUrl?: string, token?: string, timeout?: number) {
     this.apiUrl = apiUrl ?? config.api.url;
-    this.authToken = config.auth.token;
+    this.authToken = token ?? config.auth.token;
+    this.timeout = timeout ?? config.api.timeout;
+
+    // Validate URL format (#13 - URL Validation)
+    try {
+      new URL(this.apiUrl);
+    } catch (error) {
+      logger.error('Invalid CACHE_OVERFLOW_URL format', error as Error, {
+        url: this.apiUrl,
+        errorType: 'INVALID_API_URL',
+      });
+      throw new Error(`Invalid API URL: ${this.apiUrl}`);
+    }
+
+    // Validate token format (#12 - Token Validation)
+    if (!this.authToken) {
+      logger.warn('No CACHE_OVERFLOW_TOKEN provided - all API calls will fail', {});
+    } else if (!this.authToken.startsWith('co_')) {
+      logger.warn('Invalid token format - tokens should start with "co_"', {
+        tokenPrefix: this.authToken.substring(0, 3),
+      });
+    }
   }
 
   private async request<T>(
@@ -26,11 +48,33 @@ export class CacheOverflowClient {
 
     const url = `${this.apiUrl}${path}`;
 
+    // #11 - Add request logging for debugging
+    logger.info('API request', {
+      method,
+      path,
+      hasBody: !!body,
+    });
+
+    // #1 - Enforce request timeouts
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
     try {
       const response = await fetch(url, {
         method,
         headers,
         body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      // #11 - Add response logging
+      logger.info('API response', {
+        method,
+        path,
+        status: response.status,
+        ok: response.ok,
       });
 
       // Read response as text first, then try to parse as JSON
@@ -60,18 +104,66 @@ export class CacheOverflowClient {
 
       if (!response.ok) {
         const errorMessage = (data.error as string) ?? 'Unknown error';
+
+        // #7 - Detect and handle rate limiting (429)
+        if (response.status === 429) {
+          const retryAfter = response.headers.get('Retry-After') || '60';
+          logger.warn('Rate limit exceeded', {
+            method,
+            path,
+            retryAfter,
+            errorType: 'RATE_LIMIT',
+          });
+          return {
+            success: false,
+            error: `Rate limit exceeded. Please wait ${retryAfter} seconds before trying again. Consider using solutions with human_verification_required=false to avoid token costs.`,
+          };
+        }
+
+        // #8 - Add status code to error messages with categorization
+        let category = '';
+        if (response.status >= 500) {
+          category = 'Server error - try again later';
+        } else if (response.status === 401 || response.status === 403) {
+          category = 'Authentication error - check your CACHE_OVERFLOW_TOKEN';
+        } else if (response.status >= 400) {
+          category = 'Request error - check your input';
+        }
+
         logger.error('API request failed', undefined, {
           method,
           path,
           statusCode: response.status,
           errorMessage,
+          category,
           errorType: 'API_ERROR',
         });
-        return { success: false, error: errorMessage };
+
+        return {
+          success: false,
+          error: `${errorMessage} (${category})`,
+        };
       }
 
       return { success: true, data: data as T };
     } catch (error) {
+      clearTimeout(timeoutId);
+
+      // #1 - Handle timeout errors specifically
+      if ((error as Error).name === 'AbortError') {
+        logger.error('Request timed out', error as Error, {
+          method,
+          path,
+          url,
+          timeout: this.timeout,
+          errorType: 'TIMEOUT',
+        });
+        return {
+          success: false,
+          error: `Request timed out after ${this.timeout}ms. The server may be experiencing issues.`,
+        };
+      }
+
       logger.error('Network or fetch error during API request', error as Error, {
         method,
         path,
@@ -79,13 +171,89 @@ export class CacheOverflowClient {
         errorType: 'NETWORK_ERROR',
       });
 
-      // Re-throw network errors so they can be handled by the caller
+      // Re-throw network errors so they can be handled by retry logic
       throw error;
     }
   }
 
+  // #2 - Add retry logic for network failures
+  private async requestWithRetry<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    retries = 3
+  ): Promise<ApiResponse<T>> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < retries; attempt++) {
+      try {
+        const result = await this.request<T>(method, path, body);
+
+        // If successful or last attempt, return the result
+        if (result.success || attempt === retries - 1) {
+          return result;
+        }
+
+        // Check if we should retry based on the error
+        const shouldRetry = this.shouldRetryError(result.error);
+        if (shouldRetry) {
+          const delay = Math.pow(3, attempt) * 100; // 0, 300, 900ms exponential backoff
+          logger.info('Retrying request after delay', {
+            method,
+            path,
+            attempt: attempt + 1,
+            maxRetries: retries,
+            delay,
+          });
+          await new Promise(resolve => setTimeout(resolve, delay));
+          continue;
+        }
+
+        // Don't retry client errors (4xx)
+        return result;
+      } catch (error) {
+        lastError = error as Error;
+
+        // Only retry network errors, not client errors
+        if (attempt < retries - 1 && this.isNetworkError(error as Error)) {
+          const delay = Math.pow(3, attempt) * 100;
+          logger.info('Retrying after network error', {
+            method,
+            path,
+            attempt: attempt + 1,
+            maxRetries: retries,
+            delay,
+            error: (error as Error).message,
+          });
+          await new Promise(resolve => setTimeout(resolve, delay));
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  private shouldRetryError(error?: string): boolean {
+    if (!error) return false;
+
+    // Retry on server errors (5xx) or timeout errors
+    return error.includes('Server error') ||
+           error.includes('timed out') ||
+           error.includes('network');
+  }
+
+  private isNetworkError(error: Error): boolean {
+    // Network errors typically have these names or messages
+    return error.name === 'TypeError' ||
+           error.name === 'NetworkError' ||
+           error.message.includes('fetch') ||
+           error.message.includes('network');
+  }
+
   async findSolution(query: string): Promise<ApiResponse<FindSolutionResult[]>> {
-    const result = await this.request<Array<{ id: string; query_title: string; solution_body?: string; human_verification_required: boolean }>>(
+    const result = await this.requestWithRetry<Array<{ id: string; query_title: string; solution_body?: string; human_verification_required: boolean }>>(
       'GET',
       `/solutions/search?query=${encodeURIComponent(query)}`
     );
@@ -105,14 +273,14 @@ export class CacheOverflowClient {
   }
 
   async unlockSolution(solutionId: string): Promise<ApiResponse<Solution>> {
-    return this.request('POST', `/solutions/${solutionId}/unlock`);
+    return this.requestWithRetry('POST', `/solutions/${solutionId}/unlock`);
   }
 
   async publishSolution(
     queryTitle: string,
     solutionBody: string
   ): Promise<ApiResponse<Solution>> {
-    return this.request('POST', '/solutions', {
+    return this.requestWithRetry('POST', '/solutions', {
       query_title: queryTitle,
       solution_body: solutionBody,
     });
@@ -122,7 +290,7 @@ export class CacheOverflowClient {
     solutionId: string,
     isSafe: boolean
   ): Promise<ApiResponse<void>> {
-    return this.request('POST', `/solutions/${solutionId}/verify`, {
+    return this.requestWithRetry('POST', `/solutions/${solutionId}/verify`, {
       is_safe: isSafe,
     });
   }
@@ -131,7 +299,7 @@ export class CacheOverflowClient {
     solutionId: string,
     isUseful: boolean
   ): Promise<ApiResponse<void>> {
-    return this.request('POST', `/solutions/${solutionId}/feedback`, {
+    return this.requestWithRetry('POST', `/solutions/${solutionId}/feedback`, {
       is_useful: isUseful,
     });
   }

package/src/config.ts

@@ -1,6 +1,6 @@
 export const config = {
   api: {
-    url: process.env.CACHE_OVERFLOW_URL ?? 'https://cache-overflow.onrender.com/api',
+    url: process.env.CACHE_OVERFLOW_URL ?? 'https://cacheoverflow.dev/api',
     timeout: parseInt(process.env.CACHE_OVERFLOW_TIMEOUT ?? '30000'),
   },
   auth: {

package/src/tools/find-solution.ts

@@ -1,5 +1,35 @@
 import { ToolDefinition } from './index.js';
 import { showVerificationDialog } from '../ui/verification-dialog.js';
+import { config } from '../config.js';
+
+// #6 - Improve error messages with context
+function getErrorTitle(error: string): string {
+  if (error.includes('timeout') || error.includes('timed out')) return 'Request Timed Out';
+  if (error.includes('network') || error.includes('fetch')) return 'Network Connection Failed';
+  if (error.includes('balance') || error.includes('insufficient')) return 'Insufficient Token Balance';
+  if (error.includes('auth') || error.includes('Authentication')) return 'Authentication Failed';
+  if (error.includes('Rate limit')) return 'Rate Limit Exceeded';
+  return 'Operation Failed';
+}
+
+function getRecoverySuggestions(error: string): string {
+  if (error.includes('timeout') || error.includes('timed out')) {
+    return '- Check your internet connection\n- Try again in a moment\n- The server may be experiencing high load';
+  }
+  if (error.includes('balance') || error.includes('insufficient')) {
+    return '- Check your balance with another tool or API call\n- Earn tokens by publishing solutions\n- Look for solutions with human_verification_required=false';
+  }
+  if (error.includes('auth') || error.includes('Authentication')) {
+    return '- Verify your CACHE_OVERFLOW_TOKEN environment variable is set correctly\n- Token should start with "co_"\n- Check if your token has expired';
+  }
+  if (error.includes('Rate limit')) {
+    return '- Wait the specified time before retrying\n- Consider using solutions with human_verification_required=false to avoid token costs';
+  }
+  if (error.includes('network') || error.includes('fetch')) {
+    return '- Check your internet connection\n- Verify the CACHE_OVERFLOW_URL is correct\n- Try again in a moment';
+  }
+  return '- Check the log file for details\n- Verify your CACHE_OVERFLOW_TOKEN is valid\n- Try again in a moment';
+}
 
 export const findSolution: ToolDefinition = {
   definition: {
@@ -18,12 +48,44 @@ export const findSolution: ToolDefinition = {
     },
   },
   handler: async (args, client) => {
-    const query = args.query as string;
+    // #5 - Add input validation
+    const query = (args.query as string || '').trim();
+
+    if (!query) {
+      return {
+        content: [{ type: 'text', text: 'Error: Query cannot be empty. Please provide a description of the problem you are trying to solve.' }],
+      };
+    }
+
+    if (query.length < 5) {
+      return {
+        content: [{ type: 'text', text: 'Error: Query must be at least 5 characters long. Please provide more details about the problem.' }],
+      };
+    }
+
+    if (query.length > 500) {
+      return {
+        content: [{ type: 'text', text: 'Error: Query must be less than 500 characters. Please provide a more concise description.' }],
+      };
+    }
+
     const result = await client.findSolution(query);
 
     if (!result.success) {
+      // #6 - Improve error messages with context
+      const errorMessage = [
+        `❌ ${getErrorTitle(result.error || '')}`,
+        '',
+        result.error,
+        '',
+        '💡 **What to try:**',
+        getRecoverySuggestions(result.error || ''),
+        '',
+        `📋 **Logs**: Check ${config.logging.logDir || '~/.cache-overflow'}/cache-overflow-mcp.log for details`,
+      ].join('\n');
+
       return {
-        content: [{ type: 'text', text: `Error: ${result.error}` }],
+        content: [{ type: 'text', text: errorMessage }],
       };
     }
 
@@ -37,7 +99,17 @@ export const findSolution: ToolDefinition = {
 
         // If user made a choice (not cancelled), submit verification
         if (verificationResult !== null) {
-          await client.submitVerification(solution.solution_id, verificationResult);
+          // #10 - Catch verification submission errors
+          try {
+            const submitResult = await client.submitVerification(solution.solution_id, verificationResult);
+            if (!submitResult.success) {
+              // Log but don't fail - user still gets the solution content
+              console.warn(`Warning: Failed to submit verification for solution ${solution.solution_id}: ${submitResult.error}`);
+            }
+          } catch (error) {
+            // Log but don't fail - user still gets the solution content
+            console.warn(`Warning: Error submitting verification for solution ${solution.solution_id}:`, error);
+          }
         }
       }
     }

package/src/tools/publish-solution.ts

@@ -1,4 +1,34 @@
 import { ToolDefinition } from './index.js';
+import { config } from '../config.js';
+
+// #6 - Improve error messages with context
+function getErrorTitle(error: string): string {
+  if (error.includes('timeout') || error.includes('timed out')) return 'Request Timed Out';
+  if (error.includes('network') || error.includes('fetch')) return 'Network Connection Failed';
+  if (error.includes('auth') || error.includes('Authentication')) return 'Authentication Failed';
+  if (error.includes('Rate limit')) return 'Rate Limit Exceeded';
+  if (error.includes('duplicate') || error.includes('already exists')) return 'Duplicate Solution';
+  return 'Operation Failed';
+}
+
+function getRecoverySuggestions(error: string): string {
+  if (error.includes('timeout') || error.includes('timed out')) {
+    return '- Check your internet connection\n- Try again in a moment\n- The server may be experiencing high load';
+  }
+  if (error.includes('auth') || error.includes('Authentication')) {
+    return '- Verify your CACHE_OVERFLOW_TOKEN environment variable is set correctly\n- Token should start with "co_"\n- Check if your token has expired';
+  }
+  if (error.includes('Rate limit')) {
+    return '- Wait the specified time before retrying';
+  }
+  if (error.includes('duplicate') || error.includes('already exists')) {
+    return '- A similar solution may already exist\n- Try searching first with find_solution\n- Consider adding more specific details to your solution';
+  }
+  if (error.includes('network') || error.includes('fetch')) {
+    return '- Check your internet connection\n- Verify the CACHE_OVERFLOW_URL is correct\n- Try again in a moment';
+  }
+  return '- Check the log file for details\n- Verify your CACHE_OVERFLOW_TOKEN is valid\n- Try again in a moment';
+}
 
 export const publishSolution: ToolDefinition = {
   definition: {
@@ -21,13 +51,51 @@ export const publishSolution: ToolDefinition = {
     },
   },
   handler: async (args, client) => {
-    const queryTitle = args.query_title as string;
-    const solutionBody = args.solution_body as string;
+    // #5 - Add input validation
+    const queryTitle = (args.query_title as string || '').trim();
+    const solutionBody = (args.solution_body as string || '').trim();
+
+    if (!queryTitle || queryTitle.length < 5) {
+      return {
+        content: [{ type: 'text', text: 'Error: Title must be at least 5 characters. Please provide a clear, descriptive title.' }],
+      };
+    }
+
+    if (queryTitle.length > 200) {
+      return {
+        content: [{ type: 'text', text: 'Error: Title must be less than 200 characters. Please use a more concise title.' }],
+      };
+    }
+
+    if (!solutionBody || solutionBody.length < 10) {
+      return {
+        content: [{ type: 'text', text: 'Error: Solution body must be at least 10 characters. Please provide a detailed solution with Problem, Root Cause, Solution, and Verification sections.' }],
+      };
+    }
+
+    if (solutionBody.length > 50000) {
+      return {
+        content: [{ type: 'text', text: 'Error: Solution body must be less than 50,000 characters. Please be more concise.' }],
+      };
+    }
+
     const result = await client.publishSolution(queryTitle, solutionBody);
 
     if (!result.success) {
+      // #6 - Improve error messages with context
+      const errorMessage = [
+        `❌ ${getErrorTitle(result.error || '')}`,
+        '',
+        result.error,
+        '',
+        '💡 **What to try:**',
+        getRecoverySuggestions(result.error || ''),
+        '',
+        `📋 **Logs**: Check ${config.logging.logDir || '~/.cache-overflow'}/cache-overflow-mcp.log for details`,
+      ].join('\n');
+
       return {
-        content: [{ type: 'text', text: `Error: ${result.error}` }],
+        content: [{ type: 'text', text: errorMessage }],
       };
     }
 

package/src/tools/submit-feedback.ts

@@ -1,4 +1,38 @@
 import { ToolDefinition } from './index.js';
+import { config } from '../config.js';
+
+// #6 - Improve error messages with context
+function getErrorTitle(error: string): string {
+  if (error.includes('timeout') || error.includes('timed out')) return 'Request Timed Out';
+  if (error.includes('network') || error.includes('fetch')) return 'Network Connection Failed';
+  if (error.includes('auth') || error.includes('Authentication')) return 'Authentication Failed';
+  if (error.includes('Rate limit')) return 'Rate Limit Exceeded';
+  if (error.includes('not found') || error.includes('404')) return 'Solution Not Found';
+  if (error.includes('already submitted')) return 'Feedback Already Submitted';
+  return 'Operation Failed';
+}
+
+function getRecoverySuggestions(error: string): string {
+  if (error.includes('timeout') || error.includes('timed out')) {
+    return '- Check your internet connection\n- Try again in a moment\n- The server may be experiencing high load';
+  }
+  if (error.includes('auth') || error.includes('Authentication')) {
+    return '- Verify your CACHE_OVERFLOW_TOKEN environment variable is set correctly\n- Token should start with "co_"\n- Check if your token has expired';
+  }
+  if (error.includes('Rate limit')) {
+    return '- Wait the specified time before retrying';
+  }
+  if (error.includes('not found') || error.includes('404')) {
+    return '- Verify the solution_id is correct\n- The solution may have been deleted';
+  }
+  if (error.includes('already submitted')) {
+    return '- You have already submitted feedback for this solution\n- No action needed';
+  }
+  if (error.includes('network') || error.includes('fetch')) {
+    return '- Check your internet connection\n- Verify the CACHE_OVERFLOW_URL is correct\n- Try again in a moment';
+  }
+  return '- Check the log file for details\n- Verify your CACHE_OVERFLOW_TOKEN is valid\n- Try again in a moment';
+}
 
 export const submitFeedback: ToolDefinition = {
   definition: {
@@ -21,13 +55,39 @@ export const submitFeedback: ToolDefinition = {
     },
   },
   handler: async (args, client) => {
-    const solutionId = args.solution_id as string;
+    // #5 - Add input validation
+    const solutionId = (args.solution_id as string || '').trim();
     const isUseful = args.is_useful as boolean;
+
+    if (!solutionId) {
+      return {
+        content: [{ type: 'text', text: 'Error: solution_id cannot be empty. Please provide a valid solution ID.' }],
+      };
+    }
+
+    if (typeof isUseful !== 'boolean') {
+      return {
+        content: [{ type: 'text', text: 'Error: is_useful must be a boolean (true or false).' }],
+      };
+    }
+
     const result = await client.submitFeedback(solutionId, isUseful);
 
     if (!result.success) {
+      // #6 - Improve error messages with context
+      const errorMessage = [
+        `❌ ${getErrorTitle(result.error || '')}`,
+        '',
+        result.error,
+        '',
+        '💡 **What to try:**',
+        getRecoverySuggestions(result.error || ''),
+        '',
+        `📋 **Logs**: Check ${config.logging.logDir || '~/.cache-overflow'}/cache-overflow-mcp.log for details`,
+      ].join('\n');
+
       return {
-        content: [{ type: 'text', text: `Error: ${result.error}` }],
+        content: [{ type: 'text', text: errorMessage }],
       };
     }
 

package/src/tools/submit-verification.ts

@@ -1,4 +1,38 @@
 import { ToolDefinition } from './index.js';
+import { config } from '../config.js';
+
+// #6 - Improve error messages with context
+function getErrorTitle(error: string): string {
+  if (error.includes('timeout') || error.includes('timed out')) return 'Request Timed Out';
+  if (error.includes('network') || error.includes('fetch')) return 'Network Connection Failed';
+  if (error.includes('auth') || error.includes('Authentication')) return 'Authentication Failed';
+  if (error.includes('Rate limit')) return 'Rate Limit Exceeded';
+  if (error.includes('not found') || error.includes('404')) return 'Solution Not Found';
+  if (error.includes('already verified')) return 'Already Verified';
+  return 'Operation Failed';
+}
+
+function getRecoverySuggestions(error: string): string {
+  if (error.includes('timeout') || error.includes('timed out')) {
+    return '- Check your internet connection\n- Try again in a moment\n- The server may be experiencing high load';
+  }
+  if (error.includes('auth') || error.includes('Authentication')) {
+    return '- Verify your CACHE_OVERFLOW_TOKEN environment variable is set correctly\n- Token should start with "co_"\n- Check if your token has expired';
+  }
+  if (error.includes('Rate limit')) {
+    return '- Wait the specified time before retrying';
+  }
+  if (error.includes('not found') || error.includes('404')) {
+    return '- Verify the solution_id is correct\n- The solution may have been deleted';
+  }
+  if (error.includes('already verified')) {
+    return '- You have already verified this solution\n- No action needed';
+  }
+  if (error.includes('network') || error.includes('fetch')) {
+    return '- Check your internet connection\n- Verify the CACHE_OVERFLOW_URL is correct\n- Try again in a moment';
+  }
+  return '- Check the log file for details\n- Verify your CACHE_OVERFLOW_TOKEN is valid\n- Try again in a moment';
+}
 
 export const submitVerification: ToolDefinition = {
   definition: {
@@ -21,13 +55,39 @@ export const submitVerification: ToolDefinition = {
     },
   },
   handler: async (args, client) => {
-    const solutionId = args.solution_id as string;
+    // #5 - Add input validation
+    const solutionId = (args.solution_id as string || '').trim();
     const isSafe = args.is_safe as boolean;
+
+    if (!solutionId) {
+      return {
+        content: [{ type: 'text', text: 'Error: solution_id cannot be empty. Please provide a valid solution ID.' }],
+      };
+    }
+
+    if (typeof isSafe !== 'boolean') {
+      return {
+        content: [{ type: 'text', text: 'Error: is_safe must be a boolean (true or false).' }],
+      };
+    }
+
     const result = await client.submitVerification(solutionId, isSafe);
 
     if (!result.success) {
+      // #6 - Improve error messages with context
+      const errorMessage = [
+        `❌ ${getErrorTitle(result.error || '')}`,
+        '',
+        result.error,
+        '',
+        '💡 **What to try:**',
+        getRecoverySuggestions(result.error || ''),
+        '',
+        `📋 **Logs**: Check ${config.logging.logDir || '~/.cache-overflow'}/cache-overflow-mcp.log for details`,
+      ].join('\n');
+
       return {
-        content: [{ type: 'text', text: `Error: ${result.error}` }],
+        content: [{ type: 'text', text: errorMessage }],
       };
     }