SnoopScan

SnoopScan

公開ページならどれでも、きれいな Markdown、構造化された JSON、または独自に定義したスキーマに変換できます。ほかのすべてをブロックするページにも対応しています。AI エージェント向けの MCP サーバー、REST API、SDK を提供します。

このリポジトリは SnoopScan のオープンコアです。単独で動作し、ホスト型 API の snoopscan.com では、ここに含まれていない機能を追加で提供します。オープンソース版とホスト型 APIをご覧ください。

AI チャットでセットアップする

Claude Code、Codex、Cursor、VS Code、または任意の AI エージェントに、次の内容を貼り付けます。

Read and follow https://snoopscan.com/agent-onboarding/SKILL.md

エージェントがガイドを読み、すべての手順を実行します。ブラウザーが開いたら、サインインするか無料アカウントを作成し（月間 1,500 クレジット、カード不要）、Approve を押します。これで完了です。ページを読み取るように指示してください。

Claude Code では、SnoopScan のスキルと MCP サーバーが含まれる SnoopScan プラグインをインストールすることもできます。Claude Code のチャットで次の内容を入力します。

/plugin marketplace add SnoopScan/snoopscan-core
/plugin install snoopscan@snoopscan

Claude アプリと ChatGPT は、コピーするキーなしでサインインして接続できます。カスタムコネクター（Claude）または開発者モードのアプリ（ChatGPT）を、アドレス https://api.snoopscan.com/mcp-oauth で追加してください。各クライアントの手順は snoopscan.com/integrations にあります。

コードから使う

以下の例ではホスト型 API を呼び出し、SNOOPSCAN_API_KEY からキーを読み込みます。snoopscan.com/app/keys でキーを作成するか、上記のセットアップを使ってエージェントに取得させてください。

まだキーがありませんか？/v1/scrape、/v1/search、/v1/parse は Authorization ヘッダーなしでも使えます。ブラウザーなしで読み込めるページであれば、IP アドレスごとに 1 日 20 回まで無料で呼び出せます。各レスポンスには、残りの無料呼び出し回数が記載されています。

curl

curl -X POST https://api.snoopscan.com/v1/scrape \
  -H "Authorization: Bearer $SNOOPSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/", "formats": ["markdown", "links"]}'

Python

pip install snoopscan

import os
from snoopscan import SnoopScan

snoop = SnoopScan(api_key=os.environ["SNOOPSCAN_API_KEY"])
print(snoop.scrape("https://example.com/").markdown)

JavaScript / TypeScript

npm install snoopscan

import { SnoopScan } from 'snoopscan';

const snoop = new SnoopScan({ apiKey: process.env.SNOOPSCAN_API_KEY! });
console.log((await snoop.scrape('https://example.com/')).markdown);

その他の言語

すべての SDK で、同じメソッド、同じエラーコード、同じ再試行ルールを利用できます。また、キーが渡されない場合は、環境変数 SNOOPSCAN_API_KEY から読み込みます。各ディレクトリの README では、すべてのメソッドについて説明しています。

言語	インストール	ソース
PHP 8.1+	composer require snoopscan/snoopscan	sdk/php
Go 1.22+	go get github.com/SnoopScan/snoopscan-core/sdk/go	sdk/go
Ruby 3.0+	gem install snoopscan	sdk/ruby
Java 11+	com.snoopscan:snoopscan（Maven、Gradle）	sdk/java
.NET 8+	dotnet add package SnoopScan	sdk/dotnet
Rust	cargo add snoopscan	sdk/rust
Elixir	{:snoopscan, "~> 0.1"}	sdk/elixir

機能

• 整った出力：Markdown、HTML、リンク、スクリーンショット、または独自のスキーマに基づく JSON を取得できます。
• 難しいページにも対応：JavaScript のレンダリング、ブロックされたページ、プロキシに、セットアップ不要で対応します（ホスト型 API）。
• サイト全体に対応：サイトをクロールしたり、URL をマッピングしたり、数千件の URL を 1 つのジョブとして一括処理したりできます。
• 構造化データ：JSON スキーマまたは名前付きテンプレートにデータを入力し、ページごとの信頼度スコアを取得できます。
• ストアやブログを 1 回の呼び出しで処理：クロールなしで、ストアの商品カタログ全体やブログの投稿を取得できます。
• 結果に対して課金：失敗したリクエストは無料で、すべてのレスポンスに cost オブジェクトが含まれます。
• エージェント対応：すべてのエンドポイントは MCP ツールとしても利用できます。

