cache-overflow-mcp 0.3.6 → 0.3.8

package/src/client.ts

@@ -5,10 +5,32 @@ import { logger } from './logger.js';
 export class CacheOverflowClient {
   private apiUrl: string;
   private authToken: string | undefined;
+  private timeout: number;
 
-  constructor(apiUrl?: string) {
+  constructor(apiUrl?: string, token?: string, timeout?: number) {
     this.apiUrl = apiUrl ?? config.api.url;
-    this.authToken = config.auth.token;
+    this.authToken = token ?? config.auth.token;
+    this.timeout = timeout ?? config.api.timeout;
+
+    // Validate URL format (#13 - URL Validation)
+    try {
+      new URL(this.apiUrl);
+    } catch (error) {
+      logger.error('Invalid CACHE_OVERFLOW_URL format', error as Error, {
+        url: this.apiUrl,
+        errorType: 'INVALID_API_URL',
+      });
+      throw new Error(`Invalid API URL: ${this.apiUrl}`);
+    }
+
+    // Validate token format (#12 - Token Validation)
+    if (!this.authToken) {
+      logger.warn('No CACHE_OVERFLOW_TOKEN provided - all API calls will fail', {});
+    } else if (!this.authToken.startsWith('co_')) {
+      logger.warn('Invalid token format - tokens should start with "co_"', {
+        tokenPrefix: this.authToken.substring(0, 3),
+      });
+    }
   }
 
   private async request<T>(
@@ -26,11 +48,33 @@ export class CacheOverflowClient {
 
     const url = `${this.apiUrl}${path}`;
 
+    // #11 - Add request logging for debugging
+    logger.info('API request', {
+      method,
+      path,
+      hasBody: !!body,
+    });
+
+    // #1 - Enforce request timeouts
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
     try {
       const response = await fetch(url, {
         method,
         headers,
         body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      // #11 - Add response logging
+      logger.info('API response', {
+        method,
+        path,
+        status: response.status,
+        ok: response.ok,
       });
 
       // Read response as text first, then try to parse as JSON
@@ -60,18 +104,66 @@ export class CacheOverflowClient {
 
       if (!response.ok) {
         const errorMessage = (data.error as string) ?? 'Unknown error';
+
+        // #7 - Detect and handle rate limiting (429)
+        if (response.status === 429) {
+          const retryAfter = response.headers.get('Retry-After') || '60';
+          logger.warn('Rate limit exceeded', {
+            method,
+            path,
+            retryAfter,
+            errorType: 'RATE_LIMIT',
+          });
+          return {
+            success: false,
+            error: `Rate limit exceeded. Please wait ${retryAfter} seconds before trying again. Consider using solutions with human_verification_required=false to avoid token costs.`,
+          };
+        }
+
+        // #8 - Add status code to error messages with categorization
+        let category = '';
+        if (response.status >= 500) {
+          category = 'Server error - try again later';
+        } else if (response.status === 401 || response.status === 403) {
+          category = 'Authentication error - check your CACHE_OVERFLOW_TOKEN';
+        } else if (response.status >= 400) {
+          category = 'Request error - check your input';
+        }
+
         logger.error('API request failed', undefined, {
           method,
           path,
           statusCode: response.status,
           errorMessage,
+          category,
           errorType: 'API_ERROR',
         });
-        return { success: false, error: errorMessage };
+
+        return {
+          success: false,
+          error: `${errorMessage} (${category})`,
+        };
       }
 
       return { success: true, data: data as T };
     } catch (error) {
+      clearTimeout(timeoutId);
+
+      // #1 - Handle timeout errors specifically
+      if ((error as Error).name === 'AbortError') {
+        logger.error('Request timed out', error as Error, {
+          method,
+          path,
+          url,
+          timeout: this.timeout,
+          errorType: 'TIMEOUT',
+        });
+        return {
+          success: false,
+          error: `Request timed out after ${this.timeout}ms. The server may be experiencing issues.`,
+        };
+      }
+
       logger.error('Network or fetch error during API request', error as Error, {
         method,
         path,
@@ -79,13 +171,89 @@ export class CacheOverflowClient {
         errorType: 'NETWORK_ERROR',
       });
 
-      // Re-throw network errors so they can be handled by the caller
+      // Re-throw network errors so they can be handled by retry logic
       throw error;
     }
   }
 
+  // #2 - Add retry logic for network failures
+  private async requestWithRetry<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    retries = 3
+  ): Promise<ApiResponse<T>> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < retries; attempt++) {
+      try {
+        const result = await this.request<T>(method, path, body);
+
+        // If successful or last attempt, return the result
+        if (result.success || attempt === retries - 1) {
+          return result;
+        }
+
+        // Check if we should retry based on the error
+        const shouldRetry = this.shouldRetryError(result.error);
+        if (shouldRetry) {
+          const delay = Math.pow(3, attempt) * 100; // 0, 300, 900ms exponential backoff
+          logger.info('Retrying request after delay', {
+            method,
+            path,
+            attempt: attempt + 1,
+            maxRetries: retries,
+            delay,
+          });
+          await new Promise(resolve => setTimeout(resolve, delay));
+          continue;
+        }
+
+        // Don't retry client errors (4xx)
+        return result;
+      } catch (error) {
+        lastError = error as Error;
+
+        // Only retry network errors, not client errors
+        if (attempt < retries - 1 && this.isNetworkError(error as Error)) {
+          const delay = Math.pow(3, attempt) * 100;
+          logger.info('Retrying after network error', {
+            method,
+            path,
+            attempt: attempt + 1,
+            maxRetries: retries,
+            delay,
+            error: (error as Error).message,
+          });
+          await new Promise(resolve => setTimeout(resolve, delay));
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  private shouldRetryError(error?: string): boolean {
+    if (!error) return false;
+
+    // Retry on server errors (5xx) or timeout errors
+    return error.includes('Server error') ||
+           error.includes('timed out') ||
+           error.includes('network');
+  }
+
+  private isNetworkError(error: Error): boolean {
+    // Network errors typically have these names or messages
+    return error.name === 'TypeError' ||
+           error.name === 'NetworkError' ||
+           error.message.includes('fetch') ||
+           error.message.includes('network');
+  }
+
   async findSolution(query: string): Promise<ApiResponse<FindSolutionResult[]>> {
-    const result = await this.request<Array<{ id: string; query_title: string; solution_body?: string; human_verification_required: boolean }>>(
+    const result = await this.requestWithRetry<Array<{ id: string; query_title: string; solution_body?: string; human_verification_required: boolean }>>(
       'GET',
       `/solutions/search?query=${encodeURIComponent(query)}`
     );
@@ -105,14 +273,14 @@ export class CacheOverflowClient {
   }
 
   async unlockSolution(solutionId: string): Promise<ApiResponse<Solution>> {
-    return this.request('POST', `/solutions/${solutionId}/unlock`);
+    return this.requestWithRetry('POST', `/solutions/${solutionId}/unlock`);
   }
 
   async publishSolution(
     queryTitle: string,
     solutionBody: string
   ): Promise<ApiResponse<Solution>> {
-    return this.request('POST', '/solutions', {
+    return this.requestWithRetry('POST', '/solutions', {
       query_title: queryTitle,
       solution_body: solutionBody,
     });
@@ -122,7 +290,7 @@ export class CacheOverflowClient {
     solutionId: string,
     isSafe: boolean
   ): Promise<ApiResponse<void>> {
-    return this.request('POST', `/solutions/${solutionId}/verify`, {
+    return this.requestWithRetry('POST', `/solutions/${solutionId}/verify`, {
       is_safe: isSafe,
     });
   }
@@ -131,7 +299,7 @@ export class CacheOverflowClient {
     solutionId: string,
     isUseful: boolean
   ): Promise<ApiResponse<void>> {
-    return this.request('POST', `/solutions/${solutionId}/feedback`, {
+    return this.requestWithRetry('POST', `/solutions/${solutionId}/feedback`, {
       is_useful: isUseful,
     });
   }

package/src/config.ts

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

package/src/prompts/index.ts

@@ -1,4 +1,7 @@
 import { Prompt, TextContent } from '@modelcontextprotocol/sdk/types.js';
+import { configService } from '../services/config-service.js';
+import { logger } from '../logger.js';
+import type { RemotePromptDefinition } from '../types.js';
 
 export interface PromptDefinition {
   definition: Prompt;
@@ -165,4 +168,67 @@ Then call \`publish_solution\` to share it with other agents!
   }),
 };
 
-export const prompts: PromptDefinition[] = [publishGuidancePrompt, workflowGuidancePrompt];
+// Fallback prompts used when backend is unavailable
+export const FALLBACK_PROMPTS: PromptDefinition[] = [
+  publishGuidancePrompt,
+  workflowGuidancePrompt,
+];
+
+/**
+ * Convert a remote prompt definition to a local Prompt format
+ */
+function remoteToLocalPrompt(remote: RemotePromptDefinition): Prompt {
+  return {
+    name: remote.name,
+    description: remote.description,
+    arguments: remote.arguments.map((arg) => ({
+      name: arg.name,
+      description: arg.description,
+      required: arg.required,
+    })),
+  };
+}
+
+/**
+ * Create a handler for a remote prompt definition.
+ * The handler returns the pre-defined messages from the remote config.
+ */
+function createRemotePromptHandler(
+  remote: RemotePromptDefinition
+): PromptDefinition['handler'] {
+  return async () => ({
+    messages: remote.messages.map((msg) => ({
+      role: msg.role as 'user' | 'assistant',
+      content: {
+        type: msg.content.type as 'text',
+        text: msg.content.text,
+      },
+    })),
+  });
+}
+
+/**
+ * Get prompts with definitions from the backend API.
+ * Falls back to hardcoded definitions if the backend is unavailable.
+ */
+export async function getPrompts(): Promise<PromptDefinition[]> {
+  const remoteConfig = await configService.fetchConfig();
+
+  if (!remoteConfig) {
+    logger.info('Using fallback prompt definitions');
+    return FALLBACK_PROMPTS;
+  }
+
+  const prompts: PromptDefinition[] = remoteConfig.prompts.map(
+    (remotePrompt) => ({
+      definition: remoteToLocalPrompt(remotePrompt),
+      handler: createRemotePromptHandler(remotePrompt),
+    })
+  );
+
+  return prompts;
+}
+
+// Keep backward compatibility - export prompts array for existing code
+// Note: This is the fallback, prefer using getPrompts() for dynamic loading
+export const prompts: PromptDefinition[] = FALLBACK_PROMPTS;

package/src/server.ts

@@ -7,8 +7,8 @@ import {
   GetPromptRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { CacheOverflowClient } from './client.js';
-import { tools } from './tools/index.js';
-import { prompts } from './prompts/index.js';
+import { getTools } from './tools/index.js';
+import { getPrompts } from './prompts/index.js';
 import { logger } from './logger.js';
 
 export class CacheOverflowServer {
@@ -35,17 +35,21 @@ export class CacheOverflowServer {
 
   private setupHandlers(): void {
     // Tool handlers
-    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
-      tools: tools.map((t) => t.definition),
-    }));
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      const tools = await getTools();
+      return {
+        tools: tools.map((t) => t.definition),
+      };
+    });
 
     this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const tools = await getTools();
       const tool = tools.find((t) => t.definition.name === request.params.name);
       if (!tool) {
         const error = new Error(`Unknown tool: ${request.params.name}`);
         logger.error('Unknown tool requested', error, {
           toolName: request.params.name,
-          availableTools: tools.map(t => t.definition.name),
+          availableTools: tools.map((t) => t.definition.name),
         });
         throw error;
       }
@@ -58,26 +62,36 @@ export class CacheOverflowServer {
         });
         return await tool.handler(request.params.arguments ?? {}, this.client);
       } catch (error) {
-        logger.error(`Tool execution failed: ${request.params.name}`, error as Error, {
-          toolName: request.params.name,
-          errorType: 'TOOL_EXECUTION_FAILURE',
-        });
+        logger.error(
+          `Tool execution failed: ${request.params.name}`,
+          error as Error,
+          {
+            toolName: request.params.name,
+            errorType: 'TOOL_EXECUTION_FAILURE',
+          }
+        );
         throw error;
       }
     });
 
     // Prompt handlers
-    this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
-      prompts: prompts.map((p) => p.definition),
-    }));
+    this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+      const prompts = await getPrompts();
+      return {
+        prompts: prompts.map((p) => p.definition),
+      };
+    });
 
     this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-      const prompt = prompts.find((p) => p.definition.name === request.params.name);
+      const prompts = await getPrompts();
+      const prompt = prompts.find(
+        (p) => p.definition.name === request.params.name
+      );
       if (!prompt) {
         const error = new Error(`Unknown prompt: ${request.params.name}`);
         logger.error('Unknown prompt requested', error, {
           promptName: request.params.name,
-          availablePrompts: prompts.map(p => p.definition.name),
+          availablePrompts: prompts.map((p) => p.definition.name),
         });
         throw error;
       }
@@ -85,10 +99,14 @@ export class CacheOverflowServer {
       try {
         return await prompt.handler(request.params.arguments ?? {});
       } catch (error) {
-        logger.error(`Prompt execution failed: ${request.params.name}`, error as Error, {
-          promptName: request.params.name,
-          errorType: 'PROMPT_EXECUTION_FAILURE',
-        });
+        logger.error(
+          `Prompt execution failed: ${request.params.name}`,
+          error as Error,
+          {
+            promptName: request.params.name,
+            errorType: 'PROMPT_EXECUTION_FAILURE',
+          }
+        );
         throw error;
       }
     });

package/src/services/config-service.ts

@@ -0,0 +1,119 @@
+import { config } from '../config.js';
+import { logger } from '../logger.js';
+import type { McpConfigResponse } from '../types.js';
+
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const FETCH_TIMEOUT_MS = 5000; // 5 seconds
+const SUPPORTED_SCHEMA_VERSION = '1.0.0';
+
+interface CachedConfig {
+  data: McpConfigResponse;
+  fetchedAt: number;
+}
+
+class ConfigService {
+  private cache: CachedConfig | null = null;
+
+  /**
+   * Fetch MCP configuration from the backend API.
+   * Returns cached value if available and not expired.
+   * Falls back to null on failure (caller should use fallback).
+   */
+  async fetchConfig(): Promise<McpConfigResponse | null> {
+    // Return cached value if still valid
+    if (this.cache && Date.now() - this.cache.fetchedAt < CACHE_TTL_MS) {
+      return this.cache.data;
+    }
+
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+      const response = await fetch(`${config.api.url}/mcp/config`, {
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        logger.warn('Failed to fetch MCP config', {
+          status: response.status,
+          statusText: response.statusText,
+        });
+        return this.getCachedOrNull();
+      }
+
+      const data = (await response.json()) as McpConfigResponse;
+
+      // Validate schema version
+      if (!this.isSchemaVersionCompatible(data.schema_version)) {
+        logger.warn('MCP config schema version mismatch', {
+          expected: SUPPORTED_SCHEMA_VERSION,
+          received: data.schema_version,
+        });
+        return this.getCachedOrNull();
+      }
+
+      // Update cache
+      this.cache = {
+        data,
+        fetchedAt: Date.now(),
+      };
+
+      logger.info('Fetched MCP config from backend', {
+        schemaVersion: data.schema_version,
+        toolCount: data.tools.length,
+        promptCount: data.prompts.length,
+      });
+
+      return data;
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.name === 'AbortError') {
+          logger.warn('MCP config fetch timed out');
+        } else {
+          logger.warn('Failed to fetch MCP config', {
+            error: error.message,
+          });
+        }
+      }
+      return this.getCachedOrNull();
+    }
+  }
+
+  /**
+   * Check if the schema version is compatible.
+   * For now, we only support exact match.
+   * Later can implement semantic version comparison.
+   */
+  private isSchemaVersionCompatible(version: string): boolean {
+    // Extract major version for compatibility check
+    const [major] = version.split('.');
+    const [supportedMajor] = SUPPORTED_SCHEMA_VERSION.split('.');
+    return major === supportedMajor;
+  }
+
+  /**
+   * Return cached value if available, otherwise null.
+   */
+  private getCachedOrNull(): McpConfigResponse | null {
+    if (this.cache) {
+      return this.cache.data;
+    }
+    return null;
+  }
+
+  /**
+   * Invalidate the cache, forcing a fresh fetch on next request.
+   */
+  invalidateCache(): void {
+    this.cache = null;
+  }
+}
+
+// Export singleton instance
+export const configService = new ConfigService();

package/src/testing/mock-server.ts

@@ -1,6 +1,6 @@
 import * as http from 'node:http';
 import { mockSolutions, mockFindResults, createMockSolution } from './mock-data.js';
-import type { Solution, FindSolutionResult } from '../types.js';
+import type { Solution } from '../types.js';
 
 interface RouteHandler {
   (
@@ -31,13 +31,21 @@ export class MockServer {
   }
 
   private setupRoutes(): void {
-    // POST /solutions/find
-    this.addRoute('POST', '/solutions/find', (_req, body) => {
-      const { query } = body as { query: string };
-      const results: FindSolutionResult[] = mockFindResults.filter((r) =>
-        r.query_title.toLowerCase().includes((query ?? '').toLowerCase())
+    // GET /solutions/search - matches client's findSolution API
+    this.addRoute('GET', '/solutions/search', (req) => {
+      const url = new URL(req.url ?? '/', `http://localhost:${this.port}`);
+      const query = url.searchParams.get('query') ?? '';
+      const results = mockFindResults.filter((r) =>
+        r.query_title.toLowerCase().includes(query.toLowerCase())
       );
-      return { status: 200, data: results.length > 0 ? results : mockFindResults };
+      // Map solution_id to id to match API response format
+      const mappedResults = (results.length > 0 ? results : mockFindResults).map((r) => ({
+        id: r.solution_id,
+        query_title: r.query_title,
+        solution_body: r.solution_body,
+        human_verification_required: r.human_verification_required,
+      }));
+      return { status: 200, data: mappedResults };
     });
 
     // POST /solutions/:id/unlock