harbormaster-mcp 1.0.0__tar.gz

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

@@ -0,0 +1,427 @@
+# 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
+
+  smoke-fleetq:
+    # Gated live smoke against a real FleetQ instance. Skipped by default —
+    # set the `FLEETQ_SMOKE_ENABLED` repo variable to `true` and configure
+    # the `FLEETQ_TEST_BASE_URL` + `FLEETQ_TEST_API_TOKEN` secrets to enable.
+    # Build is intentionally NOT in this job's `needs:` so a skipped run on
+    # public PRs doesn't block release artifacts. Inputs are repo-admin
+    # configured (`vars.*` / `secrets.*`) — no untrusted github.event.* is
+    # consumed, consistent with the workflow-wide security note above.
+    name: Live FleetQ Bridge smoke (gated)
+    runs-on: ubuntu-24.04
+    needs: test
+    if: ${{ vars.FLEETQ_SMOKE_ENABLED == 'true' }}
+    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 --extra fleetq
+
+      - name: Run live FleetQ Bridge smoke
+        env:
+          FLEETQ_TEST_BASE_URL: ${{ secrets.FLEETQ_TEST_BASE_URL }}
+          FLEETQ_TEST_API_TOKEN: ${{ secrets.FLEETQ_TEST_API_TOKEN }}
+        run: uv run python tests/smoke_fleetq.py
+
+  smoke-mcp-streaming:
+    # Live SSE wire-shape check. Drives /mcp/harbormaster with
+    # `Accept: text/event-stream` and asserts the response is text/event-stream
+    # with a final `event: result` line. Doesn't need a real claude binary —
+    # tools/list returns the static tool registry, so the test is fast and
+    # deterministic. This catches wire-shape regressions on the daemon side
+    # that unit-mocked tests can't see.
+    name: MCP HTTP-direct SSE wire-shape smoke
+    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 mcp bound
+        env:
+          HARBORMASTER_UI_TOKEN: ${{ steps.token.outputs.token }}
+        run: |
+          # The UI app exposes /mcp/{server} when launched with mcp bound;
+          # harbormaster-ui's CLI does that by default since v1.0.0a4.
+          uv run harbormaster-ui --host 127.0.0.1 --port 17534 &
+          echo "UI_PID=$!" >> "$GITHUB_ENV"
+          for _ in $(seq 1 30); do
+            status=$(curl -s -o /dev/null -w '%{http_code}' --max-time 1 http://127.0.0.1:17534/api/health || echo 0)
+            if [ "$status" = "401" ]; then
+              echo "UI up — auth middleware live"
+              exit 0
+            fi
+            sleep 0.5
+          done
+          echo "UI did not become healthy within 15s"
+          exit 1
+
+      - name: Drive /mcp/harbormaster with SSE accept and assert wire shape
+        env:
+          TOKEN: ${{ steps.token.outputs.token }}
+        run: |
+          # Capture full body, then verify content-type + SSE event shape.
+          body=$(curl -s -i --max-time 10 \
+            -H "Authorization: Bearer $TOKEN" \
+            -H 'Accept: text/event-stream' \
+            -H 'Content-Type: application/json' \
+            -d '{"method":"tools/list","params":{}}' \
+            http://127.0.0.1:17534/mcp/harbormaster)
+
+          echo "$body" | head -20
+
+          # Strip CR from SSE wire — sse-starlette emits \r\n line endings
+          # per the SSE spec, but GNU grep's $ anchor matches before \n only,
+          # so the trailing \r breaks ^event: result$ on Ubuntu (it passed
+          # by coincidence on BSD grep / macOS). Normalize once, then assert.
+          body_norm=$(echo "$body" | tr -d '\r')
+
+          echo "$body_norm" | grep -qi '^content-type: text/event-stream' || {
+            echo "FAIL: Content-Type was not text/event-stream"
+            exit 1
+          }
+          echo "$body_norm" | grep -q '^event: result$' || {
+            echo "FAIL: response did not contain 'event: result'"
+            exit 1
+          }
+          echo "$body_norm" | grep -qE '"name":[[:space:]]*"ask_project"' || {
+            echo "FAIL: response did not list ask_project tool"
+            exit 1
+          }
+          echo "OK: SSE wire shape verified"
+
+      - 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, smoke-mcp-streaming]
+    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.0/.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.0/.gitignore

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

harbormaster_mcp-1.0.0/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.