@metamask/client-mcp-core 0.1.0

package/dist/mcp-server/tools/helpers.d.mts

@@ -0,0 +1,149 @@
+import type { Page } from "@playwright/test";
+import type { ExtensionState } from "../../capabilities/types.mjs";
+import type { McpResponse, ErrorCode, StepRecordObservation } from "../types/index.mjs";
+/**
+ * Level of detail to collect for observation data.
+ * - "full": Collect state, testIds, and a11y tree
+ * - "minimal": Collect state only (no testIds or a11y)
+ * - "none": Return empty observation
+ */
+export type ObservationLevel = 'full' | 'minimal' | 'none';
+/**
+ * Parameters for recording a tool step in the knowledge store.
+ */
+export type RecordStepParams = {
+    /**
+     * Name of the tool that was executed
+     */
+    toolName: string;
+    /**
+     * Input parameters passed to the tool
+     */
+    input: Record<string, unknown>;
+    /**
+     * Timestamp when the tool execution started
+     */
+    startTime: number;
+    /**
+     * Observation data collected after tool execution
+     */
+    observation: StepRecordObservation;
+    /**
+     * Target element information (selector, testId, etc.)
+     */
+    target?: Record<string, string>;
+    /**
+     * Path to screenshot file if captured
+     */
+    screenshotPath?: string;
+    /**
+     * Screenshot dimensions if captured
+     */
+    screenshotDimensions?: {
+        /**
+         * Screenshot width in pixels
+         */
+        width: number;
+        /**
+         * Screenshot height in pixels
+         */
+        height: number;
+    };
+};
+/**
+ * Context information for an active session.
+ */
+export type ActiveSessionContext = {
+    /**
+     * Unique session identifier
+     */
+    sessionId: string;
+    /**
+     * Current active page instance
+     */
+    page: Page;
+    /**
+     * Map of accessibility references to selectors
+     */
+    refMap: Map<string, string>;
+};
+/**
+ * Check if an active session exists and return error if not.
+ *
+ * @param startTime - Timestamp when the operation started
+ * @returns Error response if no active session, undefined otherwise
+ */
+export declare function requireActiveSession<Result>(startTime: number): McpResponse<Result> | undefined;
+/**
+ * Collect observation data from the current page state.
+ *
+ * @param page - The page to collect observation from
+ * @param level - Level of detail to collect (full, minimal, or none)
+ * @param presetState - Optional pre-fetched extension state to use instead of querying
+ * @returns Observation data with state, testIds, and accessibility tree
+ */
+export declare function collectObservation(page: Page | undefined, level: ObservationLevel, presetState?: ExtensionState): Promise<StepRecordObservation>;
+/**
+ * Wrapper that ensures an active session exists before executing a handler.
+ *
+ * @param handler - Function to execute with active session context
+ * @returns Wrapped function that validates session before calling handler
+ */
+export declare function withActiveSession<TInput, TResult>(handler: (input: TInput, ctx: ActiveSessionContext, startTime: number) => Promise<McpResponse<TResult>>): (input: TInput) => Promise<McpResponse<TResult>>;
+/**
+ * Record a tool execution step in the knowledge store.
+ *
+ * @param params - Parameters containing tool name, input, observation, and metadata
+ */
+export declare function recordToolStep(params: RecordStepParams): Promise<void>;
+/**
+ * Collect observation data and record the tool step in the knowledge store.
+ *
+ * @param page - The page to collect observation from
+ * @param toolName - Name of the tool that was executed
+ * @param input - Input parameters passed to the tool
+ * @param startTime - Timestamp when the tool execution started
+ * @param options - Optional metadata for the step record
+ * @param options.target - Target element information
+ * @param options.screenshotPath - Path to screenshot file if captured
+ * @param options.screenshotDimensions - Screenshot dimensions
+ * @param options.screenshotDimensions.width - Screenshot width in pixels
+ * @param options.screenshotDimensions.height - Screenshot height in pixels
+ * @returns Observation data collected after tool execution
+ */
+export declare function collectObservationAndRecord(page: Page, toolName: string, input: Record<string, unknown>, startTime: number, options?: {
+    /**
+     * Target element information (selector, testId, etc.)
+     */
+    target?: Record<string, string>;
+    /**
+     * Path to screenshot file if captured
+     */
+    screenshotPath?: string;
+    /**
+     * Screenshot dimensions if captured
+     */
+    screenshotDimensions?: {
+        /**
+         * Screenshot width in pixels
+         */
+        width: number;
+        /**
+         * Screenshot height in pixels
+         */
+        height: number;
+    };
+}): Promise<StepRecordObservation>;
+/**
+ * Handle tool execution errors and return appropriate error response.
+ *
+ * @param error - The error that occurred during tool execution
+ * @param defaultCode - Default error code to use if no specific match found
+ * @param defaultMessage - Default error message to use
+ * @param input - Input parameters that were passed to the tool
+ * @param sessionId - Current session ID for error context
+ * @param startTime - Timestamp when the tool execution started
+ * @returns Error response with appropriate code and message
+ */
+export declare function handleToolError<Result>(error: unknown, defaultCode: ErrorCode, defaultMessage: string, input: unknown, sessionId: string | undefined, startTime: number): McpResponse<Result>;
+//# sourceMappingURL=helpers.d.mts.map

