netconverter-cli 0.6.0__tar.gz → 0.7.1__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 (129) hide show
  1. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/CHANGELOG.md +33 -0
  2. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/PKG-INFO +49 -4
  3. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/QUICK_START.md +17 -0
  4. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/README.md +48 -3
  5. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/COMMANDS.md +45 -8
  6. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/README.md +2 -2
  7. netconverter_cli-0.7.1/docs/connect/chatgpt.md +63 -0
  8. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/pyproject.toml +1 -1
  9. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/__init__.py +1 -1
  10. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/api.py +19 -1
  11. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/catalog.py +2 -1
  12. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/cli.py +13 -2
  13. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/connect.py +6 -1
  14. netconverter_cli-0.7.1/src/netconverter_cli/diagrams.py +67 -0
  15. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/job_options.py +1 -1
  16. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/mcp_client_features.py +35 -4
  17. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/mcp_server.py +271 -47
  18. netconverter_cli-0.7.1/tests/test_diagrams.py +205 -0
  19. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_guided_mapping_012.py +3 -1
  20. netconverter_cli-0.7.1/tests/test_guided_prescan_037.py +316 -0
  21. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_mcp.py +10 -5
  22. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_mcp_features_020.py +17 -4
  23. netconverter_cli-0.6.0/docs/connect/chatgpt.md +0 -22
  24. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/.gitignore +0 -0
  25. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/LICENSE +0 -0
  26. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/SECURITY.md +0 -0
  27. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/PRIVACY.md +0 -0
  28. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/RELEASING.md +0 -0
  29. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/VERIFICATION.md +0 -0
  30. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/claude-ai.md +0 -0
  31. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/claude-code.md +0 -0
  32. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/claude-desktop.md +0 -0
  33. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/compatibility.md +0 -0
  34. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/getting-access.md +0 -0
  35. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/openclaw.md +0 -0
  36. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/connect/other-assistants.md +0 -0
  37. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/docs/guided-workflows.md +0 -0
  38. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/examples/README.md +0 -0
  39. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/activity.py +0 -0
  40. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/backend.py +0 -0
  41. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/branding.py +0 -0
  42. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/clerk.py +0 -0
  43. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/commands.py +0 -0
  44. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/connect_openclaw.py +0 -0
  45. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/controller.py +0 -0
  46. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/credential_file.py +0 -0
  47. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/credentials.py +0 -0
  48. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/design_catalog.py +0 -0
  49. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/draft_cli.py +0 -0
  50. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/draft_io.py +0 -0
  51. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/drafts.py +0 -0
  52. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/errors.py +0 -0
  53. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/exposure.py +0 -0
  54. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/guided.py +0 -0
  55. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/guided_operations.json +0 -0
  56. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/guided_projects.json +0 -0
  57. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/license.py +0 -0
  58. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/mcp_workflows.py +0 -0
  59. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/one_shot.py +0 -0
  60. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/palette.py +0 -0
  61. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/presentation.py +0 -0
  62. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/privacy.py +0 -0
  63. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/privacy_apply.py +0 -0
  64. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/privacy_cli.py +0 -0
  65. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/project_cli.py +0 -0
  66. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/projects.py +0 -0
  67. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/providers.py +0 -0
  68. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/remote_mcp.py +0 -0
  69. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/setup.py +0 -0
  70. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/summary.py +0 -0
  71. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/tui.py +0 -0
  72. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/update.py +0 -0
  73. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/walkthrough.py +0 -0
  74. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/windows_draft_io.py +0 -0
  75. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/src/netconverter_cli/workspace.py +0 -0
  76. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/conftest.py +0 -0
  77. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/fixtures/jobs/opt_4056e02e5b66.json +0 -0
  78. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/fixtures/jobs/tra_4058ef406cd6.json +0 -0
  79. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/fixtures/jobs/tra_running.json +0 -0
  80. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/fixtures/jobs/val_9f9acb9b5a59.json +0 -0
  81. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/fixtures/jobs/val_9f9acb9b5a59.sarif +0 -0
  82. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_autodetect_v5.py +0 -0
  83. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_boundaries.py +0 -0
  84. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_bridge_polish_021.py +0 -0
  85. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_clerk.py +0 -0
  86. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_clerk_host_binding.py +0 -0
  87. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_cli_020.py +0 -0
  88. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_connect_030.py +0 -0
  89. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_connect_031.py +0 -0
  90. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_connect_compat_014.py +0 -0
  91. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_connect_direct_entry.py +0 -0
  92. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_connect_openclaw_014.py +0 -0
  93. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_credential_file_010.py +0 -0
  94. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_download_analysis.py +0 -0
  95. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_draft_cli.py +0 -0
  96. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_draft_io.py +0 -0
  97. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_draft_jobs.py +0 -0
  98. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_drafts.py +0 -0
  99. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_errors_009.py +0 -0
  100. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_exposure_levels_013.py +0 -0
  101. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_folders_cd_ls.py +0 -0
  102. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_guided_full_api_019.py +0 -0
  103. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_help_008.py +0 -0
  104. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_inline.py +0 -0
  105. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_keyring_bus_017.py +0 -0
  106. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_keyring_timeout_010.py +0 -0
  107. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_license.py +0 -0
  108. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_mcp_auth_016.py +0 -0
  109. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_mcp_jobs.py +0 -0
  110. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_mcp_workflows.py +0 -0
  111. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_options_011_019.py +0 -0
  112. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_polish_028.py +0 -0
  113. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_presentation.py +0 -0
  114. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_privacy_apply_013.py +0 -0
  115. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_privacy_cli_013.py +0 -0
  116. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_projects.py +0 -0
  117. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_protocols.py +0 -0
  118. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_readonly_workspace.py +0 -0
  119. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_sessions.py +0 -0
  120. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_setup.py +0 -0
  121. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_signin_default.py +0 -0
  122. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_stage_029.py +0 -0
  123. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_strict_default_011.py +0 -0
  124. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_strict_view_015.py +0 -0
  125. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_summary_007.py +0 -0
  126. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_update.py +0 -0
  127. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_vendor_error_022.py +0 -0
  128. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_walkthrough.py +0 -0
  129. {netconverter_cli-0.6.0 → netconverter_cli-0.7.1}/tests/test_windows_draft_io.py +0 -0
