npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@mearl/mcp-server

v3.1.5

Published

MCP Server for Mearl - enables AI to interact with Chrome browser requests and logs

Readme

Mearl MCP Server

简体中文 | English

将支持 MCP 的 Agent 接入 Mearl 浏览器,让它操作页面、查看请求和日志,并调用已注册的 Skill 插件。

MCP 工具与 CLI、SDK 共用浏览器动作、插件入口和控制会话。

浏览器交互工作流

首次进入页面时调用 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。

打开、导航或快照时,已发现的主文档 WebMCP 工具会随 webmcp 数组返回。用工具的 ref 和输入 Schema 调用 browser_page_call_tool(CLI 为 page_call_tool,SDK 为 pageCallTool)。默认发现不阻塞页面动作,未发现工具时省略字段。传 browser_page_snapshot({ tabId, includeWebMcp: "full" }) 可补查,空目录返回 webmcp: []。扩展和直连 CDP 都可发现工具。浏览器能按注册实例执行时才会提供可调用的 ref,较旧的浏览器返回 webmcpStatus: "discovery-only"。页面导航或引用失效后重新获取目录。

浏览器工具与 CLI、SDK 使用同一返回结构。快照中的 @eN 可直接操作,内部节点映射只保存在运行时。 常规响应的 session 包含会话 ID、浏览器、传输、状态和代次;标签页清单通过 browser_tab_list 查询,session_manage 的普通会话交接结果还包含会话页面的 tabs。外部 Provider 使用 browser 且不传 session,返回 { controlSessionMode: "external", operation, control },可按 Provider 声明执行 handoff、resume 或带 keepTabIds 的 end。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:

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(推荐,保持最新)

# 直接运行配置向导,会自动生成 npx 配置
npx @mearl/mcp-server --configure

方式二:全局安装(启动更快)

# 全局安装
npm install -g @mearl/mcp-server

# 运行配置向导
mearl-mcp-configure

配置向导支持 VSCode Copilot、Claude Code、Cursor、Qoder、Codex、OpenCode v1/v2、Pi 和 DeepSeek Harness (dsh)。完成后重启 MCP 客户端即可使用。

新增客户端按配置目录检测,--yes 配置已检测客户端;未初始化的客户端可在交互向导中选择。

| 客户端 | 用户配置 | | --- | --- | | OpenCode | $XDG_CONFIG_HOME/opencode/opencode.json(默认 ~/.config/opencode/);存在 opencode.jsonc 时优先编辑它 | | Pi | $PI_CODING_AGENT_DIR/mcp.json(默认 ~/.pi/agent/mcp.json),需要支持原生 MCP 的 Pi | | DeepSeek Harness | $DSH_HOME/cordis.patch.yml(默认 ~/.dsh/cordis.patch.yml),插入 mcp-mearl,适用于所有 profile |

OpenCode 按已有 MCP 结构识别 v1/v2;没有可识别结构时读取 opencode --version,无法确定版本则报错且不写入。配置保留其他服务、设置及 JSONC/YAML 注释,DSH 的 !!js 标签也会保留;重复安装更新同一个条目,卸载只移除 Mearl 条目。损坏的配置会报错并保留原文件。

已有远程 Mearl 条目时,安装器会报错并保留配置;需先移除该条目才能配置本地服务。OpenCode 卸载会检查 opencode.json 和 opencode.jsonc 两份文件。

使用

打开要调试的网页,在 AI 客户端中发送:

列出当前标签页
查看当前页面截图
获取指定标签页最近的 HTTP 请求,source 使用 all

已通过 @mearl/setup plugin 注册的 Skill 插件使用固定的 plugin_invoke 工具调用:

{
  "plugin": "site-tools",
  "command": "list",
  "input": { "pageIndex": 2 },
  "browser": "<可选 Browser ID>",
  "timeoutSec": 30
}

plugin 使用 MCP Server 所在机器已注册的名称;当前能力目录声明的插件可按需安装并注册。插件的本机代码、身份和文件从该 MCP Server 所在宿主执行或读取;插件内的浏览器操作使用当前选择的浏览器,或请求中显式传入的 browser。

本地开发

pnpm install
pnpm --filter @mearl/mcp-server build

运行配置向导,选择使用自定义 Extension ID:

node packages/mcp-server/dist/configure-bin.js --extension-id <你的开发版扩展ID>

💡 在 chrome://extensions/ 查看你的 Extension ID

发行版本与根仓库及其他 Mearl 包统一维护,server.json 的版本也必须一致。发行流程见发布文档。

卸载

# 全局安装的版本
mearl-mcp-uninstall

# 或使用 npx
npx @mearl/mcp-server --uninstall

故障排查

配置失败:检查目录权限和路径是否存在

# macOS
mkdir -p ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts

"Native host has exited":删除配置后重新运行

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