Hawkeye AI Bridge

Hawkeye AI Bridge MCP サーバー

月間 1,000 万トークンの場合の検索可能期間 — 1 日あたり 50 回の検索ステップがすべてこの例と同じだと仮定した場合、月間 1,000 万トークンのコンテキスト予算を使い切るまでの日数です。バーが長いほど、より長く利用できます。

• 広範な grep — 1.6 日
• コンパクトな grep — 7.0 日
• Hawkeye のインデックス検索 — 29.0 日

Claude Code、VS Code、Cursor、AI エージェント向けのローカルコードベース検索です。

Hawkeye AI Bridge を使うと、AI コーディングアシスタントは MCP 経由で Hawkeye のローカルプロジェクトインデックスを検索できます。リポジトリ全体をアップロードすることなく、大規模なコードベース、アセット、スクリプト、ローカライズ、設定ファイル、プロジェクトのコンテンツから正確な参照箇所を見つけられます。

AI エージェントに大量の未加工の grep 出力を渡す代わりに、Hawkeye は簡潔なファイル名と行番号の検索結果を返します。これにより、エージェントは次に実際に読むべきファイルを判断できます。

1. 大規模なプロジェクトをローカルで検索
2. ノイズの多い未加工の検索出力によるトークン使用量を削減
3. コードとコード以外のプロジェクトファイルから正確な参照箇所を検索
4. C++、C#、Unreal Engine、Unity、レガシープロジェクト、独自コードベースに最適
5. Hawkeye はローカル／オンプレミスで動作し、インデックス作成や検索に AI を使用しません

---

目次

• これは何ですか？
• Hawkeye AI Bridge を使う理由
• 前提条件
• クライアントのセットアップ
  • Claude Desktop
  • Claude Code（CLI）
  • VS Code / GitHub Copilot
  • Cursor
  • OpenCode
• Claude 用スキルのインストール
• 利用可能なツール
• トークンの節約
• プロンプトの例
• プライバシーとセキュリティ
• 更新
• 削除
• トラブルシューティング
• ライセンス
• サポート

---

これは何ですか？

このリポジトリは、Hawkeye AI Bridge を MCP サーバーとして使用するための、公式の公開セットアップおよび案内用リポジトリです。

独自ソフトウェアである Hawkeye AI Bridge のソースコードは含まれていません。Hawkeye と Hawkeye AI Bridge は Zaragsoft が所有する独自ソフトウェアです。

---

Hawkeye AI Bridge を使う理由

Hawkeye は、開発者が大規模なプロジェクトをすばやく検索し、理解するのに役立ちます。MCP に対応しているため、AI コーディングアシスタントは Hawkeye にローカル検索を依頼でき、呼び出しごとのトークンを節約できます。

一般的な使用例：

• クラス、関数、シンボル、アセット、ローカライズキー、ファイルへのすべての参照箇所を検索します。
• エディターの検索だけに頼らず、大規模なコードベースを検索します。
• 変更を加える前に、AI コーディングアシスタントがプロジェクトをより深く理解できるようにします。
• 暗黙知への依存を減らしながら、大規模なゲーム／ソフトウェアプロジェクトを把握します。
• 検索をローカル／オンプレミスに保ちます。
• ファイルを無差別に読み込む場合と比べて、トークンを約 80％削減します。
• グループを指定しない場合、すべてのグループが使用されます。

---

前提条件

• Hawkeye をインストール済みであること — https://www.zaragsoft.se/downloads から入手してください
• Hawkeye AI Bridge をインストール済みであること — https://www.zaragsoft.se/aibridge から入手してください
• Hawkeye でインデックス化されたローカルプロジェクト
• セットアップ動画：https://www.youtube.com/watch?v=l1J-G36QSwI

推奨インストール先： AIBridge フォルダーを C:\Program Files\Hawkeye\AIBridge\ に配置してください。以下のすべての例では、このパスを使用します。別の場所にインストールした場合は、以降の該当箇所を実際のパスに置き換えてください。

---

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

---

Claude Desktop

