@xiuchang-midscene/shared 2.0.2

package/dist/types/mcp/base-tools.d.ts

@@ -0,0 +1,79 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BaseAgent, BaseDevice, IMidsceneTools, ToolDefinition } from './types';
+/**
+ * Base class for platform-specific MCP tools
+ * Generic type TAgent allows subclasses to use their specific agent types
+ */
+export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent> implements IMidsceneTools {
+    protected mcpServer?: McpServer;
+    protected agent?: TAgent;
+    protected toolDefinitions: ToolDefinition[];
+    /**
+     * Ensure agent is initialized and ready for use.
+     * Must be implemented by subclasses to create platform-specific agent.
+     * @param initParam Optional initialization parameter (platform-specific, e.g., URL, device ID)
+     * @returns Promise resolving to initialized agent instance
+     * @throws Error if agent initialization fails
+     */
+    protected abstract ensureAgent(initParam?: string): Promise<TAgent>;
+    /**
+     * Optional: prepare platform-specific tools (e.g., device connection)
+     */
+    protected preparePlatformTools(): ToolDefinition[];
+    /**
+     * Must be implemented by subclasses to create a temporary device instance
+     * This allows getting real actionSpace without connecting to device
+     */
+    protected abstract createTemporaryDevice(): BaseDevice;
+    /**
+     * Initialize all tools by querying actionSpace
+     * Uses two-layer fallback strategy:
+     * 1. Try to get actionSpace from connected agent (if available)
+     * 2. Create temporary device instance to read actionSpace (always succeeds)
+     */
+    initTools(): Promise<void>;
+    /**
+     * Attach to MCP server and register all tools
+     */
+    attachToServer(server: McpServer): void;
+    /**
+     * Cleanup method - destroy agent and release resources
+     */
+    destroy(): Promise<void>;
+    /**
+     * Get tool definitions
+     */
+    getToolDefinitions(): ToolDefinition[];
+    /**
+     * Set agent for the tools manager
+     */
+    setAgent(agent: TAgent): void;
+    /**
+     * Helper: Convert base64 screenshot to image content array
+     */
+    protected buildScreenshotContent(screenshot: string): {
+        type: "image";
+        data: string;
+        mimeType: string;
+    }[];
+    /**
+     * Helper: Build a simple text result for tool responses
+     */
+    protected buildTextResult(text: string): {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    };
+    /**
+     * Create a disconnect handler for releasing platform resources
+     * @param platformName Human-readable platform name for the response message
+     * @returns Handler function that destroys the agent and returns appropriate response
+     */
+    protected createDisconnectHandler(platformName: string): () => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+}

package/dist/types/mcp/base-tools.d.ts.bak

@@ -0,0 +1,79 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BaseAgent, BaseDevice, IMidsceneTools, ToolDefinition } from './types';
+/**
+ * Base class for platform-specific MCP tools
+ * Generic type TAgent allows subclasses to use their specific agent types
+ */
+export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent> implements IMidsceneTools {
+    protected mcpServer?: McpServer;
+    protected agent?: TAgent;
+    protected toolDefinitions: ToolDefinition[];
+    /**
+     * Ensure agent is initialized and ready for use.
+     * Must be implemented by subclasses to create platform-specific agent.
+     * @param initParam Optional initialization parameter (platform-specific, e.g., URL, device ID)
+     * @returns Promise resolving to initialized agent instance
+     * @throws Error if agent initialization fails
+     */
+    protected abstract ensureAgent(initParam?: string): Promise<TAgent>;
+    /**
+     * Optional: prepare platform-specific tools (e.g., device connection)
+     */
+    protected preparePlatformTools(): ToolDefinition[];
+    /**
+     * Must be implemented by subclasses to create a temporary device instance
+     * This allows getting real actionSpace without connecting to device
+     */
+    protected abstract createTemporaryDevice(): BaseDevice;
+    /**
+     * Initialize all tools by querying actionSpace
+     * Uses two-layer fallback strategy:
+     * 1. Try to get actionSpace from connected agent (if available)
+     * 2. Create temporary device instance to read actionSpace (always succeeds)
+     */
+    initTools(): Promise<void>;
+    /**
+     * Attach to MCP server and register all tools
+     */
+    attachToServer(server: McpServer): void;
+    /**
+     * Cleanup method - destroy agent and release resources
+     */
+    destroy(): Promise<void>;
+    /**
+     * Get tool definitions
+     */
+    getToolDefinitions(): ToolDefinition[];
+    /**
+     * Set agent for the tools manager
+     */
+    setAgent(agent: TAgent): void;
+    /**
+     * Helper: Convert base64 screenshot to image content array
+     */
+    protected buildScreenshotContent(screenshot: string): {
+        type: "image";
+        data: string;
+        mimeType: string;
+    }[];
+    /**
+     * Helper: Build a simple text result for tool responses
+     */
+    protected buildTextResult(text: string): {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    };
+    /**
+     * Create a disconnect handler for releasing platform resources
+     * @param platformName Human-readable platform name for the response message
+     * @returns Handler function that destroys the agent and returns appropriate response
+     */
+    protected createDisconnectHandler(platformName: string): () => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+}

