Agent Audit

Agent Audit

Lighthouse を活用した MCP サーバーです。AI コーディングエージェント向けに、Core Web Vitals、テクニカル SEO、アクセシビリティ、GEO／LLM の可視性を監査します。

🔗 NPM パッケージ

Agent Audit は、Google Lighthouse の結果と範囲を限定したページ検査結果を、コーディングエージェントが実際に実行できる構造化された修正パックに変換します。生のパフォーマンスレポートの代わりに、優先順位が付けられ、根拠に裏付けられたバックログを Claude Code、Codex、Cursor、GitHub Copilot、その他の MCP クライアントに提供します。

Lighthouse の監査結果を、コーディングエージェント向けの修正パックに変換します。

npx -y @fullstackdegen/agent-audit

Agent Audit が必要な理由

Lighthouse は診断に優れていますが、生のレポートだけでは自律型のコーディングワークフローには不十分です。コーディングエージェントは、どの問題が最も重要か、モバイル、デスクトップ、または両方に影響するか、どのセレクターやリソースが根拠となるか、検索すべきファイルはどれか、修正をどう検証するか、そして完了を安全に宣言できるタイミングを把握する必要があります。

Agent Audit は Lighthouse の出力を実装契約に変換します。

1. モバイルとデスクトップの Lighthouse 監査を実行します。
2. 繰り返し実行した結果を集約し、ばらつきを明らかにします。
3. テクニカル SEO、リンク、メタデータ、構造化データ、画像、アセット、インデックス登録可能性、AI による発見シグナルについて、同一ページを対象とした範囲限定のインテリジェンスを追加します。
4. ノイズの多い監査結果を、優先順位を付けた少数の問題リストに統合します。
5. リポジトリ内の検索ヒント、実装手順、測定可能な受け入れ基準を含む fixPacks を生成します。
6. 厳密な MCP structuredContent と、それと同等の Markdown を返します。

目標はシンプルです。コーディングエージェントが読み取り、推論し、修正し、テストし、検証できるレポートを提供します。

監査対象

Agent Audit は、次のような情報を探している人に役立ちます。

• Lighthouse を活用した MCP サーバー
• AI ウェブサイト監査ツール
• コーディングエージェント向け Lighthouse レポート
• Core Web Vitals の自動化
• Claude Code、Codex、Cursor、Copilot 向けのパフォーマンス監査
• AI エージェント向けのテクニカル SEO 監査
• アクセシビリティ修正パック
• LLM の可視性監査
• GEO 監査、生成エンジン最適化、AI 検索への対応状況
• llms.txt の対応状況と AI クローラーからの可視性

現在のチェック項目は次のとおりです。

• パフォーマンス、アクセシビリティ、ベストプラクティス、SEO のモバイルおよびデスクトップ向け Lighthouse スコア。
• FCP、Speed Index、LCP、TBT、CLS の指標分布。
• 高速で信頼性の高い監査モード。
• 取得回数を制限した、同一オリジンのページ検査。
• リンク切れ、リンク名の欠落、メタデータ、canonical タグ、robots シグナル、JSON-LD、Open Graph、インデックス登録可能性、画像、アセット、LLM の可視性チェック。
• ページコンテンツが十分な場合の、慎重な llms.txt 草案の生成。
• 根拠、推奨アクション、受け入れ基準を含む、優先順位付きの問題。
• リポジトリ内の検索ヒント、実装手順、検証ガイダンスを含むエージェント向け修正パック。
• structuredContent に対する厳密な MCP outputSchema 検証。
• 同じ正規レポートから生成される Markdown。

実際のCommaLabs JSON レポートと Markdown レポートをご覧ください。

インストール

要件：

• Node.js 20 以降。
• Google Chrome または Chromium。

MCP サーバーを実行します。

npx -y @fullstackdegen/agent-audit

便利なリンク：

• NPM パッケージ
• GitHub リポジトリ
• リリース
• イシュー
• セキュリティアドバイザリ

MCP クライアントのセットアップ

Claude Desktop

