diff --git a/docs/features/mcp-service.md b/docs/features/mcp-service.md index 4963ad748..286c2cccc 100644 --- a/docs/features/mcp-service.md +++ b/docs/features/mcp-service.md @@ -2,7 +2,7 @@ ## Overview -GNS3 Server provides a standard [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) interface, allowing AI assistants like Claude to interact with GNS3 network simulations through SSE (Server-Sent Events) transport. +GNS3 Server provides a standard [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) interface, allowing AI assistants like Claude to interact with GNS3 network simulations through the Streamable HTTP transport (the SSE transport was deprecated in the MCP specification on 2025-06-18). The MCP service exposes GNS3 project management operations as MCP tools that can be discovered and called by MCP clients. @@ -11,21 +11,24 @@ The MCP service exposes GNS3 project management operations as MCP tools that can | Path | Method | Description | |------|--------|-------------| | `/v3/mcp/` | GET | MCP service metadata | -| `/v3/mcp/transport/sse` | GET | SSE stream (MCP connection) | -| `/v3/mcp/transport/messages/` | POST | JSON-RPC messages | +| `/v3/mcp/transport` | POST | JSON-RPC requests (initialize, tools/list, tools/call, notifications) | +| `/v3/mcp/transport` | GET | Optional server-to-client event stream (opened after initialize) | +| `/v3/mcp/transport` | DELETE | Session termination | + +The server assigns a session on `initialize` and returns it in the `Mcp-Session-Id` response header; subsequent requests carry it back as a request header. ## Authentication -The SSE endpoint supports two types of credentials, passed the same way. +Every request to `/v3/mcp/transport` is authenticated. Two types of credentials are supported, passed either way. 1. **Authorization header** (recommended): ``` Authorization: Bearer ``` -2. **Query parameter** (for clients that don't support custom headers): +2. **Query parameter** (for clients that can't set headers, e.g. browser EventSource): ``` - GET /v3/mcp/transport/sse?token= + GET /v3/mcp/transport?token= ``` ### Option 1: JWT Token (24h expiry) @@ -74,13 +77,15 @@ Both JWT tokens and API keys work for MCP and REST API endpoints interchangeably When connecting with an API key: ``` -SSE connect → Authorization: Bearer gns3__ +POST initialize → Authorization: Bearer gns3__ ↓ MCP auth wrapper extracts UUID → single DB query → 1 bcrypt (thread pool) ↓ -Generates a fresh short-lived JWT → stored in ContextVar for the session +Generates a fresh 24h JWT → stored in ContextVar for the session ↓ -All subsequent tool handler REST API calls use this JWT → zero extra bcrypt +Tool handlers run in the session task created by that request → they use this JWT + ↓ +Later requests re-validate the credential (result cached ~5 min → no repeated bcrypt) ``` ### Concurrency @@ -94,7 +99,7 @@ All subsequent tool handler REST API calls use this JWT → zero extra bcrypt ## Available Tools -**76 tools** across 11 categories: +**78 tools** across 11 categories: ### Project (14) @@ -341,8 +346,8 @@ sequenceDiagram ```bash # Option A: Using API key (recommended — never expires) -claude mcp add --transport sse My_GNS3_Server \ - http://localhost:3080/v3/mcp/transport/sse \ +claude mcp add --transport http My_GNS3_Server \ + http://localhost:3080/v3/mcp/transport \ -H "Authorization: Bearer gns3_a1b2c3d4..." # Option B: Using JWT token (expires after 24h) @@ -351,14 +356,14 @@ TOKEN=$(curl -s -X POST http://localhost:3080/v3/access/users/authenticate \ -d '{"username": "admin", "password": "admin"}' | python3 -c \ "import sys,json; print(json.load(sys.stdin)['access_token'])") -claude mcp add --transport sse My_GNS3_Server \ - http://localhost:3080/v3/mcp/transport/sse \ +claude mcp add --transport http My_GNS3_Server \ + http://localhost:3080/v3/mcp/transport \ -H "Authorization: Bearer $TOKEN" ``` ## Transport Security -MCP server uses FastMCP's DNS rebinding protection to prevent attackers from +MCP server uses the MCP SDK's DNS rebinding protection to prevent attackers from exploiting DNS resolution to access the MCP endpoint through unauthorized domains. ### Default Behaviour @@ -389,7 +394,7 @@ mcp_allowed_origins = http://127.0.0.1:*,http://localhost:*,http://192.168.1.3:* ### Protection Mechanism When protection is enabled, the MCP server validates the `Host` header of -incoming SSE connection requests: +incoming MCP requests: ```python # Verify the request's Host header matches allowed patterns @@ -421,8 +426,8 @@ sequenceDiagram participant Auth as Auth participant GNS3 as GNS3 REST API - Note over Client: 1. Connect with API Key or JWT - Client->>MCP: GET /sse (Authorization: Bearer ) + Note over Client: 1. Initialize with API Key or JWT + Client->>MCP: POST /transport initialize (Authorization: Bearer ) alt API Key (gns3_<uuid>_<secret>) MCP->>Auth: Extract UUID → DB lookup → 1 bcrypt (thread pool) @@ -432,22 +437,23 @@ sequenceDiagram Auth-->>MCP: Token valid end - MCP-->>Client: event: endpoint /messages/?session_id=xxx + MCP-->>Client: initialize result + Mcp-Session-Id header - Note over Client: 2. Initialize & Call Tools - Client->>MCP: POST /messages/ (tools/call ...) - MCP->>GNS3: HTTP request (with JWT from step 1) + Note over Client: 2. Call Tools (each request re-authenticated) + Client->>MCP: POST /transport tools/call (Mcp-Session-Id + Bearer) + MCP->>GNS3: HTTP request (with JWT pinned at session creation) GNS3-->>MCP: Response - MCP-->>Client: event: message (tool result) + MCP-->>Client: tool result (SSE or JSON response body) ``` ## Internal Implementation -- **FastMCP** (Anthropic MCP SDK) is used for tool registration and SSE transport -- The SSE app is mounted as a Starlette sub-application under `/v3/mcp/transport` -- **Auth:** JWT validation via `auth_service`. API key (`gns3__`) extracts UUID for O(1) DB lookup, runs bcrypt in thread pool, returns a fresh JWT — subsequent calls use the JWT with zero extra bcrypt. +- **MCPServer** (official MCP SDK, `mcp.server.mcpserver` — `FastMCP` was renamed in SDK 2.x) is used for tool registration and the Streamable HTTP transport +- The Streamable HTTP app is mounted as a Starlette sub-application at `/v3/mcp` (endpoint `/v3/mcp/transport`) +- The session manager (`mcp.session_manager.run()`) is entered in the FastAPI lifespan (`gns3server.core.tasks.lifespan`) — Starlette does not run lifespans of mounted sub-apps +- **Auth:** JWT validation via `auth_service` on every request. API key (`gns3__`) extracts UUID for O(1) DB lookup, runs bcrypt in thread pool, returns a fresh JWT — resolutions are cached ~5 minutes so repeated requests cost no extra bcrypt. - Tool handlers use `Gns3Connector` (from `gns3_copilot.gns3_client.connector`) via the shared handler layer (`gns3_copilot.gns3_client.api_handlers`), keeping the MCP layer decoupled -- The JWT token is stored in a `contextvars.ContextVar` so it is available within tool handler threads (Python ≥ 3.9 propagates contextvars through `asyncio.to_thread`) +- The JWT token is stored in a `contextvars.ContextVar` so it is available within tool handler threads (Python ≥ 3.9 propagates contextvars through `asyncio.to_thread`). In stateful Streamable HTTP the session task inherits the context of the opening request, so handlers see the token presented at `initialize` ### Console WebSocket @@ -477,7 +483,7 @@ websocat ws://192.168.1.3:3080/v3/projects/{project_id}/nodes/{node_id}/console/ | File | Purpose | |------|---------| -| `gns3server/agent/mcp/__init__.py` | FastMCP server, tool decorators, SSE transport, JWT auth wrapper | +| `gns3server/agent/mcp/__init__.py` | MCPServer, tool decorators, Streamable HTTP transport, JWT auth wrapper | | `gns3server/agent/mcp/projects.py` | Project tool handlers | | `gns3server/agent/mcp/nodes.py` | Node tool handlers | | `gns3server/agent/mcp/links.py` | Link tool handlers | diff --git a/docs/features/project-open-performance.md b/docs/features/project-open-performance.md index e3be54315..3729a914a 100644 --- a/docs/features/project-open-performance.md +++ b/docs/features/project-open-performance.md @@ -122,7 +122,7 @@ if await asyncio.to_thread(bcrypt.checkpw, secret.encode(), db_key.key_hash.enco **File:** `gns3server/agent/mcp/__init__.py` -When an MCP client connects with an API key, the `_resolve_token` function validates the key then returns a fresh short-lived JWT instead of the raw API key. The JWT is stored in a `ContextVar` and reused for all subsequent tool calls within the same SSE session — zero extra bcrypt. +When an MCP client connects with an API key, the `_resolve_token` function validates the key then returns a fresh short-lived JWT instead of the raw API key. The JWT is stored in a `ContextVar` and reused for all subsequent tool calls within the same MCP session — zero extra bcrypt. ```python if user: diff --git a/gns3server/agent/__init__.py b/gns3server/agent/__init__.py index f27893a61..e113cd9f3 100644 --- a/gns3server/agent/__init__.py +++ b/gns3server/agent/__init__.py @@ -87,7 +87,7 @@ try: # namespace — it would shadow the gns3server.agent.mcp subpackage. import importlib - importlib.import_module("mcp.server.fastmcp") + importlib.import_module("mcp.server.mcpserver") MCP_AVAILABLE = True except ImportError: # MCP dependencies not installed, disable MCP feature diff --git a/gns3server/agent/mcp/__init__.py b/gns3server/agent/mcp/__init__.py index 541e8793c..cbc518845 100644 --- a/gns3server/agent/mcp/__init__.py +++ b/gns3server/agent/mcp/__init__.py @@ -18,19 +18,22 @@ """ MCP (Model Context Protocol) service for GNS3 server. -Implements the standard MCP protocol over SSE transport using FastMCP: +Implements the standard MCP protocol over the Streamable HTTP transport +using the official MCP SDK (mcp.server.mcpserver.MCPServer): - /v3/mcp/sse — SSE stream - /v3/mcp/messages/ — JSON-RPC messages + /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 @@ -38,7 +41,7 @@ from uuid import UUID import bcrypt from fastapi import APIRouter from fastapi.responses import Response -from mcp.server.fastmcp import FastMCP +from mcp.server.mcpserver import MCPServer from mcp.server.transport_security import TransportSecuritySettings from pydantic import Field from sqlalchemy.ext.asyncio import AsyncSession @@ -221,8 +224,11 @@ async def wait_for_mcp_ready() -> bool: # ── Per‑connection JWT token ───────────────────────────────────────── -# Set during SSE authentication, read by tool handlers running in the -# same asyncio task (contextvars propagate through asyncio.to_thread). +# 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 @@ -236,6 +242,27 @@ _jwt_token_version_var: contextvars.ContextVar[int] = contextvars.ContextVar("mc # ── 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. @@ -246,7 +273,7 @@ async def _resolve_token(token: str) -> str | None: 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 connection. + # 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) @@ -256,6 +283,15 @@ async def _resolve_token(token: str) -> str | None: 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__ → O(1) lookup if token.startswith("gns3_") and _app is not None: db_engine = getattr(_app.state, "_db_engine", None) @@ -279,6 +315,7 @@ async def _resolve_token(token: str) -> str | None: 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 @@ -304,28 +341,27 @@ def _server_url() -> str: return f"{scheme}://{host}:{cfg.Server.port}" -# ── FastMCP Server ──────────────────────────────────────────────────── +# ── MCP Server ──────────────────────────────────────────────────────── -def _create_mcp_server() -> FastMCP: - """Create MCP server with security settings from configuration.""" +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 FastMCP + # 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: - transport_security = TransportSecuritySettings( + 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:*"], ) - else: - transport_security = TransportSecuritySettings( - enable_dns_rebinding_protection=False, - ) - - mcp = FastMCP("GNS3 MCP Server", transport_security=transport_security) - return mcp + return TransportSecuritySettings(enable_dns_rebinding_protection=False) mcp = _create_mcp_server() @@ -2104,17 +2140,20 @@ async def vpcs_config_set( ) -# ── Auth‑wrapped SSE app ────────────────────────────────────────────── +# ── Auth‑wrapped Streamable HTTP app ────────────────────────────────── def _make_auth_wrapper(inner_app): - """Wrap the SSE app with JWT validation. + """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 header - 2. ?token= query parameter - - POST messages are passed through (authenticated by their session). + 2. ?token= query parameter (kept for GET streams opened by + clients that cannot set headers) """ async def auth_wrapper(scope, receive, send): @@ -2131,7 +2170,7 @@ def _make_auth_wrapper(inner_app): await response(scope, receive, send) return - if scope["type"] == "http" and scope["method"] == "GET": + if scope["type"] == "http": token = None headers = dict(scope.get("headers", [])) auth = headers.get(b"authorization", b"").decode() @@ -2170,19 +2209,51 @@ async def mcp_root(): "version": "1.0.0", "authentication": ["Authorization: Bearer ", "?token="], "transports": { - "sse": "/v3/mcp/transport/sse", + "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 MCP transports on the FastAPI app.""" + """Mount the MCP Streamable HTTP transport on the FastAPI app.""" global _app _app = app - sse_app = _make_auth_wrapper(mcp.sse_app(mount_path="")) - app.mount("/v3/mcp/transport", sse_app, name="mcp-sse") - log.info("MCP SSE server mounted at /v3/mcp/transport") + 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 = list(mcp._tool_manager._tools.keys()) - log.info("MCP tools registered (%d): %s", len(tool_names), ", ".join(sorted(tool_names))) + 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)) diff --git a/gns3server/api/server.py b/gns3server/api/server.py index 1e587f8ea..1b5c3dc0d 100644 --- a/gns3server/api/server.py +++ b/gns3server/api/server.py @@ -123,7 +123,7 @@ def get_application() -> FastAPI: app = get_application() -# Register MCP SSE transport routes (Starlette-level, for raw ASGI access) +# Register MCP Streamable HTTP transport route (Starlette-level, for raw ASGI access) if MCP_AVAILABLE: mcp.register_starlette_routes(app) diff --git a/gns3server/core/tasks.py b/gns3server/core/tasks.py index bb1f2edd6..1a3e50f45 100644 --- a/gns3server/core/tasks.py +++ b/gns3server/core/tasks.py @@ -16,6 +16,7 @@ # along with this program. If not, see . import asyncio +import contextlib import logging from contextlib import asynccontextmanager @@ -36,11 +37,21 @@ log = logging.getLogger(__name__) @asynccontextmanager async def lifespan(app: FastAPI): - await startup(app) - try: - yield - finally: - await shutdown(app) + # The MCP Streamable HTTP session manager runs for the app's whole + # lifetime (mounted sub-app lifespans are not executed by Starlette). + # Entered before startup so it is running before the MCP ready gate opens. + from gns3server.agent import MCP_AVAILABLE + + async with contextlib.AsyncExitStack() as stack: + if MCP_AVAILABLE: + from gns3server.agent.mcp import mcp_session_manager_lifespan + + await stack.enter_async_context(mcp_session_manager_lifespan()) + await startup(app) + try: + yield + finally: + await shutdown(app) async def startup(app: FastAPI) -> None: diff --git a/mcp-requirements.txt b/mcp-requirements.txt index 0c1c2fcb6..d76aa97d4 100644 --- a/mcp-requirements.txt +++ b/mcp-requirements.txt @@ -5,4 +5,6 @@ # Or directly: pip install -r mcp-requirements.txt # ============================================================================== -fastmcp>=3.4.0,<4 +# The official MCP SDK only — the server code imports mcp.server.mcpserver +# directly (no fastmcp wrapper). mcp 2.x: FastMCP was renamed to MCPServer. +mcp>=2.3.0,<3 diff --git a/requirements.txt b/requirements.txt index 338284f1d..fbaae54ef 100644 --- a/requirements.txt +++ b/requirements.txt @@ -19,7 +19,7 @@ joserfc==1.7.7 email-validator==2.3.0 watchdog==6.0.0 # upgrading to v7.0.0 creates issues zstandard==0.25.0 -platformdirs>=4.14.2 # fastmcp-slim >=3.4 requires >=4.0.0; upper bound removed for compatibility +platformdirs>=4.14.2 truststore>=0.10.5 # Shared dependencies (also used by AI Copilot)