LionScraper MCP + CLI + HTTP API (Python)

LionScraper MCP + CLI + API 服务（Python）

简体中文

• 网站：lionscraper.com
• PyPI：项目 lionscraper

这是什么？

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

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

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

开始之前

1. 浏览器：Chrome 或 Edge（请以扩展实际支持的浏览器为准）。
2. LionScraper 扩展：从浏览器应用商店安装并启用（不同商店中的扩展名称可能有所不同）。
   • Chrome：Chrome 网上应用店 — LionScraper
   • Microsoft Edge：Edge 附加组件 — LionScraper
3. Python：机器上需要安装 3.10 或更高版本。如果尚未安装，请从 Python 网站下载安装程序并按提示操作（如果安装程序提供此选项，请勾选在 Windows 上将 Python 添加到 PATH）。
4. 使用 MCP：支持 MCP 的 AI 应用（例如 Cursor、Trae）。
5. 使用 HTTP API：需要与 CLI 相同的浏览器、扩展和守护进程；使用 curl、fetch 或任何 HTTP 客户端访问 http://127.0.0.1:$PORT（参见下文的 HTTP API（本地 REST））。

此包使用 aiohttp 向守护进程发送出站 HTTP 和 WebSocket 探测请求。未检测到 Chrome/Edge 且扩展未连接时，ping / scrape* 可以使用服务端 HTTP 回退（不执行页面内 JS）。

安装（pip）

此包以 lionscraper 的名称发布在 PyPI 上。

pip install -U lionscraper

你可以使用虚拟环境（推荐），也可以运行 pip install -U --user lionscraper，以免安装到系统解释器中。

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

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

如果安装后 lionscraper-mcp 不在你的 PATH 中，请使用脚本的完整路径（例如虚拟环境中的 Scripts/ 或 bin/），或者在 MCP 中使用下文的 python -m lionscraper 形式（仍需正常运行 pip install -U lionscraper）。

---

MCP（AI 应用）

在 AI 应用中添加 MCP

示例假设 lionscraper-mcp 位于 PATH 中（不同界面有所差异）。在 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": ""
      }
    }
  }
}

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

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

如果 lionscraper-mcp 不在 PATH 中

运行 pip install -U lionscraper 后，可以使用 python -m lionscraper 执行相同的路由：模块名称后不带参数时，会通过 stdio 选择精简 MCP；带有任何额外参数（包括 --debug）时，则使用 CLI。例如：

{
  "mcpServers": {
    "lionscraper": {
      "command": "python",
      "args": ["-m", "lionscraper"]
    }
  }
}

请使用安装此软件包时所用的同一个 python 可执行文件（某些系统上使用 python3）。

与浏览器扩展中的端口保持一致

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

日常使用（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）除 工具 外，还会公开 资源 和 提示词：

• 资源：位于稳定 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）。
• 提示词：工作流模板（例如 ping-then-scrape、多 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 配置一致。使用 CLI 运行脚本、CI 或快速的单次任务，无需打开 AI 聊天。

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 查看该二进制文件支持的所有标志。

抓取：参数与更丰富的示例

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

输出与连接

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

计时与负载

标志	含义
--delay <ms>	页面加载后等待一段时间再抓取（适用于动态内容）
--timeout-ms <ms>	扩展端针对每个 URL 的超时时间
--bridge-timeout-ms <ms>	此次 CLI → daemon 调用的最长等待时间
--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	在支持时请求在 meta 中包含完整页面 HTML
--include-text + true / false	在支持时请求在 meta 中包含完整页面纯文本

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

• 电子邮件（--method emails）：--email-domain、--email-keyword、--email-limit
• 电话（--method phones）：--phone-type、--phone-area-code、--phone-keyword、--phone-limit
• URL（--method urls）：--url-domain、--url-keyword、--url-pattern、--url-limit
• 图片（--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（与 PyPI 上的 lionscraper 包相同）。