@mearl/mcp-server 3.0.0-beta.0 → 3.0.0-beta.10

package/README.md

@@ -1,133 +1,165 @@
 # Mearl MCP Server
 
-让 AI 能够与浏览器实时交互的 MCP 服务器。
+[English](README.md) | [简体中文](README.zh-CN.md)
 
-本仓库处于 3.0 迁移阶段；下列发行版命令用于正式发行环境，当前源码验证使用本地构建。通用控制由核心提供，业务协议、埋点解析与完整 App 模拟由已安装能力提供。
+An MCP server for real-time AI interaction with browsers.
 
-## 功能
+MCP tools share browser actions, plugin entry points, and control sessions with the CLI and SDK. Version 3.0 uses npm's `beta` channel.
 
-- 📊 **browser_get_requests**: 获取历史请求记录
-- 📊 **browser_get_events**: 获取指定标签页的 RUM/aplus/ARMS 埋点事件，无需打开 DevTools panel
-- 📝 **browser_get_logs**: 获取控制台日志
-- 🎭 **browser_set_mock**: 动态设置 Mock 数据
-- 🌐 **browser_list**: 统一列出普通浏览器和托管浏览器，返回默认目标、类型及连接状态
-- 📴 **browser_release**: 按用户明确要求释放 debugger/CDP 控制和会话级临时效果，并保留浏览器与全部标签页
-- 🚀 **browser_launch / browser_close**: 启动或关闭本地 Chrome 及已注册 Provider 浏览器；配对实例会直接返回二维码链接
-- 🌐 **browser_page_snapshot**: 首次获取页面结构和可交互元素
-- 🔎 **browser_page_inspect**: 查询 DOM 数量、边框盒、计算样式、遮挡、溢出和滚动容器
-- ⚡ **browser_page_click/drag/type/hover/scroll/press/upload**: 执行页面动作，默认内置观察，返回通知、可交互控件、焦点、导航或直接打开的新标签页
-- 🧩 **plugin_invoke**: 调用当前 MCP Server 宿主已注册的 Skill 插件
+## Features
 
-## 浏览器交互工作流
+- 📊 **browser_get_requests**: Retrieve historical requests.
+- 📊 **browser_get_events**: Retrieve a tab's RUM/aplus/ARMS analytics events without opening DevTools.
+- 📝 **browser_get_logs**: Retrieve console logs.
+- 🎭 **browser_set_mock**: Configure mock data dynamically.
+- 🌐 **browser_list**: List ordinary and managed browsers with default targets, types, and connection states.
+- 📴 **browser_release**: On explicit user request, release debugger/CDP control and session-scoped temporary effects while keeping the browser and all tabs open.
+- 🚀 **browser_launch / browser_close**: Launch or close local Chrome and registered Provider browsers. Pairing instances return QR-code links directly.
+- 🌐 **browser_page_snapshot**: Establish initial page structure and interactive elements.
+- 🔎 **browser_page_inspect**: Query DOM counts, bounding boxes, computed styles, occlusion, overflow, and scroll containers.
+- ⚡ **browser_page_click/drag/type/hover/scroll/press/upload**: Perform page actions with observation enabled by default, returning notifications, interactive controls, focus, navigation, or directly opened tabs.
+- 🧩 **plugin_invoke**: Invoke Skill plugins registered on the MCP Server host.
+- 💻 **browser_run_code**: Compose browser APIs and registered Skill commands in JavaScript.
 
-首次进入页面时调用 `browser_page_snapshot` 建立结构基线。后续点击、拖动、输入、悬停、滚动、按键和上传直接调用 `browser_page_click/drag/type/hover/scroll/press/upload`，它们默认内置观察，动作与异步同步在一次调用内完成；同页结果读取 `effects.notifications`、`effects.interactives` 和 `effects.focus`。新增或变化的可交互节点会尽量携带可直接用于后续动作的 `node.ref`，解析不到 ref 时回退使用 `node.selector`。导航结果读取新 URL 和就绪状态；动作直接打开新标签页时，`openedTabs` 返回可继续操作的 `tabId`，无需调用 `browser_tab_list`。通常仅在导航后、`fullSnapshotRecommended: true` 或需要视觉判断时重新 snapshot 或截图；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。`browser_page_eval` 默认裸执行，仅在表达式会修改页面且需要变化信号时显式传 `observe` 对象。
+## Browser interaction workflow
 
