Publish TopicGate Plugin Automation And Release Updates

.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "topicgate",
+  "owner": {
+    "name": "Dumdart"
+  },
+  "plugins": [
+    {
+      "name": "topicgate",
+      "source": "./topicgate-plugin",
+      "description": "Secure local access to MQTT state through TopicGate",
+      "version": "1.1.0"
+    }
+  ]
+}

.github/workflows/cd.yaml

@@ -0,0 +1,107 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yaml
+
+  release-build:
+    runs-on: ubuntu-latest
+    needs:
+      - ci
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify release versions
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: python -m release.run_cd
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  mcp-registry-publish:
+    needs: pypi-publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install MCP Publisher
+        run: |
+          curl -L \
+            "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz" \
+            | tar xz
+          sudo mv mcp-publisher /usr/local/bin/
+
+      - name: Validate MCP server metadata
+        run: mcp-publisher validate server.json
+
+      - name: Authenticate with MCP Registry
+        run: mcp-publisher login github-oidc
+
+      - name: Publish to MCP Registry
+        run: mcp-publisher publish server.json
+
+  github-release:
+    needs:
+      - pypi-publish
+      - mcp-registry-publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ github.ref_name }}" dist/* \
+            --title "TopicGate ${{ github.ref_name }}" \
+            --generate-notes

.github/workflows/ci.yaml

@@ -3,6 +3,8 @@ name: CI
 on:
   push:
   pull_request:
+  workflow_call:
+
 
 permissions:
   contents: read
@@ -12,6 +14,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Verify release versions
+        run: python -m release.run_ci
       - name: Set up Python
         uses: actions/setup-python@v5
         with:

README.md

@@ -7,7 +7,7 @@
 
 <p align="center">
   <a href="#get-started">Get started</a> ·
-  <a href="#use-it-from-codex">Use it from Codex</a> ·
+  <a href="#connect-an-agent">Connect an agent</a> ·
   <a href="#how-observations-work">Understand observations</a> ·
   <a href="docs/desktop-workflow.md">Desktop workflow</a>
 </p>
@@ -34,39 +34,24 @@ TopicGate supports exact MQTT paths and the standard `+` and `#` wildcard filter
 
 ### 1. Install
 
-TopicGate requires Python 3.11+ and access to an MQTT 5-compatible broker. It is currently installed from a source checkout; package distribution is planned but not yet published.
+TopicGate requires Python 3.11+ and access to an MQTT 5-compatible broker. Install the released package with uv:
 
 > [!IMPORTANT]
-> **Windows is the only validated platform today.** The macOS and Linux paths, desktop behaviour, and credential-store integrations have not been tested end to end. Codex is the only MCP host and plugin harness validated so far; other MCP clients may work, but are not currently supported installation paths.
-
-The Windows development installation is:
-
-```powershell
-git clone https://github.com/Dumdart/TopicGate.git
-cd TopicGate
-python -m pip install -e .
-```
-
-Then install mcp in readonly mode (codex):
+> **Windows is the only validated platform today.** The macOS and Linux paths, desktop behaviour, and credential-store integrations have not been tested end to end. TopicGate uses `keyring` for the operating-system credential store; those integrations have not yet been tested across platforms.
 
 ```powershell
-codex mcp add topicgate -- python -m topicgate   
-```
-
-or with full access:
-
-```powershell
-codex mcp add topicgate -- python -m topicgate --mode control
+uv tool install topicgate
+topicgate-gui
 ```
 
-Install Plugin (codex):
+Alternatively, install it with pip:
 
 ```powershell
-codex plugin marketplace add .
-codex plugin add topicgate@topicgate
+python -m pip install topicgate
+topicgate-gui
 ```
 
-For an unvalidated macOS or Linux source checkout, activate the environment with `source .venv/bin/activate`. Install the optional MCP Apps dashboard with `uv sync --extra apps` or `python -m pip install -e ".[apps]"`.
+For upgrades, uninstallation, backups, and recovery, see [Installation recovery and upgrades](docs/install/UPGRADE_AND_RECOVERY.md).
 
 ### 2. Configure and observe
 
@@ -111,23 +96,21 @@ Use the absolute path to `topicgate` or `topicgate.exe` if the environment is no
 fastmcp call --command topicgate --target list_brokers --json
 ```
 
-## Use it from Codex
+## Connect an agent
 
-TopicGate includes a Codex plugin with eight focused skills for setting up the connection, inspecting the current MQTT state, working with subscriptions, and safely refreshing or publishing only when control mode is enabled. Codex is the only plugin host tested by this project.
+TopicGate can be connected to an MCP-capable agent after you have configured a broker and observed data in the desktop application. The server is read-only by default; enable control mode only in a host you trust to change broker connections, subscriptions, or device state.
 
-<p align="center">
-  <img src="docs/images/plugin_in_codex.png" alt="TopicGate installed in Codex with its MCP server and skills enabled." width="720" />
-</p>
+Agent setup differs by host. Use the installation guide for yours:
 
-Install the bundled `topicgate-plugin` through your Codex plugin marketplace, enable it, and start a new thread. The plugin's default MCP configuration uses `topicgate --mode read-only` and the same platform application-data directory as TopicGate Desktop, so it can inspect the profiles, subscriptions, and observations configured there. If the executable is not on `PATH`, use TopicGate Desktop's MCP setup page to copy a configuration with the resolved absolute path.
+| Agent | Setup guide | Support |
+| --- | --- | --- |
+| Codex | [Install TopicGate for Codex](docs/install/CODEX.md) | Plugin and MCP server validated. |
+| Claude Code | [Install TopicGate for Claude Code](docs/install/CLAUDE_CODE.md) | Plugin package and MCP configuration; runtime validation pending. |
+| VS Code / GitHub Copilot | [Install TopicGate for GitHub Copilot](docs/install/VSCODE_COPILOT.md) | Agent Plugins 1.0 package; runtime validation pending. |
+| Cursor | [Install TopicGate for Cursor](docs/install/CURSOR.md) | Agent Plugins 1.0 package; runtime validation pending. |
 
-Try one of these prompts:
+If `topicgate` is not on the agent host's `PATH`, use the MCP setup page in TopicGate Desktop to copy a configuration with the resolved executable path.
 
-```text
-Help me set up TopicGate.
-Inspect my TopicGate MQTT state.
-Show the latest observed MQTT values.
-```
 
 ## How observations work
 
@@ -184,19 +167,23 @@ Set `TOPICGATE_DATA_DIR` to use a specific directory. The database contains brok
 
 Use **File > Stored observations** in the desktop app to review cache use and retention. Deleting `topicgate.db` permanently removes saved profiles, subscriptions, settings, and observations unless you have backed it up first.
 
-## Distribution and onboarding roadmap
+## Development
 
-Before TopicGate is released as a package, the project plans to:
+For a source checkout:
 
-1. Publish platform-specific installation guidance and decide whether Windows should also receive an installer or packaged executable.
-2. Validate Windows Credential Locker, macOS Keychain, and Linux secret-service behaviour.
-3. Add backup and restore guidance plus migration and release notes.
-4. Publish the Codex plugin only against a released TopicGate version.
-5. Document troubleshooting for PATH, stdio launch, credentials, broker TLS, and dashboard dependencies.
+```powershell
+git clone https://github.com/Dumdart/TopicGate.git
+cd TopicGate
+uv sync --extra apps --extra test
+uv run topicgate-gui
+```
 
-The release goal is that users no longer need an editable source checkout, desktop and plugin installation are reproducible, and upgrade and recovery procedures are documented.
+Alternatively, use an editable pip install:
 
-## Development
+```powershell
+python -m pip install -e ".[apps,test]"
+topicgate-gui
+```
 
 Run the full test suite before submitting changes:
 

docs/install/CLAUDE_CODE.md

@@ -0,0 +1,74 @@
+# Install TopicGate for Claude Code
+
+Claude Code can use TopicGate either through the bundled plugin or as a standalone stdio MCP server. The plugin is the recommended setup because it also installs the focused TopicGate skills.
+
+## Install TopicGate
+
+TopicGate's official MCP Registry identifier is `io.github.Dumdart/topicgate`. The registry provides package metadata rather than installing packages; after a release has been published, registry-aware clients can discover TopicGate with that identifier. Install the released PyPI package before connecting an MCP host:
+
+```powershell
+uv tool install topicgate
+topicgate-gui
+```
+
+Alternatively:
+
+```powershell
+python -m pip install topicgate
+topicgate-gui
+```
+
+Before connecting Claude Code, install TopicGate and use TopicGate Desktop to configure a broker, add subscriptions, and observe data. The MCP server reads the same local application-data directory as the desktop app.
+
+## Development: install from a local checkout
+
+From the TopicGate repository root, register the current directory as a local marketplace and install the plugin:
+
+```powershell
+claude plugin marketplace add .
+claude plugin install topicgate@topicgate
+```
+
+The equivalent commands inside an interactive Claude Code session are:
+
+```text
+/plugin marketplace add .
+/plugin install topicgate@topicgate
+```
+
+To load the plugin for one development session without installing it, use:
+
+```powershell
+claude --plugin-dir ./topicgate-plugin
+```
+
+The plugin automatically loads its skills and starts TopicGate in read-only mode. Restart Claude Code and open a new session after installing or updating the plugin.
+
+## Install from GitHub
+
+After the marketplace has been published, replace the local path with the GitHub repository:
+
+```powershell
+claude plugin marketplace add Dumdart/TopicGate
+claude plugin install topicgate@topicgate
+```
+
+## Install only the MCP server
+
+Use this when you do not want the plugin skills:
+
+```powershell
+claude mcp add topicgate -- topicgate --mode read-only
+```
+
+If `topicgate` is not on `PATH`, replace it with its absolute path. TopicGate Desktop's MCP setup page can copy a configuration with the resolved executable path.
+
+## Control mode
+
+Control mode can connect or disconnect brokers, change subscriptions, refresh observations, and publish MQTT messages. Use it only in a trusted environment:
+
+```powershell
+claude mcp add topicgate-control -- topicgate --mode control
+```
+
+Confirm the broker, topic, payload, and encoding before allowing a publish operation.