hardly

hardly

コンテンツに依存しない汎用 CLI および MCP サーバーです。HAR ファイルの読み取りとキャプチャを行い、クライアント SDK に必要なエンドポイント、フォームとラベル、データやメディアの種類、認証情報と認証の仕組みを提供します。

目的

ブラウザーでキャプチャした HAR ファイルは、数十メガバイトになることもよくあります。それを読み取るエージェントはトークンを消費する一方で、構造を見落とすことがあります。hardly は HAR を一度 SQLite にストリーミングし、その後、MCP 経由で小さく、機密情報を除去したページ分割ツール（および同等の CLI）を提供します。本文は切り詰められ、秘密情報は除去され、リストはページ分割されます。ファイル全体が必要になることは、ほとんどありません。

hardly は、特定のサイトではなく、技術（HTML フォーム、ASP.NET WebForms、GraphQL、OAuth/OIDC、Cookie/CSRF、ボット対策など）とリソースの種類（JSON、CSV、HTML テーブル、PDF、画像など）を把握します。後続の SDK は、それぞれ独自の手順や用語を保持します。docs/scope.mdを参照してください。

インストール

pip install hardly                  # or: pipx install hardly / uv tool install hardly
pip install 'hardly[capture]' && python -m playwright install chromium   # optional: record HARs

hardly 自体を開発する場合：pip install -e ".[dev]"（CONTRIBUTING.md）。

Python 3.10 以降が必要です。保存するには出力パスを指定してください。指定しない場合、何も書き込まれません。 output_path を渡さない限り、すべてメモリ内に保持されます（hardly session open HAR -o index.db）。Python の場合：with open_session(har) as s: ...（integrating.md）。

60 秒で始めるクイックスタート

hardly guide mode                             # which of the three modes fits
hardly session overview path/to/capture.har   # counts per server, method and status
hardly session site-brief path/to/capture.har # one-screen digest of a server-rendered site
hardly endpoint list path/to/capture.har --host api.example.com
hardly session report path/to/capture.har     # one-pass findings with severity
hardly write export path/to/capture.har --format openapi -o api.yaml
hardly write export path/to/capture.har --format client_python --host api.example.com -o client.py

エージェントの場合は、hardly_guide_task_plan(goal, har_path, url)から始めてください（CLI：hardly guide task-plan --goal ...）。呼び出し例と現在の環境状態を含む、順序付きのプランが返されます。

名前から動作がわかります

CLI と MCP サーバーで共通の用語を使います。コマンド名は、hardly_ を除いたツール名です（hardly_session_open は hardly session open HAR、hardly_send_entry は hardly send entry HAR 12 --confirm）。

先頭の語	意味
send	実際のサーバーにリクエストを送信します。confirm=true（CLI では --confirm）が必要です。指定しない場合はプランのみを返します
write	ファイルを書き込みます。overwrite=true（--overwrite）を指定しない限り、既存ファイルへの上書きを拒否します
browser	実際のブラウザーを操作するか、ブラウザーから読み取ります
その他すべて	読み込み済みのデータのみを読み取ります

統合ツールは sections リストを受け取ります。例：hardly_auth_report(sections=['credentials', 'cookies'])。リファレンス：docs/tools.md（71 個のツール）、docs/cli.md （コマンド）。安定性の保証についてはdocs/api-stability.mdを参照してください。

3 つのモード

モード	使用する状況	エントリーポイント
archive	HAR ファイルがすでにある場合	hardly_session_open(har_path) の後に hardly_session_site_brief / hardly_endpoint_list
headless	URL だけがあり、エージェントがページを操作できる場合	hardly_browser_capture_discover(url, analyze=true, confirm=true)（CLI hardly browser capture-discover URL --analyze --confirm）
interactive	ボット対策、CAPTCHA、MFA、複雑な UI がある場合	hardly_browser_start(headed=true)を実行し、人に確認してからhardly_browser_stop

キャプチャ後は、返された session_id を使って archive モードで続行してください。hardly は CAPTCHA やボット対策を決して回避しません。これらを検出し、停止する、人に確認する、または別の環境で再実行するよう案内します（docs/gate-policy.md）。詳細：docs/capture.md。

クローンせずにインストールして実行

uvx hardly serve                              # MCP server over stdio (archive mode)
uvx --from 'hardly[capture]' hardly browser --help   # with the Playwright capture extra
pipx install 'hardly[capture]'                # or install the CLI permanently
hardly skill install                          # copy the Agent Skill into ~/.claude/skills/hardly

公開パッケージ用の MCP クライアント設定：

{ "mcpServers": { "hardly": { "command": "uvx", "args": ["hardly", "serve"] } } }