Claude Desktop ではこの zip は必要ありません。 リリースページから Hawkeye.mcpb をダウンロードし、そのままインストールしてください。

• .mcpb がシステムで認識されるファイル形式の場合：ファイルをダブルクリックします。
• それ以外の場合：設定 → 拡張機能 → 拡張機能をインストールに移動し、ファイルを選択します。

---

Claude Code (CLI)

クイックスタート（5 ステップ）

1. まだインストールしていない場合は、https://www.zaragsoft.se/downloads から Hawkeye をインストールします。
2. AIBridge フォルダーを永続的な場所に移動します。推奨先：C:\Program Files\Hawkeye\AIBridge\。Downloads から実行しないでください。登録したパスが引き続き機能する必要があります。
3. Claude Code に MCP サーバーを登録します。

   claude mcp add hawkeye --scope user -- "C:\Program Files\Hawkeye\AIBridge\HawkeyeAIBridge.exe"
   

4. Claude が Hawkeye を使うタイミングを判断できるよう、スキルをインストールします。hawkeye-search.skill は zip アーカイブ（SKILL.md のみが含まれています）のため、名前を変更するのではなく、展開する必要があります。

   $skillDir = "$env:USERPROFILE\.claude\skills\hawkeye-search"
   New-Item -ItemType Directory -Force -Path $skillDir | Out-Null
   Expand-Archive -Path "C:\Program Files\Hawkeye\AIBridge\hawkeye-search.skill" -DestinationPath $skillDir -Force
   

5. 確認します。ターミナルを閉じて開き直し、次を実行します。

   claude mcp list
   

   hawkeye と、利用可能な 9 個のツールが表示されるはずです。

Claude Code が Hawkeye を見つけられることを確認する

MCP サーバーが hawkeye.exe を見つけられる必要があります。次のいずれかを選択してください。

オプション A（推奨）：HAWKEYE_PATH を設定する

# PowerShell — persistent
[Environment]::SetEnvironmentVariable("HAWKEYE_PATH", "C:\Program Files\Hawkeye\hawkeye.exe", "User")

:: Command Prompt — persistent
setx HAWKEYE_PATH "C:\Program Files\Hawkeye\hawkeye.exe"

環境変数を設定した後は、ターミナルを閉じて開き直し、新しい値を反映させてください。

オプション B：Windows GUI で Hawkeye を PATH に追加する

1. Win キーを押し、環境変数と入力して、システム環境変数の編集を開きます。
2. **環境変数…**をクリックし、ユーザー環境変数の下にある Path を選択して、編集… → 新規の順にクリックします。
3. C:\Program Files\Hawkeye を追加し、すべてのダイアログで OK をクリックします。
4. ターミナルを再起動します。

コマンドラインから setx PATH "%PATH%;..." を実行するのは避けてください。PATH が 1024 文字で切り詰められることがあります。代わりに GUI を使用してください。

登録コマンドについての注意事項

• --scope user を指定すると、現在のフォルダーだけでなく、すべての Claude Code セッションで Hawkeye を利用できるようになります。
• 区切り文字 -- は必須です。 これにより、Claude Code 自身のフラグと登録するコマンドの区切りが示されます。これがないと、登録に失敗する場合があります。

---

VS Code / GitHub Copilot

Hawkeye は VS Code の Copilot エージェントモードで MCP サーバーとして動作します。exe を登録してから、エージェントモードで Copilot Chat を開いてください。

クイックインストール（デフォルトのパス）

上のボタンをクリックし、VS Code で 許可をクリックします。

手動セットアップ

.vscode/mcp.json に次の内容を追加します（ファイルが存在しない場合は作成してください）。

{
  "servers": {
    "hawkeye": {
      "type": "stdio",
      "command": "C:\\Program Files\\Hawkeye\\AIBridge\\HawkeyeAIBridge.exe"
    }
  }
}

すべてのプロジェクトで Hawkeye を利用できるようにするには、代わりにユーザーレベルの設定に追加します。

// %APPDATA%\Code\User\mcp.json
{
  "servers": {
    "hawkeye": {
      "type": "stdio",
      "command": "C:\\Program Files\\Hawkeye\\AIBridge\\HawkeyeAIBridge.exe"
    }
  }
}