package/dist/types/mcp/chrome-path.d.ts

@@ -0,0 +1,2 @@
+export declare function getSystemChromePath(): string | undefined;
+export declare function resolveChromePath(): string;

package/dist/types/mcp/chrome-path.d.ts.bak

@@ -0,0 +1,2 @@
+export declare function getSystemChromePath(): string | undefined;
+export declare function resolveChromePath(): string;

package/dist/types/mcp/index.d.ts

@@ -0,0 +1,7 @@
+export * from './base-server';
+export * from './base-tools';
+export * from './tool-generator';
+export * from './types';
+export * from './inject-report-html-plugin';
+export * from './launcher-helper';
+export * from './chrome-path';

package/dist/types/mcp/index.d.ts.bak

@@ -0,0 +1,7 @@
+export * from './base-server';
+export * from './base-tools';
+export * from './tool-generator';
+export * from './types';
+export * from './inject-report-html-plugin';
+export * from './launcher-helper';
+export * from './chrome-path';

package/dist/types/mcp/inject-report-html-plugin.d.ts

@@ -0,0 +1,18 @@
+interface RslibPluginApi {
+    onAfterBuild: (callback: () => void) => void;
+}
+/**
+ * Rslib plugin to inject report HTML from @xiuchang-midscene/core dist into MCP bundle.
+ * This runs after build and reads the already-injected HTML from core.
+ *
+ * Prerequisites:
+ * - @midscene/report must be in devDependencies to ensure correct build order
+ * - @xiuchang-midscene/core dist must exist with injected HTML
+ *
+ * @param packageDir - The directory of the MCP package (use __dirname)
+ */
+export declare function injectReportHtmlFromCore(packageDir: string): {
+    name: string;
+    setup(api: RslibPluginApi): void;
+};
+export {};

package/dist/types/mcp/inject-report-html-plugin.d.ts.bak

@@ -0,0 +1,18 @@
+interface RslibPluginApi {
+    onAfterBuild: (callback: () => void) => void;
+}
+/**
+ * Rslib plugin to inject report HTML from @midscene/core dist into MCP bundle.
+ * This runs after build and reads the already-injected HTML from core.
+ *
+ * Prerequisites:
+ * - @midscene/report must be in devDependencies to ensure correct build order
+ * - @midscene/core dist must exist with injected HTML
+ *
+ * @param packageDir - The directory of the MCP package (use __dirname)
+ */
+export declare function injectReportHtmlFromCore(packageDir: string): {
+    name: string;
+    setup(api: RslibPluginApi): void;
+};
+export {};

package/dist/types/mcp/launcher-helper.d.ts