ブラウザーキャプチャにはローカルへのインストールが必要です（[capture] エクストラを指定し、その後 python -m playwright install chromium を実行します。ヘッド付きキャプチャにはディスプレイが必要です）。コンテナーイメージ ghcr.io/b1tninja/hardly（マルチアーキテクチャ対応、各リリースでビルド）は、アーカイブ／ヘッドレス分析専用です。作業ディレクトリを /workspace にマウントしてください。 リリースと検証の詳細：docs/releasing.md。

MCP のセットアップ（Cursor など）

ローカル仮想環境（推奨。ヘッド付きキャプチャにはディスプレイが必要です）：

{
  "mcpServers": {
    "hardly": {
      "command": "/path/to/hardly/.venv/bin/python",
      "args": ["-m", "hardly"]
    }
  }
}

Windows では ...\\.venv\\Scripts\\python.exe を使用してください。hardly serve は同じサーバーを起動します。

Docker（オフライン分析専用。作業ディレクトリをマウントしてください）：

python scripts/build_image.py       # builds hardly-mcp:latest (Windows: scripts\deploy-docker.ps1)

{
  "mcpServers": {
    "hardly": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-v", "/home/me/work:/workspace",
               "-e", "HARDLY_WORKSPACE=/workspace",
               "hardly-mcp:latest"]
    }
  }
}

マウント先のホストパスは /workspace/... に対応します。ローカルでのビルドを省略するには、hardly-mcp:latest の代わりに公開イメージ ghcr.io/b1tninja/hardly:latest を使用してください。

エージェントのオンボーディング

• hardly_guide_task_plan、hardly_guide_mode、hardly_server_status（MCP が古い場合は、サーバーを再起動してください）、hardly_guide_help(topic)。
• MCP プロンプト：analyze_har、discover_apis、capture_portal、document_api、find_auth_flow、reverse_engineer_api、build_client_sdk、diagnose_blocked_capture、verify_client。
• MCP リソース：hardly://cheatsheet と、同梱ドキュメント用の hardly://docs/<name>。
• エージェントスキル：hardly skill install [--dest DIR]（デフォルトは ~/.claude/skills/hardly）、または hardly skill print。ソース：skills/hardly。

ドキュメント

ドキュメント	内容
docs/README.md	すべてのドキュメントのインデックス
docs/scope.md	対象範囲と対象外の範囲、変更チェックリスト
docs/cheatsheet.md	1 ページのクイックリファレンス
docs/concepts.md	セッション、インデックス、秘匿化、モード
docs/sdk-workflow.md	キャプチャからクライアント SDK までの手順
docs/reporting.md	hardly_session_report の検出結果
docs/catalog.md	ターゲットカタログ、TargetAdapter、一括検証
docs/capture.md	ヘッドレス／対話型キャプチャ、レシピ、環境変数
docs/technologies.md	テクノロジーごとの検出内容
docs/architecture.md	データフローと設計ルール
docs/troubleshooting.md	初回使用時によくある問題
docs/tools.md	すべての MCP ツールの生成されたリファレンス
docs/cli.md	CLI の文法とすべてのコマンド（自動生成）
docs/api-stability.md	公開対象と v1 の互換性ポリシー
docs/api-decisions.md	v1 の名称の選定方法、旧名称から新名称への対応

ライブラリとしての使用

from hardly import open_session

with open_session("capture.har") as s:      # in memory; pass output_path= to save the index
    print(s.conn.execute("select count(*) from entries").fetchone()[0])

開発とテスト

pytest -q                 # offline; HARDLY_LIVE_CAPTURE=1 enables live Playwright tests
ruff check .

公開デモサイトに対するライブ負荷テスト（非公開 HAR は不要）：hardly soak live --list を実行してから、hardly soak live（または --ids datatables-ajax,quotes-login,…）を実行します。カタログには、ループバックの WebForms／トークンログイン、HTML／AJAX テーブル、フォームログイン、GraphQL、JSON／OpenAPI が含まれます。hardly.live_targets と docs/test-targets.md を参照してください。 CONTRIBUTING.md、AGENTS.md；リリースノートは CHANGELOG.md にあります。

セキュリティ

HAR ファイルには、有効なパスワードやセッショントークンが含まれていることがよくあります。hardly はデフォルトで秘匿化しますが、キャプチャは機密情報として扱ってください。コミットしたり共有したりせず、漏えいした場合は認証情報をローテーションしてください。アクセス権のあるターゲットに対してのみ hardly を使用してください。SECURITY.md を参照してください。

ライセンス

MPL-2.0。生成された出力（スタブ、OpenAPI、レポート）は対象外です。NOTICE.md を参照してください。