Cache Overflow

Instructions

Implementation Reference

• src/tools/unlock-solution.ts:53-95 (handler)

  The unlock_solution tool handler that validates input, calls the API client, and formats the response with error context and feedback reminders.

  handler: async (args, client) => {
    // #5 - Add input validation
    const solutionId = (args.solution_id as string || '').trim();
  
    if (!solutionId) {
      return {
        content: [{ type: 'text', text: 'Error: solution_id cannot be empty. Please provide a valid solution ID from find_solution results.' }],
      };
    }
  
    // Validate solution_id format to prevent injection attacks
    if (!/^[a-zA-Z0-9_-]+$/.test(solutionId)) {
      return {
        content: [{ type: 'text', text: 'Error: Invalid solution_id format. Must contain only alphanumeric characters, hyphens, and underscores.' }],
      };
    }
  
    const result = await client.unlockSolution(solutionId);
  
    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: errorMessage }],
      };
    }
  
    const feedbackReminder = '\n\n⚠️ REQUIRED: You MUST now call submit_feedback with this solution_id after you have tried applying the solution. Report whether it was helpful (is_useful=true/false).';
  
    return {
      content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) + feedbackReminder }],
    };
  },

• src/tools/unlock-solution.ts:37-52 (schema)

  Tool definition including name, description, and input schema that defines the solution_id parameter as a required string.

  export const unlockSolution: ToolDefinition = {
    definition: {
      name: 'unlock_solution',
      description:
        'Unlock a verified solution to access its full content. Use this ONLY for solutions where human_verification_required=false (you only received the title from find_solution). Do NOT call this for solutions that required verification - you already have the full content for those. After receiving find_solution results, assess each solution\'s title. If the title indicates the solution is relevant to your problem, you MUST call this tool to unlock it. This will deduct tokens from your balance based on the solution\'s price. Only unlock solutions that are likely to save you more tokens than they cost.',
      inputSchema: {
        type: 'object',
        properties: {
          solution_id: {
            type: 'string',
            description: 'The ID of the solution to unlock (obtained from find_solution results)',
          },
        },
        required: ['solution_id'],
      },
    },

• src/tools/index.ts:27-28 (registration)

  Registration of unlock_solution handler in the toolHandlers mapping that connects the tool name to its handler function.

  find_solution: findSolution.handler,
  unlock_solution: unlockSolution.handler,

• src/tools/unlock-solution.ts:4-35 (helper)

  Error handling helper functions getErrorTitle and getRecoverySuggestions that provide contextual error messages and recovery guidance.

  // #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';
    if (error.includes('not found') || error.includes('404')) return 'Solution Not Found';
    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('not found') || error.includes('404')) {
      return '- Verify the solution_id is correct\n- The solution may have been deleted\n- Try searching again with find_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';
  }

• src/client.ts:277-279 (helper)

  The unlockSolution client method that performs the actual API POST request to unlock a solution.

  async unlockSolution(solutionId: string): Promise<ApiResponse<Solution>> {
    return this.requestWithRetry('POST', `/solutions/${solutionId}/unlock`);
  }