@geometra/mcp 1.24.0 → 1.25.0

package/dist/server.js

@@ -3,7 +3,7 @@ import { performance } from 'node:perf_hooks';
 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, prewarmProxy, sendClick, sendFillFields, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, sendScreenshot, sendPdfGenerate, buildA11yTree, buildCompactUiIndex, buildFormRequiredSnapshot, buildPageModel, buildFormSchemas, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, nodeContextForNode, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
+import { connect, connectThroughProxy, disconnect, getSession, listSessions, getDefaultSessionId, prewarmProxy, sendClick, sendFillFields, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, sendScreenshot, sendPdfGenerate, buildA11yTree, buildCompactUiIndex, buildFormRequiredSnapshot, buildPageModel, buildFormSchemas, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, nodeContextForNode, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
 function checkedStateInput() {
     return z
         .union([z.boolean(), z.literal('mixed')])
@@ -84,14 +84,19 @@ const GEOMETRA_WAIT_FILTER_REQUIRED_MESSAGE = 'Provide at least one semantic fil
     'This tool uses a strict schema: unknown keys are rejected. There is no textGone parameter — use text with a distinctive substring and present: false to wait until that text is gone ' +
     '(common for “Parsing…”, “Parsing your resume”, or similar). Passing only present/timeoutMs is not enough without a filter.';
 /** Strict input so unknown keys (e.g. textGone) fail parse; empty-filter checks happen in handlers / waitForSemanticCondition. */
+const sessionIdSchemaField = {
+    sessionId: z.string().optional().describe('Session identifier returned by geometra_connect. Omit to use the most recent session.'),
+};
 const geometraQueryInputSchema = z.object({
     ...nodeFilterShape(),
     maxResults: z.number().int().min(1).max(50).optional().describe('Optional cap on returned matches; terse mode defaults to 8'),
     detail: detailInput(),
+    ...sessionIdSchemaField,
 }).strict();
 const geometraWaitForInputSchema = z.object({
     ...waitConditionShape(),
     detail: detailInput(),
+    ...sessionIdSchemaField,
 }).strict();
 /** Same upper bound as geometra_wait_for; resume uploads often need the full minute. */
 const geometraWaitForResumeParseInputSchema = z
@@ -108,6 +113,7 @@ const geometraWaitForResumeParseInputSchema = z
         .max(60_000)
         .default(60_000)
         .describe('Maximum time to wait before returning an error (default 60000ms)'),
+    ...sessionIdSchemaField,
 })
     .strict();
 const timeoutMsInput = z.number().int().min(50).max(60_000).optional();