package/dist/mcp-server/tools/helpers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.mts","sourceRoot":"","sources":["../../../src/mcp-server/tools/helpers.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/helpers.mjs

@@ -0,0 +1,141 @@
+import { OBSERVATION_TESTID_LIMIT } from "../constants.mjs";
+import { collectTestIds, collectTrimmedA11ySnapshot } from "../discovery.mjs";
+import { knowledgeStore, createDefaultObservation } from "../knowledge-store.mjs";
+import { getSessionManager } from "../session-manager.mjs";
+import { ErrorCodes } from "../types/index.mjs";
+import { createErrorResponse, extractErrorMessage, debugWarn } from "../utils/index.mjs";
+/**
+ * Check if an active session exists and return error if not.
+ *
+ * @param startTime - Timestamp when the operation started
+ * @returns Error response if no active session, undefined otherwise
+ */
+export function requireActiveSession(startTime) {
+    const sessionManager = getSessionManager();
+    if (!sessionManager.hasActiveSession()) {
+        return createErrorResponse(ErrorCodes.MM_NO_ACTIVE_SESSION, 'No active session. Call launch first.', undefined, undefined, startTime);
+    }
+    return undefined;
+}
+/**
+ * Collect observation data from the current page state.
+ *
+ * @param page - The page to collect observation from
+ * @param level - Level of detail to collect (full, minimal, or none)
+ * @param presetState - Optional pre-fetched extension state to use instead of querying
+ * @returns Observation data with state, testIds, and accessibility tree
+ */
+export async function collectObservation(page, level, presetState) {
+    const sessionManager = getSessionManager();
+    if (level === 'none') {
+        return createDefaultObservation({}, [], []);
+    }
+    const state = presetState ?? (await sessionManager.getExtensionState());
+    if (level === 'minimal') {
+        return createDefaultObservation(state, [], []);
+    }
+    if (!page) {
+        debugWarn('collectObservation', 'Page not provided for full observation');
+        return createDefaultObservation(state, [], []);
+    }
+    try {
+        const testIds = await collectTestIds(page, OBSERVATION_TESTID_LIMIT);
+        const { nodes, refMap } = await collectTrimmedA11ySnapshot(page);
+        sessionManager.setRefMap(refMap);
+        return createDefaultObservation(state, testIds, nodes);
+    }
+    catch (error) {
+        debugWarn('collectObservation', error);
+        return createDefaultObservation(state, [], []);
+    }
+}
+/**
+ * Wrapper that ensures an active session exists before executing a handler.
+ *
+ * @param handler - Function to execute with active session context
+ * @returns Wrapped function that validates session before calling handler
+ */
+export function withActiveSession(handler) {
+    return async (input) => {
+        const startTime = Date.now();
+        const sessionManager = getSessionManager();
+        const sessionError = requireActiveSession(startTime);
+        if (sessionError) {
+            return sessionError;
+        }
+        const sessionId = sessionManager.getSessionId();
+        if (!sessionId) {
+            return createErrorResponse(ErrorCodes.MM_NO_ACTIVE_SESSION, 'Session ID not found', undefined, undefined, startTime);
+        }
+        const page = sessionManager.getPage();
+        const refMap = sessionManager.getRefMap();
+        return handler(input, { sessionId, page, refMap }, startTime);
+    };
+}
+/**
+ * Record a tool execution step in the knowledge store.
+ *
+ * @param params - Parameters containing tool name, input, observation, and metadata
+ */
+export async function recordToolStep(params) {
+    const sessionManager = getSessionManager();
+    const sessionId = sessionManager.getSessionId() ?? '';
+    await knowledgeStore.recordStep({
+        sessionId,
+        toolName: params.toolName,
+        input: params.input,
+        target: params.target,
+        outcome: { ok: true },
+        observation: params.observation,
+        durationMs: Date.now() - params.startTime,
+        screenshotPath: params.screenshotPath,
+        screenshotDimensions: params.screenshotDimensions,
+    });
+}
+/**
+ * Collect observation data and record the tool step in the knowledge store.
+ *
+ * @param page - The page to collect observation from
+ * @param toolName - Name of the tool that was executed
+ * @param input - Input parameters passed to the tool
+ * @param startTime - Timestamp when the tool execution started
+ * @param options - Optional metadata for the step record
+ * @param options.target - Target element information
+ * @param options.screenshotPath - Path to screenshot file if captured
+ * @param options.screenshotDimensions - Screenshot dimensions
+ * @param options.screenshotDimensions.width - Screenshot width in pixels
+ * @param options.screenshotDimensions.height - Screenshot height in pixels
+ * @returns Observation data collected after tool execution
+ */
+export async function collectObservationAndRecord(page, toolName, input, startTime, options = {}) {
+    const observation = await collectObservation(page, 'full');
+    await recordToolStep({
+        toolName,
+        input,
+        startTime,
+        observation,
+        target: options.target,
+        screenshotPath: options.screenshotPath,
+        screenshotDimensions: options.screenshotDimensions,
+    });
+    return observation;
+}
+/**
+ * Handle tool execution errors and return appropriate error response.
+ *
+ * @param error - The error that occurred during tool execution
+ * @param defaultCode - Default error code to use if no specific match found
+ * @param defaultMessage - Default error message to use
+ * @param input - Input parameters that were passed to the tool
+ * @param sessionId - Current session ID for error context
+ * @param startTime - Timestamp when the tool execution started
+ * @returns Error response with appropriate code and message
+ */
+export function handleToolError(error, defaultCode, defaultMessage, input, sessionId, startTime) {
+    const message = extractErrorMessage(error);
+    if (message.includes('Unknown a11yRef') || message.includes('not found')) {
+        return createErrorResponse(ErrorCodes.MM_TARGET_NOT_FOUND, message, { input }, sessionId, startTime);
+    }
+    return createErrorResponse(defaultCode, `${defaultMessage}: ${message}`, { input }, sessionId, startTime);
+}
+//# sourceMappingURL=helpers.mjs.map

