@solarisdk/mcp 0.4.2 → 0.4.4

package/dist/browser-tools/interaction.js

@@ -0,0 +1,91 @@
+// Clicking, typing, key presses and arbitrary page-context JS.
+import { z } from "zod";
+import { text } from "./context.js";
+export function makeInteractionTools(ctx) {
+    const { need, activePage } = ctx;
+    return {
+        solari_browser_click: {
+            description: "Click on the page: give a CSS selector, or x/y viewport coordinates (e.g. from a screenshot).",
+            inputSchema: {
+                sessionId: z.string(),
+                selector: z.string().optional(),
+                x: z.number().optional(),
+                y: z.number().optional(),
+            },
+            handler: async (a) => {
+                const page = await activePage(need(a.sessionId));
+                if (a.selector) {
+                    await page.click(a.selector);
+                }
+                else if (typeof a.x === "number" && typeof a.y === "number") {
+                    await page.mouse.click(a.x, a.y);
+                }
+                else {
+                    throw new Error("provide selector or x+y");
+                }
+                return text({ ok: true, url: page.url() });
+            },
+        },
+        solari_browser_type: {
+            description: "Type text into the page. Optionally focus a CSS selector first. clear:true replaces the " +
+                "field's existing value (otherwise text is appended at the caret). pressEnter submits.",
+            inputSchema: {
+                sessionId: z.string(),
+                text: z.string(),
+                selector: z.string().optional(),
+                clear: z.boolean().optional(),
+                pressEnter: z.boolean().optional(),
+            },
+            handler: async (a) => {
+                const page = await activePage(need(a.sessionId));
+                if (a.selector) {
+                    const sel = a.selector;
+                    await page.focus(sel);
+                    if (a.clear) {
+                        await page.$eval(sel, (el) => {
+                            const f = el;
+                            f.value = "";
+                            f.dispatchEvent(new Event("input", { bubbles: true }));
+                        });
+                    }
+                }
+                await page.keyboard.type(a.text, { delay: 20 });
+                if (a.pressEnter)
+                    await page.keyboard.press("Enter");
+                return text({ ok: true });
+            },
+        },
+        solari_browser_key: {
+            description: "Press a key in the browser session (e.g. 'Enter', 'Escape', 'ArrowDown', 'PageDown'). " +
+                "Chords use '+' (e.g. 'Control+a').",
+            inputSchema: { sessionId: z.string(), key: z.string() },
+            handler: async (a) => {
+                const page = await activePage(need(a.sessionId));
+                const parts = a.key.split("+").filter(Boolean);
+                const key = parts.pop();
+                for (const m of parts)
+                    await page.keyboard.down(m);
+                try {
+                    await page.keyboard.press(key);
+                }
+                finally {
+                    for (const m of parts.reverse())
+                        await page.keyboard.up(m);
+                }
+                return text({ ok: true });
+            },
+        },
+        solari_browser_evaluate: {
+            description: "Evaluate a JavaScript expression on the page and return its JSON-serialized result.",
+            inputSchema: { sessionId: z.string(), expression: z.string() },
+            handler: async (a) => {
+                const page = await activePage(need(a.sessionId));
+                // Pass the expression as a string: puppeteer sends it as a
+                // debugger-originated Runtime.evaluate, which is exempt from the
+                // page's CSP. Wrapping it in eval() inside page context is not.
+                const result = await page.evaluate(a.expression);
+                return text(result === undefined ? "undefined" : result);
+            },
+        },
+    };
+}

package/dist/browser-tools/navigation.d.ts

@@ -0,0 +1,2 @@
+import { type BrowserToolCtx, type Tool } from "./context.js";
+export declare function makeNavigationTools(ctx: BrowserToolCtx): Record<string, Tool>;

package/dist/browser-tools/navigation.js

