@dyingc/brave-search-mcp-server 2.0.69

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Anthropic, PBC
+Copyright (c) 2025 Brave Software, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,356 @@
+# Brave Search MCP Server
+
+An MCP server implementation that integrates the Brave Search API, providing comprehensive search capabilities including web search, local business search, image search, video search, news search, and AI-powered summarization. This project supports both STDIO and HTTP transports, with STDIO as the default mode.
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/brave/brave-search-mcp-server)
+
+## Migration
+
+### 1.x to 2.x
+
+#### Default transport now STDIO
+
+To follow established MCP conventions, the server now defaults to STDIO. If you would like to continue using HTTP, you will need to set the `BRAVE_MCP_TRANSPORT` environment variable to `http`, or provide the runtime argument `--transport http` when launching the server.
+
+#### Response structure of `brave_image_search`
+
+Version 1.x of the MCP server would return base64-encoded image data along with image URLs. This dramatically slowed down the response, as well as consumed unnecessarily context in the session. Version 2.x removes the base64-encoded data, and returns a response object that more closely reflects the original Brave Search API response. The updated output schema is defined in [`src/tools/images/schemas/output.ts`](https://github.com/brave/brave-search-mcp-server/blob/main/src/tools/images/schemas/output.ts).
+
+## Tools
+
+### Web Search (`brave_web_search`)
+Performs comprehensive web searches with rich result types and advanced filtering options.
+
+**Parameters:**
+- `query` (string, required): Search terms (max 400 chars, 50 words)
+- `country` (string, optional): Country code (default: "US")
+- `search_lang` (string, optional): Search language (default: "en")
+- `ui_lang` (string, optional): UI language (default: "en-US")
+- `count` (number, optional): Results per page (1-20, default: 10)
+- `offset` (number, optional): Pagination offset (max 9, default: 0)
+- `safesearch` (string, optional): Content filtering ("off", "moderate", "strict", default: "moderate")
+- `freshness` (string, optional): Time filter ("pd", "pw", "pm", "py", or date range)
+- `text_decorations` (boolean, optional): Include highlighting markers (default: true)
+- `spellcheck` (boolean, optional): Enable spell checking (default: true)
+- `result_filter` (array, optional): Filter result types (default: ["web", "query"])
+- `goggles` (array, optional): Custom re-ranking definitions
+- `units` (string, optional): Measurement units ("metric" or "imperial")
+- `extra_snippets` (boolean, optional): Get additional excerpts (Pro plans only)
+- `summary` (boolean, optional): Enable summary key generation for AI summarization
+
+### Local Search (`brave_local_search`)
+Searches for local businesses and places with detailed information including ratings, hours, and AI-generated descriptions.
+
+**Parameters:**
+- Same as `brave_web_search` with automatic location filtering
+- Automatically includes "web" and "locations" in result_filter
+
+**Note:** Requires Pro plan for full local search capabilities. Falls back to web search otherwise.
+
+### Video Search (`brave_video_search`)
+Searches for videos with comprehensive metadata and thumbnail information.
+
+**Parameters:**
+- `query` (string, required): Search terms (max 400 chars, 50 words)
+- `country` (string, optional): Country code (default: "US")
+- `search_lang` (string, optional): Search language (default: "en")
+- `ui_lang` (string, optional): UI language (default: "en-US")
+- `count` (number, optional): Results per page (1-50, default: 20)
+- `offset` (number, optional): Pagination offset (max 9, default: 0)
+- `spellcheck` (boolean, optional): Enable spell checking (default: true)
+- `safesearch` (string, optional): Content filtering ("off", "moderate", "strict", default: "moderate")
+- `freshness` (string, optional): Time filter ("pd", "pw", "pm", "py", or date range)
+
+### Image Search (`brave_image_search`)
+Searches for images with automatic fetching and base64 encoding for direct display.
+
+**Parameters:**
+- `query` (string, required): Search terms (max 400 chars, 50 words)
+- `country` (string, optional): Country code (default: "US")
+- `search_lang` (string, optional): Search language (default: "en")
+- `count` (number, optional): Results per page (1-200, default: 50)
+- `safesearch` (string, optional): Content filtering ("off", "strict", default: "strict")
+- `spellcheck` (boolean, optional): Enable spell checking (default: true)
+
+### News Search (`brave_news_search`)
+Searches for current news articles with freshness controls and breaking news indicators.
+
+**Parameters:**
+- `query` (string, required): Search terms (max 400 chars, 50 words)
+- `country` (string, optional): Country code (default: "US")
+- `search_lang` (string, optional): Search language (default: "en")
+- `ui_lang` (string, optional): UI language (default: "en-US")
+- `count` (number, optional): Results per page (1-50, default: 20)
+- `offset` (number, optional): Pagination offset (max 9, default: 0)
+- `spellcheck` (boolean, optional): Enable spell checking (default: true)
+- `safesearch` (string, optional): Content filtering ("off", "moderate", "strict", default: "moderate")
+- `freshness` (string, optional): Time filter (default: "pd" for last 24 hours)
+- `extra_snippets` (boolean, optional): Get additional excerpts (Pro plans only)
+- `goggles` (array, optional): Custom re-ranking definitions
+
+### Summarizer Search (`brave_summarizer`)
+Generates AI-powered summaries from web search results using Brave's summarization API.
+
+**Parameters:**
+- `key` (string, required): Summary key from web search results (use `summary: true` in web search)
+- `entity_info` (boolean, optional): Include entity information (default: false)
+- `inline_references` (boolean, optional): Add source URL references (default: false)
+
+**Usage:** First perform a web search with `summary: true`, then use the returned summary key with this tool.
+
+## Configuration
+
+### Getting an API Key
+
+1. Sign up for a [Brave Search API account](https://brave.com/search/api/)
+2. Choose a plan:
+   - **Free**: 2,000 queries/month, basic web search
+   - **Pro**: Enhanced features including local search, AI summaries, extra snippets
+3. Generate your API key from the [developer dashboard](https://api-dashboard.search.brave.com/app/keys)
+
+### Environment Variables
+
+The server supports the following environment variables:
+
+**Required:**
+- `BRAVE_API_KEY`: Your Brave Search API key (required)
+
+**Optional:**
+- `BRAVE_MCP_TRANSPORT`: Transport mode ("http" or "stdio", default: "stdio")
+- `BRAVE_MCP_PORT`: HTTP server port (default: 8000)
+- `BRAVE_MCP_HOST`: HTTP server host (default: "0.0.0.0")
+- `BRAVE_MCP_LOG_LEVEL`: Desired logging level("debug", "info", "notice", "warning", "error", "critical", "alert", or "emergency", default: "info")
+- `BRAVE_MCP_ENABLED_TOOLS`: When used, specifies a whitelist for supported tools
+- `BRAVE_MCP_DISABLED_TOOLS`: When used, specifies a blacklist for supported tools
+- `BRAVE_MCP_STATELESS`: HTTP stateless mode (default: "false")
+
+**Retry Configuration:**
+- `BRAVE_MCP_MAX_RETRIES`: Maximum number of retry attempts for rate-limited requests (default: 5, range: 0-10)
+- `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)
+
+### Command Line Options
+
+```bash
+node dist/index.js [options]
+
+Options:
+  --brave-api-key <string>         Brave API key (required)
+  --transport <stdio|http>         Transport type (default: stdio)
+  --port <number>                  HTTP server port (default: 8080)
+  --host <string>                  HTTP server host (default: 0.0.0.0)
+  --logging-level <string>         Desired logging level (one of _debug_, _info_, _notice_, _warning_, _error_, _critical_, _alert_, or _emergency_)
+  --enabled-tools                  Tools whitelist (only the specified tools will be enabled)
+  --disabled-tools                 Tools blacklist (included tools will be disabled)
+  --stateless <boolean>            HTTP Stateless flag
+  --retry-max-attempts <number>    Maximum retry attempts (default: 5, range: 0-10)
+  --retry-base-delay <number>      Base delay in milliseconds (default: 1000, range: 100-60000)
+  --retry-max-delay <number>       Maximum delay in milliseconds (default: 30000, range: 1000-300000)
+```
+
+## Installation
+
+### Installing via Smithery
+
+To install Brave Search automatically via [Smithery](https://smithery.ai/server/brave):
+
+```bash
+npx -y @smithery/cli install brave
+```
+
+### Usage with Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+#### Docker
+
+```json
+{
+  "mcpServers": {
+    "brave-search": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "docker.io/mcp/brave-search"],
+      "env": {
+        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+#### NPX
+
+```json
+{
+  "mcpServers": {
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "http"],
+      "env": {
+        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### Usage with VS Code
+
+For quick installation, use the one-click installation buttons below:
+
+[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=brave-search&inputs=%5B%7B%22password%22%3Atrue%2C%22id%22%3A%22brave-api-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Brave+Search+API+Key%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40brave%2Fbrave-search-mcp-server%22%2C%22--transport%22%2C%22stdio%22%5D%2C%22env%22%3A%7B%22BRAVE_API_KEY%22%3A%22%24%7Binput%3Abrave-api-key%7D%22%7D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=brave-search&inputs=%5B%7B%22password%22%3Atrue%2C%22id%22%3A%22brave-api-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Brave+Search+API+Key%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40brave%2Fbrave-search-mcp-server%22%2C%22--transport%22%2C%22stdio%22%5D%2C%22env%22%3A%7B%22BRAVE_API_KEY%22%3A%22%24%7Binput%3Abrave-api-key%7D%22%7D%7D&quality=insiders)  
+[![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Docker-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=brave-search&inputs=%5B%7B%22password%22%3Atrue%2C%22id%22%3A%22brave-api-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Brave+Search+API+Key%22%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22BRAVE_API_KEY%22%2C%22mcp%2Fbrave-search%22%5D%2C%22env%22%3A%7B%22BRAVE_API_KEY%22%3A%22%24%7Binput%3Abrave-api-key%7D%22%7D%7D) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Docker-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=brave-search&inputs=%5B%7B%22password%22%3Atrue%2C%22id%22%3A%22brave-api-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Brave+Search+API+Key%22%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22BRAVE_API_KEY%22%2C%22mcp%2Fbrave-search%22%5D%2C%22env%22%3A%7B%22BRAVE_API_KEY%22%3A%22%24%7Binput%3Abrave-api-key%7D%22%7D%7D&quality=insiders)
+
+For manual installation, add the following to your User Settings (JSON) or `.vscode/mcp.json`:
+
+#### Docker
+
+```json
+{
+  "inputs": [
+    {
+      "password": true,
+      "id": "brave-api-key",
+      "type": "promptString",
+      "description": "Brave Search API Key",
+    }
+  ],
+  "servers": {
+    "brave-search": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "mcp/brave-search"],
+      "env": {
+        "BRAVE_API_KEY": "${input:brave-api-key}"
+      }
+    }
+  }
+}
+```
+
+#### NPX
+
+```json
+{
+  "inputs": [
+    {
+      "password": true,
+      "id": "brave-api-key",
+      "type": "promptString",
+      "description": "Brave Search API Key",
+    }
+  ],
+  "servers": {
+    "brave-search-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
+      "env": {
+        "BRAVE_API_KEY": "${input:brave-api-key}"
+      }
+    }
+  }
+}
+```
+
+## Build
+
+### Docker
+
+```bash
+docker build -t mcp/brave-search:latest .
+```
+
+### Local Build
+
+```bash
+npm install
+npm run build
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 22.x or higher
+- npm
+- Brave Search API key
+
+### Setup
+
+1. Clone the repository:
+```bash
+git clone https://github.com/brave/brave-search-mcp-server.git
+cd brave-search-mcp-server
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Build the project:
+```bash
+npm run build
+```
+
+### Testing via Claude Desktop
+
+Add a reference to your local build in `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "brave-search-dev": {
+      "command": "node",
+      "args": ["C:\\GitHub\\brave-search-mcp-server\\dist\\index.js"], // Verify your path
+      "env": {
+        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### Testing via MCP Inspector
+
+1. Build and start the server:
+```bash
+npm run build
+node dist/index.js
+```
+
+2. In another terminal, start the MCP Inspector:
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+STDIO is the default mode. For HTTP mode testing, add `--transport http` to the arguments in the Inspector UI.
+
+### Testing via Smithery.AI
+
+1. Establish and acquire a smithery.ai account and API key
+2. Run `npm run install`, `npm run smithery:build`, and lastly `npm run smithery:dev` to begin testing
+
+### Available Scripts
+
+- `npm run build`: Build the TypeScript project
+- `npm run watch`: Watch for changes and rebuild
+- `npm run format`: Format code with Prettier
+- `npm run format:check`: Check code formatting
+- `npm run prepare`: Format and build (runs automatically on npm install)
+
+- `npm run inspector`: Launch an instance of MCP Inspector
+- `npm run inspector:stdio`: Launch a instance of MCP Inspector, configured for STDIO
+- `npm run smithery:build`: Build the project for smithery.ai
+- `npm run smithery:dev`: Launch the development environment for smithery.ai
+
+### Docker Compose
+
+For local development with Docker:
+
+```bash
+docker-compose up --build
+```
+
+## License
+
+This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

package/dist/BraveAPI/index.js

@@ -0,0 +1,162 @@
+import config from '../config.js';
+import { withRetry, BraveApiError } from '../utils/retry.js';
+import { extractRetryAfterMs } from './types.js';
+import { getApiKeyManager } from '../utils/apiKeyManager.js';
+const typeToPathMap = {
+    images: '/res/v1/images/search',
+    localPois: '/res/v1/local/pois',
+    localDescriptions: '/res/v1/local/descriptions',
+    news: '/res/v1/news/search',
+    videos: '/res/v1/videos/search',
+    web: '/res/v1/web/search',
+    summarizer: '/res/v1/summarizer/search',
+};
+const getDefaultRequestHeaders = () => {
+    const manager = getApiKeyManager();
+    // Use key manager if available, otherwise fallback to first key
+    const keyToUse = manager ? manager.selectBestKey() : config.braveApiKeys[0];
+    if (!keyToUse) {
+        throw new Error('No valid API key available');
+    }
+    return {
+        Accept: 'application/json',
+        'Accept-Encoding': 'gzip',
+        'X-Subscription-Token': keyToUse,
+    };
+};
+const isValidGoggleURL = (url) => {
+    try {
+        // Only allow HTTPS URLs
+        return new URL(url).protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Perform the actual HTTP request
+ * This function is separated from issueRequest to allow retry logic
+ *
+ * @param urlWithParams - Full URL with query parameters
+ * @param headers - Request headers
+ * @returns Promise resolving to the response
+ * @throws BraveApiError on HTTP errors
+ */
+async function performRequest(urlWithParams, headers) {
+    const response = await fetch(urlWithParams, { headers });
+    // Extract used key for tracking
+    const usedApiKey = headers['X-Subscription-Token'];
+    const manager = getApiKeyManager();
+    // Handle Error
+    if (!response.ok) {
+        let responseBody;
+        try {
+            responseBody = await response.json();
+        }
+        catch {
+            // If JSON parsing fails, try to get text
+            const text = await response.text();
+            responseBody = { message: text };
+        }
+        // Update key state on error
+        if (manager && usedApiKey) {
+            if (response.status === 401) {
+                manager.markKeyInvalid(usedApiKey, responseBody.message || 'Unauthorized');
+            }
+            else if (response.status === 429) {
+                const retryAfter = extractRetryAfterMs(responseBody);
+                manager.markKeyRateLimited(usedApiKey, retryAfter);
+            }
+            else {
+                // Release key for other errors
+                manager.releaseKey(usedApiKey);
+            }
+        }
+        // Extract retry-after from rate limit metadata if available
+        const retryAfter = extractRetryAfterMs(responseBody);
+        // Throw structured error for retry logic to handle
+        throw new BraveApiError(response.status, responseBody, retryAfter);
+    }
+    // Update key state from response headers on success
+    if (manager && usedApiKey) {
+        manager.updateKeyFromHeaders(usedApiKey, response.headers);
+    }
+    // Return Response
+    const responseBody = await response.json();
+    return responseBody;
+}
+async function issueRequest(endpoint, parameters, 
+// TODO (Sampson): Implement support for custom request headers (helpful for POIs, etc.)
+requestHeaders = {}) {
+    // Determine URL, and setup parameters
+    const url = new URL(`https://api.search.brave.com${typeToPathMap[endpoint]}`);
+    const queryParams = new URLSearchParams();
+    // TODO (Sampson): Move param-construction/validation to modules
+    for (const [key, value] of Object.entries(parameters)) {
+        // The 'ids' parameter is expected to appear multiple times for multiple IDs
+        if (['localPois', 'localDescriptions'].includes(endpoint)) {
+            if (key === 'ids') {
+                if (Array.isArray(value) && value.length > 0) {
+                    value.forEach((id) => queryParams.append(key, id));
+                }
+                else if (typeof value === 'string') {
+                    queryParams.set(key, value);
+                }
+                continue;
+            }
+        }
+        // Handle `result_filter` parameter
+        if (key === 'result_filter') {
+            // Handle special behavior of 'summary' parameter:
+            // Requires `result_filter` to be empty, or only contain 'summarizer'
+            // see: https://bravesoftware.slack.com/archives/C01NNFM9XMM/p1751654841090929
+            if ('summary' in parameters && parameters.summary === true) {
+                queryParams.set(key, 'summarizer');
+            }
+            else if (Array.isArray(value) && value.length > 0) {
+                queryParams.set(key, value.join(','));
+            }
+            continue;
+        }
+        // Handle `goggles` parameter(s)
+        if (key === 'goggles') {
+            if (typeof value === 'string') {
+                queryParams.set(key, value);
+            }
+            else if (Array.isArray(value)) {
+                for (const url of value.filter(isValidGoggleURL)) {
+                    queryParams.append(key, url);
+                }
+            }
+            continue;
+        }
+        if (value !== undefined) {
+            queryParams.set(key === 'query' ? 'q' : key, value.toString());
+        }
+    }
+    // Build final URL and headers
+    const urlWithParams = url.toString() + '?' + queryParams.toString();
+    const headers = { ...getDefaultRequestHeaders(), ...requestHeaders };
+    // Special case: Summarizer uses its own polling logic, don't apply retry
+    if (endpoint === 'summarizer') {
+        return performRequest(urlWithParams, headers);
+    }
+    // All other endpoints: Use retry logic with exponential backoff
+    return withRetry(() => performRequest(urlWithParams, headers), {
+        maxRetries: config.retryMaxAttempts,
+        baseDelay: config.retryBaseDelay,
+        maxDelay: config.retryMaxDelay,
+        onRetry: (attempt, error, delay) => {
+            // Additional logging can be added here if needed
+            if (error instanceof BraveApiError && error.statusCode === 429) {
+                // Log specific rate limit info if available
+                if (error.retryAfter) {
+                    console.info(`Rate limit metadata suggests ${error.retryAfter}ms delay`);
+                }
+            }
+        },
+    });
+}
+export default {
+    issueRequest,
+};

package/dist/BraveAPI/types.js

@@ -0,0 +1,46 @@
+/**
+ * Type guard to check if an error response is a rate limit error
+ * @param error - The error to check
+ * @returns True if the error is a rate limit error
+ */
+export function isRateLimitError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'type' in error &&
+        error.type === 'ErrorResponse' &&
+        'error' in error &&
+        error.error?.code === 'RATE_LIMITED');
+}
+/**
+ * Extract the suggested retry delay from a rate limit error response
+ * Uses the rate limit metadata to calculate the optimal delay
+ * @param response - The error response from the API
+ * @returns Suggested delay in milliseconds, or undefined if no metadata available
+ *
+ * @example
+ * ```typescript
+ * const response = {
+ *   error: {
+ *     meta: { rate_limit: 1, rate_current: 1.5 }
+ *   }
+ * };
+ * const delay = extractRetryAfterMs(response); // Returns 1500
+ * ```
+ */
+export function extractRetryAfterMs(response) {
+    if (!response || typeof response !== 'object') {
+        return undefined;
+    }
+    const meta = response?.error?.meta;
+    if (!meta || typeof meta !== 'object') {
+        return undefined;
+    }
+    const rateLimit = meta.rate_limit;
+    const rateCurrent = meta.rate_current;
+    if (typeof rateLimit === 'number' && typeof rateCurrent === 'number' && rateLimit > 0) {
+        // Calculate delay based on current usage rate
+        // Example: If rate_limit=1, rate_current=1.5 → 1500ms
+        return Math.ceil((rateCurrent / rateLimit) * 1000);
+    }
+    return undefined;
+}