@@ -282,6 +288,7 @@ const batchActionSchema = z.discriminatedUnion('type', [
 ]);
 export function createServer() {
     const server = new McpServer({ name: 'geometra', version: '1.19.21' }, { capabilities: { tools: {} } });
+    const sessionIdInput = z.string().optional().describe('Session identifier returned by geometra_connect. Omit to use the most recent session.');
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
 
@@ -460,8 +467,8 @@ This is the Geometra equivalent of Playwright's locator — but instant, structu
 
 Unknown parameter names are rejected (strict schema). To wait until visible text goes away (e.g. a parsing banner), use geometra_wait_for with that substring in text and present: false — there is no textGone field.`,
         inputSchema: geometraQueryInputSchema,
-    }, async ({ id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, maxResults, detail }) => {
-        const session = getSession();
+    }, async ({ id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, maxResults, detail, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const a11y = await sessionA11yWhenReady(session);
@@ -516,8 +523,9 @@ Use this when geometra_page_model tells you the page shape, but you want one dir
         itemText: z.string().optional().describe('Nearby card/row/item label to disambiguate repeated actions'),
         maxResults: z.number().int().min(1).max(12).optional().default(6).describe('Maximum number of matches to return'),
         detail: detailInput(),
-    }, async ({ name, role, sectionText, promptText, itemText, maxResults, detail }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ name, role, sectionText, promptText, itemText, maxResults, detail, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const a11y = await sessionA11yWhenReady(session);
@@ -551,8 +559,8 @@ Use this when geometra_page_model tells you the page shape, but you want one dir
 
 The filter matches the same fields as geometra_query (strict schema — unknown keys error). Set \`present: false\` to wait until **no** node matches — for example Ashby/Lever-style “Parsing your resume” or any “Parsing…” banner: \`{ "text": "Parsing", "present": false }\` (tune the substring to the site). Do not use a textGone parameter; use \`text\` + \`present: false\`, or \`geometra_wait_for_resume_parse\` for the usual post-upload parsing banner.`,
         inputSchema: geometraWaitForInputSchema,
-    }, async ({ id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, present, timeoutMs, detail }) => {
-        const session = getSession();
+    }, async ({ id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, present, timeoutMs, detail, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const filterProbe = {
@@ -603,8 +611,8 @@ The filter matches the same fields as geometra_query (strict schema — unknown
 
 Equivalent to \`geometra_wait_for\` with \`present: false\` and \`text\` set to a banner substring. Default \`text\` is \`Parsing\` (tune per site). Strict schema (unknown keys rejected).`,
         inputSchema: geometraWaitForResumeParseInputSchema,
-    }, async ({ text, timeoutMs }) => {
-        const session = getSession();
+    }, async ({ text, timeoutMs, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const filter = { text };
@@ -629,8 +637,9 @@ Captures the current URL, then polls until the URL changes and a stable UI tree
             .default(10_000)
             .describe('Max time to wait for navigation + DOM stabilization (default 10s)'),
         expectedUrl: z.string().optional().describe('Optional URL substring to match — keeps waiting if the URL changes to something else (e.g. intermediate redirects)'),
-    }, async ({ timeoutMs, expectedUrl }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ timeoutMs, expectedUrl, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const beforeA11y = sessionA11y(session);
@@ -700,8 +709,9 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
             .default(true)
             .describe('Include per-field step results in the JSON payload (default true). Set false for the smallest batch response.'),
         detail: detailInput(),
-    }, async ({ fields, stopOnError, failOnInvalid, includeSteps, detail }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ fields, stopOnError, failOnInvalid, includeSteps, detail, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const resolvedFields = resolveFillFieldInputs(session, fields);
@@ -811,11 +821,13 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
             .default(false)
             .describe('Skip fields that already contain a matching value. Avoids overwriting good data from resume parsing or previous fills.'),
         detail: detailInput(),
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, resumeFromIndex, verifyFills, skipPreFilled, detail }) => {
+        sessionId: sessionIdInput,
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, resumeFromIndex, verifyFills, skipPreFilled, detail, sessionId }) => {
         const directFields = !includeSteps && !formId && Object.keys(valuesById ?? {}).length === 0
             ? directLabelBatchFields(valuesByLabel)
             : null;
         const resolved = await ensureToolSession({
+            sessionId,
             url,
             pageUrl,
             port,
@@ -1066,8 +1078,10 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
             .describe('Include per-action step results in the JSON payload (default true). Set false for the smallest batch response.'),
         output: z.enum(['full', 'final']).optional().default('full').describe('`full` (default) returns counts and optional step listings. `final` keeps only completion state plus final semantic signals.'),
         detail: detailInput(),
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, actions, stopOnError, includeSteps, output, detail }) => {
+        sessionId: sessionIdInput,
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, actions, stopOnError, includeSteps, output, detail, sessionId }) => {
         const resolved = await ensureToolSession({
+            sessionId,
             url,
             pageUrl,
             port,
@@ -1192,8 +1206,9 @@ Use this first on normal HTML pages when you want to understand the page shape w
             .optional()
             .default(false)
             .describe('Attach a base64 PNG viewport screenshot. Requires @geometra/proxy. Use when geometry alone is ambiguous (icon-only buttons, visual styling cues).'),
-    }, async ({ maxPrimaryActions, maxSectionsPerKind, includeScreenshot }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ maxPrimaryActions, maxSectionsPerKind, includeScreenshot, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const a11y = await sessionA11yWhenReady(session);
@@ -1221,8 +1236,9 @@ Unlike geometra_expand_section, this collapses repeated radio/button groups into
         includeContext: formSchemaContextInput(),
         sinceSchemaId: z.string().optional().describe('If the current schema matches this id, return changed=false without resending forms'),
         format: formSchemaFormatInput(),
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, formId, maxFields, onlyRequiredFields, onlyInvalidFields, includeOptions, includeContext, sinceSchemaId, format }) => {
-        const resolved = await ensureToolSession({ url, pageUrl, port, headless, width, height, slowMo }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_form_schema.');
+        sessionId: sessionIdInput,
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, formId, maxFields, onlyRequiredFields, onlyInvalidFields, includeOptions, includeContext, sinceSchemaId, format, sessionId }) => {
+        const resolved = await ensureToolSession({ sessionId, url, pageUrl, port, headless, width, height, slowMo }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_form_schema.');
         if (!resolved.ok)
             return err(resolved.error);
         const session = resolved.session;
@@ -1264,8 +1280,9 @@ Use this after geometra_page_model when you know which form/dialog/list/landmark
         itemOffset: z.number().int().min(0).optional().default(0).describe('List-item offset'),
         maxTextPreview: z.number().int().min(0).max(20).optional().default(6).describe('Cap text preview lines'),
         includeBounds: z.boolean().optional().default(false).describe('Include bounds for fields/actions/headings/items'),
-    }, async ({ id, maxHeadings, maxFields, fieldOffset, onlyRequiredFields, onlyInvalidFields, maxActions, actionOffset, maxLists, listOffset, maxItems, itemOffset, maxTextPreview, includeBounds, }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ id, maxHeadings, maxFields, fieldOffset, onlyRequiredFields, onlyInvalidFields, maxActions, actionOffset, maxLists, listOffset, maxItems, itemOffset, maxTextPreview, includeBounds, sessionId, }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const a11y = await sessionA11yWhenReady(session);
@@ -1305,8 +1322,9 @@ Use the same filters as geometra_query, plus an optional match index when repeat
             .optional()
             .default(2_500)
             .describe('Per-scroll wait timeout (default 2500ms)'),
-    }, async ({ id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, index, fullyVisible, maxSteps, timeoutMs }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, index, fullyVisible, maxSteps, timeoutMs, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const filter = {
@@ -1372,8 +1390,9 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
             .optional()
             .describe('Optional action wait timeout (use a longer value for slow submits or route transitions)'),
         detail: detailInput(),
-    }, async ({ x, y, id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, index, fullyVisible, maxRevealSteps, revealTimeoutMs, waitFor, timeoutMs, detail }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ x, y, id, role, name, text, contextText, promptText, sectionText, itemText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, index, fullyVisible, maxRevealSteps, revealTimeoutMs, waitFor, timeoutMs, detail, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
@@ -1467,8 +1486,9 @@ Each character is sent as a key event through the geometry protocol. Returns a c
             .optional()
             .describe('Optional action wait timeout'),
         detail: detailInput(),
-    }, async ({ text, timeoutMs, detail }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ text, timeoutMs, detail, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
@@ -1494,8 +1514,9 @@ Each character is sent as a key event through the geometry protocol. Returns a c
             .optional()
             .describe('Optional action wait timeout'),
         detail: detailInput(),
-    }, async ({ key, shift, ctrl, meta, alt, timeoutMs, detail }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ key, shift, ctrl, meta, alt, timeoutMs, detail, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
@@ -1531,8 +1552,9 @@ Strategies: **auto** (default) tries chooser click if x,y given, else a labeled
             .optional()
             .describe('Optional action wait timeout (resume parsing / SPA upload flows often need longer than a normal click)'),
         detail: detailInput(),
-    }, async ({ paths, x, y, fieldLabel, exact, strategy, dropX, dropY, contextText: _contextText, sectionText: _sectionText, timeoutMs, detail }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ paths, x, y, fieldLabel, exact, strategy, dropX, dropY, contextText: _contextText, sectionText: _sectionText, timeoutMs, detail, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
@@ -1576,8 +1598,9 @@ Pass \`fieldLabel\` to open a labeled dropdown semantically instead of relying o
             .optional()
             .describe('Optional action wait timeout for slow dropdowns / remote search results'),
         detail: detailInput(),
-    }, async ({ label, exact, openX, openY, fieldLabel, contextText, sectionText, query, timeoutMs, detail }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ label, exact, openX, openY, fieldLabel, contextText, sectionText, query, timeoutMs, detail, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
@@ -1625,8 +1648,9 @@ Custom React/Vue dropdowns are not supported here — use \`geometra_pick_listbo
             .optional()
             .describe('Optional action wait timeout'),
         detail: detailInput(),
-    }, async ({ x, y, value, label, index, contextText: _contextText, sectionText: _sectionText, timeoutMs, detail }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ x, y, value, label, index, contextText: _contextText, sectionText: _sectionText, timeoutMs, detail, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         if (value === undefined && label === undefined && index === undefined) {
@@ -1665,8 +1689,9 @@ Prefer this over raw coordinate clicks for custom forms that keep the real input
             .optional()
             .describe('Optional action wait timeout'),
         detail: detailInput(),
-    }, async ({ label, checked, exact, controlType, contextText: _contextText, sectionText: _sectionText, timeoutMs, detail }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ label, checked, exact, controlType, contextText: _contextText, sectionText: _sectionText, timeoutMs, detail, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
@@ -1698,8 +1723,9 @@ Prefer this over raw coordinate clicks for custom forms that keep the real input
             .optional()
             .describe('Optional action wait timeout'),
         detail: detailInput(),
-    }, async ({ deltaY, deltaX, x, y, timeoutMs, detail }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ deltaY, deltaX, x, y, timeoutMs, detail, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const before = sessionA11y(session);
@@ -1728,8 +1754,9 @@ Use this for dropdowns, location pickers, or any scrollable list where items are
         maxItems: z.number().int().min(1).max(500).optional().default(100).describe('Cap collected items (default 100)'),
         maxScrollSteps: z.number().int().min(1).max(50).optional().default(20).describe('Max scroll steps before stopping (default 20)'),
         scrollDelta: z.number().optional().default(300).describe('Vertical scroll delta per step (default 300)'),
-    }, async ({ listId: _listId, role, scrollX, scrollY, maxItems, maxScrollSteps, scrollDelta }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ listId: _listId, role, scrollX, scrollY, maxItems, maxScrollSteps, scrollDelta, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const itemRole = role ?? 'listitem';
@@ -1793,8 +1820,9 @@ JSON is minified in compact view to save tokens. For a summary-first overview, u
             .optional()
             .default(false)
             .describe('Attach a base64 PNG viewport screenshot. Requires @geometra/proxy.'),
-    }, async ({ view, maxNodes, formId, maxFields, includeOptions, includeScreenshot }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ view, maxNodes, formId, maxFields, includeOptions, includeScreenshot, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         const a11y = await sessionA11yWhenReady(session);
@@ -1841,8 +1869,9 @@ For a token-efficient semantic view, use geometra_snapshot (default compact). Fo
 
 Use this after navigating to a new page in a multi-step flow (e.g. job applications) to understand what has been completed so far. Pass \`clear: true\` to reset the workflow state.`, {
         clear: z.boolean().optional().default(false).describe('Reset the workflow state'),
-    }, async ({ clear }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ clear, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         if (clear) {
@@ -1905,8 +1934,9 @@ Returns \`{ pdf, pageUrl }\` where \`pdf\` is the base64-encoded PDF bytes.`, {
             .optional()
             .default(true)
             .describe('Include background graphics and colors.'),
-    }, async ({ html, format, landscape, margin, printBackground }) => {
-        const session = getSession();
+        sessionId: sessionIdInput,
+    }, async ({ html, format, landscape, margin, printBackground, sessionId }) => {
+        const session = getSession(sessionId);
         if (!session)
             return err('Not connected. Call geometra_connect first.');
         try {
@@ -1938,10 +1968,18 @@ Returns \`{ pdf, pageUrl }\` where \`pdf\` is the base64-encoded PDF bytes.`, {
     });
     server.tool('geometra_disconnect', `Disconnect from the Geometra server. Proxy-backed sessions keep compatible browsers alive by default so the next geometra_connect can reuse them quickly; pass closeBrowser=true to fully tear down the warm proxy/browser pool.`, {
         closeBrowser: z.boolean().optional().default(false).describe('Fully close the spawned proxy/browser instead of keeping it warm for reuse'),
-    }, async ({ closeBrowser }) => {
-        disconnect({ closeProxy: closeBrowser });
+        sessionId: sessionIdInput,
+    }, async ({ closeBrowser, sessionId }) => {
+        disconnect({ closeProxy: closeBrowser, sessionId });
         return ok(closeBrowser ? 'Disconnected and closed browser.' : 'Disconnected.');
     });
+    server.tool('geometra_list_sessions', 'List all active Geometra sessions with their IDs and URLs. Use this to discover available sessions when operating on multiple pages in parallel.', {}, async () => {
+        const sessions = listSessions();
+        return ok(JSON.stringify({
+            defaultSessionId: getDefaultSessionId(),
+            sessions,
+        }));
+    });
     return server;
 }
 // ── Helpers ──────────────────────────────────────────────────────
@@ -1955,6 +1993,7 @@ function connectPayload(session, opts) {
     const a11y = opts.detail === 'verbose' ? sessionA11y(session) : null;
     return {
         connected: true,
+        sessionId: session.id,
         transport: opts.transport,
         wsUrl: session.url,
         ...(a11y?.meta?.pageUrl || opts.requestedPageUrl ? { pageUrl: a11y?.meta?.pageUrl ?? opts.requestedPageUrl } : {}),
@@ -2133,7 +2172,7 @@ function pageModelResponsePayload(session, options) {
 }
 async function ensureToolSession(target, missingConnectionMessage = 'Not connected. Call geometra_connect first.') {
     if (!target.url && !target.pageUrl) {
-        const session = getSession();
+        const session = getSession(target.sessionId);
         if (!session)
             return { ok: false, error: missingConnectionMessage };
         return { ok: true, session, autoConnected: false };

package/dist/session.d.ts

@@ -373,6 +373,8 @@ export interface WorkflowState {
     startedAt: number;
 }
 export interface Session {
+    /** Short stable identifier (e.g. "s1", "s2") returned by geometra_connect. */
+    id: string;
     ws: WebSocket;
     layout: Record<string, unknown> | null;
     tree: Record<string, unknown> | null;
@@ -486,9 +488,15 @@ export declare function connectThroughProxy(options: {
     awaitInitialFrame?: boolean;
     eagerInitialExtract?: boolean;
 }): Promise<Session>;
-export declare function getSession(): Session | null;
+export declare function getSession(id?: string): Session | null;
+export declare function listSessions(): Array<{
+    id: string;
+    url: string;
+}>;
+export declare function getDefaultSessionId(): string | null;
 export declare function disconnect(opts?: {
     closeProxy?: boolean;
+    sessionId?: string;
 }): void;
 export declare function waitForUiCondition(session: Session, predicate: () => boolean, timeoutMs: number): Promise<boolean>;
 /**

package/dist/session.js

@@ -1,9 +1,13 @@
 import { performance } from 'node:perf_hooks';
 import WebSocket from 'ws';
 import { spawnGeometraProxy, startEmbeddedGeometraProxy } from './proxy-spawn.js';
-let activeSession = null;
+const activeSessions = new Map();
+let defaultSessionId = null;
+const MAX_ACTIVE_SESSIONS = 5;
+let nextSessionId = 0;
+function generateSessionId() { return `s${++nextSessionId}`; }
 let reusableProxies = [];
-const REUSABLE_PROXY_POOL_LIMIT = 2;
+const REUSABLE_PROXY_POOL_LIMIT = 6;
 const trackedReusableProxyChildren = new WeakSet();
 const ACTION_UPDATE_TIMEOUT_MS = 2000;
 const LISTBOX_UPDATE_TIMEOUT_MS = 4500;
@@ -29,8 +33,13 @@ function reusableProxyEntryForSession(session) {
     return reusableProxies.find(entry => (entry.child && session.proxyChild === entry.child) || (entry.runtime && session.proxyRuntime === entry.runtime));
 }
 function reusableProxyEntryIsActive(entry) {
-    return !!activeSession && ((!!entry.child && activeSession.proxyChild === entry.child)
-        || (!!entry.runtime && activeSession.proxyRuntime === entry.runtime));
+    for (const session of activeSessions.values()) {
+        if ((entry.child && session.proxyChild === entry.child)
+            || (entry.runtime && session.proxyRuntime === entry.runtime)) {
+            return true;
+        }
+    }
+    return false;
 }
 function clearReusableProxiesIfExited() {
     reusableProxies = reusableProxies.filter(entry => {
@@ -156,11 +165,21 @@ function rememberReusableProxyPageUrl(session) {
     }
     touchReusableProxy(entry);
 }
-function shutdownPreviousSession(opts) {
-    const prev = activeSession;
+function promoteDefaultSession() {
+    if (activeSessions.size > 0) {
+        defaultSessionId = Array.from(activeSessions.keys()).pop();
+    }
+    else {
+        defaultSessionId = null;
+    }
+}
+function shutdownSession(id, opts) {
+    const prev = activeSessions.get(id);
     if (!prev)
         return;
-    activeSession = null;
+    activeSessions.delete(id);
+    if (defaultSessionId === id)
+        promoteDefaultSession();
     try {
         prev.ws.close();
     }
@@ -206,6 +225,13 @@ function shutdownPreviousSession(opts) {
         void prev.proxyRuntime.close().catch(() => { });
     }
 }
+/** Evict the oldest session when at capacity. */
+function evictOldestSession() {
+    if (activeSessions.size < MAX_ACTIVE_SESSIONS)
+        return;
+    const oldestId = activeSessions.keys().next().value;
+    shutdownSession(oldestId, { closeProxy: false });
+}
 function formatUnknownError(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -338,11 +364,14 @@ async function attachToReusableProxy(proxy, options) {
     const desiredWidth = options.width ?? proxy.width;
     const desiredHeight = options.height ?? proxy.height;
     const needsSnapshotKickoff = options.awaitInitialFrame !== false && !proxy.snapshotReady;
-    const reusedActiveSession = ((proxy.child && activeSession?.proxyChild === proxy.child) ||
-        (proxy.runtime && activeSession?.proxyRuntime === proxy.runtime))
-        ? activeSession
-        : null;
-    const session = reusedActiveSession ?? await connect(proxy.wsUrl, {
+    let reusedExistingSession = null;
+    for (const s of activeSessions.values()) {
+        if ((proxy.child && s.proxyChild === proxy.child) || (proxy.runtime && s.proxyRuntime === proxy.runtime)) {
+            reusedExistingSession = s;
+            break;
+        }
+    }
+    const session = reusedExistingSession ?? await connect(proxy.wsUrl, {
         skipInitialResize: true,
         closePreviousProxy: false,
         awaitInitialFrame: needsSnapshotKickoff ? false : options.awaitInitialFrame,
@@ -375,7 +404,7 @@ async function attachToReusableProxy(proxy, options) {
         proxy.pageUrl = options.pageUrl;
         updateReusableProxySnapshotState(proxy, session);
     }
-    const baseConnectTrace = !reusedActiveSession ? session.connectTrace : undefined;
+    const baseConnectTrace = !reusedExistingSession ? session.connectTrace : undefined;
     session.connectTrace = {
         mode: 'reused-proxy',
         reused: true,
@@ -503,9 +532,10 @@ export function connect(url, opts) {
     return new Promise((resolve, reject) => {
         const startedAt = performance.now();
         clearReusableProxiesIfExited();
-        shutdownPreviousSession({ closeProxy: opts?.closePreviousProxy ?? true });
+        evictOldestSession();
         const ws = new WebSocket(url);
         const session = {
+            id: generateSessionId(),
             ws,
             layout: null,
             tree: null,
@@ -545,7 +575,8 @@ export function connect(url, opts) {
                     session.connectTrace.resolvedWithoutInitialFrame = true;
                     session.connectTrace.totalMs = performance.now() - startedAt;
                 }
-                activeSession = session;
+                activeSessions.set(session.id, session);
+                defaultSessionId = session.id;
                 resolve(session);
             }
         });
@@ -567,7 +598,8 @@ export function connect(url, opts) {
                         if (session.connectTrace) {
                             session.connectTrace.totalMs = performance.now() - startedAt;
                         }
-                        activeSession = session;
+                        activeSessions.set(session.id, session);
+                        defaultSessionId = session.id;
                         resolve(session);
                     }
                 }
@@ -587,8 +619,10 @@ export function connect(url, opts) {
             }
         });
         ws.on('close', () => {
-            if (activeSession === session) {
-                activeSession = null;
+            if (activeSessions.get(session.id) === session) {
+                activeSessions.delete(session.id);
+                if (defaultSessionId === session.id)
+                    promoteDefaultSession();
                 if (session.proxyChild && !session.proxyReusable) {
                     try {
                         session.proxyChild.kill('SIGTERM');
@@ -636,11 +670,26 @@ export async function connectThroughProxy(options) {
         throw e;
     }
 }
-export function getSession() {
-    return activeSession;
+export function getSession(id) {
+    if (id)
+        return activeSessions.get(id) ?? null;
+    if (defaultSessionId)
+        return activeSessions.get(defaultSessionId) ?? null;
+    return null;
+}
+export function listSessions() {
+    return Array.from(activeSessions.values()).map(s => ({ id: s.id, url: s.url }));
+}
+export function getDefaultSessionId() {
+    return defaultSessionId;
 }
 export function disconnect(opts) {
-    shutdownPreviousSession({ closeProxy: opts?.closeProxy ?? false });
+    if (opts?.sessionId) {
+        shutdownSession(opts.sessionId, { closeProxy: opts.closeProxy ?? false });
+    }
+    else if (defaultSessionId) {
+        shutdownSession(defaultSessionId, { closeProxy: opts?.closeProxy ?? false });
+    }
     if (opts?.closeProxy)
         closeReusableProxies();
 }

package/package.json

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