@@ -1,5 +1,38 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.7.1 — 2026-11-02
4
+
5
+ - Proxy governed `get_diagram` discovery for selected jobs in full and strict views.
6
+ - `download` accepts an artifact request recipe for SVG, PNG, PDF, draw.io or JSON.
7
+ It uses a fixed authenticated endpoint, checks the expected SHA-256 before an
8
+ atomic write, preserves earlier document revisions, and respects strict view.
9
+ - Explicit `preview_diagram` returns a verified PNG as native MCP image content for
10
+ IDE chat. Streaming, byte and canvas bounds apply; masked/selected force strict
11
+ view and none refuses previews. Automatic summaries and downloads remain metadata only.
12
+ - Availability requires the matching server release; live two-client and public
13
+ package qualification remain separate from synthetic bridge tests.
14
+
15
+ ## 0.7.0 — 2026-11-02
16
+
17
+ - New: guided migration from your AI assistant (devnexthop/aws-netconverter.ai#1090).
18
+ `submit_file(..., job_type="prescan")` uploads the file and stops at a `psc_` prescan
19
+ (`target_vendor` optional); the result names the next steps. The bridge now proxies
20
+ `list_operations`, `get_decision_document`, `validate_decision_document`,
21
+ `propose_operations` and `submit_conversion` (the one remote `submit_*` it allows: a prescan
22
+ id and a revision, no configuration text). They need exposure level `full`; the two write
23
+ tools appear only where the server enables them for the tenant, and the server gates and
24
+ audits each call. `submit_conversion` asks for confirmation like an upload. Also proxied at
25
+ `full`: `set_view_level` (it can only lower the server's view for the session).
26
+ - New: `account` reports `guided_migration` (the guided tools this session lists, or the fix
27
+ when the level hides them), and the remote `get_account` carries the same note below `full`.
28
+ - Fix (#37): assistants that advertise forms but decline without showing them (ChatGPT, Claude
29
+ Code) no longer block every upload. A decline within 1.5 s returns `confirmation_required`
30
+ with a single-use `confirm_token` for that exact call: the assistant asks you in the
31
+ conversation and retries with it; no more forms are sent in that session. Declines now carry
32
+ `reason` (`user_declined`, `form_dismissed`, `client_declined_form`). New
33
+ `netconverter mcp --no-upload-confirm` / `NETCONVERTER_MCP_UPLOAD_CONFIRM=0` turns the forms
34
+ off and relies on the assistant's own tool approval.
35
+
3
36
  ## 0.6.0 — 2026-10-30
4
37
 
5
38
  - Guided drafts retain the server-advertised ASA target format (Palo Alto SET,
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: netconverter-cli
3
- Version: 0.6.0
3
+ Version: 0.7.1
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
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
42
42
  NetConverter — by ValeronLabs LLC.
43
43
 
44
44
  ```text
45
- ◆ NetConverter v0.6.0 ● Server ◆ Bridge claude-code · 2m ago
45
+ ◆ NetConverter v0.7.1 ● Server ◆ Bridge claude-code · 2m ago
46
46
  ▍ Start
47
47
  ▍ /convert Migrate a configuration to another vendor
48
48
  ▍ /validate Check a configuration before migrating
@@ -142,9 +142,18 @@ works on your configurations only through the bridge.
142
142
  Then ask your assistant, for example: *"Validate edge-fw.conf and tell me what it finds,"*
143
143
  *"Convert it to Palo Alto XML,"* *"Can WEB reach DB on tcp/1433?"*
144
144
 
145
+ **Guided migration:** *"Prescan edge-fw.conf for Palo Alto XML and walk me through the decisions."*
146
+ `submit_file(..., job_type="prescan")` stops at a `psc_` prescan; the assistant reads the decisions
147
+ (`list_operations`, `get_decision_document`, `validate_decision_document`), records your choices
148
+ (`propose_operations`) and, with your OK, queues the conversion (`submit_conversion`). These tools
149
+ need the folder at `netconverter privacy level full`; the two write tools also need them enabled
150
+ for your tenant (docs/COMMANDS.md § Guided migration). If your assistant declines the upload
151
+ confirmation without showing it (ChatGPT, Claude Code), approve in the conversation or run the
152
+ bridge with `--no-upload-confirm`.
153
+
145
154
  Bridge tools: `submit_file`, `job_status`, `wait_for_job`, `account`, `download`,
146
- plus an allowlist of NetConverter's read-only tools (reports, evidence, NAT, flows,
147
- knowledge base). What the assistant sees is this folder's **exposure level**
155
+ plus an allowlist of NetConverter's tools (reports, evidence, NAT, flows, knowledge base,
156
+ guided mapping and guided migration). What the assistant sees is this folder's **exposure level**
148
157
  (`netconverter privacy level none|masked|selected|full`, default **masked**: the strict view,
149
158
  names as tokens, addresses masked, no configuration content); secrets are removed at every
150
159
  level, and raising the level needs a confirmation typed in a terminal (docs/PRIVACY.md).
@@ -161,6 +170,42 @@ hold the assistant at masked.
161
170
  Inside the app, `/activity` and the header's **Bridge** pill show what your AI did
162
171
  through the bridge — paths, sizes, SHA-256 and job IDs only.
163
172
 
173
+ ### Show a diagram in IDE chat
174
+
175
+ With the matching diagram-enabled server and bridge, use this prompt in your IDE:
176
+
177
+ > For my selected completed NetConverter job, show its topology diagram here in chat.
178
+ > Call get_diagram, then pass the returned PNG artifact request unchanged to
179
+ > preview_diagram with that job_id. Use the current privacy view. Do not open a local
180
+ > file or fetch an image URL. If preview is refused, report the reason.
181
+
182
+ `preview_diagram` returns an MCP `image` content block (`mimeType: image/png`, base64
183
+ `data`) plus a text/structured receipt with SHA-256, byte count, dimensions and view.
184
+ An IDE that renders MCP image content can display it inline; rendering in individual
185
+ IDE clients still needs live qualification. The bridge fetches from the fixed,
186
+ authenticated NetConverter endpoint, verifies the recipe's SHA-256, and saves no image
187
+ file. It accepts PNG only, at most **2 MiB**, **4096 pixels per side** and **8 million
188
+ pixels**. Use `download` for larger diagrams or SVG/PDF/draw.io/JSON files.
189
+
190
+ Masked and selected levels force the server's strict projection; `none` refuses image
191
+ previews. A stale hash or a hash from another privacy view is refused: request a fresh
192
+ PNG recipe from `get_diagram`. Quick API credentials and development guided mode do
193
+ not provide this preview tool's workflow. Automatic job summaries and ordinary
194
+ downloads continue returning metadata only.
195
+
196
+ For a synthetic protocol check from the source checkout:
197
+
198
+ ```sh
199
+ uv run pytest tests/test_diagrams.py -q
200
+ ```
201
+
202
+ The preview test exchanges initialize/list/call messages over serialized stdio for
203
+ all supported protocol versions, decodes the returned PNG, and checks hash, privacy,
204
+ size and invalid-input refusals. For an IDE acceptance check, run the prompt above on
205
+ a synthetic completed job and confirm an inline image, a matching receipt hash, and
206
+ no local image-file read or arbitrary-URL request. Synthetic tests alone do not prove
207
+ live server support or a client's inline rendering.
208
+
164
209
  ## Stay current
165
210
 
166
211
  `netconverter update` upgrades a PyPI install with `uv tool upgrade netconverter-cli`;
@@ -126,3 +126,20 @@ size, SHA-256 and job ID — never content.
126
126
  removes the saved sign-in and key.
127
127
 
128
128
  Something failed? See [troubleshooting](docs/COMMANDS.md#troubleshooting).
129
+
130
+
131
+ ## Branded diagrams (matching server capability required)
132
+
133
+ After selecting a completed job, call `get_diagram` with `kind` set to
134
+ `topology`, `comparison`, `traffic`, `nat` or `policy`. The response describes
135
+ coverage and provides small artifact descriptors. Choose a descriptor and pass
136
+ its `request` object as `diagram` to the local `download` tool, along with the
137
+ job ID and optional workspace destination. Do not pass its URL.
138
+
139
+ The bridge verifies the server-provided SHA-256 and writes only into the
140
+ workspace. It returns file names and hashes, never image bytes. If source,
141
+ renderer or privacy view changed, request a new descriptor. Strict view cannot
142
+ be widened by a download recipe. Missing target/flow evidence stays explicit.
143
+ Editable draw.io files are documentation; editing them changes no configuration
144
+ or validation result. Guided draft and restricted Quick credentials retain their
145
+ existing artifact flows; this request uses completed jobs on the full API.
@@ -7,7 +7,7 @@
7
7
  NetConverter — by ValeronLabs LLC.
8
8
 
9
9
  ```text
10
- ◆ NetConverter v0.6.0 ● Server ◆ Bridge claude-code · 2m ago
10
+ ◆ NetConverter v0.7.1 ● 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
@@ -107,9 +107,18 @@ works on your configurations only through the bridge.
107
107
  Then ask your assistant, for example: *"Validate edge-fw.conf and tell me what it finds,"*
108
108
  *"Convert it to Palo Alto XML,"* *"Can WEB reach DB on tcp/1433?"*
109
109
 
110
+ **Guided migration:** *"Prescan edge-fw.conf for Palo Alto XML and walk me through the decisions."*
111
+ `submit_file(..., job_type="prescan")` stops at a `psc_` prescan; the assistant reads the decisions
112
+ (`list_operations`, `get_decision_document`, `validate_decision_document`), records your choices
113
+ (`propose_operations`) and, with your OK, queues the conversion (`submit_conversion`). These tools
114
+ need the folder at `netconverter privacy level full`; the two write tools also need them enabled
115
+ for your tenant (docs/COMMANDS.md § Guided migration). If your assistant declines the upload
116
+ confirmation without showing it (ChatGPT, Claude Code), approve in the conversation or run the
117
+ bridge with `--no-upload-confirm`.
118
+
110
119
  Bridge tools: `submit_file`, `job_status`, `wait_for_job`, `account`, `download`,
111
- plus an allowlist of NetConverter's read-only tools (reports, evidence, NAT, flows,
112
- knowledge base). What the assistant sees is this folder's **exposure level**
120
+ plus an allowlist of NetConverter's tools (reports, evidence, NAT, flows, knowledge base,
121
+ guided mapping and guided migration). What the assistant sees is this folder's **exposure level**
113
122
  (`netconverter privacy level none|masked|selected|full`, default **masked**: the strict view,
114
123
  names as tokens, addresses masked, no configuration content); secrets are removed at every
115
124
  level, and raising the level needs a confirmation typed in a terminal (docs/PRIVACY.md).
@@ -126,6 +135,42 @@ hold the assistant at masked.
126
135
  Inside the app, `/activity` and the header's **Bridge** pill show what your AI did
127
136
  through the bridge — paths, sizes, SHA-256 and job IDs only.
128
137
 
138
+ ### Show a diagram in IDE chat
139
+
140
+ With the matching diagram-enabled server and bridge, use this prompt in your IDE:
141
+
142
+ > For my selected completed NetConverter job, show its topology diagram here in chat.
143
+ > Call get_diagram, then pass the returned PNG artifact request unchanged to
144
+ > preview_diagram with that job_id. Use the current privacy view. Do not open a local
145
+ > file or fetch an image URL. If preview is refused, report the reason.
146
+
147
+ `preview_diagram` returns an MCP `image` content block (`mimeType: image/png`, base64
148
+ `data`) plus a text/structured receipt with SHA-256, byte count, dimensions and view.
149
+ An IDE that renders MCP image content can display it inline; rendering in individual
150
+ IDE clients still needs live qualification. The bridge fetches from the fixed,
151
+ authenticated NetConverter endpoint, verifies the recipe's SHA-256, and saves no image
152
+ file. It accepts PNG only, at most **2 MiB**, **4096 pixels per side** and **8 million
153
+ pixels**. Use `download` for larger diagrams or SVG/PDF/draw.io/JSON files.
154
+
155
+ Masked and selected levels force the server's strict projection; `none` refuses image
156
+ previews. A stale hash or a hash from another privacy view is refused: request a fresh
157
+ PNG recipe from `get_diagram`. Quick API credentials and development guided mode do
158
+ not provide this preview tool's workflow. Automatic job summaries and ordinary
159
+ downloads continue returning metadata only.
160
+
161
+ For a synthetic protocol check from the source checkout:
162
+
163
+ ```sh
164
+ uv run pytest tests/test_diagrams.py -q
165
+ ```
166
+
167
+ The preview test exchanges initialize/list/call messages over serialized stdio for
168
+ all supported protocol versions, decodes the returned PNG, and checks hash, privacy,
169
+ size and invalid-input refusals. For an IDE acceptance check, run the prompt above on
170
+ a synthetic completed job and confirm an inline image, a matching receipt hash, and
171
+ no local image-file read or arbitrary-URL request. Synthetic tests alone do not prove
172
+ live server support or a client's inline rendering.
173
+
129
174
  ## Stay current
130
175
 
131
176
  `netconverter update` upgrades a PyPI install with `uv tool upgrade netconverter-cli`;
@@ -132,6 +132,7 @@ netconverter connect --all # every assistant found on this compute
132
132
  netconverter connect chatgpt # ChatGPT / claude.ai: prints remote-connector setup steps
133
133
  netconverter mcp --workspace ~/migrations # what an assistant runs; not for interactive use
134
134
  netconverter mcp --level none --workspace ~/migrations # lower this folder's level for one bridge
135
+ netconverter mcp --no-upload-confirm --workspace ~/migrations # no confirmation forms (ChatGPT, Claude Code)
135
136
  netconverter privacy status # this folder's exposure level, what each level shows, recent changes
136
137
  netconverter privacy level none # verdicts and counts only (lowering needs no confirmation)
137
138
  netconverter privacy level full # raising asks you to type "raise to full" in a terminal
@@ -212,38 +213,71 @@ delays a command; its result is cached in your user cache folder.
212
213
 
213
214
  | Tool | Returns |
214
215
  | --- | --- |
215
- | `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 |
216
+ | `submit_file(path, source_vendor, target_vendor?, job_type?, options?, confirm_token?)` | `job_id`, `status`, `sha256`, `bytes`. `job_type`: `convert`, `validate`, `optimize`, `prescan`, or `analyze` (= validate). `prescan` starts a guided migration: the job stops at a `psc_` prescan for your decisions (`target_vendor` optional; only `file_name` as an option) and the result adds `job_type`, `next_steps` and `guided_tools` (see Guided migration below). `confirm_token` only after a `confirmation_required` error. `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 |
216
217
  | `job_status(job_id)` | Status, verdict, review flag, progress and stage when sent, reason counts, vendors |
217
218
  | `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 |
218
- | `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` (true below `full`), `exposure_level` and `exposure_sections` (the level in force, see Exposure levels), `view_mode_grant` and `view_clamped` when the server reports them, `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) |
219
+ | `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` (true below `full`), `exposure_level` and `exposure_sections` (the level in force, see Exposure levels), `view_mode_grant` and `view_clamped` when the server reports them, `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), `guided_migration` (full API: `tools` the session lists, and `hidden_by_level` with the `fix` when the level hides them, or a `note` naming the write tools the server does not list for this account), `credential_source` (`clerk_session`, `api_key_environment`, `api_key_stored` or `none`; the one credential REST and the remote tools share) |
219
220
  | `download(job_id, dest_dir=".")` | Saved file names, sizes and SHA-256 |
220
221
 
221
222
  Every local tool declares an `outputSchema` for its `structuredContent` (error results carry
222
223
  none). When the assistant advertises form elicitation in `initialize` (Claude Code, Codex, Cursor
223
224
  CLI), `submit_file` first asks in the assistant's own dialog: "Upload <path> (<bytes>, SHA-256 …) to
224
225
  NetConverter for <job type>?". Accept uploads; Decline or a dismissed dialog sends nothing and the
225
- tool returns `upload_declined`. Without elicitation, or when the assistant answers the request with
226
- an error, the upload proceeds after the assistant's own tool approval, as before. The dialog shows
227
- the path, size and hash only, never the file's text.
226
+ tool returns `upload_declined` (`reason`: `user_declined` or `form_dismissed`). Without elicitation,
227
+ or when the assistant answers the request with an error, the upload proceeds after the assistant's
228
+ own tool approval, as before. The dialog shows the path, size and hash only, never the file's text.
229
+ `apply_mapping_answers` and `submit_conversion` ask the same way before a conversion is queued
230
+ (`apply_declined`).
231
+
232
+ Some assistants (ChatGPT, Claude Code) advertise form elicitation but decline without showing the
233
+ form. A decline or dismissal that comes back within 1.5 seconds is treated as the client's, not
234
+ yours: nothing is sent, the tool returns `confirmation_required` (`reason: client_declined_form`)
235
+ with a single-use `confirm_token` bound to that exact call (10 minutes), and the bridge sends no
236
+ more forms in that session. The assistant asks you in the conversation; only on your yes does it
237
+ repeat the call with `confirm_token`. To skip forms entirely and rely on the assistant's own tool
238
+ approval, start the bridge with `netconverter mcp --no-upload-confirm` (or set
239
+ `NETCONVERTER_MCP_UPLOAD_CONFIRM=0` in the assistant's MCP server environment).
228
240
 
229
241
  The bridge also offers two MCP prompts: `guided-migration` (from a file path to a verdict and
230
242
  artifacts) and `mapping-review` (optional `job_id`: what was mapped, what needs review, what is
231
243
  blocked). Both tell the assistant it will not get configuration content and name the folder's
232
244
  exposure level. `--guided` keeps its own prompts (`migration-studio`, `pre-cutover-review`).
233
245
 
246
+ ### Guided migration (prescan → decisions → conversion)
247
+
248
+ 1. `submit_file(path, source_vendor, target_vendor?, job_type="prescan")` uploads the file and
249
+ returns a `psc_` job id; nothing is converted yet. `wait_for_job` until it is completed.
250
+ 2. `list_operations`, `get_decision_document` and `validate_decision_document` with
251
+ `job_id=psc_…` read the decisions the prescan found.
252
+ 3. With your OK, `propose_operations(job_id, changes, base_sha256)` records each choice as a new
253
+ revision, and `submit_conversion(job_id, revision)` queues the conversion (confirmed like an
254
+ upload); it answers with the new `tra_` job id. `wait_for_job` and `download` as usual.
255
+
256
+ The guided tools are in the default list only, so they need exposure level `full`:
257
+ run `netconverter privacy level full` in a terminal in the folder, then reconnect the assistant's
258
+ netconverter server (assistants cache the tool list). `propose_operations` and `submit_conversion`
259
+ are write tools: the server lists them only where they are enabled for your tenant, and checks
260
+ and audits every call. `account` (`guided_migration`) and the remote `get_account` say which tools
261
+ this session has and why any are missing. A sign-in (`netconverter login --clerk`) or an
262
+ enterprise API key with `write:jobs` both work; pilot (Terminal Quick) keys have no prescan.
263
+
234
264
  Remote NetConverter tools are proxied only from a fixed allowlist, and never a
235
- `submit_*` tool. Default: `compare_against_intent`, `fetch`, `get_account`,
265
+ `submit_*` tool other than `submit_conversion` (a prescan id and a revision, no
266
+ configuration text). Default: `compare_against_intent`, `fetch`, `get_account`,
236
267
  `get_acl_summary`, `get_critical_object_impact`, `get_dependency_chains`,
237
268
  `get_evidence`, `get_interface_summary`, `get_job_brief`, `get_management_config`,
238
269
  `get_nat_summary`, `get_object_dependencies`, `get_object_summary`, `get_report`,
239
270
  `get_route_summary`, `get_target_config`, `get_translation_edge_summary`,
240
271
  `get_unused_objects`, `get_vpn_summary`, `get_zone_summary`, `kb_explain`,
241
272
  `kb_search`, `list_jobs`, `list_objects_with_attribute`, `list_rules_matching`,
242
- `query_ir`, `search`, `select_job`, `simulate_flow`, `vendor_capability_lookup`.
273
+ `query_ir`, `search`, `select_job`, `simulate_flow`, `vendor_capability_lookup`,
274
+ `get_mapping_questions`, `validate_mapping`, `apply_mapping_answers`, `list_operations`,
275
+ `get_decision_document`, `validate_decision_document`, `propose_operations`, `submit_conversion`,
276
+ `set_view_level` (lowers the server's view for the session; it can never raise it).
243
277
  At levels `none`, `masked` and `selected` (the default is masked; `full` uses the default list):
244
278
  `list_jobs`, `select_job`, `get_account`, `search`, `fetch`,
245
279
  `kb_search`, `kb_explain`, `vendor_capability_lookup`, `get_job_brief`,
246
- `get_evidence`, `get_report`, plus the chosen sections' tools under `selected`. A listed tool appears
280
+ `get_evidence`, `get_report`, the three guided-mapping tools, plus the chosen sections' tools under `selected`. A listed tool appears
247
281
  only if the server offers it.
248
282
  The bridge sends the level on every request (`X-NetConverter-View: none|masked|selected|full`;
249
283
  the server may only lower the grant's view, never raise it) and reads the view in force from
@@ -259,6 +293,7 @@ Environment: `NETCONVERTER_URL`, `NETCONVERTER_PROVIDER`, `NETCONVERTER_MODEL`,
259
293
  your sign-in, while `mcp` prefers the sign-in and says on stderr which API key it leaves unused;
260
294
  `NETCONVERTER_MCP_AUTH` overrides it for `mcp` only), `NETCONVERTER_TRUSTED_HOSTS`, `NETCONVERTER_MCP_VIEW=none|masked|selected|full|strict` (same as `mcp --level`; it can only lower
261
295
  the folder's exposure level, and an explicit flag wins),
296
+ `NETCONVERTER_MCP_UPLOAD_CONFIRM=0` (same as `mcp --no-upload-confirm`),
262
297
  `NETCONVERTER_NO_UPDATE_CHECK=1` (no daily update check or notice; `account` then reports
263
298
  `update_available: null`), `NETCONVERTER_KEYRING_TIMEOUT_S` (how long to wait for the OS keyring
264
299
  before reporting it locked; default 5), `NETCONVERTER_CREDENTIAL_STORE`,
@@ -309,6 +344,8 @@ file is reported as a missing file, never as "not signed in".
309
344
  | "the credentials are in the encrypted file …, which this process cannot open" | Set `NETCONVERTER_CREDENTIAL_PASSPHRASE` (or `NETCONVERTER_CREDENTIAL_PASSPHRASE_FILE`) to the passphrase used at sign-in, in the shell or in the AI client's `env` for the bridge. "does not open" means a wrong passphrase or an altered file |
310
345
  | "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` |
