@mallocfeng/chromedev 0.1.0 → 0.1.1

package/README.md

@@ -13,7 +13,7 @@ http://127.0.0.1:8787/mcp
 整个流程只有两步：
 
 1. 在 Chrome 中开启远程调试
-2. 安装并启动 `chromedev` 服务
+2. 用 npm 安装并启动 `chromedev`
 
 ### 1. 在 Chrome 中开启远程调试
 
@@ -32,25 +32,19 @@ http://127.0.0.1:8787/mcp
 
 ### 2. 安装并启动服务
 
-推荐直接用 npm 全局安装：
+安装：
 
 ```bash
 npm install -g @mallocfeng/chromedev
 ```
 
-安装完成后，后台启动：
+启动：
 
 ```bash
 chromedev run
 ```
 
-如果你是在项目源码目录里本地运行，也可以用：
-
-```bash
-node ./bin/chromedev.mjs run
-```
-
-成功后会看到：
+成功后会看到类似输出：
 
 ```text
 chromedev started in background (pid 12345)
@@ -59,47 +53,9 @@ endpoint: http://127.0.0.1:8787/mcp
 
 这表示服务已经在后台运行，其他 AI 或程序现在可以访问 `http://127.0.0.1:8787/mcp`。
 
-## npm 安装
-
-推荐安装方式：
-
-```bash
-npm install -g @mallocfeng/chromedev
-```
-
-安装完成后可直接使用：
-
-```bash
-chromedev run
-chromedev status
-chromedev stop
-```
-
-如果你不想全局安装，也可以临时执行：
-
-```bash
-npx @mallocfeng/chromedev run
-```
-
-如果用户把这个 GitHub 仓库地址直接发给 AI，AI 应该按下面的步骤理解和执行：
-
-1. 先安装命令行工具：
-
-```bash
-npm install -g @mallocfeng/chromedev
-```
-
-2. 然后启动服务：
-
-```bash
-chromedev run
-```
-
-3. 如果还需要安装 OpenClaw skill，再从 GitHub 下载项目源码，并把 `skills/chromedev` 拷贝到 OpenClaw 的 `skills` 目录。
-
 ## 常用命令
 
-后台启动：
+启动：
 
 ```bash
 chromedev run
@@ -111,16 +67,16 @@ chromedev run
 chromedev run --foreground
 ```
 
-查看状态：
+停止：
 
 ```bash
-chromedev status
+chromedev stop
 ```
 
-停止服务：
+查看状态：
 
 ```bash
-chromedev stop
+chromedev status
 ```
 
 查看日志路径：
@@ -129,21 +85,15 @@ chromedev stop
 chromedev logs
 ```
 
-如果你是在源码目录里本地运行，把 `chromedev` 换成：
-
-```bash
-node ./bin/chromedev.mjs
-```
-
 ## 如何验证服务正常
 
-看状态：
+查看状态：
 
 ```bash
 chromedev status
 ```
 
-看端点是否存在：
+检查端点：
 
 ```bash
 curl -i http://127.0.0.1:8787/mcp
@@ -151,81 +101,30 @@ curl -i http://127.0.0.1:8787/mcp
 
 如果返回 `400 Bad Request` 且内容类似 `No sessionId`，这是正常的，说明 MCP 端点已经存在。
 
-## 命令行访问网页示例
-
-列出当前页面：
-
-```bash
-node /Volumes/MacMiniDisk/project/chromeDev/skills/chromedev/scripts/http_mcp_call.mjs list_pages
-```
-
-打开 `163.com`：
-
-```bash
-node /Volumes/MacMiniDisk/project/chromeDev/skills/chromedev/scripts/http_mcp_call.mjs new_page '{"url":"https://www.163.com/","timeout":30000}'
-```
-
-读取当前页面快照：
-
-```bash
-node /Volumes/MacMiniDisk/project/chromeDev/skills/chromedev/scripts/http_mcp_call.mjs take_snapshot
-```
-
 ## 在 OpenClaw 中安装 skill
 
-这个项目里已经包含了一份 skill：
+这个仓库包含一份 skill：
 
 ```text
 skills/chromedev
 ```
 
-如果你是通过 GitHub 下载项目源码：
+安装方法：
 
-1. 打开仓库：`https://github.com/mallocfeng/chromeDev`
-2. 下载项目源码，或者直接 clone：
+1. 从 GitHub 下载项目源码：
 
 ```bash
 git clone https://github.com/mallocfeng/chromeDev.git
 ```
 
