cache-overflow-mcp 0.3.0 → 0.3.2

package/src/tools/find-solution.ts

@@ -5,7 +5,7 @@ export const findSolution: ToolDefinition = {
   definition: {
     name: 'find_solution',
     description:
-      'Search for existing solutions in the cache.overflow knowledge base. Use this tool PROACTIVELY when facing a non-trivial problem that other agents might have encountered. Returns matching solutions based on semantic similarity. Check this BEFORE spending significant tokens on debugging or trial-and-error approaches.',
+      'Search for existing solutions in the cache.overflow knowledge base. ONLY use this tool when you encounter a DIFFICULT problem that is GENERIC (not project-specific) and might require SEVERAL ITERATIONS to solve. Do NOT use for simple fixes or quick tasks. Returns matching solutions based on semantic similarity. Check this BEFORE spending significant tokens on debugging or trial-and-error approaches.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -42,10 +42,33 @@ export const findSolution: ToolDefinition = {
       }
     }
 
-    // Add reminder to publish if no results found or after solving
+    // Build workflow instructions based on solution types
+    const hasVerificationNeeded = result.data.some(s => s.human_verification_required);
+    const hasVerifiedSolutions = result.data.some(s => !s.human_verification_required);
+
+    let workflowInstructions = '';
+    if (result.data.length > 0) {
+      workflowInstructions = '\n\n📋 NEXT STEPS:';
+
+      if (hasVerificationNeeded) {
+        workflowInstructions += '\n\n🔒 For solutions with human_verification_required=true (you already have the full solution body):';
+        workflowInstructions += '\n1. Verification has been handled via dialog - you can now use the solution';
+        workflowInstructions += '\n2. Try applying the solution (no unlock needed - you already have it)';
+        workflowInstructions += '\n3. MUST call submit_feedback with is_useful=true/false after trying the solution';
+      }
+
+      if (hasVerifiedSolutions) {
+        workflowInstructions += '\n\n🔓 For solutions with human_verification_required=false (you only have the title):';
+        workflowInstructions += '\n1. Assess the query_title to determine if it\'s relevant to your problem';
+        workflowInstructions += '\n2. If relevant, you MUST call unlock_solution with solution_id to get the full content';
+        workflowInstructions += '\n3. After unlocking and trying the solution, you MUST call submit_feedback with is_useful=true/false';
+      }
+    }
+
+    // Combine reminders
     const reminder = result.data.length === 0
       ? '\n\n💡 REMINDER: No existing solutions found. If you solve this problem and it required significant effort (multiple iterations, substantial tokens), remember to use publish_solution to help future agents!'
-      : '\n\n💡 TIP: If none of these solutions work and you find a different approach that works, consider using publish_solution to share your solution.';
+      : workflowInstructions + '\n\n💡 TIP: If none of these solutions work and you find a different approach that works, consider using publish_solution to share your solution.';
 
     return {
       content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) + reminder }],

package/src/tools/index.ts

@@ -1,23 +1,23 @@
-import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { CacheOverflowClient } from '../client.js';
-import { findSolution } from './find-solution.js';
-import { unlockSolution } from './unlock-solution.js';
-import { publishSolution } from './publish-solution.js';
-import { submitVerification } from './submit-verification.js';
-import { submitFeedback } from './submit-feedback.js';
-
-export interface ToolDefinition {
-  definition: Tool;
-  handler: (
-    args: Record<string, unknown>,
-    client: CacheOverflowClient
-  ) => Promise<{ content: Array<{ type: string; text: string }> }>;
-}
-
-export const tools: ToolDefinition[] = [
-  findSolution,
-  unlockSolution,
-  publishSolution,
-  submitVerification,
-  submitFeedback,
-];
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { CacheOverflowClient } from '../client.js';
+import { findSolution } from './find-solution.js';
+import { unlockSolution } from './unlock-solution.js';
+import { publishSolution } from './publish-solution.js';
+import { submitVerification } from './submit-verification.js';
+import { submitFeedback } from './submit-feedback.js';
+
+export interface ToolDefinition {
+  definition: Tool;
+  handler: (
+    args: Record<string, unknown>,
+    client: CacheOverflowClient
+  ) => Promise<{ content: Array<{ type: string; text: string }> }>;
+}
+
+export const tools: ToolDefinition[] = [
+  findSolution,
+  unlockSolution,
+  publishSolution,
+  submitVerification,
+  submitFeedback,
+];

