python-netgear-switch-library 0.0.post405__tar.gz → 0.1.post4__tar.gz

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/.github/workflows/ci.yml

@@ -2,7 +2,10 @@ name: CI
 
 # Runs the SAME gates as local development (ruff, mypy --strict, pytest with
 # coverage >= 90) on every push to main and every pull request. A green run here
-# is what "mergeable" means; merging to main triggers the release workflows.
+# is what "mergeable" means -- and what "releasable" means: publish-pypi.yml and
+# deb.yml are triggered by this workflow COMPLETING on main and proceed only
+# when it succeeded (workflow_run + conclusion check), so a red push to main
+# is never published. Renaming this workflow breaks that trigger.
 on:
   push:
     branches: [main]

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/.github/workflows/deb.yml

@@ -1,18 +1,30 @@
 name: Debian Packages + apt repo
 
-# Rolling release: every push to main builds python3-netgear-switch-library for
-# Debian trixie AND sid and republishes a signed flat apt repository on GitHub
-# Pages (https://mithro.github.io/python-netgear-switch-library/). Mirrors the pattern
-# used by other mithro apt-repo projects (sensors2mqtt, ten64-controller). The
-# package is Architecture: all (pure Python), so it builds on the default x86
-# runner and installs on any Debian arch. No tags: the version is git-derived.
+# Rolling release: every GREEN push to main builds python3-netgear-switch-library
+# for Debian trixie AND sid and republishes a signed flat apt repository on
+# GitHub Pages (https://mith.ro/python-netgear-switch-library/). Mirrors the
+# pattern used by other mithro apt-repo projects (sensors2mqtt, ten64-controller).
+# The package is Architecture: all (pure Python), so it builds on the default x86
+# runner and installs on any Debian arch. The version is git-derived (vX.Y at a
+# tag, vX.Y.postN after it -- identical to the wheel's).
+#
+# Gated on CI exactly like publish-pypi.yml: triggered when the "CI" workflow
+# completes for main, and build-deb only proceeds when that run succeeded, so a
+# red commit never reaches the apt repo. workflow_dispatch stays for re-runs.
 on:
-  push:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
     branches: [main]
   workflow_dispatch:
 
 jobs:
   build-deb:
+    # workflow_run fires on every completion (failure/cancelled too); only a
+    # successful CI run is a release. publish-apt inherits the skip via needs.
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      github.event.workflow_run.conclusion == 'success'
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -21,7 +33,10 @@ jobs:
     steps:
       - uses: actions/checkout@v5
         with:
-          fetch-depth: 0  # full history so deb-version.py can count commits
+          # Pin to the SHA CI validated, not the default-branch HEAD (which a
+          # workflow_run checkout would otherwise use and may already be past).
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+          fetch-depth: 0  # full history + tags so deb-version.py can describe
 
       - name: Build package in debian:${{ matrix.suite }}
         run: |

python_netgear_switch_library-0.1.post4/.github/workflows/publish-pypi.yml

