Hawkeye AI Bridge

Hawkeye AI Bridge MCP 服务

按每月 1,000 万个 token 计算的续航时间——假设每天进行 50 次搜索，且每次搜索都像这样，预计耗尽每月 1,000 万个 token 上下文预算还剩多少天。横条越长，续航时间越久。

• 宽泛 grep - 1.6 天
• 精简 grep - 7.0 天
• Hawkeye 索引搜索 - 29.0 天

为 Claude Code、VS Code、Cursor 和 AI Agent 提供本地代码库搜索。

Hawkeye AI Bridge 让 AI 编码助手通过 MCP 查询 Hawkeye 的本地项目索引，从而在大型代码库、资源、脚本、本地化内容、配置文件和项目内容中查找精确引用，而无需上传整个代码库。

Hawkeye 不会向 AI Agent 提供海量的原始 grep 输出，而是返回精简的文件和行号结果，帮助 Agent 判断接下来哪些文件真正值得读取。

1. 在本地搜索大型项目
2. 减少嘈杂原始搜索输出带来的 token 消耗
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 安装 Skill
• 可用工具
• Token 节省情况
• 提示词示例
• 隐私与安全
• 更新
• 移除
• 故障排除
• 许可证
• 支持

---

这是什么？

此代码库是使用 Hawkeye AI Bridge 作为 MCP 服务的官方公开配置与发现仓库。

其中不包含专有的 Hawkeye AI Bridge 源代码。Hawkeye 和 Hawkeye AI Bridge 是 Zaragsoft 拥有的专有软件。

---

为什么使用 Hawkeye AI Bridge？

Hawkeye 可帮助开发者快速搜索和理解大型项目。借助 MCP 支持，AI 编码助手可以向 Hawkeye 请求快速的本地搜索结果，从而减少每次调用的 token 消耗。

典型用例：

• 查找类、函数、符号、资源、本地化键或文件的所有引用。
• 搜索大型代码库，而不只依赖编辑器搜索。
• 帮助 AI 编码助手在修改前更全面地了解项目。
• 更轻松地浏览大型游戏／软件项目，减少对口口相传知识的依赖。
• 在本地／本地部署环境中进行搜索。
• 与盲目读取文件相比，token 用量约减少 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 是系统识别的文件类型：双击该文件。
• 否则：前往 Settings → Extensions → Install Extension 并选择该文件。

---

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. 安装 Skill，让 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 图形界面将 Hawkeye 添加到 PATH

1. 按 Win，输入 Environment Variables，打开 Edit the system environment variables。
2. 点击 Environment Variables… → 在 User variables 下，选择 Path → Edit… → New。
3. 添加 C:\Program Files\Hawkeye，并在所有对话框中点击 OK。
4. 重启终端。

避免在命令行中使用 setx PATH "%PATH%;..."——它可能会将 PATH 截断至 1024 个字符。请改用图形界面。

注册命令说明

• --scope user 会让 Hawkeye 在每个 Claude Code 会话中都可用，而不只是当前文件夹。
• 必须使用 -- 分隔符。 它用于告知 Claude Code 自身的标志参数到此结束，后面是要注册的命令。若省略，注册可能会失败。

---

VS Code / GitHub Copilot

Hawkeye 可在 VS Code 的 Copilot Agent 模式下作为 MCP 服务使用。注册 exe，然后在 Agent 模式下打开 Copilot Chat。

快速安装（默认路径）

点击上方按钮，然后在 VS Code 中点击 Allow。

手动设置

将以下内容添加到 .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. 切换到 Agent mode（顶部的下拉菜单——必须选择 Agent，而不是 Ask 或 Edit）
3. 试试：“在我的代码库中搜索 findTeam”

注意：hawkeye-search.skill 文件仅适用于 Claude Code 和 Claude Desktop——VS Code 使用 Copilot 自己的上下文系统，不需要该文件。

---

Cursor

打开 Settings → Tools & MCP → New MCP Server 并添加：

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

为什么要使用 cmd /c？ Cursor 会将命令路径传递给 shell，但不加引号，这会导致包含空格的路径（例如 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 配置相比，有三处不同：

• 键是 "mcp"，而不是 "mcpServers"
• command 是由字符串组成的数组，而不是将 command 与 args 分开
• 必须设置 "type": "local"

为 OpenCode 安装技能

OpenCode 需要此技能。没有它，OpenCode 会尝试直接通过命令行调用 hawkeye.exe，而不会将工具调用路由到 MCP 服务。

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 安装技能

此技能会教 Claude 何时以及如何使用 Hawkeye 工具。没有它，Claude 只能根据工具描述自行猜测，结果会更差。

提供的文件名为 hawkeye-search.skill，但它实际上是一个 zip 存档，里面包含一个 SKILL.md 文件——需要将其解压，而不是重命名。（将 zip 重命名为 SKILL.md 后，得到的文件虽然名称如此，但内容仍是 zip 存档，Claude 无法将其作为技能读取。）

PowerShell（一条命令）：

$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——一个纯文本文件，而不是原始存档。

若要将技能限制在单个项目中，请将 SKILL.md 放在 <your-project>\.claude\skills\hawkeye-search\SKILL.md 中。

---

可用工具

工具	描述
hawkeye_search_minimal	节省令牌的搜索——仅返回文件路径和行号。与 grep 相比，令牌用量减少 91%。最适合基于聊天的查找。
hawkeye_expand_context	接收 hawkeye_search_minimal 返回的 {file, lines} 命中结果，并通过一次调用返回合并且扩展上下文的代码片段——无需逐个范围调用 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）	每个会话约 100,000
使用 hawkeye_search_minimal	每个会话约 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 会话 — Skills 会在会话启动时加载。

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 许可证 — 可自由修改和再分发。
• 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]