topicgate 1.5.2__tar.gz → 1.5.3__tar.gz

{topicgate-1.5.2/src/topicgate.egg-info → topicgate-1.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topicgate
-Version: 1.5.2
+Version: 1.5.3
 Summary: Secure local access to your MQTT topics
 License-Expression: MIT
 Project-URL: Repository, https://github.com/Dumdart/TopicGate
@@ -71,38 +71,29 @@ physical hardware, use the [Zigbee2MQTT scenario](demo/zigbee2mqtt_scenario/READ
 
 ## Get started
 
-TopicGate requires Python 3.11+ and an MQTT 5-compatible broker.
-
-1. Follow [Install TopicGate by operating system](docs/install/OS_INSTALL.md).
-2. Run `topicgate-gui`.
-3. Configure a broker profile and add a bounded filter such as `home/+/temperature` or `devices/#`.
-4. Add TopicGate to your agent host using one of the [connection guides](#connect-an-agent) below. The host launches the MCP server.
-
-The default MCP configuration is:
-
-```json
-{
-  "mcpServers": {
-    "topicgate": {
-      "command": "topicgate",
-      "args": ["--mode", "read-only"]
-    }
-  }
-}
-```
-
-If `topicgate` is not on the host's `PATH`, use the absolute executable path shown by TopicGate Desktop's MCP setup page.
+1. [Install TopicGate for your operating system](docs/install/OS_INSTALL.md).
+2. Run `topicgate-gui` to open **TopicGate Desktop**.
+3. Add a broker profile, enter its credentials locally, connect, and add a bounded subscription such as `home/+/temperature`.
+4. If you want AI access, connect your agent host using a guide below. Desktop works without an agent or MCP configuration.
+5. Keep **read-only mode**, the default for the MCP server and plugin.
+6. Only when you need agent-driven changes, explicitly [enable control mode](docs/install/CONTROL_AND_HEALTH.md) in a trusted environment.
 
 ## Connect an agent
 
-Configure a broker in TopicGate Desktop for read-only use, or use the authorized [control provisioning and health workflow](docs/install/CONTROL_AND_HEALTH.md).
+A **plugin integration** loads TopicGate's agent skills and MCP configuration.
+An **MCP-only integration** connects the MCP server without TopicGate's skills.
+Install the application first; installing a plugin does not install TopicGate or enable control mode.
 
-| Host | Guide |
+| Host | Plugin and MCP-only setup |
 | --- | --- |
 | Codex | [Codex](docs/install/CODEX.md) |
 | Claude Code | [Claude Code](docs/install/CLAUDE_CODE.md) |
-| VS Code / GitHub Copilot | [VS Code and GitHub Copilot](docs/install/VSCODE_COPILOT.md) |
 | Cursor | [Cursor](docs/install/CURSOR.md) |
+| VS Code / GitHub Copilot CLI | [VS Code and GitHub Copilot](docs/install/VSCODE_COPILOT.md) |
+
+The host normally starts the MCP server. Restart it and start a new agent session
+after changing MCP configuration. **Help → MCP setup...** in TopicGate Desktop
+provides the resolved executable, data directory, and a configuration to copy.
 
 ## Observation semantics
 
@@ -154,7 +145,7 @@ Health results distinguish **healthy**, **problem**, and **unknown**. A health w
 
 ### Let an agent configure and verify health
 
-With TopicGate 1.4+ and a control-mode server configured, try:
+With control mode explicitly enabled, try:
 
 > Create or reuse an anonymous broker named Lab at localhost:1883 without TLS. Activate it, subscribe to devices/#, and add an expectation that devices/status equals the UTF-8 value online. Wait up to 30 seconds for health and report any failed or unknown checks. Do not publish a test message.
 
@@ -171,7 +162,7 @@ See [Control mode and expectation verification](docs/install/CONTROL_AND_HEALTH.
 | Snapshots | `get_broker_snapshot`, `inspect_broker` | `observe_broker_snapshot` |
 | Brokers | `list_brokers` | `create_broker`, `activate_broker` |
 | Connection | `get_connection_status` | `connect`, `disconnect`, `reconnect` |
-| Topics | `list_topics`, `get_topic_state` | — |
+| Topics | `list_topics`, `get_topic_state`, `get_topic_history` | — |
 | Subscriptions | `list_subscriptions` | `add_subscription`, `update_subscription`, `remove_subscription` |
 | Expectations | `list_health_expectations` | `create_health_expectation`, `update_health_expectation`, `delete_health_expectation` |
 | Health | `query_failure_history` | `get_health_report`, `wait_for_broker_health` |
@@ -179,13 +170,9 @@ See [Control mode and expectation verification](docs/install/CONTROL_AND_HEALTH.
 | Publishing | — | `publish` |
 | Dashboard | — | `open_topicgate_dashboard` |
 
-Control mode includes the passive tools. Configure your trusted host to launch:
-
-```console
-topicgate --mode control
-```
+The optional dashboard also requires the `apps` package extra and a host that supports MCP apps.
 
-Restart the MCP server after changing mode. The plugin's default configuration stays read-only; shipping `.mcp-control.json` does not enable it automatically. Follow the [host setup instructions](docs/install/CONTROL_AND_HEALTH.md) to select a control entry.
+Control mode includes the passive tools. The plugin's default configuration stays read-only; shipping `.mcp-control.json` does not enable it automatically. Follow [Control mode and health](docs/install/CONTROL_AND_HEALTH.md) to configure and restart the server.
 
 For troubleshooting, use **Help → Export support bundle…** in Desktop or call
 `get_support_bundle` through MCP. Desktop payload inclusion is off by default and

{topicgate-1.5.2 → topicgate-1.5.3}/README.md

@@ -32,38 +32,29 @@ physical hardware, use the [Zigbee2MQTT scenario](demo/zigbee2mqtt_scenario/READ
 
 ## Get started
 
-TopicGate requires Python 3.11+ and an MQTT 5-compatible broker.
-
-1. Follow [Install TopicGate by operating system](docs/install/OS_INSTALL.md).
-2. Run `topicgate-gui`.
-3. Configure a broker profile and add a bounded filter such as `home/+/temperature` or `devices/#`.
-4. Add TopicGate to your agent host using one of the [connection guides](#connect-an-agent) below. The host launches the MCP server.
-
-The default MCP configuration is:
-
-```json
-{
-  "mcpServers": {
-    "topicgate": {
-      "command": "topicgate",
-      "args": ["--mode", "read-only"]
-    }
-  }
-}
-```
-
-If `topicgate` is not on the host's `PATH`, use the absolute executable path shown by TopicGate Desktop's MCP setup page.
+1. [Install TopicGate for your operating system](docs/install/OS_INSTALL.md).
+2. Run `topicgate-gui` to open **TopicGate Desktop**.
+3. Add a broker profile, enter its credentials locally, connect, and add a bounded subscription such as `home/+/temperature`.
+4. If you want AI access, connect your agent host using a guide below. Desktop works without an agent or MCP configuration.
+5. Keep **read-only mode**, the default for the MCP server and plugin.
+6. Only when you need agent-driven changes, explicitly [enable control mode](docs/install/CONTROL_AND_HEALTH.md) in a trusted environment.
 
 ## Connect an agent
 
-Configure a broker in TopicGate Desktop for read-only use, or use the authorized [control provisioning and health workflow](docs/install/CONTROL_AND_HEALTH.md).
+A **plugin integration** loads TopicGate's agent skills and MCP configuration.
+An **MCP-only integration** connects the MCP server without TopicGate's skills.
+Install the application first; installing a plugin does not install TopicGate or enable control mode.
 
-| Host | Guide |
+| Host | Plugin and MCP-only setup |
 | --- | --- |
 | Codex | [Codex](docs/install/CODEX.md) |
 | Claude Code | [Claude Code](docs/install/CLAUDE_CODE.md) |
-| VS Code / GitHub Copilot | [VS Code and GitHub Copilot](docs/install/VSCODE_COPILOT.md) |
 | Cursor | [Cursor](docs/install/CURSOR.md) |
+| VS Code / GitHub Copilot CLI | [VS Code and GitHub Copilot](docs/install/VSCODE_COPILOT.md) |
+
+The host normally starts the MCP server. Restart it and start a new agent session
+after changing MCP configuration. **Help → MCP setup...** in TopicGate Desktop
+provides the resolved executable, data directory, and a configuration to copy.
 
 ## Observation semantics
 
@@ -115,7 +106,7 @@ Health results distinguish **healthy**, **problem**, and **unknown**. A health w
 
 ### Let an agent configure and verify health
 
-With TopicGate 1.4+ and a control-mode server configured, try:
+With control mode explicitly enabled, try:
 
 > Create or reuse an anonymous broker named Lab at localhost:1883 without TLS. Activate it, subscribe to devices/#, and add an expectation that devices/status equals the UTF-8 value online. Wait up to 30 seconds for health and report any failed or unknown checks. Do not publish a test message.
 
@@ -132,7 +123,7 @@ See [Control mode and expectation verification](docs/install/CONTROL_AND_HEALTH.
 | Snapshots | `get_broker_snapshot`, `inspect_broker` | `observe_broker_snapshot` |
 | Brokers | `list_brokers` | `create_broker`, `activate_broker` |
 | Connection | `get_connection_status` | `connect`, `disconnect`, `reconnect` |
-| Topics | `list_topics`, `get_topic_state` | — |
+| Topics | `list_topics`, `get_topic_state`, `get_topic_history` | — |
 | Subscriptions | `list_subscriptions` | `add_subscription`, `update_subscription`, `remove_subscription` |
 | Expectations | `list_health_expectations` | `create_health_expectation`, `update_health_expectation`, `delete_health_expectation` |
 | Health | `query_failure_history` | `get_health_report`, `wait_for_broker_health` |
@@ -140,13 +131,9 @@ See [Control mode and expectation verification](docs/install/CONTROL_AND_HEALTH.
 | Publishing | — | `publish` |
 | Dashboard | — | `open_topicgate_dashboard` |
 
-Control mode includes the passive tools. Configure your trusted host to launch:
-
-```console
-topicgate --mode control
-```
+The optional dashboard also requires the `apps` package extra and a host that supports MCP apps.
 
-Restart the MCP server after changing mode. The plugin's default configuration stays read-only; shipping `.mcp-control.json` does not enable it automatically. Follow the [host setup instructions](docs/install/CONTROL_AND_HEALTH.md) to select a control entry.
+Control mode includes the passive tools. The plugin's default configuration stays read-only; shipping `.mcp-control.json` does not enable it automatically. Follow [Control mode and health](docs/install/CONTROL_AND_HEALTH.md) to configure and restart the server.
 
 For troubleshooting, use **Help → Export support bundle…** in Desktop or call
 `get_support_bundle` through MCP. Desktop payload inclusion is off by default and

{topicgate-1.5.2 → topicgate-1.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "topicgate"
-version = "1.5.2"
+version = "1.5.3"
 description = "Secure local access to your MQTT topics"
 readme = "README.md"
 license = "MIT"

{topicgate-1.5.2 → topicgate-1.5.3}/src/topicgate/app/app_dependencies.py

@@ -28,6 +28,7 @@ from topicgate.app.services.broker_snapshot_service import BrokerSnapshotService
 from topicgate.app.services.broker_resolver import BrokerResolver
 from topicgate.app.services.control_operation_service import ControlOperationService
 from topicgate.app.services.mcp_setup_service import McpSetupService
+from topicgate.app.services.integration_service import IntegrationService
 from topicgate.app.broker_runtime_state import BrokerRuntimeState
 from topicgate.app.services.support_bundle_export_service import (
     SupportBundleExporter,
@@ -252,6 +253,7 @@ class AppDependencies:
             active_broker_reader=self.broker_profiles.get_profile_summary,
             subscriptions_reader=self.broker_profiles.list_subscriptions,
         )
+        self.integration_service = IntegrationService(self.mcp_setup.information)
         self.support_bundle_service = SupportBundleService(
             self.runtime,
             self.snapshot_service,

topicgate-1.5.3/src/topicgate/app/integration_dependencies.py

@@ -0,0 +1,17 @@
+from pathlib import Path
+
+from topicgate.app.services.integration_service import IntegrationService
+from topicgate.app.services.mcp_setup_service import McpSetupService
+from topicgate.paths import prepare_database_path
+
+
+class IntegrationDependencies:
+    """Build integration-only dependencies without opening the TopicGate DB."""
+
+    def __init__(self, data_dir: Path | None = None) -> None:
+        database_path = prepare_database_path(data_dir)
+        information = McpSetupService.resolve_information(
+            database_path.parent,
+            database_path,
+        )
+        self.integration_service = IntegrationService(information)

topicgate-1.5.3/src/topicgate/app/models/integration.py

@@ -0,0 +1,84 @@
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class McpMode(StrEnum):
+    READ_ONLY = "read-only"
+    CONTROL = "control"
+
+
+@dataclass(frozen=True)
+class McpServerState:
+    name: str
+    command: str
+    arguments: tuple[str, ...]
+    environment: tuple[tuple[str, str], ...] = ()
+    source: str | None = None
+
+    @property
+    def mode(self) -> McpMode | None:
+        value: str | None = None
+        for index, argument in enumerate(self.arguments):
+            if argument == "--mode":
+                value = (
+                    self.arguments[index + 1]
+                    if index + 1 < len(self.arguments)
+                    else None
+                )
+            elif argument.startswith("--mode="):
+                value = argument.removeprefix("--mode=")
+        try:
+            return McpMode(value)
+        except (TypeError, ValueError):
+            return None
+
+
+@dataclass(frozen=True)
+class PlatformIntegrationState:
+    platform: str
+    available: bool
+    marketplace_configured: bool = False
+    plugin_installed: bool = False
+    plugin_version: str | None = None
+    servers: tuple[McpServerState, ...] = ()
+    issues: tuple[str, ...] = ()
+    plugin_enabled: bool | None = None
+
+
+class IntegrationActionKind(StrEnum):
+    ADD_MARKETPLACE = "add_marketplace"
+    REFRESH_MARKETPLACE = "refresh_marketplace"
+    INSTALL_PLUGIN = "install_plugin"
+    REMOVE_SERVER = "remove_server"
+    CONFIGURE_SERVER = "configure_server"
+
+
+@dataclass(frozen=True)
+class IntegrationAction:
+    kind: IntegrationActionKind
+    target: str
+
+
+@dataclass(frozen=True)
+class IntegrationSpec:
+    platform: str
+    mode: McpMode
+    package_version: str
+    server_name: str
+    command: str
+    arguments: tuple[str, ...]
+    environment: tuple[tuple[str, str], ...]
+
+
+@dataclass(frozen=True)
+class IntegrationPlan:
+    desired: IntegrationSpec
+    current: PlatformIntegrationState
+    actions: tuple[IntegrationAction, ...]
+
+
+@dataclass(frozen=True)
+class IntegrationResult:
+    state: PlatformIntegrationState
+    changed: bool
+    messages: tuple[str, ...] = ()

topicgate-1.5.3/src/topicgate/app/ports/__init__.py

@@ -0,0 +1 @@
+"""Application ports implemented by external integration adapters."""

topicgate-1.5.3/src/topicgate/app/ports/integration_platform.py

@@ -0,0 +1,21 @@
+from typing import Protocol
+
+from topicgate.app.models.integration import (
+    IntegrationPlan,
+    IntegrationResult,
+    IntegrationSpec,
+    PlatformIntegrationState,
+)
+
+
+class IntegrationPlatform(Protocol):
+    @property
+    def name(self) -> str: ...
+
+    def inspect(self) -> PlatformIntegrationState: ...
+
+    def plan(self, desired: IntegrationSpec) -> IntegrationPlan: ...
+
+    def apply(self, plan: IntegrationPlan) -> IntegrationResult: ...
+
+    def remove(self) -> IntegrationResult: ...

topicgate-1.5.3/src/topicgate/app/services/integration_service.py

@@ -0,0 +1,108 @@
+from dataclasses import replace
+
+from topicgate.app.models.integration import (
+    IntegrationActionKind,
+    IntegrationResult,
+    IntegrationSpec,
+    McpMode,
+    PlatformIntegrationState,
+)
+from topicgate.app.models.mcp_setup import McpSetupInformation
+from topicgate.app.ports.integration_platform import IntegrationPlatform
+
+
+class IntegrationService:
+    """Converge supported agent hosts on one TopicGate integration."""
+
+    def __init__(self, information: McpSetupInformation):
+        self._information = information
+
+    def install(
+        self,
+        platform: IntegrationPlatform,
+        mode: McpMode = McpMode.READ_ONLY,
+    ) -> IntegrationResult:
+        plan = platform.plan(self._specification(platform, mode))
+        if not plan.actions:
+            return IntegrationResult(
+                state=plan.current,
+                changed=False,
+                messages=(f"{platform.name} integration is already configured.",),
+            )
+        return platform.apply(plan)
+
+    def uninstall(self, platform: IntegrationPlatform) -> IntegrationResult:
+        return platform.remove()
+
+    def status(self, platform: IntegrationPlatform) -> PlatformIntegrationState:
+        state = platform.inspect()
+        if not state.available:
+            return state
+
+        configured_modes = {
+            server.mode for server in state.servers if server.mode is not None
+        }
+        mode = (
+            configured_modes.pop()
+            if len(configured_modes) == 1
+            else McpMode.READ_ONLY
+        )
+        plan = platform.plan(self._specification(platform, mode))
+        issues = list(state.issues)
+        action_kinds = {action.kind for action in plan.actions}
+        if IntegrationActionKind.ADD_MARKETPLACE in action_kinds:
+            issues.append("TopicGate marketplace is not configured.")
+        if (
+            state.plugin_installed
+            and state.plugin_enabled is not False
+            and IntegrationActionKind.INSTALL_PLUGIN in action_kinds
+        ):
+            issues.append(
+                "TopicGate plugin version does not match the installed "
+                f"TopicGate package {self._information.version}."
+            )
+        if (
+            state.servers
+            and IntegrationActionKind.CONFIGURE_SERVER in action_kinds
+        ):
+            issues.append(
+                "TopicGate MCP configuration does not match the resolved "
+                "executable, mode, or data directory."
+            )
+        return replace(state, issues=tuple(dict.fromkeys(issues)))
+
+    def repair(
+        self,
+        platform: IntegrationPlatform,
+        mode: McpMode | None = None,
+    ) -> IntegrationResult:
+        if mode is None:
+            state = platform.inspect()
+            configured_modes = {
+                server.mode for server in state.servers if server.mode is not None
+            }
+            mode = (
+                configured_modes.pop()
+                if len(configured_modes) == 1
+                else McpMode.READ_ONLY
+            )
+        return self.install(platform, mode)
+
+    def _specification(
+        self,
+        platform: IntegrationPlatform,
+        mode: McpMode,
+    ) -> IntegrationSpec:
+        return IntegrationSpec(
+            platform=platform.name,
+            mode=mode,
+            package_version=self._information.version,
+            server_name="topicgate",
+            command=self._information.command,
+            arguments=(
+                *self._information.command_prefix_arguments,
+                "--mode",
+                mode.value,
+            ),
+            environment=(("TOPICGATE_DATA_DIR", str(self._information.data_path)),),
+        )

{topicgate-1.5.2 → topicgate-1.5.3}/src/topicgate/app/services/mcp_setup_service.py

@@ -46,6 +46,13 @@ class McpSetupService:
         self._broker_reader = broker_reader
         self._active_broker_reader = active_broker_reader
         self._subscriptions_reader = subscriptions_reader
+        self.information = self.resolve_information(data_path, database_path)
+
+    @staticmethod
+    def resolve_information(
+        data_path: Path,
+        database_path: Path,
+    ) -> McpSetupInformation:
         executable = shutil.which("topicgate")
         if executable:
             command = str(Path(executable).resolve())
@@ -57,7 +64,7 @@ class McpSetupService:
             installed_version = version("topicgate")
         except PackageNotFoundError:
             installed_version = "development"
-        self.information = McpSetupInformation(
+        return McpSetupInformation(
             version=installed_version,
             executable_path=Path(command),
             data_path=data_path.resolve(),

topicgate-1.5.3/src/topicgate/cli/_common.py

@@ -0,0 +1,23 @@
+"""Shared types and output helpers for TopicGate CLI commands."""
+
+import sys
+from collections.abc import Callable
+from typing import Protocol
+
+from topicgate.app.app_dependencies import AppDependencies
+from topicgate.app.services.integration_service import IntegrationService
+
+
+DependenciesFactory = Callable[[], AppDependencies]
+
+
+class IntegrationDependencies(Protocol):
+    integration_service: IntegrationService
+
+
+IntegrationDependenciesFactory = Callable[[], IntegrationDependencies]
+
+
+def print_error(error: Exception) -> None:
+    message = error.args[0] if isinstance(error, KeyError) else str(error)
+    print(f"Error: {message}", file=sys.stderr)

topicgate-1.5.3/src/topicgate/cli/integration_commands.py

@@ -0,0 +1,99 @@
+import argparse
+from collections.abc import Callable
+from functools import partial
+
+from topicgate.cli._common import IntegrationDependenciesFactory
+from topicgate.cli.platform_commands.integration import (
+    PlatformFactory,
+    integration_install,
+    integration_repair,
+    integration_status,
+    integration_uninstall,
+)
+from topicgate.infrastructure.integrations.claude import ClaudeIntegration
+from topicgate.infrastructure.integrations.codex import CodexIntegration
+from topicgate.infrastructure.integrations.copilot import CopilotIntegration
+from topicgate.infrastructure.integrations.cursor import CursorIntegration
+
+
+def _platforms() -> tuple[tuple[str, str, PlatformFactory], ...]:
+    return (
+        ("codex", "Codex", CodexIntegration),
+        ("claude", "Claude Code", ClaudeIntegration),
+        ("cursor", "Cursor", CursorIntegration),
+        ("copilot", "GitHub Copilot CLI", CopilotIntegration),
+    )
+
+
+def _platform_parser(
+    parser: argparse.ArgumentParser,
+    handler: Callable[..., int],
+    dependencies_factory: IntegrationDependenciesFactory,
+    *,
+    include_mode: bool,
+) -> None:
+    platforms = parser.add_subparsers(dest="integration_platform", required=True)
+    for name, display_name, platform_factory in _platforms():
+        platform_parser = platforms.add_parser(
+            name,
+            help=f"Manage the {display_name} integration",
+        )
+        if include_mode:
+            platform_parser.add_argument(
+                "--mode",
+                choices=("read-only", "control"),
+                default=None,
+                help="MCP capability mode; install defaults to read-only",
+            )
+        platform_parser.set_defaults(
+            handler=partial(
+                handler,
+                dependencies_factory=dependencies_factory,
+                platform_factory=platform_factory,
+            )
+        )
+
+
+def configure_integration_commands(
+    parser: argparse.ArgumentParser,
+    dependencies_factory: IntegrationDependenciesFactory,
+) -> None:
+    commands = parser.add_subparsers(dest="integration_command", required=True)
+
+    install_parser = commands.add_parser(
+        "install", help="Install or update an integration"
+    )
+    _platform_parser(
+        install_parser,
+        integration_install,
+        dependencies_factory,
+        include_mode=True,
+    )
+
+    status_parser = commands.add_parser("status", help="Inspect an integration")
+    _platform_parser(
+        status_parser,
+        integration_status,
+        dependencies_factory,
+        include_mode=False,
+    )
+
+    repair_parser = commands.add_parser(
+        "repair", help="Repair an integration without changing its mode"
+    )
+    _platform_parser(
+        repair_parser,
+        integration_repair,
+        dependencies_factory,
+        include_mode=True,
+    )
+
+    uninstall_parser = commands.add_parser(
+        "uninstall", help="Remove an integration"
+    )
+    _platform_parser(
+        uninstall_parser,
+        integration_uninstall,
+        dependencies_factory,
+        include_mode=False,
+    )

topicgate-1.5.3/src/topicgate/cli/platform_commands/__init__.py

@@ -0,0 +1 @@
+"""Platform-specific TopicGate CLI command handlers."""