@midscene/mcp 1.0.1-beta-20251024064637.0 → 1.0.1-beta-20251027034431.0

package/dist/api.mdx

@@ -25,6 +25,56 @@ In Playwright and Puppeteer, there are some common parameters:
 - `forceSameTabNavigation: boolean`: If true, page navigation is restricted to the current tab. (Default: true)
 - `waitForNavigationTimeout: number`: The timeout for waiting for navigation finished. (Default: 5000ms, set to 0 means not waiting for navigation finished)
 
+These Agents also support the following advanced configuration parameters:
+
+- `modelConfig: () => IModelConfig`: Optional. Custom model configuration function. Allows you to dynamically configure different models through code instead of environment variables. This is particularly useful when you need to use different models for different AI tasks (such as VQA, planning, grounding, etc.).
+
+  **Example:**
+  ```typescript
+  const agent = new PuppeteerAgent(page, {
+    modelConfig: () => ({
+      MIDSCENE_MODEL_NAME: 'qwen3-vl-plus',
+      MIDSCENE_MODEL_BASE_URL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+      MIDSCENE_MODEL_API_KEY: 'sk-...',
+      MIDSCENE_LOCATOR_MODE: 'qwen3-vl'
+    })
+  });
+  ```
+
+- `createOpenAIClient: (openai, options) => Promise<OpenAI | undefined>`: Optional. Custom OpenAI client wrapper function. Allows you to wrap the OpenAI client instance for integrating observability tools (such as LangSmith, LangFuse) or applying custom middleware.
+
+  **Parameter Description:**
+  - `openai: OpenAI` - The base OpenAI client instance created by Midscene with all necessary configurations (API key, base URL, proxy, etc.)
+  - `options: Record<string, unknown>` - OpenAI initialization options, including:
+    - `baseURL?: string` - API endpoint URL
+    - `apiKey?: string` - API key
+    - `dangerouslyAllowBrowser: boolean` - Always true in Midscene
+    - Other OpenAI configuration options
+
+  **Return Value:**
+  - Return the wrapped OpenAI client instance, or `undefined` to use the original instance
+
+  **Example (LangSmith Integration):**
+  ```typescript
+  import { wrapOpenAI } from 'langsmith/wrappers';
+
+  const agent = new PuppeteerAgent(page, {
+    createOpenAIClient: async (openai, options) => {
+      // Wrap with LangSmith for planning tasks
+      if (options.baseURL?.includes('planning')) {
+        return wrapOpenAI(openai, {
+          metadata: { task: 'planning' }
+        });
+      }
+
+      // Return the original client for other tasks
+      return openai;
+    }
+  });
+  ```
+
+  **Note:** `createOpenAIClient` overrides the behavior of the `MIDSCENE_LANGSMITH_DEBUG` environment variable. If you provide a custom client wrapper function, you need to handle the integration of LangSmith or other observability tools yourself.
+
 In Puppeteer, there is also a parameter:
 
 - `waitForNetworkIdleTimeout: number`: The timeout for waiting for network idle between each action. (Default: 2000ms, set to 0 means not waiting for network idle)
@@ -854,9 +904,11 @@ You can override environment variables at runtime by calling the `overrideAIConf
 import { overrideAIConfig } from '@midscene/web/puppeteer'; // or another Agent
 
 overrideAIConfig({
-  OPENAI_BASE_URL: '...',
-  OPENAI_API_KEY: '...',
   MIDSCENE_MODEL_NAME: '...',
+  MODEL_BASE_URL: '...', // recommended, use new variable name
+  MODEL_API_KEY: '...', // recommended, use new variable name
+  // OPENAI_BASE_URL: '...', // deprecated but still compatible
+  // OPENAI_API_KEY: '...', // deprecated but still compatible
 });
 ```