cache-overflow-mcp 0.3.7 → 0.3.8

package/src/tools/unlock-solution.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('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';
+}
 
 export const unlockSolution: ToolDefinition = {
   definition: {
@@ -17,12 +51,32 @@ export const unlockSolution: ToolDefinition = {
     },
   },
   handler: async (args, client) => {
-    const solutionId = args.solution_id as string;
+    // #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.' }],
+      };
+    }
+
     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: `Error: ${result.error}` }],
+        content: [{ type: 'text', text: errorMessage }],
       };
     }
 

package/src/ui/verification-dialog.ts

@@ -225,9 +225,35 @@ const generateHTML = (title: string, body?: string): string => `
       font-size: 18px;
       color: rgba(255, 255, 255, 0.5);
     }
+
+    .timer {
+      position: fixed;
+      top: 20px;
+      right: 20px;
+      background: rgba(139, 92, 246, 0.2);
+      border: 1px solid rgba(139, 92, 246, 0.4);
+      padding: 12px 20px;
+      border-radius: 8px;
+      font-weight: 600;
+      font-size: 14px;
+      color: #A78BFA;
+      box-shadow: 0 4px 12px rgba(0,0,0,0.2);
+      transition: all 0.3s ease;
+    }
+    .timer.warning {
+      background: rgba(255, 68, 68, 0.25);
+      border-color: rgba(255, 68, 68, 0.5);
+      color: #FF6B6B;
+      animation: pulse-warning 1s ease-in-out infinite;
+    }
+    @keyframes pulse-warning {
+      0%, 100% { transform: scale(1); }
+      50% { transform: scale(1.05); }
+    }
   </style>
 </head>
 <body>
+  <div class="timer" id="timer">Time remaining: <span id="countdown">55</span>s</div>
   <div class="card" id="main-card">
     <div class="badge">Verification Required</div>
 
@@ -266,6 +292,22 @@ const generateHTML = (title: string, body?: string): string => `
       if (e.key === 's' || e.key === 'S') submit('safe');
       if (e.key === 'u' || e.key === 'U') submit('unsafe');
     });
+
+    // #9 - Add countdown timer
+    let timeLeft = 55;
+    const countdown = document.getElementById('countdown');
+    const timer = document.getElementById('timer');
+
+    const interval = setInterval(() => {
+      timeLeft--;
+      if (countdown) countdown.textContent = timeLeft.toString();
+      if (timeLeft <= 10 && timer) {
+        timer.classList.add('warning');
+      }
+      if (timeLeft <= 0) {
+        clearInterval(interval);
+      }
+    }, 1000);
   </script>
 </body>
 </html>
