@attson/atwebpilot-mcp 0.0.71 → 0.0.73

package/README.md

@@ -49,8 +49,8 @@ listen 端口的能力，所以方向只能如此。这也是配对页存在的
 ## 工具面
 
 - 控制面 4 个：`list_tabs / open_session / close_session / get_quota`
-- 发现 1 个：`browser_discoverTools` —— 不带参数返回未发布工具目录（按 `export / network / storage / browser-data / inspect / legacy-dom / form` 分组）；带 `enable: [...]` 把它们加进本进程的 `tools/list`（发送 `tools/list_changed`），并直接返回完整 schema。
-- 执行面默认 **core 32 个** `browser_*`：浏览 / 采集 / 填表 / 导航 / 截图 闭环所需的工具。其余 19 个由 AI 按需 `discoverTools` 拉取，用户不用配置。
+- 发现 1 个：`browser_discoverTools` —— 已知工具时直接传 `enable: [...]`，已知分组时直接传 `enableGroups: ["export", ...]`；只有两者都未知时才不带参数读取目录。启用后会加入本进程的 `tools/list`（发送 `tools/list_changed`），并直接返回完整 schema。
+- 执行面默认 **core 31 个** `browser_*`：浏览 / 采集 / 填表 / 导航 / 截图 闭环所需的工具。其余 20 个由 AI 按需 `discoverTools` 拉取，用户不用配置。
 - 不暴露 `askUser`（MCP 会话没有人在侧边栏应答）和 `attachTab` / `detachTab`（目标 tab 已由 `open_session` 绑定）。
 
 MCP 层的描述是精简英文（≈2.5k tokens for core），侧边栏内置 LLM 仍用中文长描述；两者共享同一份 `TOOL_DEFS`，靠 `mcp` 字段区分。
@@ -65,11 +65,25 @@ hover / uploadFile / scroll / waitFor`）；`browser_storage` 也不会列出，
 
 | 值 | 效果 |
 |---|---|
-| `core`（默认） | 32 个核心工具 + `browser_discoverTools`，其余按需发现 |
+| `core`（默认） | 31 个核心工具 + `browser_discoverTools`，其余按需发现 |
 | `full` | 一开始就全部列出（51 个），适合不想让 AI 多一步发现的用户 |
 
 无法识别的值（包括已移除的 `parity`）按 `core` 处理，并往 stderr 打一条提示。
 
+## 本地会话效率分析
+
+在仓库根目录运行：
+
+```bash
+pnpm analyze:sessions
+pnpm analyze:sessions -- --since 7d --clients claude --format json
+```
+
+分析器只读扫描 `~/.claude/projects` 与 `~/.codex/sessions` 中最近 30 天的
+JSONL，识别真实 AtWebPilot 工具调用及重复验证、固定等待、重复截图、可批量填表等
+模式。输出只包含聚合计数、参数字段名与不可逆指纹；不会输出或保存 prompt、参数值、
+工具结果正文、凭证或绝对会话路径。使用 `--help` 查看目录覆盖等选项。
+
 ### 从 0.0.70 及更早版本迁移
 
 | 旧 | 新 |
@@ -95,7 +109,7 @@ hover / uploadFile / scroll / waitFor`）；`browser_storage` 也不会列出，
 | `browser_drag` / `browser_drop` | `browser_drag` / `browser_drop` |
 | `browser_file_upload` | `browser_uploadFile` |
 | `browser_navigate` / `browser_navigate_back` | `browser_navigate`（`action` 取 `goto` / `back` / `forward` / `reload`） |
-| `browser_tabs` | `browser_listTabs` / `openTab` / `closeTab` / `switchToTab` |
+| `browser_tabs` | `browser_listTabs` / `openTab` / `closeTab`; `switchToTab` 需按需发现，仅用于用户明确要求前台切换 |
 | `browser_close` | `browser_closeTab` |
 | `browser_resize` | `browser_resize` |
 | `browser_take_screenshot` | `browser_screenshot`（含 `fullPage` / `format` / `scale`） |

package/dist/index.js

@@ -1425,7 +1425,9 @@ var TOOL_DEFS = [
   {
     name: "switchToTab",
     description: "[META] \u628A Chrome \u524D\u53F0\u5207\u5230\u76EE\u6807 tab\u3002tabId \u5FC5\u987B\u5DF2\u5728 attachedTabs \u6216\u5F53\u524D tab\u3002",
-    mcp: { description: "Bring the session's tab to the foreground." },
+    mcp: {
+      description: "Bring the session's tab and Chrome window to the foreground. Use only when the user explicitly asks to see that tab; all other browser tools already operate on the session-bound tab without this setup step."
+    },
     input_schema: {
       type: "object",
       properties: { tabId: { type: "integer" } },
@@ -1437,7 +1439,7 @@ var TOOL_DEFS = [
     name: "screenshot",
     description: "[VISION] \u622A\u5F53\u524D tab \u53EF\u89C1\u533A\u57DF\u4E3A PNG\uFF08\u81EA\u52A8\u4F5C\u4E3A image block \u6CE8\u5165\u4E0B\u8F6E\uFF09\u3002\u7528\u4E8E\u89C6\u89C9\u8C03\u8BD5\u3001\u770B\u56FE\u56DE\u7B54\u3001\u6838\u5BF9 page-index \u8BC1\u636E\u3002\n\u5982\u679C\u5DF2\u6709 searchPageIndex/extractPageFields \u8FD4\u56DE\u7684 blockId/indexId\uFF0C\u4F18\u5148\u4F20 {blockId,indexId}\uFF1B\u5DE5\u5177\u4F1A\u6EDA\u52A8\u5E76\u9AD8\u4EAE\u8BE5\u5C40\u90E8\u533A\u57DF\u540E\u622A\u56FE\u3002\u4E5F\u53EF\u4F20 selector\u3002",
     mcp: {
-      description: "PNG/JPEG of the visible viewport, returned as an image block. selector or blockId scrolls to and highlights that region first; fullPage stitches the whole page.",
+      description: "PNG/JPEG returned as an image block. With opt-in CDP enabled, captures viewport/fullPage/selector in the background without activating or scrolling the tab; compatibility mode may temporarily activate the tab.",
       params: { blockId: "page-index blockId to frame", indexId: "indexId that produced blockId", scale: "0.1\u20131; smaller saves tokens" }
     },
     input_schema: {
@@ -1828,7 +1830,7 @@ var TOOL_DEFS = [
   {
     name: "resize",
     description: "[FLOW] \u628A\u89C6\u53E3\u8C03\u6574\u5230\u6307\u5B9A\u5C3A\u5BF8\u3002main-world \u6863\u91CF\u53D6 outerWidth-innerWidth \u53CD\u63A8\u6D4F\u89C8\u5668\u8FB9\u6846\u540E\u6539\u7A97\u53E3\u5916\u6846\uFF0C\u89C6\u53E3\u7CBE\u786E\u4F46**\u7528\u6237\u7684\u7A97\u53E3\u4F1A\u771F\u7684\u53D8\u5927\u5C0F**\uFF1Bcdp \u6863\u7528 Emulation \u8986\u76D6\u8BBE\u5907\u5C3A\u5BF8\uFF0C\u4E0D\u52A8\u771F\u5B9E\u7A97\u53E3\u3002",
-    mcp: { description: "Resize the viewport to width\xD7height." },
+    mcp: { description: "Resize the viewport to width\xD7height and return the measured actualViewport plus verified status. Do not re-measure with runJS." },
     input_schema: {
       type: "object",
       properties: {
@@ -1927,7 +1929,6 @@ var CORE_TOOLS = [
   "listTabs",
   "openTab",
   "closeTab",
-  "switchToTab",
   "resize",
   "scroll",
   // observation
@@ -2072,7 +2073,8 @@ var DISCOVERABLE_GROUPS = {
   "browser-data": ["browser_searchBookmarks", "browser_searchHistory"],
   inspect: ["browser_inspectElement", "browser_highlight", "browser_getValue", "browser_extractFormState"],
   "legacy-dom": ["browser_snapshotDOM", "browser_querySelector", "browser_querySelectorAll", "browser_extractImages", "browser_focus"],
-  form: ["browser_submitForm"]
+  form: ["browser_submitForm"],
+  tabs: ["browser_switchToTab"]
 };
 var GROUP_BY_NAME = new Map(
   Object.entries(DISCOVERABLE_GROUPS).flatMap(([g, names]) => names.map((n) => [n, g]))
@@ -2085,13 +2087,19 @@ function discoveryCatalog(all, advertised) {
 }
 
 // src/discover-tool.ts
+var DISCOVER_GROUPS = Object.keys(DISCOVERABLE_GROUPS);
 var DISCOVER_TOOL = {
   name: "browser_discoverTools",
-  description: "The default tool list is the core set. Call with no arguments to see the catalog of additional browser tools (export, network, storage, browser-data, inspect, legacy-dom, form). Call with enable=[names] to add them to tools/list for this server; 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]. 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.",
   inputSchema: {
     type: "object",
     properties: {
-      enable: { type: "array", items: { type: "string" }, description: "Tool names from the catalog to advertise" }
+      enable: { type: "array", items: { type: "string" }, description: "Tool names from the catalog to advertise" },
+      enableGroups: {
+        type: "array",
+        items: { type: "string", enum: DISCOVER_GROUPS },
+        description: "Known groups to advertise directly, without a catalog round trip"
+      }
     },
     additionalProperties: false
   }
@@ -2102,23 +2110,36 @@ function isRunnable(t, supported) {
 function handleDiscover(input) {
   const { all, advertised, args, supported } = input;
   const byName = new Map(all.map((t) => [t.name, t]));
-  const requested = Array.isArray(args.enable) ? args.enable.map(String) : null;
-  if (!requested) {
+  const hasSelection = Array.isArray(args.enable) || Array.isArray(args.enableGroups);
+  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 unknownGroups = groups.filter((group) => !DISCOVER_GROUPS.includes(group));
+  const grouped = groups.flatMap(
+    (group) => DISCOVERABLE_GROUPS[group] ?? []
+  );
+  const requestedByName = /* @__PURE__ */ new Map();
+  for (const raw of explicit) {
+    const name = raw.startsWith("browser_") ? raw : `browser_${raw}`;
+    requestedByName.set(name, raw);
+  }
+  for (const name of grouped) {
+    if (!requestedByName.has(name)) requestedByName.set(name, name);
+  }
   const enabled = [];
   const unknown = [];
   const unsupported = [];
-  for (const raw of requested) {
-    const name = raw.startsWith("browser_") ? raw : `browser_${raw}`;
+  for (const [name, reportAs] of requestedByName) {
     const t = byName.get(name);
     if (!t) {
-      unknown.push(raw);
+      unknown.push(reportAs);
       continue;
     }
     if (!isRunnable(t, supported)) {
-      unsupported.push(raw);
+      unsupported.push(reportAs);
       continue;
     }
     if (advertised.has(name)) continue;
@@ -2128,6 +2149,7 @@ function handleDiscover(input) {
   return {
     enabled,
     ...unknown.length ? { unknown } : {},
+    ...unknownGroups.length ? { unknownGroups } : {},
     ...unsupported.length ? { unsupported } : {},
     changed: enabled.length > 0
   };
@@ -2432,7 +2454,12 @@ function toolResult(gen, data) {
   const d = data ?? {};
   if (typeof d.data !== "string") return ok(data);
   const mimeType = typeof d.media_type === "string" ? d.media_type : "image/png";
-  return { content: [{ type: "image", data: d.data, mimeType }] };
+  const { data: imageData, media_type: _mediaType, ...metadata } = d;
+  const content = [{ type: "image", data: imageData, mimeType }];
+  if (Object.keys(metadata).length > 0) {
+    content.push({ type: "text", text: JSON.stringify(metadata) });
+  }
+  return { content };
 }
 var fail2 = (message) => ({ content: [{ type: "text", text: message }], isError: true });
 async function dispatchCall(deps, name, args, onPairingRequired, state = DEFAULT_STATE, onListChanged) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attson/atwebpilot-mcp",
-  "version": "0.0.71",
+  "version": "0.0.73",
   "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",
@@ -27,7 +27,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "build": "tsup",
-    "start": "tsx src/index.ts"
+    "start": "tsx src/index.ts",
+    "analyze:sessions": "tsx src/session-analysis/cli.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",