@@ -0,0 +1,71 @@
+name: Publish to PyPI
+
+# Every GREEN push to main is a release. The version is derived from git by
+# hatch-vcs (see pyproject.toml): vX.Y at a tag, vX.Y.postN N commits later, so
+# each commit produces a new, unique version -- no manual bump.
+#
+# This workflow is gated on CI: it runs when the "CI" workflow (ruff, mypy,
+# pytest + coverage, docs) COMPLETES for a push to main, and the build job only
+# proceeds when that run SUCCEEDED. Before this gate, a red CI run and a PyPI
+# upload raced each other and broken commits were published (13ef042 shipped
+# with the docs job failing, a60bae6 with every test job failing). The
+# workflow_dispatch path stays for manual re-runs.
+#
+# Publishing uses PyPI Trusted Publishing (OIDC): there is no API token in the
+# repo; the `pypi` environment + trusted publisher are registered (see
+# RELEASING.md).
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build:
+    # workflow_run fires on EVERY completion (failure and cancelled included);
+    # only a successful CI run is a release. Dependent jobs inherit the skip.
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          # A workflow_run checkout defaults to the default branch HEAD, which
+          # may already be PAST the commit CI just validated. Pin to the SHA
+          # CI actually ran on, so the published version is exactly the one
+          # that went green.
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+          fetch-depth: 0  # full history + tags for hatch-vcs version derivation
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Show derived version
+        run: ls -1 dist/
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted Publishing requires an OIDC token and a named environment.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI (OIDC trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-netgear-switch-library
-Version: 0.0.post405
+Version: 0.1.post4
 Summary: Python library and CLI to query and control Netgear switches over SNMP, NSDP and HTTP.
 Author-email: Tim Ansell <me@mith.ro>
 License-Expression: Apache-2.0
@@ -83,14 +83,14 @@ GitHub Pages apt repository. Pick the line matching your suite:
 
 ```sh
 sudo install -d -m0755 /etc/apt/keyrings
-curl -fsSL https://mithro.github.io/python-netgear-switch-library/netgear-switch.gpg \
+curl -fsSL https://mith.ro/python-netgear-switch-library/netgear-switch.gpg \
   | sudo tee /etc/apt/keyrings/netgear-switch.gpg > /dev/null
 
 # trixie:
-echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mithro.github.io/python-netgear-switch-library/trixie/ ./" \
+echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mith.ro/python-netgear-switch-library/trixie/ ./" \
   | sudo tee /etc/apt/sources.list.d/netgear-switch.list
 # sid:
-echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mithro.github.io/python-netgear-switch-library/sid/ ./" \
+echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mith.ro/python-netgear-switch-library/sid/ ./" \
   | sudo tee /etc/apt/sources.list.d/netgear-switch.list
 
 sudo apt update

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/README.md

@@ -48,14 +48,14 @@ GitHub Pages apt repository. Pick the line matching your suite:
 
 ```sh
 sudo install -d -m0755 /etc/apt/keyrings
-curl -fsSL https://mithro.github.io/python-netgear-switch-library/netgear-switch.gpg \
+curl -fsSL https://mith.ro/python-netgear-switch-library/netgear-switch.gpg \
   | sudo tee /etc/apt/keyrings/netgear-switch.gpg > /dev/null
 
 # trixie:
-echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mithro.github.io/python-netgear-switch-library/trixie/ ./" \
+echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mith.ro/python-netgear-switch-library/trixie/ ./" \
   | sudo tee /etc/apt/sources.list.d/netgear-switch.list
 # sid:
-echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mithro.github.io/python-netgear-switch-library/sid/ ./" \
+echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mith.ro/python-netgear-switch-library/sid/ ./" \
   | sudo tee /etc/apt/sources.list.d/netgear-switch.list
 
 sudo apt update

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/RELEASING.md

@@ -1,19 +1,38 @@
 # Releasing
 
-This project is a **rolling release**. There are no tags and no manual version
-bumps: the version is derived from git (`hatch-vcs` for the wheel,
-`packaging/deb-version.py` for the `.deb`), and **every merge to `main`
-publishes new packages** automatically:
+This project is a **rolling release**. There are no manual version bumps: the
+version is derived from `git describe` (`hatch-vcs` for the wheel,
+`packaging/deb-version.py` for the `.deb`) — `X.Y` at a `vX.Y` tag,
+`X.Y.postN` N commits after it — and **every green merge to `main` publishes
+new packages** automatically:
 
 - `.github/workflows/ci.yml` — runs the gates (ruff, mypy --strict, pytest with
-  coverage >= 90) on every push and PR. A green run is what "mergeable" means.
+  coverage >= 90, docs build) on every push and PR. A green run is what
+  "mergeable" means, and it is what triggers the two release workflows.
 - `.github/workflows/publish-pypi.yml` — builds and uploads the wheel + sdist to
