@attson/atwebpilot-mcp 0.0.80 → 0.0.81

package/README.md

@@ -51,6 +51,7 @@ listen 端口的能力，所以方向只能如此。这也是配对页存在的
 - 控制面 5 个：`pairing_status / list_tabs / open_session / close_session / get_quota`
 - 发现 1 个：`browser_discoverTools` —— 已知工具时直接传 `enable: [...]`，已知分组时直接传 `enableGroups: ["export", ...]`，也可用 `profile: "core" | "full"` 切换整套工具面；只有这些都未知时才不带参数读取目录。选中的工具会加入本进程的 `tools/list`（发送 `tools/list_changed`），并始终返回完整 schema，包括已经启用的工具。
 - 同轮执行桥 1 个：`browser_call({session_id, tool, args})` —— 某些宿主虽已刷新 `tools/list`，却不会在当前模型轮次注入新工具。AI 可在 `discoverTools` 后立刻通过该桥执行，不需要让用户回复“继续”；下一轮看到原生工具后仍优先使用原生工具。
+- 批量编排 1 个：`browser_runSteps({session_id, steps, return_bindings?})` —— 在步骤和参数已经明确时，把 1–20 个 safe/caution 工具合并为一次 MCP 调用；`${binding}` 可引用前序结果。整批先做工具支持、权限和配额预检，dangerous、脚本、截图、下载与 tab 生命周期操作保持单步。
 - 执行面在浏览器连接前不进入 `tools/list`；连接确认后加载默认 **core 31 个** `browser_*`。其余 20 个由 AI 按需 `discoverTools` 拉取，用户不用配置。
 - 不暴露 `askUser`（MCP 会话没有人在侧边栏应答）和 `attachTab` / `detachTab`（目标 tab 已由 `open_session` 绑定）。
 
