ubersearch 1.7.0 → 1.7.1

package/src/core/strategy/AllProvidersStrategy.ts

@@ -7,9 +7,10 @@
  * the overall search.
  */
 
-import { withRetry } from "../../providers/retry";
+import { getErrorMessage } from "../errorUtils";
 import { createLogger } from "../logger";
 import type { SearchProvider } from "../provider";
+import { withRetry } from "../retry";
 import type { EngineId, SearchResponse, SearchResultItem } from "../types";
 import { SearchError } from "../types";
 import type {
@@ -28,7 +29,7 @@ const log = createLogger("AllProviders");
 interface EngineSearchResult {
   engineId: EngineId;
   response?: SearchResponse;
-  error?: Error;
+  error?: unknown;
 }
 
 /**
@@ -101,12 +102,7 @@ export class AllProvidersStrategy implements ISearchStrategy {
         // Record success
         attempts.push({ engineId, success: true });
 
-        // Add results, applying limit if specified
-        if (options.limit !== undefined) {
-          results.push(...response.items.slice(0, options.limit - results.length));
-        } else {
-          results.push(...response.items);
-        }
+        results.push(...response.items);
       } catch (error) {
         // Refund credits for failed search
         context.creditManager.refund(engineId);
@@ -119,18 +115,11 @@ export class AllProvidersStrategy implements ISearchStrategy {
         }
 
         // Log debug message but continue with other providers
-        log.debug(
-          `Search failed for ${engineId}: ${error instanceof Error ? error.message : String(error)}`,
-        );
+        log.debug(`Search failed for ${engineId}: ${getErrorMessage(error)}`);
       }
     }
 
-    // Apply final limit if specified
-    if (options.limit !== undefined && results.length > options.limit) {
-      results.splice(options.limit);
-    }
-
-    return { results, attempts };
+    return { results: this.finalizeResults(results, options), attempts };
   }
 
   /**
@@ -182,7 +171,7 @@ export class AllProvidersStrategy implements ISearchStrategy {
           );
           return { engineId, response };
         } catch (error) {
-          return { engineId, error: error instanceof Error ? error : new Error(String(error)) };
+          return { engineId, error };
         }
       },
     );
@@ -204,27 +193,34 @@ export class AllProvidersStrategy implements ISearchStrategy {
 
       if (settledResult.status === "rejected") {
         // Promise itself was rejected (shouldn't happen with our try/catch, but handle it)
-        attempts.push({ engineId, success: false, reason: "unknown" });
+        context.creditManager.refund(engineId);
+        const error = settledResult.reason;
+        if (error instanceof SearchError) {
+          attempts.push({ engineId, success: false, reason: error.reason });
+        } else {
+          attempts.push({ engineId, success: false, reason: "unknown" });
+        }
         log.debug(`Search failed for ${engineId}: Promise rejected`);
         continue;
       }
 
-      const { response, error } = settledResult.value;
-
-      if (error) {
+      if ("error" in settledResult.value) {
         // Refund credits for failed search
         context.creditManager.refund(engineId);
 
         // Search threw an error
+        const error = settledResult.value.error;
         if (error instanceof SearchError) {
           attempts.push({ engineId, success: false, reason: error.reason });
         } else {
           attempts.push({ engineId, success: false, reason: "unknown" });
         }
-        log.debug(`Search failed for ${engineId}: ${error.message}`);
+        log.debug(`Search failed for ${engineId}: ${getErrorMessage(error)}`);
         continue;
       }
 
+      const { response } = settledResult.value;
+
       if (response) {
         // Record success
         attempts.push({ engineId, success: true });
@@ -243,11 +239,31 @@ export class AllProvidersStrategy implements ISearchStrategy {
       (a, b) => (engineOrder.get(a.engineId) ?? 0) - (engineOrder.get(b.engineId) ?? 0),
     );
 
-    // Apply final limit if specified
-    if (options.limit !== undefined && results.length > options.limit) {
-      results.splice(options.limit);
+    return { results: this.finalizeResults(results, options), attempts };
+  }
+
+  /**
+   * Deduplicate results by URL, sort by score, and apply limit.
+   */
+  private finalizeResults(
+    results: SearchResultItem[],
+    options: UberSearchOptions,
+  ): SearchResultItem[] {
+    const seen = new Set<string>();
+    const deduped: SearchResultItem[] = [];
+    for (const item of results) {
+      if (!seen.has(item.url)) {
+        seen.add(item.url);
+        deduped.push(item);
+      }
+    }
+
+    deduped.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+
+    if (options.limit !== undefined && deduped.length > options.limit) {
+      deduped.splice(options.limit);
     }
 
-    return { results, attempts };
+    return deduped;
   }
 }

