Groundhog

Groundhog

実際のステルスパッチ済み Chrome を使って、AI エージェント向けにウェブ検索、ページの読み取り、調査を行います。 Groundhog は、モデルが信頼できるクリーンな Markdown を返す MCP サーバーです。人間には見えないテキストはモデルが読む前に除去され、その内容が報告されます。すべての情報源には来歴レシートが付き、通常のフェッチャーをブロックするページも実際のブラウザーで読み取ります。

agent / crawler  ──MCP──▶  Groundhog (search, read_url, research)  ──CDP──▶  stealth Chrome  ──▶  the web

他のフェッチレイヤーとの比較

28 ページには人間には見えないテキストが含まれ、3 つのコントロールには含まれていません。ペイロードがモデルに届かず、記事のテキストが届いた場合、そのケースは合格です。

	除去できた	記事を保持	報告した	偽陽性
requests + trafilatura	25/28	28/28	0/28	0/3
Scrapling (HTTP)	16/28	28/28	0/28	0/3
Jina Reader	15/28	28/28	0/28	0/3
Firecrawl	7/28	28/28	0/28	0/3
Groundhog	28/28	28/28	25/28	0/3

他の抽出ツールは隠しテキストを誤って削除することがよくありますが、削除されたことを呼び出し元に知らせるものはありません。Groundhog が報告しない 3 つのケース（隠し入力値、メタディスクリプション、iframe srcdoc）は、どの抽出ツールにも届きません。コーパスは dmytrome.github.io/groundhog で公開されています。ハーネスとその制限については benchmark/ をご覧ください。

クイックスタート

Claude Code：

claude mcp add groundhog -- uvx groundhog-mcp

Claude Desktop、Cursor、Windsurf：

{
  "mcpServers": {
    "groundhog": {
      "command": "uvx",
      "args": ["groundhog-mcp"]
    }
  }
}

最初のフェッチ時に、Groundhog はすでにインストールされている Chrome をヘッドレスモードで起動し、独自のプロファイル ~/.groundhog/chrome を使用します。普段のブラウジング、タブ、ログインには一切触れません。Chrome が見つからない場合は、status とエラーメッセージにインストール方法が表示されます。

GROUNDHOG_BROWSER=stealth を設定すると、代わりに強化されたブラウザーコンテナーが実行されます（Docker または Podman を使用します。初回のイメージ取得には数分かかります）。自分で実行するには：

docker run -d --rm --name groundhog-browser --shm-size 512m \
  -p 127.0.0.1:9222:9222 -- ghcr.io/dmytrome/groundhog:latest

CDP_URL を設定すると、指定されたブラウザーに Groundhog が接続します。指定された値がそのまま使われます。http:// の場合は /json/version に接続を試し、ws:// または wss://（ホステッドブラウザーが提供する形式）の場合は直接接続します。自動起動は、応答していないローカルアドレスに対してのみ実行されます。GROUNDHOG_AUTO_START_BROWSER=false を設定すると、自動起動を無効にできます。ソースから実行する場合：cd mcp && uv sync && uv run groundhog-mcp。

4 つのツールすべてに readOnlyHint の注釈が付いており、何も書き込まず、リモートの状態も変更しません。唯一の副作用は自動起動です。これにより Chrome が起動する場合があります。また、stealth の場合は、到達不能な groundhog-browser という名前のコンテナーを削除してからコンテナーを実行することがあります。

特長

