@geometra/mcp 1.63.2 → 1.65.0

package/README.md

@@ -18,14 +18,14 @@ Geometra proxy:       Chromium → DOM geometry → same WebSocket as native →
 
 Use Geometra MCP when an LLM needs to explore, interpret, and operate a real UI with compact semantic state instead of repeatedly consuming large browser snapshots. Keep Playwright-style tooling for deterministic scripts, DOM-oriented test automation, and compatibility fallback paths while Geometra closes remaining live-site gaps.
 
-Proxy-backed sessions stay warm by default on disconnect, and MCP now keeps a small warm pool so compatible headed, headless, and stealth workflows do not immediately evict each other.
+Proxy-backed browser sessions are isolated by default: each `pageUrl`/HTTP(S) connect gets a fresh Chromium that is destroyed on disconnect, and follow-up tools must use the returned `sessionId`. Pass `isolated: false` only when you intentionally want sequential warm-browser reuse, including shared cookies, localStorage, and page state. A browser prepared with `geometra_prepare_browser` is consumed only by a connect that explicitly opts into that warm pool.
 
 ## Tools
 
 | Tool | Description |
 |---|---|
 | `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy; pass `browserMode: "stock" | "cloakbrowser"` for explicit authorized testing modes; can inline `formSchema` and/or `pageModel`, or defer the page model for a faster first connect response |
-| `geometra_prepare_browser` | Pre-launch and pre-navigate a reusable proxy/browser for `pageUrl` without creating an active session; supports the same headed/headless/stealth browser settings as `geometra_connect` |
+| `geometra_prepare_browser` | Pre-launch and pre-navigate a reusable proxy/browser for `pageUrl` without creating an active session; the consuming connect must pass `isolated: false` explicitly |
 | `geometra_query` | Find elements by stable id, role, name, text content, prompt/section/item context, current value, or semantic state such as `invalid`, `required`, or `busy` |
 | `geometra_wait_for` | Wait for a semantic condition instead of guessing sleeps (`busy`, `disabled`, alerts, values, etc.). **Strict parameters** — use `text` plus `present: false` to wait until a substring disappears (e.g. “Parsing your resume”); there is no `textGone` field |
 | `geometra_wait_for_resume_parse` | Convenience wait until a parsing banner is gone (defaults: `text`: `"Parsing"`, `present` implied false). Same engine as `geometra_wait_for` |
@@ -221,12 +221,20 @@ To uninstall, remove the server entry from your client's MCP configuration.
 ### From source (this repo)
 
 ```bash
-cd mcp
 npm install
-npm run build
-claude mcp add geometra -- node ./dist/index.js
+npm run build -w @geometra/proxy
+npm run build -w @geometra/mcp
+claude mcp add geometra -- node "$(pwd)/mcp/dist/index.js"
 ```
 
+Install from the repository root so npm links `@geometra/mcp` and `@geometra/proxy` to the current checkout instead of placing an independent registry copy under `mcp/node_modules`.
+
+### Session state privacy
+
+Session lifecycle state is process-memory-only by default and does not create a state file. To opt into restart-persistent state, set `GEOMETRA_MCP_STATE_FILE` to a database path inside a private directory (mode `0700`). Geometra rejects symlinked or insecure state targets and keeps the database and SQLite sidecars at mode `0600`.
+
+Retained lifecycle and workflow state stores URL origins rather than paths or query strings, and redacts submitted field values, file paths, credentials, payloads, and raw error messages. Existing legacy state files are not migrated or deleted automatically.
+
 ## Usage
 
 ### Native Geometra server
@@ -250,6 +258,9 @@ python3 -m http.server 8080
 In another terminal (from repo root after `npm install` / `bun install` and `bun run build`):
 
 ```bash
+export GEOMETRA_PROXY_AUTH_TOKEN="replace-with-a-random-32-character-or-longer-token"
+# Required only if you want file-upload actions:
+export GEOMETRA_PROXY_FILE_ROOTS="/absolute/path/to/approved-files"
 npx geometra-proxy http://localhost:8080 --port 3200
 # Requires Chromium: npx playwright install chromium
 # Optional authorized stealth-testing prefetch: npx cloakbrowser install
@@ -259,7 +270,18 @@ npx geometra-proxy http://localhost:8080 --port 3200
 
 For blocked/challenge pages, keep `blockDetection: true` (default). Set `blockedSitePolicy` to `"continue"` (default), `"manual-handoff"` to return retry guidance for a visible user handoff, or `"error"` to stop immediately with structured `blockedSite` details.
 
