LionScraper MCP + CLI + HTTP API (Node)

LionScraper MCP + CLI + API 服务

简体中文

• 网站：lionscraper.com
• npm：软件包 lionscraper

这是什么？

LionScraper 是一款浏览器扩展，可从网页中收集列表、文章、链接、图片等内容。此 npm 软件包通过三种方式为该扩展提供配套的桥接：

• MCP（lionscraper-mcp）：连接你的 AI 应用（例如 Cursor），让模型可以在聊天中调用抓取工具。
• CLI（lionscraper）：通过与扩展相同的本地 HTTP/WebSocket 端口，在终端中运行 daemon、scrape 和 ping。
• HTTP API：在 daemon 运行时，通过本地回环 JSON HTTP（/v1/...）调用相同的工具——适用于脚本、服务或任何 HTTP 客户端，无需 MCP 或 CLI 前端。

实际的抓取逻辑在扩展中运行；此软件包负责连接并转发请求。

开始之前

1. 浏览器：Chrome 或 Edge（请以扩展实际支持的浏览器为准）。
2. LionScraper 扩展：从浏览器商店安装并启用该扩展（商店页面上的名称可能有所不同）。
   • Chrome：Chrome 网上应用店 — LionScraper
   • Microsoft Edge：Edge 加载项 — LionScraper
3. Node.js：你的设备上需要安装版本 18 或更高版本。如果尚未安装，请从 Node.js 网站下载安装程序并按提示操作。
4. 使用 MCP：需要支持 MCP 的 AI 应用（例如 Cursor、Trae）。
5. 使用 HTTP API：需要与 CLI 相同的浏览器、扩展和 daemon；使用 curl、fetch 或任何 HTTP 客户端访问 http://127.0.0.1:$PORT（请参阅下文的 HTTP API（本地 REST））。

安装（npm）

此软件包以 lionscraper 的名称发布在 npm 上。

npm install -g lionscraper

你会获得两个命令；它们共同支持三种集成方式（MCP、CLI、HTTP API）：

命令	作用
lionscraper-mcp	面向 AI 应用的轻量 MCP 服务（stdio）
lionscraper	CLI：daemon、stop、scrape、ping 等（也会运行提供 HTTP API 的进程）

不进行全局安装时，MCP 可以使用 npx；请参阅在 AI 应用中添加 MCP下的 JSON 示例。

---

MCP（AI 应用）

在 AI 应用中添加 MCP

示例假设已进行全局 lionscraper 安装（不同界面可能有所差异）。在 MCP JSON 中，所有 env 值都必须是字符串。

最简配置（省略 env 即使用内置默认值；PORT 默认为 13808，且必须与扩展桥接端口一致）：

{
  "mcpServers": {
    "lionscraper": {
      "command": "lionscraper-mcp"
    }
  }
}

完整 env 示例（删除不需要的键；对于其中大多数键，空字符串的效果等同于“未设置”）：

{
  "mcpServers": {
    "lionscraper": {
      "command": "lionscraper-mcp",
      "env": {
        "PORT": "13808",
        "TIMEOUT": "120000",
        "LANG": "en-US",
        "TOKEN": "",
        "DAEMON": ""
      }
    }
  }
}

npx（不进行全局安装）——首次运行时可能会下载软件包。command 为 npx；args 为 ["-y", "lionscraper", "lionscraper-mcp"]（npm 软件包名称 lionscraper，后接二进制文件 lionscraper-mcp）。

最简配置（npx）：

{
  "mcpServers": {
    "lionscraper": {
      "command": "npx",
      "args": ["-y", "lionscraper", "lionscraper-mcp"]
    }
  }
}

完整 env 示例（npx）：

{
  "mcpServers": {
    "lionscraper": {
      "command": "npx",
      "args": ["-y", "lionscraper", "lionscraper-mcp"],
      "env": {
        "PORT": "13808",
        "TIMEOUT": "120000",
        "LANG": "en-US",
        "TOKEN": "",
        "DAEMON": ""
      }
    }
  }
}

例如，在 args 中使用 [email protected] 替代 lionscraper，即可锁定版本。

• PORT：HTTP + WebSocket 监听端口；默认值为 13808；必须与扩展的桥接端口一致。
• TIMEOUT：在强制接管端口前，等待上一个实例释放端口的毫秒数；默认值为 120000；0 表示快速强制接管。
• LANG：工具说明和 stderr 日志的语言（en-US、zh-CN 或 en_US.UTF-8 等 POSIX 格式）。
• TOKEN：与 daemon 共享的 Bearer 令牌；为空时不发送 Authorization 标头。
• DAEMON：只有设置为 0 时，才会禁止轻量 MCP 服务自动启动 lionscraper daemon；为空或其他值时，效果与省略此键相同（允许自动启动）。

