mirror of
https://github.com/GNS3/gns3-server.git
synced 2026-11-20 13:15:14 +02:00
refactor(copilot): reuse MCP tools via a bridge; extract shared device runners
The copilot and the MCP service maintained two parallel wrapper layers (LangChain BaseTool classes vs @mcp.tool() functions) over the same handlers in gns3_client/api_handlers.py. Descriptions and parameters drifted apart (compute_id and link_type were missing on the copilot side). This makes the MCP registration the single source of truth and removes the duplicated wrappers. tools_v2/mcp_bridge.py adapts the MCP server's tool registration into LangChain tools: names, descriptions and argument schemas come from the MCP tools. The pool is filtered to project-scoped tools (MCP_ALLOWED_TOOLS) because the copilot runs inside one open project — project management, compute/appliance/image administration and server info tools stay out. The bridge carries the copilot's request JWT into the MCP contextvars (username/token_version decoded from the token so ticket-minting tools work) and runs the async MCP functions from the copilot's sync tool node on either thread flavor. Mode toolsets (teaching / lab_automation / troubleshooting_injection) are now composed from adapted MCP tools plus a few copilot-native ones that add value the MCP versions lack: link_create (port-name resolution), wait_seconds, packet_analysis(+skills), and the topology reader. Eight orphaned LangChain wrappers are deleted. The device command tools had the dependency inverted (the MCP handlers instantiated the copilot LangChain classes and round-tripped through JSON strings). The Nornir/Netmiko classes moved verbatim (git mv) into the shared layer as plain runners — DeviceConfigCommandRunner, DeviceShowCommandRunner, VpcsCommandRunner — with _run(json_string) becoming run(params, gns3_ctx). The optional Jinja2 template rendering moved from the MCP handlers into the runners (and into utils/device_configs.render_device_template), so both entry paths get it; the MCP handlers are now pure delegation. This also drops the json.dumps/json.loads detour the MCP path used to take. test_tool_params consistency gate extended: a handler that forwards the whole params dict to a callee is a wildcard (same rationale as the params.items() case) — the per-key check cannot see through delegation.
This commit is contained in:
34 files changed
+986
-2772
No files matched your search
@@ -12,11 +12,13 @@ See LICENSE file for licensing information.
|
||||
|
||||
GNS3-Copilot provides tools for managing the lifecycle of network devices and topology in GNS3 projects. These tools enable AI agents to create, connect, start, stop, suspend, and manage nodes as part of automated lab management workflows.
|
||||
|
||||
> **Tool source (single source of truth):** most copilot tools are no longer hand-written LangChain wrappers. They are adapted from the MCP server's tool registration by `tools_v2/mcp_bridge.py` — tool names, descriptions and argument schemas are identical to the MCP tools (`node_create`, `node_start`, `device_show_run`, ...). The bridge filters the MCP registration down to project-scoped tools (the copilot runs inside one open project; `project_*`, `compute_*`, `appliance_*`, `image_*` and server administration tools are excluded) and bridges the copilot's request JWT into the MCP context. Copilot-native tools remain only where they add value: `link_create` (port-name resolution), `wait_seconds`, `packet_analysis`, `packet_analysis_skills`, `gns3_topology_reader`.
|
||||
|
||||
## Available Tools
|
||||
|
||||
### GNS3TemplateTool 🆕
|
||||
### template_list 🆕
|
||||
|
||||
**Tool Name:** `get_gns3_templates`
|
||||
**Tool Name:** `template_list`
|
||||
|
||||
**Description:** Retrieves all available device templates from the GNS3 server, including template names, IDs, and types. Filters out built-in utility templates that are not useful for network device configuration.
|
||||
|
||||
@@ -70,11 +72,11 @@ The following built-in utility templates are excluded as they are not actual net
|
||||
|
||||
**Use Cases:**
|
||||
- Discover available device types before creating nodes
|
||||
- Get template_id for GNS3CreateNodeTool
|
||||
- Get template_id for node_create
|
||||
- Template inventory management
|
||||
- Focus on network devices rather than utility templates
|
||||
|
||||
### GNS3CreateNodeTool 🆕
|
||||
### node_create 🆕
|
||||
|
||||
**Tool Name:** `node_create`
|
||||
|
||||
@@ -138,7 +140,7 @@ The following built-in utility templates are excluded as they are not actual net
|
||||
|
||||
**Implementation Details:**
|
||||
- Calls `POST /projects/{project_id}/nodes` for each node
|
||||
- Uses template_id from GNS3TemplateTool
|
||||
- Uses template_id from template_list
|
||||
- Assigns default names sequentially (e.g., R1, R2, R3)
|
||||
|
||||
### GNS3LinkTool 🆕
|
||||
@@ -200,9 +202,9 @@ The following built-in utility templates are excluded as they are not actual net
|
||||
- Uses adapter_number and port_number for port identification
|
||||
- Supports both physical and virtual interfaces
|
||||
|
||||
### GNS3UpdateNodeNameTool 🆕
|
||||
### node_update 🆕
|
||||
|
||||
**Tool Name:** `update_gns3_node_name`
|
||||
**Tool Name:** `node_update`
|
||||
|
||||
**Description:** Updates the name of one or multiple nodes in a GNS3 project.
|
||||
|
||||
@@ -250,9 +252,9 @@ The following built-in utility templates are excluded as they are not actual net
|
||||
- Cannot rename while node is started (except special node types)
|
||||
- CAN rename while node is suspended
|
||||
|
||||
### GNS3StartNodeTool
|
||||
### node_start
|
||||
|
||||
**Tool Name:** `start_gns3_node`
|
||||
**Tool Name:** `node_start`
|
||||
|
||||
**Description:** Starts one or multiple nodes in a GNS3 project with progress tracking and status monitoring. Features dynamic wait time calculation based on device types for optimal performance.
|
||||
|
||||
@@ -327,7 +329,7 @@ The tool automatically detects node types and calculates optimal wait times:
|
||||
- Logs device types and selected wait strategy
|
||||
- Progress bar displays calculated wait time
|
||||
|
||||
### GNS3StartNodeQuickTool 🆕
|
||||
### node_start 🆕
|
||||
|
||||
**Tool Name:** `start_gns3_node_quick`
|
||||
|
||||
@@ -365,7 +367,7 @@ The tool automatically detects node types and calculates optimal wait times:
|
||||
|
||||
**When to Use Quick vs Regular Start:**
|
||||
|
||||
| Scenario | Use `start_gns3_node` | Use `start_gns3_node_quick` |
|
||||
| Scenario | Use `node_start` | Use `start_gns3_node_quick` |
|
||||
|----------|----------------------|-----------------------------|
|
||||
| Interactive lab startup | ✅ | ❌ |
|
||||
| CI/CD pipeline | ❌ | ✅ |
|
||||
@@ -377,11 +379,11 @@ The tool automatically detects node types and calculates optimal wait times:
|
||||
- Calls `POST /projects/{project_id}/nodes/{node_id}/start` for each node
|
||||
- Returns immediately after sending start commands (no progress bar)
|
||||
- Status reflects command send result, not boot completion
|
||||
- Source: `gns3_start_node.py` (same file as `GNS3StartNodeTool`)
|
||||
- Source: MCP tool `node_start`, adapted via `tools_v2/mcp_bridge.py`
|
||||
|
||||
### GNS3StopNodeTool
|
||||
### node_stop
|
||||
|
||||
**Tool Name:** `stop_gns3_node`
|
||||
**Tool Name:** `node_stop`
|
||||
|
||||
**Description:** Stops one or multiple nodes in a GNS3 project.
|
||||
|
||||
@@ -426,9 +428,9 @@ The tool automatically detects node types and calculates optimal wait times:
|
||||
- Retrieves updated status after stop command
|
||||
- Returns detailed results for each node
|
||||
|
||||
### GNS3SuspendNodeTool
|
||||
### node_suspend
|
||||
|
||||
**Tool Name:** `suspend_gns3_node`
|
||||
**Tool Name:** `node_suspend`
|
||||
|
||||
**Description:** Suspends one or multiple nodes in a GNS3 project. Suspended nodes preserve their state in memory and can be quickly resumed.
|
||||
|
||||
@@ -512,21 +514,18 @@ The tool automatically detects node types and calculates optimal wait times:
|
||||
|
||||
```
|
||||
gns3server/agent/gns3_copilot/tools_v2/
|
||||
├── gns3_create_node.py # Node creation tool 🆕
|
||||
├── gns3_create_link.py # Link creation tool 🆕
|
||||
├── gns3_get_node_temp.py # Template retrieval tool 🆕
|
||||
├── gns3_update_node_name.py # Node rename tool 🆕
|
||||
├── gns3_start_node.py # Start node tool (+ GNS3StartNodeQuickTool)
|
||||
├── gns3_stop_node.py # Stop node tool
|
||||
├── gns3_suspend_node.py # Suspend node tool
|
||||
├── config_tools_nornir.py # Configuration command execution
|
||||
├── display_tools_nornir.py # Display command execution
|
||||
└── packet_capture_tools.py # Packet capture analysis
|
||||
├── mcp_bridge.py # Adapts MCP server tools into LangChain tools (most tools)
|
||||
├── gns3_create_link.py # Native link_create (port-name resolution)
|
||||
├── gns3_wait.py # Native wait_seconds (boot wait timer)
|
||||
├── packet_analysis_tool.py # Native packet_analysis (tshark)
|
||||
├── device_config_commands.py # Shared runner behind MCP device_config_send
|
||||
├── device_show_commands.py # Shared runner behind MCP device_show_run
|
||||
└── vpcs_commands.py # Shared runner behind MCP vpcs_config_set
|
||||
```
|
||||
|
||||
### API Integration
|
||||
|
||||
The tools call the shared REST handler layer (`gns3_copilot.gns3_client.api_handlers`), the same functions the MCP service exposes as MCP tools:
|
||||
Most tools are generated from the MCP server registration (`agent/mcp/__init__.py`) by `mcp_bridge.adapted_mcp_tools()` — the MCP registration is the single source of truth for names, descriptions and argument schemas. Underneath, both the MCP tools and the copilot-native tools call the shared REST handler layer (`gns3_copilot.gns3_client.api_handlers`):
|
||||
|
||||
```python
|
||||
from gns3server.agent.gns3_copilot.gns3_client.api_handlers import (
|
||||
@@ -568,7 +567,7 @@ listing = get_nodes_handler({"project_id": project_id}, gns3_ctx)
|
||||
|
||||
### Progress Tracking
|
||||
|
||||
**GNS3StartNodeTool** includes visual progress bar with dynamic wait time:
|
||||
**node_start** includes visual progress bar with dynamic wait time:
|
||||
|
||||
```
|
||||
Starting 3 node(s), please wait...
|
||||
@@ -577,15 +576,15 @@ Starting 3 node(s), please wait...
|
||||
|
||||
Wait time is calculated by `calculate_startup_time()` based on node types (see Dynamic Wait Time Strategy above). No hardcoded duration.
|
||||
|
||||
**GNS3StartNodeQuickTool** does NOT include progress tracking:
|
||||
**node_start** does NOT include progress tracking:
|
||||
- Returns immediately after sending start commands
|
||||
- Nodes boot in background
|
||||
|
||||
**GNS3StopNodeTool** does not include progress tracking:
|
||||
**node_stop** does not include progress tracking:
|
||||
- Stop operations are typically fast (< 5 seconds)
|
||||
- Immediate API response provides status feedback
|
||||
|
||||
**GNS3SuspendNodeTool** does not include progress tracking:
|
||||
**node_suspend** does not include progress tracking:
|
||||
- Suspend operations are typically fast (< 10 seconds)
|
||||
- Immediate API response provides status feedback
|
||||
|
||||
@@ -612,19 +611,19 @@ stateDiagram-v2
|
||||
| **Suspended** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
|
||||
|
||||
*Except special node types: cloud, nat, ethernet_switch, ethernet_hub, frame_relay_switch, atm_switch
|
||||
Note: These special node types are filtered out by GNS3TemplateTool and won't appear in template listings for network lab creation.
|
||||
Note: These special node types are filtered out by template_list and won't appear in template listings for network lab creation.
|
||||
|
||||
## Copilot Mode Integration
|
||||
|
||||
### Teaching Assistant Mode
|
||||
|
||||
**Tools Available:**
|
||||
- `GNS3TemplateTool` - List available device templates 🆕
|
||||
- `GNS3CreateNodeTool` - Create nodes in topology 🆕
|
||||
- `template_list` - List available device templates 🆕
|
||||
- `node_create` - Create nodes in topology 🆕
|
||||
- `GNS3LinkTool` - Create links between nodes 🆕
|
||||
- `GNS3UpdateNodeNameTool` - Rename nodes 🆕
|
||||
- `GNS3StartNodeTool` - For diagnostics requiring started nodes
|
||||
- `ExecuteMultipleDeviceCommands` - Execute show/display/debug commands (READ-ONLY)
|
||||
- `node_update` - Rename nodes 🆕
|
||||
- `node_start` - For diagnostics requiring started nodes
|
||||
- `device_show_run` - Execute show/display/debug commands (READ-ONLY)
|
||||
- `PacketCaptureTool` - Analyze packets from active capture
|
||||
- `DeviceSkillsTool` - Get device-specific skills and command knowledge
|
||||
|
||||
@@ -637,16 +636,16 @@ Note: These special node types are filtered out by GNS3TemplateTool and won't ap
|
||||
### Lab Automation Assistant Mode
|
||||
|
||||
**Tools Available:**
|
||||
- `GNS3TemplateTool` - List available device templates 🆕
|
||||
- `GNS3CreateNodeTool` - Create nodes in topology 🆕
|
||||
- `template_list` - List available device templates 🆕
|
||||
- `node_create` - Create nodes in topology 🆕
|
||||
- `GNS3LinkTool` - Create links between nodes 🆕
|
||||
- `GNS3UpdateNodeNameTool` - Rename nodes 🆕
|
||||
- `GNS3StartNodeTool` - Full lab deployment
|
||||
- `GNS3StopNodeTool` - Full lab shutdown
|
||||
- `GNS3SuspendNodeTool` - Lab pause with state preservation
|
||||
- `ExecuteMultipleDeviceCommands` - Execute show/display/debug commands (READ-ONLY)
|
||||
- `ExecuteMultipleDeviceConfigCommands` - Execute configuration commands
|
||||
- `VPCSCommands` - Execute VPCS commands using Netmiko
|
||||
- `node_update` - Rename nodes 🆕
|
||||
- `node_start` - Full lab deployment
|
||||
- `node_stop` - Full lab shutdown
|
||||
- `node_suspend` - Lab pause with state preservation
|
||||
- `device_show_run` - Execute show/display/debug commands (READ-ONLY)
|
||||
- `device_config_send` - Execute configuration commands
|
||||
- `vpcs_config_set` - Execute VPCS commands using Netmiko
|
||||
- `PacketCaptureTool` - Analyze packets from active capture
|
||||
- `DeviceSkillsTool` - Get device-specific skills and command knowledge
|
||||
|
||||
@@ -662,9 +661,9 @@ Note: These special node types are filtered out by GNS3TemplateTool and won't ap
|
||||
### Example 1: Start Nodes with Progress
|
||||
|
||||
```python
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import GNS3StartNodeTool
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import node_start
|
||||
|
||||
tool = GNS3StartNodeTool()
|
||||
tool = node_start()
|
||||
result = tool._run(json.dumps({"project_id": "abc-123-def", "node_ids": ["node-1", "node-2", "node-3"]}))
|
||||
|
||||
# Output includes progress bar and final status
|
||||
@@ -673,9 +672,9 @@ result = tool._run(json.dumps({"project_id": "abc-123-def", "node_ids": ["node-1
|
||||
### Example 2: Stop Nodes
|
||||
|
||||
```python
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import GNS3StopNodeTool
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import node_stop
|
||||
|
||||
tool = GNS3StopNodeTool()
|
||||
tool = node_stop()
|
||||
result = tool._run(json.dumps({"project_id": "abc-123-def", "node_ids": ["node-1", "node-2"]}))
|
||||
|
||||
# Immediate return with stop status
|
||||
@@ -685,30 +684,30 @@ result = tool._run(json.dumps({"project_id": "abc-123-def", "node_ids": ["node-1
|
||||
|
||||
```python
|
||||
# Lab deployment
|
||||
start_tool = GNS3StartNodeTool()
|
||||
start_tool = node_start()
|
||||
start_result = start_tool._run(json.dumps({"project_id": project_id, "node_ids": all_node_ids}))
|
||||
|
||||
# ... Run tests ...
|
||||
|
||||
# Lab shutdown
|
||||
stop_tool = GNS3StopNodeTool()
|
||||
stop_tool = node_stop()
|
||||
stop_result = stop_tool._run(json.dumps({"project_id": project_id, "node_ids": all_node_ids}))
|
||||
```
|
||||
|
||||
### Example 4: Lab Pause and Resume
|
||||
|
||||
```python
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import GNS3SuspendNodeTool
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import node_suspend
|
||||
|
||||
# Start lab
|
||||
start_tool = GNS3StartNodeTool()
|
||||
start_tool = node_start()
|
||||
start_result = start_tool._run(json.dumps({"project_id": project_id, "node_ids": all_node_ids}))
|
||||
|
||||
# ... Configure devices ...
|
||||
# ... Run some tests ...
|
||||
|
||||
# Suspend lab (preserves all state)
|
||||
suspend_tool = GNS3SuspendNodeTool()
|
||||
suspend_tool = node_suspend()
|
||||
suspend_result = suspend_tool._run(json.dumps({"project_id": project_id, "node_ids": all_node_ids}))
|
||||
# Nodes suspended - state preserved in memory
|
||||
|
||||
@@ -722,14 +721,14 @@ start_result = start_tool._run(json.dumps({"project_id": project_id, "node_ids":
|
||||
### Example 5: Suspend While Renaming Nodes
|
||||
|
||||
```python
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import GNS3SuspendNodeTool, GNS3UpdateNodeNameTool
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import node_suspend, node_update
|
||||
|
||||
# Suspend nodes first (allows renaming)
|
||||
suspend_tool = GNS3SuspendNodeTool()
|
||||
suspend_tool = node_suspend()
|
||||
suspend_result = suspend_tool._run(json.dumps({"project_id": project_id, "node_ids": node_ids}))
|
||||
|
||||
# Now rename nodes (possible while suspended!)
|
||||
rename_tool = GNS3UpdateNodeNameTool()
|
||||
rename_tool = node_update()
|
||||
rename_result = rename_tool._run(
|
||||
json.dumps(
|
||||
{
|
||||
@@ -749,9 +748,9 @@ rename_result = rename_tool._run(
|
||||
### Example 6: Get Available Templates 🆕
|
||||
|
||||
```python
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import GNS3TemplateTool
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import template_list
|
||||
|
||||
tool = GNS3TemplateTool()
|
||||
tool = template_list()
|
||||
result = tool._run("")
|
||||
|
||||
# Returns all available device templates
|
||||
@@ -766,9 +765,9 @@ result = tool._run("")
|
||||
### Example 7: Create Topology Nodes 🆕
|
||||
|
||||
```python
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import GNS3CreateNodeTool
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import node_create
|
||||
|
||||
tool = GNS3CreateNodeTool()
|
||||
tool = node_create()
|
||||
result = tool._run(
|
||||
json.dumps(
|
||||
{
|
||||
@@ -818,9 +817,9 @@ result = tool._run(
|
||||
### Example 9: Apply Naming Convention 🆕
|
||||
|
||||
```python
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import GNS3UpdateNodeNameTool
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import node_update
|
||||
|
||||
tool = GNS3UpdateNodeNameTool()
|
||||
tool = node_update()
|
||||
result = tool._run(
|
||||
json.dumps(
|
||||
{
|
||||
@@ -842,20 +841,20 @@ result = tool._run(
|
||||
|
||||
```python
|
||||
from gns3server.agent.gns3_copilot.tools_v2 import (
|
||||
GNS3TemplateTool,
|
||||
GNS3CreateNodeTool,
|
||||
template_list,
|
||||
node_create,
|
||||
GNS3LinkTool,
|
||||
GNS3UpdateNodeNameTool,
|
||||
GNS3StartNodeTool,
|
||||
node_update,
|
||||
node_start,
|
||||
)
|
||||
|
||||
# Step 1: Get available templates
|
||||
template_tool = GNS3TemplateTool()
|
||||
template_tool = template_list()
|
||||
templates = template_tool._run("")
|
||||
# Find router and switch template_ids...
|
||||
|
||||
# Step 2: Create nodes
|
||||
create_tool = GNS3CreateNodeTool()
|
||||
create_tool = node_create()
|
||||
nodes = create_tool._run(
|
||||
json.dumps(
|
||||
{
|
||||
@@ -894,7 +893,7 @@ links = link_tool._run(
|
||||
)
|
||||
|
||||
# Step 4: Apply naming
|
||||
name_tool = GNS3UpdateNodeNameTool()
|
||||
name_tool = node_update()
|
||||
names = name_tool._run(
|
||||
json.dumps(
|
||||
{
|
||||
@@ -909,7 +908,7 @@ names = name_tool._run(
|
||||
)
|
||||
|
||||
# Step 5: Start nodes
|
||||
start_tool = GNS3StartNodeTool()
|
||||
start_tool = node_start()
|
||||
start_result = start_tool._run(
|
||||
json.dumps({"project_id": project_id, "node_ids": [n["node_id"] for n in nodes["created_nodes"]]})
|
||||
)
|
||||
@@ -1026,7 +1025,7 @@ _Status: ✅ Implemented - Topology management tools available in both modes. Fu
|
||||
|
||||
_Changelog:_
|
||||
- **2026-03-14 (Evening)**: Added dynamic wait time calculation
|
||||
- `GNS3StartNodeTool` now calculates optimal wait times based on device types
|
||||
- `node_start` now calculates optimal wait times based on device types
|
||||
- Fast devices (VPCS: 15s, IOU: 25s) start much faster than before
|
||||
- Conservative timing accounts for slower hardware environments
|
||||
- Slow devices (QEMU, Dynamips, etc.) use conservative 120s base time
|
||||
@@ -1035,6 +1034,6 @@ _Changelog:_
|
||||
- Logs selected strategy and detected device types
|
||||
|
||||
- **2026-03-14 (Morning)**: Added template filtering
|
||||
- `GNS3TemplateTool` now filters out built-in utility templates (cloud, nat, ethernet_hub, ethernet_switch, frame_relay_switch, atm_switch)
|
||||
- `template_list` now filters out built-in utility templates (cloud, nat, ethernet_hub, ethernet_switch, frame_relay_switch, atm_switch)
|
||||
- Focuses on network devices suitable for lab configuration
|
||||
- Logs filtered count for transparency
|
||||
Reference in new issue
Block a user