• 隠しテキストを除去し、報告します。 レンダリング済み DOM には人間が目にする内容が表示され、それ以外はすべて除去されます。除去した内容はそれぞれ threats に記録されます。これは強力なヒューリスティックですが、証明ではありません。制限事項をご覧ください。
• すべての情報源にレシートが付きます。抽出したコンテンツの SHA-256、正規化 URL、言語、単語数に加え、ページに記載がある場合は著者と日付も含まれます。
• デフォルトで安全です。 SSRF ガードが、ドキュメントのリクエスト、リダイレクト、フレームを含むすべてをチェックし、ドメインごとのレート制限も行います。セキュリティをご覧ください。
• 自動化の痕跡を残しません。 Groundhog は生の CDP 経由で Chrome を操作し、Puppeteer、Playwright、Selenium でボット対策が検出する Runtime ドメインを有効にしません。
• 本物のフィンガープリントを使用します。 実際の Chrome により、本物の TLS、HTTP/2、WebGL、canvas が使われます。ヘッドレスモードでは HeadlessChrome トークンが置き換えられ、クライアントヒントがブラウザーからコピーされます。共有ワーカーとサービスワーカーは対象外です。ステルスイメージは Xvfb 上でヘッドフルモードで実行されます。
• モデルも API キーも不要です。 research は抽出結果を返し、統合はエージェントが行います。

ツール

read_url(url, format="markdown", max_tokens=None, query=None, include_hidden=False)

Key	意味
markdown	抽出されたコンテンツです。まず記事本文を使用し、取得できない場合はレンダリングされたテキストをコードフェンス内に入れて使用するため、どの部分も Markdown として解釈されません。PDF の場合は、各ページにつきテキストをフェンスで囲んだ ## Page N セクションが 1 つ返されます。format は markdown または text です
title	ページタイトル
url	指定した URL
final_url	リダイレクト後の URL。SSRF ガードによって再確認されます。使用できない場合は、要求された URL が報告され、脅威として final_url_suppressed が付与されます
fetched_at	UTC の ISO-8601 タイムスタンプ
status	ok、または返された内容が要求したページではない場合は challenge / blocked / rate_limited / not_found / server_error / unsupported_content です。blocked は 401、403、およびその他の 4xx エラーページを含みます。too_large は、HTML が 5 MiB、テキストが 2 MiB、PDF が 10 MiB、100 ページ、または解析に 20 秒を超え、内容が一切返されないことを意味します。暗号化された PDF または形式が不正な PDF は unsupported_content です。empty は、レンダリングされたページに読者が目にするテキストがなかったことを意味します（閉じたシャドウルート、iframe、alt 属性内のテキストは含まれません）。markdown の内容にかかわらず適用されます。include_hidden を指定すると、スタイルで隠されたテキストも表示されたものとして扱われます。不可視文字は常に対象外です。unknown は、使用可能なステータスが確認されなかったことを意味します。クライアント側のリダイレクト後、テキストの取得元となったドキュメントに基づいて判定されます
http_status	トップレベルの HTTP ステータス、または null
truncated	トークン上限によってコンテンツが途中で切られたかどうか
threats	除去された内容。何も見つからなかった場合は空です
matches	query を指定した場合：id、heading、offset、end、score、および clamped（max_tokens に収まるよう短縮されたもの）を含む、スコア順の文章です。offset と end はページ全体の Markdown における位置を示し、その範囲のテキストが返されます。長いコードブロックの一部が返される場合は、その前後にフェンス行が追加されます。コードが途中で分割されることはありません。一致したコードブロックまたはその一部が max_tokens を超える場合は除外され、収まるものがない場合は markdown が空になり、truncated が設定されるため、max_tokens を増やしてください
set_aside	query を指定した場合：関連性の下限によって除外されたスコア付きの文章
provenance	コンテンツハッシュ、正規 URL、言語、単語数、著者、日付

デフォルトでは、次の内容が除去されます：display:none、visibility:hidden、content-visibility:hidden、 opacity ≤ 0.05、font-size < 4px、ゼロサイズのボックス、および何もレンダリングしない display:contents ボックス、.sr-only スタイルのサブピクセルボックス、clip: rect(...)、何も残さない clip-path（circle(0)、inset(100%)、1 行上のポリゴン）、どちらかの軸で transform: scale(0) を指定したもの、透明度が 0.05 以下の filter、オーバーフローをクリップする高さまたは幅がゼロのボックス、透明または背景色と同じ色のテキスト、ページ外への配置、折りたたまれた <details>、<template> の内容、ゼロ幅文字、双方向制御文字、および Unicode Tag 文字です。開いたポップオーバーまたはモーダルダイアログだけをテキストとして含むボックスは、ダイアログが画面に表示されるため保持されます。そのボックス内のその他のテキストは通常どおり除去されます。HTML コメントも報告されます。 PDF では、描画を行わないレンダーモード 3 または 7 で描画されたテキストが除去され、hidden_pdf として報告されます。これにはスキャンページの OCR レイヤーも含まれるため、そのレイヤーだけをテキストとして持つスキャンは、include_hidden を渡さない限り empty になります。 include_hidden=True を指定するとテキストは保持されますが、引き続き報告されます。alt、aria-label、 aria-description、および title のテキストは、markdown やレンダリングされたテキストには表示されません。125 文字以上の値は、長いテキストが既知の情報埋め込み手段であるため、上限付きの抜粋とともに hidden_attribute として報告されます。

