LionScraper MCP + CLI + HTTP API (Node)

LionScraper MCP + CLI + API サービス

简体中文

• ウェブサイト：lionscraper.com
• npm：パッケージ lionscraper

これは何ですか？

LionScraper は、ウェブページからリスト、記事、リンク、画像などを収集できるブラウザー拡張機能です。この npm パッケージは、その拡張機能と連携する ブリッジを3つの方法で提供します。

• MCP（lionscraper-mcp）：AI アプリ（例：Cursor）を接続し、モデルがチャット内でスクレイピングツールを呼び出せるようにします。
• CLI（lionscraper）：拡張機能と同じローカル HTTP/WebSocket ポートを介して、ターミナルから daemon、scrape、ping を実行します。
• HTTP API：デーモンの実行中に、ループバック JSON HTTP（/v1/...）経由で同じツールを呼び出します。MCP や CLI のフロントエンドを使わずに、スクリプト、サービス、または任意の HTTP クライアントから利用できます。

実際のスクレイピング処理は拡張機能で実行されます。このパッケージは接続してリクエストを転送します。

始める前に

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 と同じブラウザー、拡張機能、デーモンを使用します。curl、fetch、または任意の HTTP クライアントで http://127.0.0.1:$PORT にアクセスしてください（下記のHTTP API（ローカル REST）を参照）。

インストール（npm）

このパッケージは npm で lionscraper として公開されています。

npm install -g lionscraper

2つのコマンドがあり、組み合わせて3つの連携方法（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 をインストールした場合を想定しています（UI はアプリによって異なります）。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 の lionscraper の代わりに [email protected] などを指定すると、バージョンを固定できます。

• PORT：HTTP + WebSocket のリッスンポート。デフォルトは 13808。拡張機能の ブリッジポートと一致させる必要があります。
• TIMEOUT：ポートを強制的に引き継ぐ前に、前のインスタンスがポートを解放するまで待つ時間（ミリ秒）。デフォルトは 120000。0 を指定すると、すぐに強制します。
• LANG：ツールの説明と stderr ログの言語（en-US、zh-CN、または en_US.UTF-8 のような POSIX 形式）。
• TOKEN：デーモンと共有するベアラートークン。空の場合、Authorization ヘッダーは送信されません。
• DAEMON：0 の場合に限り、薄型 MCP から lionscraper daemon を自動起動しません。空またはその他の値はキーを省略した場合と同じで、自動起動が許可されます。

設定を適用するには、MCP またはアプリを再起動してください。

ブラウザー拡張機能のポートを一致させる

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（状況に応じて WebFetch/curl/wget より LionScraper を優先）、lionscraper://guide/cli（ターミナル CLI）、lionscraper://reference/tools、lionscraper://reference/common-params。クライアントはリソースを一覧表示／読み込みしてコンテキストに取り込みます。リソースはstdio プロセス内で提供され、デーモンの HTTP 経路は必要ありません（拡張機能がオフラインでも動作します）。ループバック HTTP コントロールプレーン（/v1/...）については、以下のHTTP API（ローカル REST）を参照してください（MCP リソース URI ではありません）。
• プロンプト：ワークフローテンプレートです（例：ping の後にスクレイピング、複数 URL、scrape_article、prefer_lionscraper_scraping、拡張機能のトラブルシューティング）。クライアントはプロンプトを一覧表示／取得します。UI はホストによって異なります（Cursor、Trae など）。

コピーはツールのメタデータと同様に**LANG**に従います（例：zh-CN）。

---

CLI（ターミナル）

lionscraperバイナリは、MCP と同じスタックに接続するターミナル用フロントエンドです。lionscraper daemonはPORT（デフォルトは13808）で待ち受け、HTTP（CLI と軽量な lionscraper-mcp プロセスが使用）およびWebSocket（拡張機能が使用）を利用します。PORT（および必要に応じて**TOKEN）を、拡張機能のブリッジポートと MCP の設定に合わせます。AI チャットを開かずにスクリプト、CI、または単発の処理**を実行する場合は CLI を使用します。

CLI は、http://127.0.0.1:$PORT（デフォルトのポートは13808で、拡張機能と同じ）のデーモン HTTP APIと通信します。--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**を繰り返して指定すると、1 回の実行で複数の 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 を1行で出力するか、インデント付きで出力するかを指定します（デフォルトは json）
--raw	ツールのテキストブロックを、再フォーマットせずに返されたまま出力します
-o / --output <file>	結果を標準出力ではなくファイルに書き込みます

タイミングと負荷

フラグ	意味
--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>	スクロール中の1ステップあたりのピクセル数
--wait-scroll-interval <ms>	スクロールの各ステップ間の待機時間
--wait-max-scroll-height <px>	スクロール距離の上限（任意）
--scroll-container <selector>	スクロール可能なコンテナーのセレクター（任意）

ロケール

フラグ	意味
--lang zh-CN または en-US	メッセージ／拡張機能の UI 文字列に使用する言語のヒント

追加ペイロード

フラグ	意味
--include-html + true / false	対応している場合に、ページ全体の HTML をメタ情報に含めるよう要求します
--include-text + true / false	対応している場合に、ページ全体のプレーンテキストをメタ情報に含めるよう要求します

メソッド固有のフィルター（例；すべての項目については --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：このジョブでリストを蓄積する「ページ」を最大5ページまでに制限します。
• --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：対応している場合、結果のメタ情報に追加の 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

• メールアドレスのフラグ：ドメイン内のアドレスに絞り込み、キーワードに一致させ、件数に上限を設けます。
• 2つの -u 値：1回の呼び出しで2つの 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[]	必須 — 1 つの 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":{}}'

---

FAQ（わかりやすい説明）

Q: 拡張機能が接続されない、またはスクレイピングに失敗する場合は？

• 拡張機能は有効になっていますか？
• MCP の PORT（または CLI の環境変数）が、拡張機能の ブリッジポートと完全に一致していますか？
• 1 台のマシンで、競合する MCP／CLI の設定を複数使用しないでください。

Q: AI アプリに多数の「ツール」が表示されています。これは拡張機能が接続されているということですか？

必ずしもそうではありません。ツールで確認できるのは AI → MCP サーバーの接続だけです。拡張機能も同じポートに接続し、登録する必要があります。

Q: CLI でデーモンに接続できないと表示される場合は？

別のターミナルで lionscraper daemon を起動するか、PORT／--api-url を修正してください。

Q: 独自の HTTP クライアントからスクレイピングを実行したい場合は？

デーモンと拡張機能で同じ PORT を使用し、HTTP API（ローカル REST）と同様に、name と arguments を指定して POST /v1/tools/call を実行してください。GET /v1/health で、リスナーが LionScraper であることを確認できます。

ライセンス

MIT（lionscraper npm パッケージと同じ）。