litescrape-mcp-server 0.1.1 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+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, Google Shopping and Google Reviews, 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.
 
@@ -47,6 +47,12 @@ gemini mcp add litescrape npx -y litescrape-mcp-server
 
 Requires Node.js 20 or newer.
 
+**Hosted, nothing to install**: clients that connect to remote servers can use `https://mcp.litescrape.com/mcp` instead. Same tools, same free allowance; send an API key as `Authorization: Bearer ls_live_...` to unlock the rest.
+
+```
+claude mcp add --transport http litescrape https://mcp.litescrape.com/mcp
+```
+
 ## What you get without a key
 
 | Tool                | Returns                                                                                                                                  | Free calls per network per UTC day |
@@ -61,7 +67,7 @@ One call runs at a time per network, and failed calls never count. When a limit
 
 ## 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:
+A key unlocks `google_ai_mode`, `google_ai_overview`, `google_shopping` and `google_reviews`, 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
 {
@@ -79,6 +85,8 @@ A key unlocks `google_ai_mode`, `google_ai_overview` and `google_shopping`, remo
 
 With Claude Code: `claude mcp add litescrape -e LITESCRAPE_API_KEY=ls_live_... -- npx -y litescrape-mcp-server`
 
+With the hosted endpoint: `claude mcp add --transport http litescrape https://mcp.litescrape.com/mcp --header "Authorization: Bearer ls_live_..."`
+
 ## Tools
 
 | Tool                 | Key needed | What it does                                                                                                                                                                                                                                                           |
@@ -91,6 +99,7 @@ With Claude Code: `claude mcp add litescrape -e LITESCRAPE_API_KEY=ls_live_... -
 | `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                                                                                                |
+| `google_reviews`     | Yes        | The Google Maps reviews of one place by `place_id` or `data_id` (from a `google_maps` result) with `place_info`; `sort_by`, `topic_id` or `query` filters, `num`, and `next_page_token` for the next page                                                              |
 
 Parameter names and accepted values follow the [Litescrape API reference](https://litescrape.com/docs).
 
@@ -128,6 +137,16 @@ Requests time out after 120 seconds by default (the API's own deadline is 90 sec
 | `LITESCRAPE_API_URL`    | `https://api.litescrape.com` | API origin, for self-hosted or staging deployments |
 | `LITESCRAPE_TIMEOUT_MS` | `120000`                     | Per-request timeout in milliseconds                |
 
+### Streamable HTTP mode
+
+`litescrape-mcp-server --http` (or `LITESCRAPE_MCP_TRANSPORT=http`) serves MCP over HTTP instead of stdio: stateless `POST /mcp`, `GET /healthz`, listening on `PORT` (default 8080) and `HOST` (default `0.0.0.0`), or `--port` and `--host`. Each request's API key comes from its `Authorization: Bearer` header or `?api_key=` query parameter, so one process serves keyed and keyless callers; `LITESCRAPE_API_KEY` is ignored in this mode. This is what runs at `https://mcp.litescrape.com/mcp`.
+
+Behind a shared address, keyless callers would all count against one allowance. `LITESCRAPE_KEYLESS_PROXY_SECRET` is the secret the Litescrape API shares with its own hosted endpoint for forwarding each caller's address, and `LITESCRAPE_EDGE_SECRET` is the value Cloudflare adds in front of that endpoint so the caller can be read from `CF-Connecting-IP`. Neither is needed for a private deployment, where the server's own address is metered.
+
+```
+docker build -t litescrape-mcp-server . && docker run -p 8080:8080 litescrape-mcp-server --http
+```
+
 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
@@ -135,7 +154,7 @@ Every request identifies itself with `X-Litescrape-Client: mcp/<version>` and a
 ```
 npm install
 npm run lint       # prettier + tsc
-npm test           # vitest, including a real stdio round trip
+npm test           # vitest, including real stdio and HTTP round trips
 npm run build      # tsc -> dist/
 npm run inspector  # MCP Inspector against dist/index.js
 ```

package/dist/client.d.ts

@@ -25,6 +25,8 @@ export interface ClientOptions {
     apiKey?: string;
     apiUrl?: string;
     timeoutMs?: number;
+    /** Extra request headers, e.g. the caller's address forwarded by the hosted endpoint. */
+    headers?: Record<string, string>;
     fetch?: typeof globalThis.fetch;
     sleep?: (ms: number) => Promise<void>;
 }
@@ -32,6 +34,7 @@ export declare class LitescrapeClient {
     readonly apiUrl: string;
     readonly timeoutMs: number;
     private readonly apiKey;
+    private readonly extraHeaders;
     private readonly fetchImpl;
     private readonly sleep;
     constructor(options?: ClientOptions);

package/dist/client.js

@@ -28,12 +28,14 @@ export class LitescrapeClient {
     apiUrl;
     timeoutMs;
     apiKey;
+    extraHeaders;
     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.extraHeaders = { ...(options.headers ?? {}) };
         this.fetchImpl = options.fetch ?? globalThis.fetch;
         this.sleep = options.sleep ?? defaultSleep;
     }
@@ -62,6 +64,7 @@ export class LitescrapeClient {
     }
     headers() {
         const headers = {
+            ...this.extraHeaders,
             Accept: 'application/json',
             'User-Agent': this.userAgent,
             'X-Litescrape-Client': `mcp/${VERSION}`,

package/dist/http.d.ts

@@ -0,0 +1,40 @@
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { LitescrapeClient, type ClientOptions } from './client.js';
+export declare const MCP_PATH = "/mcp";
+export declare const HEALTH_PATH = "/healthz";
+export declare const FORWARDED_IP_HEADER = "X-Litescrape-Keyless-Ip";
+export declare const PROXY_SECRET_HEADER = "X-Litescrape-Keyless-Secret";
+export declare const EDGE_SECRET_HEADER = "x-litescrape-edge-secret";
+export declare const EDGE_CLIENT_HEADER = "cf-connecting-ip";
+export interface HttpOptions {
+    /**
+     * Secret shared with the Litescrape API. When set, every upstream request
+     * carries the caller's address under it, so keyless metering applies to the
+     * caller rather than to this server's own address.
+     */
+    proxySecret?: string;
+    /**
+     * Secret Cloudflare adds to every request it relays. When set, the caller is
+     * read from CF-Connecting-IP on requests that carry it, and nothing is
+     * forwarded for requests that bypassed Cloudflare.
+     */
+    edgeSecret?: string;
+    apiUrl?: string;
+    timeoutMs?: number;
+    fetch?: ClientOptions['fetch'];
+    sleep?: ClientOptions['sleep'];
+    log?: (line: string) => void;
+}
+export declare function bearerToken(req: IncomingMessage): string | undefined;
+/**
+ * The caller as the ingress reports it. With an edge secret configured, only a
+ * request carrying it is known to have come through Cloudflare, and its caller
+ * is CF-Connecting-IP; a request that bypassed Cloudflare gets no caller at all.
+ * Without one, X-Forwarded-For is passed through unchanged: the API meters it
+ * only when it holds exactly one address, so a crafted multi-hop value is
+ * refused there instead of being trusted here.
+ */
+export declare function callerAddress(req: IncomingMessage, options?: Pick<HttpOptions, 'edgeSecret'>): string | undefined;
+export declare function clientForRequest(req: IncomingMessage, options: HttpOptions): LitescrapeClient;
+export declare function handleRequest(req: IncomingMessage, res: ServerResponse, options: HttpOptions): Promise<void>;
+export declare function createHttpServer(options?: HttpOptions): Server;

package/dist/http.js

@@ -0,0 +1,132 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { createServer as createNodeServer, } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { LitescrapeClient } from './client.js';
+import { createServer } from './server.js';
+import { PACKAGE_NAME, VERSION } from './version.js';
+export const MCP_PATH = '/mcp';
+export const HEALTH_PATH = '/healthz';
+// The Litescrape API reads the forwarded address only together with the
+// shared secret, and only when it holds exactly one address.
+export const FORWARDED_IP_HEADER = 'X-Litescrape-Keyless-Ip';
+export const PROXY_SECRET_HEADER = 'X-Litescrape-Keyless-Secret';
+// Behind Cloudflare the socket peer is one of its egress addresses and
+// X-Forwarded-For is a chain, so the caller is CF-Connecting-IP; a transform
+// rule on the zone adds the edge secret, which is how a request proves it came
+// through Cloudflare rather than straight to the origin with forged headers.
+export const EDGE_SECRET_HEADER = 'x-litescrape-edge-secret';
+export const EDGE_CLIENT_HEADER = 'cf-connecting-ip';
+function requestUrl(req) {
+    return new URL(req.url ?? '/', 'http://localhost');
+}
+export function bearerToken(req) {
+    const header = req.headers.authorization;
+    const match = typeof header === 'string' ? /^Bearer\s+(.+)$/i.exec(header.trim()) : null;
+    if (match?.[1])
+        return match[1].trim();
+    const fromQuery = requestUrl(req).searchParams.get('api_key')?.trim();
+    return fromQuery || undefined;
+}
+function headerValue(req, name) {
+    const raw = req.headers[name];
+    return (Array.isArray(raw) ? raw.join(', ') : raw)?.trim() ?? '';
+}
+function sameSecret(presented, expected) {
+    const digest = (value) => createHash('sha256').update(value).digest();
+    return timingSafeEqual(digest(presented), digest(expected));
+}
+/**
+ * The caller as the ingress reports it. With an edge secret configured, only a
+ * request carrying it is known to have come through Cloudflare, and its caller
+ * is CF-Connecting-IP; a request that bypassed Cloudflare gets no caller at all.
+ * Without one, X-Forwarded-For is passed through unchanged: the API meters it
+ * only when it holds exactly one address, so a crafted multi-hop value is
+ * refused there instead of being trusted here.
+ */
+export function callerAddress(req, options = {}) {
+    if (options.edgeSecret) {
+        const presented = headerValue(req, EDGE_SECRET_HEADER);
+        if (!presented || !sameSecret(presented, options.edgeSecret))
+            return undefined;
+        return headerValue(req, EDGE_CLIENT_HEADER) || undefined;
+    }
+    const forwarded = headerValue(req, 'x-forwarded-for');
+    if (forwarded)
+        return forwarded;
+    return req.socket?.remoteAddress || undefined;
+}
+export function clientForRequest(req, options) {
+    const headers = {};
+    const caller = options.proxySecret ? callerAddress(req, options) : undefined;
+    if (options.proxySecret && caller) {
+        headers[FORWARDED_IP_HEADER] = caller;
+        headers[PROXY_SECRET_HEADER] = options.proxySecret;
+    }
+    return new LitescrapeClient({
+        apiKey: bearerToken(req),
+        apiUrl: options.apiUrl,
+        timeoutMs: options.timeoutMs,
+        headers,
+        fetch: options.fetch,
+        sleep: options.sleep,
+    });
+}
+function json(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+const CORS_HEADERS = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization, Accept, Mcp-Session-Id, Mcp-Protocol-Version',
+    'Access-Control-Expose-Headers': 'Mcp-Session-Id, Mcp-Protocol-Version',
+    'Access-Control-Max-Age': '86400',
+};
+export async function handleRequest(req, res, options) {
+    for (const [name, value] of Object.entries(CORS_HEADERS))
+        res.setHeader(name, value);
+    const { pathname } = requestUrl(req);
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    if (pathname === HEALTH_PATH || (pathname === '/' && req.method === 'GET')) {
+        json(res, 200, { status: 'ok', name: PACKAGE_NAME, version: VERSION, mcp: MCP_PATH });
+        return;
+    }
+    if (pathname !== MCP_PATH) {
+        json(res, 404, { error: `Not found. The MCP endpoint is POST ${MCP_PATH}.` });
+        return;
+    }
+    if (req.method !== 'POST') {
+        res.setHeader('Allow', 'POST, OPTIONS');
+        json(res, 405, {
+            error: `This server is stateless: POST each JSON-RPC message to ${MCP_PATH}.`,
+        });
+        return;
+    }
+    // One server and transport per request: nothing is shared between callers,
+    // and the client built from this request's own credentials goes with it.
+    const server = createServer({ client: clientForRequest(req, options) });
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    res.on('close', () => {
+        void transport.close();
+        void server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res);
+}
+export function createHttpServer(options = {}) {
+    return createNodeServer((req, res) => {
+        handleRequest(req, res, options).catch((error) => {
+            options.log?.(`${req.method ?? ''} ${req.url ?? ''} failed: ${String(error)}`);
+            if (res.headersSent) {
+                res.end();
+            }
+            else {
+                json(res, 500, { error: 'Internal server error.' });
+            }
+        });
+    });
+}

package/dist/index.js

@@ -1,15 +1,51 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { LitescrapeClient } from './client.js';
+import { createHttpServer, MCP_PATH } from './http.js';
 import { createServer } from './server.js';
 import { PACKAGE_NAME, VERSION } from './version.js';
-async function main() {
+function flag(args, name) {
+    const index = args.indexOf(name);
+    return index === -1 ? undefined : (args[index + 1] ?? '');
+}
+async function stdio() {
     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})`);
 }
+function http(args) {
+    const port = Number(flag(args, '--port') ?? process.env.PORT ?? 8080);
+    const host = flag(args, '--host') ?? process.env.HOST ?? '0.0.0.0';
+    const proxySecret = process.env.LITESCRAPE_KEYLESS_PROXY_SECRET?.trim() || undefined;
+    const edgeSecret = process.env.LITESCRAPE_EDGE_SECRET?.trim() || undefined;
+    const apiUrl = process.env.LITESCRAPE_API_URL?.trim() || undefined;
+    const timeoutMs = Number(process.env.LITESCRAPE_TIMEOUT_MS) || undefined;
+    const server = createHttpServer({
+        proxySecret,
+        edgeSecret,
+        apiUrl,
+        timeoutMs,
+        log: console.error,
+    });
+    server.listen(port, host, () => {
+        const forwarding = proxySecret ? (edgeSecret ? 'on, Cloudflare edge' : 'on') : 'off';
+        console.error(`${PACKAGE_NAME} ${VERSION} listening on http://${host}:${port}${MCP_PATH} ` +
+            `(API key per request, caller forwarding ${forwarding})`);
+    });
+    const stop = () => server.close(() => process.exit(0));
+    process.on('SIGTERM', stop);
+    process.on('SIGINT', stop);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes('--http') || process.env.LITESCRAPE_MCP_TRANSPORT === 'http') {
+        http(args);
+        return;
+    }
+    await stdio();
+}
 main().catch((error) => {
     console.error(`${PACKAGE_NAME} failed to start:`, error);
     process.exit(1);

package/dist/messages.js

@@ -18,14 +18,15 @@ export function instructions(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. ' +
+            'slowest tool. google_reviews takes the place_id or data_id of a google_maps result ' +
+            'and pages with next_page_token. ' +
             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 ' +
+        'results only) and shares its allowance. google_ai_mode, google_ai_overview, ' +
+        'google_shopping and google_reviews 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/surfaces.js

@@ -383,6 +383,61 @@ export const SURFACES = [
                 `${sponsored} sponsored listings.`);
         },
     },
+    {
+        name: 'google_reviews',
+        title: 'Google Reviews',
+        description: 'Return the Google Maps reviews of one place (reviews with rating, snippet, author, ' +
+            'date, likes, owner response, guided details and dining subratings) plus place_info. ' +
+            'Identify the place by place_id or data_id from a google_maps result. Sort, filter by ' +
+            'topic or text, and follow pagination.next_page_token for more. Requires an API key.',
+        path: '/api/google/reviews',
+        keyless: false,
+        inputSchema: {
+            place_id: z
+                .string()
+                .optional()
+                .describe('Google place ID such as ChIJ...; exactly one of place_id and data_id'),
+            data_id: z
+                .string()
+                .optional()
+                .describe('Google data ID such as 0x89c2...:0x...; exactly one of place_id and data_id'),
+            hl,
+            gl,
+            sort_by: z
+                .enum(['qualityScore', 'newestFirst', 'ratingHigh', 'ratingLow'])
+                .optional()
+                .describe('Order: qualityScore (most relevant, default), newestFirst, ratingHigh, ratingLow'),
+            topic_id: z
+                .string()
+                .optional()
+                .describe('Keep reviews on one Google review topic; conflicts with query'),
+            query: z
+                .string()
+                .optional()
+                .describe('Keep reviews mentioning this text; conflicts with topic_id'),
+            num: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe('Reviews to return: 1-100 on a first unfiltered request (default 8), 1-20 with ' +
+                'topic_id, query or next_page_token (default 10)'),
+            next_page_token: z
+                .string()
+                .optional()
+                .describe('pagination.next_page_token from the previous response; keep the same place, sort and filters'),
+            result_groups: resultGroups,
+        },
+        summarize: (payload) => {
+            const reviews = count(payload, 'reviews') ?? 0;
+            const place = isRecord(payload.place_info) ? payload.place_info : {};
+            const name = typeof place.title === 'string' ? ` for ${place.title}` : '';
+            const pagination = isRecord(payload.pagination) ? payload.pagination : {};
+            const more = typeof pagination.next_page_token === 'string' ? '; more pages available' : '';
+            return `Google Reviews${name}: ${reviews} reviews${more}.`;
+        },
+    },
 ];
 export function findSurface(name) {
     return SURFACES.find((surface) => surface.name === name);

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "litescrape-mcp-server",
-	"version": "0.1.1",
-	"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",
+	"version": "0.2.1",
+	"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, Shopping and Reviews with one. Stdio or Streamable HTTP.",
 	"license": "MIT",
 	"homepage": "https://litescrape.com",
 	"mcpName": "com.litescrape/litescrape-mcp-server",
@@ -31,6 +31,7 @@
 		"google ai mode",
 		"google ai overview",
 		"google shopping",
+		"google reviews",
 		"web search",
 		"claude",
 		"cursor"

package/server.json

@@ -1,17 +1,41 @@
 {
-	"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+	"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/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.1",
+	"title": "Litescrape",
+	"description": "Google, Bing, DuckDuckGo and Google Maps search results, free without an API key.",
+	"repository": {
+		"url": "https://github.com/litescrape/litescrape-mcp-server",
+		"source": "github"
+	},
+	"websiteUrl": "https://litescrape.com",
+	"version": "0.2.1",
 	"packages": [
 		{
 			"registryType": "npm",
 			"identifier": "litescrape-mcp-server",
-			"version": "0.1.1",
+			"version": "0.2.1",
+			"transport": {
+				"type": "stdio"
+			},
 			"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.",
+					"description": "Optional Litescrape API key. Without it, search, google_search, bing_search, google_maps and duckduckgo_search work from a free daily allowance; with it google_ai_mode, google_ai_overview, google_shopping and google_reviews are available too and the limits are lifted.",
+					"isRequired": false,
+					"isSecret": true,
+					"format": "string"
+				}
+			]
+		}
+	],
+	"remotes": [
+		{
+			"type": "streamable-http",
+			"url": "https://mcp.litescrape.com/mcp",
+			"headers": [
+				{
+					"name": "Authorization",
+					"description": "Optional: Bearer <Litescrape API key>. Without it the same free daily allowance applies.",
 					"isRequired": false,
 					"isSecret": true
 				}