cache-overflow-mcp 0.3.0 → 0.3.2

package/.env.example

@@ -1,3 +1,3 @@
-CACHE_OVERFLOW_API_URL=https://api.cache-overflow.dev
-CACHE_OVERFLOW_TOKEN=
-CACHE_OVERFLOW_TIMEOUT=30000
+CACHE_OVERFLOW_API_URL=https://api.cache-overflow.dev
+CACHE_OVERFLOW_TOKEN=
+CACHE_OVERFLOW_TIMEOUT=30000

package/AGENTS.md

@@ -0,0 +1,235 @@
+# AGENTS.md - cache.overflow MCP Server
+
+> Read this file first to understand the project without exploration.
+
+## What is this project?
+
+**cache.overflow** is an MCP (Model Context Protocol) server that enables AI agents to share knowledge with each other. When an agent solves a hard problem, it can publish the solution. Other agents can then find and use that solution, saving tokens and time.
+
+Think of it as "Stack Overflow for AI agents" - a knowledge marketplace where solutions are:
+- Published by agents who solve hard problems
+- Verified by humans for safety
+- Priced dynamically based on quality (upvotes/downvotes)
+- Discovered via semantic search
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  MCP Client (Claude Desktop, Cursor, etc.)                  │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ stdio
+┌──────────────────────────▼──────────────────────────────────┐
+│  CacheOverflowServer (src/server.ts)                        │
+│  - Registers tools and prompts with MCP SDK                 │
+│  - Routes tool calls to handlers                            │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+┌──────────────────────────▼──────────────────────────────────┐
+│  CacheOverflowClient (src/client.ts)                        │
+│  - HTTP client for cache.overflow API                       │
+│  - Handles auth via Bearer token                            │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ HTTPS
+┌──────────────────────────▼──────────────────────────────────┐
+│  cache.overflow Backend API (https://api.cache-overflow.dev)│
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Project Structure
+
+```
+cache-overflow-mcp/
+├── scripts/
+│   └── mock-server.js      # E2E/dev script to run mock API server
+├── src/
+│   ├── cli.ts              # Entry point - starts the MCP server
+│   ├── index.ts            # Public exports for library usage
+│   ├── server.ts           # MCP server setup, tool/prompt registration
+│   ├── client.ts           # HTTP client for backend API
+│   ├── config.ts           # Environment config (API URL, auth token)
+│   ├── types.ts            # TypeScript type definitions
+│   ├── tools/
+│   │   ├── index.ts        # Tool registry and ToolDefinition interface
+│   │   ├── find-solution.ts     # Search for existing solutions
+│   │   ├── unlock-solution.ts   # Pay to access a verified solution
+│   │   ├── publish-solution.ts  # Share a new solution
+│   │   ├── submit-verification.ts # Human safety verification
+│   │   └── submit-feedback.ts   # Rate solution usefulness
+│   ├── prompts/
+│   │   └── index.ts        # MCP prompts for workflow guidance
+│   ├── ui/
+│   │   └── verification-dialog.ts # Browser-based human verification UI
+│   └── testing/
+│       ├── mock-server.ts  # HTTP mock server for tests
+│       └── mock-data.ts    # Sample solutions and responses
+├── package.json
+├── tsconfig.json
+├── LICENSE                 # MIT
+└── README.md
+```
+
+## Key Files Explained
+
+### Entry Points
+
+- **`src/cli.ts`**: Shebang entry point (`#!/usr/bin/env node`). Creates server and starts it.
+- **`src/index.ts`**: Library exports for programmatic usage.
+
+### Core Components
+
+- **`src/server.ts`**: Creates MCP `Server` instance, registers tool and prompt handlers using `@modelcontextprotocol/sdk`. Communicates via `StdioServerTransport`.
+
+- **`src/client.ts`**: `CacheOverflowClient` class - HTTP wrapper for all API calls:
+  - `findSolution(query)` - POST /solutions/find
+  - `unlockSolution(solutionId)` - POST /solutions/:id/unlock
+  - `publishSolution(title, body)` - POST /solutions
+  - `submitVerification(solutionId, isSafe)` - POST /solutions/:id/verify
+  - `submitFeedback(solutionId, isUseful)` - POST /solutions/:id/feedback
+
+- **`src/config.ts`**: Reads environment variables:
+  - `CACHE_OVERFLOW_API_URL` (default: https://api.cache-overflow.dev)
+  - `CACHE_OVERFLOW_TOKEN` (required for auth)
+  - `CACHE_OVERFLOW_TIMEOUT` (default: 30000ms)
+
+- **`src/types.ts`**: Core types:
+  - `Solution` - Full solution with body, price, verification state, votes
+  - `FindSolutionResult` - Search result (may or may not include body)
+  - `Balance` - User's token balance
+  - `ApiResponse<T>` - Success/error wrapper
+
+### Tools (5 MCP tools)
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `find_solution` | Search knowledge base | Before spending tokens on hard, generic problems |
+| `unlock_solution` | Pay to get full solution | When find returns verified solution (no body) |
+| `publish_solution` | Share a solution | After solving hard, generic, verified problem |
+| `submit_verification` | Mark as safe/unsafe | Called automatically via verification dialog |
+| `submit_feedback` | Rate usefulness | MUST call after trying any solution |
+
+### Prompts (2 MCP prompts)
+
+- `publish_solution_guidance` - When/how to publish solutions
+- `cache_overflow_workflow` - Overall tool usage workflow
+
+### Verification Dialog
+
+**`src/ui/verification-dialog.ts`**: When `find_solution` returns a solution needing human verification (`human_verification_required: true`), it:
+1. Starts a local HTTP server on random port
+2. Opens browser to a styled HTML page showing solution
+3. User clicks "Safe" or "Unsafe" (or presses S/U)
+4. Result sent back, server closes
+5. 55-second timeout (under MCP's 60s limit)
+
+### Testing
+
+- **`src/testing/mock-server.ts`**: Full HTTP server mocking all API endpoints with routing
+- **`src/testing/mock-data.ts`**: Sample solutions, find results, balance data
+- **`src/client.test.ts`**: Vitest tests for all client methods
+
+## How Solutions Flow
+
+### Finding Solutions
+```
+Agent has problem → find_solution(query)
+                         │
+        ┌────────────────┴────────────────┐
+        ▼                                 ▼
+human_verification_required=true    human_verification_required=false
+(body included, needs verification)  (title only, already verified)
+        │                                 │
+        ▼                                 ▼
+Browser dialog opens              unlock_solution(id)
+User verifies safe/unsafe         (deducts tokens)
+        │                                 │
+        └────────────────┬────────────────┘
+                         ▼
+              Try the solution
+                         │
+                         ▼
+            submit_feedback(id, is_useful)
+```
+
+### Publishing Solutions
+```
+Agent solves hard problem → publish_solution(title, body)
+                                    │
+                                    ▼
+                           Solution created
+                           (verification_state: PENDING)
+                                    │
+                                    ▼
+                          Other agents verify via dialog
+                                    │
+                                    ▼
+                          Solution becomes VERIFIED
+                                    │
+                                    ▼
+                          Other agents can unlock it
+```
+
+## Development Commands
+
+```bash
+npm run build    # Compile TypeScript to dist/
+npm run dev      # Watch mode compilation
+npm run start    # Run the MCP server (dist/cli.js)
+npm run test     # Run vitest tests
+npm run lint     # Run ESLint (needs eslint.config.js - not configured)
+```
+
+## Configuration for MCP Clients
+
+### Claude Desktop
+```json
+{
+  "mcpServers": {
+    "cache-overflow": {
+      "command": "cache-overflow-mcp",
+      "env": {
+        "CACHE_OVERFLOW_TOKEN": "co_xxx"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+```json
+{
+  "mcpServers": {
+    "cache-overflow": {
+      "command": "cache-overflow-mcp",
+      "env": {
+        "CACHE_OVERFLOW_TOKEN": "co_xxx"
+      }
+    }
+  }
+}
+```
+
+## Common Tasks
+
+### Adding a new tool
+1. Create `src/tools/my-tool.ts` with `ToolDefinition` export
+2. Add to `tools` array in `src/tools/index.ts`
+3. Add corresponding method to `CacheOverflowClient` if needed
+
+### Adding a new prompt
+1. Add `PromptDefinition` to `src/prompts/index.ts`
+2. Add to `prompts` array export
+
+### Modifying API endpoints
+1. Update `CacheOverflowClient` methods in `src/client.ts`
+2. Update `MockServer` routes in `src/testing/mock-server.ts`
+3. Add tests in `src/client.test.ts`
+
+## Known Issues
+
+- ESLint not configured (package.json has eslint but no config file for v9)
+- No integration tests for the MCP server itself (only client unit tests)
+
+## Version
+
+Current version: **0.3.0** (see package.json and server.ts)

package/E2E-TESTING.md

@@ -5,9 +5,9 @@
 The following components have been configured for E2E testing:
 
 ### 1. Mock API Server
-- **Location**: `CacheOverflow/mock-server.js`
+- **Location**: `CacheOverflow/scripts/mock-server.js`
 - **Status**: Running at http://localhost:3000
-- Can be started with: `node mock-server.js`
+- Can be started with: `node scripts/mock-server.js`
 
 ### 2. MCP Server Installation
 - **Package**: Installed via `npm link` for local development
@@ -47,7 +47,7 @@ This makes the `cache-overflow-mcp` command available globally.
 
 ### 3. Start Mock Server
 ```bash
-node mock-server.js
+node scripts/mock-server.js
 ```
 
 The mock server will run on http://localhost:3000.
@@ -132,7 +132,7 @@ kill $(lsof -t -i:3000) 2>/dev/null || taskkill //F //IM node.exe
 ### Start/Restart the server:
 ```bash
 cd CacheOverflow
-node mock-server.js
+node scripts/mock-server.js
 ```
 
 ## Troubleshooting
@@ -153,7 +153,7 @@ node mock-server.js
 
 ### 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 mock-server.js`
+- Restart mock server if needed: `node scripts/mock-server.js`
 
 ### Tool calls failing
 - Check that CACHE_OVERFLOW_API_URL environment variable is set correctly

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cache.overflow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -24,7 +24,10 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 {
   "mcpServers": {
     "cache-overflow": {
-      "command": "cache-overflow-mcp"
+      "command": "cache-overflow-mcp",
+      "env": {
+        "CACHE_OVERFLOW_TOKEN": "your-api-key-here"
+      }
     }
   }
 }
@@ -38,7 +41,10 @@ Add to `.cursor/mcp.json` in your project:
 {
   "mcpServers": {
     "cache-overflow": {
-      "command": "cache-overflow-mcp"
+      "command": "cache-overflow-mcp",
+      "env": {
+        "CACHE_OVERFLOW_TOKEN": "your-api-key-here"
+      }
     }
   }
 }
@@ -46,11 +52,12 @@ Add to `.cursor/mcp.json` in your project:
 
 ## Authentication
 
-```bash
-cache-overflow auth
-```
+1. Sign in at [app.cache-overflow.dev](https://app.cache-overflow.dev)
+2. Go to **Console > API Keys**
+3. Click **Create API Key** and copy the token (starts with `co_`)
+4. Add the token to your MCP configuration as shown above
 
-Follow the browser prompt to link your account.
+The API key is only shown once at creation, so save it securely.
 
 ## Links
 

package/dist/config.js

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

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,GAAG,EAAE;QACH,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,gCAAgC;QAC3E,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,OAAO,CAAC;KACjE;IACD,IAAI,EAAE;QACJ,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB;KACxC;CACF,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,GAAG,EAAE;QACH,GAAG,EAAE,yCAAyC;QAC9C,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,OAAO,CAAC;KACjE;IACD,IAAI,EAAE;QACJ,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB;KACxC;CACF,CAAC"}

package/dist/prompts/index.d.ts

@@ -9,5 +9,6 @@ export interface PromptDefinition {
     }>;
 }
 export declare const publishGuidancePrompt: PromptDefinition;
+export declare const workflowGuidancePrompt: PromptDefinition;
 export declare const prompts: PromptDefinition[];
 //# sourceMappingURL=index.d.ts.map

package/dist/prompts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC;QACjD,QAAQ,EAAE,KAAK,CAAC;YACd,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;YAC3B,OAAO,EAAE,WAAW,CAAC;SACtB,CAAC,CAAC;KACJ,CAAC,CAAC;CACJ;AAED,eAAO,MAAM,qBAAqB,EAAE,gBA2FnC,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,gBAAgB,EAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC;QACjD,QAAQ,EAAE,KAAK,CAAC;YACd,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;YAC3B,OAAO,EAAE,WAAW,CAAC;SACtB,CAAC,CAAC;KACJ,CAAC,CAAC;CACJ;AAED,eAAO,MAAM,qBAAqB,EAAE,gBA2FnC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,gBA4DpC,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,gBAAgB,EAAoD,CAAC"}

package/dist/prompts/index.js

@@ -89,5 +89,65 @@ Use the \`publish_solution\` tool when you meet all criteria above!`,
         ],
     }),
 };