-Point MCP at `ws://127.0.0.1:3200` instead of a native Geometra server. The proxy translates clicks and keyboard messages into Playwright actions and streams updated geometry.
+Point MCP at the authenticated loopback socket instead of a native Geometra server:
+
+```text
+geometra_connect({
+  url: "ws://127.0.0.1:3200",
+  authToken: "<GEOMETRA_PROXY_AUTH_TOKEN>"
+})
+```
+
+When MCP starts the proxy from `pageUrl`, it generates and carries the token
+privately, so no auth parameter is needed. The proxy translates clicks and
+keyboard messages into Playwright actions and streams updated geometry.
 
 Then in Claude Code (either backend):
 
@@ -302,7 +324,7 @@ No screenshots and no vision model in the loop. JSON in, JSON out.
 With `python3 -m http.server 8080` in `demos/proxy-mcp-sample` and `npx geometra-proxy http://localhost:8080 --port 3200` running:
 
 ```
-Agent:  geometra_connect({ url: "ws://127.0.0.1:3200" })
+Agent:  geometra_connect({ url: "ws://127.0.0.1:3200", authToken: "<configured token>" })
         → Connected. UI includes textbox "Email", button "Save", …
 
 Agent:  geometra_form_schema({})

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from './server.js';
-import { disconnect, listSessions } from './session.js';
+import { shutdownAllSessionsAndProxies } from './session.js';
 import { shutdownSessionLifecycleRegistry } from './session-state.js';
 let cleanedUp = false;
 function cleanupActiveSession() {
@@ -9,10 +9,7 @@ function cleanupActiveSession() {
         return;
     cleanedUp = true;
     try {
-        for (const session of listSessions()) {
-            disconnect({ sessionId: session.id, closeProxy: false });
-        }
-        disconnect({ closeProxy: true });
+        shutdownAllSessionsAndProxies();
     }
     catch {
         /* ignore */

package/dist/proxy-spawn.d.ts

@@ -1,6 +1,7 @@
 import { type ChildProcess } from 'node:child_process';
 export interface EmbeddedProxyRuntime {
     wsUrl: string;
+    authToken: string;
     ready: Promise<void>;
     getTrace?: () => Record<string, unknown>;
     closed: boolean;
@@ -33,6 +34,24 @@ export interface SpawnProxyParams {
     eagerInitialExtract?: boolean;
     proxy?: SpawnProxyConfig;
 }
+export interface RuntimeDrainOptions {
+    /** Override the environment-derived debug decision, primarily for embedders and tests. */
+    debug?: boolean;
+    /** Receive already-prefixed proxy stderr chunks when debug forwarding is enabled. */
+    forwardStderr?: (text: string) => void;
+}
+export interface SpawnedProxyReadyOptions {
+    /** Override the production ready deadline, primarily for focused process tests. */
+    readyTimeoutMs?: number;
+    /** Override post-ready output handling, primarily for embedders and tests. */
+    runtimeDrains?: RuntimeDrainOptions;
+}
+/**
+ * Consume a spawned proxy's output after its ready signal so full stdio pipes
+ * cannot block the child. Runtime logs remain quiet unless debug forwarding is
+ * explicitly enabled.
+ */
+export declare function attachRuntimeDrains(child: Pick<ChildProcess, 'stdout' | 'stderr'>, options?: RuntimeDrainOptions): void;
 export declare function resolveStealthMode(stealth?: boolean): boolean;
 export declare function startEmbeddedGeometraProxy(opts: SpawnProxyParams): Promise<{
     runtime: EmbeddedProxyRuntime;
@@ -48,4 +67,14 @@ export declare function formatProxyStartupFailure(message: string, opts: SpawnPr
 export declare function spawnGeometraProxy(opts: SpawnProxyParams): Promise<{
     child: ChildProcess;
     wsUrl: string;
+    authToken: string;
+}>;
+/**
+ * Wait for a spawned proxy's structured ready signal, then hand both output
+ * pipes to their lifetime drains before returning the child to its caller.
+ */
+export declare function waitForSpawnedProxyReady(child: ChildProcess, opts: SpawnProxyParams, authToken: string, options?: SpawnedProxyReadyOptions): Promise<{
+    child: ChildProcess;
+    wsUrl: string;
+    authToken: string;
 }>;

package/dist/proxy-spawn.js

@@ -1,4 +1,5 @@
 import { spawn, spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
 import { existsSync, realpathSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
@@ -126,6 +127,24 @@ function buildLocalProxyDistIfPossible(packageDir, entryFile, errors) {
     }
     return undefined;
 }
+/**
+ * Consume a spawned proxy's output after its ready signal so full stdio pipes
+ * cannot block the child. Runtime logs remain quiet unless debug forwarding is
+ * explicitly enabled.
+ */
+export function attachRuntimeDrains(child, options = {}) {
+    child.stdout?.resume();
+    const debug = options.debug ?? process.env.GEOMETRA_PROXY_DEBUG === '1';
+    if (!debug) {
+        child.stderr?.resume();
+        return;
+    }
+    const forwardStderr = options.forwardStderr ?? ((text) => { process.stderr.write(text); });
+    child.stderr?.on('data', chunk => {
+        const text = chunk.toString();
+        forwardStderr(/^\[geometra-proxy\](?:\s|$)/.test(text) ? text : `[geometra-proxy] ${text}`);
+    });
+}
 export function resolveStealthMode(stealth) {
     if (stealth !== undefined)
         return stealth;
@@ -165,6 +184,10 @@ export async function startEmbeddedGeometraProxy(opts) {
         eagerInitialExtract: opts.eagerInitialExtract,
         ...(opts.proxy && { proxy: opts.proxy }),
     });
+    if (typeof runtime.authToken !== 'string' || runtime.authToken.length < 32) {
+        await runtime.close().catch(() => { });
+        throw new Error(`Resolved ${runtimePath}, but that proxy runtime does not implement authenticated controller capabilities. Rebuild or update @geometra/proxy.`);
+    }
     return { runtime, wsUrl: runtime.wsUrl };
 }
 export function parseProxyReadySignalLine(line, options) {
@@ -209,6 +232,7 @@ export function formatProxyStartupFailure(message, opts) {
  */
 export function spawnGeometraProxy(opts) {
     const script = resolveProxyScriptPath();
+    const authToken = randomBytes(32).toString('base64url');
     const args = [script, opts.pageUrl, '--port', String(opts.port)];
     if (opts.width != null && opts.width > 0)
         args.push('--width', String(opts.width));
@@ -226,27 +250,34 @@ export function spawnGeometraProxy(opts) {
         args.push('--no-stealth');
     if (opts.eagerInitialExtract === false)
         args.push('--lazy-initial-extract');
-    if (opts.proxy?.server) {
-        args.push('--proxy-server', opts.proxy.server);
-        if (opts.proxy.username !== undefined)
-            args.push('--proxy-username', opts.proxy.username);
-        if (opts.proxy.password !== undefined)
-            args.push('--proxy-password', opts.proxy.password);
-        if (opts.proxy.bypass !== undefined)
-            args.push('--proxy-bypass', opts.proxy.bypass);
-    }
+    const childEnv = {
+        ...process.env,
+        GEOMETRA_PROXY_READY_JSON: '1',
+        GEOMETRA_PROXY_AUTH_TOKEN: authToken,
+        ...(opts.proxy?.server !== undefined ? { GEOMETRA_PROXY_SERVER: opts.proxy.server } : {}),
+        ...(opts.proxy?.username !== undefined ? { GEOMETRA_PROXY_USERNAME: opts.proxy.username } : {}),
+        ...(opts.proxy?.password !== undefined ? { GEOMETRA_PROXY_PASSWORD: opts.proxy.password } : {}),
+        ...(opts.proxy?.bypass !== undefined ? { GEOMETRA_PROXY_BYPASS: opts.proxy.bypass } : {}),
+    };
+    const child = spawn(process.execPath, args, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: childEnv,
+    });
+    return waitForSpawnedProxyReady(child, opts, authToken);
+}
+/**
+ * Wait for a spawned proxy's structured ready signal, then hand both output
+ * pipes to their lifetime drains before returning the child to its caller.
+ */
+export function waitForSpawnedProxyReady(child, opts, authToken, options = {}) {
     return new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, args, {
-            stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GEOMETRA_PROXY_READY_JSON: '1' },
-        });
         let settled = false;
         let stdoutBuf = '';
         let stderrBuf = '';
         const cleanup = () => {
             clearTimeout(deadline);
-            child.stdout?.removeAllListeners('data');
-            child.stderr?.removeAllListeners('data');
+            child.stdout?.off('data', consumeStdout);
+            child.stderr?.off('data', consumeStderr);
         };
         const tryResolveReady = (line) => {
             const wsUrl = parseProxyReadySignalLine(line, { allowLegacy: false });
@@ -254,7 +285,8 @@ export function spawnGeometraProxy(opts) {
                 return false;
             settled = true;
             cleanup();
-            resolve({ child, wsUrl });
+            attachRuntimeDrains(child, options.runtimeDrains);
+            resolve({ child, wsUrl, authToken });
             return true;
         };
         const consumeStdout = (chunk) => {
@@ -282,7 +314,7 @@ export function spawnGeometraProxy(opts) {
                 cleanup();
                 reject(new Error(formatProxyStartupFailure('geometra-proxy did not emit a ready signal within 45s', opts)));
             }
-        }, READY_TIMEOUT_MS);
+        }, options.readyTimeoutMs ?? READY_TIMEOUT_MS);
         child.stdout?.on('data', consumeStdout);
         child.stderr?.on('data', consumeStderr);
         child.on('error', err => {