Harbor

注意： Harbor 与容器注册表 CNCF Harbor 无关。

为什么选择 Harbor

查看 Mac 上已运行的服务

Harbor 会盘点当前用户的 TCP 监听端口，并显示端口、进程、命令、工作目录、HTTP 响应和可能使用的框架。明确的证据可将服务对应到已注册的项目；Harbor 也会标记可能重复运行的项目和可从网络访问的绑定，同时保留未知监听项供查看。

启动项目，而不是堆满终端

添加文件夹并查看 Harbor 检测到的服务。Harbor 会按顺序启动依赖项、持续输出日志、监控运行状况和资源，并解析项目端口。再次启动副本前，Harbor 会检查项目是否已有可安全复用的匹配服务。

让编码 Agent 使用同一信息源

Harbor 通过仅限环回地址的 MCP 服务公开实时项目和服务状态。Claude 和 Codex 可以检查本地监听端口、检测项目、读取日志，以及操作已注册的项目。Agent 创建的配置会保持暂停，直到你在 Harbor 中批准该配置。

安装

下载应用

从最新版本下载 .dmg，打开后将 Harbor 拖到“应用程序”文件夹。

使用 Homebrew 安装

brew install --cask luke-fairbanks/tap/harbor

正式版本由 Faba Development 签名并经 Apple 公证。Harbor 支持运行 macOS 11 Big Sur 或更高版本的 Apple Silicon 和 Intel Mac。

从 v0.4.0 开始，Harbor 会在启动后不久以及每六小时检查一次已签名的更新。安装前始终会征求你的同意。你也可以通过项目设置 → Harbor 更新手动检查。Harbor 更新并重新启动期间，由其管理的项目进程会继续运行。

快速入门

1. 打开 Harbor 并选择添加项目，或将项目文件夹拖到窗口中。
2. 检查检测到的服务和命令，然后选择添加到 Harbor。
3. 打开项目并选择启动项目。
4. 打开本地服务，查看该项目的端口以及当前由 macOS 用户运行的其他监听项。

Harbor 可识别常见的 JavaScript 框架和包管理器、Django、FastAPI、Flask、Go、Rails 以及静态网站。如果检测未能识别，你可以改为导入或编辑 harbor.json 配置。

保守设计

• 观察不等于拥有。 将服务匹配到项目，并不意味着 Harbor 有权停止它。
• 防止重复优先考虑确定性。 Harbor 会复用匹配度高的服务；如果匹配结果有歧义，则会阻止启动并请你检查。
• 清理受到身份保护。 只有独立运行且未被跟踪的服务才会提供停止选项。向进程发送信号前，Harbor 会重新检查 PID、进程启动时间和端口；对于终端、IDE、编码 Agent 和 Harbor 本身，则会拒绝操作。“可安全停止”描述的是进程隔离情况，不代表进程没有未保存的工作。
• Agent 编写的命令需要本地批准。 批准仅适用于确切的已注册配置。通过 MCP 更改配置后，需要重新批准。
• MCP 始终在本地运行。 服务绑定到 127.0.0.1，并在每次启动 Harbor 时使用新的 bearer token。在 macOS 上，其描述符和 Harbor 的应用数据目录仅限所有者访问，原生桥接程序会在转发凭据前验证监听器的所有权。
• 通过 AI 修复需要明确调用。 调用此功能时，Harbor 会将服务命令、工作路径、退出状态和近期日志传递给已安装的 Codex 或 Claude CLI。之后，这些数据将按照 Harbor 所调用的服务提供商的隐私条款处理。

Harbor 管理的内容

• 依赖感知的启动、停止、重启和一键式项目启动
• 在 IPv4 和 IPv6 上分配首选端口或下一个可用端口
• 在服务之间重写 ${PORT} 和 ${services.<name>.port}
• 识别会固定使用自身端口的命令
• HTTP、TCP、日志模式和进程存活就绪检查
• 每个受管进程组的实时日志、CPU 和内存信息
• 可选择启用带有上限退避机制的崩溃后重启
• 应用重启后重新接管仍在运行且已验证的 Harbor 进程
• 用于常见项目操作的菜单栏弹出窗口
• 感知框架的项目检测和可编辑的 harbor.json 配置

本地服务清单

本地服务视图会扫描由当前 macOS 用户拥有的 TCP 监听器。它综合进程、工作目录、命令、端口和有限的 HTTP 证据，将每个监听器分类为未知、已匹配、由 Harbor 管理或符合身份安全清理条件。

Harbor 可以在分配新端口前，识别运行在服务首选端口上且匹配度高的服务。如果该进程与终端、IDE、Claude 或 Codex 共享一个进程组，Harbor 会仅对其进行监控，不会终止所属主机进程。

