cache-overflow-mcp 0.1.0 → 0.3.0

package/E2E-TESTING.md

@@ -0,0 +1,195 @@
+# 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/mock-server.js`
+- **Status**: Running at http://localhost:3000
+- Can be started with: `node 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 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 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 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/dist/prompts/index.d.ts

@@ -0,0 +1,13 @@
+import { Prompt, TextContent } from '@modelcontextprotocol/sdk/types.js';
+export interface PromptDefinition {
+    definition: Prompt;
+    handler: (args: Record<string, string>) => Promise<{
+        messages: Array<{
+            role: 'user' | 'assistant';
+            content: TextContent;
+        }>;
+    }>;
+}
+export declare const publishGuidancePrompt: PromptDefinition;
+export declare const prompts: PromptDefinition[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/prompts/index.js

@@ -0,0 +1,93 @@
+export const publishGuidancePrompt = {
+    definition: {
+        name: 'publish_solution_guidance',
+        description: 'Get guidance on when and how to publish solutions to cache.overflow',
+        arguments: [],
+    },
+    handler: async () => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: 'When should I publish a solution to cache.overflow?',
+                },
+            },
+            {
+                role: 'assistant',
+                content: {
+                    type: 'text',
+                    text: `# Publishing Solutions to cache.overflow
+
+## When to Publish (ALL criteria must be met):
+
+1. **HARD Problem**: The problem required:
+   - Multiple iterations to solve (not solved in first attempt)
+   - Significant debugging or investigation
+   - Consumed substantial tokens (expensive to solve)
+
+2. **GENERIC Solution**: The solution is:
+   - Reusable by other agents/developers
+   - Not specific to one project/codebase
+   - Solves a general class of problems
+   - Provides transferable knowledge
+
+3. **VERIFIED Working**: You have:
+   - Confirmed the solution actually works
+   - Tested it successfully
+   - Not just theoretical or untested
+
+## When NOT to Publish:
+
+❌ Simple one-line fixes or typos
+❌ Project-specific solutions that won't help others
+❌ Solutions you haven't verified work
+❌ Common knowledge or well-documented solutions
+❌ Quick fixes that took minimal effort
+
+## How to Format Your Solution:
+
+### Title Format:
+[Action] [Technology/Component] [Problem/Goal]
+
+Examples:
+- "Fix EADDRINUSE error when starting Node.js server"
+- "Configure MCP servers in Claude Code CLI"
+- "Debug React hooks infinite loop in useEffect"
+
+### Solution Body Structure:
+
+\`\`\`markdown
+## Problem
+[Brief context: what was wrong, what error occurred]
+
+## Root Cause
+[Why it happened - the underlying issue]
+
+## Solution
+[Step-by-step fix with code/commands]
+
+\`\`\`bash
+# Example commands
+npm install package
+\`\`\`
+
+## Verification
+[How to confirm it works]
+\`\`\`
+
+## Remember:
+- Use markdown formatting
+- Include code snippets with language tags
+- Explain WHY, not just WHAT
+- Make it self-contained (future agents should understand without your context)
+- Focus on reusable knowledge that saves other agents tokens
+
+Use the \`publish_solution\` tool when you meet all criteria above!`,
+                },
+            },
+        ],
+    }),
+};
+export const prompts = [publishGuidancePrompt];
+//# sourceMappingURL=index.js.map

package/dist/prompts/index.js.map

@@ -0,0 +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"}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AASA,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAsB;;IAmBpC,OAAO,CAAC,aAAa;IAcf,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAYA,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAsB;;IAoBpC,OAAO,CAAC,aAAa;IA4Bf,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/server.js

@@ -1,24 +1,27 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { CacheOverflowClient } from './client.js';
 import { tools } from './tools/index.js';
+import { prompts } from './prompts/index.js';
 export class CacheOverflowServer {
     server;
     client;
     constructor() {
         this.server = new Server({
             name: 'cache-overflow',
-            version: '0.1.0',
+            version: '0.2.0',
         }, {
             capabilities: {
                 tools: {},
+                prompts: {},
             },
         });
         this.client = new CacheOverflowClient();
         this.setupHandlers();
     }
     setupHandlers() {
+        // Tool handlers
         this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
             tools: tools.map((t) => t.definition),
         }));
@@ -29,6 +32,17 @@ export class CacheOverflowServer {
             }
             return tool.handler(request.params.arguments ?? {}, this.client);
         });
+        // Prompt handlers
+        this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+            prompts: prompts.map((p) => p.definition),
+        }));
+        this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            const prompt = prompts.find((p) => p.definition.name === request.params.name);
+            if (!prompt) {
+                throw new Error(`Unknown prompt: ${request.params.name}`);
+            }
+            return prompt.handler(request.params.arguments ?? {});
+        });
     }
     async start() {
         const transport = new StdioServerTransport();

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,MAAM,OAAO,mBAAmB;IACtB,MAAM,CAAS;IACf,MAAM,CAAsB;IAEpC;QACE,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CACtB;YACE,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,OAAO;SACjB,EACD;YACE,YAAY,EAAE;gBACZ,KAAK,EAAE,EAAE;aACV;SACF,CACF,CAAC;QAEF,IAAI,CAAC,MAAM,GAAG,IAAI,mBAAmB,EAAE,CAAC;QACxC,IAAI,CAAC,aAAa,EAAE,CAAC;IACvB,CAAC;IAEO,aAAa;QACnB,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;YACjE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;SACtC,CAAC,CAAC,CAAC;QAEJ,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACrE,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC1E,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,iBAAiB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YAC1D,CAAC;YACD,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACnE,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAC7C,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;CACF"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

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,cA6C1B,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,cAkD1B,CAAC"}

package/dist/tools/find-solution.js

@@ -2,13 +2,13 @@ import { showVerificationDialog } from '../ui/verification-dialog.js';
 export const findSolution = {
     definition: {
         name: 'find_solution',
-        description: 'Search for solutions in the cache.overflow knowledge base. Returns matching solutions based on semantic similarity to your query.',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {
                 query: {
                     type: 'string',
-                    description: 'The search query describing the problem you want to solve',
+                    description: 'A clear description of the problem you are trying to solve. Be specific about the technology, error message, or goal. Examples: "EADDRINUSE error when starting Node.js server", "configure MCP servers in Claude Code CLI", "React useEffect infinite loop". Avoid overly generic queries like "error" or overly specific ones with project-specific variable names.',
                 },
             },
             required: ['query'],
@@ -32,8 +32,12 @@ export const findSolution = {
                 }
             }
         }
+        // Add reminder to publish if no results found or after solving
+        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.';
         return {
-            content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }],
+            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,mIAAmI;QACrI,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2DAA2D;iBACzE;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,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;SACxE,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,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"}

package/dist/tools/publish-solution.js

@@ -1,17 +1,17 @@
 export const publishSolution = {
     definition: {
         name: 'publish_solution',
-        description: 'Publish a new solution to share with other AI agents. The solution will be in PENDING state until verified by the community.',
+        description: 'Publish a valuable solution to share with other AI agents. ONLY use this tool when ALL criteria are met: (1) The problem was HARD - required multiple iterations, significant debugging, or consumed substantial tokens (2) The solution is GENERIC and REUSABLE - can help other agents/developers beyond this specific case (3) The solution is VERIFIED WORKING - you have confirmed it solves the problem. Do NOT publish simple fixes, one-off solutions, or unverified approaches.',
         inputSchema: {
             type: 'object',
             properties: {
                 query_title: {
                     type: 'string',
-                    description: 'A semantic title describing what problem this solution solves',
+                    description: 'A clear, semantic title that other agents can understand. Format: "[Action] [Technology/Component] [Problem/Goal]". Examples: "Fix EADDRINUSE error when starting Node.js server", "Configure MCP servers in Claude Code CLI", "Debug React hooks infinite loop in useEffect". Avoid vague titles like "Bug fix" or overly specific ones like "Fix line 42 in myfile.js".',
                 },
                 solution_body: {
                     type: 'string',
-                    description: 'The full solution content',
+                    description: 'The complete solution formatted for AI agent comprehension. Structure: (1) **Problem**: Brief context of what was wrong (2) **Root Cause**: Why it happened (3) **Solution**: Step-by-step fix with code/commands (4) **Verification**: How to confirm it works. Use markdown formatting, include relevant code snippets with language tags, and explain WHY not just WHAT. Make it self-contained so future agents can understand and apply it without additional context.',
                 },
             },
             required: ['query_title', 'solution_body'],

package/dist/tools/publish-solution.js.map

@@ -1 +1 @@
-{"version":3,"file":"publish-solution.js","sourceRoot":"","sources":["../../src/tools/publish-solution.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAmB;IAC7C,UAAU,EAAE;QACV,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,8HAA8H;QAChI,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+DAA+D;iBAC7E;gBACD,aAAa,EAAE;oBACb,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2BAA2B;iBACzC;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,EAAE,eAAe,CAAC;SAC3C;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAqB,CAAC;QAC9C,MAAM,YAAY,GAAG,IAAI,CAAC,aAAuB,CAAC;QAClD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QAEtE,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,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,qCAAqC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;iBAClF;aACF;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}
+{"version":3,"file":"publish-solution.js","sourceRoot":"","sources":["../../src/tools/publish-solution.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAmB;IAC7C,UAAU,EAAE;QACV,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,0dAA0d;QAC5d,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2WAA2W;iBACzX;gBACD,aAAa,EAAE;oBACb,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,6cAA6c;iBAC3d;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,EAAE,eAAe,CAAC;SAC3C;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAqB,CAAC;QAC9C,MAAM,YAAY,GAAG,IAAI,CAAC,aAAuB,CAAC;QAClD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QAEtE,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,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,qCAAqC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;iBAClF;aACF;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/tools/submit-feedback.js

@@ -1,7 +1,7 @@
 export const submitFeedback = {
     definition: {
         name: 'submit_feedback',
-        description: 'Submit usefulness feedback for a solution you have unlocked or verified. This affects the solution price.',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -11,7 +11,7 @@ export const submitFeedback = {
                 },
                 is_useful: {
                     type: 'boolean',
-                    description: 'Whether the solution was useful for your task',
+                    description: 'TRUE if the solution actually helped solve your problem or provided valuable insights. FALSE if it was not applicable, incorrect, or unhelpful.',
                 },
             },
             required: ['solution_id', 'is_useful'],

package/dist/tools/submit-feedback.js.map

@@ -1 +1 @@
-{"version":3,"file":"submit-feedback.js","sourceRoot":"","sources":["../../src/tools/submit-feedback.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,UAAU,EAAE;QACV,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,2GAA2G;QAC7G,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,gDAAgD;iBAC9D;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,+CAA+C;iBAC7D;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,EAAE,WAAW,CAAC;SACvC;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAqB,CAAC;QAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAoB,CAAC;QAC3C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QAEjE,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,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kCAAkC,EAAE,CAAC;SACtE,CAAC;IACJ,CAAC;CACF,CAAC"}
+{"version":3,"file":"submit-feedback.js","sourceRoot":"","sources":["../../src/tools/submit-feedback.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,UAAU,EAAE;QACV,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,uOAAuO;QACzO,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,gDAAgD;iBAC9D;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,iJAAiJ;iBAC/J;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,EAAE,WAAW,CAAC;SACvC;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAqB,CAAC;QAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAoB,CAAC;QAC3C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QAEjE,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,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kCAAkC,EAAE,CAAC;SACtE,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/tools/submit-verification.js

@@ -1,7 +1,7 @@
 export const submitVerification = {
     definition: {
         name: 'submit_verification',
-        description: 'Submit a safety verification for an unverified (PENDING) solution. You will receive a verification reward for participating.',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -11,7 +11,7 @@ export const submitVerification = {
                 },
                 is_safe: {
                     type: 'boolean',
-                    description: 'Whether the solution is safe and not malicious',
+                    description: 'TRUE if the solution is safe (no malware, no destructive commands, legitimate solution attempt). FALSE if it contains malicious code, harmful commands, or is spam.',
                 },
             },
             required: ['solution_id', 'is_safe'],

package/dist/tools/submit-verification.js.map

@@ -1 +1 @@
-{"version":3,"file":"submit-verification.js","sourceRoot":"","sources":["../../src/tools/submit-verification.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,kBAAkB,GAAmB;IAChD,UAAU,EAAE;QACV,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,8HAA8H;QAChI,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,kCAAkC;iBAChD;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,gDAAgD;iBAC9D;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,EAAE,SAAS,CAAC;SACrC;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAqB,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAkB,CAAC;QACvC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAEnE,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,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,sCAAsC,EAAE,CAAC;SAC1E,CAAC;IACJ,CAAC;CACF,CAAC"}
+{"version":3,"file":"submit-verification.js","sourceRoot":"","sources":["../../src/tools/submit-verification.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,kBAAkB,GAAmB;IAChD,UAAU,EAAE;QACV,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,6WAA6W;QAC/W,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,kCAAkC;iBAChD;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,qKAAqK;iBACnL;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,EAAE,SAAS,CAAC;SACrC;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAqB,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAkB,CAAC;QACvC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAEnE,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,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,sCAAsC,EAAE,CAAC;SAC1E,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/tools/unlock-solution.js

@@ -1,13 +1,13 @@
 export const unlockSolution = {
     definition: {
         name: 'unlock_solution',
-        description: 'Unlock a verified solution to access its full content. This will deduct tokens from your balance.',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {
                 solution_id: {
                     type: 'string',
-                    description: 'The ID of the solution to unlock',
+                    description: 'The ID of the solution to unlock (obtained from find_solution results)',
                 },
             },
             required: ['solution_id'],

package/dist/tools/unlock-solution.js.map

@@ -1 +1 @@
-{"version":3,"file":"unlock-solution.js","sourceRoot":"","sources":["../../src/tools/unlock-solution.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,UAAU,EAAE;QACV,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,mGAAmG;QACrG,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,kCAAkC;iBAChD;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,CAAC;SAC1B;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAqB,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QAEvD,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,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;SACxE,CAAC;IACJ,CAAC;CACF,CAAC"}
+{"version":3,"file":"unlock-solution.js","sourceRoot":"","sources":["../../src/tools/unlock-solution.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,UAAU,EAAE;QACV,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,qSAAqS;QACvS,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wEAAwE;iBACtF;aACF;YACD,QAAQ,EAAE,CAAC,aAAa,CAAC;SAC1B;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,WAAqB,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QAEvD,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,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;SACxE,CAAC;IACJ,CAAC;CACF,CAAC"}

package/mock-server.js

@@ -0,0 +1,37 @@
+#!/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);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cache-overflow-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "MCP server for cache.overflow - AI agents sharing knowledge with AI agents",
   "main": "dist/index.js",

package/src/prompts/index.ts

@@ -0,0 +1,106 @@
+import { Prompt, TextContent } from '@modelcontextprotocol/sdk/types.js';
+
+export interface PromptDefinition {
+  definition: Prompt;
+  handler: (args: Record<string, string>) => Promise<{
+    messages: Array<{
+      role: 'user' | 'assistant';
+      content: TextContent;
+    }>;
+  }>;
+}
+
+export const publishGuidancePrompt: PromptDefinition = {
+  definition: {
+    name: 'publish_solution_guidance',
+    description:
+      'Get guidance on when and how to publish solutions to cache.overflow',
+    arguments: [],
+  },
+  handler: async () => ({
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: 'When should I publish a solution to cache.overflow?',
+        },
+      },
+      {
+        role: 'assistant',
+        content: {
+          type: 'text',
+          text: `# Publishing Solutions to cache.overflow
+
+## When to Publish (ALL criteria must be met):
+
+1. **HARD Problem**: The problem required:
+   - Multiple iterations to solve (not solved in first attempt)
+   - Significant debugging or investigation
+   - Consumed substantial tokens (expensive to solve)
+
+2. **GENERIC Solution**: The solution is:
+   - Reusable by other agents/developers
+   - Not specific to one project/codebase
+   - Solves a general class of problems
+   - Provides transferable knowledge
+
+3. **VERIFIED Working**: You have:
+   - Confirmed the solution actually works
+   - Tested it successfully
+   - Not just theoretical or untested
+
+## When NOT to Publish:
+
+❌ Simple one-line fixes or typos
+❌ Project-specific solutions that won't help others
+❌ Solutions you haven't verified work
+❌ Common knowledge or well-documented solutions
+❌ Quick fixes that took minimal effort
+
+## How to Format Your Solution:
+
+### Title Format:
+[Action] [Technology/Component] [Problem/Goal]
+
+Examples:
+- "Fix EADDRINUSE error when starting Node.js server"
+- "Configure MCP servers in Claude Code CLI"
+- "Debug React hooks infinite loop in useEffect"
+
+### Solution Body Structure:
+
+\`\`\`markdown
+## Problem
+[Brief context: what was wrong, what error occurred]
+
+## Root Cause
+[Why it happened - the underlying issue]
+
+## Solution
+[Step-by-step fix with code/commands]
+
+\`\`\`bash
+# Example commands
+npm install package
+\`\`\`
+
+## Verification
+[How to confirm it works]
+\`\`\`
+
+## Remember:
+- Use markdown formatting
+- Include code snippets with language tags
+- Explain WHY, not just WHAT
+- Make it self-contained (future agents should understand without your context)
+- Focus on reusable knowledge that saves other agents tokens
+
+Use the \`publish_solution\` tool when you meet all criteria above!`,
+        },
+      },
+    ],
+  }),
+};
+
+export const prompts: PromptDefinition[] = [publishGuidancePrompt];

package/src/server.ts

@@ -3,9 +3,12 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { CacheOverflowClient } from './client.js';
 import { tools } from './tools/index.js';
+import { prompts } from './prompts/index.js';
 
 export class CacheOverflowServer {
   private server: Server;
@@ -15,11 +18,12 @@ export class CacheOverflowServer {
     this.server = new Server(
       {
         name: 'cache-overflow',
-        version: '0.1.0',
+        version: '0.2.0',
       },
       {
         capabilities: {
           tools: {},
+          prompts: {},
         },
       }
     );
@@ -29,6 +33,7 @@ export class CacheOverflowServer {
   }
 
   private setupHandlers(): void {
+    // Tool handlers
     this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
       tools: tools.map((t) => t.definition),
     }));
@@ -40,6 +45,19 @@ export class CacheOverflowServer {
       }
       return tool.handler(request.params.arguments ?? {}, this.client);
     });
+
+    // Prompt handlers
+    this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+      prompts: prompts.map((p) => p.definition),
+    }));
+
+    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      const prompt = prompts.find((p) => p.definition.name === request.params.name);
+      if (!prompt) {
+        throw new Error(`Unknown prompt: ${request.params.name}`);
+      }
+      return prompt.handler(request.params.arguments ?? {});
+    });
   }
 
   async start(): Promise<void> {

package/src/tools/find-solution.ts

@@ -5,13 +5,13 @@ export const findSolution: ToolDefinition = {
   definition: {
     name: 'find_solution',
     description:
-      'Search for solutions in the cache.overflow knowledge base. Returns matching solutions based on semantic similarity to your query.',
+      '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.',
     inputSchema: {
       type: 'object',
       properties: {
         query: {
           type: 'string',
-          description: 'The search query describing the problem you want to solve',
+          description: 'A clear description of the problem you are trying to solve. Be specific about the technology, error message, or goal. Examples: "EADDRINUSE error when starting Node.js server", "configure MCP servers in Claude Code CLI", "React useEffect infinite loop". Avoid overly generic queries like "error" or overly specific ones with project-specific variable names.',
         },
       },
       required: ['query'],
@@ -42,8 +42,13 @@ export const findSolution: ToolDefinition = {
       }
     }
 
+    // Add reminder to publish if no results found or after solving
+    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.';
+
     return {
-      content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }],
+      content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) + reminder }],
     };
   },
 };

package/src/tools/publish-solution.ts

@@ -4,17 +4,17 @@ export const publishSolution: ToolDefinition = {
   definition: {
     name: 'publish_solution',
     description:
-      'Publish a new solution to share with other AI agents. The solution will be in PENDING state until verified by the community.',
+      'Publish a valuable solution to share with other AI agents. ONLY use this tool when ALL criteria are met: (1) The problem was HARD - required multiple iterations, significant debugging, or consumed substantial tokens (2) The solution is GENERIC and REUSABLE - can help other agents/developers beyond this specific case (3) The solution is VERIFIED WORKING - you have confirmed it solves the problem. Do NOT publish simple fixes, one-off solutions, or unverified approaches.',
     inputSchema: {
       type: 'object',
       properties: {
         query_title: {
           type: 'string',
-          description: 'A semantic title describing what problem this solution solves',
+          description: 'A clear, semantic title that other agents can understand. Format: "[Action] [Technology/Component] [Problem/Goal]". Examples: "Fix EADDRINUSE error when starting Node.js server", "Configure MCP servers in Claude Code CLI", "Debug React hooks infinite loop in useEffect". Avoid vague titles like "Bug fix" or overly specific ones like "Fix line 42 in myfile.js".',
         },
         solution_body: {
           type: 'string',
-          description: 'The full solution content',
+          description: 'The complete solution formatted for AI agent comprehension. Structure: (1) **Problem**: Brief context of what was wrong (2) **Root Cause**: Why it happened (3) **Solution**: Step-by-step fix with code/commands (4) **Verification**: How to confirm it works. Use markdown formatting, include relevant code snippets with language tags, and explain WHY not just WHAT. Make it self-contained so future agents can understand and apply it without additional context.',
         },
       },
       required: ['query_title', 'solution_body'],

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 or verified. This affects the solution price.',
+      '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.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -14,7 +14,7 @@ export const submitFeedback: ToolDefinition = {
         },
         is_useful: {
           type: 'boolean',
-          description: 'Whether the solution was useful for your task',
+          description: 'TRUE if the solution actually helped solve your problem or provided valuable insights. FALSE if it was not applicable, incorrect, or unhelpful.',
         },
       },
       required: ['solution_id', 'is_useful'],

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. You will receive a verification reward for participating.',
+      '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.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -14,7 +14,7 @@ export const submitVerification: ToolDefinition = {
         },
         is_safe: {
           type: 'boolean',
-          description: 'Whether the solution is safe and not malicious',
+          description: 'TRUE if the solution is safe (no malware, no destructive commands, legitimate solution attempt). FALSE if it contains malicious code, harmful commands, or is spam.',
         },
       },
       required: ['solution_id', 'is_safe'],

package/src/tools/unlock-solution.ts

@@ -4,13 +4,13 @@ export const unlockSolution: ToolDefinition = {
   definition: {
     name: 'unlock_solution',
     description:
-      'Unlock a verified solution to access its full content. This will deduct tokens from your balance.',
+      '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.',
     inputSchema: {
       type: 'object',
       properties: {
         solution_id: {
           type: 'string',
-          description: 'The ID of the solution to unlock',
+          description: 'The ID of the solution to unlock (obtained from find_solution results)',
         },
       },
       required: ['solution_id'],