threats は信頼できないものとして扱ってください。そこに含まれる抜粋はページ作成者が記述したテキストであり、サニタイズされ、長さが制限されています。

type	含まれる情報
hidden_css	非表示にしたreason、80文字のexcerpt、DOM のlocation
hidden_attribute	alt、aria-label、aria-description、title属性内のテキストについて、同じ情報
hidden_template	<template>内のテキストについて、同じ情報
hidden_pdf	PDF が不可視で描画したテキストについて、ページをlocationとして同じ情報
zero_width / bidi / tag	配信されたテキストで検出されたコードポイントと件数をreasonに記録
report_truncated	上限により除外されたエントリ数
final_url_suppressed	ページの最終 URL が使用できず、返されなかった
detection_degraded	ページが改変可能な、ページ自身の JavaScript ワールド内で検出が実行された
strip_incomplete	通常はオープンシャドウルートが原因で、レイアウトではなくマークアップからテキストが再構築された

ページごとに返される検出結果は最大50件（researchではソースごとに10件）です。偽の囮が実際のペイロードを埋もれさせないよう、2つのクラスは別々に上限が設定されています。通知は上限適用後に追加されます。

queryでは先頭からの切り詰めに代わり、サニタイズ済みのコンテンツに対するBM25パッセージランキングを使用し、最良スコアの半分以内のパッセージを予算の上限まで保持します。

search(query, limit=10)

ヒット（title、url、snippet、engine、score、published）と、応答したbackendを返します。コンテンツの取得は行いません。SEARXNG_URLが設定されている場合は、formats: [html, json]が必要なSearXNGインスタンスを使用します。設定されていない場合は、ブラウザー経由で検索ページをレンダリングします。ヒットのテキストはクリーニングされ、長さが制限されます。クリーニングによって URL が変わるもの、http(s)ではないもの、認証情報を含むもの、2048文字を超えるものは除外されます。バックエンドが応答できない場合、空のウェブを返すのではなくエラーが発生します。

research(query, max_sources=5, max_tokens=None, include_domains=None, exclude_domains=None, published_after=None, aim=None, follow=None)

検索し、上位ソースを読み取り、すべてのソースからパッセージを一度にランク付けします。

• passages：id、text、source_url、heading、score、start、end、clamped、 fenceが含まれます。textはmarkdown[start:end]と完全に一致します。clampedは、予算に収めるために短く切り詰められたことを示します。コードブロックが途中で切り詰められることはなく、除外されるだけです。長いコードブロックから切り出されたパッセージでは、そのブロックの開始行がfenceに含まれます。textがその行で始まらない場合はその行を使ってブロックを開き、textが閉じフェンスで終わらない場合はブロックを閉じてください。ページが変わらない限り、idは安定しています。
• sources：url、title、status（ok / blocked / timeout / error）、page_status （read_urlと同様）、threats、threat_total、threat_counts（hidden_unclassifiedとして検出器が除外したページ内の範囲を含む、タイプごとのすべての検出結果）、provenance、filtered、 depth、discovered_via（そのソースをたどる元となった候補と、指定したwhy）が含まれます。ソースの取得に失敗しても、呼び出し全体は失敗しません。チャレンジ、エラーページ、emptyページ、およびmarkdownが空白のページはすべてnot_contentとみなされ、パッセージを提供しません。
• include_domainsが設定されていない場合、登録可能ドメインごとに1ページだけを対象とします。設定されている場合は、サイトごとのページ数をGROUNDHOG_MAX_CONCURRENT_PAGES以下に制限します。max_sourcesは最大10です。

