@attson/atwebpilot-mcp 0.0.77 → 0.0.79

package/README.md

@@ -17,11 +17,11 @@ Claude Code：
 **不需要手填端口。** 从 Plan 33 起是配对流程：
 
 1. 会话启动时**不绑任何端口** —— 不碰网页的会话零副作用。
-2. AI 第一次调 `list_tabs` / `pairing_status` 时才绑一个空闲端口，尝试用系统默认浏览器打开配对页，并立即返回 `pairing_required + pair_url`，不阻塞等待。
+2. AI 第一次调 `list_tabs` / `pairing_status` 时才绑一个空闲端口，通过 MCP URL elicitation 请宿主打开配对页，并立即返回 `pairing_required + pair_url`，不阻塞等待；不支持该能力的宿主回退到系统默认浏览器。
 3. 你在浏览器里点「允许」，扩展即接入；AI 用轻量 `pairing_status` 确认连接后再读取 tab，不重复阻塞式调用。
 4. 之后本机的会话都免确认（信任是安装级的）；端口能复用时连配对页都不会弹。
 
-若系统未弹出浏览器，可直接打开返回结果中的 `pair_url`。授权成功只以扩展实际建立连接并发送 `HELLO` 为准；打开配对页本身不代表已连接。
+若宿主和系统都未弹出浏览器，可直接打开返回结果中的 `pair_url`。授权成功只以扩展实际建立连接并发送 `HELLO` 为准；打开配对页本身不代表已连接。
 
 多个 Codex / Claude Code 会话可以同时接入同一个浏览器，各自一条连接。可在扩展设置 →
 Coordinator 查看已接入的会话、单独断开，或撤销信任。
@@ -49,7 +49,8 @@ listen 端口的能力，所以方向只能如此。这也是配对页存在的
 ## 工具面
 
 - 控制面 5 个：`pairing_status / list_tabs / open_session / close_session / get_quota`
-- 发现 1 个：`browser_discoverTools` —— 已知工具时直接传 `enable: [...]`，已知分组时直接传 `enableGroups: ["export", ...]`；只有两者都未知时才不带参数读取目录。启用后会加入本进程的 `tools/list`（发送 `tools/list_changed`），并直接返回完整 schema。
+- 发现 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` 后立刻通过该桥执行，不需要让用户回复“继续”；下一轮看到原生工具后仍优先使用原生工具。
 - 执行面在浏览器连接前不进入 `tools/list`；连接确认后加载默认 **core 31 个** `browser_*`。其余 20 个由 AI 按需 `discoverTools` 拉取，用户不用配置。
 - 不暴露 `askUser`（MCP 会话没有人在侧边栏应答）和 `attachTab` / `detachTab`（目标 tab 已由 `open_session` 绑定）。
 
@@ -65,8 +66,8 @@ hover / uploadFile / scroll / waitFor`）；`browser_storage` 也不会列出，
 
 | 值 | 效果 |
 |---|---|
-| `core`（默认） | 连接前仅控制面；连接后 31 个核心工具 + `browser_discoverTools` |
-| `full` | 连接前仍仅控制面；连接后列出全部 51 个工具 |
+| `core`（默认） | 连接前仅控制面、发现工具与同轮执行桥；连接后再列出 31 个核心工具 |
+| `full` | 连接前同上；连接后列出全部 51 个原生工具 |
 
 无法识别的值（包括已移除的 `parity`）按 `core` 处理，并往 stderr 打一条提示。
 

package/dist/index.js