Copilot Chat で Hawkeye を使う

1. Copilot Chat を開きます（Ctrl+Alt+I）。
2. エージェントモードに切り替えます（上部のドロップダウンで選択します。Ask や Edit ではなく、Agent にする必要があります）。
3. 次を試します：「コードベースで findTeam を検索して」

注意： hawkeye-search.skill ファイルは Claude Code と Claude Desktop 専用です。VS Code では Copilot 独自のコンテキストシステムを使用するため、必要ありません。

---

Cursor

設定 → ツールと MCP → 新しい MCP サーバーを開き、次を追加します。

{
  "mcpServers": {
    "hawkeye": {
      "command": "cmd",
      "args": ["/c", "C:\\Program Files\\Hawkeye\\AIBridge\\HawkeyeAIBridge.exe"],
      "env": {}
    }
  }
}

cmd /c を使う理由： Cursor はコマンドパスを引用符で囲まずにシェルへ渡すため、（C:\Program Files\ のような）スペースを含むパスで問題が発生します。cmd /c で囲むと、この問題を回避できます。

Hawkeye AI Bridge が別の場所にインストールされている場合は、パスを調整してください。

---

OpenCode

opencode.json に次の内容を追加します（ファイルが存在しない場合は、プロジェクトのルートまたはホームディレクトリに作成してください）。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hawkeye": {
      "type": "local",
      "command": ["C:\\Program Files\\Hawkeye\\AIBridge\\HawkeyeAIBridge.exe"]
    }
  }
}

Claude Code の設定とは次の 3 点が異なります。

• キーは "mcpServers" ではなく "mcp" です。
• command は文字列の 配列であり、command と args に分ける形式ではありません。
• "type": "local" が必要です。

OpenCode へのスキルのインストール

OpenCode にはスキルが必要です。スキルがないと、OpenCode はツール呼び出しを MCP サーバー経由でルーティングせず、コマンドラインから hawkeye.exe を直接呼び出そうとします。

OpenCode では、.skill zip アーカイブからスキルを展開する必要があります。

$skillDir = "$env:USERPROFILE\.opencode\skills"
New-Item -ItemType Directory -Force -Path $skillDir | Out-Null

$tempZip = "$env:TEMP\hawkeye-search.zip"
Copy-Item "C:\Program Files\Hawkeye\AIBridge\hawkeye-search.skill" $tempZip -Force
Expand-Archive -Path $tempZip -DestinationPath $skillDir -Force
Remove-Item $tempZip

両方を配置したら、OpenCode を再起動して、「PlayerController が定義されている場所を検索して。」 と試してください。hawkeye_search_minimal が呼び出されるはずです。

---

Claude へのスキルのインストール

このスキルは、Hawkeye のツールを いつ、どのように 使うかを Claude に教えます。スキルがないと、Claude はツールの説明だけから推測する必要があり、結果の精度が下がります。

配布ファイルの名前は hawkeye-search.skill ですが、実際には単一の SKILL.md を含む zip アーカイブです。名前を変更するのではなく、展開する必要があります。（zip の名前を SKILL.md に変更すると、ファイル名はそのようになりますが、中身は zip のままなので、Claude はスキルとして読み取れません。）

PowerShell（1 コマンド）：

$skillDir = "$env:USERPROFILE\.claude\skills\hawkeye-search"
New-Item -ItemType Directory -Force -Path $skillDir | Out-Null
Expand-Archive -Path "C:\Program Files\Hawkeye\AIBridge\hawkeye-search.skill" -DestinationPath $skillDir -Force

手動での手順：

1. エクスプローラーを開き、%USERPROFILE%\.claude\skills\ に移動します（skills フォルダーがない場合は作成します）。
2. hawkeye-search という名前の新しいフォルダーを作成します。
3. hawkeye-search.skill を右クリックし、すべて展開... を選択して、先ほど作成した hawkeye-search フォルダーに展開します。（拡張子が .zip でなくても、Windows は .skill ファイルを zip アーカイブとして認識します。「すべて展開」が表示されない場合は、ファイルをコピーし、コピーしたファイルの拡張子を .zip に変更してから展開してください。）
4. 結果が hawkeye-search\SKILL.md であることを確認します。これは元のアーカイブではなく、プレーンテキストファイルです。

