fix(shared): hide deprecated mcp behavior flag

Author: quanru

apps/site/docs/en/mcp.mdx

@@ -207,10 +207,9 @@ Common flags:
 - `--wait-after-action <ms>` maps to `waitAfterAction`: wait time after each action execution. The default is `300`.
 - `--replanning-cycle-limit <n>` maps to `replanningCycleLimit`: maximum number of `aiAct` replanning cycles.
 - `--ai-act-context <text>` maps to `aiActContext`: extra background knowledge for `aiAct`.
-- `--ai-action-context <text>` maps to `aiActionContext`: deprecated alias for `aiActContext`.
 - `--screenshot-shrink-factor <n>` maps to `screenshotShrinkFactor`: shrink screenshots before sending them to the AI model.
 
-In MCP calls, keep the API camelCase name and put it under the platform namespace: `android.waitAfterAction`, `harmony.waitAfterAction`, `ios.waitAfterAction`, `computer.waitAfterAction`, or `web.waitAfterAction`. The same pattern applies to `replanningCycleLimit`, `aiActContext`, `aiActionContext`, and `screenshotShrinkFactor`.
+In MCP calls, keep the API camelCase name and put it under the platform namespace: `android.waitAfterAction`, `harmony.waitAfterAction`, `ios.waitAfterAction`, `computer.waitAfterAction`, or `web.waitAfterAction`. The same pattern applies to `replanningCycleLimit`, `aiActContext`, and `screenshotShrinkFactor`.
 
 These parameters are part of the Agent init args for that tool call. If a later call changes them, or omits them after setting them, Midscene rebuilds the Agent so the next call uses the new effective configuration. For Web tools, `web.url` opens or navigates to the URL each time it is supplied; omit it to keep using the current page.
 

apps/site/docs/zh/mcp.mdx

@@ -207,10 +207,9 @@ midscene-ios assert --prompt "成功提示可见" --screenshot-shrink-factor 2
 - `--wait-after-action <ms>` 对应 `waitAfterAction`：每次动作执行后的等待时间，默认值为 `300`。
 - `--replanning-cycle-limit <n>` 对应 `replanningCycleLimit`：`aiAct` 的最大重规划次数。
 - `--ai-act-context <text>` 对应 `aiActContext`：传给 `aiAct` 的额外背景信息。
-- `--ai-action-context <text>` 对应 `aiActionContext`：`aiActContext` 的旧参数名，不建议继续使用。
 - `--screenshot-shrink-factor <n>` 对应 `screenshotShrinkFactor`：发送给 AI 模型前的截图压缩倍率。
 
-在 MCP 调用中，保留 API 里的 camelCase 参数名，并放在平台 namespace 下：`android.waitAfterAction`、`harmony.waitAfterAction`、`ios.waitAfterAction`、`computer.waitAfterAction` 或 `web.waitAfterAction`。`replanningCycleLimit`、`aiActContext`、`aiActionContext` 和 `screenshotShrinkFactor` 也使用同样的规则。
+在 MCP 调用中，保留 API 里的 camelCase 参数名，并放在平台 namespace 下：`android.waitAfterAction`、`harmony.waitAfterAction`、`ios.waitAfterAction`、`computer.waitAfterAction` 或 `web.waitAfterAction`。`replanningCycleLimit`、`aiActContext` 和 `screenshotShrinkFactor` 也使用同样的规则。
 
 这些参数属于当前工具调用的 Agent init args。后续调用如果改变这些参数，或在设置后省略它们，Midscene 会重建 Agent，让下一次调用使用新的有效配置。对于 Web 工具，只要传入 `web.url`，每次都会打开或导航到该 URL；省略它则继续使用当前页面。
 

packages/android/tests/unit-test/cli.test.ts