-  PyPI on every push to `main`.
+  PyPI when CI **succeeds** on `main` (`workflow_run`; a failed or cancelled CI
+  run publishes nothing, and the checkout is pinned to the SHA CI validated).
 - `.github/workflows/deb.yml` — builds `.deb`s for trixie + sid and republishes
-  the signed apt repo on GitHub Pages on every push to `main`.
+  the signed apt repo on GitHub Pages, gated the same way.
 
 Merges to `main` MUST use `--no-ff` merge commits so history stays linear per PR.
 
+## Tags
+
+Tags are the only human input to the version. `v0.0` sits on the root commit
+(so `git describe` works from the start of history, per the repo-setup
+guidance) and `v0.1` marks where the CI-gated pipeline landed (2026-08-22). The
+fallback before any tag existed was `0.0.post<commit count>`, which reached
+`0.0.post405` on PyPI; `v0.1` was chosen because it sorts above that in both
+PEP 440 and Debian ordering, whereas counting from a root tag alone would have
+re-issued `0.0.post404`/`405` (and `skip-existing` would have silently dropped
+the upload).
+
+To cut a new series, push an annotated `vX.Y` tag on `main` (a GitHub tag
+ruleset only admits `vXX.ZZZ`-shaped tags) — the next green CI run publishes
+`X.Y`, and every commit after it `X.Y.postN`. Never move or delete a tag that
+has been published from.
+
 ## One-time human setup
 
 These steps are done ONCE by a maintainer. **No secret or key is ever committed
@@ -83,7 +102,7 @@ re-runs idempotent.
 
 1. Settings → Pages → Source: **GitHub Actions**.
 2. The `deb.yml` `publish-apt` job deploys the apt repo to
-   `https://mithro.github.io/python-netgear-switch-library/`. It targets the
+   `https://mith.ro/python-netgear-switch-library/`. It targets the
    `github-pages` deployment environment, which GitHub creates automatically
    once Pages is enabled — no separate environment setup is needed for this
    one (unlike the `pypi` environment above, which must be created by hand).
@@ -91,7 +110,8 @@ re-runs idempotent.
 ## Verifying a release
 
 - PyPI: check https://pypi.org/project/python-netgear-switch-library/ for the new
-  `0.0.postN` version.
+  `X.Y.postN` version (matches `git describe --tags` on `main`, e.g. `v0.1-3-g…`
+  → `0.1.post3`).
 - apt: `sudo apt update && apt-cache policy python3-netgear-switch-library` on a
   Debian trixie/sid box configured per the README. Before the GPG key is set
   (see step 2 above), expect `apt update` to fail with a signature error for

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/debian/control

@@ -20,8 +20,11 @@ Architecture: all
 Depends: ${python3:Depends},
          ${misc:Depends},
          snmp
-Recommends: python3-httpx
-Suggests: python3-pysnmp
+Recommends: python3-httpx,
+            python3-mcp
+Suggests: python3-pysnmp,
+          python3-paramiko,
+          python3-serial
 Description: query and control Netgear switches over SNMP, NSDP and HTTP
  Python library (import name netgear_switch) and CLI (ngsw) to query and control
  Netgear managed and Plus switches behind one model-driven API. Managed switches
@@ -30,4 +33,6 @@ Description: query and control Netgear switches over SNMP, NSDP and HTTP
  The synchronous SNMP transport shells out to the net-snmp command-line tools
  (snmpget/snmpbulkwalk/snmpset) from the "snmp" package, which is why it is a
  hard runtime dependency. The optional asynchronous transport uses python3-pysnmp
- and the HTTP transport uses python3-httpx.
+ and the HTTP transport uses python3-httpx. The ngsw-mcp MCP server (installed
+ unconditionally) needs python3-mcp; the FASTPATH SSH/serial CLI backends need
+ python3-paramiko / python3-serial.

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/docs/guide/installation.rst

@@ -82,14 +82,14 @@ GitHub Pages apt repository:
 .. code-block:: sh
 
    sudo install -d -m0755 /etc/apt/keyrings
-   curl -fsSL https://mithro.github.io/python-netgear-switch-library/netgear-switch.gpg \
+   curl -fsSL https://mith.ro/python-netgear-switch-library/netgear-switch.gpg \
      | sudo tee /etc/apt/keyrings/netgear-switch.gpg > /dev/null
 
    # trixie:
-   echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mithro.github.io/python-netgear-switch-library/trixie/ ./" \
+   echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mith.ro/python-netgear-switch-library/trixie/ ./" \
      | sudo tee /etc/apt/sources.list.d/netgear-switch.list
    # sid:
-   echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mithro.github.io/python-netgear-switch-library/sid/ ./" \
+   echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mith.ro/python-netgear-switch-library/sid/ ./" \
      | sudo tee /etc/apt/sources.list.d/netgear-switch.list
 
    sudo apt update
@@ -102,10 +102,11 @@ the net-snmp tools automatically. The packaging lives in ``debian/`` and
 Versioning
 ----------
 
-A **rolling release**. The version is derived from git by ``hatch-vcs``
-(``0.0.postN``, or ``X.Y.postN`` once a ``vX.Y`` tag exists); every merge to
-``main`` publishes to PyPI and to the apt repository. No manual version bumps —
-see ``RELEASING.md``.
+A **rolling release**. The version is derived from ``git describe`` by
+``hatch-vcs``: ``X.Y`` at a ``vX.Y`` tag, ``X.Y.postN`` N commits after it
+(``0.1``, ``0.1.post1``, …). Every merge to ``main`` whose CI run is green
+publishes to PyPI and to the apt repository — a red run publishes nothing. No
+manual version bumps — see ``RELEASING.md``.
 
 .. note::
 

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/docs/mcp.rst

@@ -2,17 +2,32 @@ MCP server
 ==========
 
 ``ngsw-mcp`` exposes the library as `Model Context Protocol
-<https://modelcontextprotocol.io>`_ tools over stdio, so an LLM-driven client
-can inspect — and, if you let it, reconfigure — your switches.
+<https://modelcontextprotocol.io>`_ tools, so an LLM-driven client can inspect
+— and, if you let it, reconfigure — your switches.
 
 .. code-block:: sh
 
    pip install 'python-netgear-switch-library[mcp]'
-   ngsw-mcp
+   ngsw-mcp                                   # stdio: one client, on stdin/stdout
+   ngsw-mcp --transport streamable-http --host 127.0.0.1 --port 8766   # shared
+
+Transports
+----------
+
+``--transport stdio`` (the default) serves the one client that spawned the
+process. ``--transport streamable-http`` listens on ``--host``/``--port`` so any
+number of clients share one long-lived server — for example a systemd
+socket-activated service that several agents on the same host connect to.
+Each option also has an environment form, ``NGSW_MCP_TRANSPORT``,
+``NGSW_MCP_HOST`` and ``NGSW_MCP_PORT`` (a flag beats the environment), so a
+service unit can set them once and keep ``ExecStart=ngsw-mcp``. An invalid
+transport or port — from either tier — is rejected at start-up.
 
 Configuring a client
 --------------------
 
+A client that spawns its own server (stdio):
+
 .. code-block:: json
 
    {
@@ -32,6 +47,16 @@ Every tool resolves its target switch through the **same resolver the CLI uses**
 with credentials layered from arguments, environment and inventory. See
 :doc:`guide/configuration`.
 
+A client connecting to a shared streamable-http server instead names its URL:
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "netgear": {"type": "http", "url": "http://127.0.0.1:8765/mcp"}
+     }
+   }
+
 .. note::
 
    ``$NGSW_INVENTORY`` is an MCP-server convenience — an MCP client has no

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/packaging/apt-index.html

@@ -14,10 +14,10 @@ Rolling release &mdash; every push to <code>main</code> publishes a new version
 <h2>Setup (Debian trixie)</h2>
 <pre>
 sudo install -d -m0755 /etc/apt/keyrings
