@humbletoes/google-search 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2024 humbletoes
+
+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,339 @@
+# Google Search MCP Server
+
+A fast, reliable Google Search tool with Model Context Protocol (MCP) server integration. Bypasses anti-bot detection to provide real-time search capabilities to AI assistants.
+
+[![Star History Chart](https://api.star-history.com/svg?repos=web-agent-master/google-search&type=Date)](https://star-history.com/#web-agent-master/google-search&Date)
+
+## Features
+
+- **Fast & Reliable**: Advanced anti-bot detection bypass with intelligent caching
+- **MCP Integration**: Native support for Claude and other AI assistants  
+- **Metadata Rich**: Returns enhanced results with domain, position, snippet analysis
+- **Browser State**: Automatic state management to minimize verification prompts
+- **HTML Access**: Get raw search page HTML for debugging or analysis
+- **Open Source**: Fully open source, no API keys required
+
+## Installation
+
+```bash
+# Install from source
+git clone https://github.com/web-agent-master/google-search.git
+cd google-search
+# Install dependencies
+npm install
+# or use yarn
+yarn
+# or use pnpm
+pnpm install
+
+# Compile TypeScript code
+npm run build
+# or use yarn
+yarn build
+# or use pnpm
+pnpm build
+
+# Link package globally (required for MCP functionality)
+npm link
+# or use yarn
+yarn link
+# or use pnpm
+pnpm link
+```
+
+### Windows Environment Special Notes
+
+In the Windows environment, this tool has been specially adapted:
+
+1. Provides `.cmd` files to ensure command-line tools work properly in Windows Command Prompt and PowerShell
+2. Log files are stored in the system temporary directory, not the Unix/Linux `/tmp` directory
+3. Added Windows-specific process signal handling to ensure the server can shut down properly
+4. Uses cross-platform file path handling, supporting Windows path separators
+
+## Usage
+
+### Command Line Tool
+
+```bash
+# Use command line directly
+google-search "search keywords"
+
+# Use command line options
+google-search --limit 5 --timeout 60000 --no-headless "search keywords"
+
+
+# or use npx
+npx google-search-cli "search keywords"
+
+# Run in development mode
+pnpm dev "search keywords"
+
+# Run in debug mode (show browser interface)
+pnpm debug "search keywords"
+
+# Get raw HTML of search result page
+google-search "search keywords" --get-html
+
+# Get HTML and save to file
+google-search "search keywords" --get-html --save-html
+
+# Get HTML and save to specified file
+google-search "search keywords" --get-html --save-html --html-output "./output.html"
+```
+
+#### Command Line Options
+
+- `-l, --limit <number>`: Result count limit (default: 10)
+- `-t, --timeout <number>`: Timeout (milliseconds, default: 60000)
+- `--no-headless`: Show browser interface (for debugging)
+- `--remote-debugging-port <number>`: Enable remote debugging port (default: 9222)
+- `--state-file <path>`: Browser state file path (default: ./browser-state.json)
+- `--no-save-state`: Do not save browser state
+- `--get-html`: Get raw HTML of search result page instead of parsing results
+- `--save-html`: Save HTML to file (use with --get-html)
+- `--html-output <path>`: Specify HTML output file path (use with --get-html and --save-html)
+- `-V, --version`: Show version number
+- `-h, --help`: Show help information
+
+#### Output Example
+
+```json
+{
+  "query": "deepseek",
+  "results": [
+    {
+      "title": "DeepSeek",
+      "link": "https://www.deepseek.com/",
+      "snippet": "DeepSeek-R1 is now live and open source, rivaling OpenAI's Model o1. Available on web, app, and API. Click for details. Into ..."
+    },
+    {
+      "title": "DeepSeek",
+      "link": "https://www.deepseek.com/",
+      "snippet": "DeepSeek-R1 is now live and open source, rivaling OpenAI's Model o1. Available on web, app, and API. Click for details. Into ..."
+    },
+    {
+      "title": "deepseek-ai/DeepSeek-V3",
+      "link": "https://github.com/deepseek-ai/DeepSeek-V3",
+      "snippet": "We present DeepSeek-V3, a strong Mixture-of-Experts (MoE) language model with 671B total parameters with 37B activated for each token."
+    }
+    // more results...
+  ]
+}
+```
+
+#### HTML Output Example
+
+When using the `--get-html` option, the output will include information about the HTML content:
+
+```json
+{
+  "query": "playwright automation",
+  "url": "https://www.google.com/",
+  "originalHtmlLength": 1291733,
+  "cleanedHtmlLength": 456789,
+  "htmlPreview": "<!DOCTYPE html><html itemscope=\"\" itemtype=\"http://schema.org/SearchResultsPage\" lang=\"zh-CN\"><head><meta charset=\"UTF-8\"><meta content=\"dark light\" name=\"color-scheme\"><meta content=\"origin\" name=\"referrer\">..."
+}
+```
+
+If the `--save-html` option is also used, the output will also include the saved HTML file path:
+
+```json
+{
+  "query": "playwright automation",
+  "url": "https://www.google.com/",
+  "originalHtmlLength": 1292241,
+  "cleanedHtmlLength": 458976,
+  "savedPath": "./google-search-html/playwright_automation-2025-04-06T03-30-06-852Z.html",
+  "screenshotPath": "./google-search-html/playwright_automation-2025-04-06T03-30-06-852Z.png",
+  "htmlPreview": "<!DOCTYPE html><html itemscope=\"\" itemtype=\"http://schema.org/SearchResultsPage\" lang=\"zh-CN\">..."
+}
+```
+
+### MCP Server
+
+This project provides Model Context Protocol (MCP) server functionality, allowing AI assistants like Claude to directly use Google search capabilities. MCP is an open protocol that enables AI assistants to securely access external tools and data.
+
+```bash
+# Build project
+pnpm build
+```
+
+#### Integration with Claude Desktop
+
+1. Edit Claude Desktop configuration file
+   - Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+     - Usually located at `C:\Users\username\AppData\Roaming\Claude\claude_desktop_config.json`
+     - You can directly access by entering `%APPDATA%\Claude` in the Windows Explorer address bar
+
+2. Add server configuration and restart Claude
+
+```json
+{
+  "mcpServers": {
+    "google-search": {
+      "command": "npx",
+      "args": ["google-search-mcp"]
+    }
+  }
+}
+```
+
+For Windows environment, you can also use the following configuration scheme:
+
+1. Use cmd.exe with npx:
+
+```json
+{
+  "mcpServers": {
+    "google-search": {
+      "command": "cmd.exe",
+      "args": ["/c", "npx", "google-search-mcp"]
+    }
+  }
+}
+```
+
+2. Use node with full path (if the above method encounters issues, this is recommended):
+
+```json
+{
+  "mcpServers": {
+    "google-search": {
+      "command": "node",
+      "args": ["C:/your/path/google-search/dist/mcp-server.js"]
+    }
+  }
+}
+```
+
+Note: For the second method, you must replace `C:/your/path/google-search` with the actual full path where the google-search package is installed.
+
+After integration, you can directly use search functions in Claude, such as "search for the latest AI research".
+
+## MCP Tools
+
+The server provides two powerful tools optimized for AI assistants:
+
+### `google-search`
+**Smart web search and content fetcher.** Automatically detects if input is a URL or search query.
+
+#### Search Mode (query string)
+Returns structured results with clickable links.
+- Batch queries supported (array) for concurrent multi-topic research
+- Default 20 results (max 100) with title, URL, snippet
+- Use `condensed=true` for minimal token output
+
+#### Fetch Mode (URL input)  
+Extracts clean text from webpage.
+- Removes HTML/scripts/ads/navigation
+- Use `maxContentLength` to limit output size
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | string \| string[] | required | Search query, URL to fetch, or array for batch |
+| `limit` | number | 20 | Results per query (max: 100, search mode only) |
+| `timeout` | number | 60000/30000 | Timeout in ms |
+| `useCache` | boolean | true | Use cached results (search mode only) |
+| `condensed` | boolean | false | Minimal output: title+URL only |
+| `maxContentLength` | number | unlimited | Max chars for URL fetch content |
+
+**Examples:**
+```
+"react hooks tutorial" → searches Google
+"https://docs.python.org" → fetches page content
+["typescript generics", "rust traits"] → concurrent batch search
+```
+
+### `get_code_context`
+**Search for programming documentation, code examples, and API references.**
+
+Uses multiple sources including Context7 API for high-quality library documentation.
+Optimized for finding up-to-date context for:
+- Library/framework documentation
+- API reference and usage patterns
+- SDK integration guides  
+- Code snippets and best practices
+
+Returns condensed code snippets and docs from authoritative sources like GitHub, Stack Overflow, and official documentation sites.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | string | required | Programming topic, library, API, or code pattern |
+| `maxResults` | number | 5 | Sources to search (max: 10) |
+| `maxTokens` | number | 3000 | Approximate max output tokens |
+
+**Examples:**
+```
+"React useState hook examples"
+"Python pandas dataframe filtering"
+"Next.js app router server actions"
+"Express middleware authentication"
+"Prisma ORM schema definition"
+```
+
+**Supported Libraries (auto-detected for enhanced search):**
+React, Next.js, Vue, Angular, Svelte, Express, Django, Flask, FastAPI, Rust/Tokio, Go, TypeScript, Tailwind, Prisma, MongoDB, PostgreSQL, Redis, Docker, Kubernetes, AWS, Firebase, Supabase, Stripe, OpenAI, LangChain, and many more.
+
+**Features:**
+- Automatically targets official documentation sites
+- Integrates with Context7 for high-quality library docs
+- Prioritizes authoritative sources (GitHub, Stack Overflow, official docs)
+- Extracts code-relevant content from pages
+- Token-optimized output format
+
+## Project Structure
+
+```
+google-search/
+├── src/
+│   ├── index.ts          # CLI entry point
+│   ├── search.ts         # Core search logic with Playwright
+│   ├── mcp-server.ts     # MCP server implementation
+│   ├── cache.ts          # LRU cache for performance
+│   ├── types.ts          # TypeScript type definitions
+│   ├── browser-pool.ts   # Browser instance pooling
+│   └── browser-config.ts # Anti-bot detection configuration
+├── dist/                 # Compiled JavaScript output
+├── bin/                  # Executable wrappers
+└── test/                 # Test files
+```
+
+## Tech Stack
+
+- **TypeScript** - Type-safe development
+- **Playwright** - Browser automation
+- **MCP SDK** - Model Context Protocol implementation
+- **Zod** - Schema validation
+- **Pino** - Structured logging
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build project
+pnpm build
+
+# Run search CLI
+pnpm dev "search query"
+
+# Run MCP server
+pnpm mcp
+```
+
+## Performance
+
+- **Caching**: Intelligent LRU cache with 5-minute TTL for repeated queries
+- **Browser Pooling**: Reuses browser instances for faster subsequent searches
+- **State Management**: Persists browser state to minimize verification challenges
+
+## Notes
+
+- For educational and research purposes
+- Comply with Google's terms of service
+- Avoid excessive request frequency
+- Browser state file stored in home directory as `.google-search-browser-state.json`

package/bin/google-search

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/index.js';

package/bin/google-search-mcp

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/mcp-server.js';

package/bin/google-search-mcp.cmd

@@ -0,0 +1,2 @@
+@echo off
+node "%~dp0google-search-mcp" %*

package/bin/google-search.cmd

@@ -0,0 +1,2 @@
+@echo off
+node "%~dp0google-search" %*

package/dist/browser-config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Provides secure browser configuration arguments for anti-detection
+ */
+import { BrowserContextOptions } from "playwright";
+export interface DeviceConfig {
+    deviceName: string;
+    deviceConfig: BrowserContextOptions;
+}
+export declare class SecureBrowserConfig {
+    /**
+     * Get secure browser launch arguments
+     * @param includeInsecure - Whether to include insecure flags (should be false for production)
+     * @returns Array of browser arguments
+     */
+    static getArgs(includeInsecure?: boolean): string[];
+    /**
+     * Default browser arguments for search operations
+     * Uses secure defaults without sandbox disabling
+     */
+    static getDefaultSearchArgs(): string[];
+}
+/**
+ * Desktop device names for browser fingerprinting
+ */
+export declare const DEVICE_LIST: readonly ["Desktop Chrome", "Desktop Edge", "Desktop Firefox", "Desktop Safari"];
+/**
+ * Google domains with English language parameters
+ */
+export declare const GOOGLE_DOMAINS: readonly ["https://www.google.com?hl=en&lr=lang_en", "https://www.google.co.uk?hl=en&lr=lang_en", "https://www.google.ca?hl=en&lr=lang_en", "https://www.google.com.au?hl=en&lr=lang_en"];
+/**
+ * Get random device configuration from Playwright devices
+ * @returns Tuple of [deviceName, deviceConfig]
+ */
+export declare function getRandomDeviceConfig(): [string, BrowserContextOptions];
+/**
+ * Get random delay between min and max milliseconds
+ * @param min - Minimum delay in milliseconds
+ * @param max - Maximum delay in milliseconds
+ * @returns Random delay in milliseconds
+ */
+export declare function getRandomDelay(min: number, max: number): number;

package/dist/browser-config.js

@@ -0,0 +1,96 @@
+/**
+ * Provides secure browser configuration arguments for anti-detection
+ */
+import { devices } from "playwright";
+export class SecureBrowserConfig {
+    /**
+     * Get secure browser launch arguments
+     * @param includeInsecure - Whether to include insecure flags (should be false for production)
+     * @returns Array of browser arguments
+     */
+    static getArgs(includeInsecure = false) {
+        const args = [
+            "--disable-blink-features=AutomationControlled",
+            "--disable-features=IsolateOrigins,site-per-process",
+            "--disable-site-isolation-trials",
+            "--disable-dev-shm-usage",
+            "--disable-accelerated-2d-canvas",
+            "--no-first-run",
+            "--no-zygote",
+            "--disable-gpu",
+            "--hide-scrollbars",
+            "--mute-audio",
+            "--disable-background-networking",
+            "--disable-background-timer-throttling",
+            "--disable-backgrounding-occluded-windows",
+            "--disable-breakpad",
+            "--disable-component-extensions-with-background-pages",
+            "--disable-extensions",
+            "--disable-features=TranslateUI",
+            "--disable-ipc-flooding-protection",
+            "--disable-renderer-backgrounding",
+            "--enable-features=NetworkService,NetworkServiceInProcess",
+            "--force-color-profile=srgb",
+            "--metrics-recording-only",
+            "--allow-running-insecure-content=false",
+            "--disable-javascript-harmony-shipping",
+        ];
+        // Only add sandbox disabling if explicitly opted in via environment variable
+        // This is a security measure to prevent unauthorized sandbox disabling
+        if (process.env.GOOGLE_SEARCH_DISABLE_SANDBOX === "true") {
+            args.push("--no-sandbox");
+            args.push("--disable-setuid-sandbox");
+        }
+        // Insecure flag should NEVER be enabled in production
+        // This is only for specific development/testing scenarios
+        if (includeInsecure) {
+            // Note: --disable-web-security is intentionally NOT included
+            // as it poses significant security risks
+            console.warn("WARNING: Insecure browser flags requested. This should only be used in development.");
+        }
+        return args;
+    }
+    /**
+     * Default browser arguments for search operations
+     * Uses secure defaults without sandbox disabling
+     */
+    static getDefaultSearchArgs() {
+        return this.getArgs(false);
+    }
+}
+/**
+ * Desktop device names for browser fingerprinting
+ */
+export const DEVICE_LIST = [
+    "Desktop Chrome",
+    "Desktop Edge",
+    "Desktop Firefox",
+    "Desktop Safari",
+];
+/**
+ * Google domains with English language parameters
+ */
+export const GOOGLE_DOMAINS = [
+    "https://www.google.com?hl=en&lr=lang_en",
+    "https://www.google.co.uk?hl=en&lr=lang_en",
+    "https://www.google.ca?hl=en&lr=lang_en",
+    "https://www.google.com.au?hl=en&lr=lang_en",
+];
+/**
+ * Get random device configuration from Playwright devices
+ * @returns Tuple of [deviceName, deviceConfig]
+ */
+export function getRandomDeviceConfig() {
+    const randomDevice = DEVICE_LIST[Math.floor(Math.random() * DEVICE_LIST.length)];
+    return [randomDevice, devices[randomDevice]];
+}
+/**
+ * Get random delay between min and max milliseconds
+ * @param min - Minimum delay in milliseconds
+ * @param max - Maximum delay in milliseconds
+ * @returns Random delay in milliseconds
+ */
+export function getRandomDelay(min, max) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+//# sourceMappingURL=browser-config.js.map

package/dist/browser-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-config.js","sourceRoot":"","sources":["../src/browser-config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAyB,MAAM,YAAY,CAAC;AAO5D,MAAM,OAAO,mBAAmB;IAC9B;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,kBAA2B,KAAK;QAC7C,MAAM,IAAI,GAAG;YACX,+CAA+C;YAC/C,oDAAoD;YACpD,iCAAiC;YACjC,yBAAyB;YACzB,iCAAiC;YACjC,gBAAgB;YAChB,aAAa;YACb,eAAe;YACf,mBAAmB;YACnB,cAAc;YACd,iCAAiC;YACjC,uCAAuC;YACvC,0CAA0C;YAC1C,oBAAoB;YACpB,sDAAsD;YACtD,sBAAsB;YACtB,gCAAgC;YAChC,mCAAmC;YACnC,kCAAkC;YAClC,0DAA0D;YAC1D,4BAA4B;YAC5B,0BAA0B;YAC1B,wCAAwC;YACxC,uCAAuC;SACxC,CAAC;QAEF,6EAA6E;QAC7E,uEAAuE;QACvE,IAAI,OAAO,CAAC,GAAG,CAAC,6BAA6B,KAAK,MAAM,EAAE,CAAC;YACzD,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAC1B,IAAI,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;QACxC,CAAC;QAED,sDAAsD;QACtD,0DAA0D;QAC1D,IAAI,eAAe,EAAE,CAAC;YACpB,6DAA6D;YAC7D,yCAAyC;YACzC,OAAO,CAAC,IAAI,CACV,qFAAqF,CACtF,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,oBAAoB;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,gBAAgB;IAChB,cAAc;IACd,iBAAiB;IACjB,gBAAgB;CACR,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,yCAAyC;IACzC,2CAA2C;IAC3C,wCAAwC;IACxC,4CAA4C;CACpC,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,YAAY,GAChB,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,GAAW;IACrD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;AAC3D,CAAC"}

package/dist/browser-pool.d.ts

@@ -0,0 +1,13 @@
+import { Browser } from "playwright";
+/**
+ * Manages a pool of browser instances for efficient reuse
+ */
+export declare class BrowserPool {
+    private pool;
+    private maxSize;
+    constructor(maxSize?: number);
+    acquire(): Promise<Browser>;
+    release(browser: Browser): Promise<void>;
+    cleanup(): Promise<void>;
+}
+export declare const browserPool: BrowserPool;

package/dist/browser-pool.js

@@ -0,0 +1,37 @@
+import { chromium } from "playwright";
+import { SecureBrowserConfig } from "./browser-config.js";
+/**
+ * Manages a pool of browser instances for efficient reuse
+ */
+export class BrowserPool {
+    constructor(maxSize = 3) {
+        this.pool = [];
+        this.maxSize = maxSize;
+    }
+    async acquire() {
+        if (this.pool.length > 0) {
+            return this.pool.pop();
+        }
+        return await chromium.launch({
+            headless: true,
+            args: SecureBrowserConfig.getArgs(),
+            ignoreDefaultArgs: ["--enable-automation"],
+        });
+    }
+    async release(browser) {
+        if (this.pool.length < this.maxSize) {
+            // Reset browser state before returning to pool
+            this.pool.push(browser);
+        }
+        else {
+            await browser.close();
+        }
+    }
+    async cleanup() {
+        await Promise.all(this.pool.map(browser => browser.close().catch(() => { })));
+        this.pool = [];
+    }
+}
+// Singleton instance
+export const browserPool = new BrowserPool();
+//# sourceMappingURL=browser-pool.js.map

package/dist/browser-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-pool.js","sourceRoot":"","sources":["../src/browser-pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAW,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;GAEG;AACH,MAAM,OAAO,WAAW;IAItB,YAAY,UAAkB,CAAC;QAHvB,SAAI,GAAc,EAAE,CAAC;QAI3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAG,CAAC;QAC1B,CAAC;QACD,OAAO,MAAM,QAAQ,CAAC,MAAM,CAAC;YAC3B,QAAQ,EAAE,IAAI;YACd,IAAI,EAAE,mBAAmB,CAAC,OAAO,EAAE;YACnC,iBAAiB,EAAE,CAAC,qBAAqB,CAAC;SAC3C,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAgB;QAC5B,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YACpC,+CAA+C;YAC/C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7E,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;IACjB,CAAC;CACF;AAED,qBAAqB;AACrB,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC"}

package/dist/cache.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Simple LRU cache implementation for search results
+ * Reduces redundant searches and improves performance
+ */
+import { SearchResponse } from "./types.js";
+export declare class SearchCache {
+    private cache;
+    private maxSize;
+    private ttl;
+    private totalHits;
+    private totalMisses;
+    constructor(maxSize?: number, ttl?: number);
+    /**
+     * Generate cache key from query and options
+     */
+    private generateKey;
+    /**
+      * Get cached result if valid
+      */
+    get(query: string, limit?: number, ttl?: number): SearchResponse | null;
+    /**
+      * Store result in cache
+      */
+    set(query: string, data: SearchResponse, limit?: number, ttl?: number): void;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Remove expired entries
+     */
+    cleanup(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        ttl: number;
+        hits: number;
+        misses: number;
+        entries: Array<{
+            key: string;
+            age: number;
+            hits: number;
+        }>;
+    };
+}