harbormaster-mcp 1.0.0a9__tar.gz

harbormaster_mcp-1.0.0a9/.github/workflows/ci.yml

@@ -0,0 +1,310 @@
+# Security note: this workflow does NOT consume any untrusted github.event.*
+# fields (titles, bodies, branch labels, commit messages). The only ${{ }}
+# expansions are workflow-defined matrix values and trusted action versions —
+# no user-controlled string flows into a `run:` step. See:
+# https://github.blog/security/vulnerability-research/how-to-catch-github-actions-workflow-injections-before-attackers-do/
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: ${{ matrix.os }} · py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-14]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff)
+        run: uv run --python ${{ matrix.python-version }} ruff check src/ tests/
+
+      - name: Type check (mypy --strict)
+        run: uv run --python ${{ matrix.python-version }} mypy --strict src/harbormaster/
+
+      - name: Tests (pytest)
+        run: uv run --python ${{ matrix.python-version }} pytest tests/ -v
+
+  smoke-http:
+    name: HTTP transport smoke test (SSE + bearer auth)
+    runs-on: ubuntu-24.04
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Generate auth token
+        id: token
+        # Workflow-internal random — not user input. Stored in step output for
+        # downstream env: bindings (no ${{ }} interpolation inside run: scripts).
+        run: |
+          {
+            echo "token=$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Start harbormaster-mcp in background
+        env:
+          HARBORMASTER_MCP_TOKEN: ${{ steps.token.outputs.token }}
+        run: |
+          uv run harbormaster-mcp --transport sse --port 17532 &
+          echo "HMS_PID=$!" >> "$GITHUB_ENV"
+          # Poll until the bearer middleware is live (max 15s)
+          for _ in $(seq 1 30); do
+            status=$(curl -s -o /dev/null -w '%{http_code}' --max-time 1 http://127.0.0.1:17532/sse || echo 0)
+            if [ "$status" = "401" ]; then
+              echo "Server up — auth middleware is rejecting unauth requests"
+              exit 0
+            fi
+            sleep 0.5
+          done
+          echo "Server did not start within 15s"
+          exit 1
+
+      - name: Reject request without Authorization header
+        run: |
+          status=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 http://127.0.0.1:17532/sse)
+          test "$status" = "401" || { echo "Expected 401, got $status"; exit 1; }
+
+      - name: Reject request with wrong bearer token
+        run: |
+          status=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 \
+            -H 'Authorization: Bearer obviously-wrong' \
+            http://127.0.0.1:17532/sse)
+          test "$status" = "401" || { echo "Expected 401, got $status"; exit 1; }
+
+      - name: Accept request with correct bearer token
+        env:
+          TOKEN: ${{ steps.token.outputs.token }}
+        run: |
+          # SSE keeps the connection open, so cap the curl with --max-time.
+          # The middleware's job is "anything except 401" — the actual
+          # MCP handshake response is FastMCP's concern, not ours here.
+          status=$(curl -s -o /dev/null -w '%{http_code}' --max-time 3 \
+            -H "Authorization: Bearer $TOKEN" \
+            http://127.0.0.1:17532/sse || echo 0)
+          if [ "$status" = "401" ]; then
+            echo "FAIL: bearer middleware rejected the correct token (status=$status)"
+            exit 1
+          fi
+          echo "OK: middleware passed through to FastMCP (status=$status)"
+
+      - name: Stop background server
+        if: always()
+        run: |
+          if [ -n "${HMS_PID:-}" ]; then
+            kill "$HMS_PID" 2>/dev/null || true
+          fi
+
+  smoke-ui:
+    name: Live UI smoke test (loopback, no auth)
+    runs-on: ubuntu-24.04
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Start harbormaster-ui in background
+        run: |
+          uv run harbormaster-ui --host 127.0.0.1 --port 17531 &
+          echo "UI_PID=$!" >> "$GITHUB_ENV"
+          # Poll /api/health up to 15s
+          for _ in $(seq 1 30); do
+            status=$(curl -s -o /dev/null -w '%{http_code}' --max-time 1 http://127.0.0.1:17531/api/health || echo 0)
+            if [ "$status" = "200" ]; then
+              echo "UI up after $_ tries"
+              exit 0
+            fi
+            sleep 0.5
+          done
+          echo "UI did not become healthy within 15s"
+          exit 1
+
+      - name: /api/health returns ok + version
+        run: |
+          body=$(curl -s --max-time 5 http://127.0.0.1:17531/api/health)
+          echo "body: $body"
+          echo "$body" | grep -q '"status":"ok"' || { echo "missing status:ok"; exit 1; }
+          echo "$body" | grep -q '"version":' || { echo "missing version field"; exit 1; }
+
+      - name: /api/projects returns a JSON list
+        run: |
+          status=$(curl -s -o /tmp/projects.json -w '%{http_code}' --max-time 5 http://127.0.0.1:17531/api/projects)
+          test "$status" = "200" || { echo "Expected 200, got $status"; exit 1; }
+          # Body must be a JSON array (starts with [, ends with ])
+          first=$(head -c 1 /tmp/projects.json)
+          last=$(tail -c 1 /tmp/projects.json)
+          test "$first" = "[" || { echo "body does not start with ["; head -c 200 /tmp/projects.json; exit 1; }
+          test "$last" = "]" || { echo "body does not end with ]"; tail -c 200 /tmp/projects.json; exit 1; }
+
+      - name: / returns dashboard HTML
+        run: |
+          body=$(curl -s --max-time 5 http://127.0.0.1:17531/)
+          echo "$body" | grep -q '<title>' || { echo "missing <title>"; exit 1; }
+          echo "$body" | grep -q 'Harbormaster' || { echo "missing 'Harbormaster' in body"; exit 1; }
+          echo "$body" | grep -q 'tailwindcss' || { echo "missing tailwindcss CDN"; exit 1; }
+
+      - name: Stop background server
+        if: always()
+        run: |
+          if [ -n "${UI_PID:-}" ]; then
+            kill "$UI_PID" 2>/dev/null || true
+          fi
+
+  smoke-ui-auth:
+    name: UI auth required for non-loopback bind
+    runs-on: ubuntu-24.04
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Public bind without token must exit 2
+        run: |
+          # Run with --host 0.0.0.0 (public) and no HARBORMASTER_UI_TOKEN.
+          # The CLI must abort BEFORE binding any port. Capture exit code.
+          set +e
+          uv run harbormaster-ui --host 0.0.0.0 --port 17532 2>&1
+          rc=$?
+          set -e
+          test "$rc" = "2" || { echo "Expected exit 2, got $rc"; exit 1; }
+          echo "OK: aborted with exit 2 as expected"
+
+  smoke-ui-with-token:
+    name: UI opt-in bearer auth on loopback (token roundtrip)
+    runs-on: ubuntu-24.04
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Generate auth token
+        id: token
+        run: |
+          {
+            echo "token=$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Start harbormaster-ui with token in background
+        env:
+          HARBORMASTER_UI_TOKEN: ${{ steps.token.outputs.token }}
+        run: |
+          # Loopback bind + token set -> opt-in auth even on 127.0.0.1.
+          uv run harbormaster-ui --host 127.0.0.1 --port 17533 &
+          echo "UI_PID=$!" >> "$GITHUB_ENV"
+          # Poll until the bearer middleware is rejecting unauth (proves it's live).
+          for _ in $(seq 1 30); do
+            status=$(curl -s -o /dev/null -w '%{http_code}' --max-time 1 http://127.0.0.1:17533/api/health || echo 0)
+            if [ "$status" = "401" ]; then
+              echo "UI up — opt-in token middleware live"
+              exit 0
+            fi
+            sleep 0.5
+          done
+          echo "UI did not become healthy within 15s"
+          exit 1
+
+      - name: Reject request without Authorization header
+        run: |
+          status=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 http://127.0.0.1:17533/api/health)
+          test "$status" = "401" || { echo "Expected 401, got $status"; exit 1; }
+
+      - name: Reject request with wrong bearer token
+        run: |
+          status=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 \
+            -H 'Authorization: Bearer obviously-wrong' \
+            http://127.0.0.1:17533/api/health)
+          test "$status" = "401" || { echo "Expected 401, got $status"; exit 1; }
+
+      - name: Accept request with correct bearer token
+        env:
+          TOKEN: ${{ steps.token.outputs.token }}
+        run: |
+          status=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 \
+            -H "Authorization: Bearer $TOKEN" \
+            http://127.0.0.1:17533/api/health)
+          test "$status" = "200" || { echo "Expected 200, got $status"; exit 1; }
+          echo "OK: bearer auth on UI works end-to-end"
+
+      - name: Stop background server
+        if: always()
+        run: |
+          if [ -n "${UI_PID:-}" ]; then
+            kill "$UI_PID" 2>/dev/null || true
+          fi
+
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-24.04
+    needs: [test, smoke-http, smoke-ui, smoke-ui-auth, smoke-ui-with-token]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 14

harbormaster_mcp-1.0.0a9/.github/workflows/publish.yml

@@ -0,0 +1,104 @@
+# Security note: this workflow does NOT consume any untrusted github.event.*
+# fields. Only tag-name and step-output expressions flow into run: blocks, all
+# bound via env: for explicit handling. Uses PyPI Trusted Publishing (OIDC) —
+# no long-lived API tokens stored in the repo.
+
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        type: choice
+        options: [pypi, testpypi]
+        default: pypi
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-24.04
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Read package version
+        id: version
+        run: |
+          v=$(uv run python -c "from harbormaster import __version__; print(__version__)")
+          echo "version=$v" >> "$GITHUB_OUTPUT"
+          echo "Building harbormaster-mcp $v"
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Verify built version matches tag
+        if: github.event_name == 'push'
+        env:
+          REF: ${{ github.ref_name }}
+          PKG_VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          tag_version="${REF#v}"
+          if [ "$tag_version" != "$PKG_VERSION" ]; then
+            echo "Tag $REF (-> $tag_version) does not match package $PKG_VERSION"
+            exit 1
+          fi
+          echo "OK: tag $REF matches package version $PKG_VERSION"
+
+      - name: Upload distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 14
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    needs: build
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/harbormaster-mcp
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    needs: build
+    runs-on: ubuntu-24.04
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/harbormaster-mcp
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

harbormaster_mcp-1.0.0a9/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.uv-cache/
+.pytest_cache/
+*.egg-info/
+.DS_Store

harbormaster_mcp-1.0.0a9/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FleetQ contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

harbormaster_mcp-1.0.0a9/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: harbormaster-mcp
+Version: 1.0.0a9
+Summary: MCP server that routes Q&A across all your projects — locally or over SSH. Part of the FleetQ ecosystem.
+Project-URL: Homepage, https://github.com/FleetQ/harbormaster
+Project-URL: Repository, https://github.com/FleetQ/harbormaster
+Project-URL: Issues, https://github.com/FleetQ/harbormaster/issues
+Project-URL: Documentation, https://github.com/FleetQ/harbormaster/tree/main/docs
+Author-email: FleetQ <harbormaster@fleetq.net>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude,claude-code,fleetq,mcp,router,subagent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: jinja2>=3.1; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pysher>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest-httpserver>=1.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: fleetq
+Requires-Dist: httpx>=0.27; extra == 'fleetq'
+Requires-Dist: pysher>=1.0; extra == 'fleetq'
+Provides-Extra: ui
+Requires-Dist: bleach>=6.1; extra == 'ui'
+Requires-Dist: fastapi>=0.110; extra == 'ui'
+Requires-Dist: jinja2>=3.1; extra == 'ui'
+Requires-Dist: sse-starlette>=2.0; extra == 'ui'
+Requires-Dist: uvicorn[standard]>=0.27; extra == 'ui'
+Description-Content-Type: text/markdown
+
+# Harbormaster
+
+> MCP server that routes Q&A across all your projects — locally or over SSH. **Part of the [FleetQ](https://fleetq.net) ecosystem.**
+
+[![PyPI](https://img.shields.io/pypi/v/harbormaster-mcp.svg?label=harbormaster-mcp)](https://pypi.org/project/harbormaster-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](#status)
+
+## What it does
+
+You work across many projects, each with its own `CLAUDE.md` and Serena memories. Switching cwd loses context. Harbormaster lets one Claude Code session ask any project a question without changing directory — the project's subagent loads its own memory, answers, and returns a summary.
+
+Optional SSH fan-out lets the same tools target remote VPS hosts. Optional FleetQ adapter makes Harbormaster a first-class citizen of the FleetQ Bridge ecosystem (Platform Tool, A2A Agent Cards, federated knowledge graph).
+
+## Tools
+
+| Tool | Purpose | Cost |
+|---|---|---|
+| `list_projects(host=None)` | Enumerate configured projects (local) or remote dir listing (SSH). | ~50 ms / ~1 s |
+| `list_hosts()` | Configured `[hosts]` + `~/.ssh/config` Host aliases. | ~5 ms |
+| `project_status(name, host=None)` | Git log, Serena memories, log tails. | ~200 ms / ~2 s |
+| `ask_project(name, question, max_turns=5, host=None)` | Spawn `claude -p` in project cwd, return ≤ 800-word summary. | ~30 s / ~90 s |
+| `delegate_task(name, task, deliverable, allow_writes=False, host=None)` | Read-only delegation; v1 fails closed for writes. | ~60 s / ~90 s |
+| `fan_out_ask(question, project_filter=None, host_filter=None, max_concurrency=5, max_turns=3)` | Parallel multi-project Q&A. Returns one section per target. | ~`max_turns × claude_p_time` × ⌈targets/max_concurrency⌉ |
+
+More tools (`recall_qa`, …) land in v1.1–1.2. See [`docs/architecture-harbormaster.md`](docs/architecture-harbormaster.md).
+
+## Install
+
+```bash
+pipx install harbormaster-mcp
+# or run without install:
+uvx harbormaster-mcp
+```
+
+Register in Claude Code:
+
+```bash
+claude mcp add --scope user harbormaster harbormaster-mcp
+```
+
+Or in Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "harbormaster": {
+      "command": "/opt/homebrew/bin/harbormaster-mcp",
+      "env": {}
+    }
+  }
+}
+```
+
+### Live UI (optional)
+
+Install with the `[ui]` extra and run the dashboard alongside (or instead of) the MCP server:
+
+```bash
+pipx install 'harbormaster-mcp[ui]'
+harbormaster-ui --port 7531
+# open http://127.0.0.1:7531/
+```
+
+v1.0.0a4 ships:
+
+- **Dashboard** at `/` — project grid with framework / git / Serena / CLAUDE.md badges (HTMX + Alpine + Tailwind via CDN, ~no build step).
+- **`GET /api/projects`** — JSON list of every project Harbormaster discovers (use this to script your own dashboards).
+- **`GET /api/health`** — `{"status":"ok","version":"..."}` for liveness probes.
+
+The UI is a separate process from the MCP server. Run both — they read the same TOML config so projects discovered by one are visible to the other. SSE feed of live MCP queries lands in v1.0.0a5.
+
+### HTTP / SSE transport
+
+For remote MCP clients or running outside the desktop client, Harbormaster can speak SSE / streamable-http instead of stdio. **A bearer token is required** — there is no auth-disabled HTTP mode.
+
+```bash
+export HARBORMASTER_MCP_TOKEN=$(python -c 'import secrets; print(secrets.token_urlsafe(32))')
+harbormaster-mcp --transport sse --host 127.0.0.1 --port 7532
+# or the new MCP spec transport:
+harbormaster-mcp --transport streamable-http --port 7532
+```
+
+Clients send the token as `Authorization: Bearer <token>`. Missing or wrong tokens return 401.
+
+Override the env-var name with `--auth-token-env MY_VAR` if you keep secrets under a different name. Use `--host 0.0.0.0` only if you understand the implications — the bearer token is the only thing between the open port and your projects.
+
+Run `harbormaster-mcp --help` for the full flag set.
+
+## Configure
+
+Zero-config by default — Harbormaster discovers projects under `~/htdocs/*` if it exists. For any other layout, drop a TOML file at `~/.config/harbormaster/config.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"
+```
+
+A per-project override at `./.harbormaster.toml` in your cwd takes precedence over the user-level config.
+
+Full schema and all options: [`docs/architecture-harbormaster.md` §3](docs/architecture-harbormaster.md).
+
+## Remote hosts
+
+Every project-targeting tool accepts an optional `host` parameter. With `host` set, Harbormaster runs the equivalent command on that SSH host:
+
+```
+> ask_project(name="pricex", question="quick health check?", host="friday")
+[ssh friday bash -lc 'cd ~/htdocs/pricex && claude -p ...']
+```
+
+**Pre-flight on each remote host**:
+
+1. Install Claude Code: `npm i -g @anthropic-ai/claude-code`.
+2. Authenticate once: `claude` (this is a separate Anthropic seat per host).
+3. Ensure project paths exist with their `CLAUDE.md` / `.serena/` in place.
+4. Confirm passwordless SSH from your machine (`BatchMode=yes` is enforced).
+
+## v1 limits
+
+- Read-only delegation (`allow_writes=True` returns an error).
+- 60 s local / 90 s remote subprocess timeout.
+- 800-word output cap (full output dumped to `/tmp/harbormaster-*.md` on truncation).
+- Remote `list_projects` returns a flat list of directory names (rich metadata is local-only — gathering it remotely would mean N round-trips).
+
+## Status
+
+**v1.0.0a9** — `POST /mcp/{server}` HTTP-direct routing endpoint shipped 2026-05-08. **End-to-end FleetQ → harbormaster MCP routing now functional** (with the matching agent-fleet PR https://github.com/escapeboy/agent-fleet-o/pull/72 applied). The 6-week roadmap to general availability:
+
+| Phase | Weeks | Focus |
+|-------|-------|-------|
+| v1.0 | 1–2 | Local + SSH + Live UI scaffold + PyPI alpha |
+| v1.1 | 3–4 | FleetQ Bridge / Platform Tool / A2A integration |
+| v1.2 | 5–6 | Q&A history, federated KG, auto project graph |
+
+See [`docs/design-harbormaster.md`](docs/design-harbormaster.md) for the full design.
+
+## Lineage
+
+Harbormaster v1.0 grew out of `project-router-mcp` v0.1 (2026-05-08). v0.1 git history is preserved on this repository — the v0.1 single-file server lived at `src/server.py` and remains in commits prior to the v1.0 scaffolding refactor.
+
+## Architecture
+
+Single Python process hosting an MCP server (stdio + HTTP/SSE), an embedded Live UI, and an optional FleetQ adapter. Pluggable backend per host (default: `claude -p`). All shell-bound strings pass through `shlex.quote`.
+
+Detailed component diagrams, transport choices, and integration contract: [`docs/architecture-harbormaster.md`](docs/architecture-harbormaster.md).
+
+## FleetQ Bridge integration (optional)
+
+Install with the `[fleetq]` extra and Harbormaster can register itself as a Bridge daemon in your FleetQ deployment, advertising its 6 MCP tools to the platform:
+
+```bash
+pipx install 'harbormaster-mcp[fleetq]'
+```
+
+In your config TOML:
+
+```toml
+[fleetq]
+enabled = true
+register_as_bridge = true
+base_url = "https://app.fleetq.net"   # or your self-hosted FleetQ URL
+api_token_env = "FLEETQ_API_TOKEN"    # env var holding the Sanctum token
+heartbeat_interval = 30               # seconds between heartbeats
+```
+
+Then export your Sanctum token (must have a `team:<uuid>` ability) and run the MCP server:
+
+```bash
+export FLEETQ_API_TOKEN=...
+harbormaster-mcp
+```
+
+Harbormaster shows up in your FleetQ Connections UI as `harbormaster on <hostname>`. v1.0.0a6 ships **register + heartbeat + disconnect**; the reverse-WebSocket relay channel for incoming MCP tool calls lands in v1.0.0a7+.
+
+Discovered contract reference: [`docs/fleetq-bridge-contract.md`](docs/fleetq-bridge-contract.md).
+
+## Releasing
+
+PyPI publishing is automated via Trusted Publishing (OIDC) — no API tokens in the repo. Tag-pushes to `v*` trigger `.github/workflows/publish.yml`. Setup steps and the release checklist live in [`docs/publishing.md`](docs/publishing.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).