连接 Claude 或 Codex

打开 AI connections，然后选择 Connect Claude Code、Connect Desktop 或 Connect Codex。引导式设置会安装 Harbor 签名的、仅限所有者使用的原生桥接程序。新的客户端配置仅包含其稳定的命令路径：无需 Bearer 令牌、环境变量、Node.js 安装或首次运行下载。如果 Harbor 已关闭，桥接程序会在后台静默打开它。首次连接后，请启动新的客户端会话（或完全退出并重新打开已在运行的客户端），以便加载新条目。

当 Harbor 退出并重新打开时，由客户端管理的 stdio 进程会保持连接。它会重新读取 Harbor 受保护的端点描述文件，跟踪令牌和端口轮换，并在转发下一个请求前重放 MCP 后端生命周期。从 Harbor v0.4.2 的旧版启动器升级后，需要最后重启一次客户端；之后正常重启 Harbor 则无需重启客户端。后续 Harbor 更新若替换了桥接程序二进制文件，也需要重启客户端，才能使用新的桥接程序代码。

Harbor 会区分已保存的配置和检测到的 Bridge running 进程；后者表示客户端已启动桥接程序，而客户端自身的 MCP 工具列表才是确认其已接受工具目录的最终依据。

高级用户可以通过 Streamable HTTP 直接连接。从 ~/Library/Application Support/com.harbor.desktop/mcp.json 中读取当前端口和令牌；端口可能不同于 7777，且每次重启 Harbor 后令牌都会变化。

SETTINGS="$HOME/Library/Application Support/com.harbor.desktop/mcp.json"
PORT="$(plutil -extract port raw -o - "$SETTINGS")"
TOKEN="$(plutil -extract token raw -o - "$SETTINGS")"
claude mcp add harbor --scope user --transport http "http://127.0.0.1:${PORT}/mcp" \
  --header "Authorization: Bearer ${TOKEN}"

然后试试：

正在运行哪些本地服务？其中是否有看起来重复的？

MCP 工具

工具	用途
list_apps	列出已注册的项目及其当前运行状态
app_status(app)	检查服务、解析后的端口和端口规划
detect_app(path)	扫描文件夹并提出配置建议，但不保存
register_app(config)	添加或替换配置，并要求审批
start_app(app, profile?)	启动已获批准的项目或配置档
stop_app(app)	停止 Harbor 管理的项目服务
restart_app(app, profile?)	重启已获批准的项目或配置档
get_logs(app, service, lines?)	读取最近捕获的日志
list_local_servers	清点监听进程、匹配项和可能重复的服务
stop_local_server(pid, port, startedAt)	请求安全清理身份已确认的独立服务
open_app(app)	打开运行中项目的主要 URL

从源代码构建

Harbor 使用 Tauri 2，采用 Rust 核心和 React 19 / Radix Themes 界面。

npm install
npm run prepare:bridge
npm run tauri dev

运行本地生产构建，不包含更新器产物：

npm run tauri:build:local

验证更改

npm run prepare:bridge
npm test
npm run build
npm run test:rust

cargo fmt --manifest-path src-tauri/Cargo.toml --all -- --check
cargo fmt --manifest-path src-tauri/mcp-bridge/Cargo.toml --all -- --check
cargo clippy --manifest-path src-tauri/Cargo.toml --locked --all-targets -- -D warnings
cargo clippy --manifest-path src-tauri/mcp-bridge/Cargo.toml --locked --all-targets -- -D warnings
cargo test --manifest-path src-tauri/mcp-bridge/Cargo.toml --locked

更改 MCP 架构、传输、身份验证或原生桥接程序时，至少使用过一次一键设置后，启动修补后的 Harbor 构建，然后对确切安装的 Claude/Codex 桥接程序进行 90 秒测试：

node scripts/mcp-bridge-soak.mjs --restart-harbor --duration-ms 90000 --interval-ms 30000

该测试工具会执行兼容 Claude 的初始化、验证所有已公布的工具架构，并反复调用只读工具 list_apps。测试必须以 PASS 结束，且不得出现架构、身份验证、传输或重新连接错误。

已发布架构见 DESIGN.md，计划中的工作见 ROADMAP.md，签名发布流程见 DISTRIBUTING.md。

反馈与贡献

发现 Harbor 错误识别的监听进程、无法检测的项目，或无法连接的 MCP 客户端？提交引导式问题。发布日志或命令前，请移除令牌、凭据、.env 内容和私有路径。

欢迎提交问题和拉取请求。请通过 GitHub 安全公告表单 私下报告安全漏洞。

许可证

MIT © Luke Fairbanks