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

package/dist/config.js

@@ -49,6 +49,13 @@ export const configSchema = z.object({
         .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',
@@ -65,6 +72,7 @@ const state = {
     retryMaxDelay: 30000,
     apiKeySelectionStrategy: 'soft-max',
     apiKeyTemperature: 1.0,
+    apiKeyExplorationRate: 0.1,
 };
 export function isToolPermittedByUser(toolName) {
     return state.enabledTools.length > 0
@@ -117,6 +125,7 @@ export function getOptions() {
         .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();
@@ -180,6 +189,13 @@ export function getOptions() {
     }
     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.`);
@@ -206,6 +222,7 @@ export function getOptions() {
     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

@@ -12,6 +12,7 @@ async function main() {
     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') {

package/dist/utils/apiKeyManager.js

@@ -14,12 +14,15 @@ class ApiKeyManager {
     keys;
     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, } = options;
+        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);
@@ -89,6 +92,8 @@ 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() {
@@ -104,17 +109,23 @@ class ApiKeyManager {
             return availableKeys[0].key;
         }
         let selected;
-        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;
+        // 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) {
@@ -145,15 +156,19 @@ class ApiKeyManager {
     }
     /**
      * Calculate soft max probabilities for key selection
-     * Uses total normalization + standard soft max formula
+     * 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) {
-        // Calculate total quota for normalization
-        const totalQuota = keys.reduce((sum, k) => sum + k.remainingQuota, 0);
-        // Normalize by total (sum of normalized values = 1), then invert (lower quota = higher score)
-        // normalized_quota = quota / total_quota ∈ [0, 1]
-        // score = -normalized_quota ∈ [-1, 0], lower quota gives score closer to 0
-        const scores = keys.map((k) => -k.remainingQuota / totalQuota);
+        // 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

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.1.0",
+  "version": "2.1.1",
   "description": "Brave Search MCP Server: web results, images, videos, rich results, AI summaries, and more.",
   "keywords": [
     "api",