@geometra/mcp 1.19.0 → 1.19.1

package/README.md

@@ -1,6 +1,6 @@
 # @geometra/mcp
 
-MCP server for [Geometra](https://github.com/razroo/geometra) — interact with running Geometra apps via the geometry protocol over WebSocket. For **native** Geometra apps there is no browser in the loop. For **any existing website**, use **`geometra_connect` with `pageUrl`** — the MCP server starts [`@geometra/proxy`](../packages/proxy/README.md) for you (bundled dependency) so you do not need a separate terminal or a `ws://` URL. You can still pass `url: "ws://…"` if a proxy is already running.
+MCP server for [Geometra](https://github.com/razroo/geometra) — interact with running Geometra apps via the geometry protocol over WebSocket. For **native** Geometra apps there is no browser in the loop. For **any existing website**, use **`geometra_connect` with `pageUrl`** — the MCP server starts [`@geometra/proxy`](../packages/proxy/README.md) for you (bundled dependency) so you do not need a separate terminal or a `ws://` URL. You can still pass `url: "ws://…"` if a proxy is already running, and if you accidentally pass `https://…` in `url`, MCP will treat it as `pageUrl` and auto-start the proxy.
 
 See [`AGENT_MODEL.md`](./AGENT_MODEL.md) for the MCP mental model, why token usage can be lower than large browser snapshots, and how headed vs headless proxy mode works.
 
@@ -18,7 +18,7 @@ Geometra proxy:       Chromium → DOM geometry → same WebSocket as native →
 
 | Tool | Description |
 |---|---|
-| `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy |
+| `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy; `url: "https://…"` is auto-coerced onto the proxy path |
 | `geometra_query` | Find elements by stable id, role, name, or text content |
 | `geometra_page_model` | Summary-first webpage model: archetypes, stable section ids, counts, top-level sections, primary actions |
 | `geometra_expand_section` | Expand one form/dialog/list/landmark from `geometra_page_model` on demand |
@@ -76,6 +76,8 @@ npm run server  # starts on ws://localhost:3100
 
 ### Any web app (Geometra proxy)
 
+**Preferred path for agents:** call `geometra_connect({ pageUrl: "https://…" })` and let MCP spawn the proxy for you on an ephemeral local port. The manual CLI below is still useful for debugging or when you want to inspect the proxy directly.
+
 In one terminal, serve or open a page (example uses the repo sample):
 
 ```bash

package/dist/__tests__/connect-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/connect-utils.test.js

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import { formatConnectFailureMessage, normalizeConnectTarget } from '../connect-utils.js';
+import { formatProxyStartupFailure, parseProxyReadySignalLine } from '../proxy-spawn.js';
+describe('normalizeConnectTarget', () => {
+    it('accepts explicit pageUrl for http(s) pages', () => {
+        const result = normalizeConnectTarget({ pageUrl: 'https://example.com/jobs/123' });
+        expect(result).toEqual({
+            ok: true,
+            value: {
+                kind: 'proxy',
+                pageUrl: 'https://example.com/jobs/123',
+                autoCoercedFromUrl: false,
+            },
+        });
+    });
+    it('rejects non-http pageUrl protocols', () => {
+        const result = normalizeConnectTarget({ pageUrl: 'ws://127.0.0.1:3100' });
+        expect(result).toEqual({
+            ok: false,
+            error: 'pageUrl must use http:// or https:// (received ws:)',
+        });
+    });
+    it('auto-coerces http url input onto the proxy path', () => {
+        const result = normalizeConnectTarget({ url: 'https://jobs.example.com/apply' });
+        expect(result).toEqual({
+            ok: true,
+            value: {
+                kind: 'proxy',
+                pageUrl: 'https://jobs.example.com/apply',
+                autoCoercedFromUrl: true,
+            },
+        });
+    });
+    it('accepts ws url input for already-running peers', () => {
+        const result = normalizeConnectTarget({ url: 'ws://127.0.0.1:3100' });
+        expect(result).toEqual({
+            ok: true,
+            value: {
+                kind: 'ws',
+                wsUrl: 'ws://127.0.0.1:3100/',
+                autoCoercedFromUrl: false,
+            },
+        });
+    });
+    it('rejects ambiguous and empty connect inputs', () => {
+        expect(normalizeConnectTarget({})).toEqual({
+            ok: false,
+            error: 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).',
+        });
+        expect(normalizeConnectTarget({ url: 'ws://127.0.0.1:3100', pageUrl: 'https://example.com' })).toEqual({
+            ok: false,
+            error: 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).',
+        });
+    });
+});
+describe('formatConnectFailureMessage', () => {
+    it('adds a targeted hint when ws connect fails for a normal webpage flow', () => {
+        const message = formatConnectFailureMessage(new Error('WebSocket error connecting to ws://localhost:3100: connect ECONNREFUSED'), { kind: 'ws', wsUrl: 'ws://localhost:3100', autoCoercedFromUrl: false });
+        expect(message).toContain('ECONNREFUSED');
+        expect(message).toContain('pageUrl: "https://…"');
+    });
+});
+describe('proxy ready helpers', () => {
+    it('parses structured proxy ready JSON', () => {
+        const wsUrl = parseProxyReadySignalLine('{"type":"geometra-proxy-ready","wsUrl":"ws://127.0.0.1:41237","pageUrl":"https://example.com"}');
+        expect(wsUrl).toBe('ws://127.0.0.1:41237');
+    });
+    it('still accepts legacy human-readable ready logs', () => {
+        const wsUrl = parseProxyReadySignalLine('[geometra-proxy] WebSocket listening on ws://127.0.0.1:3200');
+        expect(wsUrl).toBe('ws://127.0.0.1:3200');
+    });
+    it('adds install and port conflict hints to proxy startup failures', () => {
+        const chromiumHint = formatProxyStartupFailure("browserType.launch: Executable doesn't exist at /tmp/chromium", { pageUrl: 'https://example.com', port: 0 });
+        expect(chromiumHint).toContain('npx playwright install chromium');
+        const portHint = formatProxyStartupFailure('listen EADDRINUSE: address already in use 127.0.0.1:3337', { pageUrl: 'https://example.com', port: 3337 });
+        expect(portHint).toContain('Requested port 3337 is unavailable');
+    });
+});

package/dist/connect-utils.d.ts

@@ -0,0 +1,18 @@
+export interface NormalizedConnectTarget {
+    kind: 'proxy' | 'ws';
+    autoCoercedFromUrl: boolean;
+    pageUrl?: string;
+    wsUrl?: string;
+}
+export declare function normalizeConnectTarget(input: {
+    url?: string;
+    pageUrl?: string;
+}): {
+    ok: true;
+    value: NormalizedConnectTarget;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function formatConnectFailureMessage(err: unknown, target: NormalizedConnectTarget): string;
+export declare function isHttpUrl(value: string): boolean;

package/dist/connect-utils.js

@@ -0,0 +1,94 @@
+export function normalizeConnectTarget(input) {
+    const rawUrl = normalizeOptional(input.url);
+    const rawPageUrl = normalizeOptional(input.pageUrl);
+    if (rawUrl && rawPageUrl) {
+        return { ok: false, error: 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).' };
+    }
+    if (!rawUrl && !rawPageUrl) {
+        return { ok: false, error: 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).' };
+    }
+    if (rawPageUrl) {
+        const parsed = parseUrl(rawPageUrl);
+        if (!parsed) {
+            return { ok: false, error: `Invalid pageUrl: ${rawPageUrl}` };
+        }
+        if (!isHttpProtocol(parsed.protocol)) {
+            return { ok: false, error: `pageUrl must use http:// or https:// (received ${parsed.protocol})` };
+        }
+        return {
+            ok: true,
+            value: {
+                kind: 'proxy',
+                pageUrl: parsed.toString(),
+                autoCoercedFromUrl: false,
+            },
+        };
+    }
+    const parsed = parseUrl(rawUrl);
+    if (!parsed) {
+        return {
+            ok: false,
+            error: `Invalid url: ${rawUrl}. Use ws://... for an already-running Geometra server, or https://... for a normal webpage.`,
+        };
+    }
+    if (isHttpProtocol(parsed.protocol)) {
+        return {
+            ok: true,
+            value: {
+                kind: 'proxy',
+                pageUrl: parsed.toString(),
+                autoCoercedFromUrl: true,
+            },
+        };
+    }
+    if (isWsProtocol(parsed.protocol)) {
+        return {
+            ok: true,
+            value: {
+                kind: 'ws',
+                wsUrl: parsed.toString(),
+                autoCoercedFromUrl: false,
+            },
+        };
+    }
+    return {
+        ok: false,
+        error: `Unsupported url protocol ${parsed.protocol}. Use ws://... for an already-running Geometra server, or http:// / https:// for webpages.`,
+    };
+}
+export function formatConnectFailureMessage(err, target) {
+    const base = err instanceof Error ? err.message : String(err);
+    const hints = [];
+    if (target.kind === 'ws' &&
+        /ECONNREFUSED|timed out|closed before first frame|WebSocket error connecting/i.test(base)) {
+        hints.push('If this is a normal website, call geometra_connect with pageUrl: "https://…" so MCP can start @geometra/proxy for you.');
+    }
+    if (/Could not resolve @geometra\/proxy/i.test(base)) {
+        hints.push('Ensure @geometra/proxy is installed alongside @geometra/mcp.');
+    }
+    if (hints.length === 0)
+        return base;
+    return `${base}\nHint: ${hints.join(' ')}`;
+}
+export function isHttpUrl(value) {
+    const parsed = parseUrl(value);
+    return parsed !== null && isHttpProtocol(parsed.protocol);
+}
+function normalizeOptional(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function parseUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+}
+function isHttpProtocol(protocol) {
+    return protocol === 'http:' || protocol === 'https:';
+}
+function isWsProtocol(protocol) {
+    return protocol === 'ws:' || protocol === 'wss:';
+}