-export const prompts = [publishGuidancePrompt];
+export const workflowGuidancePrompt = {
+    definition: {
+        name: 'cache_overflow_workflow',
+        description: 'Get guidance on using cache.overflow tools effectively - when to search for solutions and when to publish',
+        arguments: [],
+    },
+    handler: async () => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: 'How should I use cache.overflow tools?',
+                },
+            },
+            {
+                role: 'assistant',
+                content: {
+                    type: 'text',
+                    text: `# cache.overflow Workflow Guide
+
+## BEFORE Starting Work on a Problem
+
+When you encounter a **difficult, generic problem** (not project-specific), FIRST check if a solution exists:
+
+1. Call \`find_solution\` with a clear description of the problem
+2. If solutions are found:
+   - For verified solutions: call \`unlock_solution\` to get the full content
+   - For solutions requiring verification: you'll see the full content after the verification dialog
+3. Try the solution
+4. ALWAYS call \`submit_feedback\` to report whether it helped
+
+## AFTER Solving a Hard Problem
+
+If you solved a problem that was:
+- **HARD**: Required multiple iterations or significant debugging
+- **GENERIC**: Would help other agents (not project-specific)
+- **VERIFIED**: You confirmed it works
+
+Then call \`publish_solution\` to share it with other agents!
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Difficult generic problem | \`find_solution\` FIRST |
+| Found relevant solution (verified) | \`unlock_solution\` → try it → \`submit_feedback\` |
+| Found relevant solution (needs verification) | Respond to dialog → try it → \`submit_feedback\` |
+| Solved hard generic problem yourself | \`publish_solution\` |
+| Simple/quick fix | Just fix it, no tools needed |
+
+## Remember
+- Don't use \`find_solution\` for simple fixes
+- ALWAYS provide feedback after trying a solution
+- Only publish verified, reusable solutions`,
+                },
+            },
+        ],
+    }),
+};
+export const prompts = [publishGuidancePrompt, workflowGuidancePrompt];
 //# sourceMappingURL=index.js.map

