| get_workspace_infoA | Return the active workspace and the list of .nsm master files in it. Always safe to call. If no workspace has been set yet, returns
workspace_active=false with a reminder to call suggest_workspace().
Returns:
JSON string with keys:
workspace_active: true/false
working_directory: absolute path or null
masters: list of .nsm master filenames ('[MASTER]*.nsm')
xlsx_masters: list of .xlsx files that need conversion via
import_master before they can be used
other_files: list of generated outputs (DIAGRAM / AI_Context, etc.)
note: human-readable hint when no workspace is active
|
| suggest_workspaceA | Suggest OS-appropriate workspace directory candidates. Always safe to call. Returns a list of candidate paths under the
user's home directory (Windows / macOS / Linux), with hints about
which exist, which are writable, and which the agent should prefer.
The agent must propose ONE candidate to the user, get confirmation,
then call set_workspace(path). Custom paths under the user home are
also acceptable; the candidates are only suggestions.
Returns:
JSON string with keys:
os, current_workspace, home, candidates, guidance
|
| set_workspaceA | Set the active workspace directory for this session. Validates that the path is under the user's home directory (defence
against arbitrary filesystem access), creates the directory if it
does not exist, and confirms it is writable. Once set, subsequent
tool calls operate against this directory until the server restarts
or set_workspace is called again.
Args:
path: Absolute path to the desired workspace. May use '~' for
home expansion. Must resolve to a location under
Path.home().
Returns:
Confirmation message including the resolved absolute path,
or an error if validation failed.
|
| create_empty_masterA | Create a new empty Network Sketcher master file (.nsm) in the working dir. The engine's `export master_file_nodata` produces an .xlsx, which this
tool immediately converts to .nsm via xlsx_to_nsm() and discards.
The xlsx is written to a system temp directory (never to the working
directory) so that no .xlsx artefact is left behind.
Args:
filename: Optional target name. Must start with '[MASTER]' and end
with '.nsm'. No path separators allowed. Defaults to
'[MASTER]no_data.nsm'.
Returns:
Result message indicating success and final file path, or an error.
|
| get_network_stateA | Run the standard set of show commands and return aggregated results. This is the lightweight alternative to `get_ai_context`. It produces a
plain-text summary of the current network state (areas, devices,
interfaces, L1/L2/L3 topology, attributes) by invoking the show
commands listed in mcp_config.json -> ai_context_show_commands.
Args:
master: Master filename inside the working directory
(e.g. '[MASTER]office.xlsx'), or an absolute path inside
the working directory.
Returns:
Concatenated stdout from each show command, grouped by command name.
|
| get_ai_contextB | Generate the full AI Context file for a master and return its contents. This invokes `export ai_context_file` (always with
--accept-security-risk to avoid the interactive prompt) and reads back
the generated '[AI_Context]<basename>.txt'. The AI Context bundles the
network state plus the full CLI command reference, suitable for
feeding to a language model that needs to plan multi-step edits.
Args:
master: Master filename inside the working directory
(e.g. '[MASTER]office.xlsx').
Returns:
Full text content of the generated AI Context file, or an error.
|
| run_commandsA | Execute one or more Network Sketcher CLI commands against a .nsm master. PREREQUISITE: You MUST have called get_ai_context(master) (or at least
get_network_state(master)) at least once in this session before using
this tool. Without that context you do not know the current state nor
the available CLI syntax, and your edits are likely to be wrong.
Each non-empty line of `commands` is parsed with shlex and run as a
single CLI invocation. Allowed verbs: add, rename, delete, show.
`export` is intentionally excluded; use create_empty_master,
export_diagram, or get_ai_context instead.
The `--master` argument is appended automatically; do NOT include it
in the command lines.
Args:
master: Master filename inside the working directory.
commands: Newline-separated CLI command lines. Example:
add device 'SW-3' --area 'DC1'
add l1_link 'SW-2' 'GE 0/0' 'SW-3' 'GE 0/1'
Returns:
Per-line results: each command's exit summary and stdout, joined.
|
| import_masterA | Convert an existing .xlsx master into a .nsm in the working directory. The Local MCP edition operates on .nsm files exclusively. Use this tool
once at the start of a session to bring an existing .xlsx master under
.nsm management. The original .xlsx is left untouched.
Args:
xlsx_path: Absolute path to the source .xlsx file. The file must
exist and have an '.xlsx' extension. The path itself
may live outside the working directory.
target_name: Optional output filename. Must start with '[MASTER]'
and end with '.nsm'. If omitted, the source basename
is reused with the extension swapped to '.nsm'.
Returns:
Result message with the produced .nsm path, or an error.
|
| export_master_xlsxA | Convert a .nsm master back to .xlsx for Excel/Offline edition use. The output is placed in the working directory next to the source .nsm,
using the same basename with '.xlsx' extension. The .nsm itself is
not modified.
Args:
master: Master filename inside the working directory
(e.g. '[MASTER]office.nsm').
Returns:
Result message with the produced .xlsx path, or an error.
|
| export_diagramA | Export an L1, L2, or L3 network diagram for the given .nsm master. PREREQUISITE: You MUST have called get_ai_context(master) (or at least
get_network_state(master)) at least once in this session for this
master so that you understand which layer is meaningful to export
given the current network state.
Args:
master: Master filename inside the working directory.
layer: One of 'l1', 'l2', 'l3' (case-insensitive).
format: 'svg' (default) or 'pptx'. SVG is faster and renders in the
browser. PPTX is editable in PowerPoint.
area: Optional area name. When omitted, every layer now emits a
combined All-Areas diagram so that L1/L2/L3 share a
uniform default contract:
- L1: all_areas_tag
(file: '[L1_DIAGRAM]AllAreasTag_<basename>.svg' or .pptx).
- L2: all_areas
(file: '[L2_DIAGRAM]AllAreas_<basename>.svg').
NOTE: PPTX output for L2 area=None is not yet supported
by the engine ('--type all_areas requires --format svg'),
so the legacy first-area PPTX behaviour is preserved
when format='pptx' (file:
'[L2_DIAGRAM]<first_area>_<basename>.pptx').
- L3: all_areas
(file: '[L3_DIAGRAM]AllAreas_<basename>.svg' or .pptx).
When given:
- L1 generates only that area's per-area-tag SVG
(file: '[L1_DIAGRAM]PerAreaTag_<basename>_<area>.svg').
- L3 generates only that area's per-area SVG
(file: '[L3_DIAGRAM]PerArea_<basename>_<area>.svg').
- L2 generates that area's diagram
(file: '[L2_DIAGRAM]<area>_<basename>.svg' or .pptx).
area is only honored together with format='svg' for L1/L3
(the engine's PPTX path always produces an all-areas pptx);
L2 accepts area for both formats. Unknown area names are
rejected by the engine with a clear error.
Returns:
A summary describing which files were generated, plus the engine
stdout. Use get_workspace_info afterwards to enumerate the files.
|
| export_device_table_htmlA | Export an interactive HTML Device Table preview from a .nsm master. Generates a single self-contained HTML file with four tabs (L1 Table /
L2 Table / L3 Table / Attribute) whose layout, styling, and behaviour
match the Online edition's Device Preview screen (sticky-header table,
per-tab CSV / HTML download buttons, URL-hash initial tab selection).
The output file is written next to the master as
``[DEVICE_TABLE]{basename}.html`` and contains no external CDN /
script references, so it can be opened directly from disk or shared
as a single artifact.
PREREQUISITE: call get_ai_context(master) (or at least
get_network_state(master)) once per session for this master so you
understand the data being exported.
Args:
master: Master filename inside the working directory
(e.g. '[MASTER]office.nsm') or an absolute path inside
the active workspace.
Returns:
A summary describing the generated file and its size.
|
| build_default_outputsA | Generate the default deliverable bundle for a .nsm master. Runs the following three steps in a single call:
1. export combined_diagram --type all_areas
Produces FOUR artifacts in one shot:
- [L1_DIAGRAM]AllAreasTag_<base>.svg (per-layer side effect)
- [L2_DIAGRAM]AllAreas_<base>.svg (per-layer side effect)
- [L3_DIAGRAM]AllAreas_<base>.svg (per-layer side effect)
- [L1L2L3_DIAGRAM]AllAreas_<base>.html (combined tabbed HTML
viewer; primary deliverable)
The combined HTML embeds all three layer SVGs in a self-contained
page with three switchable tabs (L1 / L2 / L3) styled to match
the Device Table viewer. Per-layer SVGs are reused if already
present in the workspace; missing ones are generated as needed.
2. export_device_table_html
(file: [DEVICE_TABLE]<base>.html)
3. (re-)generate AI Context file
(file: [AI_Context]<base>.txt)
Each step is judged independently; if one step fails the remaining
steps still execute and the per-step status is reflected in the
returned summary. The summary lists six rows -- one per individual
artifact -- so callers can see which layers (if any) failed even when
the combined HTML succeeded.
Per-area combined HTMLs (e.g. ``[L1L2L3_DIAGRAM]<area>_<base>.html``)
are NOT generated by default. If you need one, request it explicitly
via ``run_commands(["export combined_diagram --type per_area --area
<name>"])`` after this tool returns.
Call this ONCE as the final step after constructing or substantially
updating a network so that diagrams, the Device Table preview, and the
AI Context bundle are all refreshed in lock-step. Prefer this tool
over individually calling export_diagram / export_device_table_html /
get_ai_context for routine finalization.
Args:
master: Master filename inside the working directory
(e.g. '[MASTER]office.nsm') or an absolute path inside
the active workspace.
Returns:
A multi-line summary listing each artifact's status, the generated
file path, and a trailing 'Summary: N/6 succeeded.' line.
|