ローカル MCP サーバーを追加します：

{
  "mcpServers": {
    "agent-audit": {
      "command": "npx",
      "args": ["-y", "@fullstackdegen/agent-audit"]
    }
  }
}

設定を保存した後、Claude Desktop を再起動します。

Claude Code

claude mcp add agent-audit -- npx -y @fullstackdegen/agent-audit

ローカル開発の監査を行う場合：

claude mcp add agent-audit-local -- npx -y @fullstackdegen/agent-audit --local

Codex

codex mcp add agent-audit -- npx -y @fullstackdegen/agent-audit

または、~/.codex/config.toml に追加します：

[mcp_servers.agent-audit]
command = "npx"
args = ["-y", "@fullstackdegen/agent-audit"]

VS Code と GitHub Copilot

ワークスペースまたはユーザーレベルの .mcp.json ファイルを作成します：

{
  "servers": {
    "agent-audit": {
      "command": "npx",
      "args": ["-y", "@fullstackdegen/agent-audit"]
    }
  }
}

または、ターミナルから登録します：

code --add-mcp '{"name":"agent-audit","command":"npx","args":["-y","@fullstackdegen/agent-audit"]}'

Cursor

ローカルの stdio MCP サーバーを設定します：

• 名前：agent-audit
• コマンド：npx
• 引数：-y、@fullstackdegen/agent-audit

localhost の監査が必要な場合は、引数に --local を追加します。

ツール

analyze_website_performance

指定した URL に対して Lighthouse とサイトインテリジェンスを実行します：

{
  "url": "https://example.com",
  "mode": "reliable"
}

mode は任意です：

• fast：モバイルで 1 回、デスクトップで 1 回実行します。
• reliable：プロファイルごとに 3 回実行し、中央値と変動範囲を算出します。これが デフォルトです。

修正パックの例

{
  "id": "fix-link-name",
  "priority": 2,
  "sourceIssueIds": ["link-name"],
  "goal": "Fix Links do not have a discernible name.",
  "category": "accessibility",
  "severity": "critical",
  "affectedProfiles": ["mobile", "desktop"],
  "repoSearchHints": [
    "div.border-t-2 > div.flex > div.flex > a.text-gray-600",
    "https://www.linkedin.com/company/commalabs"
  ],
  "implementationSteps": [
    "Inspect the repository for the evidence listed in repoSearchHints before editing.",
    "Give every link a discernible accessible name.",
    "Keep changes focused on source issue IDs: link-name."
  ],
  "acceptanceCriteria": [
    "All link elements pass the Lighthouse link-name audit.",
    "Raise the median accessibility score to at least 90/100."
  ],
  "verification": {
    "rerunMode": "reliable",
    "expectedAuditIds": ["link-name"]
  }
}

repoSearchHints は検索の手がかりであり、実際のファイルパスが保証されるわけではありません。コーディングエージェントは 編集前にリポジトリを調査する必要があります。

コーディングエージェントのワークフロー

structuredContent を信頼できる情報源として使用し、Markdown レポートを 実行の要約として使用します。

1. 優先順位に従って fixPacks を確認します。
2. repoSearchHints を使ってリポジトリを検索します。
3. 根拠を実際のファイル、コンポーネント、ルート、アセット、または設定に対応付けます。
4. 一度に 1 つの、対象を絞った修正を適用します。
5. 論理的な変更を行うたびに、リポジトリのテストを実行します。
6. Agent Audit を reliable モードで再実行します。
7. 新しいレポートを各修正パックの acceptanceCriteria と比較します。

不完全なレポートや、ベースラインより変動が大幅に大きい状態で再実行した結果をもとに、完了したと主張しないでください。

エージェント向けドキュメント：

• AGENTS.md：Codex、Cursor、Copilot、その他のコーディングエージェント向けの一般的な手順。
• CLAUDE.md：Claude Code のセットアップと実行に関するガイダンス。
• エージェントのワークフローガイド：レポートの構成と修正パックの実行サイクル。
• コピーして使えるコーディングエージェント向けプロンプト

localhost の監査