@@ -66,7 +67,7 @@ hover / uploadFile / scroll / waitFor`）；`browser_storage` 也不会列出，
 
 | 值 | 效果 |
 |---|---|
-| `core`（默认） | 连接前仅控制面、发现工具与同轮执行桥；连接后再列出 31 个核心工具 |
+| `core`（默认） | 连接前仅控制面、发现工具、同轮执行桥与批量编排；连接后再列出 31 个核心工具 |
 | `full` | 连接前同上；连接后列出全部 51 个原生工具 |
 
 无法识别的值（包括已移除的 `parity`）按 `core` 处理，并往 stderr 打一条提示。

package/dist/index.js

@@ -2414,7 +2414,7 @@ var NON_BUILTIN_CAPABILITY = {
   listTabs: "tab:open",
   openTab: "tab:open"
 };
-async function handleBrowserTool(deps, gen, args) {
+async function prepareBrowserTool(deps, gen, args) {
   const { coordinator, hub } = await deps.ensure();
   const session_id = String(args.session_id);
   const session = coordinator.sessions.get(session_id);
@@ -2429,23 +2429,20 @@ async function handleBrowserTool(deps, gen, args) {
     const unsafe = highestSeverity(runStaticScan(source)) === "dangerous";
     const v = coordinator.validateCall({ session_id, kind: "runJS", unsafe });
     if (!v.ok) throw new Error(`${v.error.code}: ${v.error.message}`);
-    coordinator.recordCall(session_id, v.dangerous);
     const requestedTimeout = toolArgs.timeoutMs;
-    const jsResult = await hub.exec(session.worker_id, {
+    return {
+      coordinator,
+      hub,
       session_id,
+      worker_id: session.worker_id,
       tab_id: session.tab_id,
       step: {
         kind: "js",
         source,
         ...typeof requestedTimeout === "number" && Number.isInteger(requestedTimeout) && requestedTimeout > 0 ? { timeoutMs: requestedTimeout } : {}
-      }
-    });
-    if (!jsResult.ok) {
-      throw new Error(
-        jsResult.error ? `${jsResult.error.code}: ${jsResult.error.message}` : "EXEC failed"
-      );
-    }
-    return jsResult.return ?? null;
+      },
+      dangerous: v.dangerous
+    };
   }
   if (tool === "switchToTab" || tool === "closeTab") {
     const boundTabId = Number.parseInt(session.tab_id, 10);
@@ -2455,10 +2452,11 @@ async function handleBrowserTool(deps, gen, args) {
     toolArgs.tabId = boundTabId;
   }
   const override = NON_BUILTIN_CAPABILITY[tool];
+  let dangerous;
   if (override) {
     const v = coordinator.validateCall({ session_id, kind: "capability", capability: override });
     if (!v.ok) throw new Error(`${v.error.code}: ${v.error.message}`);
-    coordinator.recordCall(session_id, v.dangerous);
+    dangerous = v.dangerous;
   } else {
     const raw = toolArgs;
     const v = coordinator.validateCall({
@@ -2470,13 +2468,321 @@ async function handleBrowserTool(deps, gen, args) {
       recorderArmsBodies: tool === "recorderConfig" ? raw.bodies === true : void 0
     });
     if (!v.ok) throw new Error(`${v.error.code}: ${v.error.message}`);
-    coordinator.recordCall(session_id, v.dangerous);
+    dangerous = v.dangerous;
   }
-  const result = await hub.exec(session.worker_id, { session_id, tab_id: session.tab_id, step: { kind: "tool", tool, args: toolArgs } });
+  return {
+    coordinator,
+    hub,
+    session_id,
+    worker_id: session.worker_id,
+    tab_id: session.tab_id,
+    step: { kind: "tool", tool, args: toolArgs },
+    dangerous
+  };
+}
+async function handleBrowserTool(deps, gen, args) {
+  const prepared = await prepareBrowserTool(deps, gen, args);
+  prepared.coordinator.recordCall(prepared.session_id, prepared.dangerous);
+  const result = await prepared.hub.exec(prepared.worker_id, {
+    session_id: prepared.session_id,
+    tab_id: prepared.tab_id,
+    step: prepared.step
+  });
   if (!result.ok) throw new Error(result.error ? `${result.error.code}: ${result.error.message}` : "EXEC failed");
   return result.return ?? null;
 }
 
+// src/browser-run-steps.ts
+var BROWSER_RUN_STEPS_TOOL = {
+  name: "browser_runSteps",
+  description: "Run 1-20 enabled safe/caution browser tools sequentially in one MCP call. Supports ${binding} references and returns only the final result plus requested bindings.",
+  inputSchema: {
+    type: "object",
+    required: ["session_id", "steps"],
+    properties: {
+      session_id: { type: "string", description: "Session id from open_session" },
+      steps: {
+        type: "array",
+        minItems: 1,
+        maxItems: 20,
+        items: {
+          type: "object",
+          required: ["tool", "args"],
+          properties: {
+            tool: {
+              type: "string",
+              description: "Enabled browser tool name; browser_ prefix is optional"
+            },
+            args: {
+              type: "object",
+              description: "Tool arguments excluding session_id; may reference earlier ${bindings}",
+              additionalProperties: true
+            },
+            bind_result_to: {
+              type: "string",
+              pattern: "^[A-Za-z_][A-Za-z0-9_]{0,63}$"
+            }
+          },
+          additionalProperties: false
+        }
+      },
+      return_bindings: {
+        type: "array",
+        items: {
+          type: "string",
+          pattern: "^[A-Za-z_][A-Za-z0-9_]{0,63}$"
+        },
+        uniqueItems: true
+      }
+    },
+    additionalProperties: false
+  }
+};
+var BINDING_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+var BLOCKED_BATCH_TOOLS = /* @__PURE__ */ new Set([
+  "browser_downloadImage",
+  "browser_downloadSpreadsheet",
+  "browser_openTab",
+  "browser_closeTab",
+  "browser_switchToTab"
+]);
+var CAPABILITY_SENSITIVE_FIELDS = /* @__PURE__ */ new Map([
+  ["browser_httpRequest", ["withCredentials"]],
+  ["browser_drop", ["files"]],
+  ["browser_recorderConfig", ["bodies"]]
+]);
+function runStepsPreflightError(message) {
+  return {
+    ok: false,
+    phase: "preflight",
+    completed: 0,
+    error: { message },
+    bindings: {}
+  };
+}
+async function handleBrowserRunSteps(deps, args, context) {
+  const sessionId = typeof args.session_id === "string" ? args.session_id : "";
+  if (!sessionId) throw new Error("InvalidArgs: browser_runSteps requires session_id");
+  if (!Array.isArray(args.steps) || args.steps.length < 1 || args.steps.length > 20) {
+    throw new Error("InvalidArgs: browser_runSteps requires 1-20 steps");
+  }
+  const steps = args.steps.map(parseStep);
+  const requested = parseReturnBindings(args.return_bindings);
+  const bindings = /* @__PURE__ */ Object.create(null);
+  let result = null;
+  const bindingIssue = validateBindingPlan(steps, requested);
+  if (bindingIssue) {
+    return preflightFailure(steps, bindingIssue.index, bindingIssue.message);
+  }
+  const { coordinator } = await deps.ensure();
+  const quota = coordinator.quotaFor(sessionId);
+  if (!quota) throw new Error(`session ${sessionId} not found`);
+  const remainingSteps = quota.max_steps - quota.steps_used;
+  if (steps.length > remainingSteps) {
+    const failedIndex = Math.max(0, remainingSteps);
+    return preflightFailure(
+      steps,
+      failedIndex,
+      `Session has only ${remainingSteps} steps remaining; batch requires ${steps.length}`
+    );
+  }
+  for (let index = 0; index < steps.length; index++) {
+    const step = steps[index];
+    const name = browserToolName(step.tool);
+    const generated = context.tools.get(name);
+    try {
+      assertAvailable(name, step.tool, generated, context);
+      if (generated.stepKind === "js" || generated.resultKind === "image" || BLOCKED_BATCH_TOOLS.has(name)) {
+        throw new Error(`Tool ${name} is not allowed in browser_runSteps`);
+      }
+      for (const field of CAPABILITY_SENSITIVE_FIELDS.get(name) ?? []) {
+        if (bindingReferences(step.args[field]).length > 0) {
+          throw new Error(
+            `Capability-sensitive field ${field} cannot reference bindings in browser_runSteps`
+          );
+        }
+      }
+      const prepared = await prepareBrowserTool(deps, generated, {
+        ...step.args,
+        session_id: sessionId
+      });
+      if (prepared.dangerous) {
+        throw new Error("Dangerous tool is not allowed in browser_runSteps");
+      }
+    } catch (error) {
+      return {
+        ok: false,
+        phase: "preflight",
+        completed: 0,
+        failed_step: { index, tool: name },
+        error: { message: error instanceof Error ? error.message : String(error) },
+        bindings: {}
+      };
+    }
+  }
+  for (let index = 0; index < steps.length; index++) {
+    const step = steps[index];
+    const name = browserToolName(step.tool);
+    const generated = context.tools.get(name);
+    assertAvailable(name, step.tool, generated, context);
+    const resolvedArgs = resolveBindings(step.args, bindings);
+    try {
+      result = await handleBrowserTool(deps, generated, { ...resolvedArgs, session_id: sessionId });
+    } catch (error) {
+      return {
+        ok: false,
+        phase: "execution",
+        completed: index,
+        failed_step: { index, tool: name },
+        error: { message: error instanceof Error ? error.message : String(error) },
+        bindings: selectBindings(requested, bindings, false)
+      };
+    }
+    if (step.bind_result_to) bindings[step.bind_result_to] = result;
+  }
+  return {
+    ok: true,
+    completed: steps.length,
+    result,
+    bindings: selectBindings(requested, bindings, true)
+  };
+}
+function preflightFailure(steps, index, message) {
+  const boundedIndex = Math.min(Math.max(index, 0), steps.length - 1);
+  return {
+    ok: false,
+    phase: "preflight",
+    completed: 0,
+    failed_step: {
+      index: boundedIndex,
+      tool: browserToolName(steps[boundedIndex].tool)
+    },
+    error: { message },
+    bindings: {}
+  };
+}
+function parseReturnBindings(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value) || value.some((name) => typeof name !== "string")) {
+    throw new Error("InvalidArgs: return_bindings must be an array of binding names");
+  }
+  return value;
+}
+function validateBindingPlan(steps, requested) {
+  const declared = /* @__PURE__ */ new Set();
+  for (let index = 0; index < steps.length; index++) {
+    const step = steps[index];
+    for (const name of bindingReferences(step.args)) {
+      if (!declared.has(name)) {
+        return {
+          index,
+          message: `InvalidArgs: binding ${name} must be declared by an earlier step`
+        };
+      }
+    }
+    if (step.bind_result_to) {
+      if (!BINDING_NAME.test(step.bind_result_to)) {
+        return { index, message: `InvalidArgs: invalid binding name ${step.bind_result_to}` };
+      }
+      if (declared.has(step.bind_result_to)) {
+        return { index, message: `InvalidArgs: duplicate binding ${step.bind_result_to}` };
+      }
+      declared.add(step.bind_result_to);
+    }
+  }
+  const seenRequested = /* @__PURE__ */ new Set();
+  for (const name of requested) {
+    if (!BINDING_NAME.test(name)) {
+      return { index: 0, message: `InvalidArgs: invalid return binding ${name}` };
+    }
+    if (seenRequested.has(name)) {
+      return { index: 0, message: `InvalidArgs: duplicate return binding ${name}` };
+    }
+    if (!declared.has(name)) {
+      return { index: 0, message: `InvalidArgs: unknown return binding ${name}` };
+    }
+    seenRequested.add(name);
+  }
+  return null;
+}
+function bindingReferences(value) {
+  if (typeof value === "string") {
+    return [...value.matchAll(/\$\{([^}]+)\}/g)].map((match) => match[1]);
+  }
+  if (Array.isArray(value)) return value.flatMap(bindingReferences);
+  if (value && typeof value === "object") {
+    return Object.values(value).flatMap(bindingReferences);
+  }
+  return [];
+}
+function assertAvailable(name, rawName, generated, context) {
+  if (!generated) throw new Error(`Unknown browser tool: ${rawName}`);
+  if (!context.advertised.has(name)) {
+    throw new Error(`${name} is not enabled; call browser_discoverTools first`);
+  }
+  if (context.supported && !generated.builtinTools.every((tool) => context.supported.has(tool))) {
+    throw new Error(`${name} is not supported by the connected browser extension`);
+  }
+}
+function parseStep(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("InvalidArgs: each browser_runSteps step must be an object");
+  }
+  const raw = value;
+  if (typeof raw.tool !== "string" || raw.tool.trim() === "") {
+    throw new Error("InvalidArgs: each browser_runSteps step requires tool");
+  }
+  if (!raw.args || typeof raw.args !== "object" || Array.isArray(raw.args)) {
+    throw new Error("InvalidArgs: each browser_runSteps step requires object args");
+  }
+  if (raw.bind_result_to !== void 0 && typeof raw.bind_result_to !== "string") {
+    throw new Error("InvalidArgs: bind_result_to must be a binding name");
+  }
+  return {
+    tool: raw.tool,
+    args: raw.args,
+    ...typeof raw.bind_result_to === "string" ? { bind_result_to: raw.bind_result_to } : {}
+  };
+}
+function browserToolName(raw) {
+  const name = raw.trim();
+  return name.startsWith("browser_") ? name : `browser_${name}`;
+}
+function resolveBindings(value, bindings) {
+  if (typeof value === "string") {
+    const exact = value.match(/^\$\{([^}]+)\}$/);
+    if (exact) return requireBinding(exact[1], bindings);
+    return value.replace(/\$\{([^}]+)\}/g, (_match, name) => {
+      const bound = requireBinding(name, bindings);
+      return typeof bound === "string" ? bound : JSON.stringify(bound);
+    });
+  }
+  if (Array.isArray(value)) return value.map((item) => resolveBindings(item, bindings));
+  if (value && typeof value === "object") {
+    const resolved = {};
+    for (const [key, item] of Object.entries(value)) {
+      resolved[key] = resolveBindings(item, bindings);
+    }
+    return resolved;
+  }
+  return value;
+}
+function requireBinding(name, bindings) {
+  if (!(name in bindings)) throw new Error(`InvalidArgs: binding ${name} is not available`);
+  return bindings[name];
+}
+function selectBindings(requested, bindings, requireAll) {
+  const selected = {};
+  for (const name of requested) {
+    if (!(name in bindings)) {
+      if (requireAll) throw new Error(`InvalidArgs: unknown return binding ${name}`);
+      continue;
+    }
+    selected[name] = bindings[name];
+  }
+  return selected;
+}
+
 // src/skill-bundle.ts
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
@@ -2490,8 +2796,9 @@ var TOPICS = {
 2. If list_tabs times out and returns pairing_required, show pair_url and wait for browser approval. Use pairing_status for a later non-blocking status check; do not ask the user to reply just to continue.
 3. Choose a returned tab, then call open_session with its tab_id.
 4. For interaction use browser_getPageInfo then browser_takeSnapshot; for broad reading use browser_createPageIndex.
-5. Prefer purpose-built tools and verified results. Use browser_discoverTools only for capabilities outside the connected core surface. Its response always includes the selected schemas. If a newly enabled native tool is not visible in the current turn, call it immediately with browser_call; do not ask the user to send "continue".
-6. Close the session when finished.
+5. When 2-20 safe/caution steps and their arguments are already known, use browser_runSteps to execute them in one MCP call. Keep dangerous actions and steps needing intermediate inspection as separate calls.
+6. Prefer purpose-built tools and verified results. Use browser_discoverTools only for capabilities outside the connected core surface. Its response always includes the selected schemas. If a newly enabled native tool is not visible in the current turn, call it immediately with browser_call; do not ask the user to send "continue".
+7. Close the session when finished.
 `,
   pairing: `# AtWebPilot pairing
 
@@ -2537,9 +2844,11 @@ function readSkillBundle(rawTopic = "quickstart") {
   }
   if (cached == null) {
     try {
-      cached = readFileSync(locateSkillFile(), "utf-8");
+      cached = `${TOPICS.quickstart}
+${readFileSync(locateSkillFile(), "utf-8")}`;
     } catch {
-      cached = `# ${SKILL_NAME}
+      cached = `${TOPICS.quickstart}
+# ${SKILL_NAME}
 
 ${SKILL_DESCRIPTION}
 
@@ -2569,7 +2878,7 @@ var SKILL_TOOL = {
 // package.json
 var package_default = {
   name: "@attson/atwebpilot-mcp",
-  version: "0.0.80",
+  version: "0.0.81",
   license: "Apache-2.0",
   description: "MCP server for the atwebpilot browser extension - let Codex or Claude Code drive your browser.",
   homepage: "https://github.com/attson/atwebpilot#readme",
@@ -2724,6 +3033,7 @@ function buildToolList(deps, state = DEFAULT_STATE) {
     ...CONTROL_TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
     { name: DISCOVER_TOOL.name, description: DISCOVER_TOOL.description, inputSchema: DISCOVER_TOOL.inputSchema },
     { name: BROWSER_CALL_TOOL.name, description: BROWSER_CALL_TOOL.description, inputSchema: BROWSER_CALL_TOOL.inputSchema },
+    { name: BROWSER_RUN_STEPS_TOOL.name, description: BROWSER_RUN_STEPS_TOOL.description, inputSchema: BROWSER_RUN_STEPS_TOOL.inputSchema },
     ...browser.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }))
   ];
 }
@@ -2763,6 +3073,24 @@ async function dispatchCall(deps, name, args, state = DEFAULT_STATE, onListChang
     if (name === BROWSER_CALL_TOOL.name) {
       return handleBrowserCall(deps, args, state);
     }
+    if (name === BROWSER_RUN_STEPS_TOOL.name) {
+      let result;
+      try {
+        result = await handleBrowserRunSteps(deps, args, {
+          tools: BROWSER_BY_NAME,
+          advertised: state.advertised,
+          supported: workerToolSupport(deps)
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("PAIRING_REQUIRED")) {
+          const pairUrl = deps.pairUrl();
+          if (pairUrl) onPairingRequired?.(pairUrl);
+        }
+        result = runStepsPreflightError(message);
+      }
+      return result.ok ? ok(result) : { ...ok(result), isError: true };
+    }
     if (name === "pairing_status") {
       const result = await handlePairingStatus(deps);
       if (result.status === "connected") await revealBrowserSurface(state, onListChanged);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attson/atwebpilot-mcp",
-  "version": "0.0.80",
+  "version": "0.0.81",
   "license": "Apache-2.0",
   "description": "MCP server for the atwebpilot browser extension - let Codex or Claude Code drive your browser.",
   "homepage": "https://github.com/attson/atwebpilot#readme",