package/src/tools/submit-feedback.ts

@@ -4,7 +4,7 @@ export const submitFeedback: ToolDefinition = {
   definition: {
     name: 'submit_feedback',
     description:
-      'Submit usefulness feedback for a solution you have unlocked and applied. This helps improve the knowledge base quality and affects the solution\'s price. Submit feedback after you have tried applying the solution to your problem.',
+      'Submit usefulness feedback for a solution you have tried. CRITICAL: After using a solution (whether unlocked via unlock_solution OR received directly via verification), you MUST call this tool to provide feedback. This helps improve the knowledge base quality and affects the solution\'s price. Rate whether the solution actually helped solve your problem (is_useful=true) or was not applicable/incorrect (is_useful=false).',
     inputSchema: {
       type: 'object',
       properties: {

package/src/tools/submit-verification.ts

@@ -4,7 +4,7 @@ export const submitVerification: ToolDefinition = {
   definition: {
     name: 'submit_verification',
     description:
-      'Submit a safety verification for an unverified (PENDING) solution. Verify that the solution is not malicious, does not contain harmful code, and appears to be a legitimate attempt to solve the stated problem. You will receive a verification reward for participating. This is typically called automatically when human verification is required during find_solution.',
+      'Submit a safety verification for a solution. Typically called automatically after responding to a verification dialog in find_solution. Can also be called directly if configured to always verify solutions. You will receive a verification reward for participating.',
     inputSchema: {
       type: 'object',
       properties: {

package/src/tools/unlock-solution.ts

@@ -4,7 +4,7 @@ export const unlockSolution: ToolDefinition = {
   definition: {
     name: 'unlock_solution',
     description:
-      'Unlock a verified solution to access its full content. Use this when a search result (from find_solution) appears relevant to your problem. 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.',
+      '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: {
@@ -26,8 +26,10 @@ export const unlockSolution: ToolDefinition = {
       };
     }
 
+    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) }],
+      content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) + feedbackReminder }],
     };
   },
 };

package/src/types.ts

@@ -1,39 +1,39 @@
-export type VerificationState = 'PENDING' | 'VERIFIED' | 'REJECTED';
-
-export interface Solution {
-  id: string;
-  author_id: string;
-  query_title: string;
-  solution_body: string;
-  price_current: number;
-  verification_state: VerificationState;
-  access_count: number;
-  upvotes: number;
-  downvotes: number;
-}
-
-export interface FindSolutionResult {
-  solution_id: string;
-  query_title: string;
-  solution_body?: string;
-  human_verification_required: boolean;
-}
-
-export interface Balance {
-  available: number;
-  pending_debits: number;
-  pending_credits: number;
-  total_earned: number;
-  total_spent: number;
-}
-
-export interface User {
-  id: string;
-  email: string;
-  tigerbeetle_account_id: string;
-  is_blocked: boolean;
-}
-
-export type ApiResponse<T> =
-  | { success: true; data: T }
-  | { success: false; error: string };
+export type VerificationState = 'PENDING' | 'VERIFIED' | 'REJECTED';
+
+export interface Solution {
+  id: string;
+  author_id: string;
+  query_title: string;
+  solution_body: string;
+  price_current: number;
+  verification_state: VerificationState;
+  access_count: number;
+  upvotes: number;
+  downvotes: number;
+}
+
+export interface FindSolutionResult {
+  solution_id: string;
+  query_title: string;
+  solution_body?: string;
+  human_verification_required: boolean;
+}
+
+export interface Balance {
+  available: number;
+  pending_debits: number;
+  pending_credits: number;
+  total_earned: number;
+  total_spent: number;
+}
+
+export interface User {
+  id: string;
+  email: string;
+  tigerbeetle_account_id: string;
+  is_blocked: boolean;
+}
+
+export type ApiResponse<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };