cache-overflow-mcp 0.2.0 → 0.3.1

package/src/client.test.ts

@@ -1,116 +1,116 @@
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { CacheOverflowClient } from './client.js';
-import { MockServer } from './testing/mock-server.js';
-import { mockSolutions, mockFindResults } from './testing/mock-data.js';
-
-describe('CacheOverflowClient', () => {
-  let mockServer: MockServer;
-  let client: CacheOverflowClient;
-
-  beforeAll(async () => {
-    mockServer = new MockServer();
-    await mockServer.start();
-    client = new CacheOverflowClient(mockServer.url);
-  });
-
-  afterAll(async () => {
-    await mockServer.stop();
-  });
-
-  describe('findSolution', () => {
-    it('should return search results', async () => {
-      const result = await client.findSolution('binary search');
-
-      expect(result.success).toBe(true);
-      if (result.success) {
-        expect(Array.isArray(result.data)).toBe(true);
-        expect(result.data.length).toBeGreaterThan(0);
-        expect(result.data[0]).toHaveProperty('solution_id');
-        expect(result.data[0]).toHaveProperty('query_title');
-        expect(result.data[0]).toHaveProperty('human_verification_required');
-      }
-    });
-
-    it('should return results matching the query', async () => {
-      const result = await client.findSolution('TypeScript');
-
-      expect(result.success).toBe(true);
-      if (result.success) {
-        const hasTypeScript = result.data.some((r) =>
-          r.query_title.toLowerCase().includes('typescript')
-        );
-        expect(hasTypeScript).toBe(true);
-      }
-    });
-  });
-
-  describe('unlockSolution', () => {
-    it('should return the unlocked solution', async () => {
-      const result = await client.unlockSolution(mockSolutions[0].id);
-
-      expect(result.success).toBe(true);
-      if (result.success) {
-        expect(result.data).toHaveProperty('id');
-        expect(result.data).toHaveProperty('solution_body');
-        expect(result.data).toHaveProperty('price_current');
-        expect(result.data).toHaveProperty('verification_state');
-      }
-    });
-
-    it('should return a solution even for unknown IDs', async () => {
-      const result = await client.unlockSolution('unknown_id');
-
-      expect(result.success).toBe(true);
-      if (result.success) {
-        expect(result.data).toHaveProperty('id');
-      }
-    });
-  });
-
-  describe('publishSolution', () => {
-    it('should create a new solution', async () => {
-      const result = await client.publishSolution(
-        'How to test async code in Vitest',
-        'Use async/await with expect().resolves or expect().rejects'
-      );
-
-      expect(result.success).toBe(true);
-      if (result.success) {
-        expect(result.data).toHaveProperty('id');
-        expect(result.data.query_title).toBe('How to test async code in Vitest');
-        expect(result.data.solution_body).toBe(
-          'Use async/await with expect().resolves or expect().rejects'
-        );
-        expect(result.data.verification_state).toBe('PENDING');
-      }
-    });
-  });
-
-  describe('submitVerification', () => {
-    it('should submit verification successfully', async () => {
-      const result = await client.submitVerification(mockSolutions[0].id, true);
-
-      expect(result.success).toBe(true);
-    });
-
-    it('should allow marking as unsafe', async () => {
-      const result = await client.submitVerification(mockSolutions[0].id, false);
-
-      expect(result.success).toBe(true);
-    });
-  });
-
-  describe('submitFeedback', () => {
-    it('should submit positive feedback', async () => {
-      const result = await client.submitFeedback(mockSolutions[0].id, true);
-
-      expect(result.success).toBe(true);
-    });
-
-    it('should submit negative feedback', async () => {
-      const result = await client.submitFeedback(mockSolutions[0].id, false);
-
-      expect(result.success).toBe(true);
-    });
-  });
-});
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { CacheOverflowClient } from './client.js';
+import { MockServer } from './testing/mock-server.js';
+import { mockSolutions, mockFindResults } from './testing/mock-data.js';
+
+describe('CacheOverflowClient', () => {
+  let mockServer: MockServer;
+  let client: CacheOverflowClient;
+
+  beforeAll(async () => {
+    mockServer = new MockServer();
+    await mockServer.start();
+    client = new CacheOverflowClient(mockServer.url);
+  });
+
+  afterAll(async () => {
+    await mockServer.stop();
+  });
+
+  describe('findSolution', () => {
+    it('should return search results', async () => {
+      const result = await client.findSolution('binary search');
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(Array.isArray(result.data)).toBe(true);
+        expect(result.data.length).toBeGreaterThan(0);
+        expect(result.data[0]).toHaveProperty('solution_id');
+        expect(result.data[0]).toHaveProperty('query_title');
+        expect(result.data[0]).toHaveProperty('human_verification_required');
+      }
+    });
+
+    it('should return results matching the query', async () => {
+      const result = await client.findSolution('TypeScript');
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        const hasTypeScript = result.data.some((r) =>
+          r.query_title.toLowerCase().includes('typescript')
+        );
+        expect(hasTypeScript).toBe(true);
+      }
+    });
+  });
+
+  describe('unlockSolution', () => {
+    it('should return the unlocked solution', async () => {
+      const result = await client.unlockSolution(mockSolutions[0].id);
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toHaveProperty('id');
+        expect(result.data).toHaveProperty('solution_body');
+        expect(result.data).toHaveProperty('price_current');
+        expect(result.data).toHaveProperty('verification_state');
+      }
+    });
+
+    it('should return a solution even for unknown IDs', async () => {
+      const result = await client.unlockSolution('unknown_id');
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toHaveProperty('id');
+      }
+    });
+  });
+
+  describe('publishSolution', () => {
+    it('should create a new solution', async () => {
+      const result = await client.publishSolution(
+        'How to test async code in Vitest',
+        'Use async/await with expect().resolves or expect().rejects'
+      );
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toHaveProperty('id');
+        expect(result.data.query_title).toBe('How to test async code in Vitest');
+        expect(result.data.solution_body).toBe(
+          'Use async/await with expect().resolves or expect().rejects'
+        );
+        expect(result.data.verification_state).toBe('PENDING');
+      }
+    });
+  });
+
+  describe('submitVerification', () => {
+    it('should submit verification successfully', async () => {
+      const result = await client.submitVerification(mockSolutions[0].id, true);
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should allow marking as unsafe', async () => {
+      const result = await client.submitVerification(mockSolutions[0].id, false);
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('submitFeedback', () => {
+    it('should submit positive feedback', async () => {
+      const result = await client.submitFeedback(mockSolutions[0].id, true);
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should submit negative feedback', async () => {
+      const result = await client.submitFeedback(mockSolutions[0].id, false);
+
+      expect(result.success).toBe(true);
+    });
+  });
+});

package/src/client.ts

@@ -1,76 +1,76 @@
-import { ApiResponse, Solution, FindSolutionResult } from './types.js';
-import { config } from './config.js';
-
-export class CacheOverflowClient {
-  private apiUrl: string;
-  private authToken: string | undefined;
-
-  constructor(apiUrl?: string) {
-    this.apiUrl = apiUrl ?? config.api.url;
-    this.authToken = config.auth.token;
-  }
-
-  private async request<T>(
-    method: string,
-    path: string,
-    body?: unknown
-  ): Promise<ApiResponse<T>> {
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/json',
-    };
-
-    if (this.authToken) {
-      headers['Authorization'] = `Bearer ${this.authToken}`;
-    }
-
-    const response = await fetch(`${this.apiUrl}${path}`, {
-      method,
-      headers,
-      body: body ? JSON.stringify(body) : undefined,
-    });
-
-    const data = (await response.json()) as Record<string, unknown>;
-
-    if (!response.ok) {
-      return { success: false, error: (data.error as string) ?? 'Unknown error' };
-    }
-
-    return { success: true, data: data as T };
-  }
-
-  async findSolution(query: string): Promise<ApiResponse<FindSolutionResult[]>> {
-    return this.request('POST', '/solutions/find', { query });
-  }
-
-  async unlockSolution(solutionId: string): Promise<ApiResponse<Solution>> {
-    return this.request('POST', `/solutions/${solutionId}/unlock`);
-  }
-
-  async publishSolution(
-    queryTitle: string,
-    solutionBody: string
-  ): Promise<ApiResponse<Solution>> {
-    return this.request('POST', '/solutions', {
-      query_title: queryTitle,
-      solution_body: solutionBody,
-    });
-  }
-
-  async submitVerification(
-    solutionId: string,
-    isSafe: boolean
-  ): Promise<ApiResponse<void>> {
-    return this.request('POST', `/solutions/${solutionId}/verify`, {
-      is_safe: isSafe,
-    });
-  }
-
-  async submitFeedback(
-    solutionId: string,
-    isUseful: boolean
-  ): Promise<ApiResponse<void>> {
-    return this.request('POST', `/solutions/${solutionId}/feedback`, {
-      is_useful: isUseful,
-    });
-  }
-}
+import { ApiResponse, Solution, FindSolutionResult } from './types.js';
+import { config } from './config.js';
+
+export class CacheOverflowClient {
+  private apiUrl: string;
+  private authToken: string | undefined;
+
+  constructor(apiUrl?: string) {
+    this.apiUrl = apiUrl ?? config.api.url;
+    this.authToken = config.auth.token;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<ApiResponse<T>> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+
+    if (this.authToken) {
+      headers['Authorization'] = `Bearer ${this.authToken}`;
+    }
+
+    const response = await fetch(`${this.apiUrl}${path}`, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    const data = (await response.json()) as Record<string, unknown>;
+
+    if (!response.ok) {
+      return { success: false, error: (data.error as string) ?? 'Unknown error' };
+    }
+
+    return { success: true, data: data as T };
+  }
+
+  async findSolution(query: string): Promise<ApiResponse<FindSolutionResult[]>> {
+    return this.request('POST', '/solutions/find', { query });
+  }
+
+  async unlockSolution(solutionId: string): Promise<ApiResponse<Solution>> {
+    return this.request('POST', `/solutions/${solutionId}/unlock`);
+  }
+
+  async publishSolution(
+    queryTitle: string,
+    solutionBody: string
+  ): Promise<ApiResponse<Solution>> {
+    return this.request('POST', '/solutions', {
+      query_title: queryTitle,
+      solution_body: solutionBody,
+    });
+  }
+
+  async submitVerification(
+    solutionId: string,
+    isSafe: boolean
+  ): Promise<ApiResponse<void>> {
+    return this.request('POST', `/solutions/${solutionId}/verify`, {
+      is_safe: isSafe,
+    });
+  }
+
+  async submitFeedback(
+    solutionId: string,
+    isUseful: boolean
+  ): Promise<ApiResponse<void>> {
+    return this.request('POST', `/solutions/${solutionId}/feedback`, {
+      is_useful: isUseful,
+    });
+  }
+}

package/src/config.ts

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

package/src/index.ts

@@ -1,3 +1,3 @@
-export { CacheOverflowServer } from './server.js';
-export { CacheOverflowClient } from './client.js';
-export * from './types.js';
+export { CacheOverflowServer } from './server.js';
+export { CacheOverflowClient } from './client.js';
+export * from './types.js';

package/src/prompts/index.ts

@@ -0,0 +1,168 @@
+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 workflowGuidancePrompt: PromptDefinition = {
+  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: PromptDefinition[] = [publishGuidancePrompt, workflowGuidancePrompt];

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.3.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> {