オープンソース版とホスト型 API

このリポジトリには、次のものが含まれます。

• REST API
• 抽出
• ブロック検出
• クロール
• MCP サーバー
• HTTP 取得
• ストレージ
• クライアント SDK：Python、JS/TS、PHP、Go、Ruby、Java、.NET、Rust、Elixir

snoopscan.com のホスト型 API では、次の機能が追加されます。

• ブラウザーのレンダリング
• プロキシとボット対策への対応
• リード獲得

セルフホスト版は、HTTP 経由でページを読み込みます。ブラウザーが必要なページは、空の成功レスポンスではなく BLOCKED として返されます。ホスト型 API の無料プランには、月間 1,500 クレジットが含まれます。

MCP サーバー

すべてのエンドポイントは MCP ツールでもあるため、エージェントは接着コードなしで直接呼び出せます。ホスト型サーバーは https://api.snoopscan.com/mcp（ストリーミング可能な HTTP、Authorization: Bearer <key>）です。また、https://api.snoopscan.com/mcp-oauth ではキーを使わずにサインインできます。キーなしで /mcp に接続したエージェントは、REST と同じ無料の1日あたりのトライアルで scrape、search、parse を試せます。それ以外のツールには無料キーが必要です。最も簡単なセットアップは上記の1行です。エージェントがエージェントのオンボーディングガイドに従います。このガイドでは、Claude Code、Codex、Cursor、VS Code、Windsurf、Claude アプリ、ChatGPT、その他ストリーミング可能な HTTP に対応するあらゆるクライアントを扱っています。

ツール

• ページ：scrape、fetchMore、search、parse、extract、checkChanges
• サイト：map、crawl、crawlStatus、crawlPages、listProducts、listPosts
• ドメイン：domain、domainReport、domainSnapshots、domainScreen
• 企業とリード：company、findContacts、people、hiring、findLeads、leadsStatus

製品と投稿の一覧、ドメインレポート、そのスナップショット、ドメインスクリーニング、および企業、連絡先、人材、採用、リードの各ツールにはホスト型 API が必要です。このリポジトリでは、これらに対して「このデプロイでは利用できません」とだけ応答します。

すべてのツールにはタイトルと、読み取り専用または破壊的操作を示すラベルが付いています。送信、投稿、購入を行うツールはありません。

制限

エージェントのコンテキストを小さく保つようにツールを設計しています。

• すべてのコンテンツツールは maxChars の上限を受け取ります。
• 切り詰めが発生した場合は必ず明示され、続きのトークンが返されます。
• クロールツールはページ本文をインラインで返しません。
• ガードレールにより、セッションあたりのページ数、同時クロール数、クロールサイズ、帯域幅に上限が設けられています。
• 拒否する場合は必ず制限の理由を説明するため、エージェントはむやみに再試行せず対応できます。
• executeJavascript は、どのレベルでも MCP 経由では公開されません。

API エンドポイント

POST /v1/scrape      one URL -> markdown, html, links, screenshot, json
                     (+ `actions`: click, type, scroll, then read the result)
POST /v1/crawl       a whole site, page by page
POST /v1/map         every URL on a site, ordered by relevance
POST /v1/search      the web, with the results scraped
POST /v1/extract     your JSON schema — or a named template — filled from the page
GET  /v1/templates   the named templates (product, article, jobPosting, …) and their fields
POST /v1/batch/scrape  many URLs, one job
POST /v1/parse       a PDF, DOCX or XLSX as markdown
POST /v1/monitor     watch URLs on a schedule, webhook on change
POST /v1/products    a store's whole product catalog
POST /v1/posts       every post from a blog or forum
POST /v1/company     enrich one company from its own site
POST /v1/domain      a domain's registration, DNS and backlinks
POST /v1/domain/report  a buyer's report on a domain (hosted API)
POST /v1/domain/screen  which of up to 500 names can be registered (hosted API)
POST /v1/places/search  local business listings, with contacts
POST /v1/leads       businesses by trade and town, with their contacts (hosted API)