@@ -215,6 +215,8 @@ describe('Android CLI integration', () => {
     expect(output.join('\n')).toContain('Default: 300ms');
     expect(output.join('\n')).toContain('--replanning-cycle-limit');
     expect(output.join('\n')).toContain('--ai-act-context');
+    expect(output.join('\n')).not.toContain('--ai-action-context');
+    expect(output.join('\n')).not.toContain('--aiActionContext');
     expect(output.join('\n')).toContain('--screenshot-shrink-factor');
     expect(output.join('\n')).toContain(
       'high values may reduce recognition quality, especially on mobile',

packages/android/tests/unit-test/mcp-tools.test.ts

@@ -161,6 +161,10 @@ describe('AndroidMidsceneTools', () => {
 
     expect(takeScreenshotTool?.schema).toHaveProperty('android.deviceId');
     expect(actTool?.schema).toHaveProperty('android.deviceId');
+    expect(takeScreenshotTool?.schema).toHaveProperty('android.aiActContext');
+    expect(takeScreenshotTool?.schema).not.toHaveProperty(
+      'android.aiActionContext',
+    );
   });
 
   it('prefers namespaced deviceId over top-level bare deviceId', async () => {

packages/shared/src/mcp/agent-behavior-init-args.ts

@@ -8,17 +8,18 @@ export interface AgentBehaviorInitArgs {
   screenshotShrinkFactor?: number;
 }
 
+type ExposedAgentBehaviorInitArgKey = Exclude<
+  keyof AgentBehaviorInitArgs,
+  'aiActionContext'
+>;
+
 export const agentBehaviorInitArgShape = {
   aiActContext: z
     .string()
     .optional()
     .describe(
       'Background knowledge passed to aiAct. Default: no extra context.',
     ),
-  aiActionContext: z
-    .string()
-    .optional()
-    .describe('Deprecated alias for aiActContext. Default: no extra context.'),
   replanningCycleLimit: z
     .number()
     .int()
@@ -41,7 +42,7 @@ export const agentBehaviorInitArgShape = {
     .describe(
       'Screenshot shrink factor before sending images to AI. Default: 1; high values may reduce recognition quality, especially on mobile.',
     ),
-} satisfies Record<keyof AgentBehaviorInitArgs, z.ZodTypeAny>;
+} satisfies Record<ExposedAgentBehaviorInitArgKey, z.ZodTypeAny>;
 
 export function extractAgentBehaviorInitArgs(
   extracted: Partial<AgentBehaviorInitArgs> | undefined,

packages/shared/src/mcp/tool-generator.ts

@@ -129,6 +129,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 function makePromptOptional(
   shape: Record<string, z.ZodTypeAny>,
   wrapInOptional: boolean,
+  description?: string | null,
 ): z.ZodTypeAny {
   const newShape = { ...shape };
   newShape.prompt = shape.prompt.optional();
@@ -137,6 +138,9 @@ function makePromptOptional(
   if (wrapInOptional) {
     newSchema = newSchema.optional();
   }
+  if (description) {
+    newSchema = newSchema.describe(description);
+  }
   return newSchema;
 }
 
@@ -151,7 +155,10 @@ function transformSchemaField(
   const shape = getZodObjectShape(innerValue);
 
   if (shape && isMidsceneLocatorField(innerValue)) {
-    return [key, makePromptOptional(shape, isOptional)];
+    return [
+      key,
+      makePromptOptional(shape, isOptional, getZodDescription(value)),
+    ];
   }
   return [key, value];
 }

packages/shared/tests/unit-test/tool-generator.test.ts

@@ -108,6 +108,28 @@ describe('generateToolsFromActionSpace', () => {
     });
   });
 
+  it('preserves locate field descriptions after making locate.prompt optional', () => {
+    const [tool] = generateToolsFromActionSpace(
+      [
+        {
+          name: 'Tap',
+          description: 'Tap the element',
+          paramSchema: z.object({
+            locate: locateSchema.describe('The element to be tapped'),
+          }),
+        },
+      ],
+      async () => ({
+        getActionSpace: vi.fn().mockResolvedValue([]),
+        page: {
+          screenshotBase64: vi.fn().mockResolvedValue(screenshotBase64),
+        },
+      }),
+    );
+
+    expect(tool.schema.locate.description).toBe('The element to be tapped');
+  });
+
   it('falls back to aiAction when direct action execution is unavailable', async () => {
     const aiAction = vi.fn().mockResolvedValue(undefined);
     const [tool] = generateToolsFromActionSpace(actionSpace, async () => ({