-3. 你需要用到的 skill 目录就是：
-
-```text
-chromeDev/skills/chromedev
-```
-
-如果用户把 GitHub 地址直接发给 AI，AI 可以按这套指令执行：
-
-```bash
-git clone https://github.com/mallocfeng/chromeDev.git
-```
-
-然后取出：
-
-```text
-chromeDev/skills/chromedev
-```
-
-再把它复制到 OpenClaw 的 `skills` 目录下。
-
-安装到 OpenClaw 的方法很简单：
-
-1. 把项目目录中的 `skills/chromedev` 目录拷贝到你 OpenClaw 工作目录的 `skills` 文件夹下。
-2. 如果你不清楚这个文件夹在哪里，可以先直接问 OpenClaw，它会告诉你当前 agent 工作目录在哪里。
-3. 拷贝进去以后，运行：
+2. 把其中的 `skills/chromedev` 目录拷贝到 OpenClaw 当前 agent 工作目录下的 `skills` 文件夹。
+3. 如果你不知道 OpenClaw 的工作目录在哪里，直接先问 OpenClaw。
+4. 拷贝完成后执行：
 
 ```bash
 openclaw gateway restart
 ```
 
-完成后就可以在 OpenClaw 里调用这个 skill。
-
-给 AI 的可执行描述可以直接写成这样：
-
-```text
-从 https://github.com/mallocfeng/chromeDev 下载项目，把其中的 skills/chromedev 目录拷贝到当前 OpenClaw agent 工作目录下的 skills 文件夹，然后执行 openclaw gateway restart。
-```
-
 目录结构应该像这样：
 
 ```text
@@ -239,7 +138,7 @@ openclaw gateway restart
 
 ## 在 OpenClaw 中使用
 
-在聊天框中可以直接这样输入：
+可以直接这样输入：
 
 ```text
 /chromedev 调用这个 skills 访问当前打开的纽约时报标签文章，并摘要
@@ -251,28 +150,11 @@ openclaw gateway restart
 调用 chromedev 这个 skills，访问纽约时报，并且摘要新闻
 ```
 
-这个 skill 会通过本地 `ChromeDev` MCP 服务访问你当前打开的 Chrome，并读取网页内容。
-
 注意：
 
-- OpenClaw 里的 skill 只负责“告诉 AI 怎么调用本地 ChromeDev 服务”
-- 真正提供浏览器访问能力的，还是你本机运行中的 `chromedev run`
-- 所以使用 skill 前，先确认本地 `chromedev` 服务已经启动
-
-## 日志与运行文件
-
-默认文件位置：
-
-- `~/.chromedev/run/chromedev.pid`
-- `~/.chromedev/run/chromedev.out.log`
-- `~/.chromedev/run/chromedev.err.log`
-
-直接查看日志：
-
-```bash
-tail -f ~/.chromedev/run/chromedev.out.log
-tail -f ~/.chromedev/run/chromedev.err.log
-```
+- skill 只负责告诉 AI 怎么调用本地 ChromeDev 服务
+- 真正提供浏览器访问能力的，是你本机运行中的 `chromedev run`
+- 使用 skill 前，先确认本地服务已经启动
 
 ## 默认配置
 
@@ -293,6 +175,21 @@ MCP_REQUEST_TIMEOUT=30000
 MCP_PORT=8788 chromedev run
 ```
 
+## 日志位置
+
+默认文件位置：
+
+- `~/.chromedev/run/chromedev.pid`
+- `~/.chromedev/run/chromedev.out.log`
+- `~/.chromedev/run/chromedev.err.log`
+
+查看日志：
+
+```bash
+tail -f ~/.chromedev/run/chromedev.out.log
+tail -f ~/.chromedev/run/chromedev.err.log
+```
+
 ## 常见问题
 
 ### 1. `EADDRINUSE: address already in use 127.0.0.1:8787`
@@ -321,14 +218,6 @@ MCP_PORT=8788 chromedev run
 3. 远程调试是否已经启用
 4. Chrome 是否弹出了授权确认框但还没有点
 