重启 MCP 或应用，使配置生效。

在浏览器扩展中匹配端口

1. 打开 LionScraper 设置 / 选项。
2. 将 bridge port 设置为与 PORT 相同的值（例如 13808）。
3. 如有需要，在扩展中使用 Reconnect，或重新加载扩展 / 重启浏览器。

日常使用（MCP）

1. 根据需要保持扩展已启用，并打开目标页面。
2. 使用自然语言提问，例如“检查 LionScraper 是否已连接”或“从此页面抓取列表 / 文章 / 电子邮件 / 电话号码 / 链接 / 图片。”
3. 如果看到未连接或超时，请重试连接检查，并确认 PORT 匹配。

MCP 工具（摘要）

服务注册的工具与扩展功能相对应。MCP 客户端向模型显示的名称和结构如下。

工具	用途（简述）
ping	检查扩展是否已连接并注册
scrape	自动检测结构（列表、表格等）；支持分页
scrape_article	文章正文（例如 Markdown）和元数据
scrape_emails	页面上的电子邮件地址
scrape_phones	电话号码（结构化）
scrape_urls	超链接 URL
scrape_images	图片 URL 和基本元数据

参数： 每个字段的完整 JSON 架构位于客户端显示的工具定义和与发布版本相符的文档中；在此重复很快就会过时。调用 MCP 时，请使用 AI 应用中的工具列表 / 描述。

MCP 资源 / 提示词

精简的 MCP 进程（lionscraper-mcp）除 Tools 外，还会公开 Resources 和 Prompts：

• Resources：稳定 URI 上的静态 Markdown，例如 lionscraper://guide/connection（PORT 对齐、ping 故障排除）、lionscraper://guide/when-to-use-tools（根据场景，优先选择 LionScraper，而不是 WebFetch/curl/wget）、lionscraper://guide/cli（终端 CLI）、lionscraper://reference/tools、lionscraper://reference/common-params。客户端会将它们列出 / 读取并载入上下文；它们由 stdio 进程内部提供服务，不需要守护进程 HTTP 路径（即使扩展离线也能使用）。有关环回 HTTP 控制平面（/v1/...），请参阅下文的 HTTP API（本地 REST）（它不是 MCP 资源 URI）。
• Prompts：工作流模板（例如 ping 后抓取、多 URL、scrape_article、prefer_lionscraper_scraping、扩展故障排除）。客户端会列出 / 获取提示词；界面因宿主而异（Cursor、Trae 等）。

复制内容遵循 LANG（例如 zh-CN），与工具元数据相同。

---

CLI（终端）

lionscraper 二进制文件是与 MCP 使用同一技术栈的终端前端：lionscraper daemon 通过 PORT（默认 13808）监听 HTTP（供 CLI 和精简的 lionscraper-mcp 进程使用）以及 WebSocket（供扩展使用）。设置 PORT（以及可选的 TOKEN），使其与扩展桥接端口和任何 MCP 配置相匹配。无需打开 AI 聊天，即可使用 CLI 运行脚本、CI 或快速的一次性任务。

CLI 会与 http://127.0.0.1:$PORT 上的守护进程 HTTP API通信（默认端口为 13808，与扩展相同）。如果未传入 --api-url，运行 scrape 或 ping 时会在可能的情况下自动启动本地守护进程。

常用命令：

lionscraper --help
lionscraper daemon              # keep running; HTTP + WebSocket on PORT
lionscraper stop                # stop daemon on configured PORT
lionscraper ping
lionscraper scrape -u https://www.example.com
lionscraper scrape --method article -u https://www.example.com
# Shorthand: lionscraper -u https://www.example.com   → same as scrape

--method 选择守护进程运行的工具（默认 scrape）：scrape、article、emails、phones、urls、images。重复使用 -u / --url，即可在一次运行中传入多个 URL。

在环境中设置 PORT（以及可选的 TOKEN），使 CLI 与扩展和 MCP 相匹配。如果守护进程不在默认基础 URL 上，请使用 --api-url http://127.0.0.1:PORT。运行 lionscraper --help 查看该二进制文件接受的所有标志。

Scrape：参数与更丰富的示例

以下标志会转发给扩展（--bridge-timeout-ms 除外，它只限制 CLI 在桥接上的等待时长）。实际行为仍取决于扩展版本。

输出与连接

