ubersearch 1.1.3 → 1.3.0

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "ubersearch",
-  "version": "1.1.3",
+  "version": "1.3.0",
   "module": "src/index.ts",
   "type": "module",
   "bin": {
-    "ubersearch": "src/cli.ts"
+    "ubersearch": "src/cli.ts",
+    "ubersearch-mcp": "src/mcp-server.ts"
   },
   "exports": {
     ".": {

package/src/cli.ts

@@ -43,20 +43,27 @@ ARGUMENTS:
 OPTIONS:
     --json                      Output results as JSON
     --engines <engine,list>     Use specific engines (comma-separated)
+    --categories <cat,list>     SearXNG categories (comma-separated)
     --strategy <strategy>       Search strategy: 'all' or 'first-success' (default: all)
     --limit <number>            Maximum results per engine
     --include-raw               Include raw provider responses
     --config <path>             Path to configuration file
     --help, -h                  Show this help message
 
+CATEGORIES (SearXNG):
+    general     Web search (brave, duckduckgo, startpage, qwant)
+    it          Tech (github, stackoverflow, npm, pypi, huggingface)
+    science     Academic (arxiv, google_scholar)
+    news        News (hackernews, reddit, bbc)
+    videos      Video (youtube)
+
 EXAMPLES:
     ubersearch "best TypeScript ORM 2025"
     ubersearch "llm observability" --engines tavily,brave --json
+    ubersearch "typescript error" --categories it
+    ubersearch "machine learning" --categories science,it
     ubersearch "hawaii dev meetups" --strategy first-success
     ubersearch credits
-    ubersearch health
-    ubersearch --config /path/to/config.json credits
-    ubersearch "query" --config /path/to/config.json
 
 CONFIGURATION:
     Config files are searched in order:
@@ -91,6 +98,7 @@ const options = {
   engines: undefined as string[] | undefined,
   strategy: undefined as "all" | "first-success" | undefined,
   limit: undefined as number | undefined,
+  categories: undefined as string[] | undefined,
 };
 
 // Parse --engines
@@ -128,9 +136,18 @@ if (limitIdx !== -1) {
   }
 }
 
+// Parse --categories
+const categoriesIdx = args.indexOf("--categories");
+if (categoriesIdx !== -1) {
+  const categoriesArg = args[categoriesIdx + 1];
+  if (categoriesArg !== undefined) {
+    options.categories = categoriesArg.split(",").map((c) => c.trim());
+  }
+}
+
 // Extract query (non-option arguments)
 // Filter out option flags (--*) and their values
-const optionsWithValues = ["--engines", "--strategy", "--limit", "--config"];
+const optionsWithValues = ["--engines", "--strategy", "--limit", "--config", "--categories"];
 const queryParts = args.filter((arg, idx) => {
   // Skip arguments starting with --
   if (arg.startsWith("--")) {
@@ -169,6 +186,7 @@ async function main() {
         engines: options.engines,
         includeRaw: options.includeRaw,
         strategy: options.strategy,
+        categories: options.categories,
       },
       { containerOverride: container },
     );

package/src/config/load.ts

@@ -235,7 +235,7 @@ function getDefaultConfig(): ExtendedSearchConfig {
       displayName: "Brave Search",
       apiKeyEnv: "BRAVE_API_KEY",
       endpoint: "https://api.search.brave.com/res/v1/web/search",
-      defaultLimit: 10,
+      defaultLimit: 15,
       monthlyQuota: 1000,
       creditCostPerSearch: 1,
       lowCreditThresholdPercent: 80,
@@ -273,7 +273,7 @@ function getDefaultConfig(): ExtendedSearchConfig {
       composeFile,
       containerName: "searxng",
       healthEndpoint: "http://localhost:8888/healthz",
-      defaultLimit: 10,
+      defaultLimit: 15,
       monthlyQuota: 10000,
       creditCostPerSearch: 0,
       lowCreditThresholdPercent: 80,

package/src/core/container.ts

@@ -127,7 +127,7 @@ export class Container {
 
     // Handle singleton caching
     if (binding.singleton && binding.cached !== undefined) {
-      return binding.cached;
+      return binding.cached as T;
     }
 
     // Track resolution for circular dependency detection
@@ -142,7 +142,7 @@ export class Container {
         binding.cached = instance;
       }
 
-      return instance;
+      return instance as T;
     } catch (error) {
       // Enhance error message with context
       if (error instanceof Error) {

package/src/core/orchestrator.ts

@@ -23,6 +23,9 @@ export interface UberSearchOptions {
 
   /** Search strategy */
   strategy?: "all" | "first-success";
+
+  /** SearXNG categories to search (e.g., ["general", "it", "science"]) */
+  categories?: string[];
 }
 
 export interface EngineAttempt {
@@ -54,12 +57,13 @@ export class UberSearchOrchestrator {
 
   /**
    * Determine the engine order to use for this search
+   * Only includes engines that are actually registered in the provider registry
    */
   private getEngineOrder(override?: EngineId[]): EngineId[] {
-    if (override?.length) {
-      return override;
-    }
-    return this.config.defaultEngineOrder;
+    const baseOrder = override?.length ? override : this.config.defaultEngineOrder;
+
+    // Filter to only include engines that are registered (have valid providers)
+    return baseOrder.filter((engineId) => this.registry.get(engineId) !== undefined);
   }
 
   /**

package/src/core/strategy/AllProvidersStrategy.ts

@@ -92,6 +92,7 @@ export class AllProvidersStrategy implements ISearchStrategy {
           query,
           limit: options.limit,
           includeRaw: options.includeRaw,
+          categories: options.categories,
         });
 
         // Deduct credits
@@ -175,6 +176,7 @@ export class AllProvidersStrategy implements ISearchStrategy {
             query,
             limit: options.limit,
             includeRaw: options.includeRaw,
+            categories: options.categories,
           });
           return { engineId, response };
         } catch (error) {
@@ -189,7 +191,14 @@ export class AllProvidersStrategy implements ISearchStrategy {
     // Process results in original order (maintain engine priority)
     for (let i = 0; i < searchResults.length; i++) {
       const settledResult = searchResults[i];
-      const { engineId } = eligibleEngines[i];
+      const eligibleEngine = eligibleEngines[i];
+
+      // Safety check (should always exist, but TypeScript needs this)
+      if (!settledResult || !eligibleEngine) {
+        continue;
+      }
+
+      const { engineId } = eligibleEngine;
 
       if (settledResult.status === "rejected") {
         // Promise itself was rejected (shouldn't happen with our try/catch, but handle it)

package/src/core/strategy/FirstSuccessStrategy.ts

@@ -64,6 +64,7 @@ export class FirstSuccessStrategy implements ISearchStrategy {
           query,
           limit: options.limit,
           includeRaw: options.includeRaw,
+          categories: options.categories,
         });
 
         // Deduct credits

package/src/core/strategy/ISearchStrategy.ts

@@ -42,6 +42,9 @@ export interface UberSearchOptions {
    * When false (default), providers are queried sequentially
    */
   parallel?: boolean;
+
+  /** SearXNG categories to search (e.g., ["general", "it", "science"]) */
+  categories?: string[];
 }
 
 /**

package/src/core/strategy/index.ts

@@ -6,4 +6,3 @@ export * from "./AllProvidersStrategy";
 export * from "./FirstSuccessStrategy";
 export * from "./ISearchStrategy";
 export * from "./StrategyFactory";
-export * from "./types";

package/src/core/types.ts

@@ -8,6 +8,8 @@ export interface SearchQuery {
   query: string;
   limit?: number;
   includeRaw?: boolean;
+  /** SearXNG categories to search (e.g., "general", "it", "science") */
+  categories?: string[];
 }
 
 export interface SearchResultItem {

package/src/mcp-server.ts

@@ -82,6 +82,17 @@ export async function serve() {
             description: "Maximum results per engine",
             default: 10,
           },
+          categories: {
+            type: "string",
+            description: `SearXNG categories (comma-separated). Available categories:
+- general: Web search (brave, duckduckgo, startpage, qwant)
+- it: Tech (github, stackoverflow, npm, pypi, huggingface)
+- science: Academic (arxiv, google_scholar)
+- news: News (hackernews, reddit, bbc)
+- videos: Video (youtube)
+Example: "it,science" for tech and academic results`,
+            default: "",
+          },
         },
         required: ["query"],
       },
@@ -165,12 +176,16 @@ export async function serve() {
           const engines = args.engines
             ? args.engines.split(",").map((e: string) => e.trim())
             : undefined;
+          const categories = args.categories
+            ? args.categories.split(",").map((c: string) => c.trim())
+            : undefined;
           result = await withTimeout(
             uberSearch({
               query: args.query,
               limit: args.limit,
               engines,
               strategy: args.strategy,
+              categories,
             }),
             60000,
             "uberSearch",

package/src/plugin/builtin.ts

@@ -77,14 +77,14 @@ export const searchxngPlugin: PluginDefinition<SearchxngConfig, SearchxngProvide
 
 /**
  * All built-in plugins
- * Using base types since specific configs/providers extend them
+ * Using type assertion since specific configs/providers extend base types
  */
-export const builtInPlugins: PluginDefinition<EngineConfigBase, SearchProvider>[] = [
+export const builtInPlugins = [
   tavilyPlugin,
   bravePlugin,
   linkupPlugin,
   searchxngPlugin,
-];
+] as unknown as PluginDefinition<EngineConfigBase, SearchProvider>[];
 
 /**
  * Register all built-in plugins with the registry

package/src/plugin/types.ts

@@ -119,12 +119,12 @@ export interface PluginDefinition<
 /**
  * Helper type to extract config type from a plugin definition
  */
-export type PluginConfig<T> = T extends PluginDefinition<infer C, unknown> ? C : never;
+export type PluginConfig<T> = T extends PluginDefinition<infer C, SearchProvider> ? C : never;
 
 /**
  * Helper type to extract provider type from a plugin definition
  */
-export type PluginProvider<T> = T extends PluginDefinition<unknown, infer P> ? P : never;
+export type PluginProvider<T> = T extends PluginDefinition<EngineConfigBase, infer P> ? P : never;
 
 /**
  * Registration options when adding a plugin to the registry
@@ -190,7 +190,7 @@ export function isLifecycleProvider(
   if (provider == null || typeof provider !== "object") {
     return false;
   }
-  const obj = provider as Record<string, unknown>;
+  const obj = provider as unknown as Record<string, unknown>;
   return (
     "init" in provider &&
     "healthcheck" in provider &&

package/src/providers/brave.ts

@@ -21,7 +21,7 @@ export class BraveProvider extends BaseProvider<BraveConfig> {
   async search(query: SearchQuery): Promise<SearchResponse> {
     const apiKey = this.getApiKey();
 
-    const limit = query.limit ?? this.config.defaultLimit ?? 10;
+    const limit = query.limit ?? this.config.defaultLimit ?? 15;
     const url = buildUrl(this.config.endpoint, {
       q: query.query,
       count: limit,

package/src/providers/searchxng.ts

@@ -102,13 +102,20 @@ export class SearchxngProvider
     }
 
     const limit = query.limit ?? this.defaultLimit;
-    const url = buildUrl(this.config.endpoint, {
+    const params: Record<string, string | number> = {
       q: query.query,
       format: "json",
       language: "all",
       pageno: 1,
       safesearch: 0,
-    });
+    };
+
+    // Add categories if specified (e.g., "general,it,science")
+    if (query.categories && query.categories.length > 0) {
+      params.categories = query.categories.join(",");
+    }
+
+    const url = buildUrl(this.config.endpoint, params);
 
     const { data: json, tookMs } = await fetchWithErrorHandling<SearxngApiResponse>(
       this.id,

package/src/tool/interface.ts

@@ -24,6 +24,9 @@ export interface UberSearchInput {
    * When false (default), providers are queried sequentially
    */
   parallel?: boolean;
+
+  /** SearXNG categories to search (e.g., ["general", "it", "science"]) */
+  categories?: string[];
 }
 
 export interface UberSearchEngineAttempt {

package/src/tool/uberSearchTool.ts

@@ -55,6 +55,7 @@ export async function uberSearch(
     engineOrderOverride: input.engines,
     includeRaw: input.includeRaw,
     strategy: input.strategy ?? "all",
+    categories: input.categories,
   });
 
   // Format output

package/src/core/strategy/types.ts

@@ -1,56 +0,0 @@
-/**
- * Strategy interface and types for search execution patterns
- */
-
-import type { CreditManager } from "../credits";
-import type { ProviderRegistry } from "../provider";
-import type { EngineId, SearchQuery, SearchResultItem } from "../types";
-
-/**
- * Context passed to search strategies containing dependencies
- */
-export interface StrategyContext {
-  /** Provider registry for accessing search providers */
-  registry: ProviderRegistry;
-  /** Credit manager for checking and charging credits */
-  credits: CreditManager;
-}
-
-/**
- * Result from a search strategy execution
- */
-export interface StrategyResult {
-  /** Search results from successful providers */
-  results: SearchResultItem[];
-  /** Metadata about engine attempts */
-  attempts: EngineAttempt[];
-}
-
-/**
- * Engine attempt metadata
- */
-export interface EngineAttempt {
-  engineId: EngineId;
-  success: boolean;
-  reason?: string;
-}
-
-/**
- * Interface for implementing different search execution strategies
- */
-export interface ISearchStrategy {
-  /**
-   * Execute search using this strategy
-   * @param query - The search query
-   * @param engineIds - Ordered list of engine IDs to try
-   * @param options - Search options (limit, includeRaw, etc.)
-   * @param context - Strategy context with dependencies
-   * @returns Promise resolving to strategy result
-   */
-  execute(
-    query: string,
-    engineIds: EngineId[],
-    options: SearchQuery,
-    context: StrategyContext,
-  ): Promise<StrategyResult>;
-}