package/src/core/strategy/FirstSuccessStrategy.ts

@@ -6,8 +6,9 @@
  * with insufficient credits and stops execution after the first success.
  */
 
-import { withRetry } from "../../providers/retry";
+import { getErrorMessage } from "../errorUtils";
 import { createLogger } from "../logger";
+import { withRetry } from "../retry";
 import type { EngineId } from "../types";
 import { SearchError } from "../types";
 import type {
@@ -87,9 +88,7 @@ export class FirstSuccessStrategy implements ISearchStrategy {
         }
 
         // Log debug message and continue
-        log.debug(
-          `Search failed for ${engineId}: ${error instanceof Error ? error.message : String(error)}`,
-        );
+        log.debug(`Search failed for ${engineId}: ${getErrorMessage(error)}`);
       }
     }
 

package/src/core/strategy/ISearchStrategy.ts

@@ -7,7 +7,7 @@
 
 import type { CreditManager } from "../credits";
 import type { ProviderRegistry } from "../provider";
-import type { EngineId, SearchResultItem } from "../types";
+import type { EngineId, SearchFailureReason, SearchResultItem } from "../types";
 
 /**
  * Context object providing dependencies to search strategies
@@ -58,7 +58,7 @@ export interface EngineAttempt {
   success: boolean;
 
   /** Reason for failure (if success=false) */
-  reason?: string;
+  reason?: SearchFailureReason;
 }
 
 /**

package/src/core/types.ts

@@ -33,6 +33,7 @@ export type SearchFailureReason =
   | "rate_limit"
   | "no_results"
   | "low_credit"
+  | "out_of_credit"
   | "config_error"
   | "no_provider"
   | "provider_unavailable"

package/src/mcp-server.ts

@@ -7,9 +7,10 @@
  */
 
 import { bootstrapContainer, getCreditStatus, uberSearch } from "./app/index";
+import { getErrorMessage } from "./core/errorUtils";
 import type { ProviderRegistry } from "./core/provider";
 import { ServiceKeys } from "./core/serviceKeys";