package/dist/mcp-server/tools/helpers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.mjs","sourceRoot":"","sources":["../../../src/mcp-server/tools/helpers.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Page } from '@playwright/test';\n\nimport type { ExtensionState } from '../../capabilities/types.js';\nimport { OBSERVATION_TESTID_LIMIT } from '../constants.js';\nimport { collectTestIds, collectTrimmedA11ySnapshot } from '../discovery.js';\nimport {\n  knowledgeStore,\n  createDefaultObservation,\n} from '../knowledge-store.js';\nimport { getSessionManager } from '../session-manager.js';\nimport type {\n  McpResponse,\n  ErrorCode,\n  TestIdItem,\n  StepRecordObservation,\n} from '../types';\nimport { ErrorCodes } from '../types';\nimport { createErrorResponse, extractErrorMessage, debugWarn } from '../utils';\n\n/**\n * Level of detail to collect for observation data.\n * - \"full\": Collect state, testIds, and a11y tree\n * - \"minimal\": Collect state only (no testIds or a11y)\n * - \"none\": Return empty observation\n */\nexport type ObservationLevel = 'full' | 'minimal' | 'none';\n\n/**\n * Parameters for recording a tool step in the knowledge store.\n */\nexport type RecordStepParams = {\n  /**\n   * Name of the tool that was executed\n   */\n  toolName: string;\n  /**\n   * Input parameters passed to the tool\n   */\n  input: Record<string, unknown>;\n  /**\n   * Timestamp when the tool execution started\n   */\n  startTime: number;\n  /**\n   * Observation data collected after tool execution\n   */\n  observation: StepRecordObservation;\n  /**\n   * Target element information (selector, testId, etc.)\n   */\n  target?: Record<string, string>;\n  /**\n   * Path to screenshot file if captured\n   */\n  screenshotPath?: string;\n  /**\n   * Screenshot dimensions if captured\n   */\n  screenshotDimensions?: {\n    /**\n     * Screenshot width in pixels\n     */\n    width: number;\n    /**\n     * Screenshot height in pixels\n     */\n    height: number;\n  };\n};\n\n/**\n * Context information for an active session.\n */\nexport type ActiveSessionContext = {\n  /**\n   * Unique session identifier\n   */\n  sessionId: string;\n  /**\n   * Current active page instance\n   */\n  page: Page;\n  /**\n   * Map of accessibility references to selectors\n   */\n  refMap: Map<string, string>;\n};\n\n/**\n * Check if an active session exists and return error if not.\n *\n * @param startTime - Timestamp when the operation started\n * @returns Error response if no active session, undefined otherwise\n */\nexport function requireActiveSession<Result>(\n  startTime: number,\n): McpResponse<Result> | undefined {\n  const sessionManager = getSessionManager();\n  if (!sessionManager.hasActiveSession()) {\n    return createErrorResponse(\n      ErrorCodes.MM_NO_ACTIVE_SESSION,\n      'No active session. Call launch first.',\n      undefined,\n      undefined,\n      startTime,\n    ) as McpResponse<Result>;\n  }\n  return undefined;\n}\n\n/**\n * Collect observation data from the current page state.\n *\n * @param page - The page to collect observation from\n * @param level - Level of detail to collect (full, minimal, or none)\n * @param presetState - Optional pre-fetched extension state to use instead of querying\n * @returns Observation data with state, testIds, and accessibility tree\n */\nexport async function collectObservation(\n  page: Page | undefined,\n  level: ObservationLevel,\n  presetState?: ExtensionState,\n): Promise<StepRecordObservation> {\n  const sessionManager = getSessionManager();\n\n  if (level === 'none') {\n    return createDefaultObservation({} as ExtensionState, [], []);\n  }\n\n  const state = presetState ?? (await sessionManager.getExtensionState());\n\n  if (level === 'minimal') {\n    return createDefaultObservation(state, [], []);\n  }\n\n  if (!page) {\n    debugWarn('collectObservation', 'Page not provided for full observation');\n    return createDefaultObservation(state, [], []);\n  }\n\n  try {\n    const testIds: TestIdItem[] = await collectTestIds(\n      page,\n      OBSERVATION_TESTID_LIMIT,\n    );\n    const { nodes, refMap } = await collectTrimmedA11ySnapshot(page);\n    sessionManager.setRefMap(refMap);\n    return createDefaultObservation(state, testIds, nodes);\n  } catch (error) {\n    debugWarn('collectObservation', error);\n    return createDefaultObservation(state, [], []);\n  }\n}\n\n/**\n * Wrapper that ensures an active session exists before executing a handler.\n *\n * @param handler - Function to execute with active session context\n * @returns Wrapped function that validates session before calling handler\n */\nexport function withActiveSession<TInput, TResult>(\n  handler: (\n    input: TInput,\n    ctx: ActiveSessionContext,\n    startTime: number,\n  ) => Promise<McpResponse<TResult>>,\n): (input: TInput) => Promise<McpResponse<TResult>> {\n  return async (input: TInput): Promise<McpResponse<TResult>> => {\n    const startTime = Date.now();\n    const sessionManager = getSessionManager();\n\n    const sessionError = requireActiveSession<TResult>(startTime);\n    if (sessionError) {\n      return sessionError;\n    }\n\n    const sessionId = sessionManager.getSessionId();\n    if (!sessionId) {\n      return createErrorResponse(\n        ErrorCodes.MM_NO_ACTIVE_SESSION,\n        'Session ID not found',\n        undefined,\n        undefined,\n        startTime,\n      ) as McpResponse<TResult>;\n    }\n    const page = sessionManager.getPage();\n    const refMap = sessionManager.getRefMap();\n\n    return handler(input, { sessionId, page, refMap }, startTime);\n  };\n}\n\n/**\n * Record a tool execution step in the knowledge store.\n *\n * @param params - Parameters containing tool name, input, observation, and metadata\n */\nexport async function recordToolStep(params: RecordStepParams): Promise<void> {\n  const sessionManager = getSessionManager();\n  const sessionId = sessionManager.getSessionId() ?? '';\n\n  await knowledgeStore.recordStep({\n    sessionId,\n    toolName: params.toolName,\n    input: params.input,\n    target: params.target,\n    outcome: { ok: true },\n    observation: params.observation,\n    durationMs: Date.now() - params.startTime,\n    screenshotPath: params.screenshotPath,\n    screenshotDimensions: params.screenshotDimensions,\n  });\n}\n\n/**\n * Collect observation data and record the tool step in the knowledge store.\n *\n * @param page - The page to collect observation from\n * @param toolName - Name of the tool that was executed\n * @param input - Input parameters passed to the tool\n * @param startTime - Timestamp when the tool execution started\n * @param options - Optional metadata for the step record\n * @param options.target - Target element information\n * @param options.screenshotPath - Path to screenshot file if captured\n * @param options.screenshotDimensions - Screenshot dimensions\n * @param options.screenshotDimensions.width - Screenshot width in pixels\n * @param options.screenshotDimensions.height - Screenshot height in pixels\n * @returns Observation data collected after tool execution\n */\nexport async function collectObservationAndRecord(\n  page: Page,\n  toolName: string,\n  input: Record<string, unknown>,\n  startTime: number,\n  options: {\n    /**\n     * Target element information (selector, testId, etc.)\n     */\n    target?: Record<string, string>;\n    /**\n     * Path to screenshot file if captured\n     */\n    screenshotPath?: string;\n    /**\n     * Screenshot dimensions if captured\n     */\n    screenshotDimensions?: {\n      /**\n       * Screenshot width in pixels\n       */\n      width: number;\n      /**\n       * Screenshot height in pixels\n       */\n      height: number;\n    };\n  } = {},\n): Promise<StepRecordObservation> {\n  const observation = await collectObservation(page, 'full');\n\n  await recordToolStep({\n    toolName,\n    input,\n    startTime,\n    observation,\n    target: options.target,\n    screenshotPath: options.screenshotPath,\n    screenshotDimensions: options.screenshotDimensions,\n  });\n\n  return observation;\n}\n\n/**\n * Handle tool execution errors and return appropriate error response.\n *\n * @param error - The error that occurred during tool execution\n * @param defaultCode - Default error code to use if no specific match found\n * @param defaultMessage - Default error message to use\n * @param input - Input parameters that were passed to the tool\n * @param sessionId - Current session ID for error context\n * @param startTime - Timestamp when the tool execution started\n * @returns Error response with appropriate code and message\n */\nexport function handleToolError<Result>(\n  error: unknown,\n  defaultCode: ErrorCode,\n  defaultMessage: string,\n  input: unknown,\n  sessionId: string | undefined,\n  startTime: number,\n): McpResponse<Result> {\n  const message = extractErrorMessage(error);\n\n  if (message.includes('Unknown a11yRef') || message.includes('not found')) {\n    return createErrorResponse(\n      ErrorCodes.MM_TARGET_NOT_FOUND,\n      message,\n      { input },\n      sessionId,\n      startTime,\n    ) as McpResponse<Result>;\n  }\n\n  return createErrorResponse(\n    defaultCode,\n    `${defaultMessage}: ${message}`,\n    { input },\n    sessionId,\n    startTime,\n  ) as McpResponse<Result>;\n}\n"]}