include_domainsでは指定されたドメインとそのサブドメインのみを読み取り、exclude_domainsでは指定されたドメインを読み取りません。また、published_after（YYYY-MM-DD）では、指定日より前の日付のページを除外します。含めるドメインは最大8件、除外するドメインは最大50件まで指定できます。除外対象のドメインにリダイレクトするページ、指定したドメインの範囲外にリダイレクトするページ、日付が早すぎるページ、または使用済みのページと URL かテキストが重複するページは、filteredに記載され、パッセージを提供しません。検索エンジンに送信されるクエリで指定されるドメインは最大8件です。除外ドメインがそれより多い場合、残りは検索後に除外されます。aim（最大200文字）では証拠が示すべき内容を指定でき、その内容は検索やランキングを変えずにそのまま返されます。 receiptには、executed_query、重複を除いたヒット数とhits_by_domain、取得されなかったヒット（hits_excluded、hits_outside_domains、hits_before_date、hits_same_domain、ソース上限を超えてhits_unreadとなったヒット）、各ソースをfailed、not_content、filtered、usableのいずれかとして一度だけ数えた件数、outside_domains、unknown_dates、およびomitted、set_aside、clampedとなったパッセージが記録されます。ウェブ上に答えがないと結論づける前に確認してください。

candidatesは、返されたパッセージ内のリンクです。最大12件で、1ページあたり4件まで、1ドメインあたり3件までです。それぞれに、token、url、domain、label（ページに記載されたリンクテキスト）、parent_source_url、parent_passage_id、depth、flags（parent_strip_incomplete、parent_detection_degraded、parent_threats=N、likely_unsupported_format、same_domain_pages=N）があります。ページ自身に戻るリンク、この呼び出しですでに読み込んだページへのリンク、ドメインフィルターの対象外へのリンク、または3リンク先のページからのリンクは提示されません。リンクの一部を読むには、同じqueryとフィルターを指定して、再度follow=[{"token": ..., "why": ...}]（最大8件、各whyは最大160文字）を指定して呼び出します。呼び出しの間で情報は保持されません。followでは検索は行われません。followedには各エントリーの状態として、read、not_content、failed、filtered、duplicate、same_domain_limit（期限までに読み込みを開始できるサイトごとのページ数の上限）、invalid_token、expiredのいずれかが示されます。トークンはサーバーによって署名され、30分後または再起動時に期限切れになります。

応答のJSONテキストブロックは40,000文字を超えません。MCPの結果には、同じオブジェクトがstructuredContentとして再度含まれます。上限を超える場合は、カード、脅威の抜粋、パッセージ、メタデータの順に省略され、それぞれの件数はreceiptに記録されます（candidates_omitted、threat_excerpts_omitted、passages_omitted、sources_omitted、metadata_compacted）。省略されたソースの安全性に関する件数はomitted_safetyに保持され、その旨がnotesに示されます。ソースのページを返すread_urlを使うか、クエリを絞り込むか、ソース数を減らすと、より多くの情報を含められます。

status()

browser_reachable、cdp_url（スキーム、ホスト、ポートのみ）、およびブラウザーに接続できない場合のhintを返します。

設定

MCP サーバー：