标志	含义
--format json 或 pretty	JSON 单行格式或缩进格式（默认 json）
--raw	按原样打印工具返回的文本块，不重新格式化
-o / --output <file>	将结果写入文件，而不是写入 stdout

计时与负载

标志	含义
--delay <ms>	页面加载后、开始抓取前等待的时间（用于动态内容）
--timeout-ms <ms>	扩展端每个 URL 的超时时间
--bridge-timeout-ms <ms>	此次 CLI → 守护进程 调用的最长等待时间
--scrape-interval <ms>	启动多个 URL 任务时的间隔
--concurrency <n>	多 URL 运行时的并发提示
--scroll-speed <px>	全局滚动速度（遵循扩展语义）
--max-pages <n>	列表类 scrape 的分页上限

延迟加载 / 无限滚动（映射到工具负载中的 waitForScroll）

标志	含义
--wait-scroll-speed <px>	每步滚动的像素数
--wait-scroll-interval <ms>	滚动步骤之间的延迟
--wait-max-scroll-height <px>	可选的最大滚动距离
--scroll-container <selector>	可选的可滚动容器选择器

区域设置

标志	含义
--lang zh-CN 或 en-US	消息 / 扩展界面文本的语言提示

额外负载

标志	含义
--include-html + true / false	在支持时请求将整页 HTML 纳入 meta
--include-text + true / false	在支持时请求将整页纯文本纳入 meta

特定方法的筛选条件（示例；完整列表请参阅 --help）

• Emails（--method emails）：--email-domain、--email-keyword、--email-limit
• Phones（--method phones）：--phone-type、--phone-area-code、--phone-keyword、--phone-limit
• URLs（--method urls）：--url-domain、--url-keyword、--url-pattern、--url-limit
• Images（--method images）：--img-min-width、--img-min-height、--img-format、--img-keyword、--img-limit

可选的浏览器自动化提示（扩展支持时可用）：--auto-launch-browser、--no-auto-launch-browser、--post-launch-wait-ms。

---

示例 A — 使用分页、延迟和滚动辅助抓取列表 / 表格

lionscraper scrape \
  -u https://www.example.com/items \
  --max-pages 5 \
  --delay 800 \
  --timeout-ms 90000 \
  --bridge-timeout-ms 180000 \
  --wait-scroll-speed 400 \
  --wait-scroll-interval 350 \
  --lang zh-CN \
  --format pretty \
  -o items.json

• --max-pages：此任务最多累积五个“页面”后停止。
• --delay：页面加载后多等待一段时间，再进行提取。
• --timeout-ms / --bridge-timeout-ms：分别控制扩展端与 CLI 端的等待时间；对于速度较慢的网站或内容较多的页面，请调高两者。
• --wait-scroll-*：缓慢滚动，让延迟加载的行在抓取前显示出来。
• -o / --format pretty：将易读的 JSON 文件保存下来以便检查。

---

示例 B — 抓取文章正文，并可选生成 HTML 快照

lionscraper scrape --method article \
  -u https://www.example.com/blog/post-1 \
  --include-html true \
  --timeout-ms 120000 \
  --format json

• --method article：映射到 scrape_article 工具（扩展提供时，返回 Markdown 格式的正文和元数据）。
• --include-html true：在支持时请求在结果的 meta 中附加 HTML（负载更大）。

---

示例 C — 使用筛选条件抓取邮箱和 URL，并处理多个页面

lionscraper scrape --method emails \
  -u https://www.example.com/contact \
  --email-domain example.com \
  --email-keyword support \
  --email-limit 30 \
  --format pretty

lionscraper scrape --method urls \
  -u https://www.example.com \
  -u https://www.example.com/docs \
  --url-domain example.com \
  --url-limit 200 \
  --scrape-interval 500

• 邮箱标志：将范围缩小到特定域名中的地址、匹配关键词的地址，并限制数量。
• 两个 -u 值：在一次调用中处理两个 URL；--scrape-interval 会错开任务的启动时间。

---

示例 D — 按尺寸 / 格式筛选图片

lionscraper scrape --method images \
  -u https://www.example.com/gallery \
  --img-min-width 240 \
  --img-min-height 240 \
  --img-format webp \
  --img-limit 40 \
  -o gallery-images.json

• 在扩展支持这些字段时，过滤掉小尺寸缩略图和非 WebP 资源；--img-limit 会限制返回条目数。

---

HTTP API（本地 REST）

基础 URL：http://127.0.0.1:$PORT（默认值为 13808）。仅绑定 127.0.0.1。扩展必须连接到该端口，并且必须有一个 守护进程正在监听（进程模型与此软件包的其余部分相同）。