package/dist/mcp-server/tools/index.cjs

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./error-classification.cjs"), exports);
+__exportStar(require("./run-tool.cjs"), exports);
+__exportStar(require("./helpers.cjs"), exports);
+__exportStar(require("./interaction.cjs"), exports);
+__exportStar(require("./navigation.cjs"), exports);
+__exportStar(require("./discovery-tools.cjs"), exports);
+__exportStar(require("./screenshot.cjs"), exports);
+__exportStar(require("./knowledge.cjs"), exports);
+__exportStar(require("./batch.cjs"), exports);
+__exportStar(require("./clipboard.cjs"), exports);
+//# sourceMappingURL=index.cjs.map

package/dist/mcp-server/tools/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../../../src/mcp-server/tools/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6DAA0C;AAC1C,iDAA8B;AAC9B,gDAA6B;AAC7B,oDAAiC;AACjC,mDAAgC;AAChC,wDAAqC;AACrC,mDAAgC;AAChC,kDAA+B;AAC/B,8CAA2B;AAC3B,kDAA+B","sourcesContent":["export * from './error-classification.js';\nexport * from './run-tool.js';\nexport * from './helpers.js';\nexport * from './interaction.js';\nexport * from './navigation.js';\nexport * from './discovery-tools.js';\nexport * from './screenshot.js';\nexport * from './knowledge.js';\nexport * from './batch.js';\nexport * from './clipboard.js';\n"]}