@@ -0,0 +1,94 @@
+import type { BaseMCPServer } from './base-server';
+import type { HttpLaunchOptions, LaunchMCPServerResult } from './base-server';
+import type { IMidsceneTools } from './types';
+export interface LaunchMCPServerOptions extends HttpLaunchOptions {
+    /**
+     * Whether to show server logs
+     * @default true
+     */
+    verbose?: boolean;
+}
+/**
+ * Generic agent type (avoid importing from @xiuchang-midscene/core to prevent circular deps)
+ */
+export interface GenericAgent<TDevice = any> {
+    interface: TDevice;
+    constructor: {
+        name: string;
+    };
+}
+/**
+ * Additional information for logging server startup
+ */
+export interface StartupInfo {
+    port?: number;
+    host?: string;
+}
+export interface MCPServerLauncherConfig<AgentType extends GenericAgent = GenericAgent, ToolsManagerType extends IMidsceneTools = IMidsceneTools> {
+    agent: AgentType;
+    platformName: string;
+    ToolsManagerClass: new (...args: any[]) => ToolsManagerType;
+    MCPServerClass: new (toolsManager?: ToolsManagerType) => BaseMCPServer;
+}
+/**
+ * Create a generic MCP server launcher for a given agent, tools manager, and MCP server.
+ *
+ * This helper centralizes the common wiring logic used by platform-specific launchers:
+ * it constructs a tools manager, attaches the provided `agent` to it, then instantiates
+ * the `MCPServerClass` and exposes convenience methods to start the server over stdio
+ * (`launch`) or HTTP (`launchHttp`).
+ *
+ * Use this helper when adding a new platform-specific launcher or when you want to
+ * avoid duplicating boilerplate code for starting an MCP server. Typically, callers
+ * provide:
+ * - an `agent` instance that contains the underlying device on its `interface` property
+ * - a `ToolsManagerClass` that knows how to expose tools for that agent
+ * - an `MCPServerClass` that implements the MCP protocol and supports `launch` and
+ *   `launchHttp` methods.
+ *
+ * The returned object has two methods:
+ * - `launch(options?)` to start the server using stdio transport
+ * - `launchHttp(options)` to start the server using HTTP transport
+ * Both methods accept a `verbose` flag to control console logging.
+ *
+ * @param config Configuration describing the agent, platform name (for logging),
+ *               tools manager implementation, and MCP server implementation.
+ *
+ * @returns An object with `launch` and `launchHttp` methods to start the MCP server.
+ *
+ * @example
+ * ```typescript
+ * import { createMCPServerLauncher } from '@xiuchang-midscene/shared/mcp';
+ * import { Agent } from '@xiuchang-midscene/core/agent';
+ * import { WebMidsceneTools } from './web-tools';
+ * import { WebMCPServer } from './server';
+ *
+ * const agent = new Agent();
+ * const launcher = createMCPServerLauncher({
+ *   agent,
+ *   platformName: 'Web',
+ *   ToolsManagerClass: WebMidsceneTools,
+ *   MCPServerClass: WebMCPServer,
+ * });
+ *
+ * // Start with stdio
+ * await launcher.launch({ verbose: true });
+ *
+ * // Or start with HTTP
+ * await launcher.launchHttp({ port: 3000, host: 'localhost' });
+ * ```
+ *
+ * @internal
+ */
+export declare function createMCPServerLauncher<AgentType extends GenericAgent, ToolsManagerType extends IMidsceneTools>(config: MCPServerLauncherConfig<AgentType, ToolsManagerType>): {
+    /**
+     * Launch the MCP server with stdio transport
+     */
+    launch(options?: {
+        verbose?: boolean;
+    }): Promise<LaunchMCPServerResult>;
+    /**
+     * Launch the MCP server with HTTP transport
+     */
+    launchHttp(options: LaunchMCPServerOptions): Promise<LaunchMCPServerResult>;
+};

package/dist/types/mcp/launcher-helper.d.ts.bak