311
346
  | `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 |
347
+ | `submit_file` always fails `upload_declined` / `confirmation_required` (ChatGPT, Claude Code) | The assistant declines confirmation forms without showing them. Say yes in the conversation so it can retry with the `confirm_token`, or start the bridge with `--no-upload-confirm` (`NETCONVERTER_MCP_UPLOAD_CONFIRM=0`) |
348
+ | Guided tools (`list_operations`, `submit_conversion` …) missing | They need exposure level `full` (`netconverter privacy level full`, then reconnect the assistant); the two write tools also need the tenant to have them enabled. `account` → `guided_migration` says which |
312
349
  | Assistant cannot see a NetConverter tool | The bridge lists only allowlisted remote tools the server offers (fewer below `full`; `netconverter privacy status` shows the level); update the client with `netconverter update` |
313
350
  | `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 |
314
351
 
@@ -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, Devin Desktop / Windsurf, LM Studio, OpenClaw |
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, ChatGPT desktop agent, VS Code, Devin Desktop / 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
@@ -14,7 +14,7 @@ Both need a NetConverter account with **MCP access enabled** by your administrat
14
14
 
15
15
  - **[Getting access](getting-access.md)** — new users and administrators start here
16
16
  - [claude.ai, Claude Desktop chat and the Claude mobile app](claude-ai.md) — remote connector
