netconverter-cli 0.4.3__tar.gz → 0.4.4__tar.gz
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.
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/CHANGELOG.md +71 -0
- netconverter_cli-0.4.4/LICENSE +61 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/PKG-INFO +24 -5
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/README.md +22 -3
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/COMMANDS.md +70 -13
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/PRIVACY.md +15 -3
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/RELEASING.md +1 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/README.md +2 -1
- netconverter_cli-0.4.4/docs/connect/openclaw.md +50 -0
- netconverter_cli-0.4.4/docs/guided-workflows.md +287 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/pyproject.toml +7 -3
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/__init__.py +1 -1
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/api.py +11 -1
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/backend.py +10 -4
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/branding.py +1 -1
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/clerk.py +30 -12
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/cli.py +291 -74
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/commands.py +4 -3
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/connect.py +86 -23
- netconverter_cli-0.4.4/src/netconverter_cli/connect_openclaw.py +136 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/controller.py +22 -2
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/credentials.py +83 -14
- netconverter_cli-0.4.4/src/netconverter_cli/design_catalog.py +10 -0
- netconverter_cli-0.4.4/src/netconverter_cli/draft_cli.py +102 -0
- netconverter_cli-0.4.4/src/netconverter_cli/draft_io.py +215 -0
- netconverter_cli-0.4.4/src/netconverter_cli/drafts.py +697 -0
- netconverter_cli-0.4.4/src/netconverter_cli/errors.py +95 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/guided.py +43 -5
- netconverter_cli-0.4.4/src/netconverter_cli/guided_operations.json +319 -0
- netconverter_cli-0.4.4/src/netconverter_cli/guided_projects.json +605 -0
- netconverter_cli-0.4.4/src/netconverter_cli/job_options.py +230 -0
- netconverter_cli-0.4.4/src/netconverter_cli/license.py +211 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/mcp_server.py +296 -28
- netconverter_cli-0.4.4/src/netconverter_cli/mcp_workflows.py +246 -0
- netconverter_cli-0.4.4/src/netconverter_cli/one_shot.py +45 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/presentation.py +23 -3
- netconverter_cli-0.4.4/src/netconverter_cli/project_cli.py +46 -0
- netconverter_cli-0.4.4/src/netconverter_cli/projects.py +81 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/setup.py +2 -1
- netconverter_cli-0.4.4/src/netconverter_cli/summary.py +417 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/tui.py +32 -15
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/update.py +7 -2
- netconverter_cli-0.4.4/src/netconverter_cli/walkthrough.py +100 -0
- netconverter_cli-0.4.4/src/netconverter_cli/windows_draft_io.py +378 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/conftest.py +6 -0
- netconverter_cli-0.4.4/tests/fixtures/jobs/opt_4056e02e5b66.json +73 -0
- netconverter_cli-0.4.4/tests/fixtures/jobs/tra_4058ef406cd6.json +29 -0
- netconverter_cli-0.4.4/tests/fixtures/jobs/tra_running.json +17 -0
- netconverter_cli-0.4.4/tests/fixtures/jobs/val_9f9acb9b5a59.json +146 -0
- netconverter_cli-0.4.4/tests/fixtures/jobs/val_9f9acb9b5a59.sarif +92 -0
- netconverter_cli-0.4.4/tests/test_autodetect_v5.py +127 -0
- netconverter_cli-0.4.4/tests/test_bridge_polish_021.py +69 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_clerk.py +21 -2
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_cli_020.py +2 -1
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_connect_030.py +1 -1
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_connect_031.py +1 -1
- netconverter_cli-0.4.4/tests/test_connect_direct_entry.py +79 -0
- netconverter_cli-0.4.4/tests/test_connect_openclaw_014.py +128 -0
- netconverter_cli-0.4.4/tests/test_draft_cli.py +224 -0
- netconverter_cli-0.4.4/tests/test_draft_io.py +198 -0
- netconverter_cli-0.4.4/tests/test_draft_jobs.py +392 -0
- netconverter_cli-0.4.4/tests/test_drafts.py +496 -0
- netconverter_cli-0.4.4/tests/test_errors_009.py +304 -0
- netconverter_cli-0.4.4/tests/test_help_008.py +177 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_keyring_bus_017.py +2 -1
- netconverter_cli-0.4.4/tests/test_keyring_timeout_010.py +115 -0
- netconverter_cli-0.4.4/tests/test_license.py +105 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_mcp.py +36 -10
- netconverter_cli-0.4.4/tests/test_mcp_jobs.py +286 -0
- netconverter_cli-0.4.4/tests/test_mcp_workflows.py +396 -0
- netconverter_cli-0.4.4/tests/test_options_011_019.py +186 -0
- netconverter_cli-0.4.4/tests/test_polish_028.py +60 -0
- netconverter_cli-0.4.4/tests/test_projects.py +212 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_signin_default.py +2 -2
- netconverter_cli-0.4.4/tests/test_stage_029.py +80 -0
- netconverter_cli-0.4.4/tests/test_strict_default_011.py +84 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_strict_view_015.py +4 -0
- netconverter_cli-0.4.4/tests/test_summary_007.py +254 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_update.py +3 -3
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_vendor_error_022.py +3 -3
- netconverter_cli-0.4.4/tests/test_walkthrough.py +77 -0
- netconverter_cli-0.4.4/tests/test_windows_draft_io.py +305 -0
- netconverter_cli-0.4.3/LICENSE +0 -21
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/.gitignore +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/QUICK_START.md +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/SECURITY.md +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/VERIFICATION.md +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/chatgpt.md +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/claude-ai.md +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/claude-code.md +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/claude-desktop.md +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/getting-access.md +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/other-assistants.md +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/examples/README.md +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/activity.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/catalog.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/palette.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/privacy.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/providers.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/remote_mcp.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/workspace.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_boundaries.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_clerk_host_binding.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_download_analysis.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_folders_cd_ls.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_inline.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_mcp_auth_016.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_presentation.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_protocols.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_readonly_workspace.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_sessions.py +0 -0
- {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_setup.py +0 -0
|
@@ -1,5 +1,76 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.4.4 — 2026-10-29
|
|
4
|
+
|
|
5
|
+
**License change.** From 0.4.4 the client is licensed by ValeronLabs LLC for use with
|
|
6
|
+
your NetConverter account only; it may not be redistributed or modified (see LICENSE).
|
|
7
|
+
Versions up to 0.4.3 were MIT licensed. On first run the client shows the license and
|
|
8
|
+
asks you to type `accept`; scripts and containers use `netconverter license accept --yes`
|
|
9
|
+
or `NETCONVERTER_ACCEPT_LICENSE=1`. Until it is accepted, `netconverter mcp` answers every
|
|
10
|
+
tool call with how to accept it.
|
|
11
|
+
|
|
12
|
+
**Upgrade note.** `netconverter mcp` now serves the strict view by default; add `--full`
|
|
13
|
+
(or set `NETCONVERTER_MCP_VIEW=full`) if you relied on the wider view. `connect` writes
|
|
14
|
+
`--strict` for every assistant. Errors now go to stderr with distinct exit codes.
|
|
15
|
+
|
|
16
|
+
- New: `netconverter walkthrough` and `/walkthrough`, a short guided tour of jobs, privacy
|
|
17
|
+
and AI integrations.
|
|
18
|
+
- New: `netconverter license` (`show`, `accept`, `status`).
|
|
19
|
+
- `connect` leaves one NetConverter server per assistant: it removes older bridge entries
|
|
20
|
+
and direct `api.netconverter.ai` entries (which NetConverter now refuses) from Cursor,
|
|
21
|
+
Claude Desktop, Gemini CLI, Windsurf and LM Studio, keeping every other server.
|
|
22
|
+
- New: `netconverter connect openclaw` (with `--remove`).
|
|
23
|
+
- convert / validate / optimize / resume print a short plain summary (verdict ready /
|
|
24
|
+
needs review / blocked, counts, first findings, next command); `--json` gives the raw
|
|
25
|
+
response and `--all` lists every finding. The app's job card shows a scorecard.
|
|
26
|
+
- `netconverter query unparsed_lines` (app: `/unparsed_lines`) lists unparsed lines.
|
|
27
|
+
- Job options are checked against a typed allowlist before upload; unknown keys and
|
|
28
|
+
request fields are refused by name. Guided conversion settings reach the full API as a
|
|
29
|
+
YAML v2 document instead of being silently ignored.
|
|
30
|
+
- `job_status` and `wait_for_job` report the job stage.
|
|
31
|
+
- Ctrl-C prints "Cancelled. Nothing was saved." and exits 130. Errors give the specific
|
|
32
|
+
reason (file, `--options`, the server's reason); exit codes 2 usage, 3 sign-in, 4 input,
|
|
33
|
+
5 server (docs/COMMANDS.md). A 403 says what your credential is missing.
|
|
34
|
+
- A locked system keyring is reported after 5 s instead of hanging
|
|
35
|
+
(`NETCONVERTER_KEYRING_TIMEOUT_S`); one signed-out message everywhere.
|
|
36
|
+
- Help text for every command and option, "Did you mean …?" for typos, valid vendor
|
|
37
|
+
codes when `--vendor` is missing, `--to` only on `convert`.
|
|
38
|
+
- App: `/refresh` (`/allowance` still works), the /help footer, `/ls` titles use `~/`.
|
|
39
|
+
- `update --check` prints a plain line (`--json` for JSON); one-shot JSON keeps "→".
|
|
40
|
+
- Auto-detect: Cisco switches no longer read as ArubaOS; IOS-XE switch vs router from the
|
|
41
|
+
content; NX-OS and SRX reported as unsupported.
|
|
42
|
+
- Bridge: clearer options-size refusal, `account` reports a signed-out status, and
|
|
43
|
+
signing in works without restarting the bridge.
|
|
44
|
+
|
|
45
|
+
- **Candidate multi-device project adapters (development preview).** New `project`
|
|
46
|
+
commands and capability-gated guided MCP tools use generated server schemas,
|
|
47
|
+
explicit frozen device revisions and complete link proposals. Bounded evidence
|
|
48
|
+
preserves missing decisions and staleness, verifies snapshot/evidence hashes,
|
|
49
|
+
and never grants project approval or execution. Server opt-in and deployment,
|
|
50
|
+
target/runtime qualification and real desktop acceptance remain required.
|
|
51
|
+
|
|
52
|
+
- **Typed migration proposals (development preview).** A generated server catalog
|
|
53
|
+
describes interface/zone mappings, source scope and explicit policy options.
|
|
54
|
+
CLI and guided MCP validate complete batches and require a matching server
|
|
55
|
+
catalog before submission. Bounded, paginated interface context separates observed
|
|
56
|
+
source fields from desired mappings and reports incomplete decision requirements.
|
|
57
|
+
Routing redesign remains planned; these additions
|
|
58
|
+
do not establish production, Windows or desktop-client qualification.
|
|
59
|
+
|
|
60
|
+
- **Guided draft client foundation (development preview).** `draft` commands and
|
|
61
|
+
`mcp --guided` use explicit revisions, direct local YAML transfer and independent
|
|
62
|
+
human approval references. Every operation requires a fresh versioned server
|
|
63
|
+
capability; unsupported servers refuse before upload. Guided mode refuses legacy
|
|
64
|
+
submission. This is not production/server qualification; Windows secure file IO
|
|
65
|
+
remains pending. Guided job status/wait and generated-artifact downloads bind the
|
|
66
|
+
job, draft revision and manifest; bounded streams verify length and SHA-256 before
|
|
67
|
+
saving without overwriting. See [contract](docs/guided-workflows.md).
|
|
68
|
+
|
|
69
|
+
- **`whoami` never shows an organization's raw id (#685).** An organization with no name
|
|
70
|
+
and no slug is listed as `(unnamed organization)` instead of its `org_…` id. The active
|
|
71
|
+
organization and its membership entry are the same organization and show once, with the
|
|
72
|
+
name if either entry carries one.
|
|
73
|
+
|
|
3
74
|
## 0.4.3 — 2026-10-23
|
|
4
75
|
|
|
5
76
|
- **Move between folders in the terminal app.** `/ls [FOLDER]` (or `/dir`) lists files and
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
NetConverter Terminal Client License
|
|
2
|
+
Version 1.0, effective 2026-10-29
|
|
3
|
+
|
|
4
|
+
Copyright (c) 2026 ValeronLabs LLC. All rights reserved.
|
|
5
|
+
|
|
6
|
+
This license applies to the NetConverter terminal client ("the Software"),
|
|
7
|
+
version 0.4.4 and later, including its source code, documentation and
|
|
8
|
+
installers. Versions 0.4.3 and earlier were released under the MIT License;
|
|
9
|
+
copies of those versions obtained before this license took effect keep the
|
|
10
|
+
MIT terms.
|
|
11
|
+
|
|
12
|
+
1. Grant
|
|
13
|
+
ValeronLabs LLC ("ValeronLabs") grants you a limited, non-exclusive,
|
|
14
|
+
non-transferable, revocable license to install and run the Software on
|
|
15
|
+
devices you control, solely to use NetConverter services under a valid
|
|
16
|
+
NetConverter account, for your own internal business purposes.
|
|
17
|
+
|
|
18
|
+
2. Restrictions
|
|
19
|
+
You may not, and may not permit anyone else to:
|
|
20
|
+
a. copy, distribute, publish, sublicense, sell, rent, lease, lend or
|
|
21
|
+
otherwise make the Software available to any third party, including by
|
|
22
|
+
hosting it for others or bundling it with another product;
|
|
23
|
+
b. modify, adapt, translate or create derivative works of the Software;
|
|
24
|
+
c. remove or alter any copyright, license or proprietary notice;
|
|
25
|
+
d. circumvent or disable any security, authentication, usage limit or
|
|
26
|
+
license-acceptance mechanism of the Software or NetConverter services;
|
|
27
|
+
e. use the Software to build or train a competing product or service.
|
|
28
|
+
|
|
29
|
+
3. Source availability
|
|
30
|
+
The source code may be made available for transparency and security
|
|
31
|
+
review. Being able to read the source grants no right beyond Section 1.
|
|
32
|
+
|
|
33
|
+
4. Ownership
|
|
34
|
+
ValeronLabs and its licensors own the Software and all intellectual
|
|
35
|
+
property rights in it. No rights are granted except those stated here.
|
|
36
|
+
If you send feedback, ValeronLabs may use it without obligation to you.
|
|
37
|
+
|
|
38
|
+
5. Third-party components
|
|
39
|
+
Third-party components included with or required by the Software are
|
|
40
|
+
licensed under their own terms, which govern those components.
|
|
41
|
+
|
|
42
|
+
6. Termination
|
|
43
|
+
This license ends automatically if you breach it or when your NetConverter
|
|
44
|
+
account ends. On termination you must stop using the Software and delete
|
|
45
|
+
all copies in your possession or control.
|
|
46
|
+
|
|
47
|
+
7. No warranty
|
|
48
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
49
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
50
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
51
|
+
|
|
52
|
+
8. Limitation of liability
|
|
53
|
+
IN NO EVENT SHALL VALERONLABS OR ITS LICENSORS BE LIABLE FOR ANY CLAIM,
|
|
54
|
+
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
|
|
55
|
+
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
|
|
56
|
+
USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
57
|
+
|
|
58
|
+
Your use of NetConverter services is also subject to the NetConverter Terms
|
|
59
|
+
of Service and Privacy Policy at https://netconverter.ai.
|
|
60
|
+
|
|
61
|
+
Questions: contact@netconverter.ai
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: netconverter-cli
|
|
3
|
-
Version: 0.4.
|
|
3
|
+
Version: 0.4.4
|
|
4
4
|
Summary: NetConverter CLI — any-vendor network configuration migration, validation and optimization, and a local MCP bridge for your AI assistant
|
|
5
5
|
Project-URL: Homepage, https://netconverter.ai
|
|
6
6
|
Project-URL: Repository, https://github.com/valeronlabs/netconverter_terminals
|
|
@@ -8,7 +8,7 @@ Project-URL: Documentation, https://github.com/valeronlabs/netconverter_terminal
|
|
|
8
8
|
Project-URL: Issues, https://github.com/valeronlabs/netconverter_terminals/issues
|
|
9
9
|
Project-URL: Changelog, https://github.com/valeronlabs/netconverter_terminals/blob/main/CHANGELOG.md
|
|
10
10
|
Author-email: ValeronLabs LLC <contact@netconverter.ai>
|
|
11
|
-
License-Expression:
|
|
11
|
+
License-Expression: LicenseRef-NetConverter-Proprietary
|
|
12
12
|
License-File: LICENSE
|
|
13
13
|
Keywords: check-point,cisco,firewall,fortinet,mcp,migration,model-context-protocol,netconverter,network-automation,palo-alto
|
|
14
14
|
Classifier: Development Status :: 4 - Beta
|
|
@@ -41,7 +41,7 @@ Description-Content-Type: text/markdown
|
|
|
41
41
|
NetConverter — by ValeronLabs LLC.
|
|
42
42
|
|
|
43
43
|
```text
|
|
44
|
-
◆ NetConverter v0.
|
|
44
|
+
◆ NetConverter v0.4.4 ● Server ◆ Bridge claude-code · 2m ago
|
|
45
45
|
▍ Start
|
|
46
46
|
▍ /convert Migrate a configuration to another vendor
|
|
47
47
|
▍ /validate Check a configuration before migrating
|
|
@@ -78,6 +78,11 @@ Run `netconverter capabilities` to see exactly what your credential can do.
|
|
|
78
78
|
A 0.1.x **Terminal Quick pilot key** still works and keeps its ASA → Palo Alto
|
|
79
79
|
scope; the app labels it as such.
|
|
80
80
|
|
|
81
|
+
Development preview: [revisioned drafts and guided MCP](docs/guided-workflows.md)
|
|
82
|
+
adds an opt-in client contract for manual YAML, reviewed migration preparation,
|
|
83
|
+
job status and verified result downloads.
|
|
84
|
+
It requires explicit server support and is not enabled by an ordinary MCP connection.
|
|
85
|
+
|
|
81
86
|
## Start here
|
|
82
87
|
|
|
83
88
|
One line installs everything (uv, the CLI from PyPI), signs you in and connects
|
|
@@ -114,6 +119,10 @@ first. Saved keys and sign-ins carry over (Keychain service **NetConverter Termi
|
|
|
114
119
|
|
|
115
120
|
Full walkthrough: [Quick start](QUICK_START.md).
|
|
116
121
|
|
|
122
|
+
A YAML v2 decisions file (zone and interface mappings) rides along with a conversion:
|
|
123
|
+
`netconverter convert edge.cfg --vendor fortinet --to palo_alto_xml --options "$(jq -Rs '{yaml_v2: .}' decisions.yaml)"`,
|
|
124
|
+
or inline as `--options '{"yaml_v2": {...}}'`; see [docs/COMMANDS.md](docs/COMMANDS.md#yaml-v2-decisions-yaml_v2).
|
|
125
|
+
|
|
117
126
|
## Use it from your AI
|
|
118
127
|
|
|
119
128
|
Step-by-step guides for every assistant (Claude, ChatGPT, Cursor, Gemini CLI, Codex …):
|
|
@@ -134,7 +143,15 @@ Then ask your assistant, for example: *"Validate edge-fw.conf and tell me what i
|
|
|
134
143
|
|
|
135
144
|
Bridge tools: `submit_file`, `job_status`, `wait_for_job`, `account`, `download`,
|
|
136
145
|
plus an allowlist of NetConverter's read-only tools (reports, evidence, NAT, flows,
|
|
137
|
-
knowledge base).
|
|
146
|
+
knowledge base). The bridge serves the **strict view** by default (summaries, names as
|
|
147
|
+
tokens, no configuration content); `netconverter mcp --full` offers the wider set, and
|
|
148
|
+
`connect` writes `--strict` for every assistant. Job `options` from an assistant pass an
|
|
149
|
+
allowlist with type checks: an unknown or reserved key (the file, vendors, job type, a
|
|
150
|
+
decisions document) is refused naming it, never silently sent.
|
|
151
|
+
|
|
152
|
+
**Upgrading from 0.4.x:** if your assistant relied on the wider default view, add
|
|
153
|
+
`--full` to its `netconverter mcp` command (or set `NETCONVERTER_MCP_VIEW=full` where it
|
|
154
|
+
starts the bridge).
|
|
138
155
|
|
|
139
156
|
Inside the app, `/activity` and the header's **Bridge** pill show what your AI did
|
|
140
157
|
through the bridge — paths, sizes, SHA-256 and job IDs only.
|
|
@@ -162,6 +179,8 @@ a day; set `NETCONVERTER_NO_UPDATE_CHECK=1` to turn that off.
|
|
|
162
179
|
- [Privacy and data flow](docs/PRIVACY.md) · [Verification status](docs/VERIFICATION.md)
|
|
163
180
|
- [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
|
|
164
181
|
|
|
165
|
-
The client is
|
|
182
|
+
The client is licensed for use with your NetConverter account only and may not be
|
|
183
|
+
redistributed ([license](LICENSE)); you accept it on first run (`netconverter license`).
|
|
184
|
+
Versions up to 0.4.3 were MIT licensed. The license does not grant access to the
|
|
166
185
|
hosted service or license the server code. macOS is the exercised platform;
|
|
167
186
|
Windows acceptance remains pending.
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
NetConverter — by ValeronLabs LLC.
|
|
8
8
|
|
|
9
9
|
```text
|
|
10
|
-
◆ NetConverter v0.
|
|
10
|
+
◆ NetConverter v0.4.4 ● Server ◆ Bridge claude-code · 2m ago
|
|
11
11
|
▍ Start
|
|
12
12
|
▍ /convert Migrate a configuration to another vendor
|
|
13
13
|
▍ /validate Check a configuration before migrating
|
|
@@ -44,6 +44,11 @@ Run `netconverter capabilities` to see exactly what your credential can do.
|
|
|
44
44
|
A 0.1.x **Terminal Quick pilot key** still works and keeps its ASA → Palo Alto
|
|
45
45
|
scope; the app labels it as such.
|
|
46
46
|
|
|
47
|
+
Development preview: [revisioned drafts and guided MCP](docs/guided-workflows.md)
|
|
48
|
+
adds an opt-in client contract for manual YAML, reviewed migration preparation,
|
|
49
|
+
job status and verified result downloads.
|
|
50
|
+
It requires explicit server support and is not enabled by an ordinary MCP connection.
|
|
51
|
+
|
|
47
52
|
## Start here
|
|
48
53
|
|
|
49
54
|
One line installs everything (uv, the CLI from PyPI), signs you in and connects
|
|
@@ -80,6 +85,10 @@ first. Saved keys and sign-ins carry over (Keychain service **NetConverter Termi
|
|
|
80
85
|
|
|
81
86
|
Full walkthrough: [Quick start](QUICK_START.md).
|
|
82
87
|
|
|
88
|
+
A YAML v2 decisions file (zone and interface mappings) rides along with a conversion:
|
|
89
|
+
`netconverter convert edge.cfg --vendor fortinet --to palo_alto_xml --options "$(jq -Rs '{yaml_v2: .}' decisions.yaml)"`,
|
|
90
|
+
or inline as `--options '{"yaml_v2": {...}}'`; see [docs/COMMANDS.md](docs/COMMANDS.md#yaml-v2-decisions-yaml_v2).
|
|
91
|
+
|
|
83
92
|
## Use it from your AI
|
|
84
93
|
|
|
85
94
|
Step-by-step guides for every assistant (Claude, ChatGPT, Cursor, Gemini CLI, Codex …):
|
|
@@ -100,7 +109,15 @@ Then ask your assistant, for example: *"Validate edge-fw.conf and tell me what i
|
|
|
100
109
|
|
|
101
110
|
Bridge tools: `submit_file`, `job_status`, `wait_for_job`, `account`, `download`,
|
|
102
111
|
plus an allowlist of NetConverter's read-only tools (reports, evidence, NAT, flows,
|
|
103
|
-
knowledge base).
|
|
112
|
+
knowledge base). The bridge serves the **strict view** by default (summaries, names as
|
|
113
|
+
tokens, no configuration content); `netconverter mcp --full` offers the wider set, and
|
|
114
|
+
`connect` writes `--strict` for every assistant. Job `options` from an assistant pass an
|
|
115
|
+
allowlist with type checks: an unknown or reserved key (the file, vendors, job type, a
|
|
116
|
+
decisions document) is refused naming it, never silently sent.
|
|
117
|
+
|
|
118
|
+
**Upgrading from 0.4.x:** if your assistant relied on the wider default view, add
|
|
119
|
+
`--full` to its `netconverter mcp` command (or set `NETCONVERTER_MCP_VIEW=full` where it
|
|
120
|
+
starts the bridge).
|
|
104
121
|
|
|
105
122
|
Inside the app, `/activity` and the header's **Bridge** pill show what your AI did
|
|
106
123
|
through the bridge — paths, sizes, SHA-256 and job IDs only.
|
|
@@ -128,6 +145,8 @@ a day; set `NETCONVERTER_NO_UPDATE_CHECK=1` to turn that off.
|
|
|
128
145
|
- [Privacy and data flow](docs/PRIVACY.md) · [Verification status](docs/VERIFICATION.md)
|
|
129
146
|
- [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
|
|
130
147
|
|
|
131
|
-
The client is
|
|
148
|
+
The client is licensed for use with your NetConverter account only and may not be
|
|
149
|
+
redistributed ([license](LICENSE)); you accept it on first run (`netconverter license`).
|
|
150
|
+
Versions up to 0.4.3 were MIT licensed. The license does not grant access to the
|
|
132
151
|
hosted service or license the server code. macOS is the exercised platform;
|
|
133
152
|
Windows acceptance remains pending.
|
|
@@ -31,7 +31,7 @@ commands their arguments there (`/open "edge.cfg" fortinet`).
|
|
|
31
31
|
| `/flow {"source_ip":…,"destination_ip":…,"protocol":"tcp","destination_port":80}` | Which rule decides a flow |
|
|
32
32
|
| `/activity` · `/connect` | What your AI did through the bridge · wire an assistant |
|
|
33
33
|
| `/model` | Optional in-app model for plain-language questions |
|
|
34
|
-
| `/allowance` |
|
|
34
|
+
| `/refresh` (`/allowance`) | Reconnect and reload capabilities and limits |
|
|
35
35
|
| `/help` · `/clear` · `/home` | Commands · clear · start card |
|
|
36
36
|
|
|
37
37
|
Questions need a completed job: use `/resume` first. Selecting another file or
|
|
@@ -45,7 +45,7 @@ Questions need a completed job: use `/resume` first. Selecting another file or
|
|
|
45
45
|
| `netconverter login` with an `nck_…` API or trial key | External API (+ MCP when the key has `mcp:tools`) | Same; trial keys have trial limits |
|
|
46
46
|
| A 0.1.x Terminal Quick key | The pilot profile only | ASA → Palo Alto SET/XML/Panorama, 50,000 bytes |
|
|
47
47
|
|
|
48
|
-
The app shows the profile in the header and in `/
|
|
48
|
+
The app shows the profile in the header and in `/refresh`.
|
|
49
49
|
|
|
50
50
|
## Conversion settings
|
|
51
51
|
|
|
@@ -59,9 +59,43 @@ Pilot keys must also answer the Palo Alto settings the pilot API requires:
|
|
|
59
59
|
| `panorama_device_group`, `panorama_template` | Pilot keys, Panorama target |
|
|
60
60
|
| `remove_unused_objects`, `enable_appid`, `app_id_implementation`, `add_security_profiles`, `log_all_rules`, `implicit_deny`, `default_profile_group`, `zone_mapping` | Pilot keys: optional overrides of the mode preset |
|
|
61
61
|
|
|
62
|
+
On the full API (`convert --options '{…}'`) the same settings are honoured too: the client
|
|
63
|
+
sends them as a YAML v2 decisions document (`zone_mapping`, `options`, `pa_target`,
|
|
64
|
+
`output_platform`), because the server ignores unknown body keys. `panos_target_version`,
|
|
65
|
+
`routing_engine` and `default_profile_group` apply to Palo Alto targets, the Panorama scope to
|
|
66
|
+
`palo_alto_panorama`, and `pipeline_mode` to pilot keys only; such a setting elsewhere, any
|
|
67
|
+
unknown key, or a request field (`source_config`, vendors, `technology`, `job_type`,
|
|
68
|
+
`manual_mappings`) is refused before anything is uploaded, naming it. The full API also accepts
|
|
69
|
+
`selected_device_groups`, `file_name`, `optimization_options` (optimize) and a whole `yaml_v2`.
|
|
70
|
+
|
|
71
|
+
### YAML v2 decisions (`yaml_v2`)
|
|
72
|
+
|
|
73
|
+
A conversion can carry a YAML v2 decisions document (zone mappings, interface
|
|
74
|
+
mappings and the other sections `GET /capabilities` lists under `schemas.yaml_v2`).
|
|
75
|
+
Pass it in `--options` as `"yaml_v2"`, either as YAML text or as a JSON object;
|
|
76
|
+
it applies to `convert` only, and the server checks it strictly (a typo'd section or
|
|
77
|
+
broken YAML is refused with its line and column, exit code 4). The limit is 1 MiB.
|
|
78
|
+
|
|
79
|
+
```sh
|
|
80
|
+
# YAML text from a file (jq builds the JSON string safely)
|
|
81
|
+
netconverter convert edge.cfg --vendor fortinet --to palo_alto_xml \
|
|
82
|
+
--options "$(jq -Rs '{yaml_v2: .}' decisions.yaml)"
|
|
83
|
+
# or inline, as an object
|
|
84
|
+
netconverter convert edge.cfg --vendor fortinet --to palo_alto_xml \
|
|
85
|
+
--options '{"yaml_v2": {"zone_mappings": {"inside": "Trust"}}}'
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
The MCP bridge's `submit_file` does not take `yaml_v2`: a decisions document is yours to
|
|
89
|
+
author and review, so it goes in through the terminal command above, never through the AI
|
|
90
|
+
conversation. Bridge `options` are the typed settings listed earlier, up to 16,000
|
|
91
|
+
characters of JSON.
|
|
92
|
+
|
|
62
93
|
## Plain CLI
|
|
63
94
|
|
|
64
|
-
These
|
|
95
|
+
These exit without polling. `convert`, `validate` / `analyze`, `optimize` and `resume` print a
|
|
96
|
+
short plain summary (verdict ready / needs review / blocked and why, counts, the first findings,
|
|
97
|
+
the next command); `--json` prints the raw API response instead and `--all` lists every finding.
|
|
98
|
+
The other commands print JSON.
|
|
65
99
|
|
|
66
100
|
```sh
|
|
67
101
|
netconverter capabilities
|
|
@@ -72,6 +106,7 @@ netconverter jobs
|
|
|
72
106
|
netconverter resume JOB_ID
|
|
73
107
|
netconverter download
|
|
74
108
|
netconverter query nat
|
|
109
|
+
netconverter query unparsed_lines # the configuration lines NetConverter could not parse
|
|
75
110
|
netconverter query flow --arguments '{"source_ip":"192.0.2.10","destination_ip":"198.51.100.10","protocol":"tcp","destination_port":80}'
|
|
76
111
|
netconverter connect # list assistants and whether they are connected
|
|
77
112
|
netconverter connect cursor --print # show the change only
|
|
@@ -79,8 +114,8 @@ netconverter connect claude-desktop # merge into claude_desktop_config.json
|
|
|
79
114
|
netconverter connect --all # every assistant found on this computer, one prompt each
|
|
80
115
|
netconverter connect chatgpt # ChatGPT / claude.ai: prints remote-connector setup steps
|
|
81
116
|
netconverter mcp --workspace ~/migrations # what an assistant runs; not for interactive use
|
|
82
|
-
netconverter mcp --
|
|
83
|
-
netconverter update --check # is a newer release published? (JSON)
|
|
117
|
+
netconverter mcp --full --workspace ~/migrations # the wider view (strict is the default)
|
|
118
|
+
netconverter update --check # is a newer release published? (--json for JSON)
|
|
84
119
|
netconverter update # verify and install it with uv, after a prompt
|
|
85
120
|
netconverter update --yes # same, without the prompt
|
|
86
121
|
```
|
|
@@ -109,10 +144,10 @@ delays a command; its result is cached in your user cache folder.
|
|
|
109
144
|
|
|
110
145
|
| Tool | Returns |
|
|
111
146
|
| --- | --- |
|
|
112
|
-
| `submit_file(path, source_vendor, target_vendor?, job_type?, options?)` | `job_id`, `status`, `sha256`, `bytes`. `job_type`: `convert`, `validate`, `optimize`, or `analyze` (= validate) |
|
|
147
|
+
| `submit_file(path, source_vendor, target_vendor?, job_type?, options?)` | `job_id`, `status`, `sha256`, `bytes`. `job_type`: `convert`, `validate`, `optimize`, or `analyze` (= validate). `options` keys (typed; anything else is refused naming it): `selected_device_groups`, `file_name`, `optimization_options` (optimize), and for convert `zone_mapping`, `remove_unused_objects`, `enable_appid`, `app_id_implementation`, `add_security_profiles`, `log_all_rules`, `implicit_deny`, `panos_target_version` / `routing_engine` / `default_profile_group` (Palo Alto targets), `panorama_device_group` / `panorama_template` (Panorama), `pipeline_mode` (pilot keys). On the full API the convert settings travel as a `yaml_v2` decisions document |
|
|
113
148
|
| `job_status(job_id)` | Status, verdict, review flag, progress and stage when sent, reason counts, vendors |
|
|
114
149
|
| `wait_for_job(job_id, timeout_s=45)` | The `job_status` summary plus `waited_s` and `timed_out` (plus `next` when still running: call it again); polls 2 s, ×1.5, up to 15 s apart, at most 600 s. The default stays under the 60 s tool timeout of Codex and OpenClaw; pass a larger `timeout_s` only when the client allows it. Sends MCP progress notifications when the call has a progress token |
|
|
115
|
-
| `account()` | `tier`, `job_types`, `rate_limit_per_min`, `daily_quota`, `auth_kind`, `profile`, `client_version`, `update_available`, `latest_version`, `strict_mode` (the `--strict` flag), `view_mode` (the view the server applies to this session, from `get_account`), `strict_enforced_by` (`server` when that view is strict, `client` while the bridge enforces it locally), `credential_source` (`clerk_session`, `api_key_environment`, `api_key_stored` or `none`; the one credential REST and the remote tools share) |
|
|
150
|
+
| `account()` | Signed out: `status` (`signed_out`, `keyring_unreachable`), `signed_in: false`, `message`, `client_version`, `update_available`, `latest_version` (not an error). Signed in: `tier`, `job_types`, `rate_limit_per_min`, `daily_quota`, `auth_kind`, `profile`, `client_version`, `update_available`, `latest_version`, `strict_mode` (the `--strict` flag), `view_mode` (the view the server applies to this session, from `get_account`), `strict_enforced_by` (`server` when that view is strict, `client` while the bridge enforces it locally), `credential_source` (`clerk_session`, `api_key_environment`, `api_key_stored` or `none`; the one credential REST and the remote tools share) |
|
|
116
151
|
| `download(job_id, dest_dir=".")` | Saved file names, sizes and SHA-256 |
|
|
117
152
|
|
|
118
153
|
Remote NetConverter tools are proxied only from a fixed allowlist, and never a
|
|
@@ -124,10 +159,11 @@ Remote NetConverter tools are proxied only from a fixed allowlist, and never a
|
|
|
124
159
|
`get_unused_objects`, `get_vpn_summary`, `get_zone_summary`, `kb_explain`,
|
|
125
160
|
`kb_search`, `list_jobs`, `list_objects_with_attribute`, `list_rules_matching`,
|
|
126
161
|
`query_ir`, `search`, `select_job`, `simulate_flow`, `vendor_capability_lookup`.
|
|
127
|
-
With
|
|
162
|
+
With the strict view (the default since 0.5.0; `--strict` names it explicitly, `--full` or
|
|
163
|
+
`--view full` opts out): `list_jobs`, `select_job`, `get_account`, `search`, `fetch`,
|
|
128
164
|
`kb_search`, `kb_explain`, `vendor_capability_lookup`, `get_job_brief`,
|
|
129
165
|
`get_evidence`, `get_report`. A listed tool appears only if the server offers it.
|
|
130
|
-
|
|
166
|
+
The strict view also asks the server for its strict view on every request (`X-NetConverter-View: strict`;
|
|
131
167
|
the server may only lower the grant's view, never raise it) and reads the view in force from
|
|
132
168
|
`get_account`. Until the server applies it, the bridge enforces strict locally: it refuses
|
|
133
169
|
`get_evidence section=unparsed_lines`, `get_job_brief focus=target` and any `fetch` that is not
|
|
@@ -139,11 +175,31 @@ Global options go before the subcommand: `netconverter --workspace DIR --server
|
|
|
139
175
|
Environment: `NETCONVERTER_URL`, `NETCONVERTER_PROVIDER`, `NETCONVERTER_MODEL`,
|
|
140
176
|
`NETCONVERTER_AUTH=key` or `=clerk` (force one credential; unset, plain commands use a stored key first, then
|
|
141
177
|
your sign-in, while `mcp` prefers the sign-in and says on stderr which API key it leaves unused;
|
|
142
|
-
`NETCONVERTER_MCP_AUTH` overrides it for `mcp` only), `NETCONVERTER_TRUSTED_HOSTS`, `
|
|
178
|
+
`NETCONVERTER_MCP_AUTH` overrides it for `mcp` only), `NETCONVERTER_TRUSTED_HOSTS`, `NETCONVERTER_MCP_VIEW=full` (same as `mcp --full`; strict is the default, and an
|
|
179
|
+
explicit `--strict` wins),
|
|
143
180
|
`NETCONVERTER_NO_UPDATE_CHECK=1` (no daily update check or notice; `account` then reports
|
|
144
|
-
`update_available: null`)
|
|
181
|
+
`update_available: null`), `NETCONVERTER_KEYRING_TIMEOUT_S` (how long to wait for the OS keyring
|
|
182
|
+
before reporting it locked; default 5).
|
|
145
183
|
Never put a literal key in shell history or a shared script.
|
|
146
184
|
|
|
185
|
+
## Exit codes
|
|
186
|
+
|
|
187
|
+
Plain commands print results on stdout and every error on stderr, as one
|
|
188
|
+
sentence that names the reason (the server's own reason when it sent one).
|
|
189
|
+
|
|
190
|
+
| Code | Meaning |
|
|
191
|
+
| --- | --- |
|
|
192
|
+
| `0` | Success |
|
|
193
|
+
| `1` | The command ran but did not succeed (a change was not applied, an update or model check failed) |
|
|
194
|
+
| `2` | Usage: unknown command or option, missing or unknown `--vendor` |
|
|
195
|
+
| `3` | Sign-in: not signed in, sign-in rejected or the keyring is locked, or the credential lacks the entitlement (HTTP 401/403) |
|
|
196
|
+
| `4` | Input refused: a missing, empty, oversized or out-of-workspace file, malformed `--options`, or the server's 400/404/409/413/422 reason |
|
|
197
|
+
| `5` | NetConverter unreachable or failing: connection error, HTTP 429, 5xx |
|
|
198
|
+
| `130` | Cancelled with Ctrl-C ("Cancelled. Nothing was saved.") |
|
|
199
|
+
|
|
200
|
+
Local checks (the file and `--options`) run before the sign-in, so a missing
|
|
201
|
+
file is reported as a missing file, never as "not signed in".
|
|
202
|
+
|
|
147
203
|
## Troubleshooting
|
|
148
204
|
|
|
149
205
|
| Symptom | Action |
|
|
@@ -152,9 +208,9 @@ Never put a literal key in shell history or a shared script.
|
|
|
152
208
|
| Setup suggests localhost | Run `netconverter --server https://api.netconverter.ai/external/v1 setup` to replace earlier demo settings |
|
|
153
209
|
| 401 / invalid key | Rerun `login`; verify your issued key, its server, and whether it was revoked |
|
|
154
210
|
| 403 / restricted access | The credential lacks that permission (for example a pilot key on a non-ASA source); `netconverter capabilities` shows what it can do |
|
|
155
|
-
| 413 / file too large | Check `wc -c FILE` against the limit in `/
|
|
211
|
+
| 413 / file too large | Check `wc -c FILE` against the limit in `/refresh` (5 MB full API, 50 KB trial and pilot keys) |
|
|
156
212
|
| 422 / required decisions | Complete the indicated conversion fields using the server's supported choices |
|
|
157
|
-
| 429 / quota or active job | Check `/
|
|
213
|
+
| 429 / quota or active job | Check `/refresh` and `/jobs`; resume the existing active job or wait for the UTC daily reset |
|
|
158
214
|
| Model unavailable or forbidden operation | Continue using guided commands; use `/model` to retry with an accessible model; errors distinguish key, access, quota, rate limit, timeout, and tool incompatibility |
|
|
159
215
|
| Ollama connection fails | Start the local Ollama service and select an already installed tool-capable model; no hosted fallback is attempted |
|
|
160
216
|
| File not listed | Hidden files, downloaded outputs and binary types are skipped; choose **Type a relative file path** |
|
|
@@ -166,6 +222,7 @@ Never put a literal key in shell history or a shared script.
|
|
|
166
222
|
| No verified configuration | Read validation reports and warnings; evidence can be available even when no deployable output is produced |
|
|
167
223
|
| Proxy-only network fails | Client HTTP connections ignore environment proxy settings and do not follow redirects; use a network with direct access to configured endpoints |
|
|
168
224
|
| Full-screen UI unsuitable | Use `netconverter plain` or individual CLI commands |
|
|
225
|
+
| "Your system keyring is locked" (exit 3) | The OS keyring did not answer within 5 seconds (a locked Secret Service collection after a reboot, or a keychain waiting for a password). Unlock it (for example by logging in to the desktop session), or sign in again with `netconverter login` |
|
|
169
226
|
| `keyring_unreachable` from the bridge (Linux) | The assistant launched `netconverter mcp` without `DBUS_SESSION_BUS_ADDRESS`; the bridge tries `$XDG_RUNTIME_DIR/bus` and `/run/user/<uid>/bus`, else set that variable (or `NETCONVERTER_API_KEY`) in the assistant's MCP server environment and restart it |
|
|
170
227
|
| Assistant cannot see a NetConverter tool | The bridge lists only allowlisted remote tools the server offers (fewer with `--strict`); update the client with `netconverter update` |
|
|
171
228
|
| `netconverter update` says uv is not on PATH | Install uv, or follow the printed download, `shasum -a 256 -c SHA256SUMS` and `uv tool install --force` steps |
|
|
@@ -37,7 +37,9 @@ The bridge offers its local tools (`submit_file`, `job_status`, `wait_for_job`,
|
|
|
37
37
|
`account`, `download`) and proxies NetConverter's remote tools only from a fixed
|
|
38
38
|
client-side allowlist of read tools. A tool the server adds later is not offered
|
|
39
39
|
until a client release lists it, and a remote tool named `submit_*` is never
|
|
40
|
-
proxied. `netconverter mcp
|
|
40
|
+
proxied. By default (since 0.5.0) `netconverter mcp` serves the **strict view**, and
|
|
41
|
+
`netconverter connect` writes `--strict` for every assistant; the wider view needs an
|
|
42
|
+
explicit `netconverter mcp --full` (or `NETCONVERTER_MCP_VIEW=full`). The strict view narrows the
|
|
41
43
|
remote tools to the strict-view set (job list and selection, account, search and
|
|
42
44
|
fetch, knowledge base, vendor capabilities, job brief, evidence, report), whatever
|
|
43
45
|
the server advertises, and asks the server for its strict view on every request
|
|
@@ -49,8 +51,18 @@ remote results as `<ip>`/`<cidr>` itself; names in summaries are not tokenised
|
|
|
49
51
|
locally, and `account.strict_enforced_by` says which side is enforcing. `account`
|
|
50
52
|
returns only tier, job types, rate limit, daily quota, auth kind, credential source,
|
|
51
53
|
view mode and client version facts: no tokens, e-mail addresses, key hints or
|
|
52
|
-
tenant IDs. `wait_for_job` progress messages carry
|
|
53
|
-
status
|
|
54
|
+
tenant IDs. `job_status` and `wait_for_job` (and its progress messages) carry an
|
|
55
|
+
allowlisted status and percentage plus the stage: the server's fixed-vocabulary
|
|
56
|
+
`stage_key` when it sends one, otherwise its progress text made single-line,
|
|
57
|
+
stripped of control characters and capped at 120 characters; a stage that names an
|
|
58
|
+
internal id (for example "Stored to corpus (ID: …)") is reported as `storing`.
|
|
59
|
+
|
|
60
|
+
`submit_file` accepts job `options` only from a fixed, typed allowlist (its schema
|
|
61
|
+
lists every key). The file, vendors, job type, `technology`, and any decisions document
|
|
62
|
+
(`yaml_v2`, `yaml`, `manual_mappings`) can never come from options, and an unknown key
|
|
63
|
+
is refused naming it before anything is uploaded. **Upgrade note (0.5.0):** an
|
|
64
|
+
assistant set up for the old default (full) view now gets the strict view; add `--full`
|
|
65
|
+
to its `netconverter mcp` command only if you want it to see the wider set.
|
|
54
66
|
|
|
55
67
|
### Keep the assistant out of the files
|
|
56
68
|
|
|
@@ -43,6 +43,7 @@ Do these once, before the first tag. Nothing can be published until they exist.
|
|
|
43
43
|
1. In the private repo (`devnexthop/netconverter_terminals`), on `main`:
|
|
44
44
|
- set the version in `pyproject.toml` and `src/netconverter_cli/__init__.py`;
|
|
45
45
|
- `uv lock` (updates the project version in `uv.lock`);
|
|
46
|
+
- `python3 scripts/sync_readme_version.py` (the README banner; a test fails when it differs);
|
|
46
47
|
- add a `## <version> — <date>` section at the top of `CHANGELOG.md` (it becomes the
|
|
47
48
|
release notes);
|
|
48
49
|
- `uv run pytest tests -q`, `uv build`, `uvx twine check --strict dist/*`;
|
|
@@ -4,7 +4,7 @@ NetConverter reaches your AI assistant in one of two ways. Pick the one your ass
|
|
|
4
4
|
|
|
5
5
|
| Way | What your AI can do | Assistants |
|
|
6
6
|
|---|---|---|
|
|
7
|
-
| **Terminal bridge** (`netconverter mcp`, runs on your computer) | Everything below, **plus submit** configurations for conversion, validation and optimization. The bridge uploads the file from disk; the configuration never passes through the model. | Claude Desktop, Claude Code, Cursor, Gemini CLI, Codex CLI, VS Code, Windsurf, LM Studio |
|
|
7
|
+
| **Terminal bridge** (`netconverter mcp`, runs on your computer) | Everything below, **plus submit** configurations for conversion, validation and optimization. The bridge uploads the file from disk; the configuration never passes through the model. | Claude Desktop, Claude Code, Cursor, Gemini CLI, Codex CLI, VS Code, Windsurf, LM Studio, OpenClaw |
|
|
8
8
|
| **Remote connector** (`https://api.netconverter.ai/mcp/v1`) | Read your jobs, verdicts, evidence and reports, your account, and the NetConverter migration knowledge base. No file submission. | claude.ai (web, mobile, Desktop chat), ChatGPT |
|
|
9
9
|
|
|
10
10
|
Both need a NetConverter account with **MCP access enabled** by your administrator
|
|
@@ -18,6 +18,7 @@ Both need a NetConverter account with **MCP access enabled** by your administrat
|
|
|
18
18
|
- [Claude Desktop](claude-desktop.md) — terminal bridge
|
|
19
19
|
- [Claude Code](claude-code.md) — terminal bridge
|
|
20
20
|
- [Cursor, Gemini CLI, Codex CLI, VS Code, Windsurf, LM Studio](other-assistants.md) — terminal bridge
|
|
21
|
+
- [OpenClaw](openclaw.md) — terminal bridge, through `openclaw mcp`
|
|
21
22
|
|
|
22
23
|
## Fastest path (terminal bridge)
|
|
23
24
|
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# OpenClaw
|
|
2
|
+
|
|
3
|
+
`netconverter connect openclaw` adds the terminal bridge to OpenClaw through OpenClaw's own
|
|
4
|
+
CLI; it never edits `~/.openclaw/openclaw.json` (JSON5) by hand.
|
|
5
|
+
|
|
6
|
+
```sh
|
|
7
|
+
cd ~/migrations # the folder with your configurations
|
|
8
|
+
netconverter connect openclaw # shows the commands, asks, then runs them
|
|
9
|
+
netconverter connect openclaw --print # show only
|
|
10
|
+
netconverter connect openclaw --remove
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
What it runs after you answer yes:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
openclaw mcp add netconverter --command /path/to/netconverter \
|
|
17
|
+
--arg mcp --arg --workspace --arg ~/migrations --arg --strict
|
|
18
|
+
openclaw mcp doctor netconverter --probe
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- **Strict view** is written explicitly, as for every assistant. Use `--full` in the args
|
|
22
|
+
only if you want OpenClaw to see the wider set.
|
|
23
|
+
- **Idempotent.** Re-running with the same folder changes nothing. A `netconverter` entry
|
|
24
|
+
pointing elsewhere is replaced (`openclaw mcp unset netconverter`, then `add`) after you
|
|
25
|
+
confirm. `--remove` runs `openclaw mcp unset netconverter`.
|
|
26
|
+
- **No `openclaw` on PATH:** `connect` prints the JSON5 block to merge into
|
|
27
|
+
`~/.openclaw/openclaw.json` under `mcp.servers`, then run
|
|
28
|
+
`openclaw mcp doctor netconverter --probe`.
|
|
29
|
+
|
|
30
|
+
## Gateway host
|
|
31
|
+
|
|
32
|
+
OpenClaw starts stdio MCP servers from the **Gateway** process. `netconverter` must be
|
|
33
|
+
installed, on the Gateway's PATH, and signed in (`netconverter login --clerk`) on the
|
|
34
|
+
Gateway host, with its environment. On Linux the Gateway may start the bridge without
|
|
35
|
+
`DBUS_SESSION_BUS_ADDRESS`; if the bridge reports `keyring_unreachable`, add that variable
|
|
36
|
+
(or `NETCONVERTER_API_KEY`) to the server's `env` in OpenClaw.
|
|
37
|
+
|
|
38
|
+
## Deny OpenClaw's own file tools
|
|
39
|
+
|
|
40
|
+
OpenClaw agents have their own file and exec tools, so they could open a configuration and
|
|
41
|
+
put its text into the model conversation. After connecting, deny the workspace folder
|
|
42
|
+
(`<folder>/**`) to those tools in OpenClaw's tool policy and restart the Gateway; the
|
|
43
|
+
assistant then works on configurations only through the bridge, by path. `connect` shows
|
|
44
|
+
this step with the exact path but does not apply it.
|
|
45
|
+
|
|
46
|
+
## Compatibility
|
|
47
|
+
|
|
48
|
+
The client-compatibility matrix (Claude Code, Claude Desktop, Cursor, Gemini CLI, Codex,
|
|
49
|
+
OpenClaw) is filled from the tester's run on a real machine; it is not claimed here from
|
|
50
|
+
unit tests, which only mock `openclaw`.
|