@@ -0,0 +1,94 @@
+import type { BaseMCPServer } from './base-server';
+import type { HttpLaunchOptions, LaunchMCPServerResult } from './base-server';
+import type { IMidsceneTools } from './types';
+export interface LaunchMCPServerOptions extends HttpLaunchOptions {
+    /**
+     * Whether to show server logs
+     * @default true
+     */
+    verbose?: boolean;
+}
+/**
+ * Generic agent type (avoid importing from @midscene/core to prevent circular deps)
+ */
+export interface GenericAgent<TDevice = any> {
+    interface: TDevice;
+    constructor: {
+        name: string;
+    };
+}
+/**
+ * Additional information for logging server startup
+ */
+export interface StartupInfo {
+    port?: number;
+    host?: string;
+}
+export interface MCPServerLauncherConfig<AgentType extends GenericAgent = GenericAgent, ToolsManagerType extends IMidsceneTools = IMidsceneTools> {
+    agent: AgentType;
+    platformName: string;
+    ToolsManagerClass: new (...args: any[]) => ToolsManagerType;
+    MCPServerClass: new (toolsManager?: ToolsManagerType) => BaseMCPServer;
+}
+/**
+ * Create a generic MCP server launcher for a given agent, tools manager, and MCP server.
+ *
+ * This helper centralizes the common wiring logic used by platform-specific launchers:
+ * it constructs a tools manager, attaches the provided `agent` to it, then instantiates
+ * the `MCPServerClass` and exposes convenience methods to start the server over stdio
+ * (`launch`) or HTTP (`launchHttp`).
+ *
+ * Use this helper when adding a new platform-specific launcher or when you want to
+ * avoid duplicating boilerplate code for starting an MCP server. Typically, callers
+ * provide:
+ * - an `agent` instance that contains the underlying device on its `interface` property
+ * - a `ToolsManagerClass` that knows how to expose tools for that agent
+ * - an `MCPServerClass` that implements the MCP protocol and supports `launch` and
+ *   `launchHttp` methods.
+ *
+ * The returned object has two methods:
+ * - `launch(options?)` to start the server using stdio transport
+ * - `launchHttp(options)` to start the server using HTTP transport
+ * Both methods accept a `verbose` flag to control console logging.
+ *
+ * @param config Configuration describing the agent, platform name (for logging),
+ *               tools manager implementation, and MCP server implementation.
+ *
+ * @returns An object with `launch` and `launchHttp` methods to start the MCP server.
+ *
+ * @example
+ * ```typescript
+ * import { createMCPServerLauncher } from '@midscene/shared/mcp';
+ * import { Agent } from '@midscene/core/agent';
+ * import { WebMidsceneTools } from './web-tools';
+ * import { WebMCPServer } from './server';
+ *
+ * const agent = new Agent();
+ * const launcher = createMCPServerLauncher({
+ *   agent,
+ *   platformName: 'Web',
+ *   ToolsManagerClass: WebMidsceneTools,
+ *   MCPServerClass: WebMCPServer,
+ * });
+ *
+ * // Start with stdio
+ * await launcher.launch({ verbose: true });
+ *
+ * // Or start with HTTP
+ * await launcher.launchHttp({ port: 3000, host: 'localhost' });
+ * ```
+ *
+ * @internal
+ */
+export declare function createMCPServerLauncher<AgentType extends GenericAgent, ToolsManagerType extends IMidsceneTools>(config: MCPServerLauncherConfig<AgentType, ToolsManagerType>): {
+    /**
+     * Launch the MCP server with stdio transport
+     */
+    launch(options?: {
+        verbose?: boolean;
+    }): Promise<LaunchMCPServerResult>;
+    /**
+     * Launch the MCP server with HTTP transport
+     */
+    launchHttp(options: LaunchMCPServerOptions): Promise<LaunchMCPServerResult>;
+};

package/dist/types/mcp/tool-generator.d.ts

@@ -0,0 +1,10 @@
+import type { ActionSpaceItem, BaseAgent, ToolDefinition } from './types';
+/**
+ * Converts DeviceAction from actionSpace into MCP ToolDefinition
+ * This is the core logic that removes need for hardcoded tool definitions
+ */
+export declare function generateToolsFromActionSpace(actionSpace: ActionSpaceItem[], getAgent: () => Promise<BaseAgent>): ToolDefinition[];
+/**
+ * Generate common tools (screenshot, act)
+ */
+export declare function generateCommonTools(getAgent: () => Promise<BaseAgent>): ToolDefinition[];

