@mcp-b/smart-dom-reader-server 0.2.0 → 5.1.0

package/src/index.ts

@@ -1,12 +1,17 @@
 #!/usr/bin/env tsx
 
 import { constants as fsConstants } from 'node:fs';
-import { access, readFile, stat } from 'node:fs/promises';
+import { access, open } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { type CallToolResult, ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import {
+  type CallToolResult,
+  McpServer,
+  ProtocolError,
+  ProtocolErrorCode,
+} from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { type Browser, chromium, type LaunchOptions, type Page } from 'playwright';
 import { z } from 'zod';
 
@@ -14,12 +19,14 @@ const { F_OK } = fsConstants;
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+const packageVersion = (createRequire(import.meta.url)('../package.json') as { version: string })
+  .version;
 
 const EMBEDDED_LIBRARY_RELATIVE_PATH = join('..', 'lib', 'smart-dom-reader.bundle.js');
 const DEFAULT_LAUNCH_ARGS = ['--no-sandbox', '--disable-setuid-sandbox'] as const;
 
 type ConnectBrowserArgs = {
-  executablePath?: string;
+  executablePath?: string | undefined;
   headless: boolean;
 };
 
@@ -28,29 +35,29 @@ type NavigateArgs = {
 };
 
 type OptionalSelectorArgs = {
-  selector?: string;
-  detail?: 'summary' | 'region' | 'deep';
-  maxTextLength?: number;
-  maxElements?: number;
+  selector?: string | undefined;
+  detail?: 'summary' | 'region' | 'deep' | undefined;
+  maxTextLength?: number | undefined;
+  maxElements?: number | undefined;
 };
 
 type RegionArgs = {
   selector: string;
-  options?: ProgressiveExtractorRegionConfig & FormatOptions;
+  options?: (ProgressiveExtractorRegionConfig & FormatOptions) | undefined;
 };
 
 type ContentArgs = {
   selector: string;
-  options?: ProgressiveExtractorContentConfig & FormatOptions;
+  options?: (ProgressiveExtractorContentConfig & FormatOptions) | undefined;
 };
 
 type InteractiveArgs = {
-  selector?: string;
-  options?: SmartDomReaderOptions & FormatOptions;
+  selector?: string | undefined;
+  options?: (SmartDomReaderOptions & FormatOptions) | undefined;
 };
 
 type ScreenshotArgs = {
-  path?: string;
+  path?: string | undefined;
   fullPage: boolean;
 };
 
@@ -96,7 +103,7 @@ const DEFAULT_CHROME_LOCATIONS: Partial<Record<NodeJS.Platform, readonly string[
       ? [join(process.env.PROGRAMFILES, 'Google/Chrome/Application/chrome.exe')]
       : []),
     ...(process.env['ProgramFiles(x86)']
-      ? [join(process.env['ProgramFiles(x86)']!, 'Google/Chrome/Application/chrome.exe')]
+      ? [join(process.env['ProgramFiles(x86)'], 'Google/Chrome/Application/chrome.exe')]
       : []),
     ...(process.env.LOCALAPPDATA
       ? [join(process.env.LOCALAPPDATA, 'Google/Chrome/Application/chrome.exe')]
@@ -105,29 +112,55 @@ const DEFAULT_CHROME_LOCATIONS: Partial<Record<NodeJS.Platform, readonly string[
 };
 
 interface ProgressiveExtractorRegionConfig {
-  mode?: 'interactive' | 'full';
-  includeHidden?: boolean;
-  maxDepth?: number;
+  mode?: 'interactive' | 'full' | undefined;
+  includeHidden?: boolean | undefined;
+  maxDepth?: number | undefined;
 }
 
 interface ProgressiveExtractorContentConfig {
-  includeHeadings?: boolean;
-  includeLists?: boolean;
-  includeMedia?: boolean;
-  maxTextLength?: number;
+  includeHeadings?: boolean | undefined;
+  includeLists?: boolean | undefined;
+  includeMedia?: boolean | undefined;
+  maxTextLength?: number | undefined;
 }
 
 interface SmartDomReaderOptions {
-  viewportOnly?: boolean;
-  maxDepth?: number;
+  viewportOnly?: boolean | undefined;
+  maxDepth?: number | undefined;
 }
 
 interface FormatOptions {
-  detail?: 'summary' | 'region' | 'deep';
-  maxTextLength?: number;
-  maxElements?: number;
+  detail?: 'summary' | 'region' | 'deep' | undefined;
+  maxTextLength?: number | undefined;
+  maxElements?: number | undefined;
 }
 
+const COMMON_TOOL_OPTIONS_SHAPE = {
+  maxDepth: z
+    .number()
+    .int()
+    .min(0)
+    .describe('Traversal depth for nested elements. Larger values inspect deeper trees.')
+    .optional(),
+  detail: z
+    .enum(['summary', 'region', 'deep'])
+    .default('region')
+    .describe("Output depth. 'region' is actionable; 'deep' expands more details.")
+    .optional(),
+  maxTextLength: z
+    .number()
+    .int()
+    .min(0)
+    .describe('Truncate text snippets to this many characters to save tokens.')
+    .optional(),
+  maxElements: z
+    .number()
+    .int()
+    .min(0)
+    .describe('Limit number of listed items per group (buttons, links, inputs).')
+    .optional(),
+};
+
 type LibraryCache = {
   path: string;
   code: string;
@@ -162,12 +195,13 @@ class SmartDomReaderServer {
   private readonly server: McpServer;
   private browser: Browser | null = null;
   private page: Page | null = null;
+  private browserOperation: Promise<unknown> = Promise.resolve();
   private cachedLibrary: LibraryCache | null = null;
 
   constructor() {
     this.server = new McpServer({
       name: 'smart-dom-reader-server',
-      version: '0.2.0',
+      version: packageVersion,
     });
 
     this.registerTools();
@@ -175,6 +209,16 @@ class SmartDomReaderServer {
 
   async run(): Promise<void> {
     const transport = new StdioServerTransport();
+    this.server.server.onclose = () => {
+      void this.queueBrowserOperation(() => this.closeBrowser()).catch((error) => {
+        console.error('Failed to close browser during shutdown', error);
+      });
+    };
+    process.stdin.once('end', () => {
+      void this.server.close().catch((error) => {
+        console.error('Failed to close MCP server after stdin ended', error);
+      });
+    });
     await this.server.connect(transport);
     console.error('Smart DOM Reader MCP server running on stdio');
   }
@@ -186,7 +230,7 @@ class SmartDomReaderServer {
         title: 'Connect with Playwright',
         description:
           'Launch Chromium for subsequent tools. Use this first. Returns a brief status message. Run headless=false for visual debugging.',
-        inputSchema: {
+        inputSchema: z.object({
           executablePath: z
             .string()
             .trim()
@@ -201,10 +245,9 @@ class SmartDomReaderServer {
             .describe(
               'Run without a visible window. Set false to watch interactions. Default: false.'
             ),
-        },
+        }),
       },
-      // @ts-expect-error - Complex Zod schema causes TypeScript recursion depth error (TS2589)
-      async (args: ConnectBrowserArgs) => this.connectBrowser(args)
+      async (args) => this.queueBrowserOperation(() => this.connectBrowser(args))
     );
 
     this.server.registerTool(
@@ -213,15 +256,14 @@ class SmartDomReaderServer {
         title: 'Navigate to URL',
         description:
           'Load an absolute URL in the active tab and wait for network idle. Use after browser_connect.',
-        inputSchema: {
+        inputSchema: z.object({
           url: z
             .string()
             .url('url must be a valid absolute URL')
             .describe('Absolute URL to navigate to (e.g., https://example.com).'),
-        },
+        }),
       },
-      // @ts-expect-error - Complex Zod schema causes TypeScript recursion depth error (TS2589)
-      async (args: NavigateArgs) => this.navigate(args)
+      async (args) => this.navigate(args)
     );
 
     this.server.registerTool(
@@ -230,7 +272,7 @@ class SmartDomReaderServer {
         title: 'Extract DOM Structure',
         description:
           'Start here. Returns an XML-wrapped Markdown outline (<outline>) describing page regions. Next: pick a selector/section and call dom_extract_region.',
-        inputSchema: {
+        inputSchema: z.object({
           selector: z
             .union([z.string().trim().min(1), z.literal('')])
             .describe(
@@ -254,10 +296,9 @@ class SmartDomReaderServer {
             .min(0)
             .describe('Limit number of listed items per group (buttons, links, etc.).')
             .optional(),
-        },
+        }),
       },
-      // @ts-expect-error - Complex Zod schema causes TypeScript recursion depth error (TS2589)
-      async (args: OptionalSelectorArgs) => this.extractStructure(args)
+      async (args) => this.extractStructure(args)
     );
 
     this.server.registerTool(
@@ -266,7 +307,7 @@ class SmartDomReaderServer {
         title: 'Extract DOM Region',
         description:
           'Use after the outline. Returns XML-wrapped Markdown (<section>) with actionable selectors for a specific region. Next: write a script or rerun with higher detail.',
-        inputSchema: {
+        inputSchema: z.object({
           selector: z
             .string()
             .trim()
@@ -284,37 +325,12 @@ class SmartDomReaderServer {
                 .boolean()
                 .describe('Include elements that are hidden/offscreen. Default: false.')
                 .optional(),
-              maxDepth: z
-                .number()
-                .int()
-                .min(0)
-                .describe(
-                  'Traversal depth for nested elements. Larger values inspect deeper trees.'
-                )
-                .optional(),
-              detail: z
-                .enum(['summary', 'region', 'deep'])
-                .default('region')
-                .describe("Output depth. 'region' is actionable; 'deep' expands more details.")
-                .optional(),
-              maxTextLength: z
-                .number()
-                .int()
-                .min(0)
-                .describe('Truncate text snippets to this many characters to save tokens.')
-                .optional(),
-              maxElements: z
-                .number()
-                .int()
-                .min(0)
-                .describe('Limit number of listed items per group (buttons, links, inputs).')
-                .optional(),
+              ...COMMON_TOOL_OPTIONS_SHAPE,
             })
             .optional(),
-        },
+        }),
       },
-      // @ts-expect-error - Complex Zod schema causes TypeScript recursion depth error (TS2589)
-      async (args: RegionArgs) => this.extractRegion(args)
+      async (args) => this.extractRegion(args)
     );
 
     this.server.registerTool(
@@ -323,7 +339,7 @@ class SmartDomReaderServer {
         title: 'Extract DOM Content',
         description:
           'Readable text for a region as XML-wrapped Markdown (<content>). Use for comprehension; for selectors use dom_extract_region.',
-        inputSchema: {
+        inputSchema: z.object({
           selector: z
             .string()
             .trim()
@@ -362,10 +378,9 @@ class SmartDomReaderServer {
                 .optional(),
             })
             .optional(),
-        },
+        }),
       },
-      // @ts-expect-error - Complex Zod schema causes TypeScript recursion depth error (TS2589)
-      async (args: ContentArgs) => this.extractContent(args)
+      async (args) => this.extractContent(args)
     );
 
     this.server.registerTool(
@@ -374,7 +389,7 @@ class SmartDomReaderServer {
         title: 'Extract Interactive Elements',
         description:
           'Quick list of controls within a scope as XML-wrapped Markdown (<section>). Alternative to region when you only need controls.',
-        inputSchema: {
+        inputSchema: z.object({
           selector: z
             .union([z.string().trim().min(1), z.literal('')])
             .describe(
@@ -387,37 +402,12 @@ class SmartDomReaderServer {
                 .boolean()
                 .default(false)
                 .describe('Only include elements currently within the viewport. Default: false.'),
-              maxDepth: z
-                .number()
-                .int()
-                .min(0)
-                .describe(
-                  'Traversal depth for nested elements. Larger values inspect deeper trees.'
-                )
-                .optional(),
-              detail: z
-                .enum(['summary', 'region', 'deep'])
-                .default('region')
-                .describe("Output depth. 'region' is actionable; 'deep' expands more details.")
-                .optional(),
-              maxTextLength: z
-                .number()
-                .int()
-                .min(0)
-                .describe('Truncate text snippets to this many characters to save tokens.')
-                .optional(),
-              maxElements: z
-                .number()
-                .int()
-                .min(0)
-                .describe('Limit number of listed items per group (buttons, links, inputs).')
-                .optional(),
+              ...COMMON_TOOL_OPTIONS_SHAPE,
             })
             .optional(),
-        },
+        }),
       },
-      // @ts-expect-error - Complex Zod schema causes TypeScript recursion depth error (TS2589)
-      async (args: InteractiveArgs) => this.extractInteractive(args)
+      async (args) => this.extractInteractive(args)
     );
 
     this.server.registerTool(
@@ -426,7 +416,7 @@ class SmartDomReaderServer {
         title: 'Capture Screenshot',
         description:
           'Capture a PNG screenshot of the current page. Returns a short Markdown summary (path and fullPage flag).',
-        inputSchema: {
+        inputSchema: z.object({
           path: z
             .string()
             .trim()
@@ -439,9 +429,9 @@ class SmartDomReaderServer {
             .boolean()
             .default(false)
             .describe('Capture the full scrollable page. Default: false.'),
-        },
+        }),
       },
-      async (args: ScreenshotArgs) => this.captureScreenshot(args)
+      async (args) => this.captureScreenshot(args)
     );
 
     this.server.registerTool(
@@ -450,12 +440,18 @@ class SmartDomReaderServer {
         title: 'Close Browser',
         description:
           'Shut down the launched browser instance and release resources. Safe to call multiple times.',
-        inputSchema: {},
+        inputSchema: z.object({}),
       },
-      async () => this.closeBrowser()
+      async () => this.queueBrowserOperation(() => this.closeBrowser())
     );
   }
 
+  private queueBrowserOperation(operation: () => Promise<CallToolResult>): Promise<CallToolResult> {
+    const result = this.browserOperation.then(operation);
+    this.browserOperation = result.catch(() => undefined);
+    return result;
+  }
+
   private async connectBrowser(args: ConnectBrowserArgs): Promise<CallToolResult> {
     if (this.browser?.isConnected()) {
       return createTextResult('Browser already connected');
@@ -540,8 +536,8 @@ class SmartDomReaderServer {
         selector: args.selector && args.selector.trim().length > 0 ? args.selector : null,
         format: {
           detail: args.detail ?? 'summary',
-          maxTextLength: args.maxTextLength,
-          maxElements: args.maxElements,
+          ...(args.maxTextLength !== undefined && { maxTextLength: args.maxTextLength }),
+          ...(args.maxElements !== undefined && { maxElements: args.maxElements }),
         },
       });
       const duration = Date.now() - started;
@@ -562,8 +558,10 @@ class SmartDomReaderServer {
         options: args.options ?? {},
         format: {
           detail: args.options?.detail ?? 'region',
-          maxTextLength: args.options?.maxTextLength,
-          maxElements: args.options?.maxElements,
+          ...(args.options?.maxTextLength !== undefined && {
+            maxTextLength: args.options.maxTextLength,
+          }),
+          ...(args.options?.maxElements !== undefined && { maxElements: args.options.maxElements }),
         },
       });
       const duration = Date.now() - started;
@@ -584,8 +582,10 @@ class SmartDomReaderServer {
         options: args.options ?? {},
         format: {
           detail: args.options?.detail ?? 'region',
-          maxTextLength: args.options?.maxTextLength,
-          maxElements: args.options?.maxElements,
+          ...(args.options?.maxTextLength !== undefined && {
+            maxTextLength: args.options.maxTextLength,
+          }),
+          ...(args.options?.maxElements !== undefined && { maxElements: args.options.maxElements }),
         },
       });
       const duration = Date.now() - started;
@@ -606,8 +606,10 @@ class SmartDomReaderServer {
         options: args.options ?? {},
         format: {
           detail: args.options?.detail ?? 'region',
-          maxTextLength: args.options?.maxTextLength,
-          maxElements: args.options?.maxElements,
+          ...(args.options?.maxTextLength !== undefined && {
+            maxTextLength: args.options.maxTextLength,
+          }),
+          ...(args.options?.maxElements !== undefined && { maxElements: args.options.maxElements }),
         },
       });
       const duration = Date.now() - started;
@@ -655,12 +657,16 @@ class SmartDomReaderServer {
     return createTextResult('Browser closed');
   }
 
-  private async runLibraryOperation<TResult, TArgs extends Record<string, unknown>>(
-    operation: LibraryOperation,
-    args: TArgs
-  ): Promise<TResult> {
+  /**
+   * All formatting happens in-page via the bundled library; the server never
+   * imports it, so there are no server-side dynamic imports.
+   */
+  private async runLibraryOperation<
+    TResult,
+    TArgs extends Record<string, unknown> & { format: FormatOptions },
+  >(operation: LibraryOperation, args: TArgs): Promise<TResult> {
     const page = this.getActivePage();
-    const code = await this.loadLibraryCode();
+    const code = await this.readLibraryFile(resolve(__dirname, EMBEDDED_LIBRARY_RELATIVE_PATH));
 
     return page.evaluate<TResult, { code: string; operation: LibraryOperation; args: TArgs }>(
       async ({ code, operation, args }) => {
@@ -672,6 +678,9 @@ class SmartDomReaderServer {
           const { ProgressiveExtractor, MarkdownFormatter } = moduleExports;
           const SmartDOMReader = moduleExports.SmartDOMReader ?? moduleExports.default;
 
+          const fmt = args.format;
+          const meta = { title: document.title, url: location.href };
+
           switch (operation) {
             case 'structure': {
               if (!ProgressiveExtractor) {
@@ -679,14 +688,10 @@ class SmartDomReaderServer {
               }
 
               const { selector } = args as StructureOperationArgs;
-              const target = selector ? (document.querySelector(selector) ?? document) : document;
+              const target = selector ? document.querySelector(selector) : document;
+              if (!target) throw new Error(`No matching element for selector ${selector}`);
               const overview = ProgressiveExtractor.extractStructure(target);
               if (!MarkdownFormatter) throw new Error('MarkdownFormatter export is unavailable.');
-              const argsWithFormat = args as Record<string, unknown> & {
-                format?: Record<string, unknown>;
-              };
-              const fmt = argsWithFormat.format ?? {};
-              const meta = { title: document.title, url: location.href };
               return MarkdownFormatter.structure(overview, fmt, meta) as TResult;
             }
 
@@ -696,20 +701,10 @@ class SmartDomReaderServer {
               }
 
               const { selector, options } = args as RegionOperationArgs;
-              const result = ProgressiveExtractor.extractRegion(
-                selector,
-                document,
-                options ?? {},
-                SmartDOMReader
-              );
+              const result = ProgressiveExtractor.extractRegion(selector, document, options ?? {});
               if (!result)
                 return `No matching region for selector ${selector}` as unknown as TResult;
               if (!MarkdownFormatter) throw new Error('MarkdownFormatter export is unavailable.');
-              const argsWithFormat = args as Record<string, unknown> & {
-                format?: Record<string, unknown>;
-              };
-              const fmt = argsWithFormat.format ?? {};
-              const meta = { title: document.title, url: location.href };
               return MarkdownFormatter.region(result, fmt, meta) as TResult;
             }
 
@@ -726,11 +721,6 @@ class SmartDomReaderServer {
               );
               if (!content) return `No content for selector ${selector}` as unknown as TResult;
               if (!MarkdownFormatter) throw new Error('MarkdownFormatter export is unavailable.');
-              const argsWithFormat = args as Record<string, unknown> & {
-                format?: Record<string, unknown>;
-              };
-              const fmt = argsWithFormat.format ?? {};
-              const meta = { title: document.title, url: location.href };
               return MarkdownFormatter.content(content, fmt, meta) as TResult;
             }
 
@@ -740,27 +730,18 @@ class SmartDomReaderServer {
               }
 
               const { selector, options } = args as InteractiveOperationArgs;
-              const target = selector ? (document.querySelector(selector) ?? document) : document;
+              const target = selector ? document.querySelector(selector) : document;
+              if (!target) throw new Error(`No matching element for selector ${selector}`);
 
               if (typeof SmartDOMReader.extractInteractive === 'function') {
                 const result = SmartDOMReader.extractInteractive(target, options ?? {});
                 if (!MarkdownFormatter) throw new Error('MarkdownFormatter export is unavailable.');
-                const argsWithFormat = args as Record<string, unknown> & {
-                  format?: Record<string, unknown>;
-                };
-                const fmt = argsWithFormat.format ?? {};
-                const meta = { title: document.title, url: location.href };
                 return MarkdownFormatter.region(result, fmt, meta) as TResult;
               }
 
               const reader = new SmartDOMReader({ ...options, mode: 'interactive' });
               const result = reader.extract(target, options ?? {});
               if (!MarkdownFormatter) throw new Error('MarkdownFormatter export is unavailable.');
-              const argsWithFormat = args as Record<string, unknown> & {
-                format?: Record<string, unknown>;
-              };
-              const fmt = argsWithFormat.format ?? {};
-              const meta = { title: document.title, url: location.href };
               return MarkdownFormatter.region(result, fmt, meta) as TResult;
             }
 
@@ -778,8 +759,8 @@ class SmartDomReaderServer {
 
   private getActivePage(): Page {
     if (!this.browser || !this.browser.isConnected() || !this.page) {
-      throw new McpError(
-        ErrorCode.InvalidRequest,
+      throw new ProtocolError(
+        ProtocolErrorCode.InvalidRequest,
         'Browser not connected. Call browser_connect first.'
       );
     }
@@ -787,43 +768,51 @@ class SmartDomReaderServer {
     return this.page;
   }
 
-  // All formatting happens in-page via the bundled library; no server-side dynamic imports.
-
-  private async loadLibraryCode(): Promise<string> {
-    const embeddedPath = resolve(__dirname, EMBEDDED_LIBRARY_RELATIVE_PATH);
-    return this.readLibraryFile(embeddedPath);
-  }
-
   private async readLibraryFile(resolvedPath: string): Promise<string> {
-    if (!(await pathExists(resolvedPath))) {
-      throw new McpError(
-        ErrorCode.InvalidParams,
-        `Embedded library file not found at ${resolvedPath}. Ensure the bundled file exists.`
-      );
+    let file;
+    try {
+      file = await open(resolvedPath, 'r');
+    } catch (error) {
+      if (
+        typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT'
+      ) {
+        throw new ProtocolError(
+          ProtocolErrorCode.InvalidParams,
+          `Embedded library file not found at ${resolvedPath}. Ensure the bundled file exists.`
+        );
+      }
+      throw error;
     }
 
-    // If cached, validate mtime to support hot updates without restart
-    const { mtimeMs } = await stat(resolvedPath);
-    if (this.cachedLibrary?.path === resolvedPath && this.cachedLibrary.mtimeMs === mtimeMs) {
-      return this.cachedLibrary.code;
-    }
+    try {
+      // If cached, validate mtime to support hot updates without restart
+      const { mtimeMs } = await file.stat();
+      if (this.cachedLibrary?.path === resolvedPath && this.cachedLibrary.mtimeMs === mtimeMs) {
+        return this.cachedLibrary.code;
+      }
 
-    const code = await readFile(resolvedPath, 'utf8');
-    this.cachedLibrary = { path: resolvedPath, code, mtimeMs };
-    return code;
+      const code = await file.readFile('utf8');
+      this.cachedLibrary = { path: resolvedPath, code, mtimeMs };
+      return code;
+    } finally {
+      await file.close();
+    }
   }
 
   private handleToolError(error: unknown, fallbackMessage: string): never {
-    if (error instanceof McpError) {
+    if (error instanceof ProtocolError) {
       throw error;
     }
 
     if (error instanceof Error) {
       console.error(fallbackMessage, error);
-      throw new McpError(ErrorCode.InternalError, error.message);
+      throw new ProtocolError(ProtocolErrorCode.InternalError, error.message);
     }
 
-    throw new McpError(ErrorCode.InternalError, fallbackMessage);
+    throw new ProtocolError(ProtocolErrorCode.InternalError, fallbackMessage);
   }
 }