Guion Web

Guion Web は Node.js の Web リサーチツールキットです。Exa または Brave、Context7 ライブラリのドキュメント検索、Sourcegraph の公開コード検索、そして 2 つのページ取得バックエンドを提供します。これらは CLI、stdio MCP サーバー、Pi 拡張機能、DeepSeek Harness（DSH）統合を通じて利用できます。バックエンドは、静的ページ、SSR、プリレンダリング済みページ向けの直接 HTML→Markdown 抽出と、対応するホスト上でクライアントサイドレンダリングページを対象とした明示的な agent-browser レンダリングです。

インストールと設定

Node.js 20 以降が必要です。@guionai/web は意図的に web 実行ファイルと stdio MCP サーバーだけを公開しており、ルート JavaScript または TypeScript SDK は提供しません。それらのホスト統合には Pi または DSH パッケージを使用してください。

npm install --global @guionai/web
# or run without a global install
npx @guionai/web --help

検索には 1 つのプロバイダ認証情報が必要です。両方存在する場合は、デフォルトで Exa が選択されます。プロバイダは --provider exa または --provider brave で明示的に選択してください。Context7 はキーがない場合、匿名で動作します。

export EXA_API_KEY="..."
# or
export BRAVE_API_KEY="..."
# optional, for authenticated Context7 requests
export CONTEXT7_API_KEY="..."

認証情報をコマンド引数に入れたり、コミットしたりしないでください。CLI はこれらの環境変数を直接読み取ります。dotenv ファイルや古いアプリケーション設定パスは読み込みません。

Related MCP server: FireScrape MCP Server

CLI

web はデフォルトで目視しやすい出力をします。--json を追加すると stdout に JSON ドキュメントが 1 つだけ出力され、自動化に役立ちます。

web search --provider exa -- "Node AbortSignal"
web fetch https://example.com/article --tree
web fetch https://example.com/article --section introduction
web docs resolve react
web docs fetch /facebook/react --topic hooks --tokens 2000
web sgraph --count 10 -- "repo:^github\\.com/nodejs/node$ AbortSignal"

ハイフンで始まる検索クエリや Sourcegraph クエリの前には -- を使用してください。fetch は --full、--tree、--section をサポートします。長い抽出文書はデフォルトで見出しツリーになるため、後続のリクエストで安定したセクション ID を取得できます。

MCP

同じ認証情報環境で stdio サーバーを実行します。

web mcp
# Pin search selection for the lifetime of this MCP process:
web mcp --provider brave

サーバーは search、fetch、docs_resolve、docs_fetch、source_search の 5 つのツールを公開します。stdout は MCP プロトコルメッセージ専用で、診断は stderr へ出力されます。クライアントレンダリングされるページの場合は、render: "agent-browser" と整数の waitMs を指定して明示的に fetch を呼び出します。このオプションの再試行は、ホストにインストールされた実行可能ファイルを必要とし、自動的に行われることはありません。

Pi

単体でバンドルされた Pi 拡張機能をインストールします。

pi install npm:@guionai/pi-web

これは web_search、web_fetch、web_docs、web_source_search を登録し、バンドルされたコアをプロセス内で呼び出します。Pi と TypeBox はホストが提供するピア依存関係です。CLI 実行ファイルや MCP 設定は不要です。web_fetch はデフォルトで直接 fetch を使用し、ホストがオプションの実行可能ファイルを提供する場合は、整数の waitMs を付けて明示的に render: "agent-browser" を使用できます。

DSH

既存の Web プロファイルに DSH バンドルをインストールします。

dsh plugin --profile web add @guionai/dsh-web

同梱のプロファイルパッチは、標準の PTC Web 検索を選択した Exa または Brave プロバイダ経由でルーティングします。設定 UI はプロバイダの選択を保存し、名前空間化された書き込み専用の認証情報を管理します。Fetch、ドキュメント、Sourcegraph ツールもプロセス内で実行されます。ホストに導入されている DSH パッケージと React は、DSH が提供するピア依存関係です。web_fetch はデフォルトで直接 fetch を使用し、オプションの実行可能ファイルを提供するホスト上では整数の waitMs を指定して明示的に render: "agent-browser" を使用できます。

ページ取得バックエンド

web fetch には 2 つのバックエンドがあります。デフォルトの fetch は Node の fetch、linkedom、Defuddle を使用して、静的、SSR、事前レンダリングされたページから直接 HTML を Markdown に変換します。agent-browser は、別途インストールしたホスト実行可能ファイルを介してクライアント側のページをレンダリングします。デフォルトは直接 fetch で、必要な場合のみ agent-browser を明示的に選択します。実装が自動的にフォールバックすることはありません。

web fetch https://example.com/app --render=agent-browser --wait=2000
# If it is still incomplete, retry explicitly with more time, or abandon it:
web fetch https://example.com/app --render=agent-browser --wait=10000

--wait は --render=agent-browser では必須です（--wait=0 を含む）。許可されるのは 0 から 30,000 ミリ秒までの整数のみです。直接 fetch リクエストで --wait を指定してはいけません。同じ render: "agent-browser" と必須の waitMs フィールドは、MCP の fetch、Pi の web_fetch、DSH の web_fetch ツールでも使用できます。直接 fetch の失敗時には、構造化された javascript_rendering_may_be_required ヒントと 2,000 ミリ秒の提案が返されることがあり、エージェントがより長い待機で再試行するか、ページを破棄するかを決定します。