デフォルトでは、Agent Audit は一般にルーティング可能な HTTP および HTTPS URL のみを受け付けます。これは、ホスト型エージェントや共有環境に適したデフォルト設定です。

開発者のマシンでは、ループバックターゲットを明示的に有効にします：

npx -y @fullstackdegen/agent-audit --local

次に、MCP クライアントからローカルアプリを監査します：

{
  "url": "http://localhost:3000",
  "mode": "fast"
}

このオプトインにより、localhost、*.localhost、127.0.0.0/8、および ::1 が許可されます。 プライベート LAN の範囲、リンクローカルアドレス、予約済み範囲、マルチキャストアドレス、 およびクラウドメタデータアドレスは引き続きブロックされます。

環境変数を使った形式もサポートされています：

LIGHTHOUSE_MCP_ALLOW_LOCALHOST=true npx -y @fullstackdegen/agent-audit

セキュリティモデル

Agent Audit はユーザー指定の URL に対して Chrome を起動するため、URL ポリシーが重要です。 サーバーは次のものを拒否します：

• HTTP および HTTPS 以外のプロトコル；
• 埋め込み認証情報；
• 明示的に有効にされていない localhost およびループバックターゲット；
• プライベート、リンクローカル、マルチキャスト、予約済み、およびメタデータネットワークの IP；
• パブリックではないアドレスに解決される、localhost 以外のホスト名。

ページ検査用のフェッチャーは同じ URL ポリシーを使用し、タイムアウト、 バイトサイズ、およびリソース数の上限を適用します。

ページによって制御されるタイトル、説明、URL、セレクター、スニペット、および監査テキストは サニタイズされ、長さが制限されます。利用者は、これらをエージェントへの指示ではなく、 信頼できない根拠として引き続き扱う必要があります。

Chrome のサンドボックスはデフォルトで有効です。これをサポートできない 分離環境のみ、次の設定を行ってください：

LIGHTHOUSE_CHROME_NO_SANDBOX=true

脆弱性の報告とデプロイに関するガイダンスについては、SECURITY.md を参照してください。

制限事項

Agent Audit には意図的に制限が設けられています：

• 一度に監査する URL は、指定された 1 つのみです。
• サイト全体を巡回するクローラーではありません。
• 外部の SEO データベースではありません。
• Shopify、CMS、CDN、DNS、ホスティング、リダイレクト、または分析設定は変更しません。
• 画像の圧縮、アセットの縮小、IndexNow リクエストの送信、サードパーティの SEO API の呼び出しは行いません。
• Lighthouse の結果は、ブラウザーのバージョン、ハードウェア、ネットワーク状況、 およびページの変更によって変わります。

ロードマップ

• フレームワークを考慮したリポジトリ検索のヒント。
• プルリクエストのパフォーマンスゲートに使用できるオプションの GitHub Action。
• 複数 URL のレポート。
• HTML レポートのエクスポート。
• マーケティングと発見に関するシグナルの拡充：分析タグ、同意シグナル、 Open Graph、スキーマの網羅状況、AI による発見への対応状況。
• SEO、GEO、可視性データセット用のオプションのサードパーティ連携。

開発

npm install
npm test
npm run check
npm run build
npm run validate:release

実際の Chrome でスモーク監査を実行します：

npm run --silent smoke -- https://example.com fast
npm run --silent smoke -- https://example.com reliable

スモークコマンドは、標準出力に正規の JSON を、標準エラー出力に同等の Markdown を書き込みます。

リリース

公開前に：

npm test
npm run check
npm run build
npm run validate:release
npm pack --dry-run --cache /private/tmp/agent-audit-npm-cache

公開：

npm publish --access public --cache /private/tmp/agent-audit-npm-cache

公開済みパッケージ：

npx -y @fullstackdegen/agent-audit --help

貢献

対象を絞ったイシューやプルリクエストを歓迎します。レポートの仕様、セキュリティポリシー、MCP のトランスポート動作を変更する前に、CONTRIBUTING.md をお読みください。

ライセンス

MIT