package/dist/types/mcp/tool-generator.d.ts.bak

@@ -0,0 +1,10 @@
+import type { ActionSpaceItem, BaseAgent, ToolDefinition } from './types';
+/**
+ * Converts DeviceAction from actionSpace into MCP ToolDefinition
+ * This is the core logic that removes need for hardcoded tool definitions
+ */
+export declare function generateToolsFromActionSpace(actionSpace: ActionSpaceItem[], getAgent: () => Promise<BaseAgent>): ToolDefinition[];
+/**
+ * Generate common tools (screenshot, act)
+ */
+export declare function generateCommonTools(getAgent: () => Promise<BaseAgent>): ToolDefinition[];

package/dist/types/mcp/types.d.ts

@@ -0,0 +1,103 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { z } from 'zod';
+/**
+ * Default timeout constants for app loading verification
+ */
+export declare const defaultAppLoadingTimeoutMs = 10000;
+export declare const defaultAppLoadingCheckIntervalMs = 2000;
+/**
+ * Content item types for tool results (MCP compatible)
+ */
+export type ToolResultContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+} | {
+    type: 'audio';
+    data: string;
+    mimeType: string;
+} | {
+    type: 'resource';
+    resource: {
+        text: string;
+        uri: string;
+        mimeType?: string;
+    } | {
+        uri: string;
+        blob: string;
+        mimeType?: string;
+    };
+};
+/**
+ * Result type for tool execution (MCP compatible)
+ */
+export interface ToolResult {
+    [x: string]: unknown;
+    content: ToolResultContent[];
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Tool handler function type
+ * Takes parsed arguments and returns a tool result
+ */
+export type ToolHandler<T = Record<string, unknown>> = (args: T) => Promise<ToolResult>;
+/**
+ * Tool schema type using Zod
+ */
+export type ToolSchema = Record<string, z.ZodTypeAny>;
+/**
+ * Tool definition for MCP server
+ */
+export interface ToolDefinition<T = Record<string, unknown>> {
+    name: string;
+    description: string;
+    schema: ToolSchema;
+    handler: ToolHandler<T>;
+}
+/**
+ * Tool type for mcpKitForAgent return value
+ */
+export type Tool = ToolDefinition;
+/**
+ * Action space item definition
+ * Note: Intentionally no index signature to maintain compatibility with DeviceAction
+ */
+export interface ActionSpaceItem {
+    name: string;
+    description?: string;
+    args?: Record<string, unknown>;
+    paramSchema?: z.ZodTypeAny;
+}
+/**
+ * Base agent interface
+ * Represents a platform-specific agent (Android, iOS, Web)
+ * Note: Return types use `unknown` for compatibility with platform-specific implementations
+ */
+export interface BaseAgent {
+    getActionSpace(): Promise<ActionSpaceItem[]>;
+    destroy?(): Promise<void>;
+    page?: {
+        screenshotBase64(): Promise<string>;
+    };
+    aiAction?: (description: string, params?: Record<string, unknown>) => Promise<unknown>;
+    aiWaitFor?: (assertion: string, options: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Base device interface for temporary device instances
+ */
+export interface BaseDevice {
+    actionSpace(): ActionSpaceItem[];
+    destroy?(): Promise<void>;
+}
+/**
+ * Interface for platform-specific MCP tools manager
+ */
+export interface IMidsceneTools {
+    attachToServer(server: McpServer): void;
+    initTools(): Promise<void>;
+    destroy?(): Promise<void>;
+}

package/dist/types/mcp/types.d.ts.bak

@@ -0,0 +1,103 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { z } from 'zod';
+/**
+ * Default timeout constants for app loading verification
+ */
+export declare const defaultAppLoadingTimeoutMs = 10000;
+export declare const defaultAppLoadingCheckIntervalMs = 2000;
+/**
+ * Content item types for tool results (MCP compatible)
+ */
+export type ToolResultContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+} | {
+    type: 'audio';
+    data: string;
+    mimeType: string;
+} | {
+    type: 'resource';
+    resource: {
+        text: string;
+        uri: string;
+        mimeType?: string;
+    } | {
+        uri: string;
+        blob: string;
+        mimeType?: string;
+    };
+};
+/**
+ * Result type for tool execution (MCP compatible)
+ */
+export interface ToolResult {
+    [x: string]: unknown;
+    content: ToolResultContent[];
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Tool handler function type
+ * Takes parsed arguments and returns a tool result
+ */
+export type ToolHandler<T = Record<string, unknown>> = (args: T) => Promise<ToolResult>;
+/**
+ * Tool schema type using Zod
+ */
+export type ToolSchema = Record<string, z.ZodTypeAny>;
+/**
+ * Tool definition for MCP server
+ */
+export interface ToolDefinition<T = Record<string, unknown>> {
+    name: string;
+    description: string;
+    schema: ToolSchema;
+    handler: ToolHandler<T>;
+}
+/**
+ * Tool type for mcpKitForAgent return value
+ */
+export type Tool = ToolDefinition;
+/**
+ * Action space item definition
+ * Note: Intentionally no index signature to maintain compatibility with DeviceAction
+ */
+export interface ActionSpaceItem {
+    name: string;
+    description?: string;
+    args?: Record<string, unknown>;
+    paramSchema?: z.ZodTypeAny;
+}
+/**
+ * Base agent interface
+ * Represents a platform-specific agent (Android, iOS, Web)
+ * Note: Return types use `unknown` for compatibility with platform-specific implementations
+ */
+export interface BaseAgent {
+    getActionSpace(): Promise<ActionSpaceItem[]>;
+    destroy?(): Promise<void>;
+    page?: {
+        screenshotBase64(): Promise<string>;
+    };
+    aiAction?: (description: string, params?: Record<string, unknown>) => Promise<unknown>;
+    aiWaitFor?: (assertion: string, options: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Base device interface for temporary device instances
+ */
+export interface BaseDevice {
+    actionSpace(): ActionSpaceItem[];
+    destroy?(): Promise<void>;
+}
+/**
+ * Interface for platform-specific MCP tools manager
+ */
+export interface IMidsceneTools {
+    attachToServer(server: McpServer): void;
+    initTools(): Promise<void>;
+    destroy?(): Promise<void>;
+}

package/dist/types/node/fs.d.ts

@@ -0,0 +1,15 @@
+interface PkgInfo {
+    name: string;
+    version: string;
+    dir: string;
+}
+export declare function getRunningPkgInfo(dir?: string): PkgInfo | null;
+/**
+ * Find the nearest package.json file recursively
+ * @param {string} dir - Home directory
+ * @returns {string|null} - The most recent package.json file path or null
+ */
+export declare function findNearestPackageJson(dir: string): string | null;
+export declare function getElementInfosScriptContent(): string;
+export declare function getExtraReturnLogic(tree?: boolean): Promise<string | null>;
+export {};

package/dist/types/node/fs.d.ts.bak

@@ -0,0 +1,15 @@
+interface PkgInfo {
+    name: string;
+    version: string;
+    dir: string;
+}
+export declare function getRunningPkgInfo(dir?: string): PkgInfo | null;
+/**
+ * Find the nearest package.json file recursively
+ * @param {string} dir - Home directory
+ * @returns {string|null} - The most recent package.json file path or null
+ */
+export declare function findNearestPackageJson(dir: string): string | null;
+export declare function getElementInfosScriptContent(): string;
+export declare function getExtraReturnLogic(tree?: boolean): Promise<string | null>;
+export {};

package/dist/types/node/index.d.ts

@@ -0,0 +1,2 @@
+export * from './fs';
+export * from './port';

package/dist/types/node/index.d.ts.bak

@@ -0,0 +1,2 @@
+export * from './fs';
+export * from './port';