package/dist/mcp-server/tools/index.d.cts

@@ -0,0 +1,11 @@
+export * from "./error-classification.cjs";
+export * from "./run-tool.cjs";
+export * from "./helpers.cjs";
+export * from "./interaction.cjs";
+export * from "./navigation.cjs";
+export * from "./discovery-tools.cjs";
+export * from "./screenshot.cjs";
+export * from "./knowledge.cjs";
+export * from "./batch.cjs";
+export * from "./clipboard.cjs";
+//# sourceMappingURL=index.d.cts.map

package/dist/mcp-server/tools/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../../src/mcp-server/tools/index.ts"],"names":[],"mappings":"AAAA,2CAA0C;AAC1C,+BAA8B;AAC9B,8BAA6B;AAC7B,kCAAiC;AACjC,iCAAgC;AAChC,sCAAqC;AACrC,iCAAgC;AAChC,gCAA+B;AAC/B,4BAA2B;AAC3B,gCAA+B"}

package/dist/mcp-server/tools/index.d.mts

@@ -0,0 +1,11 @@
+export * from "./error-classification.mjs";
+export * from "./run-tool.mjs";
+export * from "./helpers.mjs";
+export * from "./interaction.mjs";
+export * from "./navigation.mjs";
+export * from "./discovery-tools.mjs";
+export * from "./screenshot.mjs";
+export * from "./knowledge.mjs";
+export * from "./batch.mjs";
+export * from "./clipboard.mjs";
+//# sourceMappingURL=index.d.mts.map

package/dist/mcp-server/tools/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../src/mcp-server/tools/index.ts"],"names":[],"mappings":"AAAA,2CAA0C;AAC1C,+BAA8B;AAC9B,8BAA6B;AAC7B,kCAAiC;AACjC,iCAAgC;AAChC,sCAAqC;AACrC,iCAAgC;AAChC,gCAA+B;AAC/B,4BAA2B;AAC3B,gCAA+B"}

package/dist/mcp-server/tools/index.mjs

@@ -0,0 +1,11 @@
+export * from "./error-classification.mjs";
+export * from "./run-tool.mjs";
+export * from "./helpers.mjs";
+export * from "./interaction.mjs";
+export * from "./navigation.mjs";
+export * from "./discovery-tools.mjs";
+export * from "./screenshot.mjs";
+export * from "./knowledge.mjs";
+export * from "./batch.mjs";
+export * from "./clipboard.mjs";
+//# sourceMappingURL=index.mjs.map

package/dist/mcp-server/tools/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../../src/mcp-server/tools/index.ts"],"names":[],"mappings":"AAAA,2CAA0C;AAC1C,+BAA8B;AAC9B,8BAA6B;AAC7B,kCAAiC;AACjC,iCAAgC;AAChC,sCAAqC;AACrC,iCAAgC;AAChC,gCAA+B;AAC/B,4BAA2B;AAC3B,gCAA+B","sourcesContent":["export * from './error-classification.js';\nexport * from './run-tool.js';\nexport * from './helpers.js';\nexport * from './interaction.js';\nexport * from './navigation.js';\nexport * from './discovery-tools.js';\nexport * from './screenshot.js';\nexport * from './knowledge.js';\nexport * from './batch.js';\nexport * from './clipboard.js';\n"]}