-长列表重新感知时优先使用 `browser_page_snapshot(mode: "viewport")`；已知 CSS 区域时使用 `rootSelector`，已有 ref 时使用 `rootRef`，只查找特定文案或角色时使用 `query`；仅需要当前视口内的控件时使用 `mode: "interactive"`，避免整页 AX Tree 占用上下文。AX 信息为空或过于稀疏时显式使用 `mode: "dom"`，读取实际渲染文本、原生控件、显式 role 和高置信 clickable 节点，并继续通过返回的 `@ref` 操作；DOM 模式不会猜测任意容器的业务语义。`interactive` 在视口内缺少 AX 控件语义时仍只回退到 AX viewport，并返回 `fallbackMode: "viewport"`，不会自动切换数据来源。重复文本点击可用 `scope` 限定子树，滚动子节点所在容器可用 `containerPolicy: "nearest"`。
+Call `browser_page_snapshot` on first entering a page to establish structure. Then call `browser_page_click/drag/type/hover/scroll/press/upload` directly. Observation is built in by default, combining actions and asynchronous synchronization in one call. Read same-page results from `effects.notifications`, `effects.interactives`, and `effects.focus`. New or changed interactive nodes include actionable `node.ref` values where possible, otherwise `node.selector`. For navigation, read the new URL and readiness; directly opened tabs return reusable `tabId` values in `openedTabs`, without `browser_tab_list`. Usually take another snapshot or screenshot only after navigation, `fullSnapshotRecommended: true`, or when visual judgment is needed. After scrolling, request a viewport snapshot if the next step needs new content. `browser_page_eval` executes without observation by default; explicitly pass `observe` when an expression changes the page and change signals are needed.
 
-需要元素数量、边框盒、计算样式或中心点遮挡时使用 `browser_page_inspect`；DevTools 当前选中元素使用 `selector: "$0"`。传 `filter: "horizontal-overflow"` 可直接列出 `scrollWidth > clientWidth` 的节点、溢出像素和最近滚动容器。按文本查询时先用 snapshot `query` 获取结构化 `matches` 和 ref，再检查对应 ref。
+For long lists, prefer `browser_page_snapshot(mode: "viewport")`. Scope known CSS regions with `rootSelector`, existing refs with `rootRef`, and text or role searches with `query`. Use `mode: "interactive"` for viewport controls only, avoiding a full AX Tree. If AX data is empty or sparse, explicitly use `mode: "dom"` for rendered text, native controls, explicit roles, and high-confidence clickable nodes, then act through returned `@ref` values. DOM mode does not infer arbitrary containers' business meaning. Without AX control semantics in the viewport, `interactive` falls back only to AX viewport with `fallbackMode: "viewport"`, never changing data sources automatically. Use `scope` to disambiguate repeated text and `containerPolicy: "nearest"` to scroll a child's container.
 
-页面动作传 `observe: false` 可关闭内置观察仅执行裸动作；不需要在每次动作后固定追加 wait、snapshot 或 screenshot。
+Use `browser_page_inspect` for counts, bounding boxes, computed styles, and center-point occlusion. Use `selector: "$0"` for the selected DevTools element. `filter: "horizontal-overflow"` lists nodes with `scrollWidth > clientWidth`, overflow pixels, and nearest scroll containers. For text queries, first obtain structured `matches` and refs with snapshot `query`, then inspect the refs.
 
-浏览器工具与 CLI、SDK 使用同一返回结构。快照中的 `@eN` 可直接操作，内部节点映射只保存在运行时。
-常规响应的 `session` 包含会话 ID、浏览器、传输、状态和代次；标签页清单通过 `browser_tab_list`
-查询，`browser_control` 的交接结果还包含会话页面的 `tabs`。`browser_run_actions` 的步骤使用各 action 的返回结构。
-`browser_get_requests` 指定非空 `fields` 时默认只返回提取字段及请求元数据；同时需要正文时传
-`includeBody:true`。省略正文时不返回 `postData` / `responseBody` 字段。
+Set `observe: false` for bare page actions. Do not routinely append wait, snapshot, or screenshot calls after every action.
 
-`browser_page_click.clickMode` 默认 `auto`：可见桌面页使用可信 mouse，移动模拟页使用可信 touch；目标页隐藏时不会切换标签或还原窗口，而是使用 DOM fallback，并返回 `dispatchMode: "dom"`、`fallbackReason: "page-hidden"`。可用 `dom` / `mouse` / `touch` 覆盖自动策略；显式 `touch` 要求目标页可见，否则会直接返回前置条件错误；可信输入返回实际 `pointerType`。
+Browser tools return the same structures as the CLI and SDK. Snapshot `@eN` refs are directly actionable; internal node mappings remain in the runtime.
+Ordinary response `session` includes session ID, browser, transport, state, and generation. Query tabs with `browser_tab_list`;
+`browser_control` handoff also includes session `tabs`. `browser_run_actions` steps retain each action's return structure.
+With nonempty `fields`, `browser_get_requests` returns extracted fields and request metadata by default. To also include bodies, pass
+`includeBody:true`. Otherwise `postData` / `responseBody` are omitted.
 
-## 安装
+`browser_page_click.clickMode` defaults to `auto`: visible desktop pages use trusted mouse input and simulated mobile pages use trusted touch. Hidden pages use a DOM fallback without switching tabs or restoring windows, returning `dispatchMode: "dom"` and `fallbackReason: "page-hidden"`. Override with `dom` / `mouse` / `touch`. Explicit `touch` requires a visible target or returns a precondition error. Trusted input returns the actual `pointerType`.
 
-**方式一：使用 npx（推荐，保持最新）**
+## Code composition
+
+`browser_run_code` accepts `{ code, browser?, session?, timeoutSec? }` and runs in an independent
+Node.js process on the MCP Server host, with the same injected SDK as CLI `mearl run`:
+
+```javascript
+const tab = await mearl.tabOpen({ url: 'https://example.com', reuse: 'prefer' });
+const result = await mearl.invokePlugin('notes', {
+  command: 'search',
+  input: { query: 'project' },
+});
+console.log(result);
+```
+
+`console.log(await mearl.help('pageClick'))` returns help shared with CLI `page_click --help`;
+`help()` lists methods and registered plugins; `help({ plugin, command? })` queries plugin help.
+`console.log(mearl.structure(result))` shows bounded field/type samples from an existing result. See the client's Agent scripting documentation.
+
+APIs and Skill commands inherit browser and session options. With `session: "new"`, first await a browser call establishing the session,
+then call the plugin. JavaScript variables reset on each invocation; continue browser tasks with the returned `session.sessionId` and `tabId`.
+Browser actions retain their return structures and failure semantics. When model decisions are needed, print necessary observations and end the invocation.
+
+Results include `success`, `stdout`, `stderr`, optional `session` / `error`, plus `executionStopped`,
+`mayHaveLateEffects`, and `pendingActions`. Print only data needed by the model and await all SDK calls.
+Failures set MCP `isError`. Default execution time is 60 seconds, combined stdout/stderr is limited to 256 KiB, and source to 1 MiB.
+MCP cancellation stops the script. Timeouts and cancellation cannot undo dispatched operations; inspect actual state before retrying.
+Scripts have the MCP Server host's Node.js permissions and inherit its working directory and environment. Load modules with `await import()`;
+execute DOM code through `mearl.pageEval`. Files and registered Skills are read from that host.
+
+## Installation
+
+**Option 1: npx (recommended, stays current)**
 
 ```bash
-# 直接运行配置向导，会自动生成 npx 配置
-npx @mearl/mcp-server --configure
+# Run the configuration wizard to generate npx configuration
+npx @mearl/mcp-server@beta --configure
 ```
 
-**方式二：全局安装（启动更快）**
+**Option 2: Global installation (faster startup)**
 
 ```bash
-# 全局安装
-npm install -g @mearl/mcp-server
+# Install globally
+npm install -g @mearl/mcp-server@beta
 
-# 运行配置向导
+# Run the configuration wizard
 mearl-mcp-configure
 ```
 