17
- - [ChatGPT](chatgpt.md) — remote connector
17
+ - [ChatGPT](chatgpt.md) — desktop agent (terminal bridge: upload and guided migration) or remote connector
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, Devin Desktop / Windsurf, LM Studio](other-assistants.md) — terminal bridge
@@ -0,0 +1,63 @@
1
+ # ChatGPT
2
+
3
+ ChatGPT reaches NetConverter in two ways:
4
+
5
+ - **ChatGPT desktop app's agent (Codex)**, on your computer: it runs this terminal's bridge, so
6
+ it can **upload configuration files** by path and run a **guided migration** (prescan →
7
+ decisions → conversion). Setup below under *Upload files from ChatGPT*.
8
+ - **The hosted connector** (chatgpt.com, any ChatGPT app): reads your jobs, results, account
9
+ and the knowledge base; it cannot submit configurations. Setup under *Add the connector*.
10
+
11
+ `netconverter connect chatgpt` prints both.
12
+
13
+ ## Upload files from ChatGPT (desktop app agent)
14
+
15
+ The ChatGPT desktop app's agent reads its MCP servers from `~/.codex/config.toml`, the same
16
+ file Codex CLI uses. Use a dedicated folder for your configurations (not your home folder):
17
+
18
+ ```sh
19
+ netconverter login --clerk # once; or an enterprise API key with write:jobs
20
+ mkdir -p ~/migrations && cd ~/migrations
21
+ netconverter connect codex # adds [mcp_servers.netconverter] for this folder
22
+ netconverter privacy level full # needed for the guided-migration tools; type the phrase
23
+ ```
24
+
25
+ Then restart ChatGPT. If `~/.codex/config.toml` already has `[mcp_servers.netconverter]`,
26
+ `connect` shows the table instead of changing it: edit its `args` to
27
+ `["mcp", "--workspace", "/Users/<you>/migrations"]`.
28
+
29
+ What happens in a chat (*"Prescan ~/migrations/edge.cfg from ASA to Palo Alto XML and walk me
30
+ through the decisions"*):
31
+
32
+ 1. ChatGPT asks to run `submit_file`: approve it in ChatGPT's own tool prompt.
33
+ 2. ChatGPT cannot show the bridge's upload form (it declines it unseen), so the bridge sends
34
+ nothing and answers `confirmation_required`. ChatGPT asks you in the chat whether to upload
35
+ that file (path and size); only when you say yes does it repeat the call with the
36
+ single-use `confirm_token`. The file goes from disk to NetConverter; its text never passes
37
+ through ChatGPT. The job stops at a `psc_` prescan.
38
+ 3. ChatGPT reads the decisions (`list_operations`, `get_decision_document`,
39
+ `validate_decision_document`), asks you about each one, records your choices with
40
+ `propose_operations`, and with your OK queues the conversion with `submit_conversion`
41
+ (asked in the chat the same way). `download` saves the Palo Alto output in the folder.
42
+
43
+ Exposure level: the guided-migration tools need `full` for the folder. At `masked` (the default)
44
+ the prescan still runs, and `account` says the tools are hidden and how to fix it. The write tools
45
+ (`propose_operations`, `submit_conversion`) are listed only where they are enabled for your
46
+ tenant. If you prefer ChatGPT's own tool approval as the only confirmation, add
47
+ `"--no-upload-confirm"` to the `args` (or set `NETCONVERTER_MCP_UPLOAD_CONFIRM=0`).
48
+ ChatGPT keeps the tool list from when it started: restart it after an update or a level change.
49
+
50
+ ## Add the connector
51
+
52
+ 1. In ChatGPT: **Settings → Apps & Connectors → Advanced settings** → turn on
53
+ **Developer mode**, then **Create** a custom connector.
54
+ 2. Fill it in:
55
+ - **Name:** `NetConverter`
56
+ - **MCP server URL:** `https://api.netconverter.ai/mcp/v1`
57
+ - **Authentication:** OAuth. Under the advanced OAuth settings enter
58
+ **Client ID** `RjSv1z2Gms6iS96s` and leave the client secret empty.
59
+ 3. Save, then sign in with your NetConverter account when asked.
60
+ 4. In a chat, enable NetConverter from the **+** menu (Developer mode).
61
+
62
+ Developer mode and custom connectors depend on your ChatGPT plan and workspace
63
+ settings; on business workspaces an admin may need to allow them.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "netconverter-cli"
7
- version = "0.6.0"
7
+ version = "0.7.1"
8
8
  description = "NetConverter CLI — any-vendor network configuration migration, validation and optimization, and a local MCP bridge for your AI assistant"
9
9
  readme = "README.md"
10
10
  license = "LicenseRef-NetConverter-Proprietary"
@@ -1,3 +1,3 @@
1
1
  """NetConverter CLI: file transfer and conversation are separate paths."""
2
2
 
3
- __version__ = "0.6.0"
3
+ __version__ = "0.7.1"
@@ -225,7 +225,7 @@ class ExternalClient(Client):
225
225
  """
226
226
 
227
227
  _ALLOWED = re.compile(
228
- r"(?:me|capabilities|jobs|jobs/[A-Za-z0-9_-]{1,80}(?:/translated|/report|/evidence\.xlsx|/findings\.sarif)?)\Z"
228
+ r"(?:me|capabilities|jobs|jobs/[A-Za-z0-9_-]{1,80}(?:/translated|/report|/evidence\.xlsx|/findings\.sarif|/diagrams/render)?)\Z"
229
229
  )
230
230
 
231
231
  def me(self):
@@ -279,3 +279,21 @@ class ExternalClient(Client):
279
279
  if response.is_error:
280
280
  raise self._error(response, request_id)
281
281
  return response.content
282
+
283
+ def diagram(self, job_id: str, recipe: dict, *, max_bytes=32 * 1024 * 1024) -> bytes:
284
+ """Fixed authenticated endpoint; the expected hash binds revision and view."""
285
+ path = f"jobs/{self.identifier(job_id)}/diagrams/render"
286
+ request_id = "req_" + uuid.uuid4().hex
287
+ try:
288
+ with self.http.stream("POST", path, json=recipe,
289
+ headers={"X-Request-ID": request_id}) as response:
290
+ content = bytearray()
291
+ for chunk in response.iter_bytes(chunk_size=64 * 1024):
292
+ if len(content) + len(chunk) > max_bytes:
293
+ raise APIError(413, "diagram_too_large", request_id)
294
+ content.extend(chunk)
295
+ if response.status_code != 200:
296
+ raise self._error(httpx.Response(response.status_code, content=bytes(content)), request_id)
297
+ return bytes(content)
298
+ except httpx.HTTPError:
299
+ raise APIError(0, "connection_failed", request_id) from None
@@ -11,7 +11,7 @@ from __future__ import annotations
11
11
 
12
12
  from dataclasses import dataclass, field
13
13
 
14
- JOB_TYPES = ("convert", "validate", "optimize")
14
+ JOB_TYPES = ("convert", "validate", "optimize", "prescan")
15
15
  QUICK_SOURCES = ("cisco_asa", "palo_alto_set", "palo_alto_xml", "palo_alto_panorama")
16
16
  QUICK_LIMIT_BYTES = 50_000
17
17
  DEVICE_TYPES = ("firewall", "router", "switch")
@@ -32,6 +32,7 @@ LABELS = {
32
32
  "convert": "Convert",
33
33
  "validate": "Validate",
34
34
  "optimize": "Optimize",
35
+ "prescan": "Prescan",
35
36
  "analyze": "Validate",
36
37
  }
37
38
  FIELD_LABELS = {
@@ -191,6 +191,11 @@ def mcp_view_default() -> str | None:
191
191
  return value if value in MCP_VIEWS else None
192
192
 
193
193
 
194
+ def mcp_upload_confirm_default() -> bool:
195
+ """`mcp` asks for upload/convert confirmation forms unless NETCONVERTER_MCP_UPLOAD_CONFIRM is 0/false/off (#37)."""
196
+ return os.getenv("NETCONVERTER_MCP_UPLOAD_CONFIRM", "").strip().lower() not in {"0", "false", "no", "off"}
197
+
198
+
194
199
  def mcp_auth_default() -> str:
195
200
  """`mcp --auth` default: NETCONVERTER_MCP_AUTH, else NETCONVERTER_AUTH (#16), else auto."""
196
201
  for name in ("NETCONVERTER_MCP_AUTH", "NETCONVERTER_AUTH"):
@@ -281,7 +286,7 @@ def run_mcp(args):
281
286
  options["credential_loader"] = lambda: choose_mcp_credential(args.auth, args.server, mcp_url)
282
287
  run_stdio(Bridge(args.workspace, args.server, rest, remote, strict=strict,
283
288
  credential_source=source, level=cap.level, sections=cap.sections,
284
- workspace_level=True, **options))
289
+ workspace_level=True, upload_confirm=getattr(args, "upload_confirm", True), **options))
285
290
  finally:
286
291
  if remote:
287
292
  remote.close()
@@ -606,7 +611,13 @@ def parser():
606
611
  mcp.add_argument("--strict", dest="view", action="store_const", const="strict",
607
612
  help="at most masked (the strict view)")
608
613
  mcp.add_argument("--full", dest="view", action="store_const", const="full",
609
- help="up to full, when this folder's level is full")
614
+ help="up to full, when this folder's level is full (`netconverter privacy level full`; "
615
+ "the guided-migration tools, prescan to submit_conversion, need it)")
616
+ mcp.add_argument("--no-upload-confirm", dest="upload_confirm", action="store_false",
617
+ default=mcp_upload_confirm_default(),
618
+ help="never send a confirmation form before an upload or a queued conversion; the AI "
619
+ "client's own tool approval confirms instead (for clients that decline forms "
620
+ "unseen, e.g. ChatGPT, Claude Code; NETCONVERTER_MCP_UPLOAD_CONFIRM=0)")
610
621
  mcp.add_argument("--workspace", default=argparse.SUPPRESS, help="folder the file tools may read and write")
611
622
  from .connect import CLIENTS as _AI_CLIENTS
612
623
  connect = subs.add_parser(
@@ -371,7 +371,12 @@ REMOTE_STEPS = {
371
371
  " Authentication: OAuth. Under advanced OAuth settings enter the NetConverter OAuth\n"
372
372
  " client ID your administrator gives you, then sign in with your\n"
373
373
  " NetConverter account when asked.\n"
374
- "Then enable NetConverter in a chat from the + menu (Developer mode)."),
374
+ "Then enable NetConverter in a chat from the + menu (Developer mode).\n"
375
+ "To upload configuration files from ChatGPT: the ChatGPT desktop app's agent (Codex) runs\n"
376
+ "this bridge from ~/.codex/config.toml. In your migrations folder run\n"
377
+ "`netconverter connect codex` and, for the guided-migration tools,\n"
378
+ "`netconverter privacy level full`; then restart ChatGPT. ChatGPT cannot show the\n"
379
+ "upload form, so it asks you in the chat before each upload (docs/connect/chatgpt.md)."),
375
380
  "claude-ai": (
376
381
  "claude.ai (web and mobile)",
377
382
  "On claude.ai: Settings → Connectors → Add custom connector.\n"
@@ -0,0 +1,67 @@
1
+ """Download a governed diagram recipe; never follow a model-supplied URL."""
2
+ from __future__ import annotations
3
+
4
+ import hashlib
5
+ import struct
6
+ from typing import Literal
7
+ from pydantic import BaseModel, ConfigDict, Field
8
+
9
+ from .workspace import WorkspaceError
10
+
11
+ MAX_PREVIEW_BYTES = 2 * 1024 * 1024
12
+ MAX_PREVIEW_EDGE = 4096
13
+ MAX_PREVIEW_PIXELS = 8_000_000
14
+
15
+
16
+ class DiagramArtifact(BaseModel):
17
+ model_config = ConfigDict(extra='forbid', strict=True)
18
+ kind: Literal['topology', 'comparison', 'traffic', 'nat', 'policy'] = 'topology'
19
+ side: Literal['source', 'target'] = 'source'
20
+ max_nodes: int = Field(default=60, ge=4, le=120)
21
+ format: Literal['svg', 'png', 'pdf', 'drawio', 'json']
22
+ view: Literal['default', 'strict'] = 'default'
23
+ expected_sha256: str = Field(pattern=r'^[a-f0-9]{64}$')
24
+ flow: dict | None = None
25
+
26
+
27
+ class DiagramPreviewArtifact(DiagramArtifact):
28
+ format: Literal['png']
29
+
30
+
31
+ def fetch_diagram(client, job_id, recipe, *, strict=False, preview=False):
32
+ """One recipe/view/hash contract for disk downloads and explicit previews."""
33
+ artifact = DiagramArtifact.model_validate(recipe)
34
+ if preview and artifact.format != 'png':
35
+ raise ValueError('Previews require a PNG recipe from get_diagram')
36
+ if artifact.flow is not None and artifact.kind != 'traffic':
37
+ raise ValueError('Flow inputs require a traffic diagram')
38
+ if strict:
39
+ artifact.view = 'strict'
40
+ if artifact.flow is not None:
41
+ raise ValueError('Explicit flow inputs are unavailable in strict view')
42
+ options = {'max_bytes': MAX_PREVIEW_BYTES} if preview else {}
43
+ content = client.diagram(job_id, artifact.model_dump(exclude_none=True), **options)
44
+ if hashlib.sha256(content).hexdigest() != artifact.expected_sha256:
45
+ raise WorkspaceError('Artifact checksum failed; no diagram was returned')
46
+ return artifact, content
47
+
48
+
49
+ def preview_dimensions(content):
50
+ """Reject non-PNG and oversized canvases before sending an image to the IDE."""
51
+ if len(content) > MAX_PREVIEW_BYTES:
52
+ raise WorkspaceError('Diagram preview exceeds the 2 MiB limit; download it instead')
53
+ if (len(content) < 33 or content[:8] != b'\x89PNG\r\n\x1a\n'
54
+ or content[8:16] != b'\x00\x00\x00\x0dIHDR'):
55
+ raise WorkspaceError('Diagram preview is not a PNG image')
56
+ width, height = struct.unpack('>II', content[16:24])
57
+ if (not width or not height or max(width, height) > MAX_PREVIEW_EDGE
58
+ or width * height > MAX_PREVIEW_PIXELS):
59
+ raise WorkspaceError('Diagram preview canvas is too large; request fewer nodes or download it')
60
+ return width, height
61
+
62
+
63
+ def download_diagram(client, output, job_id, recipe, *, strict=False):
64
+ artifact, content = fetch_diagram(client, job_id, recipe, strict=strict)
65
+ # Include immutable byte identity, preserving previous document revisions.
66
+ filename = f'{artifact.kind}-{artifact.side}-{artifact.expected_sha256[:16]}.{artifact.format}'
67
+ return output.save_artifact(job_id, filename, content, artifact.expected_sha256)
@@ -57,7 +57,7 @@ BODY_OPTIONS = {
57
57
  "properties": {k: {"type": "boolean"} for k in OPTIMIZATION_FLAGS},
58
58
  "description": "Optimize only: analysis switches."}, ("optimize",)),
59
59
  "file_name": ({**_text(255), "description": "Name shown for the job in the portal."},
60
- ("convert", "validate", "optimize")),
60
+ ("convert", "validate", "optimize", "prescan")),
61
61
  }
62
62
  DECISION_OPTIONS = {
63
63
  "zone_mapping": ({"type": "object", "additionalProperties": _text(200), "maxProperties": 500,