-curl -fsSL https://mithro.github.io/python-netgear-switch-library/netgear-switch.gpg \
+curl -fsSL https://mith.ro/python-netgear-switch-library/netgear-switch.gpg \
   | sudo tee /etc/apt/keyrings/netgear-switch.gpg > /dev/null
 
-echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mithro.github.io/python-netgear-switch-library/trixie/ ./" \
+echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mith.ro/python-netgear-switch-library/trixie/ ./" \
   | sudo tee /etc/apt/sources.list.d/netgear-switch.list
 
 sudo apt update
@@ -27,10 +27,10 @@ sudo apt install python3-netgear-switch-library
 <h2>Setup (Debian sid)</h2>
 <pre>
 sudo install -d -m0755 /etc/apt/keyrings
-curl -fsSL https://mithro.github.io/python-netgear-switch-library/netgear-switch.gpg \
+curl -fsSL https://mith.ro/python-netgear-switch-library/netgear-switch.gpg \
   | sudo tee /etc/apt/keyrings/netgear-switch.gpg > /dev/null
 
-echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mithro.github.io/python-netgear-switch-library/sid/ ./" \
+echo "deb [signed-by=/etc/apt/keyrings/netgear-switch.gpg] https://mith.ro/python-netgear-switch-library/sid/ ./" \
   | sudo tee /etc/apt/sources.list.d/netgear-switch.list
 
 sudo apt update

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/pyproject.toml

@@ -63,11 +63,16 @@ ngsw-mcp = "netgear_switch.mcp.server:main"
 [dependency-groups]
 dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.11", "pytest-cov>=5.0"]
 
-# Rolling release: the version is derived from git, never hand-edited and never
-# tagged. Every commit on main increments the commit height, so post-release
-# versioning yields a real, monotonic version (0.0.postN with no tag; X.Y.postN
-# once a vX.Y tag ever exists). "no-local-version" keeps the version PyPI-upload
-# safe. These forms are also valid Debian versions verbatim.
+# Rolling release: the version is derived from git (`git describe`), never
+# hand-edited. vX.Y tags (v0.0 on the root commit per the repo-setup guidance,
+# v0.1 when the CI-gated release pipeline landed on 2026-08-22) are the only
+# human input; every commit after a tag increments the distance, so post-release
+# versioning yields a real, monotonic version: X.Y at the tag, X.Y.postN N
+# commits later. (Before any tag existed the fallback was 0.0.post<commit
+# count>, which reached 0.0.post405 on PyPI -- v0.1 was chosen to sort ABOVE
+# that, since re-counting from a root tag would have re-issued 0.0.post404/405.)
+# "no-local-version" keeps the version PyPI-upload safe. These forms are also
+# valid Debian versions verbatim; packaging/deb-version.py applies the same rule.
 [tool.hatch.version]
 source = "vcs"
 

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/src/netgear_switch/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.post405'
-__version_tuple__ = version_tuple = (0, 0, 'post405')
+__version__ = version = '0.1.post4'
+__version_tuple__ = version_tuple = (0, 1, 'post4')
 
 __commit_id__ = commit_id = None

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/src/netgear_switch/mcp/server.py

@@ -37,6 +37,8 @@ from ..models import PortSpeed, VlanMode
 from ..registry import Backend
 
 if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
     from ..sync_api import SyncSwitch
 
 _WRITE_ENV = "NGSW_MCP_ALLOW_WRITES"
@@ -168,13 +170,28 @@ def list_inventory_switches(
     ]
 
 
