ames-unifi-mcp 1.0.4 → 1.0.7

package/README.md

@@ -17,7 +17,8 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/ames-unifi-mcp"><img src="https://img.shields.io/npm/v/ames-unifi-mcp?style=flat-square&color=f5a542" alt="npm"></a>
-  <a href="https://github.com/oliverames/ames-unifi-mcp/releases/tag/v1.0.3"><img src="https://img.shields.io/github/v/release/oliverames/ames-unifi-mcp?style=flat-square&color=f5a542&label=MCPB" alt="MCPB release"></a>
+  <a href="https://github.com/oliverames/ames-unifi-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/oliverames/ames-unifi-mcp/ci.yml?branch=main&style=flat-square&label=CI&color=f5a542" alt="CI"></a>
+  <a href="https://github.com/oliverames/ames-unifi-mcp/releases/tag/v1.0.7"><img src="https://img.shields.io/github/v/release/oliverames/ames-unifi-mcp?style=flat-square&color=f5a542&label=MCPB" alt="MCPB release"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-f5a542?style=flat-square" alt="License"></a>
   <a href="https://www.buymeacoffee.com/oliverames"><img src="https://img.shields.io/badge/Buy_Me_a_Coffee-support-f5a542?style=flat-square&logo=buy-me-a-coffee&logoColor=white" alt="Buy Me a Coffee"></a>
 </p>
@@ -44,9 +45,9 @@ Every mutating operation passes through a **confirm gate** that returns a dry-ru
 
 ### Install with MCPB
 
-For Claude Desktop and other MCPB-compatible clients, download the local bundle from the [v1.0.3 release](https://github.com/oliverames/ames-unifi-mcp/releases/tag/v1.0.3):
+For Claude Desktop and other MCPB-compatible clients, download the local bundle from the [v1.0.7 release](https://github.com/oliverames/ames-unifi-mcp/releases/tag/v1.0.7):
 
-[Download `ames-unifi-mcp-1.0.3.mcpb`](https://github.com/oliverames/ames-unifi-mcp/releases/download/v1.0.3/ames-unifi-mcp-1.0.3.mcpb)
+[Download `ames-unifi-mcp-1.0.7.mcpb`](https://github.com/oliverames/ames-unifi-mcp/releases/download/v1.0.7/ames-unifi-mcp-1.0.7.mcpb)
 
 The bundle includes the UniFi favicon, production runtime binaries for macOS and Linux, and setup prompts for host, authentication, site, SSL, tool mode, and permission profile.
 
@@ -136,7 +137,7 @@ If a tool isn't in the index, the controller firmware is too old to support it.
 <tr>
 <td width="50%" valign="top">
 
-**Devices** &mdash; 29 tools
+**Devices** &mdash; 63 tools
 ```
 device_list          device_restart
 device_get           device_adopt
@@ -146,9 +147,12 @@ device_spectrum_scan device_rolling_upgrade_*
 device_migrate       device_port_action
 device_list_v2       device_stats_latest
 device_unadopt       device_pending_list
+system_device_tags   system_tag_*
+switching_stack_*    switching_lag_*
+switching_mclag_*    cloud_device_list
 ```
 
-**Clients** &mdash; 15 tools
+**Clients** &mdash; 16 tools
 ```
 client_list_active   client_block/unblock
 client_get           client_reconnect
@@ -157,112 +161,107 @@ client_rename        client_update
 client_list_v2       client_action
 ```
 
-**Networks** &mdash; 10 tools
+**Networks** &mdash; 39 tools
 ```
-network_list    network_create
-network_get     network_update
-network_delete  network_*_v2 (Integration API)
+network_list           network_create
+network_get            network_update
+network_delete         network_*_v2
+system_network_references
+system_radius_profiles_v2
+dns_policy_*           system_portprofile_*
 ```
 
-**Wireless (WLAN + WiFi)** &mdash; 12 tools
+**Wireless (WLAN + WiFi)** &mdash; 14 tools
 ```
 wlan_list       wlan_create/update/delete
 wlan_enable     wlan_disable
 wifi_broadcast_list/get/create/update/delete
 ```
 
-**Firewall** &mdash; 23 tools
+**Firewall** &mdash; 30 tools
 ```
 firewall_rule_*      (legacy CRUD)
 firewall_group_*     (address/port groups)
 firewall_zone_*      (ZBF zones, 9.0+)
 firewall_policy_*    (ZBF policies + ordering)
+acl_rule_*            acl_rule_ordering_*
 ```
 
-**ACL Rules** &mdash; 7 tools
+**QoS** &mdash; 10 tools
 ```
-acl_rule_list/get/create/update/delete
-acl_rule_ordering_get/set
-```
-
-**DNS Policies** &mdash; 5 tools
-```
-dns_policy_list/get/create/update/delete
+traffic_matching_list_*  (10.0+)
 ```
 
-**Traffic & QoS** &mdash; 15 tools
+**Routing** &mdash; 10 tools
 ```
 traffic_rule_*           (v2 API rules)
 traffic_route_*          (v2 API routes)
-traffic_matching_list_*  (10.0+)
+system_static_route_*
 ```
 
-</td>
-<td width="50%" valign="top">
-
 **VPN** &mdash; 10 tools
 ```
 vpn_server_list/get/create/update/delete
 vpn_tunnel_list/get/create/update/delete
 ```
 
-**Switching** &mdash; 15 tools
-```
-switching_stack_*    (switch stacks)
-switching_lag_*      (link aggregation)
-switching_mclag_*    (MC-LAG domains)
-```
+</td>
+<td width="50%" valign="top">
 
-**Stats & DPI** &mdash; 24 tools
+**Stats** &mdash; 20 tools
 ```
 stats_site_health    stats_sysinfo
 stats_dashboard      stats_report
 stats_speedtest_*    stats_ips_events
 stats_rogueap        stats_spectrumscan
+```
+
+**DPI** &mdash; 11 tools
+```
 stats_dpi_site       stats_dpi_client
 stats_dpi_apps       stats_dpi_categories
+misc_dpigroup_*
 ```
 
-**Events & Alarms** &mdash; 5 tools
+**Events** &mdash; 8 tools
 ```
 event_list           alarm_list
 alarm_count          alarm_archive
 alarm_archive_all
 ```
 
-**Hotspot & Guests** &mdash; 13 tools
+**Hotspot** &mdash; 27 tools
 ```
 hotspot_authorize/unauthorize_guest
 hotspot_create_voucher  hotspot_extend
 hotspot_voucher_*_v2    (Integration API)
 hotspot_config          hotspot_packages
+misc_hotspotop_*        hotspot_2_0_package_*
 ```
 
-**System & Settings** &mdash; 53 tools
+**System** &mdash; 27 tools
 ```
 system_reboot/poweroff  system_settings
-system_backup_*         system_firmware_*
-system_port_forward_*   system_static_route_*
-system_usergroup_*      system_portprofile_*
-system_dhcpoption_*     system_radiusprofile_*
-system_tag_*            system_led_toggle
+system_firmware_*       admin_site_*
+admin_invite/revoke     cloud_host_list/get
+cloud_site_list         cloud_sdwan_*
+```
+
+**Settings** &mdash; 19 tools
+```
+system_setting_*     system_led_toggle
+system_ips_update    misc_scheduletask_*
+misc_cnt_resource
 ```
 
-**Cloud API** &mdash; 9 tools
+**Backup** &mdash; 5 tools
 ```
-cloud_host_list/get     cloud_site_list
-cloud_device_list       cloud_isp_metrics
-cloud_sdwan_*
+system_backup_*      backup_restore
 ```
 
-**Admin & Misc** &mdash; 56 tools
+**PoE** &mdash; 1 tool
 ```
-admin_site_create/delete/rename
-admin_invite/revoke/grant/update
-poe_power_cycle         syslog_query
-apgroup_*               misc_rogueknown_*
-misc_scheduletask_*     misc_hotspotop_*
-misc_dpigroup_*         misc_cnt_resource
+poe_power_cycle
 ```
 
 </td>
@@ -290,6 +289,10 @@ The server covers all three UniFi API layers:
 | `UNIFI_API_KEY` | * | &mdash; | API key (preferred, requires 9.1.105+) |
 | `UNIFI_USERNAME` | * | &mdash; | Username (if no API key) |
 | `UNIFI_PASSWORD` | * | &mdash; | Password (if no API key) |
+| `UNIFI_HOST_OP_REF` | No | empty | Caller-owned 1Password reference for the controller URL |
+| `UNIFI_API_KEY_OP_REF` | No | empty | Caller-owned 1Password reference for the API key |
+| `UNIFI_USERNAME_OP_REF` | No | empty | Caller-owned 1Password reference for the username |
+| `UNIFI_PASSWORD_OP_REF` | No | empty | Caller-owned 1Password reference for the password |
 | `UNIFI_SITE` | No | `default` | Site name |
 | `UNIFI_VERIFY_SSL` | No | `true` | `false` for self-signed certs |
 | `UNIFI_TOOL_MODE` | No | `lazy` | `lazy` (3 meta-tools) or `eager` (all 310 tools) |
@@ -299,14 +302,14 @@ The server covers all three UniFi API layers:
 
 ### 1Password fallback
 
-If env vars are unset, the server falls back to 1Password CLI (`op read`) using these references:
+The server can resolve credentials through 1Password CLI, but it does not assume a vault or item name. Set the reference variables to paths you own:
 
-- `op://Development/UniFi Controller/host`
-- `op://Development/UniFi Controller/api_key`
-- `op://Development/UniFi Controller/username`
-- `op://Development/UniFi Controller/password`
+```bash
+UNIFI_HOST_OP_REF="op://Your Vault/Your Item/host"
+UNIFI_API_KEY_OP_REF="op://Your Vault/Your Item/api_key"
+```
 
-Create a `UniFi Controller` item in your `Development` vault with those fields and the server will resolve credentials at startup with no env vars required. Resolution happens in `internal/config/config.go:opRead` and requires either an interactive `op` session or `OP_SERVICE_ACCOUNT_TOKEN` in the environment.
+Plaintext environment variables take priority. The server calls `op read` only when a plaintext value is empty and its matching reference variable is set. This keeps the public package neutral and prevents unexpected 1Password lookups.
 
 ### Authentication Methods
 
@@ -314,18 +317,7 @@ Create a `UniFi Controller` item in your `Development` vault with those fields a
 
 **Username/Password** &mdash; Uses session cookies with automatic re-login on expiry. The server includes a single-flight re-login mechanism that prevents thundering-herd issues when batch operations encounter session timeouts simultaneously.
 
-### 1Password Integration
-
-If credentials are not set in the environment, the server automatically attempts to resolve them from [1Password CLI](https://developer.1password.com/docs/cli/):
-
-| Variable | 1Password Reference |
-|----------|-------------------|
-| `UNIFI_HOST` | `op://Development/UniFi Controller/host` |
-| `UNIFI_API_KEY` | `op://Development/UniFi Controller/api_key` |
-| `UNIFI_USERNAME` | `op://Development/UniFi Controller/username` |
-| `UNIFI_PASSWORD` | `op://Development/UniFi Controller/password` |
-
-This means you can skip setting env vars entirely if you have `op` installed and a service account or session active. The fallback adds ~1-2s to startup and is silently skipped if 1Password is unavailable.
+See [integration testing](docs/INTEGRATION_TESTING.md) for a safe controller test sequence and [release guidance](docs/RELEASING.md) for the checks that produce the npm package, MCPB bundle, checksums, and SBOM.
 
 ---
 

package/bin/ames-unifi-mcp

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+const { spawn } = require("child_process");
+const path = require("path");
+const os = require("os");
+
+const binaryName = "ames-unifi-mcp";
+
+const platformMap = {
+  "darwin-arm64": `${binaryName}-darwin-arm64`,
+  "darwin-x64": `${binaryName}-darwin-amd64`,
+  "linux-arm64": `${binaryName}-linux-arm64`,
+  "linux-x64": `${binaryName}-linux-amd64`,
+};
+
+const key = `${os.platform()}-${os.arch()}`;
+const platformBinary = platformMap[key];
+
+if (!platformBinary) {
+  console.error(
+    `Unsupported platform: ${key}. Supported: ${Object.keys(platformMap).join(", ")}`
+  );
+  process.exit(1);
+}
+
+const binaryPath = path.join(__dirname, "..", "dist", platformBinary);
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+});
+
+child.on("error", (error) => {
+  console.error(`Failed to start ${binaryName}: ${error.message}`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code ?? 0);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ames-unifi-mcp",
-  "version": "1.0.4",
+  "version": "1.0.7",
   "description": "UniFi Network MCP server — 310 tools for complete controller management via the Model Context Protocol",
   "keywords": [
     "mcp",
@@ -20,7 +20,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/oliverames/ames-unifi-mcp.git"
+    "url": "git+https://github.com/oliverames/ames-unifi-mcp.git"
   },
   "homepage": "https://github.com/oliverames/ames-unifi-mcp#readme",
   "bugs": {
@@ -30,14 +30,14 @@
     "ames-unifi-mcp": "bin/ames-unifi-mcp"
   },
   "files": [
-    "dist/",
-    "install.js",
+    "bin/ames-unifi-mcp",
+    "dist/ames-unifi-mcp-darwin-arm64",
+    "dist/ames-unifi-mcp-darwin-amd64",
+    "dist/ames-unifi-mcp-linux-arm64",
+    "dist/ames-unifi-mcp-linux-amd64",
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "postinstall": "node install.js"
-  },
   "os": [
     "darwin",
     "linux"

package/install.js

@@ -1,57 +0,0 @@
-#!/usr/bin/env node
-
-// Postinstall script: copies the correct platform binary to bin/ames-unifi-mcp
-
-const fs = require("fs");
-const path = require("path");
-const os = require("os");
-
-const BINARY_NAME = "ames-unifi-mcp";
-
-const PLATFORM_MAP = {
-  "darwin-arm64": `${BINARY_NAME}-darwin-arm64`,
-  "darwin-x64": `${BINARY_NAME}-darwin-amd64`,
-  "linux-arm64": `${BINARY_NAME}-linux-arm64`,
-  "linux-x64": `${BINARY_NAME}-linux-amd64`,
-};
-
-function install() {
-  const platform = os.platform();
-  const arch = os.arch();
-  const key = `${platform}-${arch}`;
-
-  const binaryFile = PLATFORM_MAP[key];
-  if (!binaryFile) {
-    console.error(
-      `Unsupported platform: ${platform}-${arch}. ` +
-        `Supported: ${Object.keys(PLATFORM_MAP).join(", ")}`
-    );
-    process.exit(1);
-  }
-
-  const distDir = path.join(__dirname, "dist");
-  const binDir = path.join(__dirname, "bin");
-  const src = path.join(distDir, binaryFile);
-  const dest = path.join(binDir, BINARY_NAME);
-
-  if (!fs.existsSync(src)) {
-    console.error(`Binary not found: ${src}`);
-    console.error("Try rebuilding: make build-all");
-    process.exit(1);
-  }
-
-  // Ensure bin/ exists
-  if (!fs.existsSync(binDir)) {
-    fs.mkdirSync(binDir, { recursive: true });
-  }
-
-  // Copy binary
-  fs.copyFileSync(src, dest);
-
-  // Make executable
-  fs.chmodSync(dest, 0o755);
-
-  console.log(`Installed ${BINARY_NAME} for ${platform}/${arch}`);
-}
-
-install();