@@ -2109,13 +2109,23 @@ function discoveryCatalog(all, advertised) {
 
 // src/discover-tool.ts
 var DISCOVER_GROUPS = Object.keys(DISCOVERABLE_GROUPS);
+var DISCOVER_PROFILES = ["core", "full"];
+var PROFILE_TOOLS = {
+  core: generateBrowserTools("core").map((tool) => tool.name),
+  full: generateBrowserTools("full").map((tool) => tool.name)
+};
 var DISCOVER_TOOL = {
   name: "browser_discoverTools",
-  description: "The default tool list is the core set. Enable known extras directly with enable=[names] or enableGroups=[groups]. Omit both only when you need the catalog. Groups: export, network, storage, browser-data, inspect, legacy-dom, form, tabs. Enabled tools join tools/list and the response includes their full schemas so you can call them immediately. Use this instead of rebuilding missing capabilities with runJS.",
+  description: "The default tool list is the core set. Enable known extras directly with enable=[names] or enableGroups=[groups]. Use profile=core|full to return and enable a complete profile. Omit both only when you need the catalog. Groups: export, network, storage, browser-data, inspect, legacy-dom, form, tabs. The response includes full schemas even for tools already enabled. If the host has not refreshed them in this turn, call them through browser_call. Use this instead of rebuilding missing capabilities with runJS.",
   inputSchema: {
     type: "object",
     properties: {
       enable: { type: "array", items: { type: "string" }, description: "Tool names from the catalog to advertise" },
+      profile: {
+        type: "string",
+        enum: [...DISCOVER_PROFILES],
+        description: "Return and enable every runnable tool in the core or full profile"
+      },
       enableGroups: {
         type: "array",
         items: { type: "string", enum: DISCOVER_GROUPS },
@@ -2131,14 +2141,16 @@ function isRunnable(t, supported) {
 function handleDiscover(input) {
   const { all, advertised, args, supported } = input;
   const byName = new Map(all.map((t) => [t.name, t]));
-  const hasSelection = Array.isArray(args.enable) || Array.isArray(args.enableGroups);
+  const hasSelection = Array.isArray(args.enable) || Array.isArray(args.enableGroups) || args.profile != null;
   if (!hasSelection) {
     const runnable = all.filter((t) => isRunnable(t, supported));
     return { catalog: discoveryCatalog(runnable, advertised), changed: false };
   }
   const explicit = Array.isArray(args.enable) ? args.enable.map(String) : [];
   const groups = Array.isArray(args.enableGroups) ? args.enableGroups.map(String) : [];
+  const profile = args.profile == null ? null : String(args.profile);
   const unknownGroups = groups.filter((group) => !DISCOVER_GROUPS.includes(group));
+  const unknownProfiles = profile != null && !DISCOVER_PROFILES.includes(profile) ? [profile] : [];
   const grouped = groups.flatMap(
     (group) => DISCOVERABLE_GROUPS[group] ?? []
   );
@@ -2150,7 +2162,13 @@ function handleDiscover(input) {
   for (const name of grouped) {
     if (!requestedByName.has(name)) requestedByName.set(name, name);
   }
+  if (profile && unknownProfiles.length === 0) {
+    for (const name of PROFILE_TOOLS[profile]) {
+      if (!requestedByName.has(name)) requestedByName.set(name, name);
+    }
+  }
   const enabled = [];
+  let changed = false;
   const unknown = [];
   const unsupported = [];
   for (const [name, reportAs] of requestedByName) {
@@ -2163,19 +2181,42 @@ function handleDiscover(input) {
       unsupported.push(reportAs);
       continue;
     }
-    if (advertised.has(name)) continue;
-    advertised.add(name);
+    if (!advertised.has(name)) {
+      advertised.add(name);
+      changed = true;
+    }
     enabled.push({ name: t.name, description: t.description, inputSchema: t.inputSchema });
   }
   return {
     enabled,
     ...unknown.length ? { unknown } : {},
     ...unknownGroups.length ? { unknownGroups } : {},
+    ...unknownProfiles.length ? { unknownProfiles } : {},
     ...unsupported.length ? { unsupported } : {},
-    changed: enabled.length > 0
+    changed
   };
 }
 
+// src/browser-call.ts
+var BROWSER_CALL_TOOL = {
+  name: "browser_call",
+  description: "Call an enabled browser tool in the current turn after browser_discoverTools returns its schema. Prefer the native tool when available.",
+  inputSchema: {
+    type: "object",
+    required: ["session_id", "tool", "args"],
+    properties: {
+      session_id: { type: "string", description: "Session id from open_session" },
+      tool: { type: "string", description: "Enabled browser tool name; browser_ prefix is optional" },
+      args: {
+        type: "object",
+        description: "Arguments matching the schema returned by browser_discoverTools, excluding session_id",
+        additionalProperties: true
+      }
+    },
+    additionalProperties: false
+  }
+};
+
 // ../shared/src/static-scan.ts
 var RULES = [
   {
@@ -2423,7 +2464,7 @@ var TOPICS = {
 2. After approval, call pairing_status. Do not retry list_tabs while status is unchanged.
 3. Call list_tabs when connected, choose a tab, then 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.
+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.
 `,
   pairing: `# AtWebPilot pairing
@@ -2502,7 +2543,7 @@ var SKILL_TOOL = {
 // package.json
 var package_default = {
   name: "@attson/atwebpilot-mcp",
-  version: "0.0.77",
+  version: "0.0.79",
   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",
@@ -2552,6 +2593,64 @@ var package_default = {
 // src/version.ts
 var MCP_VERSION = package_default.version;
 
+// src/pairing-presenter.ts
+import { randomUUID } from "crypto";
+function isCodexClient(server) {
+  return server.getClientVersion?.()?.name.toLowerCase().includes("codex") ?? false;
+}
+function createPairingPresenter(server, fallbackOpenUrl) {
+  let presentedUrl = null;
+  const runFallback = async (url) => {
+    if (!fallbackOpenUrl) return false;
+    try {
+      await fallbackOpenUrl(url);
+      return true;
+    } catch (error) {
+      console.error(
+        `[atwebpilot-mcp] failed to open pairing page ${url}:`,
+        error instanceof Error ? error.message : String(error)
+      );
+      return false;
+    }
+  };
+  const requestHostPresentation = (url, fallbackOnFailure) => {
+    void server.elicitInput({
+      mode: "url",
+      message: "Open AtWebPilot in the browser to approve this pairing request.",
+      url,
+      elicitationId: `atwebpilot-pairing-${randomUUID()}`
+    }).catch(async (error) => {
+      if (!server.transport) return;
+      console.error(
+        fallbackOnFailure ? "[atwebpilot-mcp] URL elicitation failed; falling back to the system browser:" : "[atwebpilot-mcp] URL elicitation failed:",
+        error instanceof Error ? error.message : String(error)
+      );
+      if (fallbackOnFailure && await runFallback(url)) return;
+      presentedUrl = null;
+    });
+  };
+  return (url) => {
+    if (presentedUrl === url) return;
+    presentedUrl = url;
+    const supportsUrlElicitation = Boolean(server.getClientCapabilities()?.elicitation?.url);
+    if (isCodexClient(server)) {
+      void runFallback(url).then((opened) => {
+        if (opened || !server.transport) return;
+        if (supportsUrlElicitation) requestHostPresentation(url, false);
+        else presentedUrl = null;
+      });
+      return;
+    }
+    if (supportsUrlElicitation) {
+      requestHostPresentation(url, true);
+      return;
+    }
+    void runFallback(url).then((opened) => {
+      if (!opened) presentedUrl = null;
+    });
+  };
+}
+
 // src/mcp-server.ts
 var ALL_BROWSER_TOOLS = generateBrowserTools("full");
 var BROWSER_BY_NAME = new Map(ALL_BROWSER_TOOLS.map((t) => [t.name, t]));
@@ -2598,6 +2697,7 @@ function buildToolList(deps, state = DEFAULT_STATE) {
     { name: SKILL_TOOL.name, description: SKILL_TOOL.description, inputSchema: SKILL_TOOL.inputSchema },
     ...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 },
     ...browser.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }))
   ];
 }
@@ -2617,7 +2717,7 @@ function toolResult(gen, data) {
   return { content };
 }
 var fail2 = (message) => ({ content: [{ type: "text", text: message }], isError: true });
-async function dispatchCall(deps, name, args, state = DEFAULT_STATE, onListChanged) {
+async function dispatchCall(deps, name, args, state = DEFAULT_STATE, onListChanged, onPairingRequired) {
   try {
     if (name === SKILL_TOOL.name) {
       const bundle = readSkillBundle(args.topic);
@@ -2634,14 +2734,19 @@ async function dispatchCall(deps, name, args, state = DEFAULT_STATE, onListChang
       const { changed: _c, ...body } = r;
       return ok(body);
     }
+    if (name === BROWSER_CALL_TOOL.name) {
+      return handleBrowserCall(deps, args, state);
+    }
     if (name === "pairing_status") {
       const result = await handlePairingStatus(deps);
       if (result.status === "connected") await revealBrowserSurface(state, onListChanged);
+      else onPairingRequired?.(result.pair_url);
       return ok(result);
     }
     if (name === "list_tabs") {
       const result = await handleListTabs(deps);
       if (result.status === "connected") await revealBrowserSurface(state, onListChanged);
+      else onPairingRequired?.(result.pair_url);
       return ok(result);
     }
     if (name === "open_session") {
@@ -2655,19 +2760,50 @@ async function dispatchCall(deps, name, args, state = DEFAULT_STATE, onListChang
     if (gen) return toolResult(gen, await handleBrowserTool(deps, gen, args));
     return fail2(`unknown tool: ${name}`);
   } catch (e) {
-    return fail2(e instanceof Error ? e.message : String(e));
+    const message = e instanceof Error ? e.message : String(e);
+    if (message.includes("PAIRING_REQUIRED")) {
+      const pairUrl = deps.pairUrl();
+      if (pairUrl) onPairingRequired?.(pairUrl);
+    }
+    return fail2(message);
+  }
+}
+async function handleBrowserCall(deps, args, state) {
+  const rawName = typeof args.tool === "string" ? args.tool.trim() : "";
+  if (!rawName) return fail2("InvalidArgs: browser_call requires tool");
+  const name = rawName.startsWith("browser_") ? rawName : `browser_${rawName}`;
+  const gen = BROWSER_BY_NAME.get(name);
+  if (!gen) return fail2(`Unknown browser tool: ${rawName}`);
+  if (!state.advertised.has(name)) {
+    return fail2(`${name} is not enabled; call browser_discoverTools first`);
+  }
+  const supported = workerToolSupport(deps);
+  if (supported && !gen.builtinTools.every((tool) => supported.has(tool))) {
+    return fail2(`${name} is not supported by the connected browser extension`);
+  }
+  if (typeof args.session_id !== "string" || args.session_id.length === 0) {
+    return fail2("InvalidArgs: browser_call requires session_id");
   }
+  if (args.args === null || typeof args.args !== "object" || Array.isArray(args.args)) {
+    return fail2("InvalidArgs: browser_call args must be an object");
+  }
+  const toolArgs = {
+    ...args.args,
+    session_id: args.session_id
+  };
+  return toolResult(gen, await handleBrowserTool(deps, gen, toolArgs));
 }
 async function revealBrowserSurface(state, onListChanged) {
   if (state.browserSurfaceVisible) return;
   state.browserSurfaceVisible = true;
   await onListChanged?.();
 }
-function createMcpServer(deps, state = DEFAULT_STATE) {
+function createMcpServer(deps, state = DEFAULT_STATE, options = {}) {
   const server = new Server(
     { name: "atwebpilot-mcp", version: MCP_VERSION },
     { capabilities: { tools: { listChanged: true }, logging: {} } }
   );
+  const presentPairing = createPairingPresenter(server, options.fallbackOpenUrl);
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: buildToolList(deps, state) }));
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const args = req.params.arguments ?? {};
@@ -2678,11 +2814,14 @@ function createMcpServer(deps, state = DEFAULT_STATE) {
         console.error("[atwebpilot-mcp] failed to send tools/list_changed:", error instanceof Error ? error.message : String(error));
       }
     };
-    return dispatchCall(deps, req.params.name, args, state, onListChanged);
+    return dispatchCall(deps, req.params.name, args, state, onListChanged, presentPairing);
   });
   return server;
 }
 
+// src/ensure-hub.ts
+import { readFile } from "fs/promises";
+
 // src/loopback-ws-hub.ts
 import { WebSocketServer, WebSocket } from "ws";
 import {
@@ -3119,7 +3258,7 @@ function installWire(hub, coordinator, clock, onWorkerReady) {
 import { mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join as join2 } from "path";
-import { randomBytes, randomUUID } from "crypto";
+import { randomBytes, randomUUID as randomUUID2 } from "crypto";
 var FILE = "identity.json";
 function defaultIdentityDir() {
   return join2(homedir(), ".atwebpilot");
@@ -3143,7 +3282,7 @@ function loadOrCreateIdentity(dir = defaultIdentityDir()) {
   const existing = read(dir);
   if (existing) return { installId: existing.installId, secret: existing.secret };
   const created = {
-    installId: `inst_${randomUUID().replace(/-/g, "").slice(0, 16)}`,
+    installId: `inst_${randomUUID2().replace(/-/g, "").slice(0, 16)}`,
     secret: randomBytes(24).toString("base64url")
   };
   write(dir, created);
@@ -3162,7 +3301,7 @@ function processInfo(cwd = process.cwd()) {
   const home = homedir();
   const label = home && cwd.startsWith(home) ? `~${cwd.slice(home.length)}` : cwd;
   return {
-    sessionId: `sess_${randomUUID().replace(/-/g, "").slice(0, 12)}`,
+    sessionId: `sess_${randomUUID2().replace(/-/g, "").slice(0, 12)}`,
     label,
     pid: process.pid
   };
@@ -3327,6 +3466,57 @@ function createHubEnsurer(d) {
     bound: () => bundle != null
   };
 }
+var DESKTOP_ENV_KEYS = [
+  "DISPLAY",
+  "WAYLAND_DISPLAY",
+  "XDG_RUNTIME_DIR",
+  "DBUS_SESSION_BUS_ADDRESS",
+  "XAUTHORITY"
+];
+function processId(field, status) {
+  const match = new RegExp(`^${field}:\\s+(\\d+)`, "m").exec(status);
+  if (!match) return null;
+  const value = Number(match[1]);
+  return Number.isSafeInteger(value) ? value : null;
+}
+function copyDesktopVariables(target, serialized) {
+  for (const entry of serialized.split("\0")) {
+    const separator = entry.indexOf("=");
+    if (separator <= 0) continue;
+    const key = entry.slice(0, separator);
+    if (!DESKTOP_ENV_KEYS.includes(key) || target[key]) continue;
+    const value = entry.slice(separator + 1);
+    if (value) target[key] = value;
+  }
+}
+async function resolveDesktopOpenEnvironment(options = {}) {
+  const environment = { ...options.baseEnv ?? process.env };
+  if ((options.platform ?? process.platform) !== "linux") return environment;
+  const expectedUid = options.uid ?? process.getuid?.();
+  const readTextFile = options.readTextFile ?? ((path) => readFile(path, "utf8"));
+  const seen = /* @__PURE__ */ new Set();
+  let pid = options.parentPid ?? process.ppid;
+  const maxDepth = options.maxDepth ?? 12;
+  for (let depth = 0; depth < maxDepth && pid > 1 && !seen.has(pid); depth += 1) {
+    seen.add(pid);
+    let status;
+    try {
+      status = await readTextFile(`/proc/${pid}/status`);
+    } catch {
+      break;
+    }
+    const ownerUid = processId("Uid", status);
+    if (expectedUid !== void 0 && ownerUid !== expectedUid) break;
+    try {
+      copyDesktopVariables(environment, await readTextFile(`/proc/${pid}/environ`));
+    } catch {
+    }
+    const parentPid = processId("PPid", status);
+    if (parentPid === null || parentPid === pid) break;
+    pid = parentPid;
+  }
+  return environment;
+}
 function openCommands(url) {
   if (process.platform === "darwin") return [{ command: "open", args: [url] }];
   if (process.platform === "win32") {
@@ -3340,10 +3530,14 @@ function openCommands(url) {
     { command: "gio", args: ["open", url] }
   ];
 }
-async function runOpenCommand({ command, args }) {
+async function runOpenCommand({ command, args }, environment) {
   const { spawn } = await import("child_process");
   await new Promise((resolve, reject) => {
-    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    const child = spawn(command, args, {
+      stdio: "ignore",
+      detached: true,
+      env: environment
+    });
     let settled = false;
     const finish = (error) => {
       if (settled) return;
@@ -3366,9 +3560,10 @@ async function runOpenCommand({ command, args }) {
 }
 async function defaultOpenUrl(url) {
   const errors = [];
+  const environment = await resolveDesktopOpenEnvironment();
   for (const candidate of openCommands(url)) {
     try {
-      await runOpenCommand(candidate);
+      await runOpenCommand(candidate, environment);
       return;
     } catch (error) {
       errors.push(error instanceof Error ? error.message : String(error));
@@ -3387,10 +3582,9 @@ async function main() {
     clock,
     idGen,
     explicitPort,
-    token,
-    openUrl: defaultOpenUrl
+    token
   });
-  const server = createMcpServer(deps);
+  const server = createMcpServer(deps, void 0, { fallbackOpenUrl: defaultOpenUrl });
   await server.connect(new StdioServerTransport());
   console.error("[atwebpilot-mcp] stdio MCP connected; ws port binds on first browser use");
   const shutdown = () => {

package/dist/skill/SKILL.md

@@ -64,16 +64,26 @@ do this, in order:
    `browser_discoverTools({ enable: ["browser_downloadSpreadsheet", ...] })`.
    If you know only the group, use
    `browser_discoverTools({ enableGroups: ["export"] })`.
+   To switch the whole process surface explicitly, use
+   `browser_discoverTools({ profile: "core" })` or `{ profile: "full" }`.
 2. Call `browser_discoverTools({})` only when neither the tool nor group is
    known. Enabled tools join `tools/list` (a `tools/list_changed` notification
-   is sent), and the response carries their full schemas for immediate use.
+   is sent), and the response carries the selected full schemas even if those
+   tools were already enabled.
+3. Prefer a newly visible native tool. If the MCP host has refreshed
+   `tools/list` but the current model turn still has the old snapshot, call the
+   selected tool immediately through
+   `browser_call({ session_id, tool: "browser_downloadSpreadsheet", args: {...} })`.
+   Do not ask the user to reply "continue" just to start another model turn.
+   Nested `args` omit `session_id`; the bridge injects the top-level value.
 
 **Do not** rebuild these capabilities with `runJS` (`fetch`, CSV blobs,
 `localStorage[...]`). It is slower, loses schema validation, and usually trips
 the dangerous-tier review that the purpose-built tool would have avoided.
 
 `ATWEBPILOT_MCP_TOOLS=full` advertises everything from the start for users who
-prefer to pay the context cost once.
+prefer to pay the context cost once. `browser_call` is a current-turn
+compatibility path; use the native tool once the host exposes it.
 
 ## Recommended flow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attson/atwebpilot-mcp",
-  "version": "0.0.77",
+  "version": "0.0.79",
   "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",