-def build_server(env: dict[str, str] | None = None):  # type: ignore[no-untyped-def]
+def build_server(  # type: ignore[no-untyped-def]
+    env: dict[str, str] | None = None,
+    *,
+    host: str | None = None,
+    port: int | None = None,
+):
     """Construct the FastMCP server. Write tools are registered only when
-    ``$NGSW_MCP_ALLOW_WRITES`` is set (see module docstring)."""
+    ``$NGSW_MCP_ALLOW_WRITES`` is set (see module docstring).
+
+    ``host``/``port`` are the bind address for the HTTP transport (see
+    :func:`main`); they are passed to FastMCP only when given, so the stdio
+    default is untouched.
+    """
     from mcp.server.fastmcp import FastMCP
 
     env = env if env is not None else dict(os.environ)
-    mcp = FastMCP("netgear-switch")
+    bind: dict[str, Any] = {}
+    if host is not None:
+        bind["host"] = host
+    if port is not None:
+        bind["port"] = port
+    mcp = FastMCP("netgear-switch", **bind)
 
     def resolver(
         switch: str | None,
@@ -811,9 +828,71 @@ def _register_write_tools(mcp, resolver) -> None:  # type: ignore[no-untyped-def
         )
 
 
-def main() -> None:
-    """Entry point (``ngsw-mcp``): run the server over stdio."""
-    build_server().run()
+_TRANSPORTS = ("stdio", "streamable-http")
+_TRANSPORT_ENV = "NGSW_MCP_TRANSPORT"
+_HOST_ENV = "NGSW_MCP_HOST"
+_PORT_ENV = "NGSW_MCP_PORT"
+
+
+def _parse_args(
+    argv: Sequence[str] | None, env: Mapping[str, str]
+) -> argparse.Namespace:
+    """``ngsw-mcp`` options. Flag > ``$NGSW_MCP_*`` environment > default.
+
+    The environment tier exists for service managers: a systemd unit sets
+    ``Environment=NGSW_MCP_TRANSPORT=streamable-http`` once and the ExecStart
+    stays a bare ``ngsw-mcp``. Defaults are strings so argparse applies the
+    same ``choices``/``type`` validation to an env value as to a flag -- a
+    bad ``$NGSW_MCP_PORT`` is rejected up front, not at bind time.
+    """
+    ap = argparse.ArgumentParser(
+        prog="ngsw-mcp",
+        description=(
+            "MCP server over the python-netgear-switch-library read/write API. "
+            "stdio (default) serves one client on stdin/stdout; streamable-http "
+            "listens on --host:--port for any number of clients."
+        ),
+    )
+    ap.add_argument(
+        "--transport",
+        choices=_TRANSPORTS,
+        default=env.get(_TRANSPORT_ENV, "stdio"),
+        help=f"MCP transport (default: ${_TRANSPORT_ENV} or stdio)",
+    )
+    ap.add_argument(
+        "--host",
+        default=env.get(_HOST_ENV),
+        help=f"bind address for streamable-http (default: ${_HOST_ENV}, "
+        "else FastMCP's 127.0.0.1)",
+    )
+    ap.add_argument(
+        "--port",
+        type=int,
+        default=env.get(_PORT_ENV),
+        help=f"TCP port for streamable-http (default: ${_PORT_ENV}, "
+        "else FastMCP's 8000)",
+    )
+    args = ap.parse_args(argv)
+    # argparse validates `choices` only for values given on the command line,
+    # not for a default -- so an env-supplied transport is checked by hand.
+    if args.transport not in _TRANSPORTS:
+        ap.error(
+            f"argument --transport (from ${_TRANSPORT_ENV}): invalid choice: "
+            f"{args.transport!r} (choose from {', '.join(_TRANSPORTS)})"
+        )
+    return args
+
+
+def main(
+    argv: Sequence[str] | None = None, env: Mapping[str, str] | None = None
+) -> None:
+    """Entry point (``ngsw-mcp``): build the server and run it over the chosen
+    transport -- stdio by default, or streamable-http on ``--host``/``--port``
+    for a shared, long-lived server (e.g. systemd socket activation)."""
+    env = env if env is not None else dict(os.environ)
+    args = _parse_args(argv, env)
+    server = build_server(dict(env), host=args.host, port=args.port)
+    server.run(transport=args.transport)
 
 
 if __name__ == "__main__":

{python_netgear_switch_library-0.0.post405 → python_netgear_switch_library-0.1.post4}/tests/test_deb_version.py

@@ -6,11 +6,14 @@ container with no third-party packages installed), so these tests drive it
 via ``subprocess`` under plain ``python3`` rather than importing it -- that
 also proves it truly needs nothing beyond the standard library.
 
-The commit count grows every time this repo gets a new commit, so nothing
-here hard-codes today's ``post<N>`` value; each assertion recomputes the
-expected value from ``git`` at test time, mirroring the derivation logic
-itself (see the brief's own verification: ``0.0.post$(git rev-list --count
-HEAD)``).
+The version changes every time this repo gets a commit or a tag, so nothing
+here hard-codes today's value; each assertion recomputes the expected value
+from ``git`` at test time. The live-repo check deliberately uses DIFFERENT git
+commands from the script (``describe --abbrev=0`` + ``rev-list --count
+TAG..HEAD`` versus the script's ``describe --long`` regex) so the two can
+disagree if either is wrong. The tagless fallback (``0.0.post<count>``) is
+exercised in a throwaway repo: the live repo has been tagged since v0.0/v0.1
+on 2026-08-22, so it no longer takes that path.
 """
 
 from __future__ import annotations