-import { isLifecycleProvider } from "./plugin/types.js";
+import { isLifecycleProvider } from "./plugin/types";
 
 interface MCPRequest {
   jsonrpc: string;
@@ -26,10 +27,10 @@ interface MCPTool {
 
 interface MCPResponse {
   jsonrpc: string;
-  id?: number | string;
+  id?: number | string | null;
   result?: unknown;
   error?: {
-    code?: number;
+    code: number;
     message: string;
   };
 }
@@ -40,6 +41,9 @@ interface HealthResult {
   message?: string;
 }
 
+// Module-level container reference for shutdown handlers
+let globalContainer: Awaited<ReturnType<typeof bootstrapContainer>> | null = null;
+
 // Helper function with timeout
 async function withTimeout<T>(promise: Promise<T>, ms: number, operation: string): Promise<T> {
   const timeoutPromise = new Promise<never>((_, reject) => {
@@ -48,8 +52,37 @@ async function withTimeout<T>(promise: Promise<T>, ms: number, operation: string
   return Promise.race([promise, timeoutPromise]);
 }
 
+function setupShutdownHandlers() {
+  const shutdown = async () => {
+    try {
+      const container = globalContainer;
+      if (container) {
+        const registry = container.get<ProviderRegistry>(ServiceKeys.PROVIDER_REGISTRY);
+        if (registry) {
+          for (const provider of registry.list()) {
+            if (isLifecycleProvider(provider) && typeof provider.shutdown === "function") {
+              try {
+                await provider.shutdown();
+              } catch {
+                // Best-effort shutdown
+              }
+            }
+          }
+        }
+      }
+    } catch {
+      // Best-effort cleanup
+    }
+    process.exit(0);
+  };
+
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}
+
 // MCP Server entry point for Claude Desktop
 export async function serve() {
+  setupShutdownHandlers();
   const tools: MCPTool[] = [
     {
       name: "uber_search",
@@ -113,6 +146,8 @@ Example: "it,science" for tech and academic results`,
   ];
 
   // Handle MCP tool calls via stdin/stdout
+  const validToolNames = new Set(tools.map((t) => t.name));
+
   const readline = (await import("node:readline")).createInterface({
     input: process.stdin,
     output: process.stdout,
@@ -124,6 +159,15 @@ Example: "it,science" for tech and academic results`,
     try {
       request = JSON.parse(line);
     } catch {
+      const errorResponse: MCPResponse = {
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+          code: -32700,
+          message: "Parse error: invalid JSON",
+        },
+      };
+      process.stdout.write(`${JSON.stringify(errorResponse)}\n`);
       continue;
     }
 
@@ -143,7 +187,7 @@ Example: "it,science" for tech and academic results`,
           },
         },
       };
-      console.log(JSON.stringify(response));
+      process.stdout.write(`${JSON.stringify(response)}\n`);
       continue;
     }
 
@@ -158,7 +202,7 @@ Example: "it,science" for tech and academic results`,
         id: request.id,
         result: { tools },
       };
-      console.log(JSON.stringify(response));
+      process.stdout.write(`${JSON.stringify(response)}\n`);
       continue;
     }
 
@@ -170,6 +214,48 @@ Example: "it,science" for tech and academic results`,
           ? (params.arguments as Record<string, string>)
           : ({} as Record<string, string>);
 
+      // Validate tool name
+      if (!validToolNames.has(name)) {
+        const response: MCPResponse = {
+          jsonrpc: "2.0",
+          id: request.id,
+          error: {
+            code: -32602,
+            message: `Unknown tool: '${name}'`,
+          },
+        };
+        process.stdout.write(`${JSON.stringify(response)}\n`);
+        continue;
+      }
+
+      // Validate required query parameter for uber_search
+      if (name === "uber_search" && (!args.query || args.query.trim() === "")) {
+        const response: MCPResponse = {
+          jsonrpc: "2.0",
+          id: request.id,
+          error: {
+            code: -32602,
+            message: "Invalid params: 'query' is required and must be non-empty",
+          },
+        };
+        process.stdout.write(`${JSON.stringify(response)}\n`);
+        continue;
+      }
+
+      // Input sanitization - query length check
+      if (args.query && args.query.length > 2000) {
+        const response: MCPResponse = {
+          jsonrpc: "2.0",
+          id: request.id,
+          error: {
+            code: -32602,
+            message: "Invalid params: query exceeds maximum length of 2000 characters",
+          },
+        };
+        process.stdout.write(`${JSON.stringify(response)}\n`);
+        continue;
+      }
+
       try {
         let result: unknown;
         if (name === "uber_search") {
@@ -194,7 +280,10 @@ Example: "it,science" for tech and academic results`,
         } else if (name === "uber_search_credits") {
           result = await withTimeout(getCreditStatus(), 10000, "getCreditStatus");
         } else if (name === "uber_search_health") {
-          const container = await withTimeout(bootstrapContainer(), 30000, "bootstrapContainer");
+          if (!globalContainer) {
+            globalContainer = await withTimeout(bootstrapContainer(), 30000, "bootstrapContainer");
+          }
+          const container = globalContainer;
           const registry = container.get<ProviderRegistry>(ServiceKeys.PROVIDER_REGISTRY);
           const providers = registry.list();
 
@@ -208,7 +297,7 @@ Example: "it,science" for tech and academic results`,
                 results.push({
                   engineId: provider.id,
                   status: "unhealthy",
-                  message: error instanceof Error ? error.message : String(error),
+                  message: getErrorMessage(error),
                 });
               }
             } else {
@@ -216,8 +305,6 @@ Example: "it,science" for tech and academic results`,
             }
           }
           result = results;
-        } else {
-          throw new Error(`Unknown tool: ${name}`);
         }
 
         const response: MCPResponse = {
@@ -232,17 +319,29 @@ Example: "it,science" for tech and academic results`,
             ],
           },
         };
-        console.log(JSON.stringify(response));
+        process.stdout.write(`${JSON.stringify(response)}\n`);
       } catch (error) {
         const errorResponse: MCPResponse = {
           jsonrpc: "2.0",
           id: request.id,
           error: {
+            code: -32603,
             message: error instanceof Error ? error.message : String(error),
           },
         };
-        console.log(JSON.stringify(errorResponse));
+        process.stdout.write(`${JSON.stringify(errorResponse)}\n`);
       }
+    } else if (request.id !== undefined) {
+      // Unknown method - send error response (only for requests with id, not notifications)
+      const response: MCPResponse = {
+        jsonrpc: "2.0",
+        id: request.id,
+        error: {
+          code: -32601,
+          message: `Method not found: ${request.method}`,
+        },
+      };
+      process.stdout.write(`${JSON.stringify(response)}\n`);
     }
   }
 }

package/src/plugin/PluginRegistry.ts

@@ -6,6 +6,8 @@
  */
 
 import type { EngineConfigBase } from "../config/types";
+import { getErrorMessage } from "../core/errorUtils";
+import { createLogger } from "../core/logger";
 import type {
   CreateProviderOptions,
   ManagedProvider,
@@ -15,6 +17,8 @@ import type {
   PluginRegistrationResult,
 } from "./types";
 
+const log = createLogger("PluginRegistry");
+
 /**
  * Central registry for search provider plugins
  *
@@ -108,7 +112,7 @@ export class PluginRegistry {
           await existing.onUnregister();
         } catch (error) {
           // Log but don't fail - we still want to register the new plugin
-          console.warn(`Error during onUnregister for plugin '${plugin.type}':`, error);
+          log.warn(`Error during onUnregister for plugin '${plugin.type}':`, error);
         }
       }
     }
@@ -126,7 +130,7 @@ export class PluginRegistry {
         return {
           success: false,
           type: plugin.type,
-          message: `Plugin onRegister failed: ${error instanceof Error ? error.message : String(error)}`,
+          message: `Plugin onRegister failed: ${getErrorMessage(error)}`,
         };
       }
     }
@@ -285,14 +289,21 @@ export class PluginRegistry {
         validatedConfig = plugin.configSchema.validate(config) as T & { type: string };
       } catch (error) {
         throw new Error(
-          `Config validation failed for plugin '${config.type}': ` +
-            `${error instanceof Error ? error.message : String(error)}`,
+          `Config validation failed for plugin '${config.type}': ` + `${getErrorMessage(error)}`,
         );
       }
     }
 
     // Create provider using factory
-    return plugin.factory(validatedConfig, container) as ManagedProvider;
+    try {
+      const provider = plugin.factory(validatedConfig, container);
+      return provider as ManagedProvider;
+    } catch (error) {
+      const message = getErrorMessage(error);
+      throw new Error(`Failed to create provider for plugin '${config.type}': ${message}`, {
+        cause: error,
+      });
+    }
   }
 
   /**
@@ -315,7 +326,7 @@ export class PluginRegistry {
         try {
           await plugin.onUnregister();
         } catch (error) {
-          console.warn(`Error during onUnregister for plugin '${plugin.type}':`, error);
+          log.warn(`Error during onUnregister for plugin '${plugin.type}':`, error);
         }
       }
     }

package/src/plugin/builtin.ts

@@ -8,14 +8,7 @@
  * - SearchXNG
  */
 
-import type {
-  BraveConfig,
-  EngineConfigBase,
-  LinkupConfig,
-  SearchxngConfig,
-  TavilyConfig,
-} from "../config/types";
-import type { SearchProvider } from "../core/provider";
+import type { BraveConfig, LinkupConfig, SearchxngConfig, TavilyConfig } from "../config/types";
 import { BraveProvider } from "../providers/brave";
 import { LinkupProvider } from "../providers/linkup";
 import { SearchxngProvider } from "../providers/searchxng";
@@ -77,14 +70,19 @@ export const searchxngPlugin: PluginDefinition<SearchxngConfig, SearchxngProvide
 
 /**
  * All built-in plugins
- * Using type assertion since specific configs/providers extend base types
+ *
+ * Each plugin has a specific config/provider type (e.g. TavilyConfig/TavilyProvider),
+ * but consumers only need the base PluginDefinition interface. The factory parameter
+ * is contravariant in TConfig, so TypeScript disallows a direct assignment; however,
+ * the cast is safe because each specific config extends EngineConfigBase and each
+ * provider extends SearchProvider.
  */
 export const builtInPlugins = [
   tavilyPlugin,
   bravePlugin,
   linkupPlugin,
   searchxngPlugin,
-] as unknown as PluginDefinition<EngineConfigBase, SearchProvider>[];
+] as unknown as PluginDefinition[];
 
 /**
  * Register all built-in plugins with the registry

package/src/plugin/types.ts

@@ -190,14 +190,13 @@ export function isLifecycleProvider(
   if (provider == null || typeof provider !== "object") {
     return false;
   }
-  const obj = provider as unknown as Record<string, unknown>;
   return (
     "init" in provider &&
     "healthcheck" in provider &&
     "shutdown" in provider &&
-    typeof obj.init === "function" &&
-    typeof obj.healthcheck === "function" &&
-    typeof obj.shutdown === "function"
+    typeof (provider as Record<string, unknown>).init === "function" &&
+    typeof (provider as Record<string, unknown>).healthcheck === "function" &&
+    typeof (provider as Record<string, unknown>).shutdown === "function"
   );
 }
 

package/src/providers/brave.ts

@@ -6,6 +6,7 @@ import type { BraveConfig } from "../config/types";
 import type { SearchQuery, SearchResponse } from "../core/types";
 import { BaseProvider } from "./BaseProvider";
 import { PROVIDER_DEFAULTS } from "./constants";
+import { mapSearchResults, PROVIDER_MAPPINGS } from "./helpers";
 import type { BraveApiResponse, BraveWebResult } from "./types";
 import { buildUrl, fetchWithErrorHandling } from "./utils";
 
@@ -48,13 +49,7 @@ export class BraveProvider extends BaseProvider<BraveConfig> {
     this.validateResults(webResults, "Brave");
 
     // Map to normalized format
-    const items = webResults.map((r: BraveWebResult) => ({
-      title: r.title ?? r.url,
-      url: r.url,
-      snippet: r.description ?? r.snippet ?? r.abstract ?? "",
-      score: r.rank ?? r.score,
-      sourceEngine: this.id,
-    }));
+    const items = mapSearchResults(webResults, this.id, PROVIDER_MAPPINGS.brave);
 
     return {
       engineId: this.id,

package/src/providers/helpers/resultMappers.ts

@@ -149,8 +149,8 @@ export const PROVIDER_MAPPINGS = {
   brave: {
     title: ["title", "url"],
     url: ["url"],
-    snippet: ["description", "snippet"],
-    score: ["score"],
+    snippet: ["description", "snippet", "abstract"],
+    score: ["rank", "score"],
   },
   linkup: {
     title: ["name", "title", "url"],

package/src/providers/linkup.ts

@@ -4,32 +4,25 @@
  */
 
 import type { LinkupConfig } from "../config/types";
-import { DockerLifecycleManager } from "../core/docker/dockerLifecycleManager";
 import type { ILifecycleProvider } from "../core/provider";
 import type { SearchQuery, SearchResponse } from "../core/types";
 import { BaseProvider } from "./BaseProvider";
 import { PROVIDER_DEFAULTS } from "./constants";
+import {
+  addLifecycleMethods,
+  createDockerLifecycle,
+  mapSearchResults,
+  PROVIDER_MAPPINGS,
+} from "./helpers";
 import type { LinkupApiResponse, LinkupSearchResult } from "./types";
 import { fetchWithErrorHandling } from "./utils";
 
 export class LinkupProvider extends BaseProvider<LinkupConfig> implements ILifecycleProvider {
-  private lifecycleManager: DockerLifecycleManager;
-
   constructor(config: LinkupConfig) {
     super(config);
 
-    const autoStart = config.autoStart ?? false;
-    const autoStop = config.autoStop ?? false;
-    const initTimeoutMs = config.initTimeoutMs ?? 30000;
-
-    this.lifecycleManager = new DockerLifecycleManager({
-      containerName: config.containerName,
-      composeFile: config.composeFile,
-      healthEndpoint: config.healthEndpoint,
-      autoStart,
-      autoStop,
-      initTimeoutMs,
-    });
+    const manager = createDockerLifecycle(config);
+    addLifecycleMethods(this, manager);
   }
 
   protected getDocsUrl(): string {
@@ -70,14 +63,7 @@ export class LinkupProvider extends BaseProvider<LinkupConfig> implements ILifec
     this.validateResults(results, "Linkup");
 
     // Map to normalized format
-    // Linkup results have url, name/title, content/snippet
-    const items = results.map((r: LinkupSearchResult) => ({
-      title: r.name ?? r.title ?? r.url,
-      url: r.url,
-      snippet: r.content ?? r.snippet ?? r.description ?? "",
-      score: r.score ?? r.relevance,
-      sourceEngine: this.id,
-    }));
+    const items = mapSearchResults(results, this.id, PROVIDER_MAPPINGS.linkup);
 
     return {
       engineId: this.id,
@@ -87,28 +73,10 @@ export class LinkupProvider extends BaseProvider<LinkupConfig> implements ILifec
     };
   }
 
-  // ILifecycleProvider implementation
-  async init(): Promise<void> {
-    await this.lifecycleManager.init();
-  }
-
-  async healthcheck(): Promise<boolean> {
-    return await this.lifecycleManager.healthcheck();
-  }
-
-  async shutdown(): Promise<void> {
-    await this.lifecycleManager.shutdown();
-  }
-
-  async validateConfig(): Promise<{
-    valid: boolean;
-    errors: string[];
-    warnings: string[];
-  }> {
-    return await this.lifecycleManager.validateDockerConfig();
-  }
-
-  isLifecycleManaged(): boolean {
-    return true; // This provider manages lifecycle
-  }
+  // Lifecycle methods are added via addLifecycleMethods() in constructor
+  declare init: () => Promise<void>;
+  declare healthcheck: () => Promise<boolean>;
+  declare shutdown: () => Promise<void>;
+  declare validateConfig: () => Promise<{ valid: boolean; errors: string[]; warnings: string[] }>;
+  declare isLifecycleManaged: () => boolean;
 }