python-netgear-switch-library 0.1.post2__tar.gz → 0.1.post4__tar.gz

{python_netgear_switch_library-0.1.post2 → python_netgear_switch_library-0.1.post4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-netgear-switch-library
-Version: 0.1.post2
+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

{python_netgear_switch_library-0.1.post2 → 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.1.post2 → 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.1.post2 → 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.1.post2'
-__version_tuple__ = version_tuple = (0, 1, 'post2')
+__version__ = version = '0.1.post4'
+__version_tuple__ = version_tuple = (0, 1, 'post4')
 
 __commit_id__ = commit_id = None

{python_netgear_switch_library-0.1.post2 → 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.1.post2 → python_netgear_switch_library-0.1.post4}/tests/test_mcp_server.py

@@ -443,3 +443,86 @@ def test_set_vlan_membership_rejects_bad_mode(monkeypatch) -> None:
         {"host": "h", "model": "gs110emx", "vlan": 90, "port": 1, "mode": "bogus"},
     )[0]
     assert "invalid mode" in res["error"]
+
+
+# ---------------------------------------------------------------------------
+# Entry point: transport selection (ngsw-mcp --transport / $NGSW_MCP_TRANSPORT)
+# ---------------------------------------------------------------------------
+# A shared, socket-activated ngsw-mcp (systemd --user on ten64, 2026-08-22) needs
+# the server on a local TCP port; a per-client stdio server stays the default.
+
+
+class _FakeServer:
+    def __init__(self, calls: dict[str, object]) -> None:
+        self._calls = calls
+
+    def run(self, transport: str = "stdio") -> None:
+        self._calls["transport"] = transport
+
+
+def _fake_build(calls: dict[str, object]):  # type: ignore[no-untyped-def]
+    def build(env=None, *, host=None, port=None):  # type: ignore[no-untyped-def]
+        calls["host"] = host
+        calls["port"] = port
+        return _FakeServer(calls)
+
+    return build
+
+
+def test_main_defaults_to_stdio(monkeypatch) -> None:
+    calls: dict[str, object] = {}
+    monkeypatch.setattr(mod, "build_server", _fake_build(calls))
+    mod.main([], env={})
+    assert calls == {"host": None, "port": None, "transport": "stdio"}
+
+
+def test_main_streamable_http_flags_reach_the_server(monkeypatch) -> None:
+    calls: dict[str, object] = {}
+    monkeypatch.setattr(mod, "build_server", _fake_build(calls))
+    mod.main(
+        ["--transport", "streamable-http", "--host", "127.0.0.1", "--port", "8766"],
+        env={},
+    )
+    assert calls == {
+        "host": "127.0.0.1",
+        "port": 8766,
+        "transport": "streamable-http",
+    }
+
+
+def test_main_env_supplies_defaults_and_flags_win(monkeypatch) -> None:
+    env = {
+        "NGSW_MCP_TRANSPORT": "streamable-http",
+        "NGSW_MCP_HOST": "127.0.0.1",
+        "NGSW_MCP_PORT": "9000",
+    }
+    calls: dict[str, object] = {}
+    monkeypatch.setattr(mod, "build_server", _fake_build(calls))
+    mod.main([], env=env)
+    assert calls == {"host": "127.0.0.1", "port": 9000, "transport": "streamable-http"}
+
+    calls.clear()
+    mod.main(["--port", "9001"], env=env)
+    assert calls["port"] == 9001
+    assert calls["transport"] == "streamable-http"
+
+
+@pytest.mark.parametrize(
+    ("argv", "env"),
+    [
+        (["--transport", "sse"], {}),
+        ([], {"NGSW_MCP_TRANSPORT": "carrier-pigeon"}),
+        (["--port", "not-a-port"], {}),
+        ([], {"NGSW_MCP_PORT": "8765x"}),
+    ],
+)
+def test_main_rejects_bad_transport_or_port(monkeypatch, argv, env) -> None:
+    monkeypatch.setattr(mod, "build_server", _fake_build({}))
+    with pytest.raises(SystemExit) as exc:
+        mod.main(argv, env=env)
+    assert exc.value.code != 0
+
+
+def test_build_server_applies_host_and_port() -> None:
+    srv = mod.build_server(env={}, host="127.0.0.1", port=8766)
+    assert (srv.settings.host, srv.settings.port) == ("127.0.0.1", 8766)