@@ -0,0 +1,30 @@
+// Page navigation.
+import { z } from "zod";
+import { text } from "./context.js";
+export function makeNavigationTools(ctx) {
+    const { need, activePage } = ctx;
+    return {
+        solari_browser_navigate: {
+            description: "Navigate the browser session to a URL. Returns final url, title and HTTP status.",
+            inputSchema: { sessionId: z.string(), url: z.string() },
+            handler: async (a) => {
+                const page = await activePage(need(a.sessionId));
+                let url = a.url.trim();
+                if (!/^[a-z][a-z0-9+.-]*:/i.test(url))
+                    url = `https://${url}`;
+                const scheme = url.slice(0, url.indexOf(":")).toLowerCase();
+                if (scheme !== "http" && scheme !== "https") {
+                    throw new Error(`refusing to navigate to a non-http(s) URL (${scheme}:)`);
+                }
+                // Block link-local / cloud metadata so page content can't steer the
+                // agent into reading the browser pool's instance credentials.
+                const host = new URL(url).hostname;
+                if (/^(169\.254\.|127\.|\[?::1\]?$|localhost$|metadata\.google)/i.test(host)) {
+                    throw new Error(`refusing to navigate to internal host ${host}`);
+                }
+                const resp = await page.goto(url, { waitUntil: "domcontentloaded", timeout: 60_000 });
+                return text({ url: page.url(), title: await page.title(), status: resp?.status() ?? null });
+            },
+        },
+    };
+}

package/dist/browser-tools/session.d.ts

@@ -0,0 +1,2 @@
+import { type BrowserToolCtx, type Tool } from "./context.js";
+export declare function makeSessionTools(ctx: BrowserToolCtx): Record<string, Tool>;

package/dist/browser-tools/session.js