package/dist/index.js

@@ -1,12 +1,39 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from './server.js';
+import { disconnect } from './session.js';
+let cleanedUp = false;
+function cleanupActiveSession() {
+    if (cleanedUp)
+        return;
+    cleanedUp = true;
+    try {
+        disconnect();
+    }
+    catch {
+        /* ignore */
+    }
+}
 async function main() {
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
+process.on('SIGINT', () => {
+    cleanupActiveSession();
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    cleanupActiveSession();
+    process.exit(0);
+});
+process.on('SIGHUP', () => {
+    cleanupActiveSession();
+    process.exit(0);
+});
+process.on('exit', cleanupActiveSession);
 main().catch((err) => {
+    cleanupActiveSession();
     console.error('geometra-mcp: failed to start', err);
     process.exit(1);
 });

package/dist/proxy-spawn.d.ts

@@ -1,8 +1,6 @@
 import { type ChildProcess } from 'node:child_process';
 /** Resolve bundled @geometra/proxy CLI entry (dist/index.js). */
 export declare function resolveProxyScriptPath(): string;
-/** Prefer `preferred` when free; otherwise an ephemeral port on 127.0.0.1. */
-export declare function pickFreePort(preferred?: number): Promise<number>;
 export interface SpawnProxyParams {
     pageUrl: string;
     port: number;
@@ -11,8 +9,10 @@ export interface SpawnProxyParams {
     height?: number;
     slowMo?: number;
 }
+export declare function parseProxyReadySignalLine(line: string): string | undefined;
+export declare function formatProxyStartupFailure(message: string, opts: SpawnProxyParams): string;
 /**
- * Spawn geometra-proxy as a child process and resolve when the WebSocket is listening.
+ * Spawn geometra-proxy as a child process and resolve when it emits a structured ready signal.
  */
 export declare function spawnGeometraProxy(opts: SpawnProxyParams): Promise<{
     child: ChildProcess;

package/dist/proxy-spawn.js

@@ -1,8 +1,9 @@
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { createServer } from 'node:net';
 import path from 'node:path';
 const require = createRequire(import.meta.url);
+const READY_SIGNAL_TYPE = 'geometra-proxy-ready';
+const READY_TIMEOUT_MS = 45_000;
 /** Resolve bundled @geometra/proxy CLI entry (dist/index.js). */
 export function resolveProxyScriptPath() {
     try {
@@ -13,45 +14,40 @@ export function resolveProxyScriptPath() {
         throw new Error('Could not resolve @geometra/proxy. Install it with the MCP package: npm install @geometra/proxy');
     }
 }
-function canBindPort(p) {
-    return new Promise(resolve => {
-        const s = createServer();
-        s.once('error', () => resolve(false));
-        s.listen(p, '127.0.0.1', () => {
-            s.close(() => resolve(true));
-        });
-    });
-}
-function getEphemeralPort() {
-    return new Promise((resolve, reject) => {
-        const s = createServer();
-        s.once('error', reject);
-        s.listen(0, '127.0.0.1', () => {
-            const a = s.address();
-            s.close(err => {
-                if (err) {
-                    reject(err);
-                    return;
-                }
-                if (typeof a === 'object' && a !== null && 'port' in a)
-                    resolve(a.port);
-                else
-                    reject(new Error('Could not allocate ephemeral port'));
-            });
-        });
-    });
+export function parseProxyReadySignalLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed.type === READY_SIGNAL_TYPE &&
+                typeof parsed.wsUrl === 'string' &&
+                /^ws:\/\/127\.0\.0\.1:\d+$/.test(parsed.wsUrl)) {
+                return parsed.wsUrl;
+            }
+        }
+        catch {
+            /* ignore non-JSON lines */
+        }
+    }
+    const fallback = trimmed.match(/WebSocket listening on (ws:\/\/127\.0\.0\.1:\d+)/);
+    return fallback?.[1];
 }
-/** Prefer `preferred` when free; otherwise an ephemeral port on 127.0.0.1. */
-export async function pickFreePort(preferred) {
-    if (preferred != null && preferred > 0 && preferred <= 65535) {
-        if (await canBindPort(preferred))
-            return preferred;
+export function formatProxyStartupFailure(message, opts) {
+    const hints = [];
+    if (/Executable doesn't exist|playwright install chromium|browserType\.launch/i.test(message)) {
+        hints.push('Install Chromium with: npx playwright install chromium');
     }
-    return getEphemeralPort();
+    if (opts.port > 0 && /EADDRINUSE|address already in use/i.test(message)) {
+        hints.push(`Requested port ${opts.port} is unavailable. Omit the port to use an ephemeral OS-assigned port, or choose another local port.`);
+    }
+    if (hints.length === 0)
+        return message;
+    return `${message}\nHint: ${hints.join(' ')}`;
 }
-const LISTEN_RE = /WebSocket listening on (ws:\/\/127\.0\.0\.1:\d+)/;
 /**
- * Spawn geometra-proxy as a child process and resolve when the WebSocket is listening.
+ * Spawn geometra-proxy as a child process and resolve when it emits a structured ready signal.
  */
 export function spawnGeometraProxy(opts) {
     const script = resolveProxyScriptPath();
@@ -69,41 +65,66 @@ export function spawnGeometraProxy(opts) {
     return new Promise((resolve, reject) => {
         const child = spawn(process.execPath, args, {
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env },
+            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');
+        };
+        const tryResolveReady = (line) => {
+            const wsUrl = parseProxyReadySignalLine(line);
+            if (!wsUrl || settled)
+                return false;
+            settled = true;
+            cleanup();
+            resolve({ child, wsUrl });
+            return true;
+        };
+        const consumeStdout = (chunk) => {
+            stdoutBuf += chunk.toString();
+            const lines = stdoutBuf.split(/\r?\n/);
+            stdoutBuf = lines.pop() ?? '';
+            for (const line of lines) {
+                if (tryResolveReady(line))
+                    return;
+            }
+        };
+        const consumeStderr = (chunk) => {
+            stderrBuf += chunk.toString();
+            const lines = stderrBuf.split(/\r?\n/);
+            stderrBuf = lines.pop() ?? '';
+            for (const line of lines) {
+                if (tryResolveReady(line))
+                    return;
+            }
+        };
         const deadline = setTimeout(() => {
             if (!settled) {
                 settled = true;
                 child.kill('SIGTERM');
-                reject(new Error('geometra-proxy did not report a listening WebSocket within 45s'));
+                cleanup();
+                reject(new Error(formatProxyStartupFailure('geometra-proxy did not emit a ready signal within 45s', opts)));
             }
-        }, 45_000);
-        const flushStderr = (chunk) => {
-            stderrBuf += chunk.toString();
-            const m = stderrBuf.match(LISTEN_RE);
-            if (m && !settled) {
-                settled = true;
-                clearTimeout(deadline);
-                child.stderr?.removeAllListeners('data');
-                resolve({ child, wsUrl: m[1] });
-            }
-        };
-        child.stderr?.on('data', flushStderr);
+        }, READY_TIMEOUT_MS);
+        child.stdout?.on('data', consumeStdout);
+        child.stderr?.on('data', consumeStderr);
         child.on('error', err => {
             if (!settled) {
                 settled = true;
-                clearTimeout(deadline);
-                reject(err);
+                cleanup();
+                reject(new Error(formatProxyStartupFailure(err.message, opts)));
             }
         });
         child.on('exit', (code, sig) => {
             if (!settled) {
                 settled = true;
-                clearTimeout(deadline);
-                const tail = stderrBuf.trim().slice(-2000);
-                reject(new Error(`geometra-proxy exited before ready (code=${code} signal=${sig}). Stderr (tail): ${tail || '(empty)'}`));
+                cleanup();
+                const stderrTail = stderrBuf.trim().slice(-2000);
+                reject(new Error(formatProxyStartupFailure(`geometra-proxy exited before ready (code=${code} signal=${sig}). Stderr (tail): ${stderrTail || '(empty)'}`, opts)));
             }
         });
     });

package/dist/server.js

@@ -1,23 +1,25 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
+import { formatConnectFailureMessage, isHttpUrl, normalizeConnectTarget } from './connect-utils.js';
 import { connect, connectThroughProxy, disconnect, getSession, sendClick, sendType, sendKey, sendFileUpload, sendListboxPick, sendSelectOption, sendWheel, buildA11yTree, buildCompactUiIndex, buildPageModel, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, } from './session.js';
 export function createServer() {
-    const server = new McpServer({ name: 'geometra', version: '1.19.0' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.1' }, { capabilities: { tools: {} } });
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
 
-**Prefer \`pageUrl\` for job sites and SPAs:** pass \`https://…\` and this server spawns geometra-proxy, picks a free port, and connects — you do **not** need a separate terminal or a \`ws://\` URL (fewer IDE approval steps for the human).
+**Prefer \`pageUrl\` for job sites and SPAs:** pass \`https://…\` and this server spawns geometra-proxy on an ephemeral local port and connects — you do **not** need a separate terminal or a \`ws://\` URL (fewer IDE approval steps for the human).
 
-Use \`url\` (ws://…) only when a Geometra/native server or an already-running proxy is listening.
+Use \`url\` (ws://…) only when a Geometra/native server or an already-running proxy is listening. If you accidentally pass \`https://…\` in \`url\`, MCP treats it like \`pageUrl\` and starts the proxy for you.
 
 Chromium opens **visible** by default unless \`headless: true\`. File upload / wheel / native \`<select>\` need the proxy path (\`pageUrl\` or ws to proxy).`, {
         url: z
             .string()
             .optional()
-            .describe('WebSocket URL when a server is already running (e.g. ws://127.0.0.1:3200 or ws://localhost:3100). Omit if using pageUrl.'),
+            .describe('WebSocket URL when a server is already running (e.g. ws://127.0.0.1:3200 or ws://localhost:3100). If you pass http(s) here by mistake, MCP will treat it as a page URL and start geometra-proxy.'),
         pageUrl: z
             .string()
             .url()
+            .refine(isHttpUrl, 'pageUrl must use http:// or https://')
             .optional()
             .describe('HTTP(S) page to open. MCP starts geometra-proxy and connects automatically. Use this instead of url for most web apply flows.'),
         port: z
@@ -26,7 +28,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             .positive()
             .max(65535)
             .optional()
-            .describe('Local port for spawned proxy (default: ephemeral free port).'),
+            .describe('Preferred local port for spawned proxy (default: ephemeral OS-assigned port).'),
         headless: z
             .boolean()
             .optional()
@@ -40,15 +42,14 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             .optional()
             .describe('Playwright slowMo (ms) on spawned proxy for easier visual following.'),
     }, async (input) => {
+        const normalized = normalizeConnectTarget({ url: input.url, pageUrl: input.pageUrl });
+        if (!normalized.ok)
+            return err(normalized.error);
+        const target = normalized.value;
         try {
-            const hasUrl = typeof input.url === 'string' && input.url.length > 0;
-            const hasPage = typeof input.pageUrl === 'string' && input.pageUrl.length > 0;
-            if (hasUrl === hasPage) {
-                return err('Provide exactly one of: url (WebSocket) or pageUrl (https://…).');
-            }
-            if (hasPage) {
+            if (target.kind === 'proxy') {
                 const session = await connectThroughProxy({
-                    pageUrl: input.pageUrl,
+                    pageUrl: target.pageUrl,
                     port: input.port,
                     headless: input.headless,
                     width: input.width,
@@ -56,14 +57,15 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
                     slowMo: input.slowMo,
                 });
                 const summary = compactSessionSummary(session);
-                return ok(`Started geometra-proxy and connected at ${session.url} (page: ${input.pageUrl}). UI state:\n${summary}`);
+                const inferred = target.autoCoercedFromUrl ? ' inferred from url input' : '';
+                return ok(`Started geometra-proxy and connected at ${session.url} (page: ${target.pageUrl}${inferred}). UI state:\n${summary}`);
             }
-            const session = await connect(input.url);
+            const session = await connect(target.wsUrl);
             const summary = compactSessionSummary(session);
-            return ok(`Connected to ${input.url}. UI state:\n${summary}`);
+            return ok(`Connected to ${target.wsUrl}. UI state:\n${summary}`);
         }
         catch (e) {
-            return err(`Failed to connect: ${e.message}`);
+            return err(`Failed to connect: ${formatConnectFailureMessage(e, target)}`);
         }
     });
     // ── query ────────────────────────────────────────────────────
@@ -154,8 +156,8 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
-        await sendClick(session, x, y);
-        const summary = postActionSummary(session, before);
+        const wait = await sendClick(session, x, y);
+        const summary = postActionSummary(session, before, wait);
         return ok(`Clicked at (${x}, ${y}).\n${summary}`);
     });
     // ── type ─────────────────────────────────────────────────────
@@ -168,8 +170,8 @@ Each character is sent as a key event through the geometry protocol. Returns a c
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
-        await sendType(session, text);
-        const summary = postActionSummary(session, before);
+        const wait = await sendType(session, text);
+        const summary = postActionSummary(session, before, wait);
         return ok(`Typed "${text}".\n${summary}`);
     });
     // ── key ──────────────────────────────────────────────────────
@@ -184,8 +186,8 @@ Each character is sent as a key event through the geometry protocol. Returns a c
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
-        await sendKey(session, key, { shift, ctrl, meta, alt });
-        const summary = postActionSummary(session, before);
+        const wait = await sendKey(session, key, { shift, ctrl, meta, alt });
+        const summary = postActionSummary(session, before, wait);
         return ok(`Pressed ${formatKeyCombo(key, { shift, ctrl, meta, alt })}.\n${summary}`);
     });
     // ── upload files (proxy) ───────────────────────────────────────