レンダリングはオプションのホスト機能です。これを使用する場合、agent-browser をホストとは別にインストールしてください。

npm install --global agent-browser
agent-browser install

agent-browser install は独自のブラウザランタイムを管理します。Guion パッケージはそれを実行、バンドル、またはブラウザの認証情報を再利用することはありません。互換性のある実行可能ファイルは、シェルを介さずに PATH から直接実行できる必要があります。このレンダラーは macOS と Linux ホストでサポートされています。agent-browser がなくても直接 fetch は利用でき、3 つの npm パッケージもインストール可能です。

レンダリングされたセッションは新しい空の状態で、永続的ではありません。起動前に、対象は HTTP(S) の公開ホスト名またはアドレスである必要があります。ブラウザの許可リストには、要求されたホスト名、*.<requested-hostname>（対象とそのサブドメイン）、および次の固定共通 CDN セットのみが含まれます。

• cdn.jsdelivr.net

• unpkg.com

• cdnjs.cloudflare.com

• ajax.googleapis.com

• fonts.googleapis.com

• fonts.gstatic.com

• esm.sh

呼び出し側がこのリストを拡張することはできません。リダイレクト、API、フレーム、ワーカー、ソケット、その他不明なドメインへの依存は、render_domain_not_allowed としてフェイルクローズします。waitMs を増やしても解決しません。不足しているファーストパーティまたは共通 CDN ドメインは、ページ URL とブロックされたドメインを添えて https://github.com/guionai/web/issues/new で報告してください。認証情報やページのシークレットを issue に含めないでください。

これはブラウザレベルのホスト名境界であり、完全な SSRF 保護やホストの egress ファイアウォールではありません。リテラルおよび DNS 解決後のプライベート/予約済みターゲットは起動前に拒否されますが、許可された悪意のあるホスト名は検証後に DNS 回答をプライベートアドレスへ変更できます（DNS リバインディング）。また、ここには OS レベルのホスト egress 分離はありません。このバックエンドを公開またはマルチテナントサービス内の任意の信頼できない URL に対して使用する場合は、接続ごとの SSRF フィルタリングプロキシまたはコンテナ/microVM の egress 分離を必ず使用してください。

開発

これは pnpm ワークスペースです。依存関係をインストールし、CI で使用される同じローカルゲートを実行します。

pnpm install --frozen-lockfile
pnpm format:check
pnpm typecheck
pnpm build
pnpm test
pnpm test:release
pnpm test:pack

test:release は使い捨て manifest を使用してタグバージョンの同期を実際に検証します。test:pack は、テストが所有する一時ディレクトリ内で、各公開パッケージの packed インストールまたはホスト読み込み契約を実行します。

リリース

v<semver> タグは、3 つの公開パッケージ @guionai/web、@guionai/pi-web、@guionai/dsh-web に対するリリースの唯一の真実です。リリース preflight はそのタグからチェックアウトしたマニフェストを同期し、続けてフォーマット、チェック、ビルド、テスト、リリースバージョン検証、packed smoke test を完了してから、公開を開始します。

次に、保護された npm Environment の独立した非 fail-fast の 3 つのマトリクスセルが、それぞれ 1 つのパッケージを provenance 付きの npm Trusted Publishing で公開します。同期されたバージョンは、安定版 SemVer には npm の latest タグを、プレリリースには beta タグを選択します。すべてのセルが成功した後は、ワークフローが生成したノートとソースアーカイブを含む GitHub Release を作成します。これはバイナリやプラットフォームアーカイブを公開しません。

公開が部分的に失敗した場合は、GitHub Actions の Re-run failed jobs を使用してください。 Re-run all jobs は絶対に使用しないでください。npm のバージョンは不可変であるため、すでに公開に成功したジョブを再実行してはいけません。

初回ベータのブートストラップと Trusted Publishing

これは、リリースコミットがマージされた後、定常の OIDC リリースを有効にする前に一度だけ実行します。

1. 意図したクリーンなリリースコミットをチェックアウトし、0.1.0-beta.1 などの同期するベータバージョンを選択します。

2. @guionai の公開権限と 2FA を持つ maintainer の npm アカウントで、node scripts/sync-version.mjs 0.1.0-beta.1 を実行します。次にビルド、テスト、pack、node scripts/release-dry-run.mjs 0.1.0-beta.1 のゲートを実行します。

3. 各公開パッケージの フォルダ から、同期したベータ版を npm publish --access public --tag beta で公開します。このブートストラップは maintainer による認証です。GitHub OIDC リリースジョブ以外で provenance を入力しないでください。

4. npm のパッケージ設定で、@guionai/web、@guionai/pi-web、@guionai/dsh-web のそれぞれについて、GitHub Trusted Publisher の関係を 1 つ作成します。各関係は、リポジトリ guionai/web、ワークフロー .github/workflows/release.yaml、保護された npm Environment をターゲットにする必要があります。

5. npm で 3 つの関係と npm 公開アクセスポリシーをすべて検証し、それから定常のワークフローを有効化/タグ付けします。このワークフローは npm トークンなしで GitHub OIDC を使用し、通常の公開ごとに provenance を要求します。

バージョンを上書きしたり、非公開に戻したりしないでください。GitHub Release に部分的な失敗がある場合は、失敗した公開セルだけを再実行してください。