package/dist/mcp-server/tools/interaction.cjs

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleClick = handleClick;
+exports.handleType = handleType;
+exports.handleWaitFor = handleWaitFor;
+const constants_js_1 = require("../constants.cjs");
+const discovery_js_1 = require("../discovery.cjs");
+const session_manager_js_1 = require("../session-manager.cjs");
+const error_classification_js_1 = require("./error-classification.cjs");
+const run_tool_js_1 = require("./run-tool.cjs");
+const types_1 = require("../types/index.cjs");
+const utils_1 = require("../utils/index.cjs");
+/**
+ * Handles clicking on an element specified by testId, selector, or accessibility reference.
+ *
+ * @param input The click input containing target selection and timeout options
+ * @param options Optional handler configuration
+ * @returns Promise resolving to click result with target information
+ */
+async function handleClick(input, options) {
+    const startTime = Date.now();
+    const sessionManager = (0, session_manager_js_1.getSessionManager)();
+    const sessionId = sessionManager.getSessionId();
+    const timeoutMs = input.timeoutMs ?? constants_js_1.DEFAULT_INTERACTION_TIMEOUT_MS;
+    const validation = (0, utils_1.validateTargetSelection)(input);
+    if ((0, utils_1.isInvalidTargetSelection)(validation)) {
+        return (0, utils_1.createErrorResponse)(types_1.ErrorCodes.MM_INVALID_INPUT, validation.error, { input }, sessionId, startTime);
+    }
+    if (!(0, utils_1.isValidTargetSelection)(validation)) {
+        return (0, utils_1.createErrorResponse)(types_1.ErrorCodes.MM_INVALID_INPUT, 'Invalid target selection', { input }, sessionId, startTime);
+    }
+    const { type: targetType, value: targetValue } = validation;
+    return (0, run_tool_js_1.runTool)({
+        toolName: 'mm_click',
+        input,
+        options,
+        /**
+         * Executes the click action on the target element.
+         *
+         * @param context The tool execution context containing page and reference map
+         * @returns Promise resolving to click result with success status and target info
+         */
+        execute: async (context) => {
+            const locator = await (0, discovery_js_1.waitForTarget)(context.page, targetType, targetValue, context.refMap, timeoutMs);
+            try {
+                await locator.click();
+                return {
+                    clicked: true,
+                    target: `${targetType}:${targetValue}`,
+                };
+            }
+            catch (clickError) {
+                if ((0, error_classification_js_1.isPageClosedError)(clickError)) {
+                    return {
+                        clicked: true,
+                        target: `${targetType}:${targetValue}`,
+                        pageClosedAfterClick: true,
+                    };
+                }
+                throw clickError;
+            }
+        },
+        /**
+         * Returns the target element information for recording.
+         *
+         * @returns Object containing the target type and value
+         */
+        getTarget: () => ({ [targetType]: targetValue }),
+        classifyError: error_classification_js_1.classifyClickError,
+        /**
+         * Sanitizes input for knowledge store recording.
+         *
+         * @returns Sanitized input object with timeout information
+         */
+        sanitizeInputForRecording: () => ({ timeoutMs }),
+    });
+}
+/**
+ * Handles typing text into an element specified by testId, selector, or accessibility reference.
+ *
+ * @param input The type input containing target selection, text, and timeout options
+ * @param options Optional handler configuration
+ * @returns Promise resolving to type result with target and text length information
+ */
+async function handleType(input, options) {
+    const startTime = Date.now();
+    const sessionManager = (0, session_manager_js_1.getSessionManager)();
+    const sessionId = sessionManager.getSessionId();
+    const timeoutMs = input.timeoutMs ?? constants_js_1.DEFAULT_INTERACTION_TIMEOUT_MS;
+    const validation = (0, utils_1.validateTargetSelection)(input);
+    if ((0, utils_1.isInvalidTargetSelection)(validation)) {
+        return (0, utils_1.createErrorResponse)(types_1.ErrorCodes.MM_INVALID_INPUT, validation.error, { input }, sessionId, startTime);
+    }
+    if (!(0, utils_1.isValidTargetSelection)(validation)) {
+        return (0, utils_1.createErrorResponse)(types_1.ErrorCodes.MM_INVALID_INPUT, 'Invalid target selection', { input }, sessionId, startTime);
+    }
+    const { type: targetType, value: targetValue } = validation;
+    return (0, run_tool_js_1.runTool)({
+        toolName: 'mm_type',
+        input,
+        options,
+        /**
+         * Executes the type action on the target element.
+         *
+         * @param context The tool execution context containing page and reference map
+         * @returns Promise resolving to type result with success status and text length
+         */
+        execute: async (context) => {
+            const locator = await (0, discovery_js_1.waitForTarget)(context.page, targetType, targetValue, context.refMap, timeoutMs);
+            await locator.fill(input.text);
+            return {
+                typed: true,
+                target: `${targetType}:${targetValue}`,
+                textLength: input.text.length,
+            };
+        },
+        /**
+         * Returns the target element information for recording.
+         *
+         * @returns Object containing the target type and value
+         */
+        getTarget: () => ({ [targetType]: targetValue }),
+        classifyError: error_classification_js_1.classifyTypeError,
+        /**
+         * Sanitizes input for knowledge store recording.
+         *
+         * @returns Sanitized input object with timeout and text information
+         */
+        sanitizeInputForRecording: () => ({
+            timeoutMs,
+            text: input.text,
+            testId: input.testId,
+            selector: input.selector,
+            a11yRef: input.a11yRef,
+        }),
+    });
+}
+/**
+ * Handles waiting for an element to become visible.
+ *
+ * @param input The wait input containing target selection and timeout options
+ * @param options Optional handler configuration
+ * @returns Promise resolving to wait result with target information
+ */
+async function handleWaitFor(input, options) {
+    const startTime = Date.now();
+    const sessionManager = (0, session_manager_js_1.getSessionManager)();
+    const sessionId = sessionManager.getSessionId();
+    const timeoutMs = input.timeoutMs ?? constants_js_1.DEFAULT_INTERACTION_TIMEOUT_MS;
+    const validation = (0, utils_1.validateTargetSelection)(input);
+    if ((0, utils_1.isInvalidTargetSelection)(validation)) {
+        return (0, utils_1.createErrorResponse)(types_1.ErrorCodes.MM_INVALID_INPUT, validation.error, { input }, sessionId, startTime);
+    }
+    if (!(0, utils_1.isValidTargetSelection)(validation)) {
+        return (0, utils_1.createErrorResponse)(types_1.ErrorCodes.MM_INVALID_INPUT, 'Invalid target selection', { input }, sessionId, startTime);
+    }
+    const { type: targetType, value: targetValue } = validation;
+    return (0, run_tool_js_1.runTool)({
+        toolName: 'mm_wait_for',
+        input,
+        options,
+        /**
+         * Executes the wait action for the target element.
+         *
+         * @param context The tool execution context containing page and reference map
+         * @returns Promise resolving to wait result with success status and target info
+         */
+        execute: async (context) => {
+            await (0, discovery_js_1.waitForTarget)(context.page, targetType, targetValue, context.refMap, timeoutMs);
+            return {
+                found: true,
+                target: `${targetType}:${targetValue}`,
+            };
+        },
+        /**
+         * Returns the target element information for recording.
+         *
+         * @returns Object containing the target type and value
+         */
+        getTarget: () => ({ [targetType]: targetValue }),
+        classifyError: error_classification_js_1.classifyWaitError,
+        /**
+         * Sanitizes input for knowledge store recording.
+         *
+         * @returns Sanitized input object with timeout information
+         */
+        sanitizeInputForRecording: () => ({ timeoutMs }),
+    });
+}
+//# sourceMappingURL=interaction.cjs.map