環境変数	デフォルト	用途
CDP_URL	http://127.0.0.1:9222	ローカルまたはリモートの CDP エンドポイント。認証されていないため、非公開にしてください
GROUNDHOG_BROWSER	chrome	自動起動で起動するブラウザー：chrome または stealth。GROUNDHOG_COMPOSE_FILE または GROUNDHOG_BROWSER_IMAGE が設定されている場合、デフォルトは stealth です
GROUNDHOG_CHROME_PATH	(found)	Chrome 実行ファイル
GROUNDHOG_CHROME_PROFILE	~/.groundhog/chrome	プロファイルディレクトリ。ここでログインすると、そのログイン情報が再利用されます
GROUNDHOG_BLOCK_PRIVATE_IPS	true	SSRF 対策
GROUNDHOG_MIN_DELAY_MS	5000	同一ドメインへのリクエスト間の遅延
GROUNDHOG_MAX_TOKENS	20000	トークンの上限
GROUNDHOG_MAX_CONCURRENT_PAGES	4	同時に開くタブの数
SEARXNG_URL	(unset)	search 用の SearXNG インスタンス
GROUNDHOG_SEARCH_BACKEND	auto	auto、searxng、または serp
GROUNDHOG_AUTO_START_BROWSER	true	ローカルの CDP_URL から応答がない場合にブラウザーを起動します
GROUNDHOG_BROWSER_IMAGE	ghcr.io/dmytrome/groundhog:latest	stealth 用のイメージ
GROUNDHOG_COMPOSE_FILE	(none)	代わりに docker compose -f <file> up -d で起動します

ブラウザーコンテナ：

環境変数	デフォルト	用途
USER_AGENT	インストール済みの Chrome から取得	起動時に設定する UA。スコープごとにクリーンです
PROXY	(none)	上流プロキシ http://user:pass@host:port。タイムゾーンとロケールは出口 IP に合わせられます
TZ	UTC	フォールバックのタイムゾーン
WINDOW_SIZE	1920,1080	Chrome のウィンドウサイズ
XVFB_WHD	1920x1080x24	仮想ディスプレイ

ステルス Chrome コンテナ

Xvfb 上で動作するヘッドフル Chrome と CDP エンドポイントを提供し、あらゆる CDP クライアントから使用できます。HeadlessChrome ではなく Chrome と報告し、navigator.webdriver を false に設定して、起動時に UA を設定します。 PROXY を使用すると、タイムゾーンとロケールが出口 IP に一致し、認証情報はローカルの tinyproxy を経由し、WebRTC はプロキシに固定されます。WebGL は検出された GPU を使用し、検出できない場合は Mesa llvmpipe を使用します。

新規コンテナ（Chrome 151、プロキシなし）を対象に、生の CDP で確認した結果：

検出器	結果
deviceandbrowserinfo	ボットではない（isBot: false、フラグなし）
browserscan	正常
bot.sannysoft.com	31 項目中 31 項目のチェックに合格

iphey はデータセンターの IP をすべて検出するため、追跡対象ですが採点対象外です。最新の表は RESULTS.md にあります。Puppeteer、Playwright、Selenium は Runtime を有効にするため、依然として検出されます。各ツール用のクライアントは examples/ にあり、詳細については OTHER_TOOLS.md を参照してください。

セキュリティ

CDP エンドポイントには認証がありません。ポートに接続できる人は誰でもブラウザーを操作できます。localhost またはプライベートネットワーク上に配置してください。ステルスイメージは --no-sandbox で実行されるため、コンテナーを隔離してください。脆弱性は SECURITY.md から報告してください。

SSRF ガードは各ホストを解決し、ループバック、プライベート、リンクローカル（169.254.169.254 を含む）、予約済み、マルチキャスト、未指定、CGNAT、IPv4 マップ IPv6 アドレス、http(s) 以外のスキーム、認証情報を含む URL を拒否します。Chrome が送信しようとしているすべてのドキュメントリクエスト（リダイレクトやクロスサイトフレームを含む）を確認し、final_url も再確認します。サブリソースは Chrome の Local Network Access ルールに委ねられ、Groundhog が起動する Chrome ではプリロードが無効になっています。

ガードの制限：

• ドキュメントのみが確認対象です。古い Chrome や、プロファイルでローカルネットワークへのアクセスを許可されたサイトについては、サブリソースが保護されません。
• ステルスコンテナーと、ユーザーが用意したブラウザーでは、プリロードが有効のままです。
• Groundhog と Chrome は別々に DNS を解決するため、短い TTL の DNS リバインディングが成立する時間帯が残ります。
• フェッチでは単一のプロファイルを共有するため、あるページで設定された Cookie は後続のフェッチでも保持され、ページの JavaScript はそのプロファイルから独自のリクエストを送信できます。

