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

package/README.md

@@ -129,6 +129,48 @@ The server supports the following environment variables:
 - `BRAVE_MCP_RETRY_BASE_DELAY`: Base delay for retry in milliseconds (default: 1000, range: 100-60000)
 - `BRAVE_MCP_RETRY_MAX_DELAY`: Maximum delay for retry in milliseconds (default: 30000, range: 1000-300000)
 
+### Multiple API Keys
+
+When using multiple API keys, the server automatically load balances requests across keys based on remaining monthly quota. Keys with more available quota are prioritized.
+
+**Environment Variables for Multiple Keys:**
+
+1. `BRAVE_API_KEYS`: Comma-separated list of API keys
+   ```bash
+   export BRAVE_API_KEYS="key1,key2,key3"
+   ```
+
+2. Numbered variables (legacy):
+   ```bash
+   export BRAVE_API_KEY_1="key1"
+   export BRAVE_API_KEY_2="key2"
+   export BRAVE_API_KEY_3="key3"
+   ```
+
+**State Persistence:**
+
+The server persists API key quota state to `~/.brave-mcp/state.json` to maintain consistent load balancing across server restarts:
+
+- State is saved after each API request
+- On startup, state is loaded if the timestamp is within the current month
+- State automatically resets at the beginning of each month (matches API quota cycle)
+- If the state file is missing or corrupted, the server starts with default quota (2000 requests per key)
+
+**State File Format:**
+```json
+{
+  "version": 1,
+  "keys": {
+    "BSKa1234": {
+      "remaining": 1500,
+      "timestamp": "2025-02-03T10:00:00Z"
+    }
+  }
+}
+```
+
+**Note:** For security, only the first 8 characters of each API key are stored in the state file.
+
 ### Command Line Options
 
 ```bash

package/dist/utils/apiKeyManager.js

@@ -2,17 +2,25 @@
  * API Key Manager for multi-key support with quota tracking
  * Designed for free tier keys (2000 requests/month per key)
  */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
 // Free tier constants
 const FREE_TIER_MONTHLY_QUOTA = 2000;
 const DEFAULT_PER_SECOND_LIMIT = 1;
+// State file path
+const STATE_FILE = path.join(os.homedir(), '.brave-mcp', 'state.json');
 class ApiKeyManager {
     keys;
     constructor(apiKeys, initialQuota = FREE_TIER_MONTHLY_QUOTA) {
         this.keys = new Map();
+        const savedStates = this.loadState();
         for (const key of apiKeys) {
+            const keyHash = key.slice(0, 8);
+            const savedRemaining = savedStates.get(keyHash);
             this.keys.set(key, {
                 key,
-                remainingQuota: initialQuota,
+                remainingQuota: savedRemaining ?? initialQuota,
                 monthLimit: FREE_TIER_MONTHLY_QUOTA,
                 remainingSecond: DEFAULT_PER_SECOND_LIMIT,
                 secondLimit: DEFAULT_PER_SECOND_LIMIT,
@@ -21,6 +29,60 @@ class ApiKeyManager {
             });
         }
     }
+    /**
+     * Load saved state from file, filtering for current month only
+     * Returns Map of keyHash -> remaining quota
+     */
+    loadState() {
+        try {
+            if (!fs.existsSync(STATE_FILE)) {
+                return new Map();
+            }
+            const data = JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+            const now = new Date();
+            const result = new Map();
+            for (const [keyHash, info] of Object.entries(data.keys)) {
+                const timestamp = new Date(info.timestamp);
+                // Only use state from current month
+                if (timestamp.getMonth() === now.getMonth() &&
+                    timestamp.getFullYear() === now.getFullYear()) {
+                    result.set(keyHash, info.remaining);
+                }
+            }
+            console.log(`[ApiKeyManager] Loaded state for ${result.size} keys from ${STATE_FILE}`);
+            return result;
+        }
+        catch (err) {
+            console.warn(`[ApiKeyManager] Failed to load state: ${err.message}`);
+            return new Map();
+        }
+    }
+    /**
+     * Save current state to file
+     */
+    saveState() {
+        try {
+            const dir = path.dirname(STATE_FILE);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            const data = {
+                version: 1,
+                keys: {},
+            };
+            for (const [key, state] of this.keys.entries()) {
+                const keyHash = key.slice(0, 8);
+                data.keys[keyHash] = {
+                    remaining: state.remainingQuota,
+                    timestamp: new Date().toISOString(),
+                };
+            }
+            fs.writeFileSync(STATE_FILE, JSON.stringify(data, null, 2));
+        }
+        catch (err) {
+            console.warn(`[ApiKeyManager] Failed to save state: ${err.message}`);
+        }
+    }
     /**
      * Select the best available key based on remaining quota
      * Returns null if no valid keys available
@@ -78,6 +140,8 @@ class ApiKeyManager {
         state.monthLimit = limit.perMonth;
         state.secondLimit = limit.perSecond;
         state.inUse = false;
+        // Save state after update
+        this.saveState();
         console.debug(`[ApiKeyManager] Key ${apiKey.slice(0, 8)}... quota: ${state.remainingQuota}/${state.monthLimit}`);
     }
     /**

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