@@ -207,12 +209,12 @@ Strategies: **auto** (default) tries chooser click if x,y given, else hidden \`i
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
         try {
-            await sendFileUpload(session, paths, {
+            const wait = await sendFileUpload(session, paths, {
                 click: x !== undefined && y !== undefined ? { x, y } : undefined,
                 strategy,
                 drop: dropX !== undefined && dropY !== undefined ? { x: dropX, y: dropY } : undefined,
             });
-            const summary = postActionSummary(session, before);
+            const summary = postActionSummary(session, before, wait);
             return ok(`Uploaded ${paths.length} file(s).\n${summary}`);
         }
         catch (e) {
@@ -232,11 +234,11 @@ Optional openX,openY clicks the combobox first if the list is not open. Uses sub
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
         try {
-            await sendListboxPick(session, label, {
+            const wait = await sendListboxPick(session, label, {
                 exact,
                 open: openX !== undefined && openY !== undefined ? { x: openX, y: openY } : undefined,
             });
-            const summary = postActionSummary(session, before);
+            const summary = postActionSummary(session, before, wait);
             return ok(`Picked listbox option "${label}".\n${summary}`);
         }
         catch (e) {
@@ -261,8 +263,8 @@ Custom React/Vue dropdowns are not supported — open them with geometra_click a
         }
         const before = sessionA11y(session);
         try {
-            await sendSelectOption(session, x, y, { value, label, index });
-            const summary = postActionSummary(session, before);
+            const wait = await sendSelectOption(session, x, y, { value, label, index });
+            const summary = postActionSummary(session, before, wait);
             return ok(`Selected option.\n${summary}`);
         }
         catch (e) {
@@ -281,8 +283,8 @@ Custom React/Vue dropdowns are not supported — open them with geometra_click a
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
         try {
-            await sendWheel(session, deltaY, { deltaX, x, y });
-            const summary = postActionSummary(session, before);
+            const wait = await sendWheel(session, deltaY, { deltaX, x, y });
+            const summary = postActionSummary(session, before, wait);
             return ok(`Wheel delta (${deltaX ?? 0}, ${deltaY}).\n${summary}`);
         }
         catch (e) {
@@ -357,17 +359,21 @@ function sessionOverviewFromA11y(a11y) {
     const keyNodes = nodes.length > 0 ? `Key nodes:\n${summarizeCompactIndex(nodes, 18)}` : '';
     return [pageSummary, keyNodes].filter(Boolean).join('\n');
 }
-function postActionSummary(session, before) {
+function postActionSummary(session, before, wait) {
     const after = sessionA11y(session);
+    const notes = [];
+    if (wait?.status === 'timed_out') {
+        notes.push(`No frame or patch arrived within ${wait.timeoutMs}ms after the action. The action may still have succeeded if it did not change geometry or semantics.`);
+    }
     if (!after)
-        return 'No UI update received';
+        return [...notes, 'No UI update received'].filter(Boolean).join('\n');
     if (before) {
         const delta = buildUiDelta(before, after);
         if (hasUiDelta(delta)) {
-            return `Changes:\n${summarizeUiDelta(delta)}`;
+            return [...notes, `Changes:\n${summarizeUiDelta(delta)}`].filter(Boolean).join('\n');
         }
     }
-    return `Current UI:\n${sessionOverviewFromA11y(after)}`;
+    return [...notes, `Current UI:\n${sessionOverviewFromA11y(after)}`].filter(Boolean).join('\n');
 }
 function ok(text) {
     return { content: [{ type: 'text', text }] };

package/dist/session.d.ts

@@ -195,6 +195,10 @@ export interface Session {
     /** Present when this session owns a child geometra-proxy process (pageUrl connect). */
     proxyChild?: ChildProcess;
 }
+export interface UpdateWaitResult {
+    status: 'updated' | 'timed_out';
+    timeoutMs: number;
+}
 /**
  * Connect to a running Geometra server. Waits for the first frame so that
  * layout/tree state is available immediately after connection.
@@ -217,11 +221,11 @@ export declare function disconnect(): void;
 /**
  * Send a click event at (x, y) and wait for the next frame/patch response.
  */
-export declare function sendClick(session: Session, x: number, y: number): Promise<void>;
+export declare function sendClick(session: Session, x: number, y: number): Promise<UpdateWaitResult>;
 /**
  * Send a sequence of key events to type text into the focused element.
  */
-export declare function sendType(session: Session, text: string): Promise<void>;
+export declare function sendType(session: Session, text: string): Promise<UpdateWaitResult>;
 /**
  * Send a special key (Enter, Tab, Escape, etc.)
  */
@@ -230,7 +234,7 @@ export declare function sendKey(session: Session, key: string, modifiers?: {
     ctrl?: boolean;
     meta?: boolean;
     alt?: boolean;
-}): Promise<void>;
+}): Promise<UpdateWaitResult>;
 /**
  * Attach local file(s). Paths must exist on the machine running `@geometra/proxy` (not the MCP host).
  * Optional `x`,`y` click opens a file chooser; omit to use the first `input[type=file]` in any frame.
@@ -245,7 +249,7 @@ export declare function sendFileUpload(session: Session, paths: string[], opts?:
         x: number;
         y: number;
     };
-}): Promise<void>;
+}): Promise<UpdateWaitResult>;
 /** ARIA `role=option` listbox (e.g. React Select). Optional click opens the list. */
 export declare function sendListboxPick(session: Session, label: string, opts?: {
     exact?: boolean;
@@ -253,19 +257,19 @@ export declare function sendListboxPick(session: Session, label: string, opts?:
         x: number;
         y: number;
     };
-}): Promise<void>;
+}): Promise<UpdateWaitResult>;
 /** Native `<select>` only: click the control center, then pick by value, label text, or zero-based index. */
 export declare function sendSelectOption(session: Session, x: number, y: number, option: {
     value?: string;
     label?: string;
     index?: number;
-}): Promise<void>;
+}): Promise<UpdateWaitResult>;
 /** Mouse wheel / scroll. Optional `x`,`y` move pointer before scrolling. */
 export declare function sendWheel(session: Session, deltaY: number, opts?: {
     deltaX?: number;
     x?: number;
     y?: number;
-}): Promise<void>;
+}): Promise<UpdateWaitResult>;
 /**
  * Build a flat accessibility tree from the raw UI tree + layout.
  * This is a standalone reimplementation that works with raw JSON —

package/dist/session.js

@@ -1,6 +1,7 @@
 import WebSocket from 'ws';
-import { pickFreePort, spawnGeometraProxy } from './proxy-spawn.js';
+import { spawnGeometraProxy } from './proxy-spawn.js';
 let activeSession = null;
+const ACTION_UPDATE_TIMEOUT_MS = 2000;
 function shutdownPreviousSession() {
     const prev = activeSession;
     if (!prev)
@@ -93,10 +94,9 @@ export function connect(url) {
  * process to the session so disconnect / reconnect can clean it up.
  */
 export async function connectThroughProxy(options) {
-    const port = await pickFreePort(options.port);
     const { child, wsUrl } = await spawnGeometraProxy({
         pageUrl: options.pageUrl,
-        port,
+        port: options.port ?? 0,
         headless: options.headless,
         width: options.width,
         height: options.height,
@@ -1098,18 +1098,21 @@ function waitForNextUpdate(session) {
                     session.layout = msg.layout;
                     session.tree = msg.tree;
                     cleanup();
-                    resolve();
+                    resolve({ status: 'updated', timeoutMs: ACTION_UPDATE_TIMEOUT_MS });
                 }
                 else if (msg.type === 'patch' && session.layout) {
                     applyPatches(session.layout, msg.patches);
                     cleanup();
-                    resolve();
+                    resolve({ status: 'updated', timeoutMs: ACTION_UPDATE_TIMEOUT_MS });
                 }
             }
             catch { /* ignore */ }
         };
-        // Resolve after timeout even if no update comes (action may not change layout)
-        const timeout = setTimeout(() => { cleanup(); resolve(); }, 2000);
+        // Expose timeout explicitly so action handlers can tell the user the result is ambiguous.
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve({ status: 'timed_out', timeoutMs: ACTION_UPDATE_TIMEOUT_MS });
+        }, ACTION_UPDATE_TIMEOUT_MS);
         function cleanup() {
             clearTimeout(timeout);
             session.ws.off('message', onMessage);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/mcp",
-  "version": "1.19.0",
+  "version": "1.19.1",
   "description": "MCP server for Geometra — interact with running Geometra apps via the geometry protocol, no browser needed",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "ui-testing"
   ],
   "dependencies": {
-    "@geometra/proxy": "1.19.0",
+    "@geometra/proxy": "1.19.1",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "ws": "^8.18.0",
     "zod": "^3.23.0"