@geometra/mcp 1.58.0 → 1.59.0

package/dist/proxy-spawn.d.ts

@@ -11,6 +11,19 @@ export declare function resolveProxyScriptPath(): string;
 export declare function resolveProxyScriptPathWith(customRequire: NodeRequire, moduleDir?: string): string;
 export declare function resolveProxyRuntimePath(): string;
 export declare function resolveProxyRuntimePathWith(customRequire: NodeRequire, moduleDir?: string): string;
+/**
+ * BYO outbound proxy for the spawned Chromium. JobForge sets this when the
+ * user configures a residential / mobile / SOCKS proxy in `profile.yml` to
+ * bypass datacenter-IP fingerprinting on apply portals (Ashby class B,
+ * Lever Mapbox geocoder, Cloudflare Bot Management, etc.). Geometra is the
+ * wire — the user supplies the proxy.
+ */
+export interface SpawnProxyConfig {
+    server: string;
+    username?: string;
+    password?: string;
+    bypass?: string;
+}
 export interface SpawnProxyParams {
     pageUrl: string;
     port: number;
@@ -19,6 +32,7 @@ export interface SpawnProxyParams {
     height?: number;
     slowMo?: number;
     eagerInitialExtract?: boolean;
+    proxy?: SpawnProxyConfig;
 }
 export declare function startEmbeddedGeometraProxy(opts: SpawnProxyParams): Promise<{
     runtime: EmbeddedProxyRuntime;

package/dist/proxy-spawn.js

@@ -139,6 +139,7 @@ export async function startEmbeddedGeometraProxy(opts) {
         headed: opts.headless !== true,
         slowMo: opts.slowMo,
         eagerInitialExtract: opts.eagerInitialExtract,
+        ...(opts.proxy && { proxy: opts.proxy }),
     });
     return { runtime, wsUrl: runtime.wsUrl };
 }
@@ -192,6 +193,15 @@ export function spawnGeometraProxy(opts) {
         args.push('--headed');
     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);
