mirror of
https://github.com/GNS3/gns3-server.git
synced 2026-11-19 20:55:14 +02:00
Replaces node_console (which handed a URL + ticket to the client for a bash websocat chain) with a tool that runs the whole session server-side: spawn `timeout N websocat -t --no-close <console-ws-url>`, feed the command lines through stdin (paced, CRLF), read stdout until the timeout kills websocat, return the collected output as plain text. - plain text replies: "output: ..." or bare error text — no JSON envelope, no status field (the server cannot judge command success) - raw output: UTF-8 decode with replacement only, no telnet/ANSI stripping; control keys are real characters (description teaches \u0003, no \x03 translation) - output funnel: grep=<python regex> filter; <=50 lines return as-is; beyond that a 10-line sample plus hints — regrep=true re-filters the node's cached capture (no re-run), full=true returns the last 400 lines / 64 KiB, and the full capture is written to the node's files (console-capture.txt) with a ticketed curl download URL - get_node_console_info_handler removed with its hashlib/TTL imports; the node-bound console ticket redemption path stays (comment updated, no current producer)
2479 lines
101 KiB
Python
2479 lines
101 KiB
Python
#
|
||
# Copyright (C) 2026 GNS3 Technologies Inc.
|
||
# Author: Yue Guobin
|
||
#
|
||
# This program is free software: you can redistribute it and/or modify
|
||
# it under the terms of the GNU General Public License as published by
|
||
# the Free Software Foundation, either version 3 of the License, or
|
||
# (at your option) any later version.
|
||
#
|
||
# This program is distributed in the hope that it will be useful,
|
||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
# GNU General Public License for more details.
|
||
#
|
||
# You should have received a copy of the GNU General Public License
|
||
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||
|
||
"""
|
||
MCP (Model Context Protocol) service for GNS3 server.
|
||
|
||
Implements the standard MCP protocol over the Streamable HTTP transport
|
||
using the official MCP SDK (mcp.server.mcpserver.MCPServer):
|
||
|
||
/v3/mcp/transport — POST (JSON-RPC), GET (optional server stream),
|
||
DELETE (session termination)
|
||
|
||
Tools are registered via @mcp.tool() decorators.
|
||
"""
|
||
|
||
import asyncio
|
||
import contextlib
|
||
import contextvars
|
||
import json
|
||
import logging
|
||
import socket
|
||
import time
|
||
from typing import Annotated, Any
|
||
from urllib.parse import parse_qs
|
||
from uuid import UUID
|
||
|
||
import bcrypt
|
||
from fastapi import APIRouter
|
||
from fastapi.responses import Response
|
||
from mcp.server.mcpserver import MCPServer
|
||
from mcp.server.transport_security import TransportSecuritySettings
|
||
from pydantic import Field
|
||
from sqlalchemy.ext.asyncio import AsyncSession
|
||
|
||
from gns3server.agent.gns3_copilot.gns3_client.api_handlers import (
|
||
available_filters_handler,
|
||
create_ellipse_drawing_handler,
|
||
create_link_handler,
|
||
create_node_handler,
|
||
create_rectangle_drawing_handler,
|
||
create_text_drawing_handler,
|
||
delete_link_handler,
|
||
delete_node_file_handler,
|
||
delete_node_handler,
|
||
download_capture_file_handler,
|
||
duplicate_node_handler,
|
||
get_link_handler,
|
||
get_links_handler,
|
||
get_node_file_handler,
|
||
get_node_handler,
|
||
get_node_links_handler,
|
||
get_nodes_handler,
|
||
isolate_node_handler,
|
||
link_marker_handler,
|
||
list_node_files_handler,
|
||
marker_definition_handler,
|
||
reset_link_handler,
|
||
start_all_nodes_handler,
|
||
start_capture_handler,
|
||
start_node_handler,
|
||
stop_all_nodes_handler,
|
||
stop_capture_handler,
|
||
stop_node_handler,
|
||
suspend_all_nodes_handler,
|
||
suspend_node_handler,
|
||
unisolate_node_handler,
|
||
update_link_handler,
|
||
update_node_handler,
|
||
write_node_file_handler,
|
||
)
|
||
from gns3server.config import Config
|
||
from gns3server.db import models as models
|
||
from gns3server.db.repositories.api_keys import ApiKeysRepository
|
||
from gns3server.db.repositories.users import UsersRepository
|
||
from gns3server.services import auth_service
|
||
from gns3server.services.authentication import AuthService as AuthService
|
||
from gns3server.utils.request_utils import extract_client_info
|
||
|
||
# Symbol tools are disabled for now: they require a vision-capable model to
|
||
# be genuinely useful (the tools shuttle SVG content, which a text-only LLM
|
||
# cannot inspect or produce). Revisit later.
|
||
# from .symbols import (
|
||
# get_symbols_handler, get_symbol_handler,
|
||
# get_symbol_dimensions_handler, get_default_symbols_handler,
|
||
# upload_symbol_handler, delete_symbol_handler,
|
||
# )
|
||
from .appliances import (
|
||
get_appliance_handler,
|
||
get_appliances_handler,
|
||
install_appliance_handler,
|
||
)
|
||
from .computes import (
|
||
get_compute_handler,
|
||
get_compute_images_handler,
|
||
list_computes_handler,
|
||
)
|
||
from .console_exec import DEFAULT_TIMEOUT_S, DIRECT_LINES, FULL_LINES, MAX_TIMEOUT_S, console_exec
|
||
from .device_config import (
|
||
device_config_send_handler,
|
||
device_show_run_handler,
|
||
vpcs_config_set_handler,
|
||
)
|
||
from .drawings import (
|
||
delete_drawing_handler,
|
||
get_drawing_handler,
|
||
get_drawings_handler,
|
||
update_drawing_handler,
|
||
)
|
||
from .images import (
|
||
delete_image_handler,
|
||
get_image_handler,
|
||
get_images_handler,
|
||
install_images_handler,
|
||
prune_images_handler,
|
||
)
|
||
from .locators import add_did_you_mean, resolve_locators
|
||
from .projects import (
|
||
close_project_handler,
|
||
create_project_handler,
|
||
delete_project_handler,
|
||
duplicate_project_handler,
|
||
get_locked_project_handler,
|
||
get_project_handler,
|
||
get_project_readme_handler,
|
||
get_project_stats_handler,
|
||
list_projects_handler,
|
||
lock_project_handler,
|
||
open_project_handler,
|
||
unlock_project_handler,
|
||
update_project_handler,
|
||
update_project_readme_handler,
|
||
)
|
||
from .server import (
|
||
get_statistics_handler,
|
||
get_version_handler,
|
||
)
|
||
from .skills import device_skills_handler, injection_skills_handler
|
||
from .snapshots import (
|
||
create_snapshot_handler,
|
||
delete_snapshot_handler,
|
||
get_snapshots_handler,
|
||
restore_snapshot_handler,
|
||
)
|
||
from .templates import (
|
||
create_template_handler,
|
||
delete_template_handler,
|
||
get_template_handler,
|
||
list_templates_handler,
|
||
update_template_handler,
|
||
)
|
||
|
||
log = logging.getLogger(__name__)
|
||
|
||
# Suppress noisy telnet connection logs from device config tools.
|
||
logging.getLogger("telnetlib3").setLevel(logging.WARNING)
|
||
|
||
# FastAPI app reference — used to lazily access app.state._db_engine for API key validation.
|
||
# The db engine is initialized during the lifespan startup, which runs AFTER
|
||
# register_starlette_routes() is called, so we cannot capture it at registration time.
|
||
_app = None
|
||
|
||
|
||
# ── Server ready state ────────────────────────────────────────────────
|
||
# Tracks whether GNS3 server has completed initialization.
|
||
# MCP connections wait up to 5 seconds for startup to complete, then return
|
||
# 503 Service Unavailable if initialization is not complete to prevent
|
||
# "Received request before initialization was complete" errors.
|
||
|
||
_mcp_ready_event = asyncio.Event()
|
||
|
||
|
||
def set_mcp_server_ready(ready: bool = True) -> None:
|
||
"""
|
||
Set MCP server ready state.
|
||
|
||
Should be called after GNS3 startup completes (database, controller, etc.)
|
||
to allow MCP connections to proceed.
|
||
|
||
Args:
|
||
ready: True to mark server as ready, False to mark as not ready
|
||
"""
|
||
if ready:
|
||
_mcp_ready_event.set()
|
||
log.info("MCP server is now ready to accept connections")
|
||
else:
|
||
_mcp_ready_event.clear()
|
||
|
||
|
||
async def wait_for_mcp_ready() -> bool:
|
||
"""
|
||
Wait until MCP server is ready before accepting connections.
|
||
|
||
Returns:
|
||
True if server is ready, False if timeout reached
|
||
|
||
Returns immediately if already ready. Otherwise waits with a timeout
|
||
and returns False if server does not become ready in time.
|
||
"""
|
||
if _mcp_ready_event.is_set():
|
||
return True
|
||
|
||
log.debug("MCP server not ready yet, waiting for initialization to complete...")
|
||
|
||
try:
|
||
await asyncio.wait_for(_mcp_ready_event.wait(), timeout=5.0)
|
||
log.debug("MCP server is now ready, proceeding with connection")
|
||
return True
|
||
except TimeoutError:
|
||
log.warning("MCP server ready check timed out after 5 seconds - GNS3 server initialization may have issues")
|
||
return False
|
||
|
||
|
||
# ── Per‑connection JWT token ─────────────────────────────────────────
|
||
# Set during request authentication, read by tool handlers running in the
|
||
# session task that inherited it (contextvars propagate through
|
||
# asyncio.to_thread). In stateful Streamable HTTP the session task is
|
||
# created by the opening (initialize) request, so handlers see the token
|
||
# presented when the session was established.
|
||
|
||
_jwt_token_var: contextvars.ContextVar[str | None] = contextvars.ContextVar("mcp_jwt_token", default=None)
|
||
# Username extracted during token validation — used by handlers to generate
|
||
# short-lived JWTs for download/console URLs without exposing the raw key.
|
||
_jwt_username_var: contextvars.ContextVar[str | None] = contextvars.ContextVar("mcp_jwt_username", default=None)
|
||
# token_version extracted during token validation — short-lived JWTs minted for
|
||
# download/console URLs must carry the same version, or the revocation check
|
||
# (token_data.token_version != user.token_version) rejects them as "revoked".
|
||
_jwt_token_version_var: contextvars.ContextVar[int] = contextvars.ContextVar("mcp_jwt_token_version", default=0)
|
||
# The raw API key the session authenticated with (None for JWT logins). The
|
||
# session task cannot see contextvars set by later requests, so the JWT it
|
||
# inherited at initialize ages past its 24h lifetime while the transport
|
||
# keeps authenticating fine — _gns3_ctx() uses this key to renew that JWT.
|
||
_jwt_api_key_var: contextvars.ContextVar[str | None] = contextvars.ContextVar("mcp_jwt_api_key", default=None)
|
||
|
||
|
||
# ── Token validation ──────────────────────────────────────────────────
|
||
|
||
# Short-lived cache of API-key resolutions. Streamable HTTP authenticates
|
||
# every request (not once per connection like SSE), and each API-key check
|
||
# costs a bcrypt round (~hundreds of ms of CPU). Cache the minted JWT (and
|
||
# the username/token_version contextvars) for a few minutes per key.
|
||
# Revocation lag is bounded by the TTL — the minted 24h JWT outlives the
|
||
# cache anyway, so this matches the previous per-connection behavior.
|
||
_API_KEY_CACHE_TTL = 300.0 # seconds
|
||
_API_KEY_CACHE_MAX = 128
|
||
_api_key_cache: dict[str, tuple[float, str, str, int]] = {} # token -> (expires_at, jwt, username, token_version)
|
||
|
||
|
||
def _cache_api_key(token: str, jwt: str, username: str, token_version: int) -> None:
|
||
"""Store an API-key resolution, pruning the cache when it exceeds the size cap."""
|
||
now = time.monotonic()
|
||
if len(_api_key_cache) >= _API_KEY_CACHE_MAX:
|
||
for stale in [k for k, v in _api_key_cache.items() if v[0] <= now]:
|
||
del _api_key_cache[stale]
|
||
if len(_api_key_cache) >= _API_KEY_CACHE_MAX:
|
||
_api_key_cache.pop(next(iter(_api_key_cache)))
|
||
_api_key_cache[token] = (now + _API_KEY_CACHE_TTL, jwt, username, token_version)
|
||
|
||
|
||
async def _resolve_token(token: str) -> str | None:
|
||
"""Validate a token (JWT or API key) and return the effective JWT to use.
|
||
|
||
For JWT tokens, returns the token as-is.
|
||
For API keys, validates against the database and returns a fresh short-lived JWT.
|
||
|
||
Returns None if the token is invalid.
|
||
"""
|
||
# API keys (gns3_...) are never valid JWTs — skip the JWT attempt for them
|
||
# so it doesn't log a spurious "JWT rejected" line on every API-key request.
|
||
if not token.startswith("gns3_"):
|
||
try:
|
||
token_data = auth_service.get_token_data(token)
|
||
_jwt_username_var.set(token_data.username)
|
||
_jwt_token_version_var.set(token_data.token_version)
|
||
return token
|
||
except Exception:
|
||
pass
|
||
|
||
cached = _api_key_cache.get(token)
|
||
if cached is not None:
|
||
expires_at, jwt, username, token_version = cached
|
||
if expires_at > time.monotonic():
|
||
_jwt_username_var.set(username)
|
||
_jwt_token_version_var.set(token_version)
|
||
return jwt
|
||
del _api_key_cache[token]
|
||
|
||
# Try API key — format: gns3_<api_key_id>_<random_secret> → O(1) lookup
|
||
if token.startswith("gns3_") and _app is not None:
|
||
db_engine = getattr(_app.state, "_db_engine", None)
|
||
if db_engine is not None:
|
||
try:
|
||
parts = token.split("_", 2)
|
||
if len(parts) == 3:
|
||
key_id = UUID(parts[1])
|
||
secret = parts[2]
|
||
async with AsyncSession(db_engine, expire_on_commit=False) as db_session:
|
||
repo = ApiKeysRepository(db_session)
|
||
db_key = await repo.get_api_key(key_id)
|
||
if db_key and not db_key.revoked:
|
||
if await asyncio.to_thread(bcrypt.checkpw, secret.encode(), db_key.key_hash.encode()):
|
||
await repo.update_last_used(db_key.api_key_id)
|
||
user_repo = UsersRepository(db_session)
|
||
user = await user_repo.get_user(db_key.user_id)
|
||
if user:
|
||
_jwt_username_var.set(user.username)
|
||
_jwt_token_version_var.set(user.token_version)
|
||
fresh_token = auth_service.create_access_token(
|
||
user.username, token_version=user.token_version
|
||
)
|
||
_cache_api_key(token, fresh_token, user.username, user.token_version)
|
||
return fresh_token
|
||
except Exception:
|
||
pass
|
||
|
||
return None
|
||
|
||
|
||
# ── Server URL helper ─────────────────────────────────────────────────
|
||
|
||
|
||
def _server_url() -> str:
|
||
cfg = Config.instance().settings
|
||
host = cfg.Server.host
|
||
if host in ("0.0.0.0", "::"):
|
||
try:
|
||
with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
|
||
s.settimeout(0.1)
|
||
s.connect(("8.8.8.8", 80))
|
||
host = s.getsockname()[0]
|
||
except OSError:
|
||
host = "127.0.0.1"
|
||
scheme = "https" if cfg.Server.enable_ssl else "http"
|
||
return f"{scheme}://{host}:{cfg.Server.port}"
|
||
|
||
|
||
# ── MCP Server ────────────────────────────────────────────────────────
|
||
|
||
|
||
def _create_mcp_server() -> MCPServer:
|
||
"""Create the MCP server (transport security is applied when the HTTP app is built)."""
|
||
return MCPServer("GNS3 MCP Server")
|
||
|
||
|
||
def _transport_security() -> TransportSecuritySettings:
|
||
"""Build transport security settings from configuration."""
|
||
cfg = Config.instance().settings.Server
|
||
|
||
# Always pass an explicit TransportSecuritySettings to prevent the SDK
|
||
# from auto-enabling protection when host is localhost (its default).
|
||
if cfg.mcp_enable_dns_rebinding_protection:
|
||
return TransportSecuritySettings(
|
||
enable_dns_rebinding_protection=True,
|
||
allowed_hosts=cfg.mcp_allowed_hosts or ["127.0.0.1:*", "localhost:*"],
|
||
allowed_origins=cfg.mcp_allowed_origins or ["http://127.0.0.1:*", "http://localhost:*"],
|
||
)
|
||
return TransportSecuritySettings(enable_dns_rebinding_protection=False)
|
||
|
||
|
||
mcp = _create_mcp_server()
|
||
|
||
|
||
# ── Tool handlers ─────────────────────────────────────────────────────
|
||
|
||
|
||
def _renew_expired_jwt(token: str | None, api_key: str | None, username: str | None, token_version: int) -> str | None:
|
||
"""Renew the session task's JWT once it has aged past its lifetime.
|
||
|
||
Tool handlers run in the session task created at initialize and inherit
|
||
its context; contextvars set by later requests never reach them. For
|
||
API-key sessions (the documented long-lived setup — keys never expire)
|
||
that means the minted 24h JWT eventually expires under a healthy
|
||
transport: every request still re-validates the key, but tool calls
|
||
would send the stale JWT and fail with 401.
|
||
|
||
The renewal is cheap by construction: every tools/call POST passes the
|
||
auth wrapper first, which re-validates the API key and refreshes the
|
||
module-level _api_key_cache with a freshly minted JWT — so by the time a
|
||
tool handler runs, a current JWT for this key is already cached. Only
|
||
when that cache entry has gone stale (idle gap) do we re-mint here
|
||
synchronously; no DB round-trip, the username/token_version validated at
|
||
initialize are re-used.
|
||
|
||
Returns the effective JWT, or None when renewal is not possible (JWT
|
||
login: the client's own credential expiring is the client's business).
|
||
"""
|
||
if not token or not api_key:
|
||
return token
|
||
try:
|
||
auth_service.get_token_data(token)
|
||
return token # still valid
|
||
except Exception:
|
||
pass
|
||
cached = _api_key_cache.get(api_key)
|
||
if cached is not None and cached[0] > time.monotonic():
|
||
return cached[1]
|
||
fresh = auth_service.create_access_token(username or "", token_version=token_version)
|
||
_cache_api_key(api_key, fresh, username or "", token_version)
|
||
log.info("Renewed the MCP session's expired JWT from its API key (user %s)", username)
|
||
return fresh
|
||
|
||
|
||
def _gns3_ctx() -> dict[str, Any]:
|
||
"""Build the Gns3Connector context from the request's contextvars."""
|
||
return {
|
||
"server_url": _server_url(),
|
||
"jwt_token": _renew_expired_jwt(
|
||
_jwt_token_var.get(), _jwt_api_key_var.get(), _jwt_username_var.get(), _jwt_token_version_var.get()
|
||
),
|
||
"jwt_username": _jwt_username_var.get(),
|
||
"jwt_token_version": _jwt_token_version_var.get(),
|
||
}
|
||
|
||
|
||
def _run_handler_sync(handler, params: dict[str, Any]) -> list[dict[str, Any]]:
|
||
"""Run a synchronous Gns3Connector handler in a thread."""
|
||
ctx = _gns3_ctx()
|
||
|
||
def run(h, p):
|
||
return h(p, ctx)
|
||
|
||
# Name-shaped project_id/node_id values become UUIDs before the handler
|
||
# runs; a name that matches nothing fails fast with the known names.
|
||
resolved_params, resolution_error = resolve_locators(params, run)
|
||
if resolved_params is None:
|
||
result = resolution_error
|
||
else:
|
||
result = handler(resolved_params, ctx)
|
||
# backstop for UUID transcription slips: "Did you mean ...?"
|
||
result = add_did_you_mean(result, resolved_params, run)
|
||
return [{"type": "text", "text": json.dumps(result, ensure_ascii=False, default=str)}]
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_list() -> list[dict[str, Any]]:
|
||
"""List all GNS3 projects accessible to the current user."""
|
||
return await asyncio.to_thread(_run_handler_sync, list_projects_handler, {})
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_get(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Get detailed information about a specific project."""
|
||
return await asyncio.to_thread(_run_handler_sync, get_project_handler, {"project_id": project_id})
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_create(
|
||
name: Annotated[str, Field(description="Project name")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Create a new GNS3 project. auto_close is set to False so the project stays open when clients disconnect."""
|
||
params = {"name": name, "auto_close": False}
|
||
return await asyncio.to_thread(_run_handler_sync, create_project_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_delete(
|
||
project_id: Annotated[str, Field(description="Project name or UUID to delete")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Delete a GNS3 project permanently."""
|
||
return await asyncio.to_thread(_run_handler_sync, delete_project_handler, {"project_id": project_id})
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_open(
|
||
project_id: Annotated[str, Field(description="Project name or UUID to open")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Open a closed GNS3 project."""
|
||
return await asyncio.to_thread(_run_handler_sync, open_project_handler, {"project_id": project_id})
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_close(
|
||
project_id: Annotated[str, Field(description="Project name or UUID to close")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Close an open GNS3 project."""
|
||
return await asyncio.to_thread(_run_handler_sync, close_project_handler, {"project_id": project_id})
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_stats(
|
||
project_id: Annotated[str, Field(description="Project name or UUID to get statistics for")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Get statistics (nodes, links, snapshots, drawings) for a project."""
|
||
return await asyncio.to_thread(_run_handler_sync, get_project_stats_handler, {"project_id": project_id})
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_update(
|
||
project_id: Annotated[str, Field(description="Project name or UUID to update")],
|
||
name: Annotated[str | None, Field(description="New project name")] = None,
|
||
auto_close: Annotated[bool | None, Field(description="Close project when last client leaves")] = None,
|
||
auto_open: Annotated[bool | None, Field(description="Project opens when GNS3 starts")] = None,
|
||
auto_start: Annotated[bool | None, Field(description="Project starts when opened")] = None,
|
||
scene_width: Annotated[int | None, Field(description="Width of the drawing area")] = None,
|
||
scene_height: Annotated[int | None, Field(description="Height of the drawing area")] = None,
|
||
zoom: Annotated[int | None, Field(description="Zoom of the drawing area")] = None,
|
||
show_layers: Annotated[bool | None, Field(description="Show layers on the drawing area")] = None,
|
||
snap_to_grid: Annotated[bool | None, Field(description="Snap to grid on the drawing area")] = None,
|
||
show_grid: Annotated[bool | None, Field(description="Show the grid on the drawing area")] = None,
|
||
grid_size: Annotated[int | None, Field(description="Grid size for the drawing area for nodes")] = None,
|
||
drawing_grid_size: Annotated[int | None, Field(description="Grid size for the drawing area for drawings")] = None,
|
||
show_interface_labels: Annotated[
|
||
bool | None, Field(description="Show interface labels on the drawing area")
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Update a project's properties (name, auto_close, auto_open, etc.)."""
|
||
params: dict[str, Any] = {"project_id": project_id}
|
||
local_vars = {
|
||
"name": name,
|
||
"auto_close": auto_close,
|
||
"auto_open": auto_open,
|
||
"auto_start": auto_start,
|
||
"scene_width": scene_width,
|
||
"scene_height": scene_height,
|
||
"zoom": zoom,
|
||
"show_layers": show_layers,
|
||
"snap_to_grid": snap_to_grid,
|
||
"show_grid": show_grid,
|
||
"grid_size": grid_size,
|
||
"drawing_grid_size": drawing_grid_size,
|
||
"show_interface_labels": show_interface_labels,
|
||
}
|
||
for key, val in local_vars.items():
|
||
if val is not None:
|
||
params[key] = val
|
||
return await asyncio.to_thread(_run_handler_sync, update_project_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_duplicate(
|
||
project_id: Annotated[str, Field(description="Project name or UUID to duplicate")],
|
||
name: Annotated[str, Field(description="New project name")],
|
||
reset_mac_addresses: Annotated[bool, Field(description="Reset MAC addresses for this project")] = False,
|
||
) -> list[dict[str, Any]]:
|
||
"""Duplicate a project."""
|
||
params: dict[str, Any] = {"project_id": project_id, "name": name}
|
||
if reset_mac_addresses:
|
||
params["reset_mac_addresses"] = reset_mac_addresses
|
||
return await asyncio.to_thread(_run_handler_sync, duplicate_project_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_readme_get(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Get the content of a project's README.md file — the project documentation (Markdown format)."""
|
||
return await asyncio.to_thread(_run_handler_sync, get_project_readme_handler, {"project_id": project_id})
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_readme_update(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
content: Annotated[str, Field(description="Content to write to README.md (Markdown format)")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Update or create a project's README.md file — the project documentation (Markdown format)."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync, update_project_readme_handler, {"project_id": project_id, "content": content}
|
||
)
|
||
|
||
|
||
# ── Node tools ────────────────────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_list(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
fields: Annotated[
|
||
list[str] | None,
|
||
Field(
|
||
description='Optional: return only these fields per node. e.g. ["name","status"]. Available: name, status, node_type, console, console_type, console_host, node_id, project_id, compute_id, symbol, x, y, z, locked, ports, properties, command_line, node_directory, label, tags, template_id, width, height, aux, aux_type'
|
||
),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""List all nodes in a project. Use fields=[] to return only what you need."""
|
||
return await asyncio.to_thread(_run_handler_sync, get_nodes_handler, {"project_id": project_id, "fields": fields})
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_get(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str, Field(description="Node name or UUID")],
|
||
fields: Annotated[
|
||
list[str] | None,
|
||
Field(
|
||
description='Optional: return only these fields. e.g. ["name","status"]. Available: name, status, node_type, console, console_type, console_host, node_id, project_id, compute_id, symbol, x, y, z, locked, ports, properties, command_line, node_directory, label, tags, template_id, width, height, aux, aux_type'
|
||
),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Get detailed information about a specific node. Use fields=[] to return only what you need."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
get_node_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"node_id": node_id,
|
||
"fields": fields,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_start(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str | None, Field(description="Node name or UUID (single mode)")] = None,
|
||
node_ids: Annotated[
|
||
list[str] | None, Field(description='Batch mode: ["uuid1","uuid2"] — start multiple nodes in parallel')
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Start one or more nodes. Provide node_id for single, or node_ids for batch."""
|
||
params: dict[str, Any] = {"project_id": project_id}
|
||
if node_ids:
|
||
params["node_ids"] = node_ids
|
||
else:
|
||
params["node_id"] = node_id
|
||
return await asyncio.to_thread(_run_handler_sync, start_node_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_stop(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str | None, Field(description="Node name or UUID (single mode)")] = None,
|
||
node_ids: Annotated[
|
||
list[str] | None, Field(description='Batch mode: ["uuid1","uuid2"] — stop multiple nodes in parallel')
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Stop one or more nodes. Provide node_id for single, or node_ids for batch."""
|
||
params: dict[str, Any] = {"project_id": project_id}
|
||
if node_ids:
|
||
params["node_ids"] = node_ids
|
||
else:
|
||
params["node_id"] = node_id
|
||
return await asyncio.to_thread(_run_handler_sync, stop_node_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_suspend(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str | None, Field(description="Node name or UUID (single mode)")] = None,
|
||
node_ids: Annotated[
|
||
list[str] | None, Field(description='Batch mode: ["uuid1","uuid2"] — suspend multiple nodes in parallel')
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Suspend one or more nodes. Provide node_id for single, or node_ids for batch."""
|
||
params: dict[str, Any] = {"project_id": project_id}
|
||
if node_ids:
|
||
params["node_ids"] = node_ids
|
||
else:
|
||
params["node_id"] = node_id
|
||
return await asyncio.to_thread(_run_handler_sync, suspend_node_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_create(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
template_id: Annotated[
|
||
str | None, Field(description="Template UUID (required for single mode; used as default in batch mode)")
|
||
] = None,
|
||
x: Annotated[int, Field(description="X coordinate (canvas center origin, right positive)")] = 0,
|
||
y: Annotated[int, Field(description="Y coordinate (canvas center origin, down positive)")] = 0,
|
||
compute_id: Annotated[str, Field(description="Compute ID (default: local)")] = "local",
|
||
nodes: Annotated[
|
||
list | None,
|
||
Field(
|
||
description="Batch mode: [{name, template_id?, x?, y?, compute_id?}] — top-level template_id applies as default"
|
||
),
|
||
] = None,
|
||
fields: Annotated[
|
||
list[str] | None,
|
||
Field(
|
||
description="Response fields to include (default: [node_id, name, node_type, status, console]). "
|
||
"Available: compute_id, name, node_type, node_id, console, console_type, "
|
||
"console_auto_start, aux, aux_type, properties, label, symbol, x, y, z, "
|
||
"locked, port_name_format, port_segment_size, first_port_name, "
|
||
"custom_adapters, tags, template_id, project_id, node_directory, "
|
||
"status, command_line, width, height, ports, console_host"
|
||
),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Create one or more nodes from templates.
|
||
|
||
Single mode: provide template_id, x, y (optional compute_id)
|
||
Batch mode: provide nodes=[{name, template_id?, x?, y?, compute_id?}] — creates up to 100 in parallel.
|
||
Top-level template_id applies to all nodes; individual nodes can override.
|
||
Results are always returned in submission order; correlate nodes by node_id, not name.
|
||
When a node omits `name`, the server assigns a default name (R-1, R-2, ...) and console
|
||
port — such batches are created sequentially so those assignments follow submission order.
|
||
"""
|
||
if nodes is not None:
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
create_node_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"nodes": nodes,
|
||
"fields": fields,
|
||
"template_id": template_id,
|
||
},
|
||
)
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
create_node_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"template_id": template_id,
|
||
"x": x,
|
||
"y": y,
|
||
"compute_id": compute_id,
|
||
"fields": fields,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_delete(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str | None, Field(description="Node name or UUID (single mode)")] = None,
|
||
node_ids: Annotated[
|
||
list[str] | None, Field(description='Batch mode: ["uuid1","uuid2"] — delete multiple nodes in parallel')
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Delete one or more nodes from a project. Provide node_id for single, or node_ids for batch."""
|
||
params: dict[str, Any] = {"project_id": project_id}
|
||
if node_ids:
|
||
params["node_ids"] = node_ids
|
||
else:
|
||
params["node_id"] = node_id
|
||
return await asyncio.to_thread(_run_handler_sync, delete_node_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_update(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str, Field(description="Node name or UUID to update")],
|
||
**kwargs: Any,
|
||
) -> list[dict[str, Any]]:
|
||
"""Update a node's properties (name, position, etc.)."""
|
||
params = {"project_id": project_id, "node_id": node_id, **kwargs}
|
||
return await asyncio.to_thread(_run_handler_sync, update_node_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_console_exec(
|
||
project_id: Annotated[str, Field(description="Project name or UUID containing the node")],
|
||
node_id: Annotated[str, Field(description="Node name or UUID to run commands on")],
|
||
command: Annotated[
|
||
str,
|
||
Field(
|
||
description="Commands, one per line (\\n-separated). Empty = a single Enter (wake the console / read the prompt)."
|
||
),
|
||
] = "",
|
||
timeout: Annotated[ # noqa: ASYNC109 - timeout is the session length, not an async deadline
|
||
float,
|
||
Field(
|
||
description=f"Session length in seconds, 1-{int(MAX_TIMEOUT_S)} (default {int(DEFAULT_TIMEOUT_S)}). "
|
||
"The session stays open the FULL window — set it just above the expected output time."
|
||
),
|
||
] = DEFAULT_TIMEOUT_S,
|
||
grep: Annotated[
|
||
str | None,
|
||
Field(
|
||
description="Optional Python regex (superset of grep -E). Only matching lines of the output are returned, "
|
||
"e.g. 'ospf|bgp', '^R1#'."
|
||
),
|
||
] = None,
|
||
regrep: Annotated[
|
||
bool,
|
||
Field(
|
||
description="Re-use this node's last captured output instead of running a new session "
|
||
"(no re-run, no side effects). Combine with grep= or full=true."
|
||
),
|
||
] = False,
|
||
full: Annotated[
|
||
bool,
|
||
Field(
|
||
description=f"Return the last {FULL_LINES} lines / 64 KiB of output instead of the {DIRECT_LINES}-line summary."
|
||
),
|
||
] = False,
|
||
) -> str:
|
||
"""Run commands on a node's text console and return the output (one call = one complete session).
|
||
|
||
The server connects to the node's console WebSocket, sends your command
|
||
lines, keeps collecting output until the timeout expires, disconnects,
|
||
and returns everything that came back as plain text. Works for telnet and
|
||
ssh console types on all computes (the controller proxies the WebSocket).
|
||
Node-side state persists between calls (config mode, running pings,
|
||
pager position) — a new session lands where the previous one ended.
|
||
|
||
Console input:
|
||
- command: one command per line (\\n-separated). Each line is sent with a
|
||
console line ending, lines are paced ~0.3 s apart so none is dropped.
|
||
- A line containing only a control character is a keypress, not a
|
||
command: interrupt a running command with a real Ctrl-C character — in
|
||
JSON tool arguments that is "\\u0003" as its own line. The 4-character
|
||
spelling "\\x03" is NOT translated and would arrive as text.
|
||
- command="" sends a single Enter — wakes an idle console and shows the
|
||
prompt.
|
||
|
||
Timeout: the session stays open for the FULL window (like
|
||
`timeout N websocat`). Output keeps arriving the whole time; there is no
|
||
early return. ~15 s fits a few show commands; big config blocks or
|
||
`show tech-support` need 30 s or more.
|
||
|
||
Output is raw console bytes decoded as UTF-8 with replacement — telnet
|
||
negotiation and ANSI escape sequences may show up as stray bytes; that
|
||
is expected. When more than 50 lines would come back, only a 10-line
|
||
sample returns, with instructions to narrow (grep=), re-filter the cached
|
||
capture without re-running (regrep=true), dump its tail (full=true), or
|
||
download the whole capture with curl.
|
||
|
||
Failures (node not started, VNC console, websocat missing on the server
|
||
host, silent console) return plain text describing the problem — there
|
||
is no status field, read the text itself.
|
||
|
||
Example — two checks on one router, 20 s window:
|
||
node_console_exec(project_id="ospf-lab", node_id="R1",
|
||
command="show ip ospf neighbor\\nshow ip route summary", timeout=20)
|
||
"""
|
||
return await console_exec(
|
||
project_id,
|
||
node_id,
|
||
command,
|
||
timeout,
|
||
grep=grep,
|
||
regrep=regrep,
|
||
full=full,
|
||
gns3_ctx=_gns3_ctx(),
|
||
)
|
||
|
||
|
||
# ── Link tools ────────────────────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def link_list(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
fields: Annotated[
|
||
list[str] | None,
|
||
Field(
|
||
description='Optional: return only these fields. e.g. ["link_id","nodes"]. Available: link_id, project_id, link_type, kernel_datapath, nodes, suspend, filters, capturing, capture_file_name, link_style'
|
||
),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""List all links in a project. Use fields=[] to return only what you need."""
|
||
return await asyncio.to_thread(_run_handler_sync, get_links_handler, {"project_id": project_id, "fields": fields})
|
||
|
||
|
||
@mcp.tool()
|
||
async def link_get(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
link_id: Annotated[str, Field(description="UUID of the link")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Get detailed information about a specific link."""
|
||
return await asyncio.to_thread(_run_handler_sync, get_link_handler, {"project_id": project_id, "link_id": link_id})
|
||
|
||
|
||
@mcp.tool()
|
||
async def link_create(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
nodes: Annotated[
|
||
list | None,
|
||
Field(description="Single mode: [{node_id, adapter_number, port_number}] or compact [id, ad, pt, id, ad, pt]"),
|
||
] = None,
|
||
link_type: Annotated[str, Field(description="Link type - ethernet or serial")] = "ethernet",
|
||
filters: Annotated[dict | None, Field(description="Optional packet filters")] = None,
|
||
links: Annotated[
|
||
list | None,
|
||
Field(
|
||
description="Batch mode: [{nodes, link_type?, filters?}] — nodes supports compact [id, ad, pt, id, ad, pt] format"
|
||
),
|
||
] = None,
|
||
fields: Annotated[
|
||
list[str] | None,
|
||
Field(
|
||
description="Response fields to include (default: [link_id, link_type, nodes]). "
|
||
"Available: link_id, project_id, link_type, kernel_datapath, nodes, suspend, "
|
||
"link_style, filters, show_filters_icon, capturing, "
|
||
"capture_file_name, capture_file_path, capture_compute_id, wireshark"
|
||
),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Create one or more links between nodes.
|
||
|
||
Single mode: provide nodes, link_type (optional filters)
|
||
Batch mode: provide links=[{nodes, link_type?, filters?}] — up to 100 in parallel
|
||
"""
|
||
if links:
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
create_link_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"links": links,
|
||
"fields": fields,
|
||
},
|
||
)
|
||
params: dict[str, Any] = {"project_id": project_id, "nodes": nodes, "link_type": link_type, "fields": fields}
|
||
if filters:
|
||
params["filters"] = filters
|
||
return await asyncio.to_thread(_run_handler_sync, create_link_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def link_delete(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
link_id: Annotated[str | None, Field(description="Link UUID (single mode)")] = None,
|
||
link_ids: Annotated[
|
||
list[str] | None, Field(description='Batch mode: ["uuid1","uuid2"] — delete multiple links in parallel')
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Delete one or more links from a project."""
|
||
params: dict[str, Any] = {"project_id": project_id}
|
||
if link_ids:
|
||
params["link_ids"] = link_ids
|
||
else:
|
||
params["link_id"] = link_id
|
||
return await asyncio.to_thread(_run_handler_sync, delete_link_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def link_update(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
link_id: Annotated[str, Field(description="UUID of the link to update")],
|
||
**kwargs: Any,
|
||
) -> list[dict[str, Any]]:
|
||
"""Update a link's properties (suspend, filters, etc.).
|
||
|
||
Supported kwargs:
|
||
- suspend: boolean - Suspend or resume the link
|
||
- filters: dict - Packet filters (values MUST be positional arrays). Types
|
||
marked (K) run on kernel-datapath links only (both endpoints on one
|
||
compute with an anchor of their own) and are rejected with 409 on relay
|
||
links; which types a given link accepts is authoritatively answered by
|
||
link_available_filters:
|
||
* frequency_drop: [N] - Drop every Nth packet (N: -1 to 32767; -1 = drop
|
||
everything). Exact on kernel links (eBPF counter)
|
||
* packet_loss: [chance, correl?] - Loss percentage (0-100); correl (K)
|
||
makes consecutive losses dependent (bursty). CAVEAT: the kernel netem
|
||
correl suppresses small rates — a chance below ~the correl value drops
|
||
almost nothing (1% + correl 25% ≈ zero loss); use gemodel for bursty
|
||
loss at a known mean rate
|
||
* delay: [ms, jitter?, distribution?] - Latency 1-32767 ms, jitter 0-32767
|
||
ms; distribution (K) one of uniform|normal|pareto|paretonormal, needs
|
||
jitter > 0
|
||
* corrupt: [chance] - Corruption percentage (0-100)
|
||
* bpf: [expression] - Berkeley Packet Filter expression, one per line,
|
||
any match drops
|
||
* rate (K): ["512kbit"] - Bandwidth cap, tc-style int+unit (bit/kbit/
|
||
mbit/gbit/bps/kbps/mbps, max 100gbit)
|
||
* reorder (K): [pct, correl?, gap?] - Requires delay to also be set
|
||
* gemodel (K): [p, r, 1-h] - Gilbert-Elliot bursty loss; p = chance
|
||
of moving from the good to the bad state, r = chance of moving back,
|
||
1-h = loss chance in the bad state (the good state loses nothing);
|
||
steady-state mean loss = p/(p+r)*(1-h) per direction; mutually
|
||
exclusive with packet_loss
|
||
* duplicate (K): [pct, correl?] - Duplication percentage
|
||
* seed (K): [u32] - Makes netem random draws reproducible (needs
|
||
kernel >= 6.6; older kernels silently ignore the seed)
|
||
* limit (K): [pkts] - Impairment queue depth (default 1000; raise for
|
||
low rate + long delay)
|
||
* quota (K): [bytes, pct] - After the byte quota is consumed, each
|
||
further packet drops with the chance (100 = hard cutoff)
|
||
* window_drop (K): [start_ms, outage_ms, pct, period_ms?, jitter_ms?] -
|
||
Drop with chance pct inside [start, start+outage): 3 args = single
|
||
outage (traffic passes before and after), 4 args = recurring flap
|
||
(period >= outage), 5 args = per-cycle timing randomized within +/-
|
||
jitter. start is measured from the moment this filter is applied and
|
||
ANY filter update (including re-sending the same values) or node
|
||
restart restarts the schedule — a one-shot window that already
|
||
passed will not fire again until re-applied, so arm the filter
|
||
immediately before generating traffic (or use a period); start 0 =
|
||
outage begins immediately (active, not disabled)
|
||
|
||
Example filters:
|
||
{"filters": {"frequency_drop": [10]}}
|
||
{"filters": {"delay": [100, 10]}}
|
||
{"filters": {"window_drop": [0, 2000, 100]}}
|
||
{"filters": {"delay": [50, 5], "packet_loss": [2]}}
|
||
|
||
To clear all filters: {"filters": {}}
|
||
|
||
Filters are applied **bidirectionally** — a packet crossing the link twice
|
||
(e.g. ping round-trip) is filtered in both directions independently.
|
||
For example, packet_loss: [50] gives ~75% observed loss (1 - 0.5²), not 50%;
|
||
window_drop pct likewise applies per direction.
|
||
ARP frames also pass through filters; at high loss/corrupt rates, pre-set
|
||
static ARP entries to avoid false "Destination Host Unreachable" errors.
|
||
"""
|
||
params = {"project_id": project_id, "link_id": link_id, **kwargs}
|
||
return await asyncio.to_thread(_run_handler_sync, update_link_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def link_available_filters(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
link_id: Annotated[str, Field(description="UUID of the link")],
|
||
) -> list[dict[str, Any]]:
|
||
"""List the packet filter types available for a link with their parameters
|
||
and ranges — the authoritative answer for what link_update accepts on THIS
|
||
link (topology and compute-capability gated: kernel-only types appear only
|
||
on kernel-datapath links whose compute reports support). Call this before
|
||
setting filters; a type absent here will be rejected with 409."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
available_filters_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"link_id": link_id,
|
||
},
|
||
)
|
||
|
||
|
||
# ── Template tools ────────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def template_list(
|
||
fields: Annotated[
|
||
list[str] | None,
|
||
Field(
|
||
description="Response fields to include (default: [template_id, name, template_type, category, default_name_format]). "
|
||
"Available: template_id, name, version, category, default_name_format, symbol, "
|
||
"template_type, compute_id, usage, tags, builtin, created_at, updated_at"
|
||
),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""List all available templates on the server."""
|
||
return await asyncio.to_thread(_run_handler_sync, list_templates_handler, {"fields": fields})
|
||
|
||
|
||
@mcp.tool()
|
||
async def template_get(
|
||
template_id: Annotated[str | None, Field(description="Template UUID (optional if name is provided)")] = None,
|
||
name: Annotated[str | None, Field(description="Template name (optional if template_id is provided)")] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Get detailed information about a specific template."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
get_template_handler,
|
||
{
|
||
"template_id": template_id,
|
||
"name": name,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def template_create(
|
||
name: Annotated[str, Field(description="Template name")],
|
||
template_type: Annotated[str, Field(description="Template type (e.g. qemu, docker, dynamips)")],
|
||
compute_id: Annotated[str, Field(description="Compute ID (default: local)")] = "local",
|
||
image: Annotated[
|
||
str | None, Field(description="Docker image name or Dynamips IOS image path (required for docker/dynamips)")
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Create a new template.
|
||
|
||
Template-type-specific required parameters:
|
||
docker: image is required (e.g. "ubuntu:latest")
|
||
dynamips: image is required (path to .image file)
|
||
iou: needs 'path' (IOL image path) — set via template_update after creation
|
||
qemu: needs 'hda_disk_image' or 'qemu_path' — set via template_update after creation
|
||
"""
|
||
params = {"name": name, "template_type": template_type, "compute_id": compute_id}
|
||
if image:
|
||
params["image"] = image
|
||
return await asyncio.to_thread(_run_handler_sync, create_template_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def template_update(
|
||
template_id: Annotated[str | None, Field(description="Template UUID (optional if name is provided)")] = None,
|
||
name: Annotated[str | None, Field(description="Template name (optional if template_id is provided)")] = None,
|
||
**kwargs: Any,
|
||
) -> list[dict[str, Any]]:
|
||
"""Update an existing template's properties."""
|
||
params = {"template_id": template_id, "name": name, **kwargs}
|
||
return await asyncio.to_thread(_run_handler_sync, update_template_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def template_delete(
|
||
template_id: Annotated[str | None, Field(description="Template UUID (optional if name is provided)")] = None,
|
||
name: Annotated[str | None, Field(description="Template name (optional if template_id is provided)")] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Delete a template."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
delete_template_handler,
|
||
{
|
||
"template_id": template_id,
|
||
"name": name,
|
||
},
|
||
)
|
||
|
||
|
||
# ── Compute tools ─────────────────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def compute_list() -> list[dict[str, Any]]:
|
||
"""List all remotely registered compute nodes (returns only database entries, does NOT include the built-in local compute).
|
||
|
||
For the local compute info, use server_statistics instead.
|
||
"""
|
||
return await asyncio.to_thread(_run_handler_sync, list_computes_handler, {})
|
||
|
||
|
||
@mcp.tool()
|
||
async def compute_get(
|
||
compute_id: Annotated[
|
||
str,
|
||
Field(
|
||
description="Compute ID: 'local' (default) for the built-in local compute, or a compute UUID from compute_list"
|
||
),
|
||
] = "local",
|
||
) -> list[dict[str, Any]]:
|
||
"""Get detailed information about a compute node.
|
||
|
||
Accepts 'local' for the built-in local compute or a UUID from compute_list
|
||
for a registered remote compute.
|
||
"""
|
||
return await asyncio.to_thread(_run_handler_sync, get_compute_handler, {"compute_id": compute_id})
|
||
|
||
|
||
@mcp.tool()
|
||
async def compute_images(
|
||
emulator: Annotated[str, Field(description="Emulator type (e.g. qemu, iou, docker)")],
|
||
compute_id: Annotated[
|
||
str,
|
||
Field(
|
||
description="Compute ID: 'local' (default) for the built-in local compute, or a compute UUID from compute_list"
|
||
),
|
||
] = "local",
|
||
) -> list[dict[str, Any]]:
|
||
"""List available images for an emulator on a compute node.
|
||
|
||
Accepts 'local' for the built-in local compute or a UUID from compute_list
|
||
for a registered remote compute.
|
||
"""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
get_compute_images_handler,
|
||
{
|
||
"emulator": emulator,
|
||
"compute_id": compute_id,
|
||
},
|
||
)
|
||
|
||
|
||
# ── Node file tools ────────────────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_file_list(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str, Field(description="Node name or UUID")],
|
||
path: Annotated[str, Field(description="Subdirectory path within node directory (optional)")] = "",
|
||
recursive: Annotated[bool, Field(description="Recursively list all files (optional, default: false)")] = False,
|
||
) -> list[dict[str, Any]]:
|
||
"""List files in a node directory with metadata (name, size, type, modified time).
|
||
|
||
Use this first to check file sizes before reading files with get_node_file.
|
||
Large config files should be read in chunks using offset/limit.
|
||
"""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
list_node_files_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"node_id": node_id,
|
||
"path": path,
|
||
"recursive": recursive,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_file_get(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str, Field(description="Node name or UUID")],
|
||
file_path: Annotated[str, Field(description="Path to the file within the node directory")],
|
||
offset: Annotated[int, Field(description="Line offset to start reading from (optional, default: 0)")] = 0,
|
||
limit: Annotated[int, Field(description="Maximum number of lines to return (optional, default: 200)")] = 200,
|
||
) -> list[dict[str, Any]]:
|
||
"""Read a text file from a node directory line-by-line with offset/limit support.
|
||
|
||
Best practice:
|
||
1. First call list_node_files to see the file size before deciding to read.
|
||
2. Start with offset=0, limit=200 to preview the file.
|
||
3. If metadata.has_more is true, read more by increasing offset.
|
||
Large files (>50KB) are auto-truncated; check the metadata.truncated flag.
|
||
For binary files, check the file type via list_node_files first.
|
||
"""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
get_node_file_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"node_id": node_id,
|
||
"file_path": file_path,
|
||
"offset": offset,
|
||
"limit": limit,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_file_write(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str, Field(description="Node name or UUID")],
|
||
file_path: Annotated[str, Field(description="Path to the file within the node directory")],
|
||
content: Annotated[str, Field(description="Content to write to the file")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Write content to a file in a node directory. Creates the file if it doesn't exist. Overwrites existing content."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
write_node_file_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"node_id": node_id,
|
||
"file_path": file_path,
|
||
"content": content,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_file_delete(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str, Field(description="Node name or UUID")],
|
||
file_path: Annotated[str, Field(description="Path to the file within the node directory")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Delete a file from a node directory. Cannot be undone."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
delete_node_file_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"node_id": node_id,
|
||
"file_path": file_path,
|
||
},
|
||
)
|
||
|
||
|
||
# ── Node bulk / advanced tools ─────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_start_all(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Start all nodes in a project."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
start_all_nodes_handler,
|
||
{
|
||
"project_id": project_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_stop_all(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Stop all nodes in a project."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
stop_all_nodes_handler,
|
||
{
|
||
"project_id": project_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_suspend_all(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Suspend all nodes in a project."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
suspend_all_nodes_handler,
|
||
{
|
||
"project_id": project_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_duplicate(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str, Field(description="Node name or UUID to duplicate")],
|
||
x: Annotated[int, Field(description="X coordinate for the new node")] = 0,
|
||
y: Annotated[int, Field(description="Y coordinate for the new node")] = 0,
|
||
z: Annotated[int, Field(description="Z layer for the new node")] = 0,
|
||
) -> list[dict[str, Any]]:
|
||
"""Duplicate a node in a project, creating a copy at a new position."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
duplicate_node_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"node_id": node_id,
|
||
"x": x,
|
||
"y": y,
|
||
"z": z,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_isolate(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str, Field(description="Node name or UUID to isolate")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Isolate a node by suspending all its attached links (network isolation)."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
isolate_node_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"node_id": node_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_unisolate(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str, Field(description="Node name or UUID to unisolate")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Un-isolate a node by resuming all its suspended links."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
unisolate_node_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"node_id": node_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def node_links(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
node_id: Annotated[str, Field(description="Node name or UUID")],
|
||
) -> list[dict[str, Any]]:
|
||
"""List all links connected to a specific node."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
get_node_links_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"node_id": node_id,
|
||
},
|
||
)
|
||
|
||
|
||
# ── Link capture / reset tools ────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def link_reset(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
link_id: Annotated[str | None, Field(description="Link UUID (single mode)")] = None,
|
||
link_ids: Annotated[
|
||
list[str] | None, Field(description='Batch mode: ["uuid1","uuid2"] — reset multiple links in parallel')
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Reset one or more links by tearing down and recreating the UDP connection.
|
||
|
||
Use cases:
|
||
- Clear accumulated packet errors/drops from the link's UDP connection
|
||
- Force filter state (delay, packet loss, etc.) to restart fresh
|
||
- Recover a stuck or abnormal link state
|
||
|
||
This restarts the filter state machines (e.g. frequency_drop counters)
|
||
while keeping the filter configuration intact. Filters are preserved but
|
||
their internal application state resets.
|
||
"""
|
||
params: dict[str, Any] = {"project_id": project_id}
|
||
if link_ids:
|
||
params["link_ids"] = link_ids
|
||
else:
|
||
params["link_id"] = link_id
|
||
return await asyncio.to_thread(_run_handler_sync, reset_link_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def link_capture_start(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
link_id: Annotated[str | None, Field(description="Link UUID (single mode)")] = None,
|
||
data_link_type: Annotated[str, Field(description="Data link type (default: DLT_EN10MB)")] = "DLT_EN10MB",
|
||
capture_file_name: Annotated[str | None, Field(description="Capture file name (optional)")] = None,
|
||
wireshark: Annotated[bool, Field(description="Open Wireshark automatically (default: false)")] = False,
|
||
link_ids: Annotated[
|
||
list[str] | None,
|
||
Field(description='Batch mode: ["uuid1","uuid2"] — start capture on multiple links in parallel'),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Start packet capture on one or more links."""
|
||
params: dict[str, Any] = {
|
||
"project_id": project_id,
|
||
"data_link_type": data_link_type,
|
||
"capture_file_name": capture_file_name,
|
||
"wireshark": wireshark,
|
||
}
|
||
if link_ids:
|
||
params["link_ids"] = link_ids
|
||
else:
|
||
params["link_id"] = link_id
|
||
return await asyncio.to_thread(_run_handler_sync, start_capture_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def link_capture_stop(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
link_id: Annotated[str | None, Field(description="Link UUID (single mode)")] = None,
|
||
link_ids: Annotated[
|
||
list[str] | None,
|
||
Field(description='Batch mode: ["uuid1","uuid2"] — stop capture on multiple links in parallel'),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Stop packet capture on one or more links."""
|
||
params: dict[str, Any] = {"project_id": project_id}
|
||
if link_ids:
|
||
params["link_ids"] = link_ids
|
||
else:
|
||
params["link_id"] = link_id
|
||
return await asyncio.to_thread(_run_handler_sync, stop_capture_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def link_capture_download(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
link_id: Annotated[str | None, Field(description="Link UUID (single mode)")] = None,
|
||
link_ids: Annotated[
|
||
list[str] | None, Field(description='Batch mode: ["uuid1","uuid2"] — get download URLs for multiple captures')
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Get download command(s) for PCAP capture file(s).
|
||
|
||
Returns a ready-to-run curl command per link with a short-lived access
|
||
ticket (10 min) already embedded in the URL.
|
||
|
||
IMPORTANT — copy the returned values EXACTLY:
|
||
- Run each returned "curl_command" verbatim; it already contains the
|
||
full URL with ticket. NEVER construct or edit the URL yourself, and
|
||
NEVER copy the ticket by hand — a mistyped ticket is rejected.
|
||
- The ticket expires after 10 minutes: call this tool again to get a
|
||
fresh one; do not reuse an old URL.
|
||
"""
|
||
params: dict[str, Any] = {"project_id": project_id}
|
||
if link_ids:
|
||
params["link_ids"] = link_ids
|
||
else:
|
||
params["link_id"] = link_id
|
||
return await asyncio.to_thread(_run_handler_sync, download_capture_file_handler, params)
|
||
|
||
|
||
# ── Marker (traffic-insight) tools ─────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def link_marker(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
link_id: Annotated[str, Field(description="UUID of the link")],
|
||
action: Annotated[str, Field(description="Action: create, update, or delete")],
|
||
bpf: Annotated[
|
||
str | None, Field(description="BPF expression, e.g. 'arp', 'icmp', 'tcp port 80' (required for create)")
|
||
] = None,
|
||
marker_name: Annotated[str | None, Field(description="Marker name (required for update/delete actions)")] = None,
|
||
name: Annotated[
|
||
str | None, Field(description="Custom marker name for create action (auto-generated if omitted)")
|
||
] = None,
|
||
tag: Annotated[int | None, Field(description="Numeric tag for packet correlation")] = None,
|
||
enabled: Annotated[bool | None, Field(description="Enable or disable the marker (for update action)")] = None,
|
||
direction: Annotated[
|
||
str | None,
|
||
Field(
|
||
description="Direction filter: 'tx' (capture node sending only), 'rx' (receiving only), or 'both' (no filter — on update this clears a previously set direction). Omit to leave unchanged on update."
|
||
),
|
||
] = None,
|
||
capture_node_id: Annotated[
|
||
str | None,
|
||
Field(
|
||
description="UUID of the endpoint whose uBridge hosts the marker (the observer; tx/rx are from its perspective). Must be a link endpoint and marker-capable. Omit to auto-pick."
|
||
),
|
||
] = None,
|
||
color: Annotated[str | None, Field(description="Hex color for UI highlight, e.g. '#ff5722'")] = None,
|
||
highlight_duration: Annotated[int | None, Field(description="UI highlight duration in milliseconds")] = None,
|
||
data_link_type: Annotated[
|
||
str | None,
|
||
Field(
|
||
description="pcap link-layer type for serial links (create-only): DLT_C_HDLC / DLT_PPP_SERIAL / DLT_FRELAY / DLT_ATM_RFC1483, matching the encapsulation on the serial link. Omit = DLT_EN10MB (Ethernet). Ignored on update — changing it would invalidate the capture file."
|
||
),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Manage traffic-insight markers on a link.
|
||
|
||
A marker highlights packets matching a BPF expression as they cross the link.
|
||
Set action='create' to add a marker, 'update' to modify it, 'delete' to remove.
|
||
|
||
Create requires: project_id, link_id, action='create', bpf
|
||
Update requires: project_id, link_id, action='update', marker_name, and at least one of (bpf, tag, enabled, direction, color, highlight_duration)
|
||
Delete requires: project_id, link_id, action='delete', marker_name
|
||
|
||
To read current markers, use link_get — the response includes a 'markers' dict.
|
||
|
||
NOTE: Markers named 'global-*' are inherited from project-level marker definitions
|
||
and cannot be modified or deleted via this tool.
|
||
"""
|
||
params = {"project_id": project_id, "link_id": link_id, "action": action}
|
||
for opt in (
|
||
"bpf",
|
||
"marker_name",
|
||
"name",
|
||
"tag",
|
||
"enabled",
|
||
"direction",
|
||
"capture_node_id",
|
||
"color",
|
||
"highlight_duration",
|
||
"data_link_type",
|
||
):
|
||
val = locals().get(opt)
|
||
if val is not None:
|
||
params[opt] = val
|
||
return await asyncio.to_thread(_run_handler_sync, link_marker_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def marker_definition(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
action: Annotated[str, Field(description="Action: create, update, delete, or list")],
|
||
bpf: Annotated[
|
||
str | None, Field(description="BPF expression, e.g. 'arp', 'ospf', 'tcp port 22' (required for create)")
|
||
] = None,
|
||
def_name: Annotated[str | None, Field(description="Definition name (required for update/delete actions)")] = None,
|
||
name: Annotated[
|
||
str | None, Field(description="Custom definition name for create action (auto-generated if omitted)")
|
||
] = None,
|
||
tag: Annotated[int | None, Field(description="Numeric tag for packet correlation")] = None,
|
||
color: Annotated[str | None, Field(description="Hex color for UI highlight, e.g. '#ff5722'")] = None,
|
||
highlight_duration: Annotated[int | None, Field(description="UI highlight duration in milliseconds")] = None,
|
||
data_link_type: Annotated[
|
||
str | None,
|
||
Field(
|
||
description="pcap link-layer type for serial links (DLT_C_HDLC / DLT_PPP_SERIAL / DLT_FRELAY / DLT_ATM_RFC1483). Omit = Ethernet-only (serial links skipped); setting it also covers serial links with that encapsulation"
|
||
),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Manage project-level marker definitions — traffic-insight rules that apply to ALL links.
|
||
|
||
A marker definition is a global BPF rule. On create, it auto-fans out to every
|
||
link in the project as 'global-{name}'. Updates sync to all inherited copies.
|
||
On delete, 'global-{name}' is removed from every link.
|
||
|
||
Create requires: project_id, action='create', bpf
|
||
Update requires: project_id, action='update', def_name, and at least one of (bpf, tag, color, highlight_duration, data_link_type)
|
||
Delete requires: project_id, action='delete', def_name
|
||
List requires: project_id, action='list'
|
||
|
||
A definition has NO direction (tx/rx): it fans out to every link and auto-selects
|
||
its capture node on each, so a fixed direction has no consistent meaning. Encode
|
||
the direction you want in the BPF instead (e.g. 'icmp and icmp[icmptype]==8' for
|
||
echo requests only). For a capture-node-relative direction on a single link, use
|
||
the per-link `link_marker` tool.
|
||
|
||
Common BPF examples: 'arp', 'icmp', 'ospf', 'tcp port 22', 'udp port 53'
|
||
"""
|
||
params = {"project_id": project_id, "action": action}
|
||
for opt in ("bpf", "def_name", "name", "tag", "color", "highlight_duration", "data_link_type"):
|
||
val = locals().get(opt)
|
||
if val is not None:
|
||
params[opt] = val
|
||
return await asyncio.to_thread(_run_handler_sync, marker_definition_handler, params)
|
||
|
||
|
||
# ── Snapshot tools ─────────────────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def snapshot_list(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
) -> list[dict[str, Any]]:
|
||
"""List all snapshots of a project."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
get_snapshots_handler,
|
||
{
|
||
"project_id": project_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def snapshot_create(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
name: Annotated[str, Field(description="Name for the new snapshot")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Create a new snapshot of a project.
|
||
|
||
Prerequisite: All stoppable nodes (qemu, docker, dynamips, vpcs, iou, etc.)
|
||
must be stopped first. Use node_stop_all before creating a snapshot.
|
||
Cloud, NAT, and switch nodes are always-running and can be ignored.
|
||
"""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
create_snapshot_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"name": name,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def snapshot_delete(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
snapshot_id: Annotated[str, Field(description="UUID of the snapshot to delete")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Delete a snapshot from a project. Cannot be undone."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
delete_snapshot_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"snapshot_id": snapshot_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def snapshot_restore(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
snapshot_id: Annotated[str, Field(description="UUID of the snapshot to restore")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Restore a project to a previous snapshot state. The project may be closed and reopened."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
restore_snapshot_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"snapshot_id": snapshot_id,
|
||
},
|
||
)
|
||
|
||
|
||
# ── Drawing tools ──────────────────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def drawing_list(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
) -> list[dict[str, Any]]:
|
||
"""List all drawings (labels, shapes, images) on a project canvas."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
get_drawings_handler,
|
||
{
|
||
"project_id": project_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def drawing_create_text(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
x: Annotated[int, Field(description="X coordinate of the text top-left corner on the canvas")],
|
||
y: Annotated[int, Field(description="Y coordinate of the text top-left corner on the canvas")],
|
||
text: Annotated[str, Field(description="Label text; newlines (\\n) start additional lines")],
|
||
font_size: Annotated[int, Field(description="Font size, 1-200 (default: 13)")] = 13,
|
||
color: Annotated[str, Field(description="Text color, hex like #RRGGBB (default: #000000)")] = "#000000",
|
||
bold: Annotated[bool, Field(description="Bold text (default: false)")] = False,
|
||
font_family: Annotated[str, Field(description="Font family name (default: monospace)")] = "monospace",
|
||
z: Annotated[int, Field(description="Z layer; 1 keeps text above links (default: 1)")] = 1,
|
||
) -> list[dict[str, Any]]:
|
||
"""Add a text label to a project canvas.
|
||
|
||
The SVG is assembled server-side in the Web UI compatible format
|
||
(validation, escaping and sizing included).
|
||
|
||
- XML characters (& < >) are escaped automatically.
|
||
- Multi-line: embed newlines (\\n) in text; each line renders below the previous one.
|
||
- The drawing width/height are computed from the text and returned, so labels
|
||
can be laid out without guessing the selection box size.
|
||
- Constraints: color must be hex like #RRGGBB; font_family accepts plain names
|
||
(letters, digits, spaces, . ' -); text capped at 500 characters.
|
||
|
||
Example: bold red label at (100, 80):
|
||
drawing_create_text(project_id="demo", x=100, y=80, text="R1 management", color="#CC0000", bold=True)
|
||
"""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
create_text_drawing_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"text": text,
|
||
"x": x,
|
||
"y": y,
|
||
"z": z,
|
||
"font_size": font_size,
|
||
"color": color,
|
||
"bold": bold,
|
||
"font_family": font_family,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def drawing_create_rectangle(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
x: Annotated[int, Field(description="X coordinate of the rectangle top-left corner on the canvas")],
|
||
y: Annotated[int, Field(description="Y coordinate of the rectangle top-left corner on the canvas")],
|
||
width: Annotated[int, Field(description="Rectangle width in px, 1-2000")],
|
||
height: Annotated[int, Field(description="Rectangle height in px, 1-2000")],
|
||
fill: Annotated[str, Field(description='Fill color, hex like #RRGGBB or "none" (default: #FFFFFF)')] = "#FFFFFF",
|
||
fill_opacity: Annotated[float, Field(description="Fill opacity, 0-1 (default: 1.0)")] = 1.0,
|
||
stroke: Annotated[str | None, Field(description="Border color, hex like #RRGGBB; omit for no border")] = None,
|
||
stroke_width: Annotated[int, Field(description="Border width, 1-20 (default: 1)")] = 1,
|
||
dashed: Annotated[bool, Field(description="Dashed border, uses the default 10,6 pattern (default: false)")] = False,
|
||
dasharray: Annotated[str | None, Field(description='Custom dash pattern like "4,2"; requires stroke')] = None,
|
||
rx: Annotated[int, Field(description="Corner radius, 0 to min(width, height)/2 (default: 0)")] = 0,
|
||
z: Annotated[int, Field(description="Z layer; 0 keeps shapes behind nodes and text (default: 0)")] = 0,
|
||
) -> list[dict[str, Any]]:
|
||
"""Add a rectangle to a project canvas.
|
||
|
||
The SVG is assembled server-side in the Web UI compatible format
|
||
(validation included).
|
||
|
||
- fill "none" renders an outline-only box (stroke recommended then).
|
||
- Border attributes are only emitted when stroke is given.
|
||
- dasharray must be plain "on,off" numbers; the Qt-remapped patterns
|
||
("25, 25", "5, 25", ...) are rejected because the Web UI rewrites them.
|
||
|
||
Example: semi-transparent outline box at (200, 150):
|
||
drawing_create_rectangle(project_id="demo", x=200, y=150, width=400, height=200,
|
||
fill="none", stroke="#333333", dashed=True)
|
||
"""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
create_rectangle_drawing_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"x": x,
|
||
"y": y,
|
||
"z": z,
|
||
"width": width,
|
||
"height": height,
|
||
"fill": fill,
|
||
"fill_opacity": fill_opacity,
|
||
"stroke": stroke,
|
||
"stroke_width": stroke_width,
|
||
"dashed": dashed,
|
||
"dasharray": dasharray,
|
||
"rx": rx,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def drawing_create_ellipse(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
x: Annotated[int, Field(description="X coordinate of the bounding box top-left corner on the canvas")],
|
||
y: Annotated[int, Field(description="Y coordinate of the bounding box top-left corner on the canvas")],
|
||
width: Annotated[int, Field(description="Bounding box width in px, 2-2000; equal to height gives a circle")],
|
||
height: Annotated[int, Field(description="Bounding box height in px, 2-2000")],
|
||
fill: Annotated[str, Field(description='Fill color, hex like #RRGGBB or "none" (default: #FFFFFF)')] = "#FFFFFF",
|
||
fill_opacity: Annotated[float, Field(description="Fill opacity, 0-1 (default: 1.0)")] = 1.0,
|
||
stroke: Annotated[str | None, Field(description="Border color, hex like #RRGGBB; omit for no border")] = None,
|
||
stroke_width: Annotated[int, Field(description="Border width, 1-20 (default: 1)")] = 1,
|
||
dashed: Annotated[bool, Field(description="Dashed border, uses the default 10,6 pattern (default: false)")] = False,
|
||
dasharray: Annotated[str | None, Field(description='Custom dash pattern like "4,2"; requires stroke')] = None,
|
||
z: Annotated[int, Field(description="Z layer; 0 keeps shapes behind nodes and text (default: 0)")] = 0,
|
||
) -> list[dict[str, Any]]:
|
||
"""Add an ellipse (or circle) to a project canvas.
|
||
|
||
The SVG is assembled server-side in the Web UI compatible format. cx/cy are
|
||
derived from the bounding box (the Web UI treats them as offsets inside the
|
||
drawing, not canvas coordinates); for odd width/height the drawing is 1 px
|
||
smaller than requested and the actual size is returned.
|
||
|
||
Example: circle of diameter 160 at (300, 300):
|
||
drawing_create_ellipse(project_id="demo", x=300, y=300, width=160, height=160,
|
||
fill="#5AA9DD", fill_opacity=0.8)
|
||
"""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
create_ellipse_drawing_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"x": x,
|
||
"y": y,
|
||
"z": z,
|
||
"width": width,
|
||
"height": height,
|
||
"fill": fill,
|
||
"fill_opacity": fill_opacity,
|
||
"stroke": stroke,
|
||
"stroke_width": stroke_width,
|
||
"dashed": dashed,
|
||
"dasharray": dasharray,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def drawing_get(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
drawing_id: Annotated[str, Field(description="UUID of the drawing")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Get detailed information about a specific drawing."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
get_drawing_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"drawing_id": drawing_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def drawing_update(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
drawing_id: Annotated[str, Field(description="UUID of the drawing")],
|
||
svg: Annotated[str | None, Field(description="New SVG content")] = None,
|
||
locked: Annotated[bool | None, Field(description="Lock or unlock the drawing")] = None,
|
||
x: Annotated[int | None, Field(description="New X coordinate")] = None,
|
||
y: Annotated[int | None, Field(description="New Y coordinate")] = None,
|
||
z: Annotated[int | None, Field(description="New Z layer")] = None,
|
||
rotation: Annotated[int | None, Field(description="Rotation angle in degrees, -359 to 359")] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Update a drawing's properties (svg, position, lock state, rotation, etc.)."""
|
||
params: dict[str, Any] = {"project_id": project_id, "drawing_id": drawing_id}
|
||
local_vars = {"svg": svg, "locked": locked, "x": x, "y": y, "z": z, "rotation": rotation}
|
||
for key, val in local_vars.items():
|
||
if val is not None:
|
||
params[key] = val
|
||
return await asyncio.to_thread(_run_handler_sync, update_drawing_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def drawing_delete(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
drawing_id: Annotated[str, Field(description="UUID of the drawing to delete")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Delete a drawing from a project canvas. Cannot be undone."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
delete_drawing_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"drawing_id": drawing_id,
|
||
},
|
||
)
|
||
|
||
|
||
# ── Project lock tools ────────────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_lock(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Lock all drawings and nodes in a project to prevent accidental changes."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
lock_project_handler,
|
||
{
|
||
"project_id": project_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_unlock(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Unlock a project to allow editing of drawings and nodes."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
unlock_project_handler,
|
||
{
|
||
"project_id": project_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def project_locked(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Check whether a project is locked (preventing edits to drawings and nodes)."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
get_locked_project_handler,
|
||
{
|
||
"project_id": project_id,
|
||
},
|
||
)
|
||
|
||
|
||
# ── Server info tools ─────────────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def server_version() -> list[dict[str, Any]]:
|
||
"""Get GNS3 server version information."""
|
||
return await asyncio.to_thread(_run_handler_sync, get_version_handler, {})
|
||
|
||
|
||
@mcp.tool()
|
||
async def server_statistics() -> list[dict[str, Any]]:
|
||
"""Get GNS3 server statistics including computes, projects, nodes, and links."""
|
||
return await asyncio.to_thread(_run_handler_sync, get_statistics_handler, {})
|
||
|
||
|
||
# ── Symbol tools ──────────────────────────────────────────────────────
|
||
#
|
||
# Disabled for now: symbol handling requires a vision-capable model (the
|
||
# tools shuttle SVG content, which a text-only LLM cannot inspect or
|
||
# produce). Revisit later.
|
||
#
|
||
# @mcp.tool()
|
||
# async def symbol_list() -> list[dict[str, Any]]:
|
||
# """List all available symbols on the server."""
|
||
# return await asyncio.to_thread(_run_handler_sync, get_symbols_handler, {})
|
||
#
|
||
#
|
||
# @mcp.tool()
|
||
# async def symbol_get(
|
||
# symbol_id: Annotated[str, Field(description="Symbol ID (e.g. ':/symbols/router.svg')")],
|
||
# ) -> list[dict[str, Any]]:
|
||
# """Get a download URL for a symbol file (SVG).
|
||
#
|
||
# Returns a ready-to-run curl command with a short-lived access ticket
|
||
# (10 min) embedded in the URL. Run the returned "curl_command" verbatim —
|
||
# never reconstruct the URL or copy the ticket by hand. Re-call this tool
|
||
# once the ticket has expired.
|
||
# """
|
||
# return await asyncio.to_thread(_run_handler_sync, get_symbol_handler, {
|
||
# "symbol_id": symbol_id,
|
||
# })
|
||
#
|
||
#
|
||
# @mcp.tool()
|
||
# async def symbol_dimensions(
|
||
# symbol_id: Annotated[str, Field(description="Symbol ID to get dimensions for")],
|
||
# ) -> list[dict[str, Any]]:
|
||
# """Get the dimensions (width, height) of a symbol."""
|
||
# return await asyncio.to_thread(_run_handler_sync, get_symbol_dimensions_handler, {
|
||
# "symbol_id": symbol_id,
|
||
# })
|
||
#
|
||
#
|
||
# @mcp.tool()
|
||
# async def symbol_defaults() -> list[dict[str, Any]]:
|
||
# """Get the default symbol mapping for each node type."""
|
||
# return await asyncio.to_thread(_run_handler_sync, get_default_symbols_handler, {})
|
||
#
|
||
#
|
||
# @mcp.tool()
|
||
# async def symbol_upload(
|
||
# symbol_id: Annotated[str, Field(description="Symbol ID to upload (e.g. ':/symbols/my_symbol.svg')")],
|
||
# content: Annotated[str, Field(description="SVG content of the symbol")],
|
||
# ) -> list[dict[str, Any]]:
|
||
# """Upload or update a custom symbol on the server. Provide the SVG content as a string."""
|
||
# return await asyncio.to_thread(_run_handler_sync, upload_symbol_handler, {
|
||
# "symbol_id": symbol_id, "content": content,
|
||
# })
|
||
#
|
||
#
|
||
# @mcp.tool()
|
||
# async def symbol_delete(
|
||
# symbol_id: Annotated[str, Field(description="Symbol ID to delete (e.g. ':/symbols/my_custom_symbol.svg'). Use symbol_list to get existing IDs.")],
|
||
# ) -> list[dict[str, Any]]:
|
||
# """Delete a custom symbol from the server.
|
||
#
|
||
# NOTE: Only custom (user-uploaded) symbols can be deleted.
|
||
# Built-in symbols (starting with ':/symbols/') will be rejected with 403.
|
||
# Use symbol_list to see which symbols are available and their IDs.
|
||
# """
|
||
# return await asyncio.to_thread(_run_handler_sync, delete_symbol_handler, {
|
||
# "symbol_id": symbol_id,
|
||
# })
|
||
|
||
|
||
# ── Appliance tools ───────────────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def appliance_list(
|
||
fields: Annotated[
|
||
list[str] | None,
|
||
Field(
|
||
description='Optional: return only these fields. e.g. ["name","category"]. Available: name, category, description, vendor_name, product_name, status, availability, images, versions, tags, symbol, usage, builtin'
|
||
),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""List all available appliances (template library). Use fields=[] to return only what you need."""
|
||
return await asyncio.to_thread(_run_handler_sync, get_appliances_handler, {"fields": fields} if fields else {})
|
||
|
||
|
||
@mcp.tool()
|
||
async def appliance_get(
|
||
appliance_id: Annotated[str, Field(description="UUID of the appliance")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Get detailed information about a specific appliance."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
get_appliance_handler,
|
||
{
|
||
"appliance_id": appliance_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def appliance_install(
|
||
appliance_id: Annotated[str, Field(description="UUID of the appliance to install")],
|
||
version: Annotated[
|
||
str | None,
|
||
Field(
|
||
description="Version to install (e.g. '2.7.0.356'). Required if the appliance has multiple versions. Use appliance_get to see available versions."
|
||
),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Create a template from a GNS3 appliance definition and return the created template.
|
||
|
||
NOTE: This does NOT download images. Images must be placed in the
|
||
GNS3 images directory (e.g. ~/GNS3/images/) beforehand.
|
||
The appliance definition is read from local .gns3a files bundled with the server.
|
||
Use get_appliance first to see what images are required.
|
||
"""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
install_appliance_handler,
|
||
{
|
||
"appliance_id": appliance_id,
|
||
"version": version,
|
||
},
|
||
)
|
||
|
||
|
||
# ── Image tools ───────────────────────────────────────────────────────
|
||
|
||
|
||
@mcp.tool()
|
||
async def image_list() -> list[dict[str, Any]]:
|
||
"""List all images available on the server across all emulators."""
|
||
return await asyncio.to_thread(_run_handler_sync, get_images_handler, {})
|
||
|
||
|
||
@mcp.tool()
|
||
async def image_get(
|
||
image_id: Annotated[str, Field(description="ID or filename of the image")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Get detailed information about a specific image."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
get_image_handler,
|
||
{
|
||
"image_id": image_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def image_delete(
|
||
image_id: Annotated[str, Field(description="ID or filename of the image to delete")],
|
||
) -> list[dict[str, Any]]:
|
||
"""Delete an image from the server. Cannot be undone."""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
delete_image_handler,
|
||
{
|
||
"image_id": image_id,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def image_prune() -> list[dict[str, Any]]:
|
||
"""Remove images not referenced by any template.
|
||
|
||
NOTE: Only images that are not used by any template will be removed.
|
||
If all images are still referenced by templates, no images are deleted.
|
||
Use image_list to see which images exist and check if they are in use.
|
||
"""
|
||
return await asyncio.to_thread(_run_handler_sync, prune_images_handler, {})
|
||
|
||
|
||
@mcp.tool()
|
||
async def image_install() -> list[dict[str, Any]]:
|
||
"""Scan uploaded images and auto-create templates by matching image checksums against known appliance definitions.
|
||
|
||
This is NOT for downloading images. Images must be uploaded first (via the GNS3 Web UI).
|
||
If an uploaded image matches a known appliance, a template is automatically created.
|
||
Returns {"created": [...], "skipped": [...]}: images already referenced by existing
|
||
templates are skipped, and no template is auto-created when one with the same name
|
||
already exists (regardless of version).
|
||
"""
|
||
return await asyncio.to_thread(_run_handler_sync, install_images_handler, {})
|
||
|
||
|
||
# ── Device config tools ───────────────────────────────────────────────
|
||
# These tools connect to network device consoles via telnet/SSH using
|
||
# Nornir + Netmiko. Devices must be started and have a device_type tag.
|
||
#
|
||
# Workflow:
|
||
# 1. node_list(project_id) → identify device names
|
||
# 2. node_start_all(project_id) → ensure devices are running
|
||
# 3. device_config_send(project_id, device_configs=[...]) → push config
|
||
# 4. device_show_run(project_id, device_commands=[...]) → verify
|
||
|
||
|
||
@mcp.tool()
|
||
async def device_config_send(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
device_configs: Annotated[
|
||
list,
|
||
Field(
|
||
description='List of device configs. Each entry: {"device_name": "R1", "config_commands": ["int lo0", "ip add 1.1.1.1 255.255.255.255"]}'
|
||
),
|
||
],
|
||
template: Annotated[
|
||
str | None,
|
||
Field(
|
||
description='Optional Jinja2 template. Use with vars in each device to reduce token usage for batch config. Example: "interface lo{{ n }}\\nip address {{ ip }} 255.255.255.255"'
|
||
),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Send configuration commands to network devices via console (telnet/SSH).
|
||
|
||
Two modes:
|
||
1. Direct commands: each device has config_commands=[...]
|
||
2. Jinja2 template: provide template + vars per device — template is rendered for each
|
||
Example: device_configs=[{\"device_name\": \"R1\", \"vars\": {\"n\": 0, \"ip\": \"1.1.1.1\"}}]
|
||
|
||
Devices must be started first (use node_start or node_start_all).
|
||
Device type is auto-detected from the 'device_type:<type>' tag on each node.
|
||
Common device types: cisco_ios_telnet, cisco_xr_telnet, huawei_telnet, gns3_huawei_telnet_ce
|
||
|
||
Error contract: every failure is reported in-band as an entry with
|
||
status "failed" and an "error" message (per-device entries also carry
|
||
device_name and commands).
|
||
"""
|
||
params = {"project_id": project_id, "device_configs": device_configs}
|
||
if template is not None:
|
||
params["template"] = template
|
||
return await asyncio.to_thread(_run_handler_sync, device_config_send_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def device_show_run(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
device_configs: Annotated[
|
||
list,
|
||
Field(
|
||
description='List of device commands. Each entry: {"device_name": "R1", "commands": ["show ip int brief", "show running-config"]}'
|
||
),
|
||
],
|
||
template: Annotated[
|
||
str | None,
|
||
Field(
|
||
description='Optional Jinja2 template. Use with vars per device. Example: "show ip route {{ protocol }}"'
|
||
),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Run read-only diagnostic (show) commands on network devices via console.
|
||
|
||
Two modes:
|
||
1. Direct commands: each device has commands=[...] (read-only show/display/ping/traceroute only)
|
||
2. Jinja2 template: provide template + vars per device
|
||
|
||
Use this to inspect device status, view configurations, or verify changes.
|
||
For configuration changes use device_config_send instead.
|
||
|
||
Prerequisites:
|
||
- Devices must be started first (use node_start or node_start_all).
|
||
- Each node must have a device_type:<type> tag set in GNS3
|
||
(e.g. device_type:cisco_ios_telnet, device_type:gns3_huawei_telnet_ce).
|
||
Nodes without this tag will fail with "device_type tag not found".
|
||
Docker/Linux nodes are not supported (use node_console_exec instead).
|
||
|
||
Error contract: every failure is reported in-band as an entry with
|
||
status "failed" and an "error" message (per-device entries also carry
|
||
device_name and commands).
|
||
"""
|
||
params = {"project_id": project_id, "device_configs": device_configs}
|
||
if template is not None:
|
||
params["template"] = template
|
||
return await asyncio.to_thread(_run_handler_sync, device_show_run_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def vpcs_config_set(
|
||
project_id: Annotated[str, Field(description="Project name or UUID")],
|
||
device_configs: Annotated[
|
||
list,
|
||
Field(
|
||
description='List of VPCS configs. Each entry: {"device_name": "PC1", "commands": ["ip 10.0.0.1/24 10.0.0.254", "save"]}'
|
||
),
|
||
],
|
||
) -> list[dict[str, Any]]:
|
||
"""Configure VPCS devices (set IP addresses, gateway, etc.).
|
||
|
||
Only VPCS nodes are accepted: any other node type in device_configs fails
|
||
with a per-device error instead of typing VPCS syntax into its CLI.
|
||
Every failure is reported in-band as an entry with status "failed"
|
||
and an "error" message.
|
||
|
||
VPCS-specific configuration commands:
|
||
- ip <address>/<mask> <gateway> Set IP and gateway
|
||
- save Save config to startup.vpc
|
||
- ping <target> Test connectivity
|
||
"""
|
||
return await asyncio.to_thread(
|
||
_run_handler_sync,
|
||
vpcs_config_set_handler,
|
||
{
|
||
"project_id": project_id,
|
||
"device_configs": device_configs,
|
||
},
|
||
)
|
||
|
||
|
||
@mcp.tool()
|
||
async def device_skill_get(
|
||
device_type: Annotated[
|
||
str | None,
|
||
Field(description="Skill key exactly as action='list' returns it, e.g. 'frr_vtysh', 'cisco_ios_telnet'"),
|
||
] = None,
|
||
action: Annotated[str | None, Field(description='"list" to enumerate skills; "get" (default) to fetch one')] = None,
|
||
category: Annotated[str | None, Field(description='Optional category filter, e.g. "device" or "feature"')] = None,
|
||
topic: Annotated[
|
||
str | None,
|
||
Field(
|
||
description='Protocol topic key from the topic index, e.g. "ospf", "bgp". '
|
||
"Topic bodies load ONLY on an explicit topic request — every other call returns the base skill plus the topic index"
|
||
),
|
||
] = None,
|
||
detail: Annotated[str | None, Field(description='"index" | "summary" | "full" (default)')] = None,
|
||
issue: Annotated[str | None, Field(description="Single troubleshooting-issue key from the skill")] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Read device knowledge from the GNS3-Skills repository — BEFORE driving an unfamiliar console.
|
||
|
||
TOKEN-EFFICIENT USAGE (same protocol as the copilot's device_skills tool):
|
||
1. List every skill: device_skill_get(action="list")
|
||
2. Device skill list (topics): device_skill_get(device_type="frr_vtysh")
|
||
3. ONE targeted topic body: device_skill_get(device_type="frr_vtysh", topic="bgp")
|
||
|
||
Step 2 returns the base skill plus the topic index; step 3 loads the
|
||
targeted body. Pass the key exactly as step 1 returned it.
|
||
Devices without topics (single-file skills such as gns3_vpcs_telnet
|
||
or nokia_srlinux_cli) are complete at step 2 with the default full
|
||
detail — there is no topic step, and detail="index" only lists their
|
||
sections (config_commands, display_commands, ...).
|
||
category="device" or "feature" narrows both list and get.
|
||
Skills carry the operational quirks the generic tools cannot know:
|
||
FRR's console lands directly in vtysh (no -c on its ping, 'do' prefixes
|
||
inside scripted config), VPCS command syntax, IOS paging pitfalls.
|
||
|
||
Requires the skills repository to be configured (cloned); an
|
||
uninitialized repository fails with a clear error, while an empty but
|
||
initialized repository returns an empty list.
|
||
|
||
IF YOUR CLIENT OFFERS SUBAGENTS: on long tasks, delegate steps 1-2
|
||
to a subagent and ask it to return the exact command/quirk snippets
|
||
you need — not a prose summary. The full skill bodies then never
|
||
occupy this conversation's context.
|
||
"""
|
||
params: dict[str, Any] = {"action": action}
|
||
if device_type is not None:
|
||
params["device_type"] = device_type
|
||
if category is not None:
|
||
params["category"] = category
|
||
if topic is not None:
|
||
params["topic"] = topic
|
||
if detail is not None:
|
||
params["detail"] = detail
|
||
if issue is not None:
|
||
params["issue"] = issue
|
||
return await asyncio.to_thread(_run_handler_sync, device_skills_handler, params)
|
||
|
||
|
||
@mcp.tool()
|
||
async def injection_skill_get(
|
||
action: Annotated[
|
||
str | None,
|
||
Field(description='"list" (requires context) to find fault categories; "get" (default with device_type)'),
|
||
] = None,
|
||
context: Annotated[
|
||
list[str] | None,
|
||
Field(
|
||
description='REQUIRED for action="list": protocols/services found in the topology, '
|
||
'e.g. ["ospf", "bgp"]. Returns only the matching fault categories'
|
||
),
|
||
] = None,
|
||
device_type: Annotated[
|
||
str | None,
|
||
Field(description="Fault category key from action='list', e.g. 'injection_ospf_issues'"),
|
||
] = None,
|
||
detail: Annotated[str | None, Field(description='"index" | "summary" | "full" (default)')] = None,
|
||
issue: Annotated[
|
||
str | None,
|
||
Field(description="Single fault key from the category's issue index, e.g. 'ospf_hello_dead_mismatch'"),
|
||
] = None,
|
||
) -> list[dict[str, Any]]:
|
||
"""Read fault-injection knowledge from the GNS3-Skills repository.
|
||
|
||
Multi-call by design — analyze the topology first, then:
|
||
1. Find the fault categories that fit it (context REQUIRED):
|
||
injection_skill_get(action="list", context=["ospf", "bgp"])
|
||
2. Get one category's fault index (names only):
|
||
injection_skill_get(device_type="injection_ospf_issues", detail="index")
|
||
3. Get ONE fault's full detail:
|
||
injection_skill_get(device_type="injection_ospf_issues", issue="ospf_hello_dead_mismatch")
|
||
|
||
Then inject it with device_config_send, and verify with device_show_run.
|
||
|
||
context matches the skill's category, key and declared protocols
|
||
(case-insensitive), so aliases such as "ebgp" and "ospfv3" work.
|
||
Category keys are derived from the repository filenames — always pass
|
||
the key exactly as action="list" returned it.
|
||
"""
|
||
params: dict[str, Any] = {"action": action}
|
||
if context is not None:
|
||
params["context"] = context
|
||
if device_type is not None:
|
||
params["device_type"] = device_type
|
||
if detail is not None:
|
||
params["detail"] = detail
|
||
if issue is not None:
|
||
params["issue"] = issue
|
||
return await asyncio.to_thread(_run_handler_sync, injection_skills_handler, params)
|
||
|
||
|
||
# ── Auth‑wrapped Streamable HTTP app ──────────────────────────────────
|
||
|
||
|
||
def _make_auth_wrapper(inner_app):
|
||
"""Wrap the Streamable HTTP app with JWT validation.
|
||
|
||
Every request (POST / GET / DELETE) is authenticated. This is stricter
|
||
than the SSE transport, where only the opening GET was checked and
|
||
POSTs were trusted by session.
|
||
|
||
Supports two ways to pass the token (checked in order):
|
||
1. Authorization: Bearer <jwt> header
|
||
2. ?token=<jwt> query parameter (kept for GET streams opened by
|
||
clients that cannot set headers)
|
||
"""
|
||
|
||
async def auth_wrapper(scope, receive, send):
|
||
# Wait for GNS3 server to complete initialization before accepting MCP connections
|
||
server_ready = await wait_for_mcp_ready()
|
||
if not server_ready:
|
||
# Server initialization timed out - return 503 Service Unavailable
|
||
client_info = extract_client_info(scope, auth_service)
|
||
log.warning(
|
||
f"Rejecting MCP connection - GNS3 server initialization not complete. "
|
||
f"Client: {client_info['host']}:{client_info['port']} ({client_info['user_info']}, Path: {client_info['path']})"
|
||
)
|
||
response = Response("GNS3 server initialization not complete - please retry later", status_code=503)
|
||
await response(scope, receive, send)
|
||
return
|
||
|
||
if scope["type"] == "http":
|
||
token = None
|
||
headers = dict(scope.get("headers", []))
|
||
auth = headers.get(b"authorization", b"").decode()
|
||
if auth.startswith("Bearer "):
|
||
token = auth[7:]
|
||
if not token:
|
||
params = parse_qs(scope.get("query_string", b"").decode())
|
||
tokens = params.get("token", [])
|
||
if tokens:
|
||
token = tokens[0]
|
||
if not token:
|
||
response = Response("Missing or invalid token", status_code=401)
|
||
await response(scope, receive, send)
|
||
return
|
||
resolved = await _resolve_token(token)
|
||
if not resolved:
|
||
response = Response("Missing or invalid token", status_code=401)
|
||
await response(scope, receive, send)
|
||
return
|
||
_jwt_token_var.set(resolved)
|
||
# Remember the raw API key: the session task created by the
|
||
# initialize request inherits this context and uses it to renew
|
||
# its JWT once the minted one ages out (see _renew_expired_jwt).
|
||
if token.startswith("gns3_"):
|
||
_jwt_api_key_var.set(token)
|
||
await inner_app(scope, receive, send)
|
||
|
||
return auth_wrapper
|
||
|
||
|
||
# ── FastAPI router ────────────────────────────────────────────────────
|
||
|
||
router = APIRouter(prefix="/mcp", tags=["MCP"])
|
||
|
||
|
||
@router.get("/")
|
||
async def mcp_root():
|
||
"""MCP service metadata."""
|
||
return {
|
||
"name": "GNS3 MCP Server",
|
||
"version": "1.0.0",
|
||
"authentication": ["Authorization: Bearer <jwt>", "?token=<jwt>"],
|
||
"transports": {
|
||
"streamable_http": "/v3/mcp/transport",
|
||
},
|
||
}
|
||
|
||
|
||
# The auth-wrapped Streamable HTTP app — built once, mounted on the FastAPI
|
||
# app by register_starlette_routes() and reused by mcp_session_manager_lifespan().
|
||
_streamable_app = None
|
||
|
||
|
||
def _ensure_streamable_app():
|
||
"""Build the auth-wrapped Streamable HTTP app on first use."""
|
||
global _streamable_app
|
||
if _streamable_app is None:
|
||
_streamable_app = _make_auth_wrapper(
|
||
mcp.streamable_http_app(
|
||
streamable_http_path="/transport",
|
||
transport_security=_transport_security(),
|
||
)
|
||
)
|
||
return _streamable_app
|
||
|
||
|
||
@contextlib.asynccontextmanager
|
||
async def mcp_session_manager_lifespan():
|
||
"""Run the Streamable HTTP session manager for the lifetime of the GNS3 app.
|
||
|
||
Starlette does not run lifespans of mounted sub-apps, so the manager must
|
||
be entered in the FastAPI lifespan (gns3server.core.tasks.lifespan).
|
||
Enter it before startup finishes: the MCP ready gate opens at the end of
|
||
startup, and no request may pass it before the session manager is running
|
||
(its task group would otherwise reject the request).
|
||
"""
|
||
_ensure_streamable_app()
|
||
async with mcp.session_manager.run():
|
||
yield
|
||
|
||
|
||
def register_starlette_routes(app):
|
||
"""Mount the MCP Streamable HTTP transport on the FastAPI app."""
|
||
global _app
|
||
_app = app
|
||
app.mount("/v3/mcp", _ensure_streamable_app(), name="mcp-streamable-http")
|
||
log.info("MCP Streamable HTTP server mounted at /v3/mcp/transport")
|
||
|
||
# Log registered MCP tools for verification
|
||
tool_names = sorted(tool.name for tool in mcp._tool_manager.list_tools())
|
||
log.info("MCP tools registered (%d): %s", len(tool_names), ", ".join(tool_names))
|