GROUNDHOG_BLOCK_PRIVATE_IPS=false を設定するとガードが無効になります。内部アドレスへの接続が意図されている場合に限り使用してください。

隠しテキスト検出の制限

threats リストが空でも、安全性が確認されたことにはなりません。検出はページから改変できない隔離された環境で実行され、実行中のページが変更されることはありません。ただし、次の制限があります。

• 閾値のぎりぎり内側に設定できます（opacity: 0.06、transform: scale(0.01)）。また、スタイルは何も描画しないことが確実な場合にのみ非表示として扱われるため、次の方法では検出されません：text-indent、inset(50%)（Chrome が報告する値は丸められます）、ピクセル指定または url()／path() による clip-path、3D 回転、mask-image、別の要素で覆われたテキスト、要素の背後に重ねられたテキスト、オーバーフローをクリップするボックスの外側に配置された子要素。
• PDF ではレンダーモード 3 と 7 のみが検出されます。白色または小さなテキスト、ページ外のテキスト、非表示レイヤー、画像の下にあるテキストは検出されません。すべての PDF の結果には、その旨を示す detection_degraded 通知が含まれます。不可視テキストがグリフ幅を測定できないフォント（縦書き、Identity-H 以外の CMap）に含まれる PDF は、include_hidden を渡さない限り、そのテキストを含めて返されるのではなく、unsupported_content になります。解析は子プロセスで実行され、20 秒で終了させられます。Linux ではメモリも 1 GiB に制限されます。それ以外の環境では、時間制限とデコード済みストリームの 256 MiB 上限のみが適用されます。
• 不可視文字のセットは拒否リストです。
• クローズドシャドウルートは読み取れないため、その内容はすべて除外されます。
• ページ側のカスケードが非表示スタイルに優先する場合や、ページが自身の <body> を非表示にする場合、テキストはマークアップから再構築され、改行は推定されます。その旨は strip_incomplete で示されます。

ブロック検出の制限

• ベンダーのヘッダー（cf-mitigated、x-vercel-mitigated、x-amzn-waf-action、x-dd-b、x-datadome-cid）またはチャレンジ用アセット（Cloudflare、DataDome、PerimeterX、Imperva）から、チャレンジであると確実に判定できます。それ以外のベンダーでは、ほぼ空のページにある英語の文言を手がかりに判定します。
• ソフトブロック（データがひそかに保留された状態での 200）は、コンテンツとして扱われます。
• unknown は ok ではありませんが、ブロックとしても扱われません。
• ベンダーの存在を示す情報（server: cloudflare、cf-ray）は意図的に無視されます。

「ステルス」について

ベストエフォートです。一般的なオープンソースの検出器には有効ですが、IP レピュテーションや振る舞いを基準にアクセスを制限する商用のアンチボットシステムには対抗できません。正当な、認可された自動化に使用してください。

プライバシーポリシー

Groundhog はセルフホスト可能なソフトウェアであり、プロジェクトが運用するサーバーとは通信しません。データは一切収集しません。テレメトリー、アナリティクス、クラッシュレポート、アカウントもありません。

ページはお使いのマシン上のブラウザーで取得され、MCP クライアントに返されます。サーバーはデータベースを保持せず、ログも書き込みません。ブラウザープロファイルには Cookie とストレージが保存されます。ローカルの Chrome の場合は ~/.groundhog/chrome（フォルダーを削除すると破棄されます）、stealth の場合はコンテナー（docker rm -f groundhog-browser）に保存されます。

通信先は、取得するサイト、検索バックエンド（お使いの SearXNG、またはそれがない場合は公開検索エンジン）、PROXY が設定されている場合に限りプロキシの出口 IP を調べる IP ジオロケーションサービス、そしてインストール時の PyPI と GHCR です。

ご質問は SECURITY.md または https://github.com/dmytrome/groundhog/issues までお寄せください。

ライセンス

MIT