mirror of
https://github.com/GNS3/gns3-server.git
synced 2026-11-22 05:55:14 +02:00
Upgrade MCP SDK to 2.3 and switch transport from SSE to Streamable HTTP
- Drop the unused fastmcp wrapper pin (mcp-requirements.txt) and depend on the official SDK directly: mcp>=2.3,<3. The code only ever imported mcp.server.* modules; fastmcp was pulled in solely as a dependency vehicle and its <4 pin kept mcp locked at 1.x. - Migrate to the SDK 2.x API: FastMCP -> MCPServer (mcp.server.mcpserver); transport_security moves from the constructor into streamable_http_app(). - Replace the deprecated SSE transport (spec-deprecated 2025-06-18) with Streamable HTTP at POST/GET/DELETE /v3/mcp/transport, mounted at /v3/mcp. - Run the StreamableHTTP session manager in the FastAPI lifespan (Starlette does not execute mounted sub-app lifespans), entered before startup finishes so no request passes the MCP ready gate first. - Authenticate every request (the SSE wrapper only checked the opening GET and trusted POSTs by session). Add a 5-minute TTL cache for API-key resolutions so the stricter per-request check does not cost a bcrypt round on every call. - Update docs to the new endpoint, auth flow, and client configuration. Wire-format verified unchanged against SDK 1.30 (structured output auto-detection and content conversion are byte-identical for the list[dict] returns used by all tool handlers).
This commit is contained in:
1 parent
a5e98e2109
commit
fe1b2a5cb0
8 files changed
+160
-70
No files matched your search
@@ -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
|
||||
|
||||
@@ -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_<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)
|
||||
@@ -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 <jwt> header
|
||||
2. ?token=<jwt> query parameter
|
||||
|
||||
POST messages are passed through (authenticated by their session).
|
||||
2. ?token=<jwt> 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 <jwt>", "?token=<jwt>"],
|
||||
"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))
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -16,6 +16,7 @@
|
||||
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
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:
|
||||
|
||||
Reference in new issue
Block a user