@midscene/shared 0.30.10 → 1.0.0

package/src/extractor/dom-util.ts

@@ -1,5 +1,4 @@
-import { NodeType } from '../constants';
-import { generateHashId } from '../utils';
+import type { LocateResultElement } from '../types';
 
 export function isFormElement(node: globalThis.Node) {
   return (
@@ -132,20 +131,24 @@ function includeBaseElement(node: globalThis.Node) {
   return false;
 }
 
-export function generateElementByPosition(position: { x: number; y: number }) {
+export function generateElementByPosition(
+  position: {
+    x: number;
+    y: number;
+  },
+  description: string,
+): LocateResultElement {
+  const edgeSize = 8;
   const rect = {
-    left: Math.max(position.x - 4, 0),
-    top: Math.max(position.y - 4, 0),
-    width: 8,
-    height: 8,
+    left: Math.round(Math.max(position.x - edgeSize / 2, 0)),
+    top: Math.round(Math.max(position.y - edgeSize / 2, 0)),
+    width: edgeSize,
+    height: edgeSize,
   };
-  const id = generateHashId(rect);
   const element = {
-    id,
-    attributes: { nodeType: NodeType.POSITION },
     rect,
-    content: '',
-    center: [position.x, position.y],
+    center: [position.x, position.y] as [number, number],
+    description: description || '',
   };
 
   return element;

package/src/extractor/index.ts

@@ -35,10 +35,7 @@ export { extractTreeNode as webExtractNodeTree } from './web-extractor';
 
 export { extractTreeNodeAsString as webExtractNodeTreeAsString } from './web-extractor';
 
-export { setNodeHashCacheListOnWindow, getNodeFromCacheList } from './util';
-
 export {
-  getXpathsById,
   getXpathsByPoint,
   getNodeInfoByXpath,
   getElementInfoByXpath,

package/src/extractor/locator.ts

@@ -1,7 +1,6 @@
 import type { ElementInfo } from '.';
 import type { Point } from '../types';
 import { isSvgElement } from './dom-util';
-import { getNodeFromCacheList } from './util';
 import { getRect, isElementPartiallyInViewport } from './util';
 import { collectElementInfo } from './web-extractor';
 
@@ -105,17 +104,6 @@ export const getElementXpath = (
   return buildCurrentElementXpath(el, isOrderSensitive, isLeafElement);
 };
 
-export function getXpathsById(id: string): string[] | null {
-  const node = getNodeFromCacheList(id);
-
-  if (!node) {
-    return null;
-  }
-
-  const fullXPath = getElementXpath(node, false, true);
-  return [fullXPath];
-}
-
 export function getXpathsByPoint(
   point: Point,
   isOrderSensitive: boolean,
@@ -140,6 +128,9 @@ export function getNodeInfoByXpath(xpath: string): Node | null {
   );
 
   if (xpathResult.snapshotLength !== 1) {
+    console.warn(
+      `[midscene:warning] Received XPath "${xpath}" but it matched ${xpathResult.snapshotLength} elements. Discarding this result.`,
+    );
     return null;
   }
 

package/src/extractor/tree.ts

@@ -45,7 +45,7 @@ export function trimAttributes(
       res[currentKey] = truncateText(attributeVal, truncateTextLength);
       return res;
     },
-    {} as BaseElement['attributes'],
+    {} as Record<string, string>,
   );
   return tailorAttributes;
 }
@@ -106,8 +106,8 @@ export function descriptionOfTree<
           .replace(/\sNode$/, '')
           .toLowerCase();
       }
-      const markerId = node.node.indexId;
-      const markerIdString = markerId ? `markerId="${markerId}"` : '';
+      // const markerId = node.node.indexId;
+      // const markerIdString = markerId ? `markerId="${markerId}"` : '';
       const rectAttribute = node.node.rect
         ? {
             left: node.node.rect.left,
@@ -116,7 +116,7 @@ export function descriptionOfTree<
             height: node.node.rect.height,
           }
         : {};
-      before = `<${nodeTypeString} id="${node.node.id}" ${markerIdString} ${attributesString(trimAttributes(node.node.attributes || {}, truncateTextLength))} ${attributesString(rectAttribute)}>`;
+      before = `<${nodeTypeString} id="${node.node.id}" ${attributesString(trimAttributes(node.node.attributes || {}, truncateTextLength))} ${attributesString(rectAttribute)}>`;
       const content = truncateText(node.node.content, truncateTextLength);
       contentWithIndent = content ? `\n${indentStr}  ${content}` : '';
       after = `</${nodeTypeString}>`;

package/src/extractor/util.ts

@@ -399,42 +399,10 @@ export function midsceneGenerateHash(
 ): string {
   const slicedHash = generateHashId(rect, content);
 
-  if (node) {
-    if (!(window as any).midsceneNodeHashCacheList) {
-      setNodeHashCacheListOnWindow();
-    }
-
-    setNodeToCacheList(node, slicedHash);
-  }
-
   // Returns the first 10 characters as a short hash
   return slicedHash;
 }
 
-export function setNodeHashCacheListOnWindow() {
-  if (typeof window !== 'undefined') {
-    (window as any).midsceneNodeHashCacheList = [];
-  }
-}
-
-export function setNodeToCacheList(node: globalThis.Node, id: string) {
-  if (typeof window !== 'undefined') {
-    if (getNodeFromCacheList(id)) {
-      return;
-    }
-    (window as any).midsceneNodeHashCacheList?.push({ node, id });
-  }
-}
-
-export function getNodeFromCacheList(id: string) {
-  if (typeof window !== 'undefined') {
-    return (window as any).midsceneNodeHashCacheList?.find(
-      (item: { node: Node; id: string }) => item.id === id,
-    )?.node;
-  }
-  return null;
-}
-
 export function generateId(numberId: number) {
   //   const letters = 'ABCDEFGHIJKLMNPRSTUVXYZ';
   //   const numbers = '0123456789';

package/src/index.ts

@@ -3,4 +3,6 @@ export {
   createPlaygroundCopyPlugin,
 } from './build/copy-static';
 
+export { commonIgnoreWarnings } from './build/rspack-config';
+
 export default {};

package/src/mcp/base-server.ts

@@ -0,0 +1,435 @@
+import { randomUUID } from 'node:crypto';
+import type { ParseArgsConfig } from 'node:util';
+import { setIsMcp } from '@midscene/shared/utils';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express, {
+  type Application,
+  type Request,
+  type Response,
+} from 'express';
+import type { IMidsceneTools } from './types';
+
+export interface BaseMCPServerConfig {
+  name: string;
+  version: string;
+  description: string;
+}
+
+export interface HttpLaunchOptions {
+  port: number;
+  host?: string;
+}
+
+interface SessionData {
+  transport: StreamableHTTPServerTransport;
+  createdAt: Date;
+  lastAccessedAt: Date;
+}
+
+/**
+ * CLI argument configuration for MCP servers
+ */
+export const CLI_ARGS_CONFIG: ParseArgsConfig['options'] = {
+  mode: { type: 'string', default: 'stdio' },
+  port: { type: 'string', default: '3000' },
+  host: { type: 'string', default: 'localhost' },
+};
+
+export interface CLIArgs {
+  mode?: string;
+  port?: string;
+  host?: string;
+}
+
+/**
+ * Launch an MCP server based on CLI arguments
+ * Shared helper to reduce duplication across platform CLI entry points
+ */
+export function launchMCPServer(
+  server: BaseMCPServer,
+  args: CLIArgs,
+): Promise<void> {
+  if (args.mode === 'http') {
+    return server.launchHttp({
+      port: Number.parseInt(args.port || '3000', 10),
+      host: args.host || 'localhost',
+    });
+  }
+  return server.launch();
+}
+
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+const MAX_SESSIONS = 100; // Maximum concurrent sessions to prevent DoS
+
+/**
+ * Base MCP Server class with programmatic launch() API
+ * Each platform extends this to provide their own tools manager
+ */
+export abstract class BaseMCPServer {
+  protected mcpServer: McpServer;
+  protected toolsManager?: IMidsceneTools;
+  protected config: BaseMCPServerConfig;
+
+  constructor(config: BaseMCPServerConfig) {
+    this.config = config;
+    this.mcpServer = new McpServer({
+      name: config.name,
+      version: config.version,
+      description: config.description,
+    });
+  }
+
+  /**
+   * Platform-specific: create tools manager instance
+   */
+  protected abstract createToolsManager(): IMidsceneTools;
+
+  /**
+   * Initialize tools manager and attach to MCP server
+   */
+  private async initializeToolsManager(): Promise<void> {
+    setIsMcp(true);
+    this.toolsManager = this.createToolsManager();
+
+    try {
+      await this.toolsManager.initTools();
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Failed to initialize tools: ${message}`);
+      console.error('Tools will be initialized on first use');
+    }
+
+    this.toolsManager.attachToServer(this.mcpServer);
+  }
+
+  /**
+   * Perform cleanup on shutdown
+   */
+  private performCleanup(): void {
+    console.error(`${this.config.name} closing...`);
+    this.mcpServer.close();
+    this.toolsManager?.closeBrowser?.().catch(console.error);
+  }
+
+  /**
+   * Initialize and launch the MCP server with stdio transport
+   */
+  public async launch(): Promise<void> {
+    // Hijack stdout-based console methods to stderr for stdio mode
+    // This prevents them from breaking MCP JSON-RPC protocol on stdout
+    // Note: console.warn and console.error already output to stderr
+    console.log = (...args: unknown[]) => {
+      console.error('[LOG]', ...args);
+    };
+    console.info = (...args: unknown[]) => {
+      console.error('[INFO]', ...args);
+    };
+    console.debug = (...args: unknown[]) => {
+      console.error('[DEBUG]', ...args);
+    };
+
+    await this.initializeToolsManager();
+
+    const transport = new StdioServerTransport();
+
+    try {
+      await this.mcpServer.connect(transport);
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Failed to connect MCP stdio transport: ${message}`);
+      throw new Error(`Failed to initialize MCP stdio transport: ${message}`);
+    }
+
+    // Setup process-level error handlers to prevent crashes
+    process.on('uncaughtException', (error: Error) => {
+      console.error(`[${this.config.name}] Uncaught Exception:`, error);
+      console.error('Stack:', error.stack);
+      // Don't exit - try to recover
+    });
+
+    process.on('unhandledRejection', (reason: unknown) => {
+      console.error(`[${this.config.name}] Unhandled Rejection:`, reason);
+      if (reason instanceof Error) {
+        console.error('Stack:', reason.stack);
+      }
+      // Don't exit - try to recover
+    });
+
+    // Setup cleanup handlers
+    process.stdin.on('close', () => this.performCleanup());
+
+    // Setup signal handlers for graceful shutdown
+    const cleanup = () => {
+      console.error(`${this.config.name} shutting down...`);
+      this.performCleanup();
+      process.exit(0);
+    };
+
+    process.once('SIGINT', cleanup);
+    process.once('SIGTERM', cleanup);
+  }
+
+  /**
+   * Launch MCP server with HTTP transport
+   * Supports stateful sessions for web applications and service integration
+   */
+  public async launchHttp(options: HttpLaunchOptions): Promise<void> {
+    // Validate port number
+    if (
+      !Number.isInteger(options.port) ||
+      options.port < 1 ||
+      options.port > 65535
+    ) {
+      throw new Error(
+        `Invalid port number: ${options.port}. Port must be between 1 and 65535.`,
+      );
+    }
+
+    await this.initializeToolsManager();
+
+    const app: Application = express();
+
+    // Add JSON body parser with size limit
+    app.use(express.json({ limit: '10mb' }));
+
+    const sessions = new Map<string, SessionData>();
+
+    app.all('/mcp', async (req: Request, res: Response) => {
+      const startTime = Date.now();
+      const requestId = randomUUID().substring(0, 8);
+
+      try {
+        const rawSessionId = req.headers['mcp-session-id'];
+        const sessionId = Array.isArray(rawSessionId)
+          ? rawSessionId[0]
+          : rawSessionId;
+        let session = sessionId ? sessions.get(sessionId) : undefined;
+
+        if (!session && req.method === 'POST') {
+          // Check session limit to prevent DoS
+          if (sessions.size >= MAX_SESSIONS) {
+            console.error(
+              `[${new Date().toISOString()}] [${requestId}] Session limit reached: ${sessions.size}/${MAX_SESSIONS}`,
+            );
+            res.status(503).json({
+              error: 'Too many active sessions',
+              message: 'Server is at maximum capacity. Please try again later.',
+            });
+            return;
+          }
+          session = await this.createHttpSession(sessions);
+          console.log(
+            `[${new Date().toISOString()}] [${requestId}] New session created: ${session.transport.sessionId}`,
+          );
+        }
+
+        if (session) {
+          session.lastAccessedAt = new Date();
+          await session.transport.handleRequest(req, res, req.body);
+          const duration = Date.now() - startTime;
+          console.log(
+            `[${new Date().toISOString()}] [${requestId}] Request completed in ${duration}ms`,
+          );
+        } else {
+          console.error(
+            `[${new Date().toISOString()}] [${requestId}] Invalid session or GET without session`,
+          );
+          res
+            .status(400)
+            .json({ error: 'Invalid session or GET without session' });
+        }
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        const duration = Date.now() - startTime;
+        console.error(
+          `[${new Date().toISOString()}] [${requestId}] MCP request error after ${duration}ms: ${message}`,
+        );
+        if (!res.headersSent) {
+          res.status(500).json({
+            error: 'Internal server error',
+            message: 'Failed to process MCP request',
+          });
+        }
+      }
+    });
+
+    const host = options.host || 'localhost';
+
+    // Create server with error handling
+    const server = app
+      .listen(options.port, host, () => {
+        console.log(
+          `${this.config.name} HTTP server listening on http://${host}:${options.port}/mcp`,
+        );
+      })
+      .on('error', (error: NodeJS.ErrnoException) => {
+        if (error.code === 'EADDRINUSE') {
+          console.error(
+            `ERROR: Port ${options.port} is already in use.\nPlease try a different port: --port=<number>\nExample: --mode=http --port=${options.port + 1}`,
+          );
+        } else if (error.code === 'EACCES') {
+          console.error(
+            `ERROR: Permission denied to bind to port ${options.port}.\nPorts below 1024 require root/admin privileges.\nPlease use a port above 1024 or run with elevated privileges.`,
+          );
+        } else {
+          console.error(
+            `ERROR: Failed to start HTTP server on ${host}:${options.port}\n` +
+              `Reason: ${error.message}\n` +
+              `Code: ${error.code || 'unknown'}`,
+          );
+        }
+        process.exit(1);
+      });
+
+    const cleanupInterval = this.startSessionCleanup(sessions);
+    this.setupHttpShutdownHandlers(server, sessions, cleanupInterval);
+  }
+
+  /**
+   * Create a new HTTP session with transport
+   */
+  private async createHttpSession(
+    sessions: Map<string, SessionData>,
+  ): Promise<SessionData> {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (sid: string) => {
+        sessions.set(sid, {
+          transport,
+          createdAt: new Date(),
+          lastAccessedAt: new Date(),
+        });
+        console.log(
+          `[${new Date().toISOString()}] Session ${sid} initialized (total: ${sessions.size})`,
+        );
+      },
+    });
+
+    transport.onclose = () => {
+      if (transport.sessionId) {
+        sessions.delete(transport.sessionId);
+        console.log(
+          `[${new Date().toISOString()}] Session ${transport.sessionId} closed (remaining: ${sessions.size})`,
+        );
+      }
+    };
+
+    try {
+      await this.mcpServer.connect(transport);
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(
+        `[${new Date().toISOString()}] Failed to connect MCP transport: ${message}`,
+      );
+      // Clean up the failed transport
+      if (transport.sessionId) {
+        sessions.delete(transport.sessionId);
+      }
+      throw new Error(`Failed to initialize MCP session: ${message}`);
+    }
+
+    return {
+      transport,
+      createdAt: new Date(),
+      lastAccessedAt: new Date(),
+    };
+  }
+
+  /**
+   * Start periodic session cleanup for inactive sessions
+   */
+  private startSessionCleanup(
+    sessions: Map<string, SessionData>,
+  ): ReturnType<typeof setInterval> {
+    return setInterval(() => {
+      const now = Date.now();
+      for (const [sid, session] of sessions) {
+        if (now - session.lastAccessedAt.getTime() > SESSION_TIMEOUT_MS) {
+          try {
+            session.transport.close();
+            sessions.delete(sid);
+            console.log(
+              `[${new Date().toISOString()}] Session ${sid} cleaned up due to inactivity (remaining: ${sessions.size})`,
+            );
+          } catch (error: unknown) {
+            const message =
+              error instanceof Error ? error.message : String(error);
+            console.error(
+              `[${new Date().toISOString()}] Failed to close session ${sid} during cleanup: ${message}`,
+            );
+            // Still delete from map to prevent retry loops
+            sessions.delete(sid);
+          }
+        }
+      }
+    }, CLEANUP_INTERVAL_MS);
+  }
+
+  /**
+   * Setup shutdown handlers for HTTP server
+   */
+  private setupHttpShutdownHandlers(
+    server: ReturnType<Application['listen']>,
+    sessions: Map<string, SessionData>,
+    cleanupInterval: ReturnType<typeof setInterval>,
+  ): void {
+    const cleanup = () => {
+      console.error(`${this.config.name} shutting down...`);
+      clearInterval(cleanupInterval);
+
+      // Close all sessions with error handling
+      for (const session of sessions.values()) {
+        try {
+          session.transport.close();
+        } catch (error: unknown) {
+          const message =
+            error instanceof Error ? error.message : String(error);
+          console.error(`Error closing session during shutdown: ${message}`);
+        }
+      }
+      sessions.clear();
+
+      // Close HTTP server gracefully
+      try {
+        server.close(() => {
+          // Server closed callback - all connections finished
+          this.performCleanup();
+          process.exit(0);
+        });
+
+        // Set a timeout in case server.close() hangs
+        setTimeout(() => {
+          console.error('Forcefully shutting down after timeout');
+          this.performCleanup();
+          process.exit(1);
+        }, 5000);
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error closing HTTP server: ${message}`);
+        this.performCleanup();
+        process.exit(1);
+      }
+    };
+
+    // Use once() to prevent multiple registrations
+    process.once('SIGINT', cleanup);
+    process.once('SIGTERM', cleanup);
+  }
+
+  /**
+   * Get the underlying MCP server instance
+   */
+  public getServer(): McpServer {
+    return this.mcpServer;
+  }
+
+  /**
+   * Get the tools manager instance
+   */
+  public getToolsManager(): IMidsceneTools | undefined {
+    return this.toolsManager;
+  }
+}