+    }
     return new Promise((resolve, reject) => {
         const child = spawn(process.execPath, args, {
             stdio: ['ignore', 'pipe', 'pipe'],

package/dist/server.js

@@ -376,6 +376,20 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             .optional()
             .default(false)
             .describe('When true, bypass the reusable proxy pool and spawn a brand-new Chromium for this session that is destroyed on disconnect. Required for safe parallel form submission — without this, two parallel sessions can land on the same pooled proxy and contaminate each other. Default false (use the pool for speed).'),
+        proxy: z
+            .object({
+            server: z
+                .string()
+                .describe('Proxy URL (http://host:port, https://host:port, or socks5://host:port).'),
+            username: z.string().optional().describe('Proxy auth username.'),
+            password: z.string().optional().describe('Proxy auth password.'),
+            bypass: z
+                .string()
+                .optional()
+                .describe('Comma-separated host patterns to bypass (e.g. "*.internal,localhost").'),
+        })
+            .optional()
+            .describe('BYO outbound proxy for the spawned Chromium. Routes all browser traffic through the supplied residential / mobile / SOCKS proxy — useful for apply portals (Ashby, Lever, Cloudflare-fronted ATSes) that fingerprint datacenter IPs and flag headless sessions as bots. The reusable proxy pool is partitioned by proxy identity so callers with different proxy configs never share a Chromium instance.'),
         returnForms: z
             .boolean()
             .optional()
@@ -431,6 +445,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
                     height: input.height,
                     slowMo: input.slowMo,
                     isolated: input.isolated,
+                    proxy: input.proxy,
                     awaitInitialFrame: deferInlinePageModel ? false : undefined,
                     eagerInitialExtract: deferInlinePageModel ? true : undefined,
                 });
@@ -501,9 +516,23 @@ Use this when you can prepare ahead of the user-facing task so the next \`geomet
             .nonnegative()
             .optional()
             .describe('Playwright slowMo (ms) for the warmed browser.'),
-    }, async ({ pageUrl, port, headless, width, height, slowMo }) => {
+        proxy: z
+            .object({
+            server: z
+                .string()
+                .describe('Proxy URL (http://host:port, https://host:port, or socks5://host:port).'),
+            username: z.string().optional().describe('Proxy auth username.'),
+            password: z.string().optional().describe('Proxy auth password.'),
+            bypass: z
+                .string()
+                .optional()
+                .describe('Comma-separated host patterns to bypass.'),
+        })
+            .optional()
+            .describe('BYO outbound proxy for the warmed Chromium. The pool entry is partitioned by proxy identity, so a later geometra_connect with the same proxy config will reuse this warmed browser; a different proxy config (or no proxy) will not.'),
+    }, async ({ pageUrl, port, headless, width, height, slowMo, proxy }) => {
         try {
-            const prepared = await prewarmProxy({ pageUrl, port, headless, width, height, slowMo });
+            const prepared = await prewarmProxy({ pageUrl, port, headless, width, height, slowMo, proxy });
             return ok(JSON.stringify(prepared));
         }
         catch (e) {

package/dist/session.d.ts

@@ -1,6 +1,6 @@
 import type { ChildProcess } from 'node:child_process';
 import WebSocket from 'ws';
-import { type EmbeddedProxyRuntime } from './proxy-spawn.js';
+import { type EmbeddedProxyRuntime, type SpawnProxyConfig } from './proxy-spawn.js';
 /**
  * Parsed accessibility node from the UI tree + computed layout.
  * Mirrors the shape of @geometra/core's AccessibilityNode without importing it
@@ -492,6 +492,7 @@ export declare function prewarmProxy(options: {
     width?: number;
     height?: number;
     slowMo?: number;
+    proxy?: SpawnProxyConfig;
 }): Promise<{
     prepared: true;
     reused: boolean;
@@ -535,6 +536,13 @@ export declare function connectThroughProxy(options: {
      * leak into another. Default false preserves the existing pool behavior.
      */
     isolated?: boolean;
+    /**
+     * BYO outbound proxy for the Chromium. Routes all browser traffic through
+     * the supplied residential / mobile / SOCKS proxy. The reusable pool is
+     * partitioned by proxy identity so two callers with different proxy
+     * configs never share a Chromium instance.
+     */
+    proxy?: SpawnProxyConfig;
 }): Promise<Session>;
 export declare function getSession(id?: string): Session | null;
 export declare function pruneDisconnectedSessions(): string[];

package/dist/session.js

@@ -3,6 +3,19 @@ import { performance } from 'node:perf_hooks';
 import WebSocket from 'ws';
 import { spawnGeometraProxy, startEmbeddedGeometraProxy } from './proxy-spawn.js';
 import { completeSessionLifecycle, failSessionLifecycle, heartbeatSessionLifecycle, initializeSessionLifecycle, recordSessionSnapshot, } from './session-state.js';
+/**
+ * Stable identity for an outbound proxy config, used as the reusable-pool
+ * partition key. Two sessions with different proxy configs MUST NOT share a
+ * pooled Chromium — otherwise the first apply's IP leaks into subsequent
+ * applies even when the caller opted into a fresh proxy. Password is
+ * excluded from the key to keep logs safe; `server + username + bypass` is
+ * enough to distinguish every realistic multi-tenant config.
+ */
+function proxyKeyFor(proxy) {
+    if (!proxy?.server)
+        return '';
+    return `${proxy.server}|${proxy.username ?? ''}|${proxy.bypass ?? ''}`;
+}
 const activeSessions = new Map();
 let defaultSessionId = null;
 const MAX_ACTIVE_SESSIONS = 5;
@@ -129,6 +142,7 @@ function enforceReusableProxyPoolLimit() {
 function setReusableProxy(proxy, wsUrl, opts) {
     clearReusableProxiesIfExited();
     const now = Date.now();
+    const proxyKey = proxyKeyFor(opts.proxy);
     const existing = reusableProxies.find(entry => sameReusableProxyEntry(entry, proxy));
     if (existing) {
         existing.wsUrl = wsUrl;
@@ -137,6 +151,7 @@ function setReusableProxy(proxy, wsUrl, opts) {
         existing.width = opts.width ?? 1280;
         existing.height = opts.height ?? 720;
         existing.pageUrl = opts.pageUrl;
+        existing.proxyKey = proxyKey;
         existing.snapshotReady = opts.snapshotReady ?? existing.snapshotReady;
         existing.lastUsedAt = now;
         return;
@@ -151,6 +166,7 @@ function setReusableProxy(proxy, wsUrl, opts) {
             width: opts.width ?? 1280,
             height: opts.height ?? 720,
             pageUrl: opts.pageUrl,
+            proxyKey,
             snapshotReady: opts.snapshotReady === true,
             lastUsedAt: now,
         };
@@ -176,6 +192,7 @@ function setReusableProxy(proxy, wsUrl, opts) {
         width: opts.width ?? 1280,
         height: opts.height ?? 720,
         pageUrl: opts.pageUrl,
+        proxyKey,
         snapshotReady: opts.snapshotReady === true,
         lastUsedAt: now,
     });
@@ -390,7 +407,8 @@ function reusableProxyMatchesOptions(entry, options) {
         entry.headless === (options.headless === true) &&
         entry.slowMo === (options.slowMo ?? 0) &&
         entry.width === (options.width ?? 1280) &&
-        entry.height === (options.height ?? 720));
+        entry.height === (options.height ?? 720) &&
+        entry.proxyKey === proxyKeyFor(options.proxy));
 }
 function findExactReusableProxy(options) {
     clearReusableProxiesIfExited();
@@ -407,8 +425,14 @@ function findReusableProxy(options) {
     const desiredSlowMo = options.slowMo ?? 0;
     const desiredWidth = options.width ?? 1280;
     const desiredHeight = options.height ?? 720;
+    const desiredProxyKey = proxyKeyFor(options.proxy);
     return reusableProxies
-        .filter(entry => entry.headless === desiredHeadless && entry.slowMo === desiredSlowMo)
+        .filter(entry => entry.headless === desiredHeadless
+        && entry.slowMo === desiredSlowMo
+        // Proxy partition is hard — a session with residential proxy MUST NOT
+        // attach to a pooled direct-connection Chromium (and vice versa).
+        // Different proxy credentials also get separate pool entries.
+        && entry.proxyKey === desiredProxyKey)
         .sort((a, b) => {
         const score = (entry) => {
             let value = 0;
@@ -448,6 +472,7 @@ export async function prewarmProxy(options) {
             width: options.width,
             height: options.height,
             slowMo: options.slowMo,
+            proxy: options.proxy,
         });
         try {
             await runtime.ready;
@@ -463,6 +488,7 @@ export async function prewarmProxy(options) {
             height: options.height,
             pageUrl: options.pageUrl,
             snapshotReady: true,
+            proxy: options.proxy,
         });
         return {
             prepared: true,
@@ -486,6 +512,7 @@ export async function prewarmProxy(options) {
             width: options.width,
             height: options.height,
             slowMo: options.slowMo,
+            proxy: options.proxy,
         });
         setReusableProxy({ child }, wsUrl, {
             headless: options.headless,
@@ -493,6 +520,7 @@ export async function prewarmProxy(options) {
             width: options.width,
             height: options.height,
             pageUrl: options.pageUrl,
+            proxy: options.proxy,
         });
         return {
             prepared: true,
@@ -594,6 +622,7 @@ async function startFreshProxySession(options) {
             height: options.height,
             slowMo: options.slowMo,
             eagerInitialExtract,
+            proxy: options.proxy,
         });
         pendingEmbeddedRuntime = runtime;
         const proxyStartMs = performance.now() - proxyStartStartedAt;
@@ -624,6 +653,7 @@ async function startFreshProxySession(options) {
                 height: options.height,
                 pageUrl: options.pageUrl,
                 snapshotReady: Boolean(session.tree && session.layout),
+                proxy: options.proxy,
             });
         }
         const baseConnectTrace = session.connectTrace;
@@ -667,6 +697,7 @@ async function startFreshProxySession(options) {
             height: options.height,
             slowMo: options.slowMo,
             eagerInitialExtract,
+            proxy: options.proxy,
         });
         const proxyStartMs = performance.now() - proxyStartStartedAt;
         try {
@@ -691,6 +722,7 @@ async function startFreshProxySession(options) {
                     height: options.height,
                     pageUrl: options.pageUrl,
                     snapshotReady: Boolean(session.tree && session.layout),
+                    proxy: options.proxy,
                 });
             }
             const baseConnectTrace = session.connectTrace;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/mcp",
-  "version": "1.58.0",
+  "version": "1.59.0",
   "description": "MCP server for Geometra — interact with running Geometra apps via the geometry protocol, no browser needed",
   "license": "MIT",
   "type": "module",