stinger-python-utils 0.1.7__tar.gz → 0.1.8rc2__tar.gz

{stinger_python_utils-0.1.7 → stinger_python_utils-0.1.8rc2}/PKG-INFO

@@ -1,12 +1,16 @@
 Metadata-Version: 2.4
 Name: stinger-python-utils
-Version: 0.1.7
+Version: 0.1.8rc2
 Summary: Common utilities for Stinger Python services.
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.7
 Requires-Dist: pydantic>=2.5.3
 Requires-Dist: pyqttier>=0.2.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Requires-Dist: stevedore>=5.0; extra == 'mcp'
+Requires-Dist: uvicorn>=0.20.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # stinger-python-utils

{stinger_python_utils-0.1.7 → stinger_python_utils-0.1.8rc2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stinger-python-utils"
-version = "0.1.7"
+version = "0.1.8rc2"
 description = "Common utilities for Stinger Python services."
 readme = "README.md"
 license = "MIT"
@@ -14,6 +14,16 @@ dependencies = [
     "pyqttier>=0.2.0",
 ]
 
+[project.optional-dependencies]
+mcp = [
+    "mcp>=1.0.0",
+    "stevedore>=5.0",
+    "uvicorn>=0.20.0",
+]
+
+[project.scripts]
+stinger-mcp-server = "stinger_python_utils.mcp.__main__:main"
+
 [tool.uv]
 managed = true
 

stinger_python_utils-0.1.8rc2/src/stinger_python_utils/mcp/__init__.py

@@ -0,0 +1,20 @@
+"""Stinger MCP server – plugin-based MCP interface to stinger-ipc services.
+
+Public API re-exported here for convenience::
+
+    from stinger_python_utils.mcp import StingerMCPPlugin, SignalDefinition, ...
+"""
+
+from .plugin import (
+    MethodDefinition,
+    PropertyDefinition,
+    SignalDefinition,
+    StingerMCPPlugin,
+)
+
+__all__ = [
+    "MethodDefinition",
+    "PropertyDefinition",
+    "SignalDefinition",
+    "StingerMCPPlugin",
+]

stinger_python_utils-0.1.8rc2/src/stinger_python_utils/mcp/__main__.py

@@ -0,0 +1,56 @@
+"""Entry-point for ``python -m stinger_python_utils.mcp``."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="stinger-mcp-server",
+        description="Stinger MCP Server – expose stinger-ipc services over MCP",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse"],
+        default="stdio",
+        help="MCP transport to use (default: stdio)",
+    )
+    parser.add_argument(
+        "--host",
+        default="0.0.0.0",
+        help="Bind address for SSE transport (default: 0.0.0.0)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Port for SSE transport (default: 8000)",
+    )
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        help="Logging level (default: INFO)",
+    )
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        level=getattr(logging, args.log_level),
+        format="%(asctime)s  %(levelname)-8s  %(name)s  %(message)s",
+    )
+
+    from .server import StingerMCPServer
+
+    server = StingerMCPServer()
+
+    if args.transport == "stdio":
+        asyncio.run(server.run_stdio())
+    elif args.transport == "sse":
+        asyncio.run(server.run_sse(host=args.host, port=args.port))
+
+
+if __name__ == "__main__":
+    main()

stinger_python_utils-0.1.8rc2/src/stinger_python_utils/mcp/plugin.py

@@ -0,0 +1,214 @@
+"""ABC interface and data models for stinger MCP plugins.
+
+Third-party packages implement :class:`StingerMCPPlugin` and register it
+as a stevedore entry-point under the
+``stinger_python_utils.mcp_plugins`` namespace.
+
+Example ``pyproject.toml`` of a *plugin* package::
+
+    [project.entry-points."stinger_python_utils.mcp_plugins"]
+    my_service = "my_package.mcp_plugin:MyServicePlugin"
+"""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# ------------------------------------------------------------------
+# Data models
+# ------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SignalDefinition:
+    """Describes a signal emitted by a stinger-ipc client.
+
+    The MCP server calls ``client.receive_{name}(callback)`` and stores
+    received payloads in a per-instance mailbox exposed as an MCP
+    resource.
+    """
+
+    name: str
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class PropertyDefinition:
+    """Describes a property on a stinger-ipc client.
+
+    Every property is exposed as an MCP **resource**.  Writable
+    properties (``readonly=False``) additionally get an MCP **tool**
+    whose ``inputSchema`` is *schema*.
+
+    *schema* must be a valid `JSON Schema`_ object.
+
+    .. _JSON Schema: https://json-schema.org/
+    """
+
+    name: str
+    schema: dict[str, Any] = field(
+        default_factory=lambda: {
+            "type": "object",
+            "properties": {"value": {}},
+            "required": ["value"],
+        }
+    )
+    readonly: bool = True
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class MethodDefinition:
+    """Describes a callable method on a stinger-ipc client.
+
+    Each method is exposed as an MCP **tool** whose ``inputSchema`` is
+    *arguments_schema*.
+
+    *arguments_schema* must be a valid `JSON Schema`_ of type
+    ``"object"``.  The property names **must** match the keyword
+    argument names accepted by the client method.
+
+    .. _JSON Schema: https://json-schema.org/
+    """
+
+    name: str
+    arguments_schema: dict[str, Any] = field(
+        default_factory=lambda: {"type": "object"}
+    )
+    description: str = ""
+
+
+# ------------------------------------------------------------------
+# Plugin ABC
+# ------------------------------------------------------------------
+
+
+class StingerMCPPlugin(ABC):
+    """ABC that stevedore plugins must implement.
+
+    Register concrete subclasses as entry-points under the namespace
+    ``stinger_python_utils.mcp_plugins``::
+
+        # pyproject.toml of the *plugin* package
+        [project.entry-points."stinger_python_utils.mcp_plugins"]
+        my_service = "my_package.plugin:MyPlugin"
+
+    The MCP server loads all registered plugins at startup and:
+
+    1. Instantiates the **discoverer** (from :meth:`get_discovery_class`)
+       with a shared ``pyqttier`` ``IBrokerConnection``.
+    2. On each discovered instance, instantiates the **client** (from
+       :meth:`get_client_class`) with ``(connection, discovered_instance)``.
+    3. Wires signals, properties, and methods into the MCP protocol.
+    """
+
+    # ------------------------------------------------------------------
+    # Required – every plugin must implement these
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def get_plugin_name(self) -> str:
+        """Return a unique, short identifier for this plugin.
+
+        Used as the scheme/prefix in MCP resource URIs and tool names
+        (e.g. ``"lights"`` → ``lights://instance123/property/brightness``).
+        """
+        ...
+
+    @abstractmethod
+    def get_discovery_class(self) -> type:
+        """Return the *Discoverer* class for this service type.
+
+        The MCP server instantiates it as::
+
+            discoverer = DiscovererClass(connection)
+
+        The class **must** expose:
+
+        * ``add_discovered_service_callback(cb)`` – *cb* receives a
+          ``DiscoveredInstance`` (opaque pydantic model with at minimum
+          an ``instance_id: str`` attribute).
+        * ``add_removed_service_callback(cb)`` – *cb* receives the
+          ``instance_id: str`` of the departed instance.
+        """
+        ...
+
+    @abstractmethod
+    def get_client_class(self) -> type:
+        """Return the *Client* class for this service type.
+
+        The MCP server instantiates it as::
+
+            client = ClientClass(connection, discovered_instance)
+        """
+        ...
+
+    @abstractmethod
+    def get_signals(self) -> list[SignalDefinition]:
+        """Return the list of signals the client can emit."""
+        ...
+
+    @abstractmethod
+    def get_properties(self) -> list[PropertyDefinition]:
+        """Return the list of properties the client exposes."""
+        ...
+
+    @abstractmethod
+    def get_methods(self) -> list[MethodDefinition]:
+        """Return the list of callable methods the client exposes."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Defaults – override for non-standard behaviour
+    # ------------------------------------------------------------------
+
+    def read_property(self, client: Any, prop_name: str) -> Any:
+        """Read a property value from *client*.
+
+        The default implementation returns ``getattr(client, prop_name)``.
+        """
+        return getattr(client, prop_name)
+
+    def write_property(
+        self, client: Any, prop_name: str, arguments: dict[str, Any]
+    ) -> None:
+        """Set a property on *client* from MCP tool *arguments*.
+
+        *arguments* is the dict parsed from the tool's JSON Schema
+        input.  The default implementation does::
+
+            setattr(client, prop_name, arguments["value"])
+
+        Override when the property value is a composite type that must
+        be reconstructed from several arguments.
+        """
+        setattr(client, prop_name, arguments["value"])
+
+    def call_method(
+        self, client: Any, method_name: str, arguments: dict[str, Any]
+    ) -> Any:
+        """Invoke *method_name* on *client* with *arguments*.
+
+        The default implementation calls::
+
+            getattr(client, method_name)(**arguments)
+
+        and returns whatever the method returns (typically a
+        ``concurrent.futures.Future``).
+        """
+        method = getattr(client, f"call_{method_name}")
+        return method(**arguments)
+
+    def serialize_property(self, prop_name: str, value: Any) -> str:
+        """Serialize a property *value* to a JSON string for the MCP resource.
+
+        The default implementation handles pydantic ``BaseModel``
+        instances and falls back to :func:`json.dumps`.
+        """
+        if hasattr(value, "model_dump_json"):
+            return value.model_dump_json()
+        return json.dumps(value, default=str)

stinger_python_utils-0.1.8rc2/src/stinger_python_utils/mcp/server.py

@@ -0,0 +1,557 @@
+"""MCP server that dynamically exposes stinger-ipc services via plugins.
+
+Plugins are discovered through stevedore entry-points registered under
+the ``stinger_python_utils.mcp_plugins`` namespace.  Each plugin
+supplies a discoverer, a client class, and metadata describing signals,
+properties, and methods.  As service instances appear and disappear on
+the MQTT bus the MCP tool and resource lists are updated accordingly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import re
+import threading
+import uuid
+from collections import deque
+from concurrent.futures import Future
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from urllib.parse import urlparse
+
+import mcp.server.stdio
+import mcp.types as types
+from mcp.server.lowlevel import NotificationOptions, Server
+from mcp.server.models import InitializationOptions
+from pydantic import AnyUrl
+from pyqttier.connection import Mqtt5Connection
+from pyqttier.transport import MqttTransport, MqttTransportType
+from stevedore import ExtensionManager
+
+from .plugin import (
+    MethodDefinition,
+    PropertyDefinition,
+    SignalDefinition,
+    StingerMCPPlugin,
+)
+
+logger = logging.getLogger(__name__)
+
+# ------------------------------------------------------------------
+# Internal data structures
+# ------------------------------------------------------------------
+
+SIGNAL_MAILBOX_SIZE = 10
+
+
+@dataclass
+class SignalMailbox:
+    """Bounded FIFO of the most recent signal payloads."""
+
+    _entries: deque[dict[str, Any]] = field(
+        default_factory=lambda: deque(maxlen=SIGNAL_MAILBOX_SIZE)
+    )
+
+    def append(self, data: dict[str, Any]) -> None:
+        self._entries.append(
+            {
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "data": data,
+            }
+        )
+
+    def to_json(self) -> str:
+        return json.dumps(list(self._entries), default=str)
+
+
+@dataclass
+class InstanceState:
+    """Run-time bookkeeping for one discovered service instance."""
+
+    plugin_name: str
+    plugin: StingerMCPPlugin
+    instance_id: str
+    client: Any
+    signal_mailboxes: dict[str, SignalMailbox] = field(default_factory=dict)
+    property_cache: dict[str, Any] = field(default_factory=dict)
+
+
+# ------------------------------------------------------------------
+# Helpers
+# ------------------------------------------------------------------
+
+
+def _sanitize(value: str) -> str:
+    """Turn an arbitrary string into a safe MCP identifier fragment."""
+    return re.sub(r"[^A-Za-z0-9_]", "_", value)
+
+
+def _instance_key(plugin_name: str, instance_id: str) -> str:
+    return f"{_sanitize(plugin_name)}_{_sanitize(instance_id)}"
+
+
+async def _resolve_future(future: Future[Any], timeout: float = 30.0) -> Any:
+    """Bridge a :class:`concurrent.futures.Future` into *asyncio*."""
+    return await asyncio.wait_for(asyncio.wrap_future(future), timeout=timeout)
+
+
+# ------------------------------------------------------------------
+# MQTT connection factory
+# ------------------------------------------------------------------
+
+
+def create_mqtt_connection() -> Mqtt5Connection:
+    """Create an :class:`Mqtt5Connection` from environment variables.
+
+    ==================  ===========  ===============================
+    Variable            Default      Description
+    ==================  ===========  ===============================
+    ``MQTT_HOST``       localhost    Broker hostname
+    ``MQTT_PORT``       1883         Broker port
+    ``MQTT_TRANSPORT``  tcp          ``tcp`` | ``websocket`` | ``unix``
+    ``MQTT_CLIENT_ID``  (random)     MQTT client identifier
+    ==================  ===========  ===============================
+    """
+    host = os.environ.get("MQTT_HOST", "localhost")
+    port = int(os.environ.get("MQTT_PORT", "1883"))
+    transport_str = os.environ.get("MQTT_TRANSPORT", "tcp").upper()
+    transport_type = getattr(MqttTransportType, transport_str, MqttTransportType.TCP)
+    client_id = os.environ.get(
+        "MQTT_CLIENT_ID", f"stinger-mcp-{uuid.uuid4().hex[:8]}"
+    )
+
+    transport = MqttTransport(transport_type, host=host, port=port)
+    return Mqtt5Connection(transport=transport, client_id=client_id)
+
+
+# ------------------------------------------------------------------
+# The server
+# ------------------------------------------------------------------
+
+
+class StingerMCPServer:
+    """Loads stevedore plugins and serves them over MCP."""
+
+    STEVEDORE_NAMESPACE = "stinger_python_utils.mcp_plugins"
+
+    def __init__(self) -> None:
+        self._server = Server("stinger-mcp")
+        self._plugins: list[StingerMCPPlugin] = []
+        self._instances: dict[str, InstanceState] = {}
+        self._lock = threading.Lock()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._connection: Mqtt5Connection | None = None
+
+        self._register_handlers()
+
+    # ==================================================================
+    # MCP handler registration
+    # ==================================================================
+
+    def _register_handlers(self) -> None:
+        server = self._server
+
+        @server.list_tools()
+        async def handle_list_tools() -> list[types.Tool]:
+            return self._build_tool_list()
+
+        @server.call_tool()
+        async def handle_call_tool(
+            name: str, arguments: dict[str, Any] | None
+        ) -> list[types.TextContent]:
+            return await self._dispatch_tool(name, arguments or {})
+
+        @server.list_resources()
+        async def handle_list_resources() -> list[types.Resource]:
+            return self._build_resource_list()
+
+        @server.read_resource()
+        async def handle_read_resource(uri: AnyUrl) -> str:
+            return self._read_resource(uri)
+
+    # ==================================================================
+    # Tools
+    # ==================================================================
+
+    def _build_tool_list(self) -> list[types.Tool]:
+        tools: list[types.Tool] = []
+        with self._lock:
+            for state in self._instances.values():
+                pn = _sanitize(state.plugin_name)
+                iid = _sanitize(state.instance_id)
+
+                for mdef in state.plugin.get_methods():
+                    tools.append(
+                        types.Tool(
+                            name=f"{pn}_{iid}_{_sanitize(mdef.name)}",
+                            description=(
+                                mdef.description
+                                or f"Call {mdef.name} on {state.plugin_name} "
+                                f"instance {state.instance_id}"
+                            ),
+                            inputSchema=mdef.arguments_schema,
+                        )
+                    )
+
+                for pdef in state.plugin.get_properties():
+                    if not pdef.readonly:
+                        tools.append(
+                            types.Tool(
+                                name=f"{pn}_{iid}_set_{_sanitize(pdef.name)}",
+                                description=(
+                                    pdef.description
+                                    or f"Set {pdef.name} on {state.plugin_name} "
+                                    f"instance {state.instance_id}"
+                                ),
+                                inputSchema=pdef.schema,
+                            )
+                        )
+        return tools
+
+    def _resolve_tool(
+        self, name: str
+    ) -> tuple[InstanceState, str, str] | None:
+        """Map a tool *name* → ``(state, kind, item_name)``.
+
+        *kind* is ``"method"`` or ``"property"``.  Methods are checked
+        first so that a method named ``set_foo`` takes precedence over
+        a property setter for ``foo``.
+        """
+        with self._lock:
+            for state in self._instances.values():
+                pn = _sanitize(state.plugin_name)
+                iid = _sanitize(state.instance_id)
+                prefix = f"{pn}_{iid}_"
+
+                if not name.startswith(prefix):
+                    continue
+
+                remainder = name[len(prefix) :]
+
+                # Methods take priority
+                for mdef in state.plugin.get_methods():
+                    if _sanitize(mdef.name) == remainder:
+                        return state, "method", mdef.name
+
+                # Property setters: set_<prop_name>
+                if remainder.startswith("set_"):
+                    prop_token = remainder[4:]
+                    for pdef in state.plugin.get_properties():
+                        if (
+                            _sanitize(pdef.name) == prop_token
+                            and not pdef.readonly
+                        ):
+                            return state, "property", pdef.name
+
+        return None
+
+    async def _dispatch_tool(
+        self, name: str, arguments: dict[str, Any]
+    ) -> list[types.TextContent]:
+        target = self._resolve_tool(name)
+        if target is None:
+            raise ValueError(f"Unknown tool: {name}")
+
+        state, kind, item_name = target
+
+        if kind == "property":
+            try:
+                state.plugin.write_property(state.client, item_name, arguments)
+                text = json.dumps({"status": "ok", "property": item_name})
+            except Exception as exc:
+                logger.exception("Error setting property %s", item_name)
+                text = json.dumps(
+                    {"status": "error", "error": str(exc)}, default=str
+                )
+            return [types.TextContent(type="text", text=text)]
+
+        # kind == "method"
+        try:
+            result = state.plugin.call_method(
+                state.client, item_name, arguments
+            )
+            if isinstance(result, Future):
+                result = await _resolve_future(result)
+
+            if hasattr(result, "model_dump_json"):
+                text = result.model_dump_json()
+            elif result is None:
+                text = json.dumps({"status": "ok"})
+            else:
+                text = json.dumps(result, default=str)
+        except Exception as exc:
+            logger.exception("Error calling method %s", item_name)
+            text = json.dumps(
+                {"status": "error", "error": str(exc)}, default=str
+            )
+
+        return [types.TextContent(type="text", text=text)]
+
+    # ==================================================================
+    # Resources
+    # ==================================================================
+
+    def _build_resource_list(self) -> list[types.Resource]:
+        resources: list[types.Resource] = []
+        with self._lock:
+            for state in self._instances.values():
+                pn = state.plugin_name
+                iid = state.instance_id
+
+                for pdef in state.plugin.get_properties():
+                    resources.append(
+                        types.Resource(
+                            uri=AnyUrl(f"{pn}://{iid}/property/{pdef.name}"),
+                            name=f"{pn} {iid} – {pdef.name}",
+                            description=pdef.description
+                            or f"Property {pdef.name}",
+                            mimeType="application/json",
+                        )
+                    )
+
+                for sdef in state.plugin.get_signals():
+                    resources.append(
+                        types.Resource(
+                            uri=AnyUrl(f"{pn}://{iid}/signal/{sdef.name}"),
+                            name=f"{pn} {iid} – {sdef.name} (signals)",
+                            description=sdef.description
+                            or f"Mailbox of the last {SIGNAL_MAILBOX_SIZE} "
+                            f"'{sdef.name}' signals",
+                            mimeType="application/json",
+                        )
+                    )
+        return resources
+
+    def _read_resource(self, uri: AnyUrl) -> str:
+        parsed = urlparse(str(uri))
+        plugin_name = parsed.scheme
+        instance_id = parsed.netloc
+        path_parts = [p for p in parsed.path.strip("/").split("/") if p]
+
+        if len(path_parts) < 2:
+            raise ValueError(f"Invalid resource URI: {uri}")
+
+        category, item_name = path_parts[0], path_parts[1]
+        key = _instance_key(plugin_name, instance_id)
+
+        with self._lock:
+            state = self._instances.get(key)
+
+        if state is None:
+            raise ValueError(
+                f"No active instance for {plugin_name}/{instance_id}"
+            )
+
+        if category == "property":
+            value = state.plugin.read_property(state.client, item_name)
+            return state.plugin.serialize_property(item_name, value)
+
+        if category == "signal":
+            mailbox = state.signal_mailboxes.get(item_name)
+            if mailbox is None:
+                return "[]"
+            return mailbox.to_json()
+
+        raise ValueError(f"Unknown resource category: {category}")
+
+    # ==================================================================
+    # Plugin loading & discovery wiring
+    # ==================================================================
+
+    def _load_plugins(self) -> None:
+        def _on_failure(
+            _mgr: ExtensionManager, entrypoint: Any, err: Exception
+        ) -> None:
+            logger.error("Failed to load plugin %s: %s", entrypoint, err)
+
+        mgr = ExtensionManager(
+            namespace=self.STEVEDORE_NAMESPACE,
+            invoke_on_load=True,
+            on_load_failure_callback=_on_failure,
+        )
+        for ext in mgr:
+            plugin = ext.obj
+            if isinstance(plugin, StingerMCPPlugin):
+                self._plugins.append(plugin)
+                logger.info(
+                    "Loaded MCP plugin: %s", plugin.get_plugin_name()
+                )
+            else:
+                logger.warning(
+                    "Entry-point %s did not produce a StingerMCPPlugin "
+                    "(got %s); skipping.",
+                    ext.name,
+                    type(plugin).__name__,
+                )
+
+    def _start_discovery(self) -> None:
+        assert self._connection is not None
+        for plugin in self._plugins:
+            discoverer_cls = plugin.get_discovery_class()
+            discoverer = discoverer_cls(self._connection)
+
+            discoverer.add_discovered_service_callback(
+                lambda inst, _p=plugin: self._on_discovered(inst, _p)
+            )
+            discoverer.add_removed_service_callback(
+                lambda iid, _p=plugin: self._on_removed(iid, _p)
+            )
+            logger.info(
+                "Discovery started for plugin '%s'",
+                plugin.get_plugin_name(),
+            )
+
+    # ---- callbacks (called on the MQTT thread) -----------------------
+
+    def _on_discovered(
+        self, discovered_instance: Any, plugin: StingerMCPPlugin
+    ) -> None:
+        """Register a newly-discovered service instance."""
+        plugin_name = plugin.get_plugin_name()
+        instance_id: str = discovered_instance.instance_id
+        key = _instance_key(plugin_name, instance_id)
+
+        with self._lock:
+            if key in self._instances:
+                logger.debug(
+                    "Instance %s/%s already tracked; ignoring.",
+                    plugin_name,
+                    instance_id,
+                )
+                return
+
+        logger.info("Discovered %s / %s", plugin_name, instance_id)
+
+        client_cls = plugin.get_client_class()
+        client = client_cls(self._connection, discovered_instance)
+
+        state = InstanceState(
+            plugin_name=plugin_name,
+            plugin=plugin,
+            instance_id=instance_id,
+            client=client,
+        )
+
+        # -- signals ---------------------------------------------------
+        for sdef in plugin.get_signals():
+            mailbox = SignalMailbox()
+            state.signal_mailboxes[sdef.name] = mailbox
+
+            recv_fn = getattr(client, f"receive_{sdef.name}", None)
+            if recv_fn is not None:
+
+                def _make_signal_cb(mb: SignalMailbox) -> Any:
+                    def _cb(**kwargs: Any) -> None:
+                        mb.append(kwargs)
+
+                    return _cb
+
+                recv_fn(_make_signal_cb(mailbox))
+
+        # -- properties ------------------------------------------------
+        for pdef in plugin.get_properties():
+            try:
+                state.property_cache[pdef.name] = plugin.read_property(
+                    client, pdef.name
+                )
+            except Exception:
+                state.property_cache[pdef.name] = None
+
+            changed_fn = getattr(client, f"{pdef.name}_changed", None)
+            if changed_fn is not None:
+
+                def _make_prop_cb(
+                    _state: InstanceState, _pname: str
+                ) -> Any:
+                    def _cb(value: Any = None, **kwargs: Any) -> None:
+                        _state.property_cache[_pname] = value
+
+                    return _cb
+
+                changed_fn(_make_prop_cb(state, pdef.name))
+
+        with self._lock:
+            self._instances[key] = state
+
+    def _on_removed(
+        self, instance_id: str, plugin: StingerMCPPlugin
+    ) -> None:
+        """Deregister a departed service instance."""
+        plugin_name = plugin.get_plugin_name()
+        key = _instance_key(plugin_name, instance_id)
+
+        logger.info("Removed %s / %s", plugin_name, instance_id)
+        with self._lock:
+            self._instances.pop(key, None)
+
+    # ==================================================================
+    # Transports
+    # ==================================================================
+
+    def _init_options(self) -> InitializationOptions:
+        return InitializationOptions(
+            server_name="stinger-mcp",
+            server_version="0.1.0",
+            capabilities=self._server.get_capabilities(
+                notification_options=NotificationOptions(),
+                experimental_capabilities={},
+            ),
+        )
+
+    async def run_stdio(self) -> None:
+        """Run the MCP server over the *stdio* transport."""
+        self._loop = asyncio.get_running_loop()
+        self._connection = create_mqtt_connection()
+        self._load_plugins()
+        self._start_discovery()
+
+        try:
+            async with mcp.server.stdio.stdio_server() as (read, write):
+                await self._server.run(read, write, self._init_options())
+        finally:
+            if self._connection is not None:
+                logger.info("Shutting down MQTT connection")
+
+    async def run_sse(
+        self, host: str = "0.0.0.0", port: int = 8000
+    ) -> None:
+        """Run the MCP server over the *SSE* transport."""
+        try:
+            from mcp.server.sse import SseServerTransport
+            from starlette.applications import Starlette
+            from starlette.requests import Request
+            from starlette.routing import Mount, Route
+            import uvicorn
+        except ImportError as exc:
+            raise RuntimeError(
+                "SSE transport requires additional packages. "
+                "Install with:  pip install 'stinger-python-utils[mcp]'"
+            ) from exc
+
+        self._loop = asyncio.get_running_loop()
+        self._connection = create_mqtt_connection()
+        self._load_plugins()
+        self._start_discovery()
+
+        sse = SseServerTransport("/messages/")
+
+        async def handle_sse(request: Request) -> None:
+            async with sse.connect_sse(
+                request.scope, request.receive, request._send
+            ) as (read, write):
+                await self._server.run(read, write, self._init_options())
+
+        app = Starlette(
+            routes=[
+                Route("/sse", endpoint=handle_sse),
+                Mount("/messages/", app=sse.handle_post_message),
+            ],
+        )
+
+        config = uvicorn.Config(app, host=host, port=port)
+        server = uvicorn.Server(config)
+        await server.serve()

{stinger_python_utils-0.1.7 → stinger_python_utils-0.1.8rc2}/uv.lock

@@ -1272,7 +1272,7 @@ wheels = [
 
 [[package]]
 name = "stinger-python-utils"
-version = "0.1.7"
+version = "0.1.6"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic", version = "2.5.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.8'" },