@midscene/shared 1.0.1-beta-20251208112226.0 → 1.0.1-beta-20251209112631.0

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

@@ -0,0 +1,55 @@
+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;
+    /**
+     * Wrapper for auto-destroy behavior
+     */
+    private toolWithAutoDestroy;
+    /**
+     * Cleanup method - destroy agent and release resources
+     */
+    closeBrowser(): Promise<void>;
+    /**
+     * Helper: Convert base64 screenshot to image content array
+     */
+    protected buildScreenshotContent(screenshot: string): {
+        type: "image";
+        data: string;
+        mimeType: string;
+    }[];
+}

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

@@ -0,0 +1,5 @@
+export * from './base-server';
+export * from './base-tools';
+export * from './tool-generator';
+export * from './types';
+export * from './inject-report-html-plugin';

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 @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/tool-generator.d.ts

@@ -0,0 +1,11 @@
+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, waitFor)
+ * SIMPLIFIED: Only keep essential helper tools, removed assert
+ */
+export declare function generateCommonTools(getAgent: () => Promise<BaseAgent>): ToolDefinition[];

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

@@ -0,0 +1,100 @@
+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>;
+    autoDestroy?: boolean;
+}
+/**
+ * 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>;
+    closeBrowser?(): Promise<void>;
+}

package/dist/types/zod-schema-utils.d.ts

@@ -0,0 +1,23 @@
+import type { z } from 'zod';
+/**
+ * Recursively unwrap optional, nullable, default, and effects wrapper types
+ * to get the actual inner Zod type
+ */
+export declare function unwrapZodField(field: unknown): unknown;
+/**
+ * Check if a field is a Midscene locator field
+ * Checks for either:
+ * 1. midscene_location_field_flag in shape (result schema)
+ * 2. prompt field in shape (input schema)
+ */
+export declare function isMidsceneLocatorField(field: unknown): boolean;
+/**
+ * Get type name string from a Zod schema field
+ * @param field - Zod schema field
+ * @param locatorTypeDescription - Optional description for MidsceneLocation fields (used by core)
+ */
+export declare function getZodTypeName(field: unknown, locatorTypeDescription?: string): string;
+/**
+ * Get description from a Zod schema field
+ */
+export declare function getZodDescription(field: z.ZodTypeAny): string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/shared",
-  "version": "1.0.1-beta-20251208112226.0",
+  "version": "1.0.1-beta-20251209112631.0",
   "repository": "https://github.com/web-infra-dev/midscene",
   "homepage": "https://midscenejs.com/",
   "types": "./dist/types/index.d.ts",
@@ -57,6 +57,16 @@
       "import": "./dist/es/common.mjs",
       "require": "./dist/lib/common.js"
     },
+    "./mcp": {
+      "types": "./dist/types/mcp/index.d.ts",
+      "import": "./dist/es/mcp/index.mjs",
+      "require": "./dist/lib/mcp/index.js"
+    },
+    "./logger": {
+      "types": "./dist/types/logger.d.ts",
+      "import": "./dist/es/logger.mjs",
+      "require": "./dist/lib/logger.js"
+    },
     "./*": {
       "types": "./dist/types/*.d.ts",
       "import": "./dist/es/*.mjs",
@@ -72,21 +82,25 @@
     "@silvia-odwyer/photon": "0.3.3",
     "@silvia-odwyer/photon-node": "0.3.3",
     "debug": "4.4.0",
+    "express": "^4.21.2",
     "jimp": "0.22.12",
     "js-sha256": "0.11.0",
     "sharp": "^0.34.3",
     "uuid": "11.1.0"
   },
   "devDependencies": {
-    "@rslib/core": "^0.18.2",
+    "@rslib/core": "^0.18.3",
+    "@modelcontextprotocol/sdk": "1.10.2",
     "@types/debug": "4.1.12",
+    "@types/express": "^4.17.21",
     "@types/node": "^18.0.0",
     "@ui-tars/shared": "1.2.0",
     "dotenv": "^16.4.5",
     "openai": "6.3.0",
     "rimraf": "~3.0.2",
     "typescript": "^5.8.3",
-    "vitest": "3.0.5"
+    "vitest": "3.0.5",
+    "zod": "3.24.3"
   },
   "sideEffects": [],
   "publishConfig": {