方法	路径	响应（成功）
GET	/v1/health	{ "ok", "identity", "bridgePort", "sessionCount" }
POST	/v1/daemon/shutdown	{ "ok": true }，然后守护进程退出
POST	/v1/tools/call	工具结果 JSON（见下文）

其他任何请求 → 404 { "ok": false, "error": { "code": "NOT_FOUND", "message": "Not found" } }。

**身份验证：**如果守护进程设置了环境变量 TOKEN，每个请求都需要 Authorization: Bearer <TOKEN>；否则省略此标头。

POST /v1/tools/call

• 标头：Content-Type: application/json。若要流式传输，还需设置 Accept: application/x-ndjson。
• 请求体：

{ "name": "<tool>", "arguments": { }, "progressToken": "<optional>" }

字段	含义
name	以下选项之一：ping、scrape、scrape_article、scrape_emails、scrape_phones、scrape_urls、scrape_images
arguments	工具负载；为空时省略或使用 {}
progressToken	任意字符串或数字；使用 Accept: application/x-ndjson 时，请求体为 NDJSON（先发送 type: "progress" 行，最后发送 type: "result" 或 type: "error" 行）

arguments（JSON 键）

**仅适用于 ping：**可选的 lang（"en-US" | "zh-CN"）、autoLaunchBrowser（布尔值）、postLaunchWaitMs（数字，3000–60000）。

所有 scrape 系列工具（scrape、scrape_article、scrape_emails、scrape_phones、scrape_urls、scrape_images）共用：

键	类型	限制 / 说明
url	string | string[]	必填——一个 URL 或 URL 数组
lang	"en-US" | "zh-CN"	可选
delay	number	可选，≥ 0
timeoutMs	number	可选，≥ 1000
bridgeTimeoutMs	number	可选，≥ 1000
includeHtml	boolean	可选
includeText	boolean	可选
scrapeInterval	number	可选
concurrency	number	可选
scrollSpeed	number	可选
autoLaunchBrowser	boolean	可选
postLaunchWaitMs	number	可选，3000–60000
waitForScroll	object	可选；若设置，必须包含 scrollSpeed 和 scrollInterval；可包含 maxScrollHeight、scrollContainerSelector

**仅适用于 scrape：**可选的 maxPages（数字，≥ 1）。

可选的 filter 对象（仅适用于对应的工具）：

name	filter 属性
scrape_emails	domain、keyword、limit（≥ 1）
scrape_phones	type、areaCode、keyword、limit（≥ 1）
scrape_urls	domain、keyword、pattern、limit（≥ 1）
scrape_images	minWidth、minHeight（≥ 0）、format、keyword、limit（≥ 1）

未知的 name、无效的 JSON 或不符合架构 → 400 { "code": "BAD_REQUEST", ... }。Bearer 凭据无效 → 401 UNAUTHORIZED。工具崩溃 → 500 INTERNAL。

200 响应体：{ "content": [ { "type": "text", "text": "..." } ], "isError"?: boolean }。

示例（PORT=13808）

curl -sS "http://127.0.0.1:13808/v1/health"
curl -sS -X POST "http://127.0.0.1:13808/v1/tools/call" \
  -H "Content-Type: application/json" \
  -d '{"name":"ping","arguments":{}}'
curl -sS -X POST "http://127.0.0.1:13808/v1/tools/call" \
  -H "Content-Type: application/json" \
  -d '{"name":"scrape_article","arguments":{"url":"https://www.example.com","timeoutMs":120000}}'
# With TOKEN on the daemon:
curl -sS -X POST "http://127.0.0.1:13808/v1/tools/call" \
  -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name":"ping","arguments":{}}'

---

常见问题（通俗说明）

问：扩展未连接或抓取失败？

• 扩展已启用？
• MCP 中的 PORT（或 CLI 环境变量）是否与扩展的 bridge port 完全一致？
• 避免在同一台机器上使用多个互相冲突的 MCP/CLI 配置。

问：AI 应用中显示了很多“工具”，这是否意味着扩展已连接？

不一定。工具只能确认 AI → MCP 服务；扩展仍须在同一端口连接并注册。

问：CLI 提示无法访问守护进程？

在另一个终端中启动 lionscraper daemon，或修正 PORT / --api-url。

问：我想通过自己的 HTTP 客户端驱动抓取？

让守护进程和扩展使用相同的 PORT，然后按 HTTP API（本地 REST） 中的说明，使用 name 和 arguments 调用 POST /v1/tools/call。GET /v1/health 可检查监听器是否为 LionScraper。

许可证

MIT（与 lionscraper npm 包相同）。