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.
Files changed (112) hide show
  1. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/CHANGELOG.md +71 -0
  2. netconverter_cli-0.4.4/LICENSE +61 -0
  3. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/PKG-INFO +24 -5
  4. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/README.md +22 -3
  5. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/COMMANDS.md +70 -13
  6. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/PRIVACY.md +15 -3
  7. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/RELEASING.md +1 -0
  8. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/README.md +2 -1
  9. netconverter_cli-0.4.4/docs/connect/openclaw.md +50 -0
  10. netconverter_cli-0.4.4/docs/guided-workflows.md +287 -0
  11. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/pyproject.toml +7 -3
  12. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/__init__.py +1 -1
  13. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/api.py +11 -1
  14. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/backend.py +10 -4
  15. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/branding.py +1 -1
  16. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/clerk.py +30 -12
  17. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/cli.py +291 -74
  18. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/commands.py +4 -3
  19. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/connect.py +86 -23
  20. netconverter_cli-0.4.4/src/netconverter_cli/connect_openclaw.py +136 -0
  21. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/controller.py +22 -2
  22. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/credentials.py +83 -14
  23. netconverter_cli-0.4.4/src/netconverter_cli/design_catalog.py +10 -0
  24. netconverter_cli-0.4.4/src/netconverter_cli/draft_cli.py +102 -0
  25. netconverter_cli-0.4.4/src/netconverter_cli/draft_io.py +215 -0
  26. netconverter_cli-0.4.4/src/netconverter_cli/drafts.py +697 -0
  27. netconverter_cli-0.4.4/src/netconverter_cli/errors.py +95 -0
  28. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/guided.py +43 -5
  29. netconverter_cli-0.4.4/src/netconverter_cli/guided_operations.json +319 -0
  30. netconverter_cli-0.4.4/src/netconverter_cli/guided_projects.json +605 -0
  31. netconverter_cli-0.4.4/src/netconverter_cli/job_options.py +230 -0
  32. netconverter_cli-0.4.4/src/netconverter_cli/license.py +211 -0
  33. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/mcp_server.py +296 -28
  34. netconverter_cli-0.4.4/src/netconverter_cli/mcp_workflows.py +246 -0
  35. netconverter_cli-0.4.4/src/netconverter_cli/one_shot.py +45 -0
  36. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/presentation.py +23 -3
  37. netconverter_cli-0.4.4/src/netconverter_cli/project_cli.py +46 -0
  38. netconverter_cli-0.4.4/src/netconverter_cli/projects.py +81 -0
  39. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/setup.py +2 -1
  40. netconverter_cli-0.4.4/src/netconverter_cli/summary.py +417 -0
  41. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/tui.py +32 -15
  42. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/update.py +7 -2
  43. netconverter_cli-0.4.4/src/netconverter_cli/walkthrough.py +100 -0
  44. netconverter_cli-0.4.4/src/netconverter_cli/windows_draft_io.py +378 -0
  45. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/conftest.py +6 -0
  46. netconverter_cli-0.4.4/tests/fixtures/jobs/opt_4056e02e5b66.json +73 -0
  47. netconverter_cli-0.4.4/tests/fixtures/jobs/tra_4058ef406cd6.json +29 -0
  48. netconverter_cli-0.4.4/tests/fixtures/jobs/tra_running.json +17 -0
  49. netconverter_cli-0.4.4/tests/fixtures/jobs/val_9f9acb9b5a59.json +146 -0
  50. netconverter_cli-0.4.4/tests/fixtures/jobs/val_9f9acb9b5a59.sarif +92 -0
  51. netconverter_cli-0.4.4/tests/test_autodetect_v5.py +127 -0
  52. netconverter_cli-0.4.4/tests/test_bridge_polish_021.py +69 -0
  53. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_clerk.py +21 -2
  54. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_cli_020.py +2 -1
  55. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_connect_030.py +1 -1
  56. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_connect_031.py +1 -1
  57. netconverter_cli-0.4.4/tests/test_connect_direct_entry.py +79 -0
  58. netconverter_cli-0.4.4/tests/test_connect_openclaw_014.py +128 -0
  59. netconverter_cli-0.4.4/tests/test_draft_cli.py +224 -0
  60. netconverter_cli-0.4.4/tests/test_draft_io.py +198 -0
  61. netconverter_cli-0.4.4/tests/test_draft_jobs.py +392 -0
  62. netconverter_cli-0.4.4/tests/test_drafts.py +496 -0
  63. netconverter_cli-0.4.4/tests/test_errors_009.py +304 -0
  64. netconverter_cli-0.4.4/tests/test_help_008.py +177 -0
  65. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_keyring_bus_017.py +2 -1
  66. netconverter_cli-0.4.4/tests/test_keyring_timeout_010.py +115 -0
  67. netconverter_cli-0.4.4/tests/test_license.py +105 -0
  68. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_mcp.py +36 -10
  69. netconverter_cli-0.4.4/tests/test_mcp_jobs.py +286 -0
  70. netconverter_cli-0.4.4/tests/test_mcp_workflows.py +396 -0
  71. netconverter_cli-0.4.4/tests/test_options_011_019.py +186 -0
  72. netconverter_cli-0.4.4/tests/test_polish_028.py +60 -0
  73. netconverter_cli-0.4.4/tests/test_projects.py +212 -0
  74. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_signin_default.py +2 -2
  75. netconverter_cli-0.4.4/tests/test_stage_029.py +80 -0
  76. netconverter_cli-0.4.4/tests/test_strict_default_011.py +84 -0
  77. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_strict_view_015.py +4 -0
  78. netconverter_cli-0.4.4/tests/test_summary_007.py +254 -0
  79. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_update.py +3 -3
  80. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_vendor_error_022.py +3 -3
  81. netconverter_cli-0.4.4/tests/test_walkthrough.py +77 -0
  82. netconverter_cli-0.4.4/tests/test_windows_draft_io.py +305 -0
  83. netconverter_cli-0.4.3/LICENSE +0 -21
  84. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/.gitignore +0 -0
  85. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/QUICK_START.md +0 -0
  86. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/SECURITY.md +0 -0
  87. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/VERIFICATION.md +0 -0
  88. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/chatgpt.md +0 -0
  89. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/claude-ai.md +0 -0
  90. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/claude-code.md +0 -0
  91. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/claude-desktop.md +0 -0
  92. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/getting-access.md +0 -0
  93. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/docs/connect/other-assistants.md +0 -0
  94. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/examples/README.md +0 -0
  95. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/activity.py +0 -0
  96. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/catalog.py +0 -0
  97. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/palette.py +0 -0
  98. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/privacy.py +0 -0
  99. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/providers.py +0 -0
  100. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/remote_mcp.py +0 -0
  101. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/src/netconverter_cli/workspace.py +0 -0
  102. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_boundaries.py +0 -0
  103. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_clerk_host_binding.py +0 -0
  104. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_download_analysis.py +0 -0
  105. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_folders_cd_ls.py +0 -0
  106. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_inline.py +0 -0
  107. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_mcp_auth_016.py +0 -0
  108. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_presentation.py +0 -0
  109. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_protocols.py +0 -0
  110. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_readonly_workspace.py +0 -0
  111. {netconverter_cli-0.4.3 → netconverter_cli-0.4.4}/tests/test_sessions.py +0 -0
  112. {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
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: MIT
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.3.0 ● Server ◆ Bridge claude-code · 2m ago
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). `netconverter mcp --strict` narrows those to the strict-view set.
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 [MIT licensed](LICENSE). The license does not grant access to the
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.3.0 ● Server ◆ Bridge claude-code · 2m ago
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). `netconverter mcp --strict` narrows those to the strict-view set.
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 [MIT licensed](LICENSE). The license does not grant access to the
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` | Refresh capabilities and limits |
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 `/allowance`.
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 print JSON and exit; they do not poll.
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 --strict --workspace ~/migrations # strict-view remote tools only
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 `--strict`: `list_jobs`, `select_job`, `get_account`, `search`, `fetch`,
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
- `--strict` also asks the server for its strict view on every request (`X-NetConverter-View: strict`;
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`, `NETCONVERTER_MCP_STRICT=1` (same as `mcp --strict`),
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 `/allowance` (5 MB full API, 50 KB trial and pilot keys) |
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 `/allowance` and `/jobs`; resume the existing active job or wait for the UTC daily reset |
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 --strict` (or `NETCONVERTER_MCP_STRICT=1`) narrows the
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 only an allowlisted
53
- status, stage and percentage.
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`.