cache-overflow-mcp 0.3.6 → 0.3.8

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/index.ts

@@ -1,5 +1,8 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { CacheOverflowClient } from '../client.js';
+import { configService } from '../services/config-service.js';
+import { logger } from '../logger.js';
+import type { RemoteToolDefinition } from '../types.js';
 import { findSolution } from './find-solution.js';
 import { unlockSolution } from './unlock-solution.js';
 import { publishSolution } from './publish-solution.js';
@@ -14,10 +17,76 @@ export interface ToolDefinition {
   ) => Promise<{ content: Array<{ type: string; text: string }> }>;
 }
 
-export const tools: ToolDefinition[] = [
+// Map of tool handlers by name
+const toolHandlers: Record<
+  string,
+  (
+    args: Record<string, unknown>,
+    client: CacheOverflowClient
+  ) => Promise<{ content: Array<{ type: string; text: string }> }>
+> = {
+  find_solution: findSolution.handler,
+  unlock_solution: unlockSolution.handler,
+  publish_solution: publishSolution.handler,
+  submit_verification: submitVerification.handler,
+  submit_feedback: submitFeedback.handler,
+};
+
+// Fallback tools used when backend is unavailable
+export const FALLBACK_TOOLS: ToolDefinition[] = [
   findSolution,
   unlockSolution,
   publishSolution,
   submitVerification,
   submitFeedback,
 ];
+
+/**
+ * Convert a remote tool definition to a local Tool format
+ */
+function remoteToLocalTool(remote: RemoteToolDefinition): Tool {
+  return {
+    name: remote.name,
+    description: remote.description,
+    inputSchema: {
+      type: remote.inputSchema.type as 'object',
+      properties: remote.inputSchema.properties,
+      required: remote.inputSchema.required,
+    },
+  };
+}
+
+/**
+ * Get tools with definitions from the backend API.
+ * Falls back to hardcoded definitions if the backend is unavailable.
+ */
+export async function getTools(): Promise<ToolDefinition[]> {
+  const remoteConfig = await configService.fetchConfig();
+
+  if (!remoteConfig) {
+    logger.info('Using fallback tool definitions');
+    return FALLBACK_TOOLS;
+  }
+
+  const tools: ToolDefinition[] = [];
+
+  for (const remoteTool of remoteConfig.tools) {
+    const handler = toolHandlers[remoteTool.name];
+
+    if (!handler) {
+      // Skip tools without handlers (allows backend to prepare for future tools)
+      continue;
+    }
+
+    tools.push({
+      definition: remoteToLocalTool(remoteTool),
+      handler,
+    });
+  }
+
+  return tools;
+}
+
+// Keep backward compatibility - export tools array for existing code
+// Note: This is the fallback, prefer using getTools() for dynamic loading
+export const tools: ToolDefinition[] = FALLBACK_TOOLS;

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 }],
       };
     }
 

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/types.ts

@@ -37,3 +37,51 @@ export interface User {
 export type ApiResponse<T> =
   | { success: true; data: T }
   | { success: false; error: string };
+
+// Remote MCP configuration types (fetched from backend)
+
+export interface RemoteInputProperty {
+  type: string;
+  description: string;
+}
+
+export interface RemoteInputSchema {
+  type: string;
+  properties: Record<string, RemoteInputProperty>;
+  required: string[];
+}
+
+export interface RemoteToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: RemoteInputSchema;
+}
+
+export interface RemotePromptArgument {
+  name: string;
+  description: string;
+  required: boolean;
+}
+
+export interface RemotePromptMessageContent {
+  type: string;
+  text: string;
+}
+
+export interface RemotePromptMessage {
+  role: string;
+  content: RemotePromptMessageContent;
+}
+
+export interface RemotePromptDefinition {
+  name: string;
+  description: string;
+  arguments: RemotePromptArgument[];
+  messages: RemotePromptMessage[];
+}
+
+export interface McpConfigResponse {
+  schema_version: string;
+  tools: RemoteToolDefinition[];
+  prompts: RemotePromptDefinition[];
+}