@@ -116,12 +119,37 @@ def test_only_stdlib_imports():
     assert seen <= stdlib_allow, f"non-stdlib imports found: {seen - stdlib_allow}"
 
 
-def test_version_matches_commit_count_fallback():
-    """No tags exist upstream, so the fallback path (0.0.post<count>) is live."""
-    expected = f"0.0.post{_git('rev-list', '--count', 'HEAD')}"
+def test_live_repo_version_matches_git_describe():
+    """The real checkout: X.Y at the nearest vX.Y tag, X.Y.postN N commits on.
+
+    Expected value is derived independently of the script: the nearest tag via
+    ``describe --abbrev=0`` and the distance via ``rev-list --count TAG..HEAD``
+    (the script parses ``describe --long`` instead). This broke on 2026-08-22
+    when v0.1 was pushed and the old assertion still expected the tagless
+    ``0.0.post<count>`` fallback -- CI went red and, correctly, nothing was
+    published for that commit.
+    """
+    tag = _git("describe", "--tags", "--abbrev=0", "--match", "v[0-9]*")
+    assert tag.startswith("v"), tag
+    base = tag[1:]
+    distance = int(_git("rev-list", "--count", f"{tag}..HEAD"))
+    expected = base if distance == 0 else f"{base}.post{distance}"
     assert _run() == expected
 
 
+def test_commit_count_fallback_in_tagless_repo(tmp_path):
+    """With no vX.Y tag at all the version is 0.0.post<commit count>.
+
+    The live repo left this path when it was tagged, so exercise it in a
+    throwaway repo: three commits, no tags -> 0.0.post3.
+    """
+    repo = tmp_path / "tagless-repo"
+    _init_repo(repo)
+    for i in range(3):
+        _commit(repo, f"commit {i}")
+    assert _run_in_repo(repo).stdout.strip() == "0.0.post3"
+
+
 def test_version_is_a_valid_debian_version_string():
     printed = _run()
     assert _DEBIAN_VERSION_RE.match(printed), printed
@@ -159,9 +187,10 @@ def test_write_changelog_produces_parseable_debian_changelog(tmp_path):
 def test_version_tag_based_path(tmp_path):
     """vX.Y -> X.Y at the tag; X.Y.postN with N commits after it.
 
-    The live upstream repo has no tags, so this path (the ``git describe``
-    branch of ``version()``) has no coverage from the other tests above --
-    exercise it directly against a throwaway repo instead.
+    This is the path the live upstream repo takes since v0.0 (root commit) and
+    v0.1 (2026-08-22) were tagged; the live-repo test above checks it against
+    the real checkout, this one pins the exact arithmetic on a throwaway
+    repo whose tag and distance are fully controlled.
     """
     repo = tmp_path / "tag-repo"
     _init_repo(repo)