スキルを単一のプロジェクトに限定するには、代わりに <your-project>\.claude\skills\hawkeye-search\SKILL.md に SKILL.md を配置します。

---

利用可能なツール

ツール	説明
hawkeye_search_minimal	トークン効率の高い検索です。ファイルパスと行番号のみを返します。grep より 91% 少ないトークンで済みます。チャットでの検索に最適です。
hawkeye_expand_context	hawkeye_search_minimal の {file, lines} 検索結果を受け取り、コンテキストを拡張して結合したコードスニペットを 1 回の呼び出しで返します。範囲ごとの Read 呼び出しは不要です。サーバー側での結合（デフォルトの mergeGap=8）により、近接する検索結果を単一のブロックにまとめます。
hawkeye_search	メタデータを含む詳細検索です。コンテキスト付きの完全な結果オブジェクトを返します。詳細な分析に最適です。
hawkeye_get_groups	Hawkeye で設定されている検索可能なコードグループをすべて一覧表示します。
hawkeye_get_editors	ファイルを開くために設定されているエディターを一覧表示します。
hawkeye_execute_editor	設定済みのエディターで、指定した行番号のファイルを開きます。
hawkeye_health_check	Hawkeye サービスが実行中で、アクセス可能であることを確認します。
hawkeye_reload_index	リクエストに応じて、ウィンドウを開かず、フォーカスを奪わずに Hawkeye のインデックスをヘッドレスで再読み込みします。
validate_hawkeye_path	設定された Hawkeye のパスが存在し、有効であることを確認します。
get_settings	現在の Hawkeye 設定（パス、最大結果数、大文字と小文字の区別）を取得します。
save_settings	Hawkeye の設定を保存します。
copy_to_clipboard	テキストをシステムのクリップボードにコピーします。

---

トークンの節約

方法	使用トークン数
ファイルを無作為に読み取る（Hawkeye なし）	1 セッションあたり約 100,000
hawkeye_search_minimal を使用	1 セッションあたり約 20,000
節約量	約 80% 削減

---

プロンプトの例

AI コーディングアシスタントに次のように依頼できます。

• Hawkeye 内のグループを一覧表示して、すべてのグループを見つけてください。
• Hawkeye を使って、このクラスへの参照をすべて見つけてください。
• ワークスペースを検索して、このアセット名が使われている場所を見つけてください。
• グループ 4,7 で、インベントリーシステムに関連する可能性の高いファイルを見つけてください。
• プロジェクト全体で、このローカライズキーを検索してください。
• この Blueprint または Unreal アセットが参照されている場所を見つけてください。
• コードを編集する前に、ロードアウト機能に関連するファイルを表示してください。
• グループ 1,5,7 にある爆発音をすべて見つけてください。
• このファイルを変更する前に、Hawkeye を使ってコードとコンテンツの参照を見つけてください。
• グループを指定しない場合は、すべてのグループが使われます。

---

プライバシーとセキュリティ

• Hawkeye はローカル／オンプレミスで動作します。
• Hawkeye はソースコードをアップロードしません。
• Hawkeye 自体は、インデックス作成や検索に AI を使用しません。
• MCP サーバーは、ローカルで設定したツールに Hawkeye の機能を公開するだけです。
• どの MCP クライアントが接続できるかは、ご自身で管理できます。
• AI が生成したコードの変更は、適用する前に必ず確認してください。
• 当社のプライバシーガイドラインはこちらをご覧ください - https://www.zaragsoft.se/privacy

---

更新

新しいバージョンの HawkeyeAIBridge.exe がリリースされた場合：

• インストール先が同じ場合： exe を上書きするだけです。再登録は不要です。
• インストール先が異なる場合： 登録を解除して再登録します：

  claude mcp remove hawkeye
  claude mcp add hawkeye --scope user -- "C:\Program Files\Hawkeye\AIBridge\HawkeyeAIBridge.exe"
  

