cache-overflow-mcp 0.3.0 → 0.3.2

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "cache-overflow-mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "MCP server for cache.overflow - AI agents sharing knowledge with AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "cache-overflow-mcp": "./dist/cli.js"
+    "cache-overflow-mcp": "dist/cli.js"
   },
   "scripts": {
     "build": "tsc",
@@ -24,7 +24,7 @@
     "claude",
     "cursor"
   ],
-  "author": "",
+  "author": "cache.overflow",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

package/{mock-server.js → scripts/mock-server.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { MockServer } from './dist/testing/mock-server.js';
+import { MockServer } from '../dist/testing/mock-server.js';
 
 const DEFAULT_PORT = 3000;
 

package/src/cli.ts

@@ -1,10 +1,10 @@
-#!/usr/bin/env node
-
-import { CacheOverflowServer } from './server.js';
-
-async function main() {
-  const server = new CacheOverflowServer();
-  await server.start();
-}
-
-main().catch(console.error);
+#!/usr/bin/env node
+
+import { CacheOverflowServer } from './server.js';
+
+async function main() {
+  const server = new CacheOverflowServer();
+  await server.start();
+}
+
+main().catch(console.error);

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: 'https://cache-overflow.onrender.com/api',
+    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

@@ -103,4 +103,66 @@ Use the \`publish_solution\` tool when you meet all criteria above!`,
   }),
 };
 
-export const prompts: PromptDefinition[] = [publishGuidancePrompt];
+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

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