package/dist/mcp-server/tools/interaction.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction.cjs","sourceRoot":"","sources":["../../../src/mcp-server/tools/interaction.ts"],"names":[],"mappings":"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","sourcesContent":["import { DEFAULT_INTERACTION_TIMEOUT_MS } from '../constants.js';\nimport { waitForTarget } from '../discovery.js';\nimport { getSessionManager } from '../session-manager.js';\nimport {\n  classifyClickError,\n  classifyTypeError,\n  classifyWaitError,\n  isPageClosedError,\n} from './error-classification.js';\nimport { runTool } from './run-tool.js';\nimport type {\n  ClickInput,\n  ClickResult,\n  TypeInput,\n  TypeResult,\n  WaitForInput,\n  WaitForResult,\n  McpResponse,\n  HandlerOptions,\n} from '../types';\nimport { ErrorCodes } from '../types';\nimport {\n  createErrorResponse,\n  validateTargetSelection,\n  isValidTargetSelection,\n  isInvalidTargetSelection,\n} from '../utils';\n\n/**\n * Handles clicking on an element specified by testId, selector, or accessibility reference.\n *\n * @param input The click input containing target selection and timeout options\n * @param options Optional handler configuration\n * @returns Promise resolving to click result with target information\n */\nexport async function handleClick(\n  input: ClickInput,\n  options?: HandlerOptions,\n): Promise<McpResponse<ClickResult>> {\n  const startTime = Date.now();\n  const sessionManager = getSessionManager();\n  const sessionId = sessionManager.getSessionId();\n  const timeoutMs = input.timeoutMs ?? DEFAULT_INTERACTION_TIMEOUT_MS;\n\n  const validation = validateTargetSelection(input);\n  if (isInvalidTargetSelection(validation)) {\n    return createErrorResponse(\n      ErrorCodes.MM_INVALID_INPUT,\n      validation.error,\n      { input },\n      sessionId,\n      startTime,\n    );\n  }\n\n  if (!isValidTargetSelection(validation)) {\n    return createErrorResponse(\n      ErrorCodes.MM_INVALID_INPUT,\n      'Invalid target selection',\n      { input },\n      sessionId,\n      startTime,\n    );\n  }\n\n  const { type: targetType, value: targetValue } = validation;\n\n  return runTool<ClickInput, ClickResult>({\n    toolName: 'mm_click',\n    input,\n    options,\n\n    /**\n     * Executes the click action on the target element.\n     *\n     * @param context The tool execution context containing page and reference map\n     * @returns Promise resolving to click result with success status and target info\n     */\n    execute: async (context) => {\n      const locator = await waitForTarget(\n        context.page,\n        targetType,\n        targetValue,\n        context.refMap,\n        timeoutMs,\n      );\n\n      try {\n        await locator.click();\n        return {\n          clicked: true,\n          target: `${targetType}:${targetValue}`,\n        };\n      } catch (clickError) {\n        if (isPageClosedError(clickError)) {\n          return {\n            clicked: true,\n            target: `${targetType}:${targetValue}`,\n            pageClosedAfterClick: true,\n          };\n        }\n        throw clickError;\n      }\n    },\n\n    /**\n     * Returns the target element information for recording.\n     *\n     * @returns Object containing the target type and value\n     */\n    getTarget: () => ({ [targetType]: targetValue }),\n\n    classifyError: classifyClickError,\n\n    /**\n     * Sanitizes input for knowledge store recording.\n     *\n     * @returns Sanitized input object with timeout information\n     */\n    sanitizeInputForRecording: () => ({ timeoutMs }),\n  });\n}\n\n/**\n * Handles typing text into an element specified by testId, selector, or accessibility reference.\n *\n * @param input The type input containing target selection, text, and timeout options\n * @param options Optional handler configuration\n * @returns Promise resolving to type result with target and text length information\n */\nexport async function handleType(\n  input: TypeInput,\n  options?: HandlerOptions,\n): Promise<McpResponse<TypeResult>> {\n  const startTime = Date.now();\n  const sessionManager = getSessionManager();\n  const sessionId = sessionManager.getSessionId();\n  const timeoutMs = input.timeoutMs ?? DEFAULT_INTERACTION_TIMEOUT_MS;\n\n  const validation = validateTargetSelection(input);\n  if (isInvalidTargetSelection(validation)) {\n    return createErrorResponse(\n      ErrorCodes.MM_INVALID_INPUT,\n      validation.error,\n      { input },\n      sessionId,\n      startTime,\n    );\n  }\n\n  if (!isValidTargetSelection(validation)) {\n    return createErrorResponse(\n      ErrorCodes.MM_INVALID_INPUT,\n      'Invalid target selection',\n      { input },\n      sessionId,\n      startTime,\n    );\n  }\n\n  const { type: targetType, value: targetValue } = validation;\n\n  return runTool<TypeInput, TypeResult>({\n    toolName: 'mm_type',\n    input,\n    options,\n\n    /**\n     * Executes the type action on the target element.\n     *\n     * @param context The tool execution context containing page and reference map\n     * @returns Promise resolving to type result with success status and text length\n     */\n    execute: async (context) => {\n      const locator = await waitForTarget(\n        context.page,\n        targetType,\n        targetValue,\n        context.refMap,\n        timeoutMs,\n      );\n      await locator.fill(input.text);\n\n      return {\n        typed: true,\n        target: `${targetType}:${targetValue}`,\n        textLength: input.text.length,\n      };\n    },\n\n    /**\n     * Returns the target element information for recording.\n     *\n     * @returns Object containing the target type and value\n     */\n    getTarget: () => ({ [targetType]: targetValue }),\n\n    classifyError: classifyTypeError,\n\n    /**\n     * Sanitizes input for knowledge store recording.\n     *\n     * @returns Sanitized input object with timeout and text information\n     */\n    sanitizeInputForRecording: () => ({\n      timeoutMs,\n      text: input.text,\n      testId: input.testId,\n      selector: input.selector,\n      a11yRef: input.a11yRef,\n    }),\n  });\n}\n\n/**\n * Handles waiting for an element to become visible.\n *\n * @param input The wait input containing target selection and timeout options\n * @param options Optional handler configuration\n * @returns Promise resolving to wait result with target information\n */\nexport async function handleWaitFor(\n  input: WaitForInput,\n  options?: HandlerOptions,\n): Promise<McpResponse<WaitForResult>> {\n  const startTime = Date.now();\n  const sessionManager = getSessionManager();\n  const sessionId = sessionManager.getSessionId();\n  const timeoutMs = input.timeoutMs ?? DEFAULT_INTERACTION_TIMEOUT_MS;\n\n  const validation = validateTargetSelection(input);\n  if (isInvalidTargetSelection(validation)) {\n    return createErrorResponse(\n      ErrorCodes.MM_INVALID_INPUT,\n      validation.error,\n      { input },\n      sessionId,\n      startTime,\n    );\n  }\n\n  if (!isValidTargetSelection(validation)) {\n    return createErrorResponse(\n      ErrorCodes.MM_INVALID_INPUT,\n      'Invalid target selection',\n      { input },\n      sessionId,\n      startTime,\n    );\n  }\n\n  const { type: targetType, value: targetValue } = validation;\n\n  return runTool<WaitForInput, WaitForResult>({\n    toolName: 'mm_wait_for',\n    input,\n    options,\n\n    /**\n     * Executes the wait action for the target element.\n     *\n     * @param context The tool execution context containing page and reference map\n     * @returns Promise resolving to wait result with success status and target info\n     */\n    execute: async (context) => {\n      await waitForTarget(\n        context.page,\n        targetType,\n        targetValue,\n        context.refMap,\n        timeoutMs,\n      );\n\n      return {\n        found: true,\n        target: `${targetType}:${targetValue}`,\n      };\n    },\n\n    /**\n     * Returns the target element information for recording.\n     *\n     * @returns Object containing the target type and value\n     */\n    getTarget: () => ({ [targetType]: targetValue }),\n\n    classifyError: classifyWaitError,\n\n    /**\n     * Sanitizes input for knowledge store recording.\n     *\n     * @returns Sanitized input object with timeout information\n     */\n    sanitizeInputForRecording: () => ({ timeoutMs }),\n  });\n}\n"]}