@@ -280,11 +322,14 @@ function escapeHtml(text: string): string {
     .replace(/'/g, '&#039;');
 }
 
+// #15 - Distinguish error types in verification dialog resolution
+type VerificationResult = boolean | null | { error: string };
+
 /**
  * Shows a modern verification dialog in the browser.
  * @param title The solution's query title
  * @param body The solution body (if available/unlocked)
- * @returns true if user clicked "Safe", false if "Unsafe", null if cancelled
+ * @returns true if user clicked "Safe", false if "Unsafe", null if cancelled, or error object if failed
  */
 export async function showVerificationDialog(
   title: string,
@@ -299,12 +344,36 @@ export async function showVerificationDialog(
 
       if (url.pathname === '/result') {
         const value = url.searchParams.get('value');
-        res.writeHead(200, { 'Content-Type': 'text/plain', 'Access-Control-Allow-Origin': '*' });
-        res.end('OK');
+
+        // #4 - Handle HTTP response errors
+        try {
+          res.writeHead(200, { 'Content-Type': 'text/plain', 'Access-Control-Allow-Origin': '*' });
+          res.end('OK');
+        } catch (error) {
+          logger.error('Error sending response to verification dialog', error as Error, {
+            solutionTitle: title,
+            errorType: 'RESPONSE_WRITE_ERROR',
+          });
+          // Continue with resolution anyway - user already made choice
+        }
 
         if (!resolved) {
           resolved = true;
-          server.close();
+
+          // #14 - Improve server cleanup
+          server.close((err) => {
+            if (err) {
+              logger.error('Error closing verification dialog server', err, {
+                solutionTitle: title,
+                errorType: 'SERVER_CLOSE_ERROR',
+              });
+            }
+          });
+
+          // Destroy all active sockets to speed up cleanup (Node 18.2+)
+          if (typeof (server as any).closeAllConnections === 'function') {
+            (server as any).closeAllConnections();
+          }
 
           switch (value) {
             case 'safe':
@@ -329,6 +398,7 @@ export async function showVerificationDialog(
       }
     });
 
+    // #15 - Distinguish error types
     server.on('error', (error) => {
       logger.error('Verification dialog HTTP server error', error, {
         solutionTitle: title,
@@ -336,6 +406,7 @@ export async function showVerificationDialog(
       });
       if (!resolved) {
         resolved = true;
+        // Return null for errors (treated same as cancellation for now)
         resolve(null);
       }
     });
@@ -349,12 +420,20 @@ export async function showVerificationDialog(
           solutionTitle: title
         });
 
+        // #3 - Fix verification dialog browser open failure
         open(url).catch((error) => {
           logger.error('Failed to open verification dialog in browser', error, {
             url,
             solutionTitle: title,
             errorType: 'BROWSER_OPEN_FAILURE',
           });
+
+          // Provide fallback manual URL when browser open fails
+          console.error(`\n${'='.repeat(60)}`);
+          console.error('⚠️  Could not open browser automatically');
+          console.error('Please open this URL manually to verify the solution:');
+          console.error(`\n   ${url}\n`);
+          console.error(`${'='.repeat(60)}\n`);
         });
 
         // Timeout after 55 seconds (within MCP client default 60s limit)
@@ -363,6 +442,7 @@ export async function showVerificationDialog(
             resolved = true;
             server.close();
             logger.warn('Verification dialog timed out', { solutionTitle: title });
+            // Return null for timeout (treated as cancellation)
             resolve(null);
           }
         }, 55 * 1000);

package/E2E-TESTING.md

@@ -1,195 +0,0 @@
-# E2E Testing Guide for Cache Overflow MCP Server
-
-## Setup Complete
-
-The following components have been configured for E2E testing:
-
-### 1. Mock API Server
-- **Location**: `CacheOverflow/scripts/mock-server.js`
-- **Status**: Running at http://localhost:3000
-- Can be started with: `node scripts/mock-server.js`
-
-### 2. MCP Server Installation
-- **Package**: Installed via `npm link` for local development
-- **Command**: `cache-overflow-mcp`
-- **Entry point**: `CacheOverflow/dist/cli.js`
-
-### 3. MCP Server Configuration
-- **Config file**: `~/.claude.json` (local scope, managed by CLI)
-- **Configuration method**: `claude mcp add` command (not manual JSON editing)
-- **API URL**: http://localhost:3000 (pointing to mock server)
-- **Token**: test-token
-
-## Available Endpoints
-
-The mock server responds to:
-- `POST /solutions` - Publish solution
-- `POST /solutions/find` - Find solutions
-- `POST /solutions/:id/unlock` - Unlock solution
-- `POST /solutions/:id/verify` - Submit verification
-- `POST /solutions/:id/feedback` - Submit feedback
-
-## Setup Instructions
-
-### 1. Build the Project
-```bash
-cd CacheOverflow
-npm install
-npm run build
-```
-
-### 2. Install Package Locally
-```bash
-npm link
-```
-
-This makes the `cache-overflow-mcp` command available globally.
-
-### 3. Start Mock Server
-```bash
-node scripts/mock-server.js
-```
-
-The mock server will run on http://localhost:3000.
-
-### 4. Configure MCP Server in Claude Code
-```bash
-claude mcp add --transport stdio cache-overflow \
-  --env CACHE_OVERFLOW_API_URL=http://localhost:3000 \
-  --env CACHE_OVERFLOW_TOKEN=test-token \
-  -- cache-overflow-mcp
-```
-
-### 5. Verify Configuration
-```bash
-claude mcp list
-```
-
-Expected output: `cache-overflow: cache-overflow-mcp - ✓ Connected`
-
-### 6. Restart Claude Code
-After configuring the MCP server, restart Claude Code for the changes to take effect.
-
-## Testing the MCP Server
-
-### 1. Verify Mock Server is Running
-```bash
-curl -X POST http://localhost:3000/solutions/find \
-  -H "Content-Type: application/json" \
-  -d '{"query":"test"}'
-```
-
-Expected response: A JSON array with sample solutions.
-
-### 2. Check MCP Server Status
-In Claude Code, run:
-```
-/mcp
-```
-
-You should see the `cache-overflow` server listed with 5 tools.
-
-### 3. Available MCP Tools
-Once configured, the following tools are available:
-- `publish_solution`
-- `find_solution`
-- `unlock_solution`
-- `submit_verification`
-- `submit_feedback`
-
-### 4. Test publish_solution Tool
-
-Use the `publish_solution` tool with test data:
-
-**Input**:
-```json
-{
-  "query_title": "How to set up E2E testing for MCP servers",
-  "solution_body": "Create a mock HTTP server that responds to API endpoints, configure the MCP server to use localhost, and test the integration end-to-end."
-}
-```
-
-**Expected behavior**:
-- Tool calls the mock server at http://localhost:3000
-- Mock server logs the incoming request
-- Response includes a solution ID and other metadata
-- Tool returns success with solution details
-
-## Managing the Mock Server
-
-### Check if running:
-```bash
-curl http://localhost:3000/solutions/find -X POST -H "Content-Type: application/json" -d '{"query":"test"}'
-```
-
-### Stop the server:
-If running in background, press Ctrl+C in the terminal, or:
-```bash
-# On Windows with Git Bash/WSL:
-kill $(lsof -t -i:3000) 2>/dev/null || taskkill //F //IM node.exe
-```
-
-### Start/Restart the server:
-```bash
-cd CacheOverflow
-node scripts/mock-server.js
-```
-
-## Troubleshooting
-
-### MCP server not appearing in `/mcp`
-1. Verify the server is configured:
-   ```bash
-   claude mcp list
-   ```
-2. Check if it shows "✓ Connected"
-3. If not listed, re-run the `claude mcp add` command
-4. Restart Claude Code after configuration changes
-
-### "No MCP servers configured" error
-- Claude Code CLI uses `~/.claude.json`, not `mcp_settings.json`
-- Configure servers using `claude mcp add` command (see Setup Instructions above)
-- Don't manually edit `~/.claude.json` - use CLI commands
-
-### Connection refused errors
-- Check if mock server is running: `curl http://localhost:3000/solutions/find -X POST -H "Content-Type: application/json" -d '{"query":"test"}'`
-- Restart mock server if needed: `node scripts/mock-server.js`
-
-### Tool calls failing
-- Check that CACHE_OVERFLOW_API_URL environment variable is set correctly
-- Run `claude mcp get cache-overflow` to verify configuration
-- Check mock server logs for incoming requests
-- Verify `cache-overflow-mcp` command is available: `which cache-overflow-mcp`
-
-## Managing MCP Configuration
-
-### View current configuration:
-```bash
-claude mcp get cache-overflow
-```
-
-### Remove the MCP server:
-```bash
-claude mcp remove cache-overflow
-```
-
-### Update environment variables:
-```bash
-# Remove old configuration
-claude mcp remove cache-overflow
-
-# Add with updated config
-claude mcp add --transport stdio cache-overflow \
-  --env CACHE_OVERFLOW_API_URL=http://localhost:3000 \
-  --env CACHE_OVERFLOW_TOKEN=new-token \
-  -- cache-overflow-mcp
-```
-
-## Next Steps
-
-After verifying the setup works:
-1. Test all 5 MCP tools
-2. Verify request/response formats match expected schemas
-3. Test error handling scenarios
-4. Test human verification popup workflow
-5. Document any issues or improvements needed

package/TROUBLESHOOTING.md

@@ -1,219 +0,0 @@
-# Troubleshooting cache.overflow MCP Server
-
-This guide helps you troubleshoot issues with the cache.overflow MCP server and explains how to use the error logs for debugging.
-
-## Quick Diagnostics
-
-### 1. Check if the server is running
-
-If the MCP server isn't working, check your MCP client's logs:
-
-**Claude Desktop:**
-- macOS: `~/Library/Logs/Claude/mcp*.log`
-- Windows: `%APPDATA%\Claude\logs\mcp*.log`
-
-**Cursor:**
-- Check the Output panel in Cursor (View → Output → MCP)
-
-### 2. Locate the cache.overflow log file
-
-The cache.overflow server maintains its own detailed log file:
-
-**Default locations:**
-- macOS/Linux: `~/.cache-overflow/cache-overflow-mcp.log`
-- Windows: `%USERPROFILE%\.cache-overflow\cache-overflow-mcp.log`
-
-**Fallback location (if home directory is not writable):**
-- All platforms: `[temp-directory]/cache-overflow/cache-overflow-mcp.log`
-  - macOS/Linux: `/tmp/cache-overflow/cache-overflow-mcp.log`
-  - Windows: `%TEMP%\cache-overflow\cache-overflow-mcp.log`
-
-### 3. View the log file
-
-**macOS/Linux:**
-```bash
-# View the entire log
-cat ~/.cache-overflow/cache-overflow-mcp.log
-
-# View the last 50 lines
-tail -n 50 ~/.cache-overflow/cache-overflow-mcp.log
-
-# Follow the log in real-time
-tail -f ~/.cache-overflow/cache-overflow-mcp.log
-```
-
-**Windows (PowerShell):**
-```powershell
-# View the entire log
-Get-Content $env:USERPROFILE\.cache-overflow\cache-overflow-mcp.log
-
-# View the last 50 lines
-Get-Content $env:USERPROFILE\.cache-overflow\cache-overflow-mcp.log -Tail 50
-
-# Follow the log in real-time
-Get-Content $env:USERPROFILE\.cache-overflow\cache-overflow-mcp.log -Wait
-```
-
-**Windows (Command Prompt):**
-```cmd
-# View the entire log
-type %USERPROFILE%\.cache-overflow\cache-overflow-mcp.log
-
-# View the last few lines
-more %USERPROFILE%\.cache-overflow\cache-overflow-mcp.log
-```
-
-## Understanding the Log File
-
-The log file is structured as JSON lines (one JSON object per line). Each log entry includes:
-
-```json
-{
-  "timestamp": "2026-02-01T10:30:45.123Z",
-  "level": "ERROR",
-  "message": "API request failed",
-  "context": {
-    "method": "GET",
-    "path": "/solutions/search",
-    "statusCode": 401,
-    "errorMessage": "Invalid token",
-    "errorType": "API_ERROR"
-  },
-  "error": {
-    "name": "Error",
-    "message": "Unauthorized",
-    "stack": "Error: Unauthorized\n    at ..."
-  }
-}
-```
-
-### Log Levels
-
-- **ERROR**: Critical errors that prevent operations from completing
-- **WARN**: Warnings about unexpected but non-fatal situations
-- **INFO**: Informational messages about normal operations
-
-### Error Types
-
-Common `errorType` values and what they mean:
-
-| Error Type | Description | Common Causes |
-|------------|-------------|---------------|
-| `STARTUP_FAILURE` | Server failed to start | Missing dependencies, port conflicts |
-| `CONNECTION_FAILURE` | MCP transport connection failed | Communication issues with MCP client |
-| `API_ERROR` | Backend API returned an error | Invalid token, rate limiting, server issues |
-| `NETWORK_ERROR` | Network request failed | No internet, firewall, DNS issues |
-| `TOOL_EXECUTION_FAILURE` | A tool failed to execute | Invalid parameters, API errors |
-| `VERIFICATION_DIALOG_ERROR` | Verification UI failed | Port conflicts, browser issues |
-| `BROWSER_OPEN_FAILURE` | Could not open browser for verification | No default browser, permissions |
-
-## Common Issues
-
-### Issue: "Invalid token" or 401 errors
-
-**Symptoms:**
-- Log shows `API_ERROR` with `statusCode: 401`
-- Error message: "Invalid token" or "Unauthorized"
-
-**Solution:**
-1. Verify your API token is correct in the MCP configuration
-2. Ensure the token starts with `co_`
-3. Check if the token has expired (tokens don't expire, but can be revoked)
-4. Generate a new token at [app.cache-overflow.dev](https://app.cache-overflow.dev)
-
-### Issue: "Network error" or timeout
-
-**Symptoms:**
-- Log shows `NETWORK_ERROR`
-- Fetch or connection failures
-
-**Solution:**
-1. Check your internet connection
-2. Verify you can access https://cache-overflow.onrender.com/api
-3. Check firewall settings
-4. Try increasing the timeout:
-   ```json
-   "env": {
-     "CACHE_OVERFLOW_TOKEN": "your-token",
-     "CACHE_OVERFLOW_TIMEOUT": "60000"
-   }
-   ```
-
-### Issue: Verification dialog doesn't open
-
-**Symptoms:**
-- Log shows `BROWSER_OPEN_FAILURE`
-- Browser window doesn't appear
-
-**Solution:**
-1. Check if your system has a default browser set
-2. Ensure no firewall is blocking localhost connections
-3. Try manually opening the URL from the log (looks like `http://localhost:XXXXX`)
-
-### Issue: Server not starting
-
-**Symptoms:**
-- Log shows `STARTUP_FAILURE`
-- MCP client reports server crashed
-
-**Solution:**
-1. Check Node.js version: `node --version` (requires >= 18.0.0)
-2. Reinstall the package: `npm install -g cache-overflow-mcp`
-3. Clear npm cache: `npm cache clean --force`
-4. Check for conflicting global packages
-
-## Reporting Bugs
-
-When reporting issues to support, please include:
-
-1. **Your configuration** (with token redacted):
-   ```json
-   {
-     "mcpServers": {
-       "cache-overflow": {
-         "command": "cache-overflow-mcp",
-         "env": {
-           "CACHE_OVERFLOW_TOKEN": "[REDACTED]"
-         }
-       }
-     }
-   }
-   ```
-
-2. **Relevant log entries**: Copy the last 20-50 lines from your log file showing the error
-
-3. **Environment information** (from the startup log entry):
-   - cache.overflow version
-   - Node.js version
-   - Platform and architecture
-
-4. **Steps to reproduce**: What were you doing when the error occurred?
-
-## Privacy & Security
-
-The log file automatically sanitizes sensitive information:
-
-- ✅ **Logged**: Error types, stack traces, API endpoints, tool names
-- ❌ **Not logged**: API tokens, passwords, secrets, solution content, user queries
-
-You can safely share your log file with support without exposing credentials.
-
-## Custom Log Location
-
-To store logs in a custom directory, set the `CACHE_OVERFLOW_LOG_DIR` environment variable:
-
-```json
-{
-  "mcpServers": {
-    "cache-overflow": {
-      "command": "cache-overflow-mcp",
-      "env": {
-        "CACHE_OVERFLOW_TOKEN": "your-token",
-        "CACHE_OVERFLOW_LOG_DIR": "/custom/path/to/logs"
-      }
-    }
-  }
-}
-```
-
-The directory will be created automatically if it doesn't exist.

package/scripts/mock-server.js

@@ -1,37 +0,0 @@
-#!/usr/bin/env node
-
-import { MockServer } from '../dist/testing/mock-server.js';
-
-const DEFAULT_PORT = 3000;
-
-async function main() {
-  const port = process.env.PORT ? parseInt(process.env.PORT) : DEFAULT_PORT;
-
-  const server = new MockServer();
-
-  console.log('Starting mock Cache Overflow API server...');
-
-  await server.start(port);
-
-  console.log(`\n✓ Mock server running at: ${server.url}`);
-  console.log('\nAvailable endpoints:');
-  console.log('  POST /solutions - Publish solution');
-  console.log('  POST /solutions/find - Find solutions');
-  console.log('  POST /solutions/:id/unlock - Unlock solution');
-  console.log('  POST /solutions/:id/verify - Submit verification');
-  console.log('  POST /solutions/:id/feedback - Submit feedback');
-  console.log('\nPress Ctrl+C to stop the server');
-
-  // Keep the process alive
-  process.on('SIGINT', async () => {
-    console.log('\n\nShutting down mock server...');
-    await server.stop();
-    console.log('✓ Server stopped');
-    process.exit(0);
-  });
-}
-
-main().catch((error) => {
-  console.error('Failed to start mock server:', error);
-  process.exit(1);
-});