-配置向导会自动完成所有设置，支持 **VSCode Copilot**、**Claude Code**、**Cursor**。完成后重启 MCP 客户端即可使用。
+The wizard configures **VSCode Copilot**, **Claude Code**, and **Cursor**. Restart the MCP client afterward.
 
-## 使用
+## Usage
 
-打开要调试的网页，在 AI 客户端中发送：
+Open a page to debug and ask your AI client:
 
 ```
-列出当前标签页
-查看当前页面截图
-获取指定标签页最近的 HTTP 请求，source 使用 all
+List the current tabs
+Take a screenshot of the current page
+Get the latest HTTP requests for the specified tab using source all
 ```
 
-已通过 `@mearl/setup plugin` 注册的 Skill 插件使用固定的 `plugin_invoke` 工具调用：
+Invoke Skill plugins registered through `@mearl/setup plugin` with the fixed `plugin_invoke` tool:
 
 ```json
 {
   "plugin": "site-tools",
   "command": "list",
   "input": { "pageIndex": 2 },
-  "browser": "<可选 Browser ID>",
+  "browser": "<optional Browser ID>",
   "timeoutSec": 30
 }
 ```
 
-`plugin` 使用 MCP Server 所在机器已注册的名称；当前能力目录声明的插件可按需安装并注册。插件的本机代码、身份和文件从该 MCP Server 所在宿主执行或读取；插件内的浏览器操作使用当前选择的浏览器，或请求中显式传入的 `browser`。
+`plugin` is a name registered on the MCP Server machine. Plugins declared in the current capability catalog can be installed and registered on demand. Native plugin code, identities, and files execute or are read on that host. Browser operations use the selected browser or an explicitly supplied `browser`.
 
-## 本地开发
+## Local development
 
 ```bash
 pnpm install
 pnpm --filter @mearl/mcp-server build
 ```
 
-运行配置向导，选择使用自定义 Extension ID：
+Run the configuration wizard with a custom Extension ID:
 
 ```bash
-node packages/mcp-server/dist/configure-bin.js --extension-id <你的开发版扩展ID>
+node packages/mcp-server/dist/configure-bin.js --extension-id <your-development-extension-id>
 ```
 
-> 💡 在 `chrome://extensions/` 查看你的 Extension ID
+> 💡 Find the Extension ID at `chrome://extensions/`.
 
-发行版本与根仓库及其他 Mearl 包统一维护，`server.json` 的版本也必须一致。完整产品迁移与发布准备完成后，按仓库统一流程发行。
+Release versions are maintained together with the root repository and other Mearl packages; `server.json` must match. See the [release guide](../../docs/releases.md).
 
-## 卸载
+## Uninstall
 
 ```bash
-# 全局安装的版本
+# Globally installed version
 mearl-mcp-uninstall
 
-# 或使用 npx
-npx @mearl/mcp-server --uninstall
+# Or use npx
+npx @mearl/mcp-server@beta --uninstall
 ```
 
-## 故障排查
+## Troubleshooting
 
-**配置失败**：检查目录权限和路径是否存在
+**Configuration fails**: Check directory permissions and path existence.
 
 ```bash
 # macOS
 mkdir -p ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts
 ```
 
-**"Native host has exited"**：删除配置后重新运行
+**"Native host has exited"**: Remove the configuration and rerun.
 
 ```bash
-rm ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.alibaba.mearl.mcp.*
+rm ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/ai.mearl.mcp.*
 ```
 
-**Extension ID 不匹配**：使用 `mearl-mcp-configure` 重新配置
+**Extension ID mismatch**: Reconfigure with `mearl-mcp-configure`.
 
-**查看日志**：
+**Logs:**
 
-- MCP Server: AI 客户端的输出面板
+- MCP Server: The AI client's output panel.
 - Chrome Extension: `chrome://extensions/` → Mearl → background page
 
 ## License

package/README.zh-CN.md

@@ -0,0 +1,167 @@
+# Mearl MCP Server
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+让 AI 能够与浏览器实时交互的 MCP 服务器。
+
+MCP 工具与 CLI、SDK 共用浏览器动作、插件入口和控制会话。3.0 使用 npm 的 `beta` 通道。
+
+## 功能
+
+- 📊 **browser_get_requests**: 获取历史请求记录
+- 📊 **browser_get_events**: 获取指定标签页的 RUM/aplus/ARMS 埋点事件，无需打开 DevTools panel
+- 📝 **browser_get_logs**: 获取控制台日志
+- 🎭 **browser_set_mock**: 动态设置 Mock 数据
+- 🌐 **browser_list**: 统一列出普通浏览器和托管浏览器，返回默认目标、类型及连接状态
+- 📴 **browser_release**: 按用户明确要求释放 debugger/CDP 控制和会话级临时效果，并保留浏览器与全部标签页
+- 🚀 **browser_launch / browser_close**: 启动或关闭本地 Chrome 及已注册 Provider 浏览器；配对实例会直接返回二维码链接
+- 🌐 **browser_page_snapshot**: 首次获取页面结构和可交互元素
+- 🔎 **browser_page_inspect**: 查询 DOM 数量、边框盒、计算样式、遮挡、溢出和滚动容器
+- ⚡ **browser_page_click/drag/type/hover/scroll/press/upload**: 执行页面动作，默认内置观察，返回通知、可交互控件、焦点、导航或直接打开的新标签页
+- 🧩 **plugin_invoke**: 调用当前 MCP Server 宿主已注册的 Skill 插件
+- 💻 **browser_run_code**: 使用 JavaScript 组合浏览器 API 与已注册 Skill 命令
+
+## 浏览器交互工作流
+
+首次进入页面时调用 `browser_page_snapshot` 建立结构基线。后续点击、拖动、输入、悬停、滚动、按键和上传直接调用 `browser_page_click/drag/type/hover/scroll/press/upload`，它们默认内置观察，动作与异步同步在一次调用内完成；同页结果读取 `effects.notifications`、`effects.interactives` 和 `effects.focus`。新增或变化的可交互节点会尽量携带可直接用于后续动作的 `node.ref`，解析不到 ref 时回退使用 `node.selector`。导航结果读取新 URL 和就绪状态；动作直接打开新标签页时，`openedTabs` 返回可继续操作的 `tabId`，无需调用 `browser_tab_list`。通常仅在导航后、`fullSnapshotRecommended: true` 或需要视觉判断时重新 snapshot 或截图；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。`browser_page_eval` 默认裸执行，仅在表达式会修改页面且需要变化信号时显式传 `observe` 对象。
+
+长列表重新感知时优先使用 `browser_page_snapshot(mode: "viewport")`；已知 CSS 区域时使用 `rootSelector`，已有 ref 时使用 `rootRef`，只查找特定文案或角色时使用 `query`；仅需要当前视口内的控件时使用 `mode: "interactive"`，避免整页 AX Tree 占用上下文。AX 信息为空或过于稀疏时显式使用 `mode: "dom"`，读取实际渲染文本、原生控件、显式 role 和高置信 clickable 节点，并继续通过返回的 `@ref` 操作；DOM 模式不会猜测任意容器的业务语义。`interactive` 在视口内缺少 AX 控件语义时仍只回退到 AX viewport，并返回 `fallbackMode: "viewport"`，不会自动切换数据来源。重复文本点击可用 `scope` 限定子树，滚动子节点所在容器可用 `containerPolicy: "nearest"`。
+
+需要元素数量、边框盒、计算样式或中心点遮挡时使用 `browser_page_inspect`；DevTools 当前选中元素使用 `selector: "$0"`。传 `filter: "horizontal-overflow"` 可直接列出 `scrollWidth > clientWidth` 的节点、溢出像素和最近滚动容器。按文本查询时先用 snapshot `query` 获取结构化 `matches` 和 ref，再检查对应 ref。
+
+页面动作传 `observe: false` 可关闭内置观察仅执行裸动作；不需要在每次动作后固定追加 wait、snapshot 或 screenshot。
+
+浏览器工具与 CLI、SDK 使用同一返回结构。快照中的 `@eN` 可直接操作，内部节点映射只保存在运行时。
+常规响应的 `session` 包含会话 ID、浏览器、传输、状态和代次；标签页清单通过 `browser_tab_list`
+查询，`browser_control` 的交接结果还包含会话页面的 `tabs`。`browser_run_actions` 的步骤使用各 action 的返回结构。
+`browser_get_requests` 指定非空 `fields` 时默认只返回提取字段及请求元数据；同时需要正文时传
+`includeBody:true`。省略正文时不返回 `postData` / `responseBody` 字段。
+
+`browser_page_click.clickMode` 默认 `auto`：可见桌面页使用可信 mouse，移动模拟页使用可信 touch；目标页隐藏时不会切换标签或还原窗口，而是使用 DOM fallback，并返回 `dispatchMode: "dom"`、`fallbackReason: "page-hidden"`。可用 `dom` / `mouse` / `touch` 覆盖自动策略；显式 `touch` 要求目标页可见，否则会直接返回前置条件错误；可信输入返回实际 `pointerType`。
+
+## 代码组合调用
+
+`browser_run_code` 接受 `{ code, browser?, session?, timeoutSec? }`，在 MCP Server 宿主的独立
+Node.js 进程运行代码，预注入与 CLI `mearl run` 相同的 SDK：
+
+```javascript
+const tab = await mearl.tabOpen({ url: 'https://example.com', reuse: 'prefer' });
+const result = await mearl.invokePlugin('notes', {
+  command: 'search',
+  input: { query: 'project' },
+});
+console.log(result);
+```
+
+`console.log(await mearl.help('pageClick'))` 返回与 CLI `page_click --help` 共享的帮助；
+`help()` 列出方法和已注册插件，`help({ plugin, command? })` 查询插件帮助。
+`console.log(mearl.structure(result))` 查看任意已取得结果的有界字段/类型样本，具体用法见 client 的 Agent 脚本说明。
+
+浏览器与会话选项由 API 和 Skill 命令继承。`session: "new"` 需要先 await 建立会话的浏览器调用，
+然后再调用插件。脚本每轮重建 JS 变量，浏览器任务通过返回的 `session.sessionId` 与 `tabId` 继续。
+浏览器动作保留原有返回结构与失败语义；需要模型决策时，打印必要观察后结束本轮。
+
+结果包含 `success`、`stdout`、`stderr`、可选 `session` / `error`，以及 `executionStopped`、
+`mayHaveLateEffects`、`pendingActions`。仅打印需要返回模型的数据，await 所有 SDK 调用；
+失败会设置 MCP `isError`。默认执行时限为 60 秒，stdout/stderr 合计最多 256 KiB，源码最多 1 MiB；
+MCP 取消会停止脚本。超时或取消不能撤销已派发的操作，应先核验现场再决定是否重试。
+脚本拥有 MCP Server 宿主的 Node.js 权限，并继承其工作目录与环境；通过 `await import()` 加载模块，
+DOM 代码通过 `mearl.pageEval` 执行。文件和已注册 Skill 均从该宿主读取。
+
+## 安装
+
+**方式一：使用 npx（推荐，保持最新）**
+
+```bash
+# 直接运行配置向导，会自动生成 npx 配置
+npx @mearl/mcp-server@beta --configure
+```
+
+**方式二：全局安装（启动更快）**
+
+```bash
+# 全局安装
+npm install -g @mearl/mcp-server@beta
+
+# 运行配置向导
+mearl-mcp-configure
+```
+
+配置向导会自动完成所有设置，支持 **VSCode Copilot**、**Claude Code**、**Cursor**。完成后重启 MCP 客户端即可使用。
+
+## 使用
+
+打开要调试的网页，在 AI 客户端中发送：
+
+```
+列出当前标签页
+查看当前页面截图
+获取指定标签页最近的 HTTP 请求，source 使用 all
+```
+
+已通过 `@mearl/setup plugin` 注册的 Skill 插件使用固定的 `plugin_invoke` 工具调用：
+
+```json
+{
+  "plugin": "site-tools",
+  "command": "list",
+  "input": { "pageIndex": 2 },
+  "browser": "<可选 Browser ID>",
+  "timeoutSec": 30
+}
+```
+
+`plugin` 使用 MCP Server 所在机器已注册的名称；当前能力目录声明的插件可按需安装并注册。插件的本机代码、身份和文件从该 MCP Server 所在宿主执行或读取；插件内的浏览器操作使用当前选择的浏览器，或请求中显式传入的 `browser`。
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm --filter @mearl/mcp-server build
+```
+
+运行配置向导，选择使用自定义 Extension ID：
+
+```bash
+node packages/mcp-server/dist/configure-bin.js --extension-id <你的开发版扩展ID>
+```
+
+> 💡 在 `chrome://extensions/` 查看你的 Extension ID
+
+发行版本与根仓库及其他 Mearl 包统一维护，`server.json` 的版本也必须一致。发行流程见[发布文档](../../docs/releases.zh-CN.md)。
+
+## 卸载
+
+```bash
+# 全局安装的版本
+mearl-mcp-uninstall
+
+# 或使用 npx
+npx @mearl/mcp-server@beta --uninstall
+```
+
+## 故障排查
+
+**配置失败**：检查目录权限和路径是否存在
+
+```bash
+# macOS
+mkdir -p ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts
+```
+
+**"Native host has exited"**：删除配置后重新运行
+
+```bash
+rm ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/ai.mearl.mcp.*
+```
+
+**Extension ID 不匹配**：使用 `mearl-mcp-configure` 重新配置
+
+**查看日志**：
+
+- MCP Server: AI 客户端的输出面板
+- Chrome Extension: `chrome://extensions/` → Mearl → background page
+
+## License
+
+[Apache-2.0](../../LICENSE)