すべてのページには、ページを構築したプラットフォームを示す metadata.platform が含まれ、すべてのレスポンスには cost オブジェクトが含まれます。

スキーマを使ったデータの抽出

curl -X POST https://api.snoopscan.com/v1/extract \
  -H "Authorization: Bearer $SNOOPSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "urls": ["https://example.com/product/1"],
        "schema": {"type": "object",
                   "properties": {"name":  {"type": "string"},
                                  "price": {"type": "string"}}}
      }'

ページの変更を監視

ページを60分ごとに確認し、変更があった場合は Webhook を送信します。

curl -X POST https://api.snoopscan.com/v1/monitor \
  -H "Authorization: Bearer $SNOOPSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/pricing"],
       "intervalMinutes": 60,
       "webhook": "https://your.app/hook"}'

開発

エンジンをローカルにセットアップして実行します。

uv venv --python 3.12 && uv pip install -e ".[dev]"
uv pip install -e sdk/python --python .venv/bin/python
cp .env.example .env && createdb scraping_engine && .venv/bin/alembic upgrade head
.venv/bin/python tools/create_key.py "local-dev" --rpm 600
.venv/bin/uvicorn engine.api.app:app --reload --port 8099

JS/TS SDK は sdk/js にあり、単独でビルドできます。

cd sdk/js && npm install && npm run build && npm test

その他の SDK もそれぞれ独自のディレクトリとツールチェーンで同じようにビルドでき、各 README の Development セクションにコマンドが記載されています。それらの依存関係のライセンスは sdk/check_licences.py で確認します。

python3 sdk/check_licences.py rust     # after the SDK's own tests have run

テスト、リンター、型チェックを実行します。

.venv/bin/pytest engine/tests -q
.venv/bin/ruff check engine tools && .venv/bin/mypy --strict engine/core

依存関係のライセンス

すべての依存関係は MIT、Apache-2.0、BSD、ISC、または MPL-2.0 でなければなりません。このチェックは必須です。ほかのライセンスを含むビルドは失敗します。また、推移的依存関係のライセンスが変更される可能性があるため、週次でも実行されます。

.venv/bin/pip-licenses --format=json > licences.json \
  && .venv/bin/python tools/check_licences.py licences.json

このルールの適用例は、すでにコードに2つあります。LGPL の psycopg2 は使用せず、Alembic は asyncpg 経由でマイグレーションを実行します。推移的依存関係として取り込まれる tld には、三重ライセンスのどの分岐を使用するかを明記した許可リスト項目が記録されています。

コントリビューション

コントリビューションでは、次の3つのルールに従う必要があります。

1. クリーンルーム実装。AGPL、GPL、または SSPL のプロジェクトのコードを使用しないでください。このカテゴリで一般的なオプション名に API を合わせることは、インターフェースの互換性として正当ですが、実装は独立しています。
2. ライセンスチェックは必須であり、助言にとどまりません。
3. リポジトリに個人情報や個人を特定できる情報を含めないでください。設定には環境変数のみを使用します。すべてのフィクスチャでは example.com または .invalid を使用します。

ライセンス

エンジンはAGPL-3.0でライセンスされています。改変したバージョンをネットワークサービスとして実行する場合、第13条により、そのソースをユーザーに提供する必要があります。実行中のインスタンスはGET /v1/sourceでソースを自ら提供するため、フォークで更新を忘れる可能性のあるドキュメントには依存しません。

sdk/内の各SDKはMITライセンスです。AGPLのクライアントライブラリを使うと、それをインポートするすべてのアプリケーションにコピーレフトが及びますが、これはクライアントライブラリの目的ではありません。

一部のモジュールはプロプライエタリであり、AGPLの対象外です。対象はブラウザーのレンダリング、プロキシとボット対策の処理、リード獲得です。これらはengine/licensing.pyから生成されるLICENSE-PROPRIETARYに記載されています。CIはこの分離を強制します。tools/check_split.pyは、公開モジュールがこれらのいずれかに依存している場合、ビルドを失敗させます。