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.
5.0 KiB
This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
Fault Injection Feature
Overview
The fault injection feature enables GNS3 Copilot to automatically inject realistic network faults into GNS3 labs for troubleshooting training. The agent analyzes the topology, selects an appropriate fault based on the configured protocols, injects it, and documents the results.
Architecture
graph TD
subgraph "Agent Workflow"
TG[Topology Gathering]
CFG[Config Collection]
FA[Fault Analysis]
FI[Fault Injection]
FD[Fault Documentation]
end
subgraph "Skills Repository"
IS[INJECTION_SKILLS_REGISTRY<br/>39 categories, 368 issues]
SK[injection_skill_get Tool]
end
subgraph "Tools"
DC[device_show_run]
CC[device_config_send]
GK[gns3_topology_reader]
end
TG -->|Get topology| GK
CFG -->|Get configs| DC
FA -->|Query filtered skills| IS
FA -->|Select fault| SK
FI -->|Inject config changes| CC
FD -->|Output report| FD
Injection Skills Tool
The injection_skill_get (LangChain BaseTool) is the primary interface for querying available faults.
Listing Faults (with context filter)
The LLM MUST pass topology context when listing faults:
{"action": "list", "context": ["ospf", "bgp", "vlan"]}
This returns only faults matching the protocols found in the topology. The tool rejects calls without context:
{
"error": "context parameter is required when action='list'",
"hint": "Analyze the topology and device configurations first...",
"available_categories": ["bgp", "interface", "mpls", "ospf", ...]
}
Getting Fault Details
Token-efficient usage pattern:
// Step 1: List issue names only (~300 tokens)
{"device_type": "injection_ospf_issues", "detail": "index"}
// Step 2: Get single issue detail (~500 tokens)
{"device_type": "injection_ospf_issues", "issue": "ospf_hello_dead_mismatch"}
Parameters
| Parameter | Required | Description |
|---|---|---|
action |
No ("get") |
"list" to browse, "get" for details |
context |
Yes for action="list" |
Protocols found in topology: ["ospf", "bgp"] |
device_type |
Yes for action="get" |
e.g. "injection_ospf_issues" |
detail |
No ("full") |
"index" (names), "summary" (+desc), "full" (all) |
issue |
No | Single issue key for targeted detail |
Fault Injection Workflow
sequenceDiagram
participant LLM
participant injection_skill_get
participant TopologyTool
participant DeviceCommands
LLM->>TopologyTool: Get topology info
TopologyTool-->>LLM: Topology + device types
LLM->>DeviceCommands: Get device configs
DeviceCommands-->>LLM: Running configurations
Note over LLM: Analyze which protocols are in use
LLM->>injection_skill_get: {"action": "list", "context": ["ospf", "vlan"]}
injection_skill_get-->>LLM: Matching fault categories
LLM->>injection_skill_get: {"device_type": "injection_ospf_issues", "detail": "index"}
injection_skill_get-->>LLM: Issue names (token-efficient)
LLM->>injection_skill_get: {"device_type": "injection_ospf_issues", "issue": "ospf_hello_dead_mismatch"}
injection_skill_get-->>LLM: Full fault detail + config commands
LLM->>DeviceCommands: Inject fault configuration
DeviceCommands-->>LLM: Execution result
Note over LLM: Document fault in response
Injection Skills Repository
Skills are organized by protocol/category in the external GNS3-Skills repository:
| Category | File | Example Issues |
|---|---|---|
| OSPF | injection/ospf_issues.yaml |
Hello/Dead mismatch, MTU mismatch, area mismatch |
| BGP | injection/bgp_issues.yaml |
AS-path prepend, next-hop unreachable, route filtering |
| VLAN | injection/vlan_issues.yaml |
Trunk allowed mismatch, native VLAN mismatch |
| STP | injection/stp_issues.yaml |
Root guard, loop guard, port priority |
| MPLS | injection/mpls_issues.yaml |
LDP session down, label binding failure |
| ... | 34 more files | 368 issues total |
Recovery
Each injected fault includes restore commands in the documentation. The LLM always provides commands to fully revert all changes.
API Endpoint
POST /copilot/projects/{project_id}/chat/inject
Dedicated endpoint for fault injection. Internally sets copilot_mode to troubleshooting_injection and runs the agent.
Request:
{
"message": "Inject a network fault for troubleshooting practice",
"session_id": "optional-session-uuid"
}
Response: Server-Sent Events (SSE) stream identical to the chat stream endpoint.