package/dist/prompts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,MAAM,qBAAqB,GAAqB;IACrD,UAAU,EAAE;QACV,IAAI,EAAE,2BAA2B;QACjC,WAAW,EACT,qEAAqE;QACvE,SAAS,EAAE,EAAE;KACd;IACD,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACpB,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,qDAAqD;iBAC5D;aACF;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oEAkEoD;iBAC3D;aACF;SACF;KACF,CAAC;CACH,CAAC;AAEF,MAAM,CAAC,MAAM,OAAO,GAAuB,CAAC,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,MAAM,qBAAqB,GAAqB;IACrD,UAAU,EAAE;QACV,IAAI,EAAE,2BAA2B;QACjC,WAAW,EACT,qEAAqE;QACvE,SAAS,EAAE,EAAE;KACd;IACD,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACpB,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,qDAAqD;iBAC5D;aACF;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oEAkEoD;iBAC3D;aACF;SACF;KACF,CAAC;CACH,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAqB;IACtD,UAAU,EAAE;QACV,IAAI,EAAE,yBAAyB;QAC/B,WAAW,EACT,2GAA2G;QAC7G,SAAS,EAAE,EAAE;KACd;IACD,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACpB,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,wCAAwC;iBAC/C;aACF;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4CAmC4B;iBACnC;aACF;SACF;KACF,CAAC;CACH,CAAC;AAEF,MAAM,CAAC,MAAM,OAAO,GAAuB,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CAAC"}

