litescrape-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Litescrape
+
+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,147 @@
+# Litescrape MCP Server
+
+Google Search, Bing, DuckDuckGo and Google Maps results for any MCP client, free and without an API key. Add a key for Google AI Mode, Google AI Overview and Google Shopping, and to lift every limit.
+
+Results come straight from the search engines' own pages as structured JSON, through the [Litescrape API](https://litescrape.com). Links are real destinations, never redirects, and nothing is cached: every call runs fresh.
+
+## Quick start
+
+No account, no key, one line.
+
+**Claude Code**
+
+```
+claude mcp add litescrape -- npx -y litescrape-mcp-server
+```
+
+**Cursor, Windsurf, Claude Desktop, Codex, Gemini CLI and most other clients** (`mcp.json`, `claude_desktop_config.json`, or the client's MCP settings)
+
+```json
+{
+	"mcpServers": {
+		"litescrape": {
+			"command": "npx",
+			"args": ["-y", "litescrape-mcp-server"]
+		}
+	}
+}
+```
+
+**VS Code**
+
+```
+code --add-mcp '{"name":"litescrape","command":"npx","args":["-y","litescrape-mcp-server"]}'
+```
+
+**Codex CLI**
+
+```
+codex mcp add litescrape -- npx -y litescrape-mcp-server
+```
+
+**Gemini CLI**
+
+```
+gemini mcp add litescrape npx -y litescrape-mcp-server
+```
+
+Requires Node.js 20 or newer.
+
+## What you get without a key
+
+| Tool                | Returns                                                                                                                                  | Free calls per network per UTC day |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| `search`            | Google organic results in fast mode (title, link, snippet); shares the `google_search` allowance                                         | 25                                 |
+| `google_search`     | The full Google results page: organic results, Knowledge Graph, AI Overview, ads, related questions and every other module Google served | 25                                 |
+| `bing_search`       | Bing organic results, answer boxes, Knowledge Graph, Copilot answer and more                                                             | 50                                 |
+| `duckduckgo_search` | DuckDuckGo organic results with region, safety and date filters                                                                          | 50                                 |
+| `google_maps`       | Google Maps places (name, address, rating, hours, phone, website, coordinates) or one exact place                                        | 50                                 |
+
+One call runs at a time per network, and failed calls never count. When a limit is reached, the tool result says so and tells the model exactly how to add a key, so the agent can relay it to you.
+
+## Add an API key
+
+A key unlocks `google_ai_mode`, `google_ai_overview` and `google_shopping`, removes the daily limits and allows concurrent calls. Get one at [litescrape.com](https://litescrape.com), then set `LITESCRAPE_API_KEY` in the server's environment:
+
+```json
+{
+	"mcpServers": {
+		"litescrape": {
+			"command": "npx",
+			"args": ["-y", "litescrape-mcp-server"],
+			"env": {
+				"LITESCRAPE_API_KEY": "ls_live_..."
+			}
+		}
+	}
+}
+```
+
+With Claude Code: `claude mcp add litescrape -e LITESCRAPE_API_KEY=ls_live_... -- npx -y litescrape-mcp-server`
+
+## Tools
+
+| Tool                 | Key needed | What it does                                                                                                                                                                                                                                                           |
+| -------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `search`             | No         | Web search through Google, organic results only. Parameters: `q`, `gl`, `hl`, `location`, `num`, `start`                                                                                                                                                               |
+| `google_search`      | No         | Full Google Search page. Localization (`gl`, `hl`, `location`, `uule`, `lat`/`lon`), verticals (`tbm`: news, videos, local, shopping, patents), date filters (`tbs`, `as_qdr`), site restriction (`as_sitesearch`), pagination (`start`, `num`), `device`, `fast_mode` |
+| `bing_search`        | No         | Bing web search with `mkt`/`cc`, `location`, `lat`/`lon`, `first`, `safeSearch`, `filters`, `device`                                                                                                                                                                   |
+| `duckduckgo_search`  | No         | DuckDuckGo web search with `kl`, `safe`, `df`, `start`, `m`                                                                                                                                                                                                            |
+| `google_maps`        | No         | Places by query inside a viewport (`ll`, `location`, `lat`/`lon` with `z` or `m`) with price, rating and opening-hours filters, or one exact place by `place_id`, `data_cid` or `data`                                                                                 |
+| `google_ai_overview` | Yes        | Only the AI Overview for a Google search, or `null` when Google shows none                                                                                                                                                                                             |
+| `google_ai_mode`     | Yes        | Google AI Mode's generated answer with its cited sources; `continuable` returns a follow-up token, `image_url` adds a picture to the question                                                                                                                          |
+| `google_shopping`    | Yes        | The Google Shopping product grid, category blocks, sponsored listings and refinement chips; price, sale, shipping and small-business refinements, `sort_by`, pagination                                                                                                |
+
+Parameter names and accepted values follow the [Litescrape API reference](https://litescrape.com/docs).
+
+Every tool accepts `result_groups`, a list of top-level groups to keep (for example `["organic_results", "knowledge_graph"]`) so the model's context stays small. `search_metadata` is always included.
+
+## Results
+
+A tool result is one text block: a one-line summary, a blank line, then the API's JSON response unchanged.
+
+```
+Google Search for "espresso machine": 10 organic results; also knowledge_graph, related_questions, ai_overview. Free allowance: 24 of 25 google_search calls left today (no API key set).
+
+{"search_metadata":{...},"search_parameters":{...},"organic_results":[...],...}
+```
+
+The same JSON is also returned as `structuredContent` for clients that read it.
+
+## Limits and errors
+
+| What happened                            | Tool result                                                                                                                                  |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Daily allowance for that tool is used up | Error text naming the tool and the limit, when it resets (00:00 UTC), and how to add a key                                                   |
+| A keyless call is already in flight      | The server waits for the API's `Retry-After` (a few seconds) and retries up to twice before reporting the limit                              |
+| A key-only tool was called without a key | Error text naming the tool and the free alternatives, and how to add a key; no request is made                                               |
+| The upstream page could not be fetched   | Error text with the API's `error_code`, HTTP status and `request_id`; retryable failures are retried twice, and failed calls are not charged |
+| Invalid arguments                        | Rejected by the tool schema before any request                                                                                               |
+
+Requests time out after 120 seconds by default (the API's own deadline is 90 seconds). AI Mode is the slowest tool.
+
+## Configuration
+
+| Environment variable    | Default                      | Meaning                                            |
+| ----------------------- | ---------------------------- | -------------------------------------------------- |
+| `LITESCRAPE_API_KEY`    | unset                        | Bearer key; unset means the free keyless allowance |
+| `LITESCRAPE_API_URL`    | `https://api.litescrape.com` | API origin, for self-hosted or staging deployments |
+| `LITESCRAPE_TIMEOUT_MS` | `120000`                     | Per-request timeout in milliseconds                |
+
+Every request identifies itself with `X-Litescrape-Client: mcp/<version>` and a `litescrape-mcp-server/<version>` user agent. The server writes protocol messages to stdout and its logs to stderr.
+
+## Development
+
+```
+npm install
+npm run lint       # prettier + tsc
+npm test           # vitest, including a real stdio round trip
+npm run build      # tsc -> dist/
+npm run inspector  # MCP Inspector against dist/index.js
+```
+
+`npm run dev` runs the server from source with tsx. Releases are tagged with the package version (for example `0.1.0`); the publish workflow builds and publishes to npm with provenance.
+
+## License
+
+[MIT](LICENSE)

package/dist/client.d.ts

@@ -0,0 +1,46 @@
+export declare const DEFAULT_API_URL = "https://api.litescrape.com";
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+export declare const MAX_RETRIES = 2;
+export type Params = Record<string, string | number | boolean | undefined>;
+export type Payload = Record<string, unknown>;
+export interface KeylessAllowance {
+    limit: number;
+    remaining: number;
+}
+export interface ApiResult {
+    payload: Payload;
+    requestId?: string;
+    /** Present when the call was served from the keyless allowance. */
+    keyless?: KeylessAllowance;
+}
+export declare class LitescrapeError extends Error {
+    readonly status: number;
+    readonly errorCode: string;
+    readonly requestId: string | undefined;
+    readonly retryable: boolean;
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(message: string, status: number, errorCode: string, requestId: string | undefined, retryable: boolean, retryAfterSeconds?: number | undefined);
+}
+export interface ClientOptions {
+    apiKey?: string;
+    apiUrl?: string;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class LitescrapeClient {
+    readonly apiUrl: string;
+    readonly timeoutMs: number;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly sleep;
+    constructor(options?: ClientOptions);
+    static fromEnv(env: NodeJS.ProcessEnv): LitescrapeClient;
+    get keyed(): boolean;
+    get userAgent(): string;
+    url(path: string, params: Params): string;
+    headers(): Record<string, string>;
+    get(path: string, params: Params): Promise<ApiResult>;
+    private once;
+}
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/client.js

@@ -0,0 +1,146 @@
+import { PACKAGE_NAME, VERSION } from './version.js';
+export const DEFAULT_API_URL = 'https://api.litescrape.com';
+export const DEFAULT_TIMEOUT_MS = 120_000;
+export const MAX_RETRIES = 2;
+const MAX_RETRY_WAIT_MS = 10_000;
+export class LitescrapeError extends Error {
+    status;
+    errorCode;
+    requestId;
+    retryable;
+    retryAfterSeconds;
+    constructor(message, status, errorCode, requestId, retryable, retryAfterSeconds) {
+        super(message);
+        this.status = status;
+        this.errorCode = errorCode;
+        this.requestId = requestId;
+        this.retryable = retryable;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'LitescrapeError';
+    }
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function positiveInteger(value) {
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+export class LitescrapeClient {
+    apiUrl;
+    timeoutMs;
+    apiKey;
+    fetchImpl;
+    sleep;
+    constructor(options = {}) {
+        this.apiKey = (options.apiKey ?? '').trim();
+        this.apiUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, '');
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        this.sleep = options.sleep ?? defaultSleep;
+    }
+    static fromEnv(env) {
+        return new LitescrapeClient({
+            apiKey: env.LITESCRAPE_API_KEY,
+            apiUrl: env.LITESCRAPE_API_URL?.trim() || undefined,
+            timeoutMs: positiveInteger(env.LITESCRAPE_TIMEOUT_MS),
+        });
+    }
+    get keyed() {
+        return this.apiKey.length > 0;
+    }
+    get userAgent() {
+        return `${PACKAGE_NAME}/${VERSION} (node ${process.versions.node}; ${process.platform})`;
+    }
+    url(path, params) {
+        const query = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (value === undefined)
+                continue;
+            query.set(key, typeof value === 'boolean' ? String(value) : String(value));
+        }
+        const encoded = query.toString();
+        return `${this.apiUrl}${path}${encoded ? `?${encoded}` : ''}`;
+    }
+    headers() {
+        const headers = {
+            Accept: 'application/json',
+            'User-Agent': this.userAgent,
+            'X-Litescrape-Client': `mcp/${VERSION}`,
+        };
+        if (this.keyed)
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        return headers;
+    }
+    async get(path, params) {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                return await this.once(path, params);
+            }
+            catch (error) {
+                if (!(error instanceof LitescrapeError) || !error.retryable || attempt >= MAX_RETRIES) {
+                    throw error;
+                }
+                const backoff = 1_000 * 2 ** attempt;
+                const wait = error.retryAfterSeconds ? error.retryAfterSeconds * 1_000 : backoff;
+                await this.sleep(Math.min(wait, MAX_RETRY_WAIT_MS));
+            }
+        }
+    }
+    async once(path, params) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await this.fetchImpl(this.url(path, params), {
+                method: 'GET',
+                headers: this.headers(),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (controller.signal.aborted) {
+                throw new LitescrapeError(`The request did not complete within ${this.timeoutMs / 1000} seconds.`, 0, 'timeout', undefined, true);
+            }
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new LitescrapeError(`Could not reach ${this.apiUrl}: ${reason}`, 0, 'network_error', undefined, true);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        const body = await response.text();
+        let parsed = null;
+        try {
+            parsed = body ? JSON.parse(body) : null;
+        }
+        catch {
+            parsed = null;
+        }
+        const payload = isRecord(parsed) ? parsed : null;
+        if (!response.ok) {
+            const message = typeof payload?.error === 'string' && payload.error
+                ? payload.error
+                : `Litescrape returned HTTP ${response.status}.`;
+            const errorCode = typeof payload?.error_code === 'string' && payload.error_code
+                ? payload.error_code
+                : `http_${response.status}`;
+            const retryable = typeof payload?.retryable === 'boolean'
+                ? payload.retryable
+                : [429, 502, 503, 504].includes(response.status);
+            const retryAfter = positiveInteger(response.headers.get('retry-after') ?? undefined);
+            throw new LitescrapeError(message, response.status, errorCode, typeof payload?.request_id === 'string' ? payload.request_id : requestId, retryable, retryAfter);
+        }
+        if (payload === null) {
+            throw new LitescrapeError('Litescrape returned a response that is not a JSON object.', response.status, 'invalid_response', requestId, false);
+        }
+        const limit = positiveInteger(response.headers.get('x-litescrape-keyless-limit') ?? undefined);
+        const remainingHeader = response.headers.get('x-litescrape-keyless-remaining');
+        const remaining = remainingHeader === null ? undefined : Number(remainingHeader);
+        const keyless = limit !== undefined && remaining !== undefined && Number.isInteger(remaining)
+            ? { limit, remaining }
+            : undefined;
+        return { payload, requestId, keyless };
+    }
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { LitescrapeClient } from './client.js';
+import { createServer } from './server.js';
+import { PACKAGE_NAME, VERSION } from './version.js';
+async function main() {
+    const client = LitescrapeClient.fromEnv(process.env);
+    const server = createServer({ client });
+    await server.connect(new StdioServerTransport());
+    // stdout carries the protocol; every log line goes to stderr.
+    console.error(`${PACKAGE_NAME} ${VERSION} ready (${client.keyed ? 'API key' : 'keyless'} mode, ${client.apiUrl})`);
+}
+main().catch((error) => {
+    console.error(`${PACKAGE_NAME} failed to start:`, error);
+    process.exit(1);
+});

package/dist/messages.d.ts

@@ -0,0 +1,5 @@
+export declare const KEY_URL = "https://litescrape.com";
+export declare const ACCOUNT_FIX: string;
+export declare const KEYLESS_TOOLS: string[];
+export declare function keyRequiredMessage(tool: string): string;
+export declare function instructions(keyed: boolean): string;

package/dist/messages.js

@@ -0,0 +1,31 @@
+export const KEY_URL = 'https://litescrape.com';
+// MCP hosts forward a tool error's text to the model, not structured fields,
+// so the recovery steps live in the sentence itself.
+export const ACCOUNT_FIX = `Fix: Get a free API key at ${KEY_URL}, set LITESCRAPE_API_KEY in the MCP server's ` +
+    'environment, then start a new session.';
+export const KEYLESS_TOOLS = ['google_search', 'bing_search', 'google_maps', 'duckduckgo_search'];
+export function keyRequiredMessage(tool) {
+    return (`${tool} needs a Litescrape API key. Without one this server offers ` +
+        `${KEYLESS_TOOLS.join(', ')} and search for free.\n\n${ACCOUNT_FIX}`);
+}
+export function instructions(keyed) {
+    const shared = 'Every tool returns the Litescrape API response as JSON, unchanged, after a one-line ' +
+        'summary. Pass result_groups to keep only the top-level groups you need (search_metadata ' +
+        'is always kept). Results come straight from Google, Bing, DuckDuckGo or Google Maps; ' +
+        'links are real destinations, never redirects. When a call reports a limit, relay its ' +
+        '"Fix:" line to the user.';
+    if (keyed) {
+        return ('This session is authenticated with a Litescrape API key: every tool is available and ' +
+            'each successful call is billed to that key. search is google_search in fast mode ' +
+            '(organic results only). google_ai_mode generates an answer per request and is the ' +
+            'slowest tool. ' +
+            shared);
+    }
+    return ('This session has no Litescrape API key. google_search (25 calls), bing_search (50), ' +
+        'google_maps (50) and duckduckgo_search (50) are free per network per UTC day, one call ' +
+        'at a time; failed calls do not count. search is google_search in fast mode (organic ' +
+        'results only) and shares its allowance. google_ai_mode, google_ai_overview and ' +
+        'google_shopping need an API key, which also lifts every limit: get one at ' +
+        `${KEY_URL} and set LITESCRAPE_API_KEY in this server's environment. ` +
+        shared);
+}

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { LitescrapeClient, LitescrapeError, type KeylessAllowance, type Params, type Payload } from './client.js';
+import { type Surface } from './surfaces.js';
+export { LitescrapeClient, LitescrapeError } from './client.js';
+export { SURFACES } from './surfaces.js';
+export declare function toParams(args: Record<string, unknown>): Params;
+export declare function selectGroups(payload: Payload, groups: unknown): Payload;
+export declare function allowanceLine(surface: Surface, allowance: KeylessAllowance): string;
+export declare function formatError(error: LitescrapeError): string;
+export interface ServerOptions {
+    client: LitescrapeClient;
+}
+export declare function createServer({ client }: ServerOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,86 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { LitescrapeError, } from './client.js';
+import { instructions, keyRequiredMessage } from './messages.js';
+import { SURFACES } from './surfaces.js';
+import { PACKAGE_NAME, VERSION } from './version.js';
+export { LitescrapeClient, LitescrapeError } from './client.js';
+export { SURFACES } from './surfaces.js';
+// Error codes whose message already carries the "Fix:" line for the caller.
+const SELF_EXPLANATORY = new Set([
+    'mcp_keyless_daily_limit',
+    'mcp_keyless_concurrency_limit',
+    'mcp_keyless_capacity_limit',
+    'mcp_api_key_required',
+    'mcp_keyless_network_unknown',
+]);
+export function toParams(args) {
+    const params = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (value === undefined || value === null || key === 'result_groups')
+            continue;
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            params[key] = value;
+        }
+    }
+    return params;
+}
+export function selectGroups(payload, groups) {
+    if (!Array.isArray(groups) || groups.length === 0)
+        return payload;
+    const wanted = new Set(groups.filter((group) => typeof group === 'string'));
+    wanted.add('search_metadata');
+    const selected = {};
+    for (const [key, value] of Object.entries(payload)) {
+        if (wanted.has(key))
+            selected[key] = value;
+    }
+    return selected;
+}
+export function allowanceLine(surface, allowance) {
+    return `Free allowance: ${allowance.remaining} of ${allowance.limit} ${surface.name} calls left today (no API key set).`;
+}
+export function formatError(error) {
+    if (SELF_EXPLANATORY.has(error.errorCode))
+        return error.message;
+    const request = error.requestId ? `, request ${error.requestId}` : '';
+    const retry = error.retryable ? ' The call was not charged; retrying may succeed.' : '';
+    return `Litescrape ${error.errorCode} (HTTP ${error.status}${request}): ${error.message}${retry}`;
+}
+function textResult(text, structured, isError = false) {
+    const result = { content: [{ type: 'text', text }] };
+    if (structured !== undefined)
+        result.structuredContent = structured;
+    if (isError)
+        result.isError = true;
+    return result;
+}
+export function createServer({ client }) {
+    const server = new McpServer({ name: PACKAGE_NAME, version: VERSION }, { instructions: instructions(client.keyed), capabilities: { tools: {} } });
+    for (const surface of SURFACES) {
+        server.registerTool(surface.name, {
+            title: surface.title,
+            description: surface.description,
+            inputSchema: surface.inputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: true },
+        }, async (args) => {
+            if (!client.keyed && !surface.keyless) {
+                return textResult(keyRequiredMessage(surface.name), undefined, true);
+            }
+            const params = { ...toParams(args), ...surface.defaults };
+            try {
+                const { payload, keyless } = await client.get(surface.path, params);
+                const selected = selectGroups(payload, args.result_groups);
+                const summary = keyless
+                    ? `${surface.summarize(payload, args)} ${allowanceLine(surface, keyless)}`
+                    : surface.summarize(payload, args);
+                return textResult(`${summary}\n\n${JSON.stringify(selected)}`, selected);
+            }
+            catch (error) {
+                if (error instanceof LitescrapeError)
+                    return textResult(formatError(error), undefined, true);
+                throw error;
+            }
+        });
+    }
+    return server;
+}

package/dist/surfaces.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import { type Params, type Payload } from './client.js';
+export interface Surface {
+    name: string;
+    title: string;
+    description: string;
+    path: string;
+    /** Served without an API key from the per-network daily allowance. */
+    keyless: boolean;
+    inputSchema: z.ZodRawShape;
+    /** Fixed query parameters the caller cannot override. */
+    defaults?: Params;
+    summarize: (payload: Payload, args: Record<string, unknown>) => string;
+}
+export declare const SURFACES: Surface[];
+export declare function findSurface(name: string): Surface | undefined;

package/dist/surfaces.js

@@ -0,0 +1,389 @@
+import { z } from 'zod';
+import { isRecord } from './client.js';
+const device = z
+    .enum(['desktop', 'tablet', 'mobile'])
+    .optional()
+    .describe('Layout to request; default desktop');
+const gl = z
+    .string()
+    .length(2)
+    .optional()
+    .describe('Two-letter country for localization, e.g. "us"');
+const hl = z
+    .string()
+    .min(2)
+    .max(10)
+    .optional()
+    .describe('Language code such as "en" or "en-GB"; default en');
+const googleDomain = z
+    .string()
+    .optional()
+    .describe('Google domain such as google.co.uk; default google.com');
+const location = z
+    .string()
+    .max(512)
+    .optional()
+    .describe('Named search origin such as "Austin, Texas"; conflicts with uule and lat/lon');
+const uule = z
+    .string()
+    .max(2048)
+    .optional()
+    .describe('Pre-encoded Google location token; conflicts with location');
+const lat = z.number().min(-90).max(90).optional().describe('Latitude; supply together with lon');
+const lon = z
+    .number()
+    .min(-180)
+    .max(180)
+    .optional()
+    .describe('Longitude; supply together with lat');
+const resultGroups = z
+    .array(z.string().min(1))
+    .optional()
+    .describe('Return only these top-level result groups, e.g. ["organic_results", "knowledge_graph"]; ' +
+    'omit for the complete response. search_metadata is always kept');
+const googleSearchBase = {
+    q: z
+        .string()
+        .min(1)
+        .max(2048)
+        .optional()
+        .describe('Search query; required unless ludocid or kgmid is supplied'),
+    ludocid: z.string().optional().describe('Google CID of a local entity, for a targeted lookup'),
+    kgmid: z.string().optional().describe('Knowledge Graph machine ID such as /m/0k8z'),
+    location,
+    uule,
+    lat,
+    lon,
+    radius: z
+        .number()
+        .positive()
+        .optional()
+        .describe('Radius in meters around the location or coordinates'),
+    google_domain: googleDomain,
+    gl,
+    hl,
+    cr: z.string().optional().describe('Country restrict such as countryUS|countryCA'),
+    lr: z.string().optional().describe('Language restrict such as lang_en|lang_fr'),
+    tbs: z
+        .string()
+        .max(4096)
+        .optional()
+        .describe('Google search-filter string, e.g. qdr:w for the past week'),
+    tbm: z
+        .enum(['lcl', 'vid', 'nws', 'shop', 'pts'])
+        .optional()
+        .describe('Vertical: lcl local, vid videos, nws news, shop shopping, pts patents'),
+    safe: z.enum(['active', 'off']).optional().describe('SafeSearch'),
+    nfpr: z.enum(['0', '1']).optional().describe('1 disables spelling auto-correction'),
+    filter: z.enum(['0', '1']).optional().describe('0 disables duplicate-content filtering'),
+    as_sitesearch: z.string().max(253).optional().describe('Restrict results to this hostname'),
+    as_qdr: z
+        .string()
+        .optional()
+        .describe('Date range: d, w, m or y with an optional count, e.g. d7 for the past week'),
+    start: z.number().int().min(0).optional().describe('Result offset for pagination'),
+    num: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe('Requested result count, 1-100; Google may return fewer'),
+    device,
+};
+function count(payload, key) {
+    const value = payload[key];
+    return Array.isArray(value) ? value.length : undefined;
+}
+function presentGroups(payload, skip) {
+    return Object.keys(payload).filter((key) => !skip.includes(key) && key !== 'search_metadata' && key !== 'search_parameters');
+}
+function quoted(args) {
+    return typeof args.q === 'string' ? ` for "${args.q}"` : '';
+}
+function summarizeSerp(engine) {
+    return (payload, args) => {
+        const organic = count(payload, 'organic_results') ?? 0;
+        const others = presentGroups(payload, ['organic_results', 'search_information', 'pagination']);
+        const also = others.length ? `; also ${others.join(', ')}` : '';
+        return `${engine}${quoted(args)}: ${organic} organic results${also}.`;
+    };
+}
+export const SURFACES = [
+    {
+        name: 'search',
+        title: 'Web search',
+        description: 'Search the web through Google and return ranked organic results (title, link, snippet) ' +
+            'as JSON. Fast mode: no Knowledge Graph, ads or AI modules; use google_search for the ' +
+            'full results page. Free without an API key (shares the google_search allowance).',
+        path: '/api/google/search',
+        keyless: true,
+        inputSchema: {
+            q: z.string().min(1).max(2048).describe('What to search for'),
+            gl,
+            hl,
+            location,
+            num: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe('Requested result count, 1-100; Google may return fewer'),
+            start: z.number().int().min(0).optional().describe('Result offset for pagination'),
+            result_groups: resultGroups,
+        },
+        defaults: { fast_mode: true },
+        summarize: summarizeSerp('Google Search (fast mode)'),
+    },
+    {
+        name: 'google_search',
+        title: 'Google Search',
+        description: 'Fetch a first-party Google Search results page as JSON: organic_results plus whichever ' +
+            'modules Google served (knowledge_graph, answer_box, ai_overview, ads, related_questions, ' +
+            'related_searches, local_results, top_stories, inline_videos and more). Supports ' +
+            'localization, verticals (news, videos, local, shopping, patents), date filters and site ' +
+            'restriction. Free without an API key: 25 calls per network per day.',
+        path: '/api/google/search',
+        keyless: true,
+        inputSchema: {
+            ...googleSearchBase,
+            fast_mode: z
+                .boolean()
+                .optional()
+                .describe('true returns only organic_results (faster and smaller); skips AI Overview, ' +
+                'Knowledge Graph, ads and every other module'),
+            result_groups: resultGroups,
+        },
+        summarize: summarizeSerp('Google Search'),
+    },
+    {
+        name: 'bing_search',
+        title: 'Bing Search',
+        description: 'Fetch a Bing web search results page as JSON: organic_results plus the modules Bing ' +
+            'served (answer_box, knowledge_graph, copilot_answer, ads, related_questions, ' +
+            'inline_videos, top_stories and more). Free without an API key: 50 calls per network ' +
+            'per day.',
+        path: '/api/bing/search',
+        keyless: true,
+        inputSchema: {
+            q: z.string().min(1).max(2048).describe('Search query; Bing operators are preserved'),
+            location: z.string().max(256).optional().describe('City-level search origin'),
+            lat,
+            lon,
+            mkt: z.string().optional().describe('Market such as en-US; conflicts with cc'),
+            cc: z.string().length(2).optional().describe('Two-letter country code; conflicts with mkt'),
+            first: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('One-based organic result offset for pagination; default 1'),
+            safeSearch: z.enum(['off', 'moderate', 'strict']).optional().describe('Default moderate'),
+            filters: z.string().max(8192).optional().describe('Native Bing display or date filters'),
+            device,
+            result_groups: resultGroups,
+        },
+        summarize: summarizeSerp('Bing'),
+    },
+    {
+        name: 'duckduckgo_search',
+        title: 'DuckDuckGo Search',
+        description: 'Fetch ranked DuckDuckGo web results (organic_results with title, link, snippet) with ' +
+            'region, safety and date controls. Free without an API key: 50 calls per network per day.',
+        path: '/api/duckduckgo/search',
+        keyless: true,
+        inputSchema: {
+            q: z.string().min(1).max(500).describe('Search query'),
+            kl: z.string().max(32).optional().describe('Region and language token such as us-en'),
+            search_assist: z.boolean().optional().describe('Default true; cannot be combined with m'),
+            safe: z
+                .enum(['1', '-1', '-2'])
+                .optional()
+                .describe('1 strict, -1 moderate (default), -2 off'),
+            df: z.string().optional().describe('Date filter: d, w, m, y, or YYYY-MM-DD..YYYY-MM-DD'),
+            start: z.number().int().min(0).max(10000).optional().describe('Result offset'),
+            m: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe('Result count 1-50; cannot be combined with search_assist'),
+            result_groups: resultGroups,
+        },
+        summarize: summarizeSerp('DuckDuckGo'),
+    },
+    {
+        name: 'google_maps',
+        title: 'Google Maps',
+        description: 'Search Google Maps for places (local_results with name, address, rating, reviews, ' +
+            'hours, phone, website, coordinates) or fetch one exact place (place_results) by ' +
+            'place_id, data_cid or data sequence. Filter by price, rating and opening hours. Free ' +
+            'without an API key: 50 calls per network per day.',
+        path: '/api/google/maps',
+        keyless: true,
+        inputSchema: {
+            q: z.string().optional().describe('Search text; required for type=search'),
+            type: z
+                .enum(['search', 'place'])
+                .optional()
+                .describe('search (default) for a query, or place for one exact place identified by ' +
+                'place_id, data_cid or data'),
+            ll: z.string().optional().describe('Viewport as @lat,lon,14z or @lat,lon,5000m'),
+            location,
+            lat,
+            lon,
+            z: z.number().min(3).max(30).optional().describe('Zoom 3-30; use with location or lat/lon'),
+            m: z.number().min(1).optional().describe('Radius in meters; use with location or lat/lon'),
+            nearby: z.boolean().optional().describe('Restrict results to places near the viewport'),
+            place_id: z.string().optional().describe('Exact place by Google place ID'),
+            data_cid: z.string().optional().describe('Exact place by decimal Google CID'),
+            data: z.string().max(8192).optional().describe('Exact place by Google Maps data sequence'),
+            start: z.number().int().min(0).optional().describe('Native Maps result offset'),
+            hl,
+            gl,
+            google_domain: googleDomain,
+            min_price: z.number().int().min(0).optional().describe('Price level lower bound'),
+            max_price: z.number().int().min(0).optional().describe('Price level upper bound'),
+            min_rating: z
+                .enum(['2.0', '2.5', '3.0', '3.5', '4.0', '4.5'])
+                .optional()
+                .describe('Minimum rating preference'),
+            open_state: z
+                .enum(['now', '24h'])
+                .optional()
+                .describe('Open now, or open 24 hours; cannot combine with open_on_day'),
+            open_on_day: z.enum(['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']).optional(),
+            open_at_hour: z
+                .number()
+                .int()
+                .min(0)
+                .max(23)
+                .optional()
+                .describe('Hour 0-23; requires open_on_day'),
+            result_groups: resultGroups,
+        },
+        summarize: (payload, args) => {
+            const place = payload.place_results;
+            if (isRecord(place)) {
+                const title = typeof place.title === 'string' ? place.title : 'one place';
+                return `Google Maps place: ${title}.`;
+            }
+            const places = count(payload, 'local_results') ?? 0;
+            return `Google Maps${quoted(args)}: ${places} places.`;
+        },
+    },
+    {
+        name: 'google_ai_overview',
+        title: 'Google AI Overview',
+        description: 'Return only the AI Overview Google generates for a search (ai_overview with ordered ' +
+            'text_blocks and cited references), or null when Google shows none. Accepts the ' +
+            'google_search parameters. Requires an API key.',
+        path: '/api/google/ai-overview',
+        keyless: false,
+        inputSchema: { ...googleSearchBase, result_groups: resultGroups },
+        summarize: (payload, args) => {
+            const overview = payload.ai_overview;
+            if (!isRecord(overview))
+                return `Google served no AI Overview${quoted(args)}.`;
+            if (isRecord(overview.error))
+                return `Google AI Overview${quoted(args)}: unavailable.`;
+            const blocks = count(overview, 'text_blocks') ?? 0;
+            const references = count(overview, 'references') ?? 0;
+            return `Google AI Overview${quoted(args)}: ${blocks} text blocks, ${references} references.`;
+        },
+    },
+    {
+        name: 'google_ai_mode',
+        title: 'Google AI Mode',
+        description: 'Ask Google AI Mode a question and return its generated answer (ordered text_blocks: ' +
+            'paragraphs, headings, lists, tables, code) with the sources it cited (references). ' +
+            'Set continuable to get a token for follow-up questions; image_url adds a picture to ' +
+            'the prompt. Slow: answers are generated per request. Requires an API key.',
+        path: '/api/google/ai-mode',
+        keyless: false,
+        inputSchema: {
+            q: z.string().min(1).max(2048).describe('The question to ask'),
+            location,
+            uule,
+            google_domain: googleDomain,
+            gl,
+            hl,
+            device,
+            continuable: z
+                .boolean()
+                .optional()
+                .describe('Return a subsequent_request_token so the conversation can continue'),
+            subsequent_request_token: z
+                .string()
+                .optional()
+                .describe('Token from a previous continuable answer; send with a new q. Expires after ' +
+                '30 minutes; cannot combine with image_url'),
+            image_url: z
+                .string()
+                .url()
+                .optional()
+                .describe('Public http(s) image to include in the prompt; cannot combine with a token'),
+            result_groups: resultGroups,
+        },
+        summarize: (payload, args) => {
+            const blocks = count(payload, 'text_blocks') ?? 0;
+            const references = count(payload, 'references') ?? 0;
+            const token = typeof payload.subsequent_request_token === 'string' ? '; follow-up token included' : '';
+            return `Google AI Mode${quoted(args)}: ${blocks} text blocks, ${references} references${token}.`;
+        },
+    },
+    {
+        name: 'google_shopping',
+        title: 'Google Shopping',
+        description: 'Search Google Shopping and return the product grid (shopping_results with title, ' +
+            'price, source, rating, thumbnail), category blocks, sponsored listings and the ' +
+            'refinement chips Google renders (filters). Price bounds, sale, shipping and small ' +
+            'business refinements are mutually exclusive; sort_by combines with one of them. ' +
+            'Requires an API key.',
+        path: '/api/google/shopping',
+        keyless: false,
+        inputSchema: {
+            q: z
+                .string()
+                .min(1)
+                .max(2048)
+                .optional()
+                .describe('Product query; required unless shoprs is supplied'),
+            location,
+            uule,
+            google_domain: googleDomain,
+            gl,
+            hl,
+            shoprs: z
+                .string()
+                .max(4096)
+                .optional()
+                .describe("Refinement token from a previous response's filters"),
+            min_price: z.number().min(0).optional().describe('Lower price bound'),
+            max_price: z.number().min(0).optional().describe('Upper price bound'),
+            sort_by: z
+                .enum(['1', '2', '3', '4'])
+                .optional()
+                .describe('1 price low to high, 2 price high to low, 3 rating, 4 relevance'),
+            free_shipping: z.boolean().optional(),
+            on_sale: z.boolean().optional(),
+            small_business: z.boolean().optional(),
+            start: z.number().int().min(0).max(1000).optional().describe('Result offset'),
+            num: z.number().int().min(1).max(100).optional().describe('Product count, 1-100'),
+            device,
+            result_groups: resultGroups,
+        },
+        summarize: (payload, args) => {
+            const products = count(payload, 'shopping_results') ?? 0;
+            const categories = count(payload, 'categorized_shopping_results') ?? 0;
+            const sponsored = count(payload, 'inline_shopping_results') ?? 0;
+            return (`Google Shopping${quoted(args)}: ${products} products, ${categories} category blocks, ` +
+                `${sponsored} sponsored listings.`);
+        },
+    },
+];
+export function findSurface(name) {
+    return SURFACES.find((surface) => surface.name === name);
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const PACKAGE_NAME: string;
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from 'node:module';
+const pkg = createRequire(import.meta.url)('../package.json');
+export const PACKAGE_NAME = pkg.name;
+export const VERSION = pkg.version;

package/package.json

@@ -0,0 +1,75 @@
+{
+	"name": "litescrape-mcp-server",
+	"version": "0.1.0",
+	"description": "MCP server for the Litescrape API: Google Search, Bing, DuckDuckGo and Google Maps free without an API key, plus Google AI Mode, AI Overview and Shopping with one",
+	"license": "MIT",
+	"homepage": "https://litescrape.com",
+	"mcpName": "com.litescrape/litescrape-mcp-server",
+	"type": "module",
+	"bin": {
+		"litescrape-mcp-server": "dist/index.js"
+	},
+	"main": "dist/server.js",
+	"types": "dist/server.d.ts",
+	"files": [
+		"dist",
+		"server.json"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"keywords": [
+		"mcp",
+		"mcp-server",
+		"model context protocol",
+		"litescrape",
+		"serp api",
+		"google search",
+		"google maps",
+		"bing search",
+		"duckduckgo",
+		"google ai mode",
+		"google ai overview",
+		"google shopping",
+		"web search",
+		"claude",
+		"cursor"
+	],
+	"author": {
+		"name": "Litescraper",
+		"email": "support@litescrape.com"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/litescrape/litescrape-mcp-server.git"
+	},
+	"bugs": {
+		"url": "https://github.com/litescrape/litescrape-mcp-server/issues"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run",
+		"format": "prettier --write .",
+		"format:check": "prettier --check .",
+		"lint": "npm run format:check && npm run typecheck",
+		"dev": "tsx src/index.ts",
+		"inspector": "npx @modelcontextprotocol/inspector node dist/index.js",
+		"prepublishOnly": "npm run lint && npm run test && npm run build"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.30.0",
+		"zod": "^3.25.76"
+	},
+	"devDependencies": {
+		"@types/node": "^24.0.0",
+		"prettier": "3.8.3",
+		"tsx": "^4.23.13",
+		"typescript": "^5.9.3",
+		"vitest": "^4.1.5"
+	}
+}

package/server.json

@@ -0,0 +1,21 @@
+{
+	"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+	"name": "com.litescrape/litescrape-mcp-server",
+	"description": "Google Search, Bing, DuckDuckGo and Google Maps results free without an API key; Google AI Mode, AI Overview and Shopping with one.",
+	"version": "0.1.0",
+	"packages": [
+		{
+			"registryType": "npm",
+			"identifier": "litescrape-mcp-server",
+			"version": "0.1.0",
+			"environmentVariables": [
+				{
+					"name": "LITESCRAPE_API_KEY",
+					"description": "Optional Litescrape API key. Without it, google_search, bing_search, google_maps and duckduckgo_search work from a free daily allowance; with it every tool is available.",
+					"isRequired": false,
+					"isSecret": true
+				}
+			]
+		}
+	]
+}