@dyingc/brave-search-mcp-server 2.0.70 → 2.1.1

package/dist/config.js

@@ -37,6 +37,25 @@ export const configSchema = z.object({
         .default(false)
         .describe('Whether the server should be stateless')
         .optional(),
+    apiKeySelectionStrategy: z
+        .enum(['greedy-max', 'greedy-min', 'soft-max'])
+        .default('soft-max')
+        .describe('API key selection strategy')
+        .optional(),
+    apiKeyTemperature: z
+        .number()
+        .min(0)
+        .max(5.0)
+        .default(1.0)
+        .describe('Temperature for soft-max strategy (0-5.0, 0 = hard limit)')
+        .optional(),
+    apiKeyExplorationRate: z
+        .number()
+        .min(0)
+        .max(1.0)
+        .default(0.1)
+        .describe('Epsilon for epsilon-greedy exploration (0-1, 0 = no exploration, 1 = always random)')
+        .optional(),
 });
 const state = {
     transport: 'stdio',
@@ -51,6 +70,9 @@ const state = {
     retryMaxAttempts: 5,
     retryBaseDelay: 1000,
     retryMaxDelay: 30000,
+    apiKeySelectionStrategy: 'soft-max',
+    apiKeyTemperature: 1.0,
+    apiKeyExplorationRate: 0.1,
 };
 export function isToolPermittedByUser(toolName) {
     return state.enabledTools.length > 0
@@ -101,6 +123,9 @@ export function getOptions() {
         .option('--retry-max-attempts <number>', 'Maximum retry attempts for rate-limited requests', process.env.BRAVE_MCP_MAX_RETRIES ?? '5')
         .option('--retry-base-delay <number>', 'Base delay for retry in milliseconds', process.env.BRAVE_MCP_RETRY_BASE_DELAY ?? '1000')
         .option('--retry-max-delay <number>', 'Maximum delay for retry in milliseconds', process.env.BRAVE_MCP_RETRY_MAX_DELAY ?? '30000')
+        .option('--api-key-selection-strategy <strategy>', 'API key selection strategy (greedy-max, greedy-min, soft-max)', process.env.BRAVE_API_KEY_SELECTION_STRATEGY ?? 'soft-max')
+        .option('--api-key-temperature <number>', 'Temperature for soft-max strategy (0-5.0, default: 1.0, 0 = hard limit)', process.env.BRAVE_API_KEY_TEMPERATURE ?? '1.0')
+        .option('--api-key-exploration-rate <number>', 'Epsilon for epsilon-greedy exploration (0-1, default: 0.1)', process.env.BRAVE_API_KEY_EXPLORATION_RATE ?? '0.1')
         .allowUnknownOption()
         .parse(process.argv);
     const options = program.opts();
@@ -150,6 +175,27 @@ export function getOptions() {
         return false;
     }
     options.retryMaxDelay = retryMaxDelay;
+    // Validate API key selection strategy
+    const validStrategies = ['greedy-max', 'greedy-min', 'soft-max'];
+    if (!validStrategies.includes(options.apiKeySelectionStrategy)) {
+        console.error(`Invalid --api-key-selection-strategy value: '${options.apiKeySelectionStrategy}'. Must be one of: ${validStrategies.join(', ')}`);
+        return false;
+    }
+    // Validate temperature (range 0-5.0)
+    const temperature = parseFloat(options.apiKeyTemperature);
+    if (isNaN(temperature) || temperature < 0 || temperature > 5.0) {
+        console.error(`Invalid --api-key-temperature value: '${options.apiKeyTemperature}'. Must be a number between 0 and 5.0`);
+        return false;
+    }
+    options.apiKeyTemperature = temperature;
+    options.apiKeySelectionStrategy = options.apiKeySelectionStrategy;
+    // Validate exploration rate (range 0-1)
+    const explorationRate = parseFloat(options.apiKeyExplorationRate ?? '0.1');
+    if (isNaN(explorationRate) || explorationRate < 0 || explorationRate > 1) {
+        console.error(`Invalid --api-key-exploration-rate value: '${options.apiKeyExplorationRate}'. Must be a number between 0 and 1`);
+        return false;
+    }
+    options.apiKeyExplorationRate = explorationRate;
     if (options.transport === 'http') {
         if (options.port < 1 || options.port > 65535) {
             console.error(`Invalid --port value: '${options.port}'. Must be a valid port number between 1 and 65535.`);
@@ -174,6 +220,9 @@ export function getOptions() {
     state.retryMaxAttempts = options.retryMaxAttempts;
     state.retryBaseDelay = options.retryBaseDelay;
     state.retryMaxDelay = options.retryMaxDelay;
+    state.apiKeySelectionStrategy = options.apiKeySelectionStrategy;
+    state.apiKeyTemperature = options.apiKeyTemperature;
+    state.apiKeyExplorationRate = options.apiKeyExplorationRate;
     state.ready = true;
     return options;
 }

package/dist/index.js

@@ -8,8 +8,12 @@ async function main() {
         console.error('Invalid configuration');
         process.exit(1);
     }
-    // Initialize API Key Manager with parsed keys
-    initApiKeyManager(options.braveApiKeys);
+    // Initialize API Key Manager with parsed keys and selection strategy
+    initApiKeyManager(options.braveApiKeys, {
+        selectionStrategy: options.apiKeySelectionStrategy,
+        temperature: options.apiKeyTemperature,
+        explorationRate: options.apiKeyExplorationRate,
+    });
     // default to stdio server unless http is explicitly requested
     if (options.transport === 'http') {
         httpServer.start();

package/dist/utils/apiKeyManager.js

@@ -12,9 +12,17 @@ const DEFAULT_PER_SECOND_LIMIT = 1;
 const STATE_FILE = path.join(os.homedir(), '.brave-mcp', 'state.json');
 class ApiKeyManager {
     keys;
-    constructor(apiKeys, initialQuota = FREE_TIER_MONTHLY_QUOTA) {
+    selectionStrategy;
+    temperature;
+    explorationRate; // Probability of random exploration
+    constructor(apiKeys, options = {}) {
         this.keys = new Map();
         const savedStates = this.loadState();
+        const { initialQuota = FREE_TIER_MONTHLY_QUOTA, selectionStrategy = 'soft-max', temperature = 1.0, explorationRate = 0.1, // Default 10% exploration rate
+         } = options;
+        this.selectionStrategy = selectionStrategy;
+        this.temperature = temperature;
+        this.explorationRate = explorationRate;
         for (const key of apiKeys) {
             const keyHash = key.slice(0, 8);
             const savedRemaining = savedStates.get(keyHash);
@@ -49,7 +57,6 @@ class ApiKeyManager {
                     result.set(keyHash, info.remaining);
                 }
             }
-            console.log(`[ApiKeyManager] Loaded state for ${result.size} keys from ${STATE_FILE}`);
             return result;
         }
         catch (err) {
@@ -85,25 +92,121 @@ class ApiKeyManager {
     }
     /**
      * Select the best available key based on remaining quota
+     * Uses epsilon-greedy strategy: explore randomly with probability epsilon,
+     * otherwise exploit using the configured selection strategy
      * Returns null if no valid keys available
      */
     selectBestKey() {
         // Filter valid keys with remaining quota and not in use
         const availableKeys = Array.from(this.keys.values()).filter((k) => k.isValid && k.remainingQuota > 0 && !k.inUse);
+        // No available keys
         if (availableKeys.length === 0) {
             return null;
         }
-        // Sort by remaining quota (descending)
-        availableKeys.sort((a, b) => b.remainingQuota - a.remainingQuota);
-        // Get keys with max quota
-        const maxQuota = availableKeys[0].remainingQuota;
-        const topKeys = availableKeys.filter((k) => k.remainingQuota === maxQuota);
-        // Random selection if tied
-        const selected = topKeys.length > 1 ? topKeys[Math.floor(Math.random() * topKeys.length)] : topKeys[0];
-        // Mark as in-use
+        // Single available key - return directly
+        if (availableKeys.length === 1) {
+            availableKeys[0].inUse = true;
+            return availableKeys[0].key;
+        }
+        let selected;
+        // Epsilon-greedy exploration: random selection with probability epsilon
+        if (Math.random() < this.explorationRate) {
+            selected = availableKeys[Math.floor(Math.random() * availableKeys.length)];
+        }
+        else {
+            switch (this.selectionStrategy) {
+                case 'greedy-min':
+                    selected = this.selectGreedyMin(availableKeys);
+                    break;
+                case 'soft-max':
+                    selected = this.selectKeyWithSoftMax(availableKeys, this.temperature);
+                    break;
+                case 'greedy-max':
+                default:
+                    selected = this.selectGreedyMax(availableKeys);
+                    break;
+            }
+        }
+        // selected should never be null here since we checked availableKeys.length >= 2
+        if (!selected) {
+            return null;
+        }
         selected.inUse = true;
         return selected.key;
     }
+    /**
+     * Select key with maximum remaining quota (greedy-max)
+     */
+    selectGreedyMax(keys) {
+        keys.sort((a, b) => b.remainingQuota - a.remainingQuota);
+        const maxQuota = keys[0].remainingQuota;
+        const topKeys = keys.filter((k) => k.remainingQuota === maxQuota);
+        return topKeys.length > 1 ? topKeys[Math.floor(Math.random() * topKeys.length)] : topKeys[0];
+    }
+    /**
+     * Select key with minimum remaining quota (greedy-min)
+     */
+    selectGreedyMin(keys) {
+        keys.sort((a, b) => a.remainingQuota - b.remainingQuota);
+        const minQuota = keys[0].remainingQuota;
+        const bottomKeys = keys.filter((k) => k.remainingQuota === minQuota);
+        return bottomKeys.length > 1
+            ? bottomKeys[Math.floor(Math.random() * bottomKeys.length)]
+            : bottomKeys[0];
+    }
+    /**
+     * Calculate soft max probabilities for key selection
+     * Uses standard soft max formula: softmax_i(z;T) = exp(z_i/T) / sum(exp(z_j/T))
+     * where z_i = -remainingQuota (lower remaining = higher selection probability)
+     *
+     * Example with T=1:
+     * - Key with 1 remaining: score = -1, exp(-1) ≈ 0.368
+     * - Key with 10 remaining: score = -10, exp(-10) ≈ 0.000045
+     * - Key with 1 remaining has much higher selection probability
+     *
+     * Probabilities always sum to 1 by definition of softmax formula
+     */
+    calculateSoftMaxProbabilities(keys, temperature) {
+        // Use negative remaining quota as score: lower remaining = higher score
+        const scores = keys.map((k) => -k.remainingQuota);
+        // Standard soft max: scale by temperature
+        const scaledScores = scores.map((s) => s / temperature);
+        // Numerical stability: subtract max value
+        const maxScore = Math.max(...scaledScores);
+        const expScores = scaledScores.map((s) => Math.exp(s - maxScore));
+        const sumExp = expScores.reduce((sum, exp) => sum + exp, 0);
+        const probabilities = expScores.map((exp) => exp / sumExp);
+        return keys.map((key, index) => ({
+            key,
+            probability: probabilities[index],
+        }));
+    }
+    /**
+     * Select key using soft max probability distribution
+     * temperature = 0: hard limit (equivalent to greedy-min)
+     */
+    selectKeyWithSoftMax(keys, temperature) {
+        // Empty array
+        if (keys.length === 0) {
+            return null;
+        }
+        // temperature = 0: hard limit, equivalent to greedy-min
+        if (temperature === 0) {
+            return this.selectGreedyMin(keys);
+        }
+        const keyProbabilities = this.calculateSoftMaxProbabilities(keys, temperature);
+        // Weighted random sampling (roulette wheel selection)
+        const random = Math.random();
+        let cumulativeProbability = 0;
+        for (const { key, probability } of keyProbabilities) {
+            cumulativeProbability += probability;
+            if (random <= cumulativeProbability) {
+                return key;
+            }
+        }
+        // Fallback to last key
+        return keyProbabilities[keyProbabilities.length - 1].key;
+    }
     /**
      * Release a key after request completion
      */
@@ -142,7 +245,6 @@ class ApiKeyManager {
         state.inUse = false;
         // Save state after update
         this.saveState();
-        console.debug(`[ApiKeyManager] Key ${apiKey.slice(0, 8)}... quota: ${state.remainingQuota}/${state.monthLimit}`);
     }
     /**
      * Mark a key as invalid (e.g., 401 Unauthorized)
@@ -180,8 +282,8 @@ class ApiKeyManager {
 }
 // Singleton instance
 let apiKeyManagerInstance = null;
-export function initApiKeyManager(apiKeys) {
-    apiKeyManagerInstance = new ApiKeyManager(apiKeys);
+export function initApiKeyManager(apiKeys, options) {
+    apiKeyManagerInstance = new ApiKeyManager(apiKeys, options);
 }
 export function getApiKeyManager() {
     return apiKeyManagerInstance;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@dyingc/brave-search-mcp-server",
   "mcpName": "io.github.brave/brave-search-mcp-server",
   "private": false,
-  "version": "2.0.70",
+  "version": "2.1.1",
   "description": "Brave Search MCP Server: web results, images, videos, rich results, AI summaries, and more.",
   "keywords": [
     "api",