@solarisdk/mcp 0.2.0 → 0.2.1

package/README.md

@@ -15,7 +15,48 @@ agents (Claude Desktop **incl. Cowork**, Claude Code, Cursor, Windsurf, …) use
 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)
+## Use it — hosted connector (no install)
+
+Point any MCP client at the hosted Streamable HTTP endpoint with your API key:
+
+- **Prod:** `https://mcp.getsolari.com/mcp`
+- **Staging:** `https://mcp-sta.solaribrowser.com/mcp`
+
+Claude Desktop / claude.ai: **Settings → Connectors → Add custom connector**,
+URL as above, and send `Authorization: Bearer slr_live_…`. Or in
+`claude_desktop_config.json` / Claude Code:
+
+```jsonc
+{
+  "mcpServers": {
+    "solari": {
+      "type": "http",
+      "url": "https://mcp.getsolari.com/mcp",
+      "headers": { "Authorization": "Bearer slr_live_…" }
+    }
+  }
+}
+```
+
+Each MCP session is bound to the API key that initialized it; sessions idle
+longer than 30 min are evicted server-side (your cloud sessions keep their own
+lifecycles — re-attach with `solari_connect`).
+
+## Use it — local stdio (Claude Desktop / Cowork / Cursor / Windsurf)
+
+```jsonc
+{
+  "mcpServers": {
+    "solari": {
+      "command": "npx",
+      "args": ["-y", "@solarisdk/mcp"],
+      "env": { "SOLARI_API_KEY": "slr_live_…" }
+    }
+  }
+}
+```
+
+## Use it — single-file bundle (no npm)
 
 ```jsonc
 // claude_desktop_config.json (Claude Desktop: Developer → Edit Config)

package/dist/browser.js

@@ -258,7 +258,14 @@ export function makeBrowserToolset(cfg, reg, deps = defaultDeps) {
                     }
                     reg.sessions.delete(id);
                 }
-                const res = await api(cfg, "DELETE", `/sessions/${encodeURIComponent(id)}`);
+                // Gateway bearer verification can transiently 401 (control-plane
+                // verify blip / auth-cache churn); a failed release leaks the pool
+                // slot until TTL, so retry once before surfacing the error.
+                let res = await api(cfg, "DELETE", `/sessions/${encodeURIComponent(id)}`);
+                if (res.status === 401) {
+                    await new Promise((r) => setTimeout(r, 1500));
+                    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;

package/dist/http.d.ts

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

package/dist/http.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// solari-mcp over Streamable HTTP — the hosted, multi-tenant variant.
+//
+// One deployment serves every customer: each MCP session is bound to the
+// slr_live_ API key presented in the Authorization header at initialize time,
+// and gets its own McpServer + tool registries. Subsequent requests are routed
+// by the mcp-session-id header and must present the same key (sessions are a
+// tenant boundary, not just a transport detail).
+//
+//   PORT                 listen port (default 8080)
+//   SOLARI_BASE_URL      sandbox/desktop gateway (default https://api.getsolari.com)
+//   SOLARI_BROWSER_URL   browser gateway (default = SOLARI_BASE_URL)
+//   SESSION_IDLE_MS      evict MCP sessions idle longer than this (default 30 min)
+import { createServer } from "node:http";
+import { createHash, randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { buildServerParts } from "./server.js";
+const PORT = Number(process.env.PORT ?? 8080);
+const IDLE_MS = Number(process.env.SESSION_IDLE_MS ?? 30 * 60 * 1000);
+const BROWSER_URL = process.env.SOLARI_BROWSER_URL ?? process.env.SOLARI_BASE_URL ?? "https://api.getsolari.com";
+const sessions = new Map();
+const hash = (key) => createHash("sha256").update(key).digest("hex");
+// Cheap upfront key validation (the gateways are the real authority; this just
+// gives a clean 401 at connect time instead of failures on the first tool
+// call). Positive results cached briefly to absorb client reconnect storms.
+const keyOkUntil = new Map();
+async function validateKey(key) {
+    const h = hash(key);
+    const until = keyOkUntil.get(h);
+    if (until && until > Date.now())
+        return true;
+    try {
+        const res = await fetch(`${BROWSER_URL}/profiles`, {
+            headers: { authorization: `Bearer ${key}` },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (res.ok) {
+            keyOkUntil.set(h, Date.now() + 60_000);
+            return true;
+        }
+        // Gateway auth can negative-cache a freshly minted key for a few seconds;
+        // treat only a definitive 401/403 as invalid.
+        return res.status !== 401 && res.status !== 403;
+    }
+    catch {
+        return true; // don't lock customers out on our own transient errors
+    }
+}
+function bearer(req) {
+    const m = /^Bearer\s+(.+)$/i.exec(req.headers.authorization ?? "");
+    return m?.[1];
+}
+function json(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(c);
+    const raw = Buffer.concat(chunks).toString("utf8");
+    if (!raw)
+        return undefined;
+    return JSON.parse(raw);
+}
+async function evict(id, why) {
+    const s = sessions.get(id);
+    if (!s)
+        return;
+    sessions.delete(id);
+    // Disconnect any live puppeteer handles (the cloud sessions themselves are
+    // governed by their own idle/pause TTLs — we only drop our sockets).
+    for (const e of s.browserReg.sessions.values()) {
+        try {
+            await e.browser.disconnect();
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    try {
+        await s.transport.close();
+    }
+    catch {
+        /* already closed */
+    }
+    console.error(`mcp session ${id} evicted (${why})`);
+}
+setInterval(() => {
+    const now = Date.now();
+    for (const [id, s] of sessions)
+        if (now - s.lastSeen > IDLE_MS)
+            void evict(id, "idle");
+}, 60_000).unref();
+async function handleMcp(req, res) {
+    const key = bearer(req);
+    if (!key || !key.startsWith("slr_live_")) {
+        json(res, 401, { error: "Authorization: Bearer slr_live_… required" });
+        return;
+    }
+    const sid = req.headers["mcp-session-id"];
+    if (sid) {
+        const s = sessions.get(sid);
+        if (!s) {
+            json(res, 404, { error: "unknown mcp-session-id (session may have been evicted)" });
+            return;
+        }
+        if (s.keyHash !== hash(key)) {
+            json(res, 403, { error: "mcp-session-id belongs to a different API key" });
+            return;
+        }
+        s.lastSeen = Date.now();
+        const body = req.method === "POST" ? await readBody(req) : undefined;
+        await s.transport.handleRequest(req, res, body);
+        return;
+    }
+    // No session id → must be a POST initialize.
+    if (req.method !== "POST") {
+        json(res, 400, { error: "mcp-session-id header required" });
+        return;
+    }
+    if (!(await validateKey(key))) {
+        json(res, 401, { error: "invalid Solari API key" });
+        return;
+    }
+    const body = await readBody(req);
+    const { server, browserReg } = buildServerParts(undefined, {
+        apiKey: key,
+        baseUrl: BROWSER_URL,
+    });
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: randomUUID,
+        onsessioninitialized: (id) => {
+            sessions.set(id, { transport, browserReg, keyHash: hash(key), lastSeen: Date.now() });
+            console.error(`mcp session ${id} started (key …${key.slice(-4)})`);
+        },
+        onsessionclosed: (id) => void evict(id, "client closed"),
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, body);
+}
+const httpServer = createServer((req, res) => {
+    const url = req.url?.split("?")[0];
+    if (url === "/health" || url === "/healthz") {
+        json(res, 200, { ok: true, sessions: sessions.size });
+        return;
+    }
+    if (url === "/mcp") {
+        handleMcp(req, res).catch((err) => {
+            console.error("mcp request failed:", err);
+            if (!res.headersSent)
+                json(res, 500, { error: "internal error" });
+            else
+                res.end();
+        });
+        return;
+    }
+    json(res, 404, { error: "not found (use /mcp)" });
+});
+httpServer.listen(PORT, () => {
+    console.error(`solari-mcp http listening on :${PORT} (browser gw ${BROWSER_URL}, ` +
+        `desktop gw ${process.env.SOLARI_BASE_URL ?? "https://api.getsolari.com"})`);
+});

package/dist/server.d.ts

@@ -2,7 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type ZodTypeAny } from "zod";
 import { SolariClient } from "@solarisdk/sdk";
-import { type BrowserConfig } from "./browser.js";
+import { type BrowserConfig, type BrowserRegistry } from "./browser.js";
 type Kind = "sandbox" | "desktop";
 interface Entry {
     kind: Kind;
@@ -29,6 +29,11 @@ export interface Tool {
 }
 export declare function makeToolset(client: SolariClient, reg: Registry): Record<string, Tool>;
 export declare function registerToolset(server: McpServer, toolset: Record<string, Tool>): void;
+export interface ServerParts {
+    server: McpServer;
+    browserReg: BrowserRegistry;
+}
+export declare function buildServerParts(client?: SolariClient, browserCfg?: BrowserConfig): ServerParts;
 export declare function buildServer(client?: SolariClient, browserCfg?: BrowserConfig): McpServer;
 export declare function main(): Promise<void>;
 export {};

package/dist/server.js

@@ -203,8 +203,8 @@ export function registerToolset(server, toolset) {
         async (args) => t.handler(args));
     }
 }
-export function buildServer(client, browserCfg) {
-    const apiKey = process.env.SOLARI_API_KEY ?? "";
+export function buildServerParts(client, browserCfg) {
+    const apiKey = browserCfg?.apiKey ?? process.env.SOLARI_API_KEY ?? "";
     const c = client ??
         new SolariClient({
             apiKey,
@@ -224,7 +224,10 @@ export function buildServer(client, browserCfg) {
         ...makeToolset(c, { sessions: new Map() }),
         ...makeBrowserToolset(bCfg, browserReg),
     });
-    return server;
+    return { server, browserReg };
+}
+export function buildServer(client, browserCfg) {
+    return buildServerParts(client, browserCfg).server;
 }
 export async function main() {
     if (!process.env.SOLARI_API_KEY) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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": {