harbormaster

# Harbormaster > **停止在项目之间切换目录。** 一个 MCP 服务器可以将任何问题路由到任何项目的子代理 — 本地或通过 SSH — 并带有整个舰队的实时操作员仪表盘。 [](https://pypi.org/project/harbormaster-mcp/) [](https://pypi.org/project/harbormaster-mcp/) [](https://opensource.org/licenses/MIT) [](#versioning) [](https://modelcontextprotocol.io/) **Harbormaster** 是一个模型上下文协议（MCP）服务器和操作员控制台，适用于同时处理**多个项目**的开发人员。 将您的 [Claude Code](https://claude.com/product/claude-code)、[Claude Desktop](https://claude.ai/desktop)、[Codex](https://github.com/openai/codex)、[Cursor](https://cursor.sh/) 或任何 MCP 客户端指向它，您可以询问任何项目的问题 — **无需切换目录** — 目标项目的子代理加载其自己的 `CLAUDE.md` 和 [Serena](https://github.com/oraios/serena) 内存，回答并返回摘要。 随附的 Web 仪表盘将同一服务器转变为可一览的任务控制中心：项目网格，带有 KPI，项目间网络图，实时调度器跟踪瀑布图，Markdown 内存编辑器，多轴预算（每主机 / 每工具 / 每项目），以及浅色 / 深色主题。 > [FleetQ](https://fleetq.net) 生态系统的一部分。独立 OSS 完全可用，无需 FleetQ；FleetQ Bridge 集成纯粹是附加的。 --- ## 为什么选择 Harbormaster？ 您可能已经拥有： - `~/htdocs/`（或 `~/work/`，或 `~/code/`）中的 5–80 个项目 - 每个项目都有自己的 `CLAUDE.md`，Serena 内存，框架，Git 状态 - 可能有 1–5 个 SSH 可达的 VPS 主机运行生产副本 - 每个项目一个 LLM 编码会话（Claude Code，Codex，Cursor）— 这意味着每次切换目录时都会产生**上下文切换成本** **没有 Harbormaster：** 您需要切换目录，等待代理重新引导上下文，提出问题，复制答案。每天重复 12 次。 **使用 Harbormaster：** ``` > ask_project "accounting-fleetq" "cron 作业今天运行了吗？" > fan_out_ask "自上次发布以来有哪些 flaky 测试？" --hosts=local,prod-1 > delegate_task "hr-fleetq" "总结过去 10 次提交" --deliverable=changelog ``` 调用会话永远不会离开其自己的当前工作目录。目标项目的子代理加载其自己的内存，回答，返回摘要，并且您的提问 + 答案进入可回忆的问答历史记录。 ## 谁适合使用？ | 您是… | Harbormaster 给您… | |---|---| | **拥有 10+ 个侧项目的独立开发者** | 所有项目的控制台，跨项目搜索和调用图 | | **小型团队的 CTO** | 一个 MCP 端点，您的代理跨本地 + 生产主机对话，具有每个主机 / 工具 / 项目的预算上限 | | **平台工程师** | [FleetQ](https://fleetq.net) 的即插即用 Bridge 守护进程 — 平台工具，A2A 代理卡，联合知识图 | | **AI 代理研究人员** | 具有 Web UI 的现实世界多代理编排目标，用于可观察性 | | **拥有太多标签的 vibe 编码器** | 基于键盘的仪表盘（Cmd-K 调色板，1-5 标签导航）和更宁静的生活 | --- ## 它做什么？ 您跨多个项目工作，每个项目都有自己的 `CLAUDE.md` 和 Serena 内存。切换当前工作目录会丢失上下文。Harbormaster 让一个 Claude Code（或 Codex）会话可以询问任何项目的问题，而无需更改目录 — 项目的子代理加载其自己的内存，回答并返回摘要。 八种 MCP 工具涵盖日常流程：列出项目和主机，检查项目状态，询问单个项目，将问题扩展到多个项目，回忆之前的问答，遍历项目间依赖图。 可选的 SSH 扩展目标远程 VPS 主机。可选的 FleetQ 适配器将 Harbormaster 暴露为一流的 Bridge 守护进程（平台工具，A2A 代理卡，联合知识图）。 配套的 Web UI 将同一 MCP 服务器转变为本地操作员控制台：仪表盘，跟踪瀑布图，网络图，内存编辑器。 --- ## 快速入门 使用 `[ui]` 额外功能安装以获取操作员仪表盘： ```bash uvx --prerelease=allow 'harbormaster-mcp[ui]' --version # 或使用 pipx： pipx install --pip-args='--pre' 'harbormaster-mcp[ui]' ``` 在 Claude Code 中注册： ```bash claude mcp add --scope user harbormaster harbormaster-mcp ``` 或在 Claude Desktop 中（`~/Library/Application Support/Claude/claude_desktop_config.json`）： ```json { "mcpServers": { "harbormaster": { "command": "/opt/homebrew/bin/harbormaster-mcp", "env": {} } } } ``` 在操作员 UI 旁边运行（单独的进程 — 两个都读取相同的 TOML 配置，因此一个发现的项目对另一个可见）： ```bash export HARBORMASTER_UI_TOKEN=$(python -c 'import secrets; print(secrets.token_urlsafe(32))') harbormaster-ui --port 7531 # 然后打开 http://127.0.0.1:7531/ — 在提示符处粘贴令牌 ``` 默认情况下零配置：Harbormaster 自动发现 `~/htdocs/*` 下的项目（如果存在）。对于其他布局，请参阅 [配置](#配置)。 --- ## 工具 十二种 MCP 工具，可选地针对远程主机通过 `host="<label>"` 进行定位。 | 工具 | 用途 | 成本 | |---|---|---| | `list_projects(host=None)` | 列出配置的项目（本地）或远程目录列表（SSH）。 | ~50 ms / ~1 s | | `list_hosts()` | 配置的 `[hosts]` 加上 `~/.ssh/config` 主机别名。 | ~5 ms | | `project_status(name, host=None)` | Git 日志，Serena 内存列表，日志尾部。 | ~200 ms / ~2 s | | `ask_project(name, question, max_turns=5, host=None)` | 在项目 cwd 中启动 `claude -p`（或配置的后端），返回 ≤ 800 字摘要。 | ~30 s / ~90 s | | `delegate_task(name, task, deliverable, allow_writes=False, mode="sync", inbox_id="default", host=None)` | 委托任务；`allow_writes=true` 允许子代理直接编辑文件，`false`（默认）保持只读。`mode="async"` 入队并立即返回；调用者使用 `get_delegated_task` 轮询或使用 `recall_pending_results` 排空收件箱。 | 同步：~60 s / 异步：~5 ms 入队 | | `get_delegated_task(job_id)` | v22.0.0 — 一个异步委托作业的状态。 | ~5 ms | | `recall_pending_results(inbox_id, mark_read=True, limit=50)` | v22.0.0 — 从一个收件箱（FIFO 完成）排空已完成 / 失败的异步作业。 | ~10 ms | | `await_delegated_task(job_id, timeout_seconds=900)` | v22.1.0 — 阻塞直到一个特定作业完成。如果已完成则立即返回；超时返回当前行，状态为 `running` 或 `queued`。 | 最多 `timeout_seconds` | | `await_inbox(inbox_id, timeout_seconds=900, since=None)` | v22.1.0 — 阻塞直到收件箱中的任意作业完成。`since` 跳过已看到的完成。调用者使用 `recall_pending_results` 排空。 | 最多 `timeout_seconds` | | `fan_out_ask(question, project_filter=None, host_filter=None, max_concurrency=5, max_turns=3)` | 并行多项目问答；每个目标一个部分。 | ~`max_turns × backend_time × ⌈targets / max_concurrency⌉` | | `recall_qa(question, top_k=5, host=None, project=None, min_similarity=0.6)` | 对先前问答答案的语义回忆。 通过 `[history] enabled = true` 选择加入。 | ~50 ms（FTS5）/ ~150 ms（向量，预热后） | | `project_graph(format="json", include_dev_deps=False, transitive=False)` | 从清单解析的跨项目依赖图。返回节点 + 边 + 可选的 Mermaid 标记。 | ~100 ms / ~10 ms 缓存 | 每个工具的完整设计说明位于 [`docs/architecture-harbormaster.md`](docs/architecture-harbormaster.md)。 --- ## UI 概览 配套仪表盘（`harbormaster-ui --port 7531`）是一个本地优先的操作员控制台。所有表面都使用相同的 SSE 事件流，这是 MCP 传输的动力，因此您在 UI 中看到的内容与您的 MCP 客户端看到的内容相符。  ### 工作区 Shell（v19+） 每个页面都在一个固定的三列工作区内渲染，灵感来自 VSCode / Postman / Linear： ``` ┌─ 顶部栏（h-12，固定） ────────────────────────────────┐ ├──────────┬──────────────────────────┬─────────────────┤ │ 侧边栏 │ 主内容 │ 检查器 │ │ （240px）│ （1fr，滚动-y） │ （320px， │ │ 项目 │ 页面特定内容 │ 可折叠） │ └──────────┴──────────────────────────┴─────────────────┘ ``` * **顶部栏** — 品牌标记 + 页面标题 + Cmd-K 提示 + 主题切换 + 身份验证指示器。 * **侧边栏** — `所有主机 ▾` 过滤器 + `筛选项目…` 搜索 + `最近提问` + 语言组（`GO`，`JAVASCRIPT`，`PHP`，…）带有 `★`- 置顶项目标记。 * **主内容** — 页面内容；布局选择（单列 / 卡片网格 / 分窗格 / 标签）属于页面。 * **检查器** — 每个页面的上下文感知小部件（KPI 摘要 + 实时活动提要，项目元数据 + 预算表，等等）。通过 `«` 按钮折叠（状态在 `localStorage` 中持久化）；在 1280 像素以下自动折叠。 Linear-紫色 OKLCH 调色板，紧凑密度，浅色 / 深色主题切换。 ### 每个页面的表面 - **仪表盘（/`）** — 顶部的 **快速提问** 卡片（项目选择器 + 问题 → 导航到具有预填充查询的项目页面），KPI 条（项目，活动嵌入，近期查询，桥接状态，分发器健康状况，主机预算余量），2 列卡片网格（近期活动，自动重新嵌入，FleetQ 桥接，插件，回忆问答历史记录全宽，项目图全宽）。检查器显示一个 KPI 微型条 + 一个实时 SSE 驱动的活动提要，具有脉冲效果。 - **项目页面（/projects/<name>）** — 五个选项卡系统：**概览** / **内存** / **轨迹** / **问答历史** / **设置**。数字键 `1`-`5` 跳转到选项卡；`#tab=<id>` URL 哈希创建可共享的深层链接。检查器显示项目元数据 + 24 小时预算消耗。  - **内存选项卡** — 分窗格编辑器：文件列表（左侧）+ 原始 Markdown 文本区域（中心）+ 漂白消毒的实时 HTML 预览（右侧）。工具栏：保存 / 撤销（`Cmd-Z`）/ 恢复（`Cmd-Shift-Z`）/ `diff vs:` 修订选择器。最近 20 个文件历史记录，侧边栏 HTML 差异比较。  - **网络（/network）** — 使用 vendored Cytoscape 构建的项目间调用图。边权重跟踪实际的 Harbormaster MCP 调用（调用者 → 目标）。按主机 / 项目 / 工具 / 窗口过滤；可切换的图 / 聊天列表视图；SSE 驱动的实时追加。聚合统计信息位于 `/api/network/stats?window=…`。  - **调度器跟踪（/dispatcher）** — 实时飞行中的跨度 + 最近 100 个完成的跨度渲染为瀑布图，具有父 / 子嵌套。每个跨度公开工具，项目，主机，持续时间和（后端发出时）工具调用子跨度，用于模型的自身工具使用。实时后端令牌使用情况在 SSE `usage` 事件中。  ### 移动版（< 1024px） 低于 1024px，三列 Shell 折叠成抽屉。汉堡菜单（☰）切换侧边栏；信息按钮（ⓘ）切换检查器。单击背景或按 `Esc` 取消。 <table> <tr> <td><img src="docs/screenshots/dashboard-mobile.png" alt="移动版仪表盘 — 抽屉关闭，汉堡菜单 + 信息按钮在顶部栏" width="320"></td> <td><img src="docs/screenshots/dashboard-mobile-drawer.png" alt="移动版仪表盘 — 侧边栏抽屉打开，带有背景叠加层" width="320"></td> </tr> <tr> <td align="center"><sub>抽屉关闭</sub></td> <td align="center"><sub>侧边栏抽屉打开</sub></td> </table> - **Cmd-K 命令调色板** — 双字母模糊匹配动作启动器；可共享的 URL 通过 `?q=` 预填充；从单个目录中提取动作，因此每个页面表面添加自身，以便免费使用。  --- ## 配置 默认情况下零配置。对于其他任何布局，请在 `~/.config/harbormaster/config.toml` 处放置一个 TOML 文件： ```toml [projects] glob = ["~/code/*", "~/work/*"] exclude = ["**/node_modules/**", "**/vendor/**"] [hosts.friday] ssh_host = "katsarov-server.local" remote_htdocs = "~/htdocs" [hosts.hetzner-1] ssh_host = "hetzner-1.example.com" remote_htdocs = "/var/www" # 可选 — 选择加入问答历史记录 / 回忆 [history] enabled = true # 可选 — 每日调用预算 [budget] daily_call_budget_per_tool = { ask_project = 200, delegate_task = 50 } ``` 可以在任何时候使用以下命令验证每个项目级别的覆盖文件 `./.harbormaster.toml`： ```bash harbormaster-mcp config check ``` 完整的模式（每个部分、键、类型、默认值、有效范围）：**[`docs/operator-config-reference.md`](docs/operator-config-reference.md)**。 --- ## 后端 Harbormaster 的后端抽象是一种协议；该项目自带两个一流的实现： | 后端 | 默认适用于 | 注释 | |---|---|---| | `claude` (`claude -p`) | `[backends.default]` | 引用后端。每个令牌的流式传输，实时后端报告的令牌使用情况在 SSE `usage` 事件中，tool_use 子跨度仪表盘。 | | `codex` (Codex CLI) | 通过 `[backends.codex]` 选择加入 | 令牌仪表盘兼容性（v12.0.0a1）。工具使用子跨度仪表盘兼容性（v17.0.0a2）。与 ask / delegate / fan-out 接口相同。 | 切换项目的后端是 TOML 编辑 — 无需代码更改。SSH 主机各自携带自己的后端设置（主机块上的 `backend = "codex"`，因此您可以在整个舰队中使用不同的后端。 每个远程主机上的预飞行：安装后端的 CLI，验证一次， 确保项目路径存在并带有其 `CLAUDE.md` / `.serena/` 目录，并确认来自您机器的无密码 SSH（`BatchMode=yes` 由 Harbormaster 强制执行）。 --- ## FleetQ 桥接集成（可选） 使用 `[fleetq]` 额外功能安装，Harbormaster 注册自己作为桥接守护进程，将其 MCP 工具宣传为平台工具，发布每个项目的 A2A 代理卡，并将语义三元组写入联合知识图谱： ```bash pipx install 'harbormaster-mcp[ui,fleetq]' ``` ```toml [fleetq] enabled = true register_as_bridge = true base_url = "https://app.fleetq.net" api_token_env = "FLEETQ_API_TOKEN" heartbeat_interval = 30 ``` ```bash export FLEETQ_API_TOKEN=... harbormaster-mcp ``` Harbormaster 在 FleetQ 连接界面中显示为 `harbormaster on <hostname>`。反向隧道调用从 FleetQ → 桥接器 → Harbormaster 透明地转发，具有 `text/event-stream` 转发（`X-Accel-Buffering: no`，因此反向代理不会缓冲）。 发现的合约参考： [`docs/fleetq-bridge-contract.md`](docs/fleetq-bridge-contract.md). --- ## 比较 | | **Harbormaster** | 单个项目一个 MCP | 每次项目切换 `cd` | Bash 别名 | |---|---|---|---|---| | MCP 服务器进程数量 | **1** | N（每个项目一个） | 0 | 0 | | 跨项目搜索的问答历史记录 | ✅ | ❌ | ❌ | ❌ | | 项目间调用图 | ✅ Cytoscape 网络视图 | ❌ | ❌ | ❌ | | 实时跟踪瀑布图 | ✅ `/dispatcher` | ❌ | ❌ | ❌ | | 多轴预算 | ✅ 每主机 + 每工具 + 每项目 | ❌ | ❌ | ❌ | | 远程 SSH 项目路由 | ✅ 相同工具目标 `host=...` | 需要 N 个 SSH MCP | 手动 ssh + cd | 手动 ssh + cd | | 内存编辑器（CLAUDE.md，`.serena/memories/*.md`） | ✅ 分窗格 + 漂白预览 + 修订历史 | 编辑磁盘上的文件 | 编辑磁盘上的文件 | 编辑磁盘上的文件 | | Web 操作员控制台 | ✅ | ❌ | ❌ | ❌ | | 新项目设置 | 0（自动发现） | 新的 MCP 条目 | 不适用 | 不适用 | ## 常见问题 **Harbormaster 是否在没有 Claude Code 的情况下工作？** 是的。任何 MCP 兼容的客户端都可以使用 — Claude Code、Claude Desktop、Codex、Cursor、Aider 或通过 [MCP 规范](https://modelcontextprotocol.io/) 的自定义集成。 **我需要 FleetQ 吗？** 不需要。Harbormaster 独立功能齐全。 `[fleetq]` 额外功能纯粹是附加的 — 注册为桥接器，发布 A2A 代理卡，将轨迹镜像到 FleetQ 内存。所有功能均可选择加入。 **我的数据存储在哪里？** 本地。SQLite 在 `~/.harbormaster/qa_local.db`（问答历史记录）+ `~/.harbormaster/network_log.db`（项目间调用记录）+ `~/.harbormaster/memory_revisions.db`（每个文件的前 20 个内存修订记录）。无遥测，无电话上报。可选的 `[telemetry]` 配置块仅限选择加入，并将路由到您自己的端点。 **安全性如何？** 每个 UI 端点使用承载令牌身份验证 + cookie 支持的 SSE（v12+）。内存编辑器通过 `bleach.clean()` 在渲染时进行处理（允许列出的标签，阻止 `javascript:`/ `data:` 方案）。路径遍历保护每个项目（仅 `CLAUDE.md` + `.serena/memories/*.md`）。 **我可以将其作为长期运行的守护进程运行吗？** 是的。`harbormaster-ui --port 7531 &` 然后将书签添加到 `http://127.0.0.1:7531/`。或使用 launchd / systemd 包装。或使用 Tauri shell（计划中，独立项目：`harbormaster-desktop`）。 **它与 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 有何不同？** MCP Inspector 是用于单个 MCP 服务器的调试 UI。Harbormaster 是多项目路由器 *以及* 操作员控制台 — 它公开了针对多个项目的 MCP 工具，并可视化了它们的交互。 ## 版本控制 Harbormaster 遵循一种成熟的 alpha 节奏：每个主要版本 (`vN.0.0`) 都由一系列 `vN.0.0aK` alpha 标签预先发布，每个 alpha 版本都是一个 PyPI 发布版本，而 GA 标签 `vN.0.0` 是一个无需代码变更的推广，并附带一份累积的回顾文档。 该节奏已经成功发布 GA 版本 18 次（从 v1 到 v18），没有一次强制回滚。目前的最新版本是 **v21.0.0a3**。 每个行为变更都会在某个 alpha 版本中实现，并在 [`CHANGELOG.md`](CHANGELOG.md) 中相应地记录在对应的主要版本下。在 [`docs/sprint-retro-harbormaster-v*.md`](docs/) 下的每个主要版本的回顾文档是变更原因的权威叙述。 PyPI 发布是通过 Trusted Publishing（OIDC）自动化的 —— 仓库中没有 API token。推送到 `v*` 的标签会触发发布工作流。 --- ## 预提交钩子 两个仓库本地钩子在 [`.pre-commit-config.yaml`](.pre-commit-config.yaml) 中提供： - **`harbormaster-config-check`** — 验证 [`examples/harbormaster.toml`](examples/harbormaster.toml) 是否符合 TOML 模式。如果出现任何模式错误，提交操作将会失败。 - **`harbormaster-config-doc-parity`** — 如果在 `src/harbormaster/config.py` 中添加了 Pydantic 字段，但未在 [`docs/operator-config-reference.md`](docs/operator-config-reference.md) 中提及，则提交操作将会失败。在失败时，钩子会输出一个可以直接粘贴的 markdown 区块，以便快速添加缺失的文档。 安装方式： ```sh uv sync --extra dev bash scripts/post_sync_install_hooks.sh ``` 或者使用系统 / pipx 预提交：`pipx install pre-commit && pre-commit install`. --- ## 贡献 Harbormaster 主要是一个单操作员工具。当以下条件符合时，欢迎提交拉取请求： 1. 每个分支对应一个功能 —— `feat/v<N>.<P>-<phase-name>`。 2. 在请求审查之前，请确保测试 + `mypy --strict` + `ruff` 清理通过。 3. 为任何新的配置字段更新 [`docs/operator-config-reference.md`](docs/operator-config-reference.md)（文档一致性钩子会通知您）。 4. 尽可能保持变更为累加性 —— Harbormaster 的不变性是每个发布线上的零破坏变更。 操作员工作流程和部署场景在 [`docs/operator-guide.md`](docs/operator-guide.md) 中有详细记录。 --- ## 血统 Harbormaster v1.0 源自 `project-router-mcp` v0.1（2026-05-08）。v0.1 的 Git 历史记录保留在此仓库中 —— v0.1 单文件服务器位于 `src/server.py`，存在于 v1.0 脚手架重构之前的提交中。 --- ## 许可证 MIT —— 请参阅 [LICENSE](LICENSE)。