新しい hawkeye-search.skill がリリースされた場合は、Skill のインストール手順を繰り返してください — Expand-Archive -Force により、既存の SKILL.md が上書きされます。

---

削除

# Unregister from Claude Code
claude mcp remove hawkeye

# Delete the Skill (optional)
Remove-Item -Recurse "$env:USERPROFILE\.claude\skills\hawkeye-search"

# Delete the install folder (optional)
Remove-Item -Recurse "C:\Program Files\Hawkeye\AIBridge"

# Remove the HAWKEYE_PATH environment variable (optional)
[Environment]::SetEnvironmentVariable("HAWKEYE_PATH", $null, "User")

---

トラブルシューティング

claude コマンドが見つからない

Claude Code がインストールされていないか、PATH に含まれていません。https://docs.claude.com/en/docs/build-with-claude/claude-code からインストールし、ターミナルを再起動してください。

claude mcp list に hawkeye が表示されない

別のスコープに登録した可能性があります。--scope user を指定して再登録してください：

claude mcp remove hawkeye
claude mcp add hawkeye --scope user -- "C:\Program Files\Hawkeye\AIBridge\HawkeyeAIBridge.exe"

claude mcp list に hawkeye は表示されるが、ツールが 0 個

exe は登録されましたが、起動に失敗しています。よくある原因：

• 登録後に AIBridge フォルダーを移動または削除した。
• Hawkeye 自体が見つかりません — 新しいターミナルで hawkeye --version を実行して確認してください。
• 対処法：claude mcp remove hawkeye を実行してから、再登録してください。

Hawkeye が見つからない

Error: Failed to start Hawkeye process

1. 新しいターミナルを開き、hawkeye --version を実行します。
2. 失敗する場合は、HAWKEYE_PATH を設定し（上記の前提条件を参照）、ターミナルを閉じてから再度開きます。
3. 環境変数は、設定後に開いたターミナルでのみ適用されます。

Claude が Skill を使用しない

• ファイルが %USERPROFILE%\.claude\skills\hawkeye-search\SKILL.md に存在すること、および 別の名前が付いた .skill アーカイブではなく、プレーンテキストファイルであることを確認してください。右クリックして「プロパティ」を開きます。サイズが元の .skill ファイル（約 14 KB）と一致し、テキストエディターで開けない場合は、展開せずに名前を変更した状態です。削除して、上記の Expand-Archive 手順を再実行してください。
• Claude Code のセッションを再起動してください — Skill はセッション開始時に読み込まれます。

Cursor：パスエラーで接続に失敗する

Cursor のログに 'C:\Program' is not recognized as an internal or external command と表示される場合、スペースを含むパスが引用符で囲まれずに渡されています。上記の Cursor セクションに記載されている cmd /c を使った回避策を使用してください。

グループが返されない

No groups available / Empty group list

1. hawkeye --getgroups を手動で実行してテストします。
2. Hawkeye の設定が正しいことを確認します。
3. 作業ディレクトリのアクセス許可を確認します。

タイムアウトエラー

Error: Operation timed out waiting for Hawkeye

1. Hawkeye のプロセスが応答しなくなっていないか確認します。
2. システムリソースを確認します。
3. Hawkeye を再起動して、もう一度お試しください。

---

ライセンス

デュアルライセンス：

• SKILL.md と Skill コンポーネント：MIT License — 自由に変更および再配布できます。
• HawkeyeAIBridge 実行ファイル：プロプライエタリ（Zaragsoft）— 無料で使用できますが、変更、リバースエンジニアリング、再配布はできません。

利用条件の詳細については、LICENSE をご覧ください。

---

サポート

• Hawkeye：https://www.zaragsoft.se/downloads
• Hawkeye AI Bridge：https://www.zaragsoft.se/aibridge
• Claude Code：https://docs.claude.com/en/docs/build-with-claude/claude-code
• Smithery：
• Hawkeye AI Bridge に関するご質問やフィードバック：[email protected]