@solarisdk/mcp 0.2.0

package/README.md

@@ -0,0 +1,105 @@
+# solari-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI
+agents (Claude Desktop **incl. Cowork**, Claude Code, Cursor, Windsurf, …) use
+**Solari as their browser, sandbox, and desktop**:
+
+- **Cloud browser** — create stealth/proxied browser sessions, navigate, read
+  pages, screenshot, click/type, session replay (wraps the Solari browser
+  gateway + CDP via puppeteer-core).
+- **Sandboxes** — headless microVMs: run commands/code, read/write files,
+  expose ports.
+- **Desktops** — GUI microVMs: screenshot/click/type, launch apps, noVNC
+  stream URL.
+
+MCP tool calls are stateless, so the server keeps an in-memory **session
+registry**: `*_create` tools return a `sessionId`, and the rest take it.
+
+## Use it (Claude Desktop / Cowork / Cursor / Windsurf)
+
+```jsonc
+// claude_desktop_config.json (Claude Desktop: Developer → Edit Config)
+{
+  "mcpServers": {
+    "solari": {
+      "command": "node",
+      "args": ["/absolute/path/to/solari-mcp.bundle.cjs"],
+      "env": {
+        "SOLARI_API_KEY": "slr_live_…"
+        // optional overrides (defaults hit prod https://api.getsolari.com):
+        // "SOLARI_BASE_URL":    "https://desktops-sta.solaribrowser.com",  // sandbox/desktop gateway
+        // "SOLARI_BROWSER_URL": "https://api-sta.solaribrowser.com"        // browser gateway
+      }
+    }
+  }
+}
+```
+
+Fully quit and reopen Claude Desktop after editing; the tools then show up in
+Chat, Code and Cowork alike.
+
+## Environment
+
+| Var | Required | Default | Meaning |
+|---|---|---|---|
+| `SOLARI_API_KEY` | ✅ | — | unified `slr_live_…` key (works on both gateways) |
+| `SOLARI_BASE_URL` | | `https://api.getsolari.com` | sandbox/desktop gateway |
+| `SOLARI_BROWSER_URL` | | `SOLARI_BASE_URL` → prod | cloud-browser gateway (differs from `SOLARI_BASE_URL` on staging) |
+
+## Tools
+
+### Browser (Solari cloud browser)
+
+| Tool | What it does |
+|---|---|
+| `solari_browser_create` | Start a browser session (`stealth`, `proxy`, `captcha`, `recording`, `profileId`) → `sessionId` |
+| `solari_browser_navigate` | Go to a URL → `{url, title, status}` |
+| `solari_browser_read_page` | Page text / links / HTML (30k-char cap) |
+| `solari_browser_screenshot` | JPEG screenshot (image content) |
+| `solari_browser_click` / `solari_browser_type` / `solari_browser_key` | Interact (selector or x/y) |
+| `solari_browser_evaluate` | Run a JS expression on the page |
+| `solari_browser_replay_url` | rrweb replay URL (needs `recording: true`) |
+| `solari_browser_close` | Release the session |
+
+### Sandboxes + desktops
+
+| Tool | What it does |
+|---|---|
+| `solari_sandbox_create` | Create a headless sandbox → `sessionId` |
+| `solari_desktop_create` | Create a GUI desktop → `sessionId` + `streamUrl` |
+| `solari_list` | List the org's sandboxes |
+| `solari_kill` | Destroy a session |
+| `solari_connect` | Re-attach to a session by id across restarts (auto-resumes if paused) |
+| `solari_exec` | Run a shell command (via `sh -c`) → `{stdout,stderr,exitCode}` |
+| `solari_run_command_bg` | Start a background shell command → `{cmdId}` |
+| `solari_run_code` | Run code (default Python) → results incl. structured charts |
+| `solari_read_file` / `solari_write_file` / `solari_list_files` | Guest filesystem |
+| `solari_get_preview_url` | Public preview URL for an in-guest port |
+| `solari_screenshot` | Capture the desktop as a PNG (image content) |
+| `solari_click` / `solari_type` / `solari_key` | Desktop mouse/keyboard |
+| `solari_open_app` | Launch an app on the desktop |
+
+(The desktop GUI tools require a `solari_desktop_create` session; they error on
+a sandbox. The browser tools are independent of both.)
+
+## Develop
+
+```bash
+npm install          # installs @modelcontextprotocol/sdk, puppeteer-core + the local SDK
+npm run build        # tsc → dist/
+npm test             # mock-client toolset tests (no network)
+npm run build:bundle # esbuild → dist/solari-mcp.bundle.cjs (single file, no node_modules)
+```
+
+**Live smoke (manual, hits real pools):**
+
+```bash
+SOLARI_API_KEY=slr_live_… \
+SOLARI_BASE_URL=https://desktops-sta.solaribrowser.com \
+SOLARI_BROWSER_URL=https://api-sta.solaribrowser.com \
+node test/live-smoke.mjs            # add SMOKE_SERVER=dist/solari-mcp.bundle.cjs to test the bundle
+```
+
+Round-trips browser create→navigate→read→screenshot→search→close, sandbox
+create→exec→run_code→kill, and desktop create→screenshot→kill as a real MCP
+client over stdio.