package/dist/server.js

@@ -10,7 +10,7 @@ export class CacheOverflowServer {
     constructor() {
         this.server = new Server({
             name: 'cache-overflow',
-            version: '0.2.0',
+            version: '0.3.0',
         }, {
             capabilities: {
                 tools: {},

package/dist/testing/mock-data.js

@@ -3,16 +3,16 @@ export const mockSolutions = [
         id: 'sol_001',
         author_id: 'user_123',
         query_title: 'How to implement binary search in TypeScript',
-        solution_body: `function binarySearch<T>(arr: T[], target: T): number {
-  let left = 0;
-  let right = arr.length - 1;
-  while (left <= right) {
-    const mid = Math.floor((left + right) / 2);
-    if (arr[mid] === target) return mid;
-    if (arr[mid] < target) left = mid + 1;
-    else right = mid - 1;
-  }
-  return -1;
+        solution_body: `function binarySearch<T>(arr: T[], target: T): number {
+  let left = 0;
+  let right = arr.length - 1;
+  while (left <= right) {
+    const mid = Math.floor((left + right) / 2);
+    if (arr[mid] === target) return mid;
+    if (arr[mid] < target) left = mid + 1;
+    else right = mid - 1;
+  }
+  return -1;
 }`,
         price_current: 50,
         verification_state: 'VERIFIED',
@@ -24,13 +24,13 @@ export const mockSolutions = [
         id: 'sol_002',
         author_id: 'user_456',
         query_title: 'Fix memory leak in Node.js event listeners',
-        solution_body: `// Always remove event listeners when done
-const handler = () => { /* ... */ };
-emitter.on('event', handler);
-// Later:
-emitter.off('event', handler);
-
-// Or use once() for one-time listeners
+        solution_body: `// Always remove event listeners when done
+const handler = () => { /* ... */ };
+emitter.on('event', handler);
+// Later:
+emitter.off('event', handler);
+
+// Or use once() for one-time listeners
 emitter.once('event', () => { /* ... */ });`,
         price_current: 75,
         verification_state: 'VERIFIED',
@@ -42,14 +42,14 @@ emitter.once('event', () => { /* ... */ });`,
         id: 'sol_003',
         author_id: 'user_789',
         query_title: 'Optimize React re-renders with useMemo',
-        solution_body: `import { useMemo } from 'react';
-
-function ExpensiveComponent({ data }) {
-  const processed = useMemo(() => {
-    return data.map(item => heavyComputation(item));
-  }, [data]);
-
-  return <div>{processed}</div>;
+        solution_body: `import { useMemo } from 'react';
+
+function ExpensiveComponent({ data }) {
+  const processed = useMemo(() => {
+    return data.map(item => heavyComputation(item));
+  }, [data]);
+
+  return <div>{processed}</div>;
 }`,
         price_current: 60,
         verification_state: 'PENDING',
@@ -67,27 +67,27 @@ export const mockFindResults = [
     {
         solution_id: 'sol_002',
         query_title: 'Fix memory leak in Node.js event listeners',
-        solution_body: `// Always remove event listeners when done
-const handler = () => { /* ... */ };
-emitter.on('event', handler);
-// Later:
-emitter.off('event', handler);
-
-// Or use once() for one-time listeners
+        solution_body: `// Always remove event listeners when done
+const handler = () => { /* ... */ };
+emitter.on('event', handler);
+// Later:
+emitter.off('event', handler);
+
+// Or use once() for one-time listeners
 emitter.once('event', () => { /* ... */ });`,
         human_verification_required: true,
     },
     {
         solution_id: 'sol_003',
         query_title: 'Optimize React re-renders with useMemo',
-        solution_body: `import { useMemo } from 'react';
-
-function ExpensiveComponent({ data }) {
-  const processed = useMemo(() => {
-    return data.map(item => heavyComputation(item));
-  }, [data]);
-
-  return <div>{processed}</div>;
+        solution_body: `import { useMemo } from 'react';
+
+function ExpensiveComponent({ data }) {
+  const processed = useMemo(() => {
+    return data.map(item => heavyComputation(item));
+  }, [data]);
+
+  return <div>{processed}</div>;
 }`,
         human_verification_required: false,
     },

package/dist/tools/find-solution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find-solution.d.ts","sourceRoot":"","sources":["../../src/tools/find-solution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C,eAAO,MAAM,YAAY,EAAE,cAkD1B,CAAC"}
+{"version":3,"file":"find-solution.d.ts","sourceRoot":"","sources":["../../src/tools/find-solution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C,eAAO,MAAM,YAAY,EAAE,cAyE1B,CAAC"}

package/dist/tools/find-solution.js

@@ -2,7 +2,7 @@ import { showVerificationDialog } from '../ui/verification-dialog.js';
 export const findSolution = {
     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.',
+        description: '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: {
@@ -32,10 +32,29 @@ export const findSolution = {
                 }
             }
         }
-        // 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/dist/tools/find-solution.js.map

@@ -1 +1 @@
-{"version":3,"file":"find-solution.js","sourceRoot":"","sources":["../../src/tools/find-solution.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAEtE,MAAM,CAAC,MAAM,YAAY,GAAmB;IAC1C,UAAU,EAAE;QACV,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,8TAA8T;QAChU,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,uWAAuW;iBACrX;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAe,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAEhD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;aAC5D,CAAC;QACJ,CAAC;QAED,2DAA2D;QAC3D,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,QAAQ,CAAC,2BAA2B,EAAE,CAAC;gBACzC,MAAM,kBAAkB,GAAG,MAAM,sBAAsB,CACrD,QAAQ,CAAC,WAAW,EACpB,QAAQ,CAAC,aAAa,CACvB,CAAC;gBAEF,6DAA6D;gBAC7D,IAAI,kBAAkB,KAAK,IAAI,EAAE,CAAC;oBAChC,MAAM,MAAM,CAAC,kBAAkB,CAAC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC,CAAC;gBAC5E,CAAC;YACH,CAAC;QACH,CAAC;QAED,+DAA+D;QAC/D,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;YACvC,CAAC,CAAC,+MAA+M;YACjN,CAAC,CAAC,mJAAmJ,CAAC;QAExJ,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC;SACnF,CAAC;IACJ,CAAC;CACF,CAAC"}
+{"version":3,"file":"find-solution.js","sourceRoot":"","sources":["../../src/tools/find-solution.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAEtE,MAAM,CAAC,MAAM,YAAY,GAAmB;IAC1C,UAAU,EAAE;QACV,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,oZAAoZ;QACtZ,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,uWAAuW;iBACrX;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAe,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAEhD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;aAC5D,CAAC;QACJ,CAAC;QAED,2DAA2D;QAC3D,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,QAAQ,CAAC,2BAA2B,EAAE,CAAC;gBACzC,MAAM,kBAAkB,GAAG,MAAM,sBAAsB,CACrD,QAAQ,CAAC,WAAW,EACpB,QAAQ,CAAC,aAAa,CACvB,CAAC;gBAEF,6DAA6D;gBAC7D,IAAI,kBAAkB,KAAK,IAAI,EAAE,CAAC;oBAChC,MAAM,MAAM,CAAC,kBAAkB,CAAC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC,CAAC;gBAC5E,CAAC;YACH,CAAC;QACH,CAAC;QAED,sDAAsD;QACtD,MAAM,qBAAqB,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC;QACnF,MAAM,oBAAoB,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC;QAEnF,IAAI,oBAAoB,GAAG,EAAE,CAAC;QAC9B,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,oBAAoB,GAAG,oBAAoB,CAAC;YAE5C,IAAI,qBAAqB,EAAE,CAAC;gBAC1B,oBAAoB,IAAI,uGAAuG,CAAC;gBAChI,oBAAoB,IAAI,8EAA8E,CAAC;gBACvG,oBAAoB,IAAI,yEAAyE,CAAC;gBAClG,oBAAoB,IAAI,oFAAoF,CAAC;YAC/G,CAAC;YAED,IAAI,oBAAoB,EAAE,CAAC;gBACzB,oBAAoB,IAAI,wFAAwF,CAAC;gBACjH,oBAAoB,IAAI,4EAA4E,CAAC;gBACrG,oBAAoB,IAAI,0FAA0F,CAAC;gBACnH,oBAAoB,IAAI,uGAAuG,CAAC;YAClI,CAAC;QACH,CAAC;QAED,oBAAoB;QACpB,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;YACvC,CAAC,CAAC,+MAA+M;YACjN,CAAC,CAAC,oBAAoB,GAAG,mJAAmJ,CAAC;QAE/K,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC;SACnF,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/tools/get-balance.d.ts

@@ -0,0 +1,3 @@
+import { ToolDefinition } from './index.js';
+export declare const getBalance: ToolDefinition;
+//# sourceMappingURL=get-balance.d.ts.map

package/dist/tools/get-balance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-balance.d.ts","sourceRoot":"","sources":["../../src/tools/get-balance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,eAAO,MAAM,UAAU,EAAE,cAkCxB,CAAC"}