@mseep/safe-omada-mcp 0.17.0

package/.env.example

@@ -0,0 +1,136 @@
+# ==============================================================================
+# Tool Category Filtering
+# ==============================================================================
+
+# High-level capability profile (default: safe-read)
+# Options:
+#   safe-read      - default read-only baseline
+#   ops-write      - low-risk operational writes on top of the baseline
+#   admin          - broad administrative access
+#   compatibility  - reserved for future controller-specific fallback modules
+# OMADA_CAPABILITY_PROFILE=safe-read
+
+# Comma-separated list of tool categories to enable at startup (defaults derive from OMADA_CAPABILITY_PROFILE).
+# Each token is <category>[:<suffix>] where suffix is one of:
+#   :r   — register read tools only
+#   :w   — register write tools only
+#   :rw  — register read and write tools
+#   (no suffix) — same as :rw
+#
+# Group aliases expand to multiple categories:
+#   all          → every category
+#   devices-all  → devices-general, devices-ap, devices-switch, devices-gateway
+#   wireless-all → wireless-ssid, wireless-radio, wireless-auth
+#   network-all  → network-wan, network-lan, network-routing, network-nat, network-services
+#                  (excludes network-sim-lte* — not yet implemented)
+#   firewall-all → firewall-acl, firewall-traffic, firewall-ids
+#   security-all → security-threat, security-wids
+#
+# Full category list (* = not yet implemented, reserved for future phases):
+#   Dashboard & Insights: dashboard, client-insights, insights*
+#   Clients:              clients
+#   Devices:              devices-general, devices-ap, devices-switch, devices-gateway
+#   Wireless:             wireless-ssid, wireless-radio, wireless-auth
+#   Network:              network-wan, network-sim-lte*, network-lan, network-routing, network-nat, network-services
+#   Firewall & Security:  firewall-acl, firewall-traffic, firewall-ids, security-threat, security-wids
+#   VPN:                  vpn
+#   Profiles & Schedules: profiles, schedules, auth-profiles
+#   Logs:                 logs
+#   Controller & Org:     controller, sites, maintenance, account-users, account-sso*, account-cloud
+#   Hotspot:              hotspot-portal*, hotspot-vouchers*, hotspot-users*
+#   Niche:                voip*, olt*, msp*
+#
+# Examples:
+#   All read-only:                   OMADA_TOOL_CATEGORIES=all:r
+#   Default (safe read subset):      OMADA_TOOL_CATEGORIES=dashboard:r,client-insights:r,clients:r,devices-all:r
+#   Full access including writes:    OMADA_TOOL_CATEGORIES=all:rw
+#   Network read + client writes:    OMADA_TOOL_CATEGORIES=network-all:r,clients:rw
+#
+# OMADA_TOOL_CATEGORIES=dashboard:r,client-insights:r,clients:r,devices-all:r
+
+# ==============================================================================
+# Omada Client Configuration
+# ==============================================================================
+
+# Base URL of the Omada controller (required)
+# Example: https://omada-controller.local
+OMADA_BASE_URL=https://controller.example.com:8043
+
+# OAuth client credentials (required)
+# Generate these under Omada Platform Integration
+OMADA_CLIENT_ID=your-client-id
+OMADA_CLIENT_SECRET=your-client-secret
+
+# Omada controller ID (omadacId) to target (required)
+# Shown in the application details
+OMADA_OMADAC_ID=your-omadac-id
+
+# Optional default site ID
+# If omitted, each MCP call must pass a siteId argument
+# OMADA_SITE_ID=optional-default-site
+
+# Enforce strict SSL certificate validation (default: true)
+# Set to false to accept self-signed certificates during development
+# OMADA_STRICT_SSL=true
+
+# HTTP request timeout in milliseconds (default: 30000)
+# OMADA_TIMEOUT=30000
+
+# ==============================================================================
+# MCP Generic Server Configuration
+# ==============================================================================
+
+# Logging verbosity (default: info)
+# Options: debug, info, warn, error, silent
+# MCP_SERVER_LOG_LEVEL=info
+
+# Log output format (default: plain)
+# Options: plain, json, gcp-json
+#   - plain: human-readable text format
+#   - json: structured JSON format
+#   - gcp-json: structured JSON format compatible with Google Cloud Logging
+# MCP_SERVER_LOG_FORMAT=plain
+
+# Start HTTP server instead of stdio (default: false)
+# HTTP mode is intentionally unsupported in the safe baseline.
+# MCP_SERVER_USE_HTTP=false
+
+# Required to acknowledge that HTTP mode is unsafe and for lab use only.
+# MCP_UNSAFE_ENABLE_HTTP=false
+
+# ==============================================================================
+# MCP Server HTTP Configuration
+# (Only used when MCP_SERVER_USE_HTTP=true and MCP_UNSAFE_ENABLE_HTTP=true)
+# ==============================================================================
+
+# Port for the HTTP server (default: 3000)
+# MCP_HTTP_PORT=3000
+
+# Bind address for the HTTP server (default: 127.0.0.1)
+# The safe baseline only allows loopback addresses: 127.0.0.1 or ::1
+# MCP_HTTP_BIND_ADDR=127.0.0.1
+
+# Base path for MCP HTTP endpoints (default: /mcp)
+# MCP_HTTP_PATH=/mcp
+
+# Enable a healthcheck endpoint (default: true)
+# MCP_HTTP_ENABLE_HEALTHCHECK=true
+
+# Path for the healthcheck endpoint (default: /healthz)
+# MCP_HTTP_HEALTHCHECK_PATH=/healthz
+
+# Enable CORS for the HTTP server (default: true)
+# MCP_HTTP_ALLOW_CORS=true
+
+# Comma-separated list of allowed origins for DNS rebinding protection (default: 127.0.0.1, localhost)
+# Must contain valid hostnames, IPv4, IPv6 addresses, or '*' to allow all origins
+# Use '*' to allow all origins (WARNING: only for development, not recommended for production)
+# Examples: localhost, 127.0.0.1, ::1, example.com, *
+# MCP_HTTP_ALLOWED_ORIGINS=127.0.0.1,localhost
+# MCP_HTTP_ALLOWED_ORIGINS=*
+
+# Public tunnel support is intentionally disabled in the safe baseline.
+# MCP_HTTP_NGROK_ENABLED=false
+
+# Legacy placeholder only.
+# MCP_HTTP_NGROK_AUTH_TOKEN=your-ngrok-auth-token

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.17.0 - 2026-04-05
+
+- added explicit two-step `confirmDangerous` confirmation gate to all four restore tools (`restoreController`, `restoreControllerFromFileServer`, `restoreSites`, `restoreSitesFromFileServer`) — irreversibility warning surfaces before any execution
+- fixed three API contract bugs: `getRogueApExport` format values corrected to spec (`'0'`/`'1'`), threat API timestamps converted to seconds, `getThreatList` site scoping via `siteList` param
+- expanded `ops-write` capability profile to include `maintenance:rw`, `logs:r`, `network-wan:r`, `security-threat:r`, `vpn:r`
+- documented `confirmDangerous` scope and limitations in `CLAUDE.md` and `README.md`
+- added `AGENTS.md` symlink to `CLAUDE.md` for cross-agent instruction pickup
+- fixed Docker publish workflow to use dynamic repository owner
+
+## 0.16.0 - 2026-04-03
+
+- promoted the hardened Omada MCP platform to a stdio-first production baseline
+- completed Phase 3 administrative tooling for AP, gateway, DHCP, ACL, and traffic-control workflows
+- aligned server version reporting with package metadata
+- tightened legacy HTTP mode so it remains loopback-only even when explicitly enabled for lab use
+- refreshed README, Docker README, and AI-agent instructions to match the current platform behavior
+- strengthened CI with symlink validation and cleaned release metadata for the published package and container image

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 João Miguel Tabosa Vaz Marques Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.