package/dist/browser.d.ts

@@ -0,0 +1,39 @@
+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;
+}
+export interface BrowserRegistry {
+    sessions: Map<string, BrowserEntry>;
+}
+declare function api(cfg: BrowserConfig, method: string, path: string, body?: unknown): Promise<Response>;
+export interface BrowserDeps {
+    connect: (cdpEndpoint: string) => Promise<Browser>;
+    fetchApi: typeof api;
+}
+export declare function makeBrowserToolset(cfg: BrowserConfig, reg: BrowserRegistry, deps?: BrowserDeps): Record<string, Tool>;
+export {};

package/dist/browser.js

@@ -0,0 +1,281 @@
+// Solari cloud-browser toolset for solari-mcp.
+//
+// The browser gateway is a session control plane only (create/release); all
+// page-level actions here are driven client-side over the session's raw CDP
+// endpoint via puppeteer-core. We keep the connected Browser handle for the
+// session's lifetime — the signed ws URL cannot be re-dialed after 90 minutes.
+import puppeteer from "puppeteer-core";
+import { z } from "zod";
+const text = (o) => ({
+    content: [{ type: "text", text: typeof o === "string" ? o : JSON.stringify(o, null, 2) }],
+});
+const MAX_PAGE_TEXT = 30_000;
+async function api(cfg, method, path, body) {
+    // Session create can block up to 60s gateway-side waiting for a slot.
+    const res = await fetch(`${cfg.baseUrl}${path}`, {
+        method,
+        headers: {
+            authorization: `Bearer ${cfg.apiKey}`,
+            ...(body ? { "content-type": "application/json" } : {}),
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+        signal: AbortSignal.timeout(90_000),
+    });
+    return res;
+}
+async function apiError(res, what) {
+    let detail = "";
+    try {
+        detail = await res.text();
+    }
+    catch {
+        /* body unavailable */
+    }
+    throw new Error(`${what} failed: HTTP ${res.status} ${detail.slice(0, 500)}`);
+}
+const defaultDeps = {
+    connect: (cdpEndpoint) => puppeteer.connect({
+        browserWSEndpoint: cdpEndpoint,
+        defaultViewport: { width: 1280, height: 800 },
+    }),
+    fetchApi: api,
+};
+export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
+    const api = deps.fetchApi;
+    const need = (id) => {
+        const e = reg.sessions.get(id);
+        if (!e)
+            throw new Error(`unknown browser sessionId: ${id} (create one with solari_browser_create)`);
+        return e;
+    };
+    // The agent may have navigated into a popup/new tab; act on the most
+    // recently opened page that is still attached.
+    const activePage = async (e) => {
+        if (!e.page.isClosed())
+            return e.page;
+        const pages = await e.browser.pages();
+        if (pages.length === 0)
+            throw new Error("no open pages in this browser session");
+        e.page = pages[pages.length - 1];
+        return e.page;
+    };
+    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. Options: stealth (anti-bot " +
+                "hardened pool), proxy ('smart' | country code like 'us' — requires stealth), captcha " +
+                "auto-solving (requires stealth), recording (rrweb replay).",
+            inputSchema: {
+                stealth: z.boolean().optional(),
+                proxy: z.string().optional(),
+                captcha: z.boolean().optional(),
+                recording: z.boolean().optional(),
+                profileId: z.string().optional(),
+            },
+            handler: async (a) => {
+                const body = {};
+                if (a.stealth)
+                    body.stealth = true;
+                if (a.captcha)
+                    body.captcha = true;
+                if (a.recording)
+                    body.recording = true;
+                if (a.proxy)
+                    body.proxy = a.proxy;
+                if (a.profileId)
+                    body.profileId = a.profileId;
+                const res = await api(cfg, "POST", "/sessions", body);
+                if (res.status !== 201)
+                    await apiError(res, "session create");
+                const s = (await res.json());
+                const browser = await deps.connect(s.cdpEndpoint);
+                const pages = await browser.pages();
+                const page = pages[0] ?? (await browser.newPage());
+                reg.sessions.set(s.sessionId, {
+                    sessionId: s.sessionId,
+                    browser,
+                    page,
+                    expiresAt: s.expiresAt,
+                    recording: Boolean(a.recording),
+                });
+                // Proxy silently degrades rather than erroring — surface what we got.
+                return text({
+                    sessionId: s.sessionId,
+                    expiresAt: s.expiresAt,
+                    proxy: s.proxy ?? (a.proxy ? "NOT APPLIED (check plan/stealth)" : undefined),
+                });
+            },
+        },
+        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));
+                const resp = await page.goto(a.url, { waitUntil: "domcontentloaded", timeout: 60_000 });
+                return text({ url: page.url(), title: await page.title(), status: resp?.status() ?? null });
+            },
+        },
+        solari_browser_read_page: {
+            description: "Read the current page. format 'text' (default) returns visible text; 'links' returns " +
+                "clickable links {text, href}; 'html' returns raw HTML. Output is truncated to 30k chars.",
+            inputSchema: {
+                sessionId: z.string(),
+                format: z.enum(["text", "links", "html"]).optional(),
+            },
+            handler: async (a) => {
+                const page = await activePage(need(a.sessionId));
+                const fmt = a.format ?? "text";
+                let out;
+                if (fmt === "html") {
+                    out = await page.content();
+                }
+                else if (fmt === "links") {
+                    const links = await page.$$eval("a[href]", (as) => as
+                        .map((el) => ({
+                        text: (el.textContent ?? "").trim().slice(0, 120),
+                        href: el.href,
+                    }))
+                        .filter((l) => l.text)
+                        .slice(0, 200));
+                    out = JSON.stringify(links, null, 2);
+                }
+                else {
+                    out = await page.evaluate(() => document.body?.innerText ?? "");
+                }
+                const truncated = out.length > MAX_PAGE_TEXT;
+                return text(`${page.url()}\n\n${out.slice(0, MAX_PAGE_TEXT)}${truncated ? "\n…[truncated]" : ""}`);
+            },
+        },
+        solari_browser_screenshot: {
+            description: "Screenshot the browser session's current page (JPEG image).",
+            inputSchema: { sessionId: z.string(), fullPage: z.boolean().optional() },
+            handler: async (a) => {
+                const page = await activePage(need(a.sessionId));
+                const buf = await page.screenshot({
+                    type: "jpeg",
+                    quality: 75,
+                    fullPage: Boolean(a.fullPage),
+                });
+                return {
+                    content: [
+                        { type: "image", data: Buffer.from(buf).toString("base64"), mimeType: "image/jpeg" },
+                    ],
+                };
+            },
+        },
+        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. Set pressEnter to submit.",
+            inputSchema: {
+                sessionId: z.string(),
+                text: z.string(),
+                selector: z.string().optional(),
+                pressEnter: z.boolean().optional(),
+            },
+            handler: async (a) => {
+                const page = await activePage(need(a.sessionId));
+                if (a.selector)
+                    await page.click(a.selector);
+                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').",
+            inputSchema: { sessionId: z.string(), key: z.string() },
+            handler: async (a) => {
+                const page = await activePage(need(a.sessionId));
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                await page.keyboard.press(a.key);
+                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));
+                const result = await page.evaluate((expr) => {
+                    // eslint-disable-next-line no-eval
+                    const v = (0, eval)(expr);
+                    try {
+                        return JSON.parse(JSON.stringify(v ?? null));
+                    }
+                    catch {
+                        return String(v);
+                    }
+                }, a.expression);
+                return text(result);
+            },
+        },
+        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 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;
+                const e = reg.sessions.get(id);
+                if (e) {
+                    try {
+                        await e.browser.disconnect();
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                    reg.sessions.delete(id);
+                }
+                const res = await api(cfg, "DELETE", `/sessions/${encodeURIComponent(id)}`);
+                // 204 = released; bare 404 = already gone (fine); 404 + InvalidSessionId = real failure.
+                if (res.status === 404) {
+                    let code;
+                    try {
+                        code = (await res.json()).code;
+                    }
+                    catch {
+                        /* no body */
+                    }
+                    if (code === "InvalidSessionId")
+                        throw new Error("release failed: gateway rejected sessionId");
+                }
+                else if (res.status !== 204) {
+                    await apiError(res, "session release");
+                }
+                return text({ ok: true });
+            },
+        },
+    };
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// CLI + bundle entry point: unconditionally start the stdio server. The
+// import.meta.url main-gate in server.ts fails under npm bin symlinks (argv[1]
+// is the symlink, import.meta.url the real file) and inside the esbuild cjs
+// bundle — so both routes come through here instead.
+import { main } from "./server.js";
+main().catch((err) => {
+    console.error("solari-mcp fatal:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ZodTypeAny } from "zod";
+import { SolariClient } from "@solarisdk/sdk";
+import { type BrowserConfig } from "./browser.js";
+type Kind = "sandbox" | "desktop";
+interface Entry {
+    kind: Kind;
+    handle: any;
+}
+export interface Registry {
+    sessions: Map<string, Entry>;
+}
+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 declare function makeToolset(client: SolariClient, reg: Registry): Record<string, Tool>;
+export declare function registerToolset(server: McpServer, toolset: Record<string, Tool>): void;
+export declare function buildServer(client?: SolariClient, browserCfg?: BrowserConfig): McpServer;
+export declare function main(): Promise<void>;
+export {};

package/dist/server.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+// solari-mcp — a Model Context Protocol server that lets agents (Claude
+// Desktop/Code, Cursor, Windsurf, …) drive Solari sandboxes + desktops.
+//
+// Stdio transport. Auth via SOLARI_API_KEY (+ optional SOLARI_BASE_URL).
+// MCP tool calls are stateless, so the server keeps a session registry keyed by
+// sessionId: create tools return an id, and the rest take it.
+//
+// The toolset is built as a plain map (makeToolset) so it can be unit-tested
+// against a mock SolariClient without an MCP transport.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { SolariClient } from "@solarisdk/sdk";
+import { makeBrowserToolset } from "./browser.js";
+const text = (o) => ({
+    content: [{ type: "text", text: typeof o === "string" ? o : JSON.stringify(o, null, 2) }],
+});
+export function makeToolset(client, reg) {
+    const need = (id) => {
+        const e = reg.sessions.get(id);
+        if (!e)
+            throw new Error(`unknown sessionId: ${id}`);
+        return e;
+    };
+    const live = async (id) => {
+        const e = need(id);
+        if (!e.handle.connected)
+            await e.handle.connect();
+        return e;
+    };
+    const desktop = async (id) => {
+        const e = await live(id);
+        if (e.kind !== "desktop")
+            throw new Error(`session ${id} is a sandbox; this tool needs a desktop`);
+        return e;
+    };
+    return {
+        solari_sandbox_create: {
+            description: "Create a headless sandbox (microVM). Returns its sessionId.",
+            inputSchema: { template: z.string().optional(), cpu: z.number().optional(), memMb: z.number().optional() },
+            handler: async (a) => {
+                const sbx = await client.sandboxes.create({
+                    ...(a.template ? { template: a.template } : {}),
+                    ...(a.cpu ? { cpu: a.cpu } : {}),
+                    ...(a.memMb ? { memMb: a.memMb } : {}),
+                });
+                reg.sessions.set(sbx.sandboxId, { kind: "sandbox", handle: sbx });
+                return text({ sessionId: sbx.sandboxId });
+            },
+        },
+        solari_desktop_create: {
+            description: "Create a GUI desktop (microVM). Returns sessionId + streamUrl (noVNC).",
+            inputSchema: { template: z.string().optional(), resolution: z.string().optional() },
+            handler: async (a) => {
+                const d = await client.desktops.create({
+                    ...(a.template ? { template: a.template } : {}),
+                    ...(a.resolution ? { resolution: a.resolution } : {}),
+                });
+                reg.sessions.set(d.sessionId, { kind: "desktop", handle: d });
+                return text({ sessionId: d.sessionId, streamUrl: d.streamUrl });
+            },
+        },
+        solari_list: {
+            description: "List the org's sandboxes.",
+            inputSchema: {},
+            handler: async () => text(await client.sandboxes.list()),
+        },
+        solari_kill: {
+            description: "Destroy a session by id.",
+            inputSchema: { sessionId: z.string() },
+            handler: async (a) => {
+                const e = need(a.sessionId);
+                await e.handle.kill();
+                reg.sessions.delete(a.sessionId);
+                return text({ ok: true });
+            },
+        },
+        solari_exec: {
+            description: "Run a shell command in a session. Returns { stdout, stderr, exitCode }.",
+            inputSchema: { sessionId: z.string(), command: z.string() },
+            handler: async (a) => {
+                const e = await live(a.sessionId);
+                // Guest exec is no-shell (cmd = binary + argv); route through sh -c so
+                // pipes, $(), globs and quoting behave the way "shell command" implies.
+                return text(await e.handle.commands.run("sh", { args: ["-c", a.command] }));
+            },
+        },
+        solari_run_command_bg: {
+            description: "Start a shell command in the background (non-blocking). Returns its cmdId; the process keeps running after this call.",
+            inputSchema: { sessionId: z.string(), command: z.string() },
+            handler: async (a) => {
+                const e = await live(a.sessionId);
+                const h = await e.handle.commands.start("sh", { args: ["-c", a.command] });
+                return text({ cmdId: h.cmdId });
+            },
+        },
+        solari_get_preview_url: {
+            description: "Get a public preview URL for an in-guest port (e.g. a dev server on :3000). Returns { url, token? }.",
+            inputSchema: { sessionId: z.string(), port: z.number() },
+            handler: async (a) => {
+                const e = await live(a.sessionId);
+                return text(await e.handle.previewUrl(a.port));
+            },
+        },
+        solari_connect: {
+            description: "Re-attach to an existing session by id (across process restarts); auto-resumes it if paused. Registers it and returns { sessionId, kind }.",
+            inputSchema: { sessionId: z.string(), kind: z.enum(["sandbox", "desktop"]).optional() },
+            handler: async (a) => {
+                const id = a.sessionId;
+                const existing = reg.sessions.get(id);
+                const kind = a.kind ?? existing?.kind ?? "sandbox";
+                const handle = kind === "desktop"
+                    ? await client.desktops.connect(id)
+                    : await client.sandboxes.connect(id);
+                reg.sessions.set(id, { kind, handle });
+                return text({ sessionId: id, kind });
+            },
+        },
+        solari_run_code: {
+            description: "Run code (default Python) in a session's kernel. Returns results incl. structured charts.",
+            inputSchema: { sessionId: z.string(), code: z.string(), language: z.string().optional() },
+            handler: async (a) => {
+                const e = await live(a.sessionId);
+                return text(await e.handle.runCode(a.code, a.language ? { language: a.language } : {}));
+            },
+        },
+        solari_read_file: {
+            description: "Read an in-guest text file.",
+            inputSchema: { sessionId: z.string(), path: z.string() },
+            handler: async (a) => {
+                const e = await live(a.sessionId);
+                return text(await e.handle.files.readText(a.path));
+            },
+        },
+        solari_write_file: {
+            description: "Write a text file into the guest.",
+            inputSchema: { sessionId: z.string(), path: z.string(), content: z.string() },
+            handler: async (a) => {
+                const e = await live(a.sessionId);
+                await e.handle.files.write(a.path, a.content);
+                return text({ ok: true });
+            },
+        },
+        solari_list_files: {
+            description: "List a guest directory.",
+            inputSchema: { sessionId: z.string(), path: z.string() },
+            handler: async (a) => {
+                const e = await live(a.sessionId);
+                return text(await e.handle.files.list(a.path));
+            },
+        },
+        solari_screenshot: {
+            description: "Capture the desktop screen as a PNG image.",
+            inputSchema: { sessionId: z.string() },
+            handler: async (a) => {
+                const e = await desktop(a.sessionId);
+                const png = await e.handle.screenshot();
+                return { content: [{ type: "image", data: Buffer.from(png).toString("base64"), mimeType: "image/png" }] };
+            },
+        },
+        solari_click: {
+            description: "Click the desktop at (x, y).",
+            inputSchema: { sessionId: z.string(), x: z.number(), y: z.number() },
+            handler: async (a) => {
+                const e = await desktop(a.sessionId);
+                await e.handle.mouse.click(a.x, a.y);
+                return text({ ok: true });
+            },
+        },
+        solari_type: {
+            description: "Type text into the focused desktop element.",
+            inputSchema: { sessionId: z.string(), text: z.string() },
+            handler: async (a) => {
+                const e = await desktop(a.sessionId);
+                await e.handle.keyboard.type(a.text);
+                return text({ ok: true });
+            },
+        },
+        solari_key: {
+            description: "Press a key or chord (e.g. 'Return', 'ctrl+c') on the desktop.",
+            inputSchema: { sessionId: z.string(), key: z.string() },
+            handler: async (a) => {
+                const e = await desktop(a.sessionId);
+                await e.handle.keyboard.press(a.key);
+                return text({ ok: true });
+            },
+        },
+        solari_open_app: {
+            description: "Launch an application on the desktop. Returns its pid.",
+            inputSchema: { sessionId: z.string(), name: z.string() },
+            handler: async (a) => {
+                const e = await desktop(a.sessionId);
+                return text({ pid: await e.handle.open(a.name) });
+            },
+        },
+    };
+}
+export function registerToolset(server, toolset) {
+    for (const [name, t] of Object.entries(toolset)) {
+        server.registerTool(name, { description: t.description, inputSchema: t.inputSchema }, 
+        // The MCP SDK passes validated args; our handlers accept a record.
+        async (args) => t.handler(args));
+    }
+}
+export function buildServer(client, browserCfg) {
+    const apiKey = process.env.SOLARI_API_KEY ?? "";
+    const c = client ??
+        new SolariClient({
+            apiKey,
+            ...(process.env.SOLARI_BASE_URL ? { baseUrl: process.env.SOLARI_BASE_URL } : {}),
+        });
+    // The cloud-browser gateway is a separate service from the sandbox/desktop
+    // gateway (same domain in prod, different domains on staging).
+    const bCfg = browserCfg ?? {
+        apiKey,
+        baseUrl: process.env.SOLARI_BROWSER_URL ??
+            process.env.SOLARI_BASE_URL ??
+            "https://api.getsolari.com",
+    };
+    const server = new McpServer({ name: "solari-mcp", version: "0.2.0" });
+    const browserReg = { sessions: new Map() };
+    registerToolset(server, {
+        ...makeToolset(c, { sessions: new Map() }),
+        ...makeBrowserToolset(bCfg, browserReg),
+    });
+    return server;
+}
+export async function main() {
+    if (!process.env.SOLARI_API_KEY) {
+        console.error("solari-mcp: SOLARI_API_KEY is required");
+        process.exit(1);
+    }
+    const server = buildServer();
+    await server.connect(new StdioServerTransport());
+}
+// Run only when executed as the binary (not when imported by tests).
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+    main().catch((err) => {
+        console.error("solari-mcp fatal:", err);
+        process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@solarisdk/mcp",
+  "version": "0.2.0",
+  "description": "Model Context Protocol server for the Solari cloud browser, sandboxes + desktops — drive them from Claude Desktop/Cowork, Claude Code, Cursor, etc.",
+  "type": "module",
+  "bin": {
+    "solari-mcp": "./dist/cli.js"
+  },
+  "main": "./dist/server.js",
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "build:bundle": "esbuild src/cli.ts --bundle --platform=node --format=cjs --target=node18 --outfile=dist/solari-mcp.bundle.cjs --log-level=warning"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@solarisdk/sdk": "^0.1.2",
+    "puppeteer-core": "^24.43.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.28.1",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "solari",
+    "browser",
+    "sandbox",
+    "desktop",
+    "agent"
+  ]
+}