@@ -0,0 +1,182 @@
+import { z } from "zod";
+import { apiError, CDP_DIAL_ATTEMPTS, redact, releaseBrowserSession, text, } from "./context.js";
+export function makeSessionTools(ctx) {
+    const { cfg, reg, deps, api } = ctx;
+    return {
+        solari_browser_create: {
+            description: "Start a Solari cloud browser session. Use this whenever you need to browse the web. " +
+                "Returns a sessionId for the other solari_browser_* tools.\n" +
+                "mode defaults to 'stealth' — the anti-bot hardened pool. Just call this with no " +
+                "arguments and you get it; you do NOT need to ask for stealth explicitly. Stealth is " +
+                "the right default for the open web: ordinary sites work fine on it, and it is what " +
+                "keeps bot-detection from blocking the session.\n" +
+                "Pass mode:'fast' ONLY for a site you already know does not fingerprint or block " +
+                "automation (internal tools, localhost, your own app, plain docs/API pages) and you " +
+                "want the lower-latency pool. If a page in fast mode returns a block/captcha/challenge, " +
+                "close the session and retry with mode:'stealth'.\n" +
+                "captcha auto-solving is ALSO on by default (it follows the pool: on for stealth, off " +
+                "for fast). Pass captcha:false to turn it off — solving a challenge costs money and " +
+                "adds latency, so switch it off for sites you know never challenge.\n" +
+                "proxy ('smart' | country code like 'us') REQUIRES stealth, as does captcha; both are " +
+                "rejected if you ask for them explicitly in fast mode. recording gives an rrweb replay.",
+            inputSchema: {
+                mode: z.enum(["stealth", "fast"]).optional(),
+                /** @deprecated use mode. Kept so existing callers keep working. */
+                stealth: z.boolean().optional(),
+                proxy: z.string().optional(),
+                /** Defaults to ON (following the pool). Pass false to opt out. */
+                captcha: z.boolean().optional(),
+                recording: z.boolean().optional(),
+                profileId: z.string().optional(),
+                /** Defaults to ON. Pass false to never auto-sign-in on this session. */
+                autoLogin: z.boolean().optional(),
+            },
+            handler: async (a) => {
+                // STEALTH IS THE DEFAULT. Models consistently declined to opt in when it
+                // was an optional boolean, so sessions silently landed on the fast pool
+                // and got blocked by bot detection — the failure looked like "the site
+                // is broken" rather than "we picked the wrong pool". Defaulting on, with
+                // an explicit escape hatch, removes that whole class of confusion.
+                //
+                // Precedence: explicit mode wins; then the deprecated stealth boolean
+                // (so `stealth:false` still means fast for old callers); then stealth.
+                const stealth = a.mode !== undefined ? a.mode === "stealth" : (a.stealth ?? true);
+                // CAPTCHA IS ALSO ON BY DEFAULT — same reasoning as stealth: a model
+                // that has to opt in does not, and the resulting failure ("the page is
+                // a challenge screen") reads as a broken site rather than a missing
+                // option.
+                //
+                // The default FOLLOWS the pool rather than being a flat `true`, because
+                // captcha is stealth-only upstream. A flat true would make plain
+                // mode:'fast' throw on an option the caller never asked for, turning the
+                // escape hatch into a dead end. So: stealth ⇒ on, fast ⇒ off, and an
+                // explicit value always wins (captcha:false is the opt-out).
+                const captcha = a.captcha ?? stealth;
+                // proxy/captcha are stealth-only upstream. Previously a fast-pool
+                // session with proxy came back with the proxy silently dropped and only
+                // a note in the response; fail loudly instead — a silently unproxied
+                // request can leak the origin IP, which is the one thing the caller was
+                // trying to avoid. Only an EXPLICIT ask conflicts; the captcha default
+                // simply turns itself off in fast mode.
+                if (!stealth) {
+                    const needsStealth = [a.proxy ? "proxy" : "", a.captcha === true ? "captcha" : ""].filter(Boolean);
+                    if (needsStealth.length) {
+                        throw new Error(`${needsStealth.join(" and ")} ${needsStealth.length > 1 ? "require" : "requires"} ` +
+                            `stealth, but mode is 'fast'. ` +
+                            `Drop ${needsStealth.length > 1 ? "them" : "it"} or use mode:'stealth'.`);
+                    }
+                }
+                const body = {};
+                if (stealth)
+                    body.stealth = true;
+                if (captcha)
+                    body.captcha = true;
+                if (a.recording)
+                    body.recording = true;
+                if (a.proxy)
+                    body.proxy = a.proxy;
+                if (a.profileId)
+                    body.profileId = a.profileId;
+                // Auto-login is ON by default. If the account has connected a password
+                // manager and configured this site, the gateway signs the session in on
+                // its own — the agent never sees or handles the credential. Costs
+                // nothing when nothing is configured: the gateway finds no connection
+                // and the flow is exactly as before.
+                if (a.autoLogin !== false)
+                    body.autoLogin = true;
+                const res = await api(cfg, "POST", "/sessions", body);
+                if (res.status !== 201)
+                    await apiError(res, "session create");
+                const s = (await res.json());
+                // cdpEndpoint is optional on the wire; derive it from wsEndpoint the
+                // way the official SDK does.
+                const cdp = s.cdpEndpoint ?? s.wsEndpoint?.replace("/ws/", "/cdp/");
+                if (!cdp)
+                    throw new Error("gateway returned no cdpEndpoint or wsEndpoint");
+                // From here on the session is BILLABLE. Any failure before it is
+                // registered must release it, or it leaks until TTL with an id the
+                // model never saw.
+                try {
+                    let browser;
+                    let lastErr;
+                    for (let i = 0; i < CDP_DIAL_ATTEMPTS; i++) {
+                        try {
+                            browser = await deps.connect(cdp);
+                            break;
+                        }
+                        catch (err) {
+                            // A freshly-started session has a transient upstream window.
+                            lastErr = err;
+                            await new Promise((r) => setTimeout(r, 500 * (i + 1)));
+                        }
+                    }
+                    if (!browser)
+                        throw lastErr ?? new Error("could not connect to the browser");
+                    const pages = await browser.pages();
+                    const page = pages.find((p) => !p.isClosed()) ?? (await browser.newPage());
+                    reg.sessions.set(s.sessionId, {
+                        sessionId: s.sessionId,
+                        browser,
+                        page,
+                        expiresAt: s.expiresAt,
+                        recording: Boolean(a.recording),
+                        cdpEndpoint: cdp,
+                    });
+                }
+                catch (err) {
+                    await releaseBrowserSession(cfg, s.sessionId, api).catch(() => { });
+                    throw new Error(`browser session started but could not be attached (released it): ${redact(err instanceof Error ? err.message : String(err))}`);
+                }
+                // Proxy silently degrades rather than erroring — surface what we got.
+                // Echo the resolved mode back: the caller did not necessarily pick it
+                // (stealth is the default), and knowing which pool it landed on is what
+                // makes a later block actionable — "retry on stealth" vs "this site
+                // blocks us even hardened".
+                return text({
+                    sessionId: s.sessionId,
+                    mode: stealth ? "stealth" : "fast",
+                    captcha,
+                    expiresAt: s.expiresAt,
+                    proxy: s.proxy ?? (a.proxy ? "NOT APPLIED (check plan)" : undefined),
+                });
+            },
+        },
+        solari_browser_replay_url: {
+            description: "Get the session-replay URL for a browser session created with recording: true. " +
+                "May 404 for a few seconds right after close — retry.",
+            inputSchema: { sessionId: z.string() },
+            handler: async (a) => {
+                const id = a.sessionId;
+                const known = reg.sessions.get(id);
+                if (known && !known.recording) {
+                    throw new Error(`session ${id} was not created with recording: true, so it has no replay`);
+                }
+                const res = await api(cfg, "GET", `/sessions/${encodeURIComponent(id)}/replay-url`);
+                if (!res.ok)
+                    await apiError(res, "replay-url");
+                return text(await res.json());
+            },
+        },
+        solari_browser_close: {
+            description: "Close a browser session and release it.",
+            inputSchema: { sessionId: z.string() },
+            handler: async (a) => {
+                const id = a.sessionId;
+                // Release FIRST: if it fails, keep the registry entry so the model can
+                // retry rather than losing the handle to a still-billing session.
+                await releaseBrowserSession(cfg, id, api);
+                const e = reg.sessions.get(id);
+                if (e) {
+                    try {
+                        await e.browser.disconnect();
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                    reg.sessions.delete(id);
+                }
+                return text({ ok: true });
+            },
+        },
+    };
+}

package/dist/browser.d.ts

@@ -1,52 +1,7 @@
-import { type Browser, type Page } from "puppeteer-core";
-import { type ZodTypeAny } from "zod";
-export interface McpResult {
-    content: Array<{
-        type: "text";
-        text: string;
-    } | {
-        type: "image";
-        data: string;
-        mimeType: string;
-    }>;
-    isError?: boolean;
-}
-export interface Tool {
-    description: string;
-    inputSchema: Record<string, ZodTypeAny>;
-    handler: (args: Record<string, unknown>) => Promise<McpResult>;
-}
-export interface BrowserConfig {
-    apiKey: string;
-    baseUrl: string;
-}
-interface BrowserEntry {
-    sessionId: string;
-    browser: Browser;
-    page: Page;
-    expiresAt: string;
-    recording: boolean;
-    /**
-     * The session's raw CDP endpoint, kept so the handoff flow can RECONNECT.
-     *
-     * A login handoff severs the agent's socket gateway-side — deliberately, so
-     * the agent cannot watch the human type. That kills this entry's puppeteer
-     * handle, so resuming afterwards needs a fresh connect rather than the dead
-     * one. Without this the agent "resumes" into a Target-closed error.
-     */
-    cdpEndpoint: string;
-}
-export interface BrowserRegistry {
-    sessions: Map<string, BrowserEntry>;
-}
-declare function api(cfg: BrowserConfig, method: string, path: string, body?: unknown): Promise<Response>;
-/** Release a browser session gateway-side. Safe to call for unknown ids. */
-export declare function releaseBrowserSession(cfg: BrowserConfig, id: string, fetchApi?: typeof api): Promise<void>;
-export interface BrowserDeps {
-    connect: (cdpEndpoint: string) => Promise<Browser>;
-    fetchApi: typeof api;
-}
+import { api, type BrowserDeps } from "./browser-tools/context.js";
+export type { BrowserConfig, BrowserDeps, BrowserRegistry, McpResult, Tool, } from "./browser-tools/context.js";
+export { releaseBrowserSession } from "./browser-tools/context.js";
+import type { BrowserConfig, BrowserRegistry, Tool } from "./browser-tools/context.js";
 export declare function makeBrowserToolset(cfg: BrowserConfig, reg: BrowserRegistry, deps?: BrowserDeps): Record<string, Tool>;
 /** Release every browser session in a registry (used on eviction/shutdown). */
 export declare function releaseAllBrowserSessions(cfg: BrowserConfig, reg: BrowserRegistry, fetchApi?: typeof api): Promise<void>;
-export {};