package/dist/mcp-server/tools/interaction.d.cts

@@ -0,0 +1,26 @@
+import type { ClickInput, ClickResult, TypeInput, TypeResult, WaitForInput, WaitForResult, McpResponse, HandlerOptions } from "../types/index.cjs";
+/**
+ * Handles clicking on an element specified by testId, selector, or accessibility reference.
+ *
+ * @param input The click input containing target selection and timeout options
+ * @param options Optional handler configuration
+ * @returns Promise resolving to click result with target information
+ */
+export declare function handleClick(input: ClickInput, options?: HandlerOptions): Promise<McpResponse<ClickResult>>;
+/**
+ * Handles typing text into an element specified by testId, selector, or accessibility reference.
+ *
+ * @param input The type input containing target selection, text, and timeout options
+ * @param options Optional handler configuration
+ * @returns Promise resolving to type result with target and text length information
+ */
+export declare function handleType(input: TypeInput, options?: HandlerOptions): Promise<McpResponse<TypeResult>>;
+/**
+ * Handles waiting for an element to become visible.
+ *
+ * @param input The wait input containing target selection and timeout options
+ * @param options Optional handler configuration
+ * @returns Promise resolving to wait result with target information
+ */
+export declare function handleWaitFor(input: WaitForInput, options?: HandlerOptions): Promise<McpResponse<WaitForResult>>;
+//# sourceMappingURL=interaction.d.cts.map