-### 3. 第一次连接会卡几秒
-
-通常是正常的，可能是：
-
-- Chrome 正在等待授权确认
-- `autoConnect` 正在连接浏览器
-- 页面本身还在加载
-
 ## 安全说明
 
 - 服务只应监听本地地址 `127.0.0.1`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mallocfeng/chromedev",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "CLI that exposes chrome-devtools-mcp as a local background service connected to your live Chrome browser.",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "LICENSE"
   ],
   "bin": {
-    "chromedev": "./bin/chromedev.mjs"
+    "chromedev": "bin/chromedev.mjs"
   },
   "scripts": {
     "start": "node ./server/chrome-mcp-daemon.mjs",

package/skills/chromedev/SKILL.md

@@ -8,6 +8,7 @@ description: Use this skill when you need to access or control a live Chrome bro
 Use this skill when the user wants browser-backed data from real web pages through the local `chrome-devtools-mcp` middleware running at `http://127.0.0.1:8787/mcp`.
 
 This skill is for cases where rendered browser state matters: JavaScript-heavy sites, login state in the user's Chrome, interaction flows, screenshots, DOM snapshots, or page data that should come from the live browser instead of plain HTTP fetches.
+The primary behavior is simple: if the user gives a URL, open it and return the page content. If the page is a list page, return the list content in order.
 
 ## Preconditions
 
@@ -29,9 +30,28 @@ A response like `400 Bad Request` with `No sessionId` means the endpoint exists
 2. Connect to `http://127.0.0.1:8787/mcp`.
 3. Use MCP browser tools to open or select a page.
 4. Prefer `take_snapshot` or `evaluate_script` for structured extraction.
-5. Use `wait_for` when content depends on async rendering.
+5. Use `wait_for` only when the page is still loading and you know a stable piece of text or UI state to wait for.
 6. Return the extracted data, not raw protocol noise.
 
+## How To Interpret Requests
+
+When the user gives a URL, treat it as a request to read the page and return its content:
+
+1. Open the target URL with `new_page`.
+2. Immediately call `list_pages` and select the page whose URL matches the target URL, or whose title clearly matches the target site.
+3. If multiple tabs match, choose the most recently opened matching tab.
+4. Only use `wait_for` if the page is still visibly loading and you know a stable text or selector to wait on.
+5. Use `take_snapshot` or `evaluate_script` to read the selected page.
+6. Return the page content faithfully and concisely. Do not add a summary unless the user explicitly asks for one.
+
+Examples:
+
+- "访问 163.com" means open `https://www.163.com/` and return the visible page content.
+- "给我这个网页内容" means read the current page and return the content as-is.
+- "访问纽约时报并读取文章" means open the NYTimes page or the specified article and return the article/page content.
+- "读取这个 list 页面" means return the visible list items in order, including titles, text, and links when available.
+- "读取 list" means extract the list structure, not a summary of the topic.
+
 ## Preferred tool order
 
 - `list_pages`: inspect current browser pages before changing state.
@@ -46,9 +66,11 @@ A response like `400 Bad Request` with `No sessionId` means the endpoint exists
 
 This skill includes a reusable script:
 
-- [`scripts/http_mcp_call.mjs`](/Volumes/MacMiniDisk/project/chromeDev/skills/chromedev/scripts/http_mcp_call.mjs)
+- [`scripts/http_mcp_call.mjs`](scripts/http_mcp_call.mjs)
 
 It connects to the local HTTP MCP endpoint and calls one tool.
+Use the copy that lives inside `skills/chromedev` so the skill always runs the version bundled with the current workspace.
+If `list_pages` reports that the selected page has been closed, the script creates a blank page and retries once so the tab list can be returned.
 
 If `@modelcontextprotocol/sdk` is missing in the current workspace, install it in that workspace first:
 
@@ -61,52 +83,70 @@ npm install @modelcontextprotocol/sdk
 List current pages:
 
 ```bash
-node /Volumes/MacMiniDisk/project/chromeDev/skills/chromedev/scripts/http_mcp_call.mjs list_pages
+node skills/chromedev/scripts/http_mcp_call.mjs list_pages
 ```
 
 Open `163.com`:
 
 ```bash
-node /Volumes/MacMiniDisk/project/chromeDev/skills/chromedev/scripts/http_mcp_call.mjs new_page '{"url":"https://www.163.com/","timeout":30000}'
+node skills/chromedev/scripts/http_mcp_call.mjs new_page '{"url":"https://www.163.com/","timeout":30000}'
+```
+
+Select the matching page before reading:
+
+```bash
+node skills/chromedev/scripts/http_mcp_call.mjs list_pages
+```
+
+Then choose the tab whose URL matches `https://www.163.com/` before calling `take_snapshot` or `evaluate_script`.
+
+Read the current 163.com page:
+
+```bash
+node skills/chromedev/scripts/http_mcp_call.mjs take_snapshot
 ```
 
 Get the current page snapshot:
 
 ```bash
-node /Volumes/MacMiniDisk/project/chromeDev/skills/chromedev/scripts/http_mcp_call.mjs take_snapshot
+node skills/chromedev/scripts/http_mcp_call.mjs take_snapshot
 ```
 
 Extract page title and URL:
 
 ```bash
-node /Volumes/MacMiniDisk/project/chromeDev/skills/chromedev/scripts/http_mcp_call.mjs evaluate_script '{"function":"() => ({ title: document.title, url: location.href })"}'
+node skills/chromedev/scripts/http_mcp_call.mjs evaluate_script '{"function":"() => ({ title: document.title, url: location.href })"}'
 ```
 
 Wait for specific text:
 
 ```bash
-node /Volumes/MacMiniDisk/project/chromeDev/skills/chromedev/scripts/http_mcp_call.mjs wait_for '{"text":["网易","163"],"timeout":30000}'
+node skills/chromedev/scripts/http_mcp_call.mjs wait_for '{"text":["网易","163"],"timeout":30000}'
 ```
 
+If `list_pages` returns `The selected page has been closed`, just run it again. The bundled script will open `about:blank` and retry automatically.
+
 ## Extraction guidance
 
-- Use `take_snapshot` for readable page summaries, navigation labels, and visible content.
+- Use `take_snapshot` for readable page content and page structure.
 - Use `evaluate_script` for precise fields, arrays, links, prices, tables, or JSON-shaped output.
-- Use `wait_for` before reading if the site is client-rendered or slow.
+- Use `wait_for` only if the page is still loading and you know a reliable text or selector to wait on.
 - Use `list_network_requests` and `get_network_request` only when DOM extraction is insufficient.
+- For list pages, preserve order and return the item text or link target for each visible entry.
+- For article pages, return the article text and visible metadata, not a recap unless asked.
 
 ## Example patterns
 
 For article text:
 
 ```bash
-node /Volumes/MacMiniDisk/project/chromeDev/skills/chromedev/scripts/http_mcp_call.mjs evaluate_script '{"function":"() => ({ title: document.title, text: document.body.innerText.slice(0, 4000) })"}'
+node skills/chromedev/scripts/http_mcp_call.mjs evaluate_script '{"function":"() => ({ title: document.title, text: document.body.innerText.slice(0, 4000) })"}'
 ```
 
 For links on the page:
 
 ```bash
-node /Volumes/MacMiniDisk/project/chromeDev/skills/chromedev/scripts/http_mcp_call.mjs evaluate_script '{"function":"() => Array.from(document.querySelectorAll(\"a\")).slice(0,50).map(a => ({ text: (a.innerText || a.textContent || \"\").trim(), href: a.href })).filter(x => x.href)"}'
+node skills/chromedev/scripts/http_mcp_call.mjs evaluate_script '{"function":"() => Array.from(document.querySelectorAll(\"a\")).slice(0,50).map(a => ({ text: (a.innerText || a.textContent || \"\").trim(), href: a.href })).filter(x => x.href)"}'
 ```
 
 ## Operational notes
@@ -115,3 +155,9 @@ node /Volumes/MacMiniDisk/project/chromeDev/skills/chromedev/scripts/http_mcp_ca
 - If a tool call hangs near connection start, assume Chrome may be waiting for the authorization dialog.
 - Prefer returning concise extracted data over full raw snapshots unless the user asked for raw output.
 - Do not expose the local MCP endpoint outside `127.0.0.1`.
+- Prefer the bundled `skills/chromedev/scripts/http_mcp_call.mjs` over ad hoc absolute paths so the current workspace copy is always used.
+- For URL-reading tasks, return the page content faithfully and concisely. Do not summarize unless explicitly requested.
+- For list pages, return the list items faithfully and in order.
+- Never assume the currently selected tab is the one you just opened. Always re-check `list_pages` and target the matching URL or title before reading.
+- Prefer `take_snapshot` for the first pass and `evaluate_script` only when the user wants exact fields or raw text.
+- Treat `wait_for` as optional. Use it only if a page is visibly still loading and you know a reliable text or selector to wait on.

package/skills/chromedev/scripts/http_mcp_call.mjs

@@ -47,13 +47,32 @@ async function main() {
 
   try {
     await client.connect(transport)
-    const result = await client.callTool({ name: toolName, arguments: args })
+    const result = await callWithRecovery(client, toolName, args)
     console.log(JSON.stringify(result, null, 2))
   } finally {
     await transport.close().catch(() => {})
   }
 }
 
+async function callWithRecovery(client, toolName, args) {
+  const result = await client.callTool({ name: toolName, arguments: args })
+
+  if (toolName === 'list_pages' && isClosedPageError(result)) {
+    await client.callTool({
+      name: 'new_page',
+      arguments: { url: 'about:blank', timeout: 30000 },
+    })
+    return client.callTool({ name: toolName, arguments: args })
+  }
+
+  return result
+}
+
+function isClosedPageError(result) {
+  const text = result?.content?.find?.((item) => item?.type === 'text')?.text || ''
+  return Boolean(result?.isError && text.includes('selected page has been closed'))
+}
+
 function printUsage() {
   console.error('Usage: http_mcp_call.mjs <tool_name> [json_args]')
   console.error("Example: http_mcp_call.mjs new_page '{\"url\":\"https://www.163.com/\",\"timeout\":30000}'")