@teamnetwork-nz/sonicwall-api-mcp-server 0.9.1 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.env.example ADDED
@@ -0,0 +1,40 @@
1
+ # Sanitised template: no live credentials or identities.
2
+ # See README.md for requirements, defaults and .env loading behaviour.
3
+ # Replace required/alternative placeholders privately; uncomment optional settings only when needed.
4
+
5
+ # Private JSON device-profile array; replaces single-device credentials and settings, including per-profile read_only.
6
+ # SONICWALL_DEVICES_FILE=<set-privately>
7
+ # Local name for the single-device profile.
8
+ # SONICWALL_DEVICE_NAME=default
9
+ # Firewall hostname; required unless SONICWALL_DEVICES_FILE is set.
10
+ SONICWALL_HOST=<set-privately>
11
+ # Comma-separated Host allowlist required for non-loopback HTTP; use the public hostnames accepted by the listener.
12
+ # SONICWALL_HTTP_ALLOWED_HOSTS=<set-privately>
13
+ # Comma-separated browser Origin allowlist; configure when browser clients need access.
14
+ # SONICWALL_HTTP_ALLOWED_ORIGINS=<set-privately>
15
+ # Private bearer secret required for non-loopback HTTP; clients send Authorization: Bearer <secret>.
16
+ # SONICWALL_HTTP_BEARER_TOKEN=<set-privately>
17
+ # Listener bind address. Non-loopback binding requires a bearer token and explicit allowed hosts.
18
+ # SONICWALL_HTTP_HOST=127.0.0.1
19
+ # Maximum HTTP request body; integer 1–16777216 bytes.
20
+ # SONICWALL_HTTP_MAX_BODY_BYTES=1048576
21
+ # HTTP listener port; integer 1–65535.
22
+ # SONICWALL_HTTP_PORT=3000
23
+ # Firewall API password; required in single-device mode.
24
+ SONICWALL_PASSWORD=<set-privately>
25
+ # Firewall HTTPS port; integer 1–65535.
26
+ # SONICWALL_PORT=443
27
+ # Only true enables mutation tools; read-only is the default. Review each operation before use. Applies to single-device mode; JSON profiles use read_only.
28
+ # SONICWALL_READWRITE=false
29
+ # Compatibility alias: false enables writes only when SONICWALL_READWRITE is unset; single-device mode only.
30
+ # SONICWALL_READ_ONLY=<set-privately>
31
+ # Firewall request timeout; integer 1–300 seconds.
32
+ # SONICWALL_REQUEST_TIMEOUT=30
33
+ # Parsed compatibility setting, integer 1–65535; does not start an SSE listener. Use HTTP_PORT for Streamable HTTP.
34
+ # SONICWALL_SSE_PORT=8000
35
+ # false disables TLS verification globally if any profile disables it; retain true.
36
+ # SONICWALL_SSL_VERIFY=true
37
+ # stdio or http; HTTP serves /mcp and GET /health.
38
+ # SONICWALL_TRANSPORT=stdio
39
+ # Firewall API username; required in single-device mode.
40
+ SONICWALL_USERNAME=<set-privately>
package/README.md CHANGED
@@ -1,189 +1,242 @@
1
- # SonicWall NSA MCP Server
2
-
3
- ## Streamable HTTP
4
-
5
- Set `SONICWALL_TRANSPORT=http` to serve stateless MCP at `/mcp`. It binds to `127.0.0.1` by default; remote binding requires `SONICWALL_HTTP_BEARER_TOKEN` and `SONICWALL_HTTP_ALLOWED_HOSTS`. Optional controls include `SONICWALL_HTTP_PORT`, `SONICWALL_HTTP_ALLOWED_ORIGINS`, and `SONICWALL_HTTP_MAX_BODY_BYTES`; `/health` is available for health checks.
6
-
7
- A [Model Context Protocol](https://modelcontextprotocol.io/) server that provides full read/write access to SonicWall NSA series appliances via the SonicOS REST API.
8
-
9
- ## Features
10
-
1
+ # SonicWall NSA MCP Server
2
+
3
+ Both TypeScript and Python tools accept optional `outputFormat: "json"` for client consistency. The TypeScript server returns valid JSON text when requested; the Python server already returns structured data that FastMCP serializes as JSON. In both implementations the option is handled locally and is never sent to the SonicWall appliance.
4
+
5
+ ## Streamable HTTP
6
+
7
+ Set `SONICWALL_TRANSPORT=http` to serve stateless MCP at `/mcp`. It binds to `127.0.0.1` by default; remote binding requires `SONICWALL_HTTP_BEARER_TOKEN` and `SONICWALL_HTTP_ALLOWED_HOSTS`. Optional controls include `SONICWALL_HTTP_PORT`, `SONICWALL_HTTP_ALLOWED_ORIGINS`, and `SONICWALL_HTTP_MAX_BODY_BYTES`; `/health` is available for health checks.
8
+
9
+ A [Model Context Protocol](https://modelcontextprotocol.io/) server that provides full read/write access to SonicWall NSA series appliances via the SonicOS REST API.
10
+
11
+ ## Features
12
+
11
13
  - **Log configuration** — inspect log categories and event-definition settings (not runtime event history)
12
- - **Address objects & groups** — CRUD for IPv4, IPv6, FQDN, and MAC address objects and their groups
13
- - **Service objects & groups** — CRUD for protocol/port service definitions
14
- - **Access rules** — create, update, enable/disable, and delete firewall access rules (IPv4 & IPv6)
15
- - **NAT policies** — full CRUD for inbound/outbound NAT rules
16
- - **Security policies** — CRUD for zone-based security policies
17
- - **Network discovery** — list zones, interfaces, schedules, and route policies (read-only)
18
- - **Appliance diagnostics** — network-path lookup, ARP cache, ping, traceroute, and combined IP diagnosis (read-only)
19
- - **GeoIP lookup** — identify the country/botnet classification of an IP address
20
- - **Config management** — view and commit (or discard) staged changes
21
-
14
+ - **Address objects & groups** — CRUD for IPv4, IPv6, FQDN, and MAC address objects and their groups
15
+ - **Service objects & groups** — CRUD for protocol/port service definitions
16
+ - **Access rules** — create, update, enable/disable, and delete firewall access rules (IPv4 & IPv6)
17
+ - **NAT policies** — full CRUD for inbound/outbound NAT rules
18
+ - **Security policies** — CRUD for zone-based security policies
19
+ - **Network discovery** — list zones, interfaces, schedules, and route policies (read-only)
20
+ - **Appliance diagnostics** — network-path lookup, ARP cache, ping, traceroute, and combined IP diagnosis (read-only)
21
+ - **GeoIP lookup** — identify the country/botnet classification of an IP address
22
+ - **Config management** — view and commit (or discard) staged changes
23
+
22
24
  > The SonicOS REST API is configuration-focused. Runtime event/threat/connection logs and GeoIP *policy* objects are not exposed as REST endpoints and therefore have no tools. `get_log_categories` and `list_log_event_definitions` inspect logging configuration only.
23
-
24
- ### Diagnosing an unreachable IP
25
-
26
- Use `diagnose_ip` for a combined report containing the appliance's selected network path, configured interfaces and route policies, matching ARP entry, ping result, and traceroute. Set `interface` to force the live tests through an interface such as `X1`, or set `include_traceroute=false` for a faster check. The focused tools `find_network_path`, `lookup_arp`, `ping_from_appliance`, and `traceroute_from_appliance` are also available. Diagnostic POST actions are read-only and work without enabling `SONICWALL_READWRITE`.
27
-
28
- Supports SonicOS 6.5.x, 7.x, and 8.x with automatic version detection.
29
-
30
- ## Quick Start
31
-
32
- ### Prerequisites
33
-
34
- - A SonicWall NSA appliance running SonicOS 6.5, 7.x, or 8.x
35
- - SonicOS API enabled: **Device › Settings › Administration › SonicOS API** — toggle **SonicOS API** on, and ensure **RFC-2617 HTTP Basic Access authentication** is also enabled (the MCP server uses Basic auth to obtain a session token, falling back to RFC-7616 Digest if Basic is disabled)
36
- - For npm install: [Node.js ≥ 18](https://nodejs.org/) and [uv](https://docs.astral.sh/uv/)
37
- - For Python install: Python ≥ 3.11
38
-
39
- ### Install
40
-
41
- **Via npx (recommended — no Python setup required):**
42
-
43
- ```bash
44
- npx @teamnetwork-nz/sonicwall-api-mcp-server
45
- ```
46
-
47
- > The npm package is a thin launcher that calls `uvx sonicwall-mcp-server` under the hood. Only [uv](https://docs.astral.sh/uv/) needs to be installed — no Python environment setup required.
48
-
49
- **Via pip / uv (Python):**
50
-
51
- ```bash
52
- pip install sonicwall-mcp-server
53
- # or
54
- uv pip install sonicwall-mcp-server
55
- ```
56
-
57
- ### Environment variables
58
-
59
- | Variable | Required | Default | Description |
60
- |----------|----------|---------|-------------|
61
- | `SONICWALL_HOST` | Yes | — | Appliance IP or hostname |
62
- | `SONICWALL_USERNAME` | Yes | — | Admin username |
63
- | `SONICWALL_PASSWORD` | Yes | — | Admin password |
64
- | `SONICWALL_PORT` | No | `443` | HTTPS management port |
65
- | `SONICWALL_SSL_VERIFY` | No | `true` | Set `false` for self-signed certificates |
66
- | `SONICWALL_READWRITE` | No | `false` | Set `true` to allow write operations |
67
-
68
- `SONICWALL_READ_ONLY=false` remains a deprecated compatibility alias for one release. `SONICWALL_READWRITE` takes precedence when both are set.
69
- | `SONICWALL_DEVICES_FILE` | No | — | Path to JSON file for multi-device config |
70
- | `SONICWALL_REQUEST_TIMEOUT` | No | `30.0` | Per-request timeout in seconds |
71
-
72
- Copy `.env.example` to `.env` for local development.
73
-
74
- ### Claude Desktop / Claude Code Integration
75
-
76
- Add to your MCP config (`claude_desktop_config.json` or `.claude/settings.json`):
77
-
78
- **Using npx (easiest):**
79
-
80
- ```json
81
- {
82
- "mcpServers": {
83
- "sonicwall": {
84
- "command": "npx",
85
- "args": ["-y", "@teamnetwork-nz/sonicwall-api-mcp-server"],
86
- "env": {
87
- "SONICWALL_HOST": "192.168.168.168",
88
- "SONICWALL_USERNAME": "admin",
89
- "SONICWALL_PASSWORD": "your_password",
90
- "SONICWALL_SSL_VERIFY": "false",
91
- "SONICWALL_READWRITE": "true"
92
- }
93
- }
94
- }
95
- }
96
- ```
97
-
98
- **Using uvx directly:**
99
-
100
- ```json
101
- {
102
- "mcpServers": {
103
- "sonicwall": {
104
- "command": "uvx",
105
- "args": ["sonicwall-mcp-server"],
106
- "env": {
107
- "SONICWALL_HOST": "192.168.168.168",
108
- "SONICWALL_USERNAME": "admin",
109
- "SONICWALL_PASSWORD": "your_password",
110
- "SONICWALL_SSL_VERIFY": "false",
111
- "SONICWALL_READWRITE": "true"
112
- }
113
- }
114
- }
115
- }
116
- ```
117
-
118
- **Using the installed Python CLI:**
119
-
120
- ```json
121
- {
122
- "mcpServers": {
123
- "sonicwall": {
124
- "command": "sonicwall-mcp",
125
- "env": {
126
- "SONICWALL_HOST": "192.168.168.168",
127
- "SONICWALL_USERNAME": "admin",
128
- "SONICWALL_PASSWORD": "your_password",
129
- "SONICWALL_SSL_VERIFY": "false",
130
- "SONICWALL_READWRITE": "true"
131
- }
132
- }
133
- }
134
- }
135
- ```
136
-
137
- ### Multi-device setup
138
-
139
- To manage multiple appliances, set `SONICWALL_DEVICES_FILE` to a JSON file:
140
-
141
- ```json
142
- [
143
- {
144
- "name": "site-a",
145
- "host": "10.0.1.1",
146
- "username": "admin",
147
- "password": "secret",
148
- "ssl_verify": false,
149
- "read_only": false
150
- },
151
- {
152
- "name": "site-b",
153
- "host": "10.0.2.1",
154
- "username": "admin",
155
- "password": "secret",
156
- "ssl_verify": false,
157
- "read_only": true
158
- }
159
- ]
160
- ```
161
-
162
- Pass `device="site-b"` to any tool to target a specific appliance; omit it to use the first device.
163
-
164
- ### Development
165
-
166
- ```bash
167
- uv venv && source .venv/bin/activate
168
- uv pip install -e ".[dev]"
169
- pytest tests/ -v # unit tests (no appliance needed)
170
- mcp dev src/sonicwall_mcp/server.py # interactive MCP inspector
171
- ```
172
-
173
- ## Agent guidance
174
-
175
- The server supplies MCP `instructions` that are automatically delivered to the calling agent at session start. These cover:
176
-
177
- - **Staged configuration** — always `commit_config` after a related set of changes, or `discard_config` to abandon
178
- - **Datetime handling** — log timestamps use the appliance's local timezone; no UTC conversion needed
25
+
26
+ ### Diagnosing an unreachable IP
27
+
28
+ Use `diagnose_ip` for a combined report containing the appliance's selected network path, configured interfaces and route policies, matching ARP entry, ping result, and traceroute. Set `interface` to force the live tests through an interface such as `X1`, or set `include_traceroute=false` for a faster check. The focused tools `find_network_path`, `lookup_arp`, `ping_from_appliance`, and `traceroute_from_appliance` are also available. Diagnostic POST actions are read-only and work without enabling `SONICWALL_READWRITE`.
29
+
30
+ Supports SonicOS 6.5.x, 7.x, and 8.x with automatic version detection.
31
+
32
+ ## Quick Start
33
+
34
+ ### Prerequisites
35
+
36
+ - A SonicWall NSA appliance running SonicOS 6.5, 7.x, or 8.x
37
+ - SonicOS API enabled: **Device › Settings › Administration › SonicOS API** — toggle **SonicOS API** on, and ensure **RFC-2617 HTTP Basic Access authentication** is also enabled (the MCP server uses Basic auth to obtain a session token, falling back to RFC-7616 Digest if Basic is disabled)
38
+ - For npm install: [Node.js ≥ 18](https://nodejs.org/) and [uv](https://docs.astral.sh/uv/)
39
+ - For Python install: Python ≥ 3.11
40
+
41
+ ### Install
42
+
43
+ **Via npx (recommended — no Python setup required):**
44
+
45
+ ```bash
46
+ npx @teamnetwork-nz/sonicwall-api-mcp-server
47
+ ```
48
+
49
+ > The npm package is a thin launcher that calls `uvx sonicwall-mcp-server` under the hood. Only [uv](https://docs.astral.sh/uv/) needs to be installed — no Python environment setup required.
50
+
51
+ **Via pip / uv (Python):**
52
+
53
+ ```bash
54
+ pip install sonicwall-mcp-server
55
+ # or
56
+ uv pip install sonicwall-mcp-server
57
+ ```
58
+
59
+ ### Environment variables
60
+
61
+ | Variable | Required | Default | Description |
62
+ |----------|----------|---------|-------------|
63
+ | `SONICWALL_HOST` | Yes | — | Appliance IP or hostname |
64
+ | `SONICWALL_USERNAME` | Yes | — | Admin username |
65
+ | `SONICWALL_PASSWORD` | Yes | — | Admin password |
66
+ | `SONICWALL_PORT` | No | `443` | HTTPS management port |
67
+ | `SONICWALL_SSL_VERIFY` | No | `true` | Set `false` for self-signed certificates |
68
+ | `SONICWALL_READWRITE` | No | `false` | Set `true` to allow write operations |
69
+
70
+ `SONICWALL_READ_ONLY=false` remains a deprecated compatibility alias for one release. `SONICWALL_READWRITE` takes precedence when both are set.
71
+ | `SONICWALL_DEVICES_FILE` | No | — | Path to JSON file for multi-device config |
72
+ | `SONICWALL_REQUEST_TIMEOUT` | No | `30.0` | Per-request timeout in seconds |
73
+
74
+ Copy `.env.example` to `.env` for local development.
75
+
76
+ ### Claude Desktop / Claude Code Integration
77
+
78
+ Add to your MCP config (`claude_desktop_config.json` or `.claude/settings.json`):
79
+
80
+ **Using npx (easiest):**
81
+
82
+ ```json
83
+ {
84
+ "mcpServers": {
85
+ "sonicwall": {
86
+ "command": "npx",
87
+ "args": ["-y", "@teamnetwork-nz/sonicwall-api-mcp-server"],
88
+ "env": {
89
+ "SONICWALL_HOST": "192.168.168.168",
90
+ "SONICWALL_USERNAME": "admin",
91
+ "SONICWALL_PASSWORD": "your_password",
92
+ "SONICWALL_SSL_VERIFY": "false",
93
+ "SONICWALL_READWRITE": "true"
94
+ }
95
+ }
96
+ }
97
+ }
98
+ ```
99
+
100
+ **Using uvx directly:**
101
+
102
+ ```json
103
+ {
104
+ "mcpServers": {
105
+ "sonicwall": {
106
+ "command": "uvx",
107
+ "args": ["sonicwall-mcp-server"],
108
+ "env": {
109
+ "SONICWALL_HOST": "192.168.168.168",
110
+ "SONICWALL_USERNAME": "admin",
111
+ "SONICWALL_PASSWORD": "your_password",
112
+ "SONICWALL_SSL_VERIFY": "false",
113
+ "SONICWALL_READWRITE": "true"
114
+ }
115
+ }
116
+ }
117
+ }
118
+ ```
119
+
120
+ **Using the installed Python CLI:**
121
+
122
+ ```json
123
+ {
124
+ "mcpServers": {
125
+ "sonicwall": {
126
+ "command": "sonicwall-mcp",
127
+ "env": {
128
+ "SONICWALL_HOST": "192.168.168.168",
129
+ "SONICWALL_USERNAME": "admin",
130
+ "SONICWALL_PASSWORD": "your_password",
131
+ "SONICWALL_SSL_VERIFY": "false",
132
+ "SONICWALL_READWRITE": "true"
133
+ }
134
+ }
135
+ }
136
+ }
137
+ ```
138
+
139
+ ### Multi-device setup
140
+
141
+ To manage multiple appliances, set `SONICWALL_DEVICES_FILE` to a JSON file:
142
+
143
+ ```json
144
+ [
145
+ {
146
+ "name": "site-a",
147
+ "host": "10.0.1.1",
148
+ "username": "admin",
149
+ "password": "secret",
150
+ "ssl_verify": false,
151
+ "read_only": false
152
+ },
153
+ {
154
+ "name": "site-b",
155
+ "host": "10.0.2.1",
156
+ "username": "admin",
157
+ "password": "secret",
158
+ "ssl_verify": false,
159
+ "read_only": true
160
+ }
161
+ ]
162
+ ```
163
+
164
+ Pass `device="site-b"` to any tool to target a specific appliance; omit it to use the first device.
165
+
166
+ ### Development
167
+
168
+ ```bash
169
+ uv venv && source .venv/bin/activate
170
+ uv pip install -e ".[dev]"
171
+ pytest debug/tests/ -v # unit tests (no appliance needed)
172
+ mcp dev src/sonicwall_mcp/server.py # interactive MCP inspector
173
+ ```
174
+
175
+ ## Agent guidance
176
+
177
+ The server supplies MCP `instructions` that are automatically delivered to the calling agent at session start. These cover:
178
+
179
+ - **Staged configuration** — always `commit_config` after a related set of changes, or `discard_config` to abandon
180
+ - **Datetime handling** — log timestamps use the appliance's local timezone; no UTC conversion needed
179
181
  - **Log configuration scope** — log tools expose categories and event definitions, not searchable runtime history
180
- - **Object and rule management** — recommended workflow for creating address objects and firewall rules
181
- - **Concurrent sessions** — SonicOS limit of one active API session per appliance
182
-
183
- No special prompting is required — the agent receives these guidelines automatically.
184
-
185
- ## Important Notes
186
-
187
- - SonicOS allows only **one concurrent API session** per appliance. Ensure no other admin sessions are active when using this server.
188
- - All configuration changes (create/update/delete) are **staged** and do not take effect until you call `commit_config`. Use `discard_config` to abandon staged changes.
189
- - Enable the SonicOS API in the appliance web UI: **DEVICE > Settings > Administration > SonicOS API**.
182
+ - **Object and rule management** — recommended workflow for creating address objects and firewall rules
183
+ - **Concurrent sessions** — SonicOS limit of one active API session per appliance
184
+
185
+ No special prompting is required — the agent receives these guidelines automatically.
186
+
187
+ ## Important Notes
188
+
189
+ - SonicOS allows only **one concurrent API session** per appliance. Ensure no other admin sessions are active when using this server.
190
+ - All configuration changes (create/update/delete) are **staged** and do not take effect until you call `commit_config`. Use `discard_config` to abandon staged changes.
191
+ - Enable the SonicOS API in the appliance web UI: **DEVICE > Settings > Administration > SonicOS API**.
192
+
193
+ <!-- BEGIN MCP configuration reference -->
194
+ ## Environment variable reference
195
+
196
+ The server does **not** automatically load `.env`. Inject these variables through the MCP client or process environment; copying the example alone does not configure the server.
197
+
198
+ Copy `.env.example` for variable names and safe placeholders. Replace required placeholders privately. Optional variables should be omitted unless needed; an empty value may override a default. Never commit credentials, real identities, device profiles, exports, or logs.
199
+
200
+ | Variable | Required | Default | Purpose and accepted values |
201
+ |---|---|---|---|
202
+ | `SONICWALL_DEVICES_FILE` | Alternative | `unset` | Private JSON device-profile array; replaces single-device credentials and settings, including per-profile read_only. |
203
+ | `SONICWALL_DEVICE_NAME` | No | `default` | Local name for the single-device profile. |
204
+ | `SONICWALL_HOST` | Conditional | `unset` | Firewall hostname; required unless SONICWALL_DEVICES_FILE is set. |
205
+ | `SONICWALL_HTTP_ALLOWED_HOSTS` | Conditional | `unset` | Comma-separated Host allowlist required for non-loopback HTTP; use the public hostnames accepted by the listener. |
206
+ | `SONICWALL_HTTP_ALLOWED_ORIGINS` | No | `unset` | Comma-separated browser Origin allowlist; configure when browser clients need access. |
207
+ | `SONICWALL_HTTP_BEARER_TOKEN` | Conditional | `unset` | Private bearer secret required for non-loopback HTTP; clients send Authorization: Bearer <secret>. |
208
+ | `SONICWALL_HTTP_HOST` | No | `127.0.0.1` | Listener bind address. Non-loopback binding requires a bearer token and explicit allowed hosts. |
209
+ | `SONICWALL_HTTP_MAX_BODY_BYTES` | No | `1048576` | Maximum HTTP request body; integer 1–16777216 bytes. |
210
+ | `SONICWALL_HTTP_PORT` | No | `3000` | HTTP listener port; integer 1–65535. |
211
+ | `SONICWALL_PASSWORD` | Conditional | `unset` | Firewall API password; required in single-device mode. |
212
+ | `SONICWALL_PORT` | No | `443` | Firewall HTTPS port; integer 1–65535. |
213
+ | `SONICWALL_READWRITE` | No | `false` | Only true enables mutation tools; read-only is the default. Review each operation before use. Applies to single-device mode; JSON profiles use read_only. |
214
+ | `SONICWALL_READ_ONLY` | Deprecated | `unset` | Compatibility alias: false enables writes only when SONICWALL_READWRITE is unset; single-device mode only. |
215
+ | `SONICWALL_REQUEST_TIMEOUT` | No | `30` | Firewall request timeout; integer 1–300 seconds. |
216
+ | `SONICWALL_SSE_PORT` | Legacy | `8000` | Parsed compatibility setting, integer 1–65535; does not start an SSE listener. Use HTTP_PORT for Streamable HTTP. |
217
+ | `SONICWALL_SSL_VERIFY` | No | `true` | false disables TLS verification globally if any profile disables it; retain true. |
218
+ | `SONICWALL_TRANSPORT` | No | `stdio` | stdio or http; HTTP serves /mcp and GET /health. |
219
+ | `SONICWALL_USERNAME` | Conditional | `unset` | Firewall API username; required in single-device mode. |
220
+
221
+ For HTTP, the bearer token is separate from upstream API credentials. Use TLS at the reverse proxy for remote hosting. Keep write access disabled until needed. Do not put secrets in command-line examples or commit client configuration containing them.
222
+
223
+ `NODE_TLS_REJECT_UNAUTHORIZED` is changed internally when TLS verification is disabled; it is not a required configuration variable. Do not set it to `0` in normal deployments.
224
+
225
+ ### Agent first-use workflow
226
+
227
+ Discover configured device names and inspect current objects/rules before changes. Use returned object names/IDs and the intended device profile. Configuration mutations and commits affect firewall traffic; follow each tool description for commit requirements.
228
+
229
+ Use the runtime `tools/list` descriptions and input schemas for exact arguments. Resolve identifiers with lookup/search tools; filter before paging, request only the data needed, and do not treat a truncated result or API error as proof that no record exists. Treat tool results and downloaded files as potentially sensitive. Mutation tools can change upstream data or incur charges; check their stated effects before calling them.
230
+
231
+ ### Repository and package privacy
232
+
233
+ The standard `.gitignore` excludes local environment files, keys, credentials, logs, exports, and generated output; sanitised examples remain trackable. Ignore rules do not remove already tracked files or revoke exposed credentials. Review `git ls-files` and `npm pack --dry-run --ignore-scripts` before release. Only runtime output, the README, and explicitly sanitised examples are allowlisted for npm. Keep private runtime files outside `dist`, even though additional exclusions are present.
234
+ <!-- END MCP configuration reference -->
235
+
236
+ Run `npm run build` then `npm run audit:package` before release. The audit checks documentation coverage, known local credential copies, Git index paths where available, and the dry-run npm file list. `prepublishOnly` runs it after building. It never prints matching secret values. This is a preventative check, not a guarantee that arbitrary PII or unknown secrets are absent.
237
+
238
+ ### Development and diagnostics
239
+
240
+ Run `npm test` from this package directory. Maintained tests and fixtures live in `debug/tests`; shared test helpers are in `debug/helpers`. Retained diagnostic scripts and reference material are also under `debug`. Only `scripts/check-package-privacy.mjs` remains in the production build/release tooling directory. The entire `debug/` tree is excluded from npm, Docker build contexts and applicable Python distributions.
241
+
242
+ Keep live diagnostic output in `debug/local`, `debug/output` or `debug/artifacts`; those private directories are also ignored by Git. Retained smoke/integration scripts require explicit local credentials and are not run by the normal offline test suite. Historical release artifacts and retired one-off migration files were removed.
package/dist/index.js CHANGED
@@ -2317,11 +2317,40 @@ function strictSchema(schema) {
2317
2317
  if (isSchema(schema) && typeof schema.strict === "function") return schema.strict();
2318
2318
  return schema;
2319
2319
  }
2320
+ function addOutputFormat(schema) {
2321
+ const strict = strictSchema(schema);
2322
+ if (typeof strict.extend !== "function") return strict;
2323
+ return strict.extend({
2324
+ outputFormat: import_v317.z.enum(["json"]).optional().describe("Return the result as valid JSON text without Markdown wrappers.")
2325
+ }).strict?.() ?? strict;
2326
+ }
2327
+ function toJsonValue(text2) {
2328
+ const fenced = text2.match(/\x60\x60\x60json\s*([\s\S]*?)\s*\x60\x60\x60/i)?.[1];
2329
+ const candidate = fenced ?? text2;
2330
+ try {
2331
+ return JSON.parse(candidate);
2332
+ } catch {
2333
+ return text2;
2334
+ }
2335
+ }
2320
2336
  function enforceStrictToolInputs(server) {
2321
2337
  const mutable = server;
2322
2338
  const createRegisteredTool = mutable._createRegisteredTool.bind(server);
2323
2339
  mutable._createRegisteredTool = (...args) => {
2324
- args[3] = strictSchema(args[3]);
2340
+ args[3] = addOutputFormat(args[3]);
2341
+ const handler = args[8];
2342
+ if (typeof handler === "function") {
2343
+ args[8] = async (input, ...rest) => {
2344
+ const values = input && typeof input === "object" ? input : {};
2345
+ const { outputFormat, ...toolArgs } = values;
2346
+ const result = await handler(toolArgs, ...rest);
2347
+ if (outputFormat !== "json" || result?.isError || !Array.isArray(result?.content)) return result;
2348
+ const textItems = result.content.filter((item) => item.type === "text" && typeof item.text === "string");
2349
+ if (textItems.length === 0) return result;
2350
+ const data = result.structuredContent !== void 0 ? result.structuredContent : textItems.length === 1 ? toJsonValue(textItems[0]?.text ?? "") : textItems.map((item) => toJsonValue(item.text));
2351
+ return { ...result, content: [{ type: "text", text: JSON.stringify(data, null, 2) }], ...result.structuredContent === void 0 && data && typeof data === "object" ? { structuredContent: data } : {} };
2352
+ };
2353
+ }
2325
2354
  return createRegisteredTool(...args);
2326
2355
  };
2327
2356
  }
@@ -39,11 +39,40 @@ function strictSchema(schema) {
39
39
  if (isSchema(schema) && typeof schema.strict === "function") return schema.strict();
40
40
  return schema;
41
41
  }
42
+ function addOutputFormat(schema) {
43
+ const strict = strictSchema(schema);
44
+ if (typeof strict.extend !== "function") return strict;
45
+ return strict.extend({
46
+ outputFormat: import_v3.z.enum(["json"]).optional().describe("Return the result as valid JSON text without Markdown wrappers.")
47
+ }).strict?.() ?? strict;
48
+ }
49
+ function toJsonValue(text) {
50
+ const fenced = text.match(/\x60\x60\x60json\s*([\s\S]*?)\s*\x60\x60\x60/i)?.[1];
51
+ const candidate = fenced ?? text;
52
+ try {
53
+ return JSON.parse(candidate);
54
+ } catch {
55
+ return text;
56
+ }
57
+ }
42
58
  function enforceStrictToolInputs(server) {
43
59
  const mutable = server;
44
60
  const createRegisteredTool = mutable._createRegisteredTool.bind(server);
45
61
  mutable._createRegisteredTool = (...args) => {
46
- args[3] = strictSchema(args[3]);
62
+ args[3] = addOutputFormat(args[3]);
63
+ const handler = args[8];
64
+ if (typeof handler === "function") {
65
+ args[8] = async (input, ...rest) => {
66
+ const values = input && typeof input === "object" ? input : {};
67
+ const { outputFormat, ...toolArgs } = values;
68
+ const result = await handler(toolArgs, ...rest);
69
+ if (outputFormat !== "json" || result?.isError || !Array.isArray(result?.content)) return result;
70
+ const textItems = result.content.filter((item) => item.type === "text" && typeof item.text === "string");
71
+ if (textItems.length === 0) return result;
72
+ const data = result.structuredContent !== void 0 ? result.structuredContent : textItems.length === 1 ? toJsonValue(textItems[0]?.text ?? "") : textItems.map((item) => toJsonValue(item.text));
73
+ return { ...result, content: [{ type: "text", text: JSON.stringify(data, null, 2) }], ...result.structuredContent === void 0 && data && typeof data === "object" ? { structuredContent: data } : {} };
74
+ };
75
+ }
47
76
  return createRegisteredTool(...args);
48
77
  };
49
78
  }
package/package.json CHANGED
@@ -1,52 +1,53 @@
1
- {
2
- "name": "@teamnetwork-nz/sonicwall-api-mcp-server",
3
- "version": "0.9.1",
4
- "description": "MCP server for SonicWall appliance configuration and diagnostics \u2014 objects, rules, NAT, routing, reachability, and GeoIP lookup",
5
- "keywords": [
6
- "mcp",
7
- "model-context-protocol",
8
- "sonicwall",
9
- "firewall",
10
- "sonicOS",
11
- "api",
12
- "network",
13
- "security"
14
- ],
15
- "homepage": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server",
16
- "bugs": {
17
- "url": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server/issues"
18
- },
19
- "license": "MIT",
20
- "author": "Daryl",
21
- "repository": {
22
- "type": "git",
23
- "url": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server.git"
24
- },
25
- "main": "dist/index.js",
26
- "bin": {
27
- "sonicwall-mcp": "./dist/index.js"
28
- },
29
- "files": [
30
- "dist/",
31
- "README.md",
32
- "LICENSE"
33
- ],
34
- "scripts": {
35
- "build": "tsup",
36
- "test": "npm run build && node --test tests/*.test.mjs",
37
- "prepublishOnly": "npm run build",
38
- "start": "node dist/index.js"
39
- },
40
- "engines": {
41
- "node": ">=18"
42
- },
43
- "dependencies": {
44
- "@modelcontextprotocol/sdk": "^1.32.2",
45
- "zod": "^4.6.7"
46
- },
47
- "devDependencies": {
48
- "@types/node": "^20.0.0",
49
- "tsup": "^8.0.0",
50
- "typescript": "^5.4.0"
51
- }
52
- }
1
+ {
2
+ "name": "@teamnetwork-nz/sonicwall-api-mcp-server",
3
+ "version": "0.10.0",
4
+ "description": "MCP server for SonicWall appliance configuration and diagnostics — objects, rules, NAT, routing, reachability, and GeoIP lookup",
5
+ "keywords": [
6
+ "mcp",
7
+ "model-context-protocol",
8
+ "sonicwall",
9
+ "firewall",
10
+ "sonicOS",
11
+ "api",
12
+ "network",
13
+ "security"
14
+ ],
15
+ "homepage": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server",
16
+ "bugs": {
17
+ "url": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server/issues"
18
+ },
19
+ "license": "MIT",
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "https://github.com/teamnetwork-nz/sonicwall-api-mcp-server.git"
23
+ },
24
+ "main": "dist/index.js",
25
+ "bin": {
26
+ "sonicwall-mcp": "./dist/index.js"
27
+ },
28
+ "files": [
29
+ "dist/**/*.js",
30
+ "dist/**/*.d.ts",
31
+ "README.md",
32
+ ".env.example"
33
+ ],
34
+ "scripts": {
35
+ "build": "tsup",
36
+ "test": "npm run build && node --test debug/tests/*.test.mjs",
37
+ "prepublishOnly": "npm run build && npm run audit:package",
38
+ "start": "node dist/index.js",
39
+ "audit:package": "node scripts/check-package-privacy.mjs"
40
+ },
41
+ "engines": {
42
+ "node": ">=18"
43
+ },
44
+ "dependencies": {
45
+ "@modelcontextprotocol/sdk": "^1.32.2",
46
+ "zod": "^4.6.7"
47
+ },
48
+ "devDependencies": {
49
+ "@types/node": "^20.0.0",
50
+ "tsup": "^8.0.0",
51
+ "typescript": "^5.4.0"
52
+ }
53
+ }