package/dist/THIRD_PARTY_NOTICES.txt

@@ -1,6 +1,6 @@
 Third-party code included in this bundle retains the following notices.
 
-@modelcontextprotocol/sdk@1.27.1
+@modelcontextprotocol/sdk@1.32.0
 LICENSE
 
 MIT License

package/dist/configure.js

@@ -345,7 +345,7 @@ export async function runConfigure(argv = process.argv.slice(2)) {
     console.log('\n✅ 全部配置完成！');
     console.log('\n💡 后续步骤:');
     console.log('   1. 重启 MCP 客户端');
-    console.log('   2. 打开淘宝/飞猪页面');
+    console.log('   2. 打开需要调试的页面');
     console.log('   3. 在 AI 中测试: "获取最近 5 个请求"\n');
 }
 export async function main(argv = process.argv.slice(2)) {

package/dist/constants.d.ts

@@ -6,5 +6,5 @@ export declare const RESPONSE_SIZE_SMALL: number;
 export declare const RESPONSE_SIZE_MEDIUM: number;
 export declare const RESPONSE_SIZE_LARGE: number;
 export declare const RESPONSE_SIZE_MAX: number;
-export declare const HOST_NAME = "com.alibaba.mearl.mcp";
+export declare const HOST_NAME: "ai.mearl.mcp";
 export declare const DEFAULT_EXTENSION_ID = "aoehhjnofngknnjefamjbplchbolghkm";

package/dist/constants.js

@@ -1,3 +1,4 @@
+import { MEARL_NATIVE_HOST_NAMES } from '@mearl/client/native-host';
 /**
  * MCP Server 共享常量
  */
@@ -9,5 +10,5 @@ export const RESPONSE_SIZE_MEDIUM = 200 * 1024; // 200KB - 中等响应，格式
 export const RESPONSE_SIZE_LARGE = 500 * 1024; // 500KB - 大响应，压缩+提示
 export const RESPONSE_SIZE_MAX = 1024 * 1024; // 1MB - 超大响应，截断+建议
 // Native Messaging Host 配置
-export const HOST_NAME = 'com.alibaba.mearl.mcp';
+export const HOST_NAME = MEARL_NATIVE_HOST_NAMES.mcp;
 export const DEFAULT_EXTENSION_ID = 'aoehhjnofngknnjefamjbplchbolghkm';