scrapeless-mcp-server 0.3.0 → 0.4.0

package/build/tools/browser/browser.js

@@ -0,0 +1,444 @@
+import { z } from "zod";
+import { defineTool, wrapMcpBrowserResponse, snapshot } from "../utils.js";
+export const browserCreate = defineTool({
+    name: "browser_create",
+    description: "Create or reuse a cloud browser session using Scrapeless. Updates the active session.",
+    inputSchema: {
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, a new session is created."),
+    },
+});
+export const browserClose = defineTool({
+    name: "browser_close",
+    description: "Closes the current session by disconnecting the cloud browser. This will terminate the recording for the session.",
+    inputSchema: {
+        sessionId: z
+            .string()
+            .describe("The session ID to identify target browser. If not provided or invalid, you cannot close the session."),
+    },
+});
+export const browserGoto = defineTool({
+    name: "browser_goto",
+    description: `Navigate browser to a specified URL.
+    Restrictions: Only for direct URL navigation, not for searches.
+    Valid: Go to https://google.com.
+    Invalid: Search for "cats" on Google (use google_search).`,
+    inputSchema: {
+        url: z
+            .string()
+            .url()
+            .describe("The URL to navigate to in the browser session."),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, the active session is used."),
+    },
+    handle: async (context, params) => {
+        const session = context.getSession(params.sessionId);
+        if (!session?.page) {
+            return wrapMcpBrowserResponse("No active browser session found. Please create a browser session first.");
+        }
+        await session.page.goto(params.url);
+        const accessibilitySnapshot = await snapshot(session.page);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Navigated to ${params.url}`,
+                },
+                {
+                    type: "text",
+                    text: accessibilitySnapshot
+                }
+            ],
+        };
+    },
+});
+export const browserGoBack = defineTool({
+    name: "browser_go_back",
+    description: `Go back one step in browser history.
+    Restrictions: Only works if a previous page exists in the session history.
+    Valid: After navigating from page A to B, go back to A.
+    Invalid: Attempting to go back on the first page of a session.`,
+    inputSchema: {
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, the active session is used."),
+    },
+    handle: async (context, params) => {
+        const session = context.getSession(params.sessionId);
+        if (!session?.page) {
+            return wrapMcpBrowserResponse("No active browser session found. Please create a browser session first.");
+        }
+        await session.page.goBack();
+        const accessibilitySnapshot = await snapshot(session.page);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Navigated back.",
+                },
+                {
+                    type: "text",
+                    text: accessibilitySnapshot,
+                },
+            ],
+        };
+    },
+});
+export const browserGoForward = defineTool({
+    name: "browser_go_forward",
+    description: `Go forward one step in browser history.
+    Restrictions: Only works after a "go_back" action has been performed.
+    Valid: After going back from page B to A, go forward to B.
+    Invalid: Attempting to go forward without a preceding "go_back" action.`,
+    inputSchema: {
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, the active session is used."),
+    },
+    handle: async (context, params) => {
+        const session = context.getSession(params.sessionId);
+        if (!session?.page) {
+            return wrapMcpBrowserResponse("No active browser session found. Please create a browser session first.");
+        }
+        await session.page.goForward();
+        const accessibilitySnapshot = await snapshot(session.page);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Navigated forward.",
+                },
+                {
+                    type: "text",
+                    text: accessibilitySnapshot,
+                },
+            ],
+        };
+    },
+});
+export const browserClick = defineTool({
+    name: "browser_click",
+    description: `Click a specific element on the page.
+    Restrictions: Requires a valid CSS selector for the target element.
+    Valid: Click the button with selector "#submit-button".
+    Invalid: Click "the login button" without providing a selector.`,
+    inputSchema: {
+        selector: z.string().describe("The CSS selector of the element to click."),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, the active session is used."),
+    },
+    handle: async (context, params) => {
+        const session = context.getSession(params.sessionId);
+        if (!session?.page) {
+            return wrapMcpBrowserResponse("No active browser session found. Please create a browser session first.");
+        }
+        try {
+            await session.page.click(params.selector);
+            const accessibilitySnapshot = await snapshot(session.page);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Clicked on element with selector ${params.selector}`
+                    },
+                    {
+                        type: "text",
+                        text: accessibilitySnapshot
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            return wrapMcpBrowserResponse(`Failed to click on element: ${error.message}`);
+        }
+    },
+});
+export const browserType = defineTool({
+    name: "browser_type",
+    description: `Type text into a specified input field.
+    Restrictions: Requires a CSS selector for an input/textarea and the text to type.
+    Valid: Type "hello world" into input "[name='q']".
+    Invalid: Type "hello world" without specifying a target field.`,
+    inputSchema: {
+        selector: z.string().describe("CSS selector for the element to type into."),
+        text: z.string().describe("Text to type."),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, the active session is used."),
+    },
+    handle: async (context, params) => {
+        const session = context.getSession(params.sessionId);
+        if (!session?.page) {
+            return wrapMcpBrowserResponse("No active browser session found. Please create a browser session first.");
+        }
+        try {
+            await session.page.type(params.selector, params.text);
+            const accessibilitySnapshot = await snapshot(session.page);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Typed ${params.text} into element with selector ${params.selector}`
+                    },
+                    {
+                        type: "text",
+                        text: accessibilitySnapshot
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            return wrapMcpBrowserResponse(`Failed to type into element: ${error.message}`);
+        }
+    },
+});
+export const browserWaitFor = defineTool({
+    name: "browser_wait_for",
+    description: `Wait for a specific page element to appear.
+    Restrictions: Requires a valid CSS selector for the element to wait for.
+    Valid: Wait for the element "#results" to become visible.
+    Invalid: Wait for "the results to load" without a selector.`,
+    inputSchema: {
+        selector: z.string().describe("CSS selector of the element to wait for."),
+        timeout: z
+            .number()
+            .optional()
+            .describe("Maximum time to wait in milliseconds (default: 30000)."),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, the active session is used."),
+    },
+    handle: async (context, params) => {
+        const session = context.getSession(params.sessionId);
+        if (!session?.page) {
+            return wrapMcpBrowserResponse("No active browser session found. Please create a browser session first.");
+        }
+        try {
+            await session.page.waitForSelector(params.selector, {
+                timeout: params.timeout ?? 30000,
+            });
+            return wrapMcpBrowserResponse(`Successfully waited for element ${params.selector}`);
+        }
+        catch (error) {
+            return wrapMcpBrowserResponse(`Failed to wait for condition: ${error.message}`);
+        }
+    },
+});
+export const browserWait = defineTool({
+    name: "browser_wait",
+    description: `Pause execution for a fixed duration.
+    Restrictions: Requires a duration in milliseconds. Should be used sparingly.
+    Valid: Wait for 2000 milliseconds.
+    Invalid: Wait for a page to finish loading (use "browser_wait_for")`,
+    inputSchema: {
+        time: z
+            .number()
+            .int()
+            .positive()
+            .describe("Time to wait in milliseconds (default: 30000)."),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, the active session is used."),
+    },
+    handle: async (context, params) => {
+        await new Promise((resolve) => setTimeout(resolve, params.time ?? 30000));
+        return wrapMcpBrowserResponse(`Waited for ${params.time ?? 30000} milliseconds`);
+    },
+});
+export const browserScreenshot = defineTool({
+    name: "browser_screenshot",
+    description: `Capture a screenshot of the current page.
+    Restrictions: Can capture either the full page or the visible viewport.
+    Valid: Take a screenshot of the current browser view.
+    Invalid: Capture a screenshot of a specific element (not supported).`,
+    inputSchema: {
+        fullPage: z
+            .boolean()
+            .optional()
+            .describe([
+            "Whether to screenshot the full page (default: false)",
+            "You should avoid fullscreen if it's not important, since the " +
+                "images can be quite large",
+        ].join("\n")),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, the active session is used."),
+    },
+    handle: async (context, params) => {
+        const session = context.getSession(params.sessionId);
+        if (!session?.page) {
+            return wrapMcpBrowserResponse("No active browser session found. Please create a browser session first.");
+        }
+        try {
+            const screenshot = await session.page.screenshot({
+                fullPage: params.fullPage ?? false,
+            });
+            const accessibilitySnapshot = await snapshot(session.page);
+            return {
+                content: [
+                    {
+                        type: "image",
+                        // @ts-ignore
+                        data: screenshot.toString("base64"),
+                        mimeType: "image/png",
+                    },
+                    {
+                        type: "text",
+                        text: accessibilitySnapshot,
+                    }
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [],
+            };
+        }
+    },
+});
+export const browserGetHtml = defineTool({
+    name: "browser_get_html",
+    description: `Get the full HTML of the current page.
+    Restrictions: Returns the entire raw HTML source code.
+    Valid: Get the HTML of the current page to parse its structure.
+    Invalid: Get only the visible text (use "browser_get_text")`,
+    inputSchema: {
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, the active session is used."),
+    },
+    handle: async (context, params) => {
+        const session = context.getSession(params.sessionId);
+        if (!session?.page) {
+            return wrapMcpBrowserResponse("No active browser session found. Please create a browser session first.");
+        }
+        try {
+            const html = await session.page.content();
+            return wrapMcpBrowserResponse(html);
+        }
+        catch (error) {
+            return wrapMcpBrowserResponse(`Failed to retrieve HTML content: ${error.message}`);
+        }
+    },
+});
+export const browserGetText = defineTool({
+    name: "browser_get_text",
+    description: `Get all visible text from the current page.
+    Restrictions: Extracts only text content, ignoring HTML tags.
+    Valid: Get the text content of the current page for summarization.
+    Invalid: Get the page's HTML structure (use "browser_get_html")`,
+    inputSchema: {
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, the active session is used."),
+    },
+    handle: async (context, params) => {
+        const session = context.getSession(params.sessionId);
+        if (!session?.page) {
+            return wrapMcpBrowserResponse("No active browser session found. Please create a browser session first.");
+        }
+        try {
+            const text = await session.page.evaluate(() => document.body.innerText);
+            return wrapMcpBrowserResponse(text);
+        }
+        catch (error) {
+            return wrapMcpBrowserResponse(`Failed to retrieve text content: ${error.message}`);
+        }
+    },
+});
+export const browserScroll = defineTool({
+    name: "browser_scroll",
+    description: `Scroll the current page to a specific position.
+    Restrictions: Requires pixel coordinates for scrolling.
+    Valid: Scroll to the bottom of the page (e.g., { x: 0, y: 10000 }).
+    Invalid: Scroll to "the top" without specifying coordinates.`,
+    inputSchema: {
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, the active session is used."),
+    },
+    handle: async (context, params) => {
+        const session = context.getSession(params.sessionId);
+        if (!session?.page) {
+            return wrapMcpBrowserResponse("No active browser session found. Please create a browser session first.");
+        }
+        try {
+            await session.page.evaluate(() => {
+                window.scrollTo(0, document.body.scrollHeight);
+            });
+            const accessibilitySnapshot = await snapshot(session.page);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Scrolled to the bottom of the page.`,
+                    },
+                    {
+                        type: "text",
+                        text: accessibilitySnapshot,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return wrapMcpBrowserResponse(`Failed to scroll page: ${error.message}`);
+        }
+    },
+});
+export const browserScrollTo = defineTool({
+    name: "browser_scroll_to",
+    description: `Scroll a specific element into view.
+    Restrictions: Requires a valid CSS selector for the target element.
+    Valid: Scroll to the element "#footer".
+    Invalid: Scroll to the bottom of the page (use "browser_scroll").`,
+    inputSchema: {
+        x: z.number().describe("X coordinate to scroll to."),
+        y: z.number().describe("Y coordinate to scroll to."),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Optional session ID to use/reuse. If not provided or invalid, the active session is used."),
+    },
+    handle: async (context, params) => {
+        const session = context.getSession(params.sessionId);
+        if (!session?.page) {
+            return wrapMcpBrowserResponse("No active browser session found. Please create a browser session first.");
+        }
+        try {
+            await session.page.evaluate((x, y) => {
+                window.scrollTo(x, y);
+            }, params.x, params.y);
+            const accessibilitySnapshot = await snapshot(session.page);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Scrolled to position (${params.x}, ${params.y})`,
+                    },
+                    {
+                        type: "text",
+                        text: accessibilitySnapshot,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return wrapMcpBrowserResponse(`Failed to scroll page: ${error.message}`);
+        }
+    },
+});

package/build/tools/deepserp/googleFlights.js

@@ -0,0 +1,188 @@
+import { defineTool, wrapMcpResponse } from "../utils.js";
+import z from "zod";
+export const googleFlights = defineTool({
+    name: 'google_flights',
+    description: `Exclusive Flight Information Query Tool.
+    Activated only when requests include departure city, arrival city, and specific date/date range.
+    Valid:Check flights from Beijing to Shanghai on July 15.
+    Invalid:Compare airline service quality (use google-search instead)`,
+    inputSchema: {
+        gl: z
+            .string()
+            .describe("Parameter defines the country to use for the Google search. It's a two-letter country code. (e.g., us for the United States, uk for United Kingdom, or fr for France).")
+            .default('us'),
+        hl: z
+            .string()
+            .describe("Parameter defines the language to use for the Google search. It's a two-letter language code. (e.g., en for English, es for Spanish, or fr for French).")
+            .default('en'),
+        currency: z
+            .union([
+            z.literal('ALL'),
+            z.literal('DZD'),
+            z.literal('ARS'),
+            z.literal('AMD'),
+            z.literal('AWG'),
+            z.literal('AUD'),
+            z.literal('AZN'),
+            z.literal('BSD'),
+            z.literal('BHD'),
+            z.literal('BYN'),
+            z.literal('BMD'),
+            z.literal('BAM'),
+            z.literal('BRL'),
+            z.literal('GBP'),
+            z.literal('BGN'),
+            z.literal('XPF'),
+            z.literal('CAD'),
+            z.literal('CLP'),
+            z.literal('CNY'),
+            z.literal('COP'),
+            z.literal('CRC'),
+            z.literal('CUP'),
+            z.literal('CZK'),
+            z.literal('DKK'),
+            z.literal('DOP'),
+            z.literal('EGP'),
+            z.literal('EUR'),
+            z.literal('GEL'),
+            z.literal('HKD'),
+            z.literal('HUF'),
+            z.literal('ISK'),
+            z.literal('INR'),
+            z.literal('IDR'),
+            z.literal('IRR'),
+            z.literal('ILS'),
+            z.literal('JMD'),
+            z.literal('JPY'),
+            z.literal('JOD'),
+            z.literal('KZT'),
+            z.literal('KWD'),
+            z.literal('LBP'),
+            z.literal('MKD'),
+            z.literal('MYR'),
+            z.literal('MXN'),
+            z.literal('MDL'),
+            z.literal('MAD'),
+            z.literal('TWD'),
+            z.literal('NZD'),
+            z.literal('NOK'),
+            z.literal('OMR'),
+            z.literal('PKR'),
+            z.literal('PAB'),
+            z.literal('PEN'),
+            z.literal('PHP'),
+            z.literal('PLN'),
+            z.literal('QAR'),
+            z.literal('RON'),
+            z.literal('RUB'),
+            z.literal('SAR'),
+            z.literal('RSD'),
+            z.literal('SGD'),
+            z.literal('ZAR'),
+            z.literal('KRW'),
+            z.literal('SEK'),
+            z.literal('CHF'),
+            z.literal('THB'),
+            z.literal('TRY'),
+            z.literal('USD'),
+            z.literal('UAH'),
+            z.literal('AED'),
+            z.literal('VND')
+        ])
+            .describe('Parameter defines the currency of the returned prices. Default to USD.')
+            .optional(),
+        departure_id: z
+            .string()
+            .describe('Departure airport code or location kgmid. An airport code is an uppercase 3-letter code. You can search for it on Google Flights or IATA. For example, CDG is Paris Charles de Gaulle Airport, /m/0vzm is the location kgmid for Austin.You can specify multiple departure airports by separating them with a comma. For example, CDG,ORY,/m/04jpl.')
+            .default('ORY'),
+        arrival_id: z
+            .string()
+            .describe('An airport code is an uppercase 3-letter code. You can search for it on Google Flights or IATA.')
+            .default('BCN'),
+        data_type: z
+            .number()
+            .describe('Parameter defines the type of the flights.\nAvailable options:\n1 - Round trip (default)\n2 - One way\n3 - Multi-city\n\nWhen this parameter is set to 3, use multi_city_json to set the flight information.\n\nTo obtain the returning flight information for Round Trip (1), you need to make another request using a departure_token.')
+            .default(1),
+        travel_class: z
+            .union([
+            z.literal(1).describe('Economy(default) - 1'),
+            z.literal(2).describe('Premium economy - 2'),
+            z.literal(3).describe('Business - 3'),
+            z.literal(4).describe('First - 4')
+        ])
+            .describe('Parameter defines the travel class.\nAvailable options:\n1 - Economy (default)\n2 - Premium economy\n3 - Business\n4 - First')
+            .default(1),
+        multi_city_json: z
+            .any()
+            .describe("Parameter defines the flight information for multi-city flights. It's a JSON string containing multiple flight information objects. Each object should contain the following fields: departure_id, arrival_id, date, times (optional). See schema for details.")
+            .optional(),
+        adults: z.number().describe('Parameter defines the number of adults. Default to 1.').default(1),
+        children: z.number().describe('Parameter defines the number of children. Default to 0.').default(0),
+        infants_in_seat: z.number().describe('Parameter defines the number of infants in seat. Default to 0.').default(0),
+        infants_on_lap: z.number().describe('Parameter defines the number of infants on lap. Default to 0.').default(0),
+        outbound_date: z
+            .string()
+            .describe('Parameter defines the outbound date. The format is YYYY-MM-DD. e.g. 2025-03-09')
+            .default('next_1d'),
+        return_date: z
+            .string()
+            .describe('Parameter defines the return date. The format is YYYY-MM-DD. e.g. 2025-03-15\n\nParameter is required if type parameter is set to: 1 (Round trip)')
+            .default('next_1w'),
+        stops: z
+            .union([
+            z.literal(0).describe('Any number of stops (default) - 0'),
+            z.literal(1).describe('Nonstop only - 1'),
+            z.literal(2).describe('1 stop or fewer - 2'),
+            z.literal(3).describe('2 stops or fewer - 3')
+        ])
+            .describe('Parameter defines the number of stops during the flight.\nAvailable options:\n0 - Any number of stops (default)\n1 - Nonstop only\n2 - 1 stop or fewer\n3 - 2 stops or fewer')
+            .default(0),
+        include_airlines: z
+            .string()
+            .describe("Parameter defines the airline codes to be included. Split multiple airlines with comma. It can't be used together with exclude_airlines. Each airline code should be a 2-character IATA code consisting of either two uppercase letters or one uppercase letter and one digit. Alliances can also be included. See schema for details.")
+            .optional()
+            .optional(),
+        bags: z.number().describe('Parameter defines the number of carry-on bags. Default to 0.').default(0),
+        max_price: z.number().describe('Parameter defines the maximum ticket price. Default to unlimited.').default(0),
+        outbound_times: z
+            .string()
+            .describe('Parameter defines the outbound times range. See schema for details.')
+            .optional()
+            .optional(),
+        return_times: z
+            .string()
+            .describe('Parameter defines the return times range. See schema for details.')
+            .optional()
+            .optional(),
+        emissions: z
+            .union([z.literal(0).describe('reset'), z.literal(1).describe('Less emissions only - ·')])
+            .describe('Parameter defines the emission level of the flight.\nAvailable options:\n1 - Less emissions only')
+            .default(0),
+        layover_duration: z
+            .string()
+            .describe("Parameter defines the layover duration, in minutes. It's a string containing two comma-separated numbers. See schema for details.")
+            .optional()
+            .optional(),
+        exclude_conns: z
+            .string()
+            .describe('Parameter defines the connecting airport codes to be excluded. See schema for details.')
+            .optional()
+            .optional(),
+        max_duration: z
+            .number()
+            .describe('Parameter defines the maximum flight duration, in minutes. For example, specify 1500 for 25 hours.')
+            .default(0)
+            .optional(),
+        departure_token: z
+            .string()
+            .describe('Parameter is used to select the flight and get returning flights (for Round trip) or flights for the next leg of itinerary (for Multi-city). Find this token in the departure flight results.')
+            .optional()
+            .optional()
+    },
+    handle: async (params, client) => {
+        return wrapMcpResponse(() => client.deepserp.scrape({
+            actor: 'scraper.google.flights',
+            input: params
+        }));
+    }
+});