diff --git a/nitrostack/transports/http.py b/nitrostack/transports/http.py deleted file mode 100644 index d5a2b60..0000000 --- a/nitrostack/transports/http.py +++ /dev/null @@ -1,797 +0,0 @@ -""" -Streamable HTTP transport for NitroStack (Phase 3). - -The official `mcp` SDK's `StreamableHTTPSessionManager` already provides -per-session isolation (one transport + one `Server.run()` task per session), -SSE streaming, resumability via an event store, idle-session timeouts, and -DNS-rebinding protection via `TransportSecuritySettings`. This module does -NOT reimplement any of that — it wires those existing features through -NitroStack's config/env vars and adds the handful of pieces the manager does -not provide out of the box: - -- CORS headers for browser-based MCP clients -- A concurrent-session cap with a `429` response (the manager has no public - session-count API or creation hook, so this is tracked via a thin ASGI - middleware watching the `mcp-session-id` header) -- A `/mcp/health` endpoint -- A documentation landing page at `GET /` (connection setup + tool catalog) -- Chrome DevTools discovery stubs at `GET /json` and `GET /json/version` so - inspector probes do not 404 -- JSON 404s for OAuth discovery / DCR (`/register`) so MCP Inspector does not - treat the HTML landing page as an OAuth error -- Legacy SSE (`/sse` + `/mcp/messages/`) for older HTTP+SSE-only clients - -See `dev-plan/PHASE-3-http-transport.md` for the full scope. -""" -from __future__ import annotations - -import contextlib -import logging -import os -import sys -import time -from typing import TYPE_CHECKING, Any, Dict, List, Optional - -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.middleware.cors import CORSMiddleware -from starlette.responses import HTMLResponse, JSONResponse, Response -from starlette.routing import Mount, Route -from starlette.types import ASGIApp, Receive, Scope, Send - -from nitrostack.transports.landing_page import render_landing_page -from nitrostack.widgets.preview_page import render_preview_page -from nitrostack.core.di import DIContainer -from nitrostack.transports.cors import configured_cors_origins -from pydantic_core import PydanticUndefined -from mcp.server.sse import SseServerTransport -from mcp.server.streamable_http_manager import StreamableHTTPSessionManager -from mcp.server.transport_security import TransportSecuritySettings - -from nitrostack.protocol.version import ( - HttpEngine, - ProtocolEra, - WireMode, - protocol_version_for_era, - resolve_http_engine, -) -from nitrostack.protocol.constants import LEGACY_SESSION_HEADER -from nitrostack.transports.headers import ( - CORS_ALLOW_HEADER_NAMES, - CORS_EXPOSE_HEADER_NAMES, - SSE_SUBSCRIPTIONS_PATH, - strip_legacy_session_headers_asgi, -) -from nitrostack.transports.subscriptions import subscriptions_listen_endpoint -from nitrostack.transports.proxy import public_url_for_request -from nitrostack.core.log_emitter import install_log_handler - -if TYPE_CHECKING: - from nitrostack.core.app import McpApplication - -logger = logging.getLogger("nitrostack.transports.http") - -DEFAULT_ENDPOINT = "/mcp" - -# Shared 2026 allow-headers. Session id is exposed only on the sessionful engine. -CORS_ALLOW_HEADERS = list(CORS_ALLOW_HEADER_NAMES) - -# The Accept value `StreamableHTTPServerTransport` requires: it needs -# `application/json` on POST and `text/event-stream` on both POST and GET. -MCP_ACCEPT = "application/json, text/event-stream" - -_PROCESS_START = time.monotonic() - - -def _server_meta(mcp_app: "McpApplication") -> Dict[str, str]: - cfg = getattr(mcp_app, "server_config", None) - return { - "name": getattr(cfg, "name", None) or "NitroStack MCP Server", - "version": getattr(cfg, "version", None) or "1.0.0", - } - - -def _landing_tools(mcp_app: "McpApplication") -> List[Dict[str, Any]]: - tools: List[Dict[str, Any]] = [] - for entry in getattr(mcp_app, "_tools", {}).values(): - try: - schema = mcp_app._tool_input_schema(entry.input_model) - except Exception: - logger.exception("Landing page schema failed for %s", entry.config.name) - schema = None - tools.append( - { - "name": entry.config.name, - "description": entry.config.description or "", - "inputSchema": schema, - } - ) - return tools - - -def _env_list(name: str) -> List[str]: - raw = os.environ.get(name) - if not raw: - return [] - return [item.strip() for item in raw.split(",") if item.strip()] - - -def _env_flag(name: str) -> bool: - return (os.environ.get(name) or "").strip().lower() in {"1", "true", "yes", "on"} - - -def _enable_trace_logging() -> None: - """ - Give `logger` its own stderr handler so tracing works regardless of how the - host application configured logging. - - `FileLogger` only attaches handlers to the `nitrostack` logger when it is - first instantiated, which for an HTTP server may not happen until a tool - runs. Until then this module's records fall through to `logging`'s - last-resort handler and INFO is discarded. Propagation is disabled so the - traces are not emitted twice once `FileLogger` does attach its handler. - stderr keeps them off stdout, which dual mode uses for JSON-RPC. - """ - install_log_handler("nitrostack.transports.http") - if any(getattr(handler, "_nitrostack_trace", False) for handler in logger.handlers): - return - handler = logging.StreamHandler(sys.stderr) - handler.setFormatter(logging.Formatter("%(asctime)s [%(levelname)s] (%(name)s): %(message)s")) - handler._nitrostack_trace = True # type: ignore[attr-defined] - logger.addHandler(handler) - logger.setLevel(logging.INFO) - logger.propagate = False - - -class RequestTraceMiddleware: - """ - Log the raw request line, headers and body of every HTTP request, plus the - response status and headers. - - Enabled only when `NITROSTACK_HTTP_DEBUG=1`. uvicorn's access log has no - timestamps and no headers, which makes it impossible to tell *why* the - `mcp` SDK rejected a client request (a `406` and a `400` from the SDK are - both header-driven) or even to correlate a failed client connection with a - log line. This middleware is the outermost layer so it sees requests - exactly as the client sent them, before CORS or any path rewriting. - """ - - MAX_BODY_CHARS = 2000 - REDACTED_HEADERS = {"authorization", "proxy-authorization", "cookie", "set-cookie"} - - def __init__(self, app: ASGIApp) -> None: - self.app = app - - @classmethod - def _decode_headers(cls, raw: Any) -> Dict[str, str]: - headers = {} - for key, value in raw or []: - name = key.decode("latin-1") - headers[name] = "" if name.lower() in cls.REDACTED_HEADERS else value.decode("latin-1") - return headers - - async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: - if scope["type"] != "http": - await self.app(scope, receive, send) - return - - method = scope.get("method") - path = scope.get("path") - query = (scope.get("query_string") or b"").decode("latin-1") - target = f"{path}?{query}" if query else path - logger.info("trace >> %s %s headers=%s", method, target, self._decode_headers(scope.get("headers"))) - - async def traced_receive() -> Any: - message = await receive() - if message.get("type") == "http.request": - body = message.get("body") or b"" - if body: - text = body.decode("utf-8", errors="replace") - if len(text) > self.MAX_BODY_CHARS: - text = text[: self.MAX_BODY_CHARS] + "..." - logger.info("trace >> %s %s body=%s", method, target, text) - return message - - async def traced_send(message: Any) -> None: - if message.get("type") == "http.response.start": - logger.info( - "trace << %s %s status=%s headers=%s", - method, - target, - message.get("status"), - self._decode_headers(message.get("headers")), - ) - await send(message) - - await self.app(scope, traced_receive, traced_send) - - -def _preview_default_arguments(entry: Any) -> Dict[str, Any]: - """Prefill live preview with tool examples (shopId, openNow, …).""" - examples = getattr(getattr(entry, "config", None), "examples", None) - raw = getattr(examples, "input", None) if examples is not None else None - if isinstance(raw, dict): - return dict(raw) - model = getattr(entry, "input_model", None) - if model is None: - return {} - data: Dict[str, Any] = {} - for fname, field in getattr(model, "model_fields", {}).items(): - default = getattr(field, "default", PydanticUndefined) - if default is not PydanticUndefined and default is not None: - data[fname] = default - continue - if fname in ("shopId", "shop_id"): - data[fname] = "tonys-pizza" - elif fname == "product_id": - data[fname] = "sku-1" - elif fname == "filter": - data[fname] = "all" - elif fname == "openNow": - data[fname] = True - elif fname == "origin": - data[fname] = "JFK" - elif fname == "destination": - data[fname] = "LAX" - elif fname in ("departureDate", "departure_date"): - data[fname] = "2026-09-15" - elif fname in ("offerId", "offer_id"): - data[fname] = "off_mock123456" - elif fname in ("orderId", "order_id"): - data[fname] = "ord_mock123456" - elif fname == "query": - data[fname] = "London" - return data - - -class ExactEndpointSlashMiddleware: - """ - Internally rewrite `/mcp` → `/mcp/` so Starlette does not 307. - - `Mount("/mcp")` only matches `/mcp/...`. With `redirect_slashes=True` - (Starlette's default) a request to `/mcp` becomes `307 Location: /mcp/`. - MCP Inspector's Streamable HTTP client POSTs and GETs `/mcp` with no - trailing slash; following that 307 on the GET SSE stream drops the - connection, so List Tools shows a blank page and disconnects. - """ - - def __init__(self, app: ASGIApp, endpoint: str) -> None: - self.app = app - self._exact = endpoint.rstrip("/") or "/" - - async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: - if scope["type"] == "http" and scope.get("path") == self._exact: - scope = dict(scope) - scope["path"] = self._exact + "/" - raw = scope.get("raw_path") - if isinstance(raw, (bytes, bytearray)): - scope["raw_path"] = raw.rstrip(b"/") + b"/" - await self.app(scope, receive, send) - - -class HeaderCompatMiddleware: - """ - Normalize ``Accept`` on the Streamable HTTP mount so wildcard or absent - Accept does not 406. Session ids are stripped only when - ``drop_session_headers`` is set. - - ``MCP-Protocol-Version`` is never deleted. Duplicate casings are collapsed - to lowercase names and client values are preserved so the official - transport can reject duplicate or inconsistent version claims. - - Stack order on the HTTP app: CORS → this middleware (preserve) → handler. - This middleware only normalizes transport headers; JSON-RPC dispatch remains - owned by the official MCP Streamable HTTP manager. - """ - - def __init__(self, app: ASGIApp, *, drop_session_headers: bool = False, - require_protocol_version: bool = False) -> None: - self.app = app - self.drop_session_headers = drop_session_headers - self.require_protocol_version = require_protocol_version - - @staticmethod - def _normalize_accept(value: Optional[str]) -> Optional[str]: - if value is None or not value.strip(): - return MCP_ACCEPT - media_types = [media_type.strip() for media_type in value.split(",")] - has_json = any(media_type.startswith("application/json") for media_type in media_types) - has_sse = any(media_type.startswith("text/event-stream") for media_type in media_types) - if has_json and has_sse: - return None - # Only a wildcard is rewritten. A client that names concrete media types - # but omits one the transport needs is genuinely non-compliant (the spec - # requires both on POST), so it keeps getting the transport's 406. - if any(media_type.startswith("*/*") for media_type in media_types): - return MCP_ACCEPT - return None - - @staticmethod - def _canonicalize_protocol_version(headers: List[Any]) -> List[Any]: - """Normalize casing without hiding duplicates from MCP's validator.""" - version_values: List[bytes] = [] - kept: List[Any] = [] - for key, value in headers: - if key.lower() == b"mcp-protocol-version": - version_values.append(value) - else: - kept.append((key, value)) - if not version_values: - return headers - kept.extend((b"mcp-protocol-version", value) for value in version_values) - return kept - - async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: - if scope["type"] != "http": - await self.app(scope, receive, send) - return - - headers: List[Any] = list(scope.get("headers") or []) - if self.require_protocol_version and scope.get("method") == "POST" and not any( - key.lower() == b"mcp-protocol-version" and value.strip() for key, value in headers - ): - # The official manager selects its strict path using this header. - # Reject before that selection without reading/replaying the body - # or interpreting a method. All JSON-RPC dispatch stays in MCP. - response = JSONResponse( - {"jsonrpc": "2.0", "id": None, "error": { - "code": -32020, "message": "MCP-Protocol-Version header is required", - }}, status_code=400, - ) - await response(scope, receive, send) - return - if self.drop_session_headers: - headers = strip_legacy_session_headers_asgi(headers) - headers = self._canonicalize_protocol_version(headers) - - raw_accept = next((value for key, value in headers if key.lower() == b"accept"), None) - accept = self._normalize_accept(raw_accept.decode("latin-1") if raw_accept is not None else None) - if accept is not None: - headers = [(key, value) for key, value in headers if key.lower() != b"accept"] - headers.append((b"accept", accept.encode("latin-1"))) - logger.debug("Rewrote Accept %r -> %r for %s", raw_accept, accept, scope.get("path")) - - scope = dict(scope) - scope["headers"] = headers - await self.app(scope, receive, send) - - -class SessionCapMiddleware: - """ - Enforce a `max_sessions` concurrent-session cap on the Streamable HTTP - mount, returning a `429` JSON-RPC error once at capacity. - - `StreamableHTTPSessionManager` doesn't expose a public session count or a - session-created/closed hook, so this middleware tracks session ids itself - by observing the `mcp-session-id` request header (existing sessions) and - the `Mcp-Session-Id` response header (newly created sessions), and prunes - entries locally after `session_idle_timeout` so the count self-heals even - if a client disconnects without sending `DELETE`. - """ - - def __init__( - self, - app: ASGIApp, - max_sessions: Optional[int], - session_idle_timeout: Optional[float] = None, - ) -> None: - self.app = app - self.max_sessions = max_sessions - self.session_idle_timeout = session_idle_timeout - self._sessions: Dict[str, float] = {} - - def _prune_stale(self) -> None: - if not self.session_idle_timeout: - return - cutoff = time.monotonic() - self.session_idle_timeout - for sid in [s for s, seen in self._sessions.items() if seen < cutoff]: - self._sessions.pop(sid, None) - - async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: - if scope["type"] != "http" or not self.max_sessions: - await self.app(scope, receive, send) - return - - self._prune_stale() - - headers = dict(scope.get("headers") or []) - raw_session_id = headers.get(b"mcp-session-id") - session_id = raw_session_id.decode() if raw_session_id else None - is_known = session_id is not None and session_id in self._sessions - - if not is_known and len(self._sessions) >= self.max_sessions: - response = JSONResponse( - { - "jsonrpc": "2.0", - "error": { - "code": -32000, - "message": "Too many sessions: server at capacity, retry later", - }, - "id": None, - }, - status_code=429, - ) - await response(scope, receive, send) - return - - if is_known: - self._sessions[session_id] = time.monotonic() - - new_session_id: Dict[str, Optional[str]] = {"value": None} - - async def send_wrapper(message: Any) -> None: - if message["type"] == "http.response.start": - for key, value in message.get("headers", []): - if key.lower() == b"mcp-session-id": - new_session_id["value"] = value.decode() - await send(message) - - await self.app(scope, receive, send_wrapper) - - if new_session_id["value"]: - self._sessions[new_session_id["value"]] = time.monotonic() - - if scope.get("method") == "DELETE" and session_id: - self._sessions.pop(session_id, None) - - @property - def active_session_count(self) -> int: - self._prune_stale() - return len(self._sessions) - - -def _oauth_is_configured() -> bool: - """True when ``OAuthModule.for_root`` registered an ``OAuthService`` instance.""" - try: - from nitrostack.auth.oauth import OAuthService - - return DIContainer.get_instance().has_value(OAuthService) - except Exception: - return False - - -def build_http_app( - mcp_app: "McpApplication", - *, - endpoint: str = DEFAULT_ENDPOINT, - max_sessions: Optional[int] = None, - session_idle_timeout: Optional[float] = None, - enable_cors: bool = True, - stateless: bool = False, - json_response: bool = False, - protocol_era: ProtocolEra = "auto", - wire_mode: WireMode = "stateless", - http_engine: Optional[HttpEngine] = None, -) -> Starlette: - """ - Build the Starlette app exposing NitroStack's owned low-level server over - Streamable HTTP (`/mcp`), legacy SSE (`/sse` + `/mcp/messages/`), and a - health check (`/mcp/health`). - - Args: - mcp_app: The bootstrapped `McpApplication` whose `mcp_server` (and - registered tools/resources/prompts) this app serves. - endpoint: Streamable HTTP mount path (default `/mcp`). - max_sessions: Optional concurrent-session cap; `None`/`0` disables the cap. - session_idle_timeout: Optional idle timeout in seconds for stateful - sessions (ignored when `stateless=True`). - enable_cors: Whether to add permissive CORS headers (default `True`). - When `False`, DNS-rebinding - protection (Origin/Host validation) is enabled instead, configured - via `MCP_ALLOWED_HOSTS`/`MCP_ALLOWED_ORIGINS` env vars. - stateless: When `True`, every request gets a fresh transport with no - session id and no session tracking (see `StreamableHTTPSessionManager`). - This is the primitive the `2026-07-28` stateless MCP spec needs; - exposed here as a config knob so adopting that spec later doesn't - require touching this wiring again. - json_response: When `True`, a POST carrying a JSON-RPC request is - answered with a plain `application/json` body instead of a - `text/event-stream` SSE frame. The spec allows either, but a client - that doesn't implement SSE parsing for POST responses sees the SSE - form as a stream that ended without a result. Server-initiated - streaming (progress, notifications) is unavailable in this mode. - protocol_era: ``legacy`` / ``modern`` / ``auto``. Distinct from ``stateless``. - wire_mode: Dual-spec policy for 2025 traffic (``sessionful``, ``stateless`` - fallback, or ``reject``). ``auto`` uses ``stateless``; ``modern`` uses - ``reject``. - http_engine: Era factory result. ``sessionless`` for modern/auto, - ``sessionful`` only for legacy. ``auto`` / ``modern`` never start - a sessionful manager, even if ``stateless=False``. - """ - http_engine = resolve_http_engine( - protocol_era, http_engine=http_engine, stateless=stateless - ) - stateless = http_engine == "sessionless" - - server = mcp_app.mcp_server - if server is not None: - server.http_engine = http_engine - server.sessionful = http_engine == "sessionful" - server.protocol_era = protocol_era - - security_settings = None - if not enable_cors: - allowed_hosts = _env_list("MCP_ALLOWED_HOSTS") or ["localhost:*", "127.0.0.1:*"] - allowed_origins = _env_list("MCP_ALLOWED_ORIGINS") - security_settings = TransportSecuritySettings( - enable_dns_rebinding_protection=True, - allowed_hosts=allowed_hosts, - allowed_origins=allowed_origins, - ) - else: - security_settings = TransportSecuritySettings(enable_dns_rebinding_protection=False) - - # Official mcp 2.x owns /mcp (streamable HTTP, both protocol eras). - # One manager only; auto/modern are sessionless and legacy is sessionful. - session_manager = StreamableHTTPSessionManager( - app=mcp_app.mcp_server, - stateless=stateless, - json_response=json_response, - session_idle_timeout=None if stateless else session_idle_timeout, - security_settings=security_settings, - ) - # Trailing slash is required: Starlette's Mount("/mcp/messages") only matches - # "/mcp/messages/" (or deeper), NOT bare "/mcp/messages". Without the slash the - # endpoint event points at a path that falls through to Mount("/mcp") (Streamable - # HTTP), which then 406s SSE clients that don't send Streamable Accept headers. - # Matches the mcp SDK's own SseServerTransport example ("/messages/"). - sse_messages_path = f"{endpoint.rstrip('/')}/messages/" - sse_transport = SseServerTransport(sse_messages_path) - - async def handle_streamable_http(scope: Scope, receive: Receive, send: Send) -> None: - await session_manager.handle_request(scope, receive, send) - - # Wraps only the Streamable HTTP mount, so `/mcp/health` and the legacy SSE - # routes keep their own (correct) content negotiation. - mcp_asgi_app: ASGIApp = HeaderCompatMiddleware( - handle_streamable_http, drop_session_headers=stateless, - require_protocol_version=protocol_era == "modern", - ) - session_cap: Optional[SessionCapMiddleware] = None - if max_sessions and not stateless: - session_cap = SessionCapMiddleware( - mcp_asgi_app, max_sessions=max_sessions, session_idle_timeout=session_idle_timeout - ) - mcp_asgi_app = session_cap - - async def handle_sse(request): - async with sse_transport.connect_sse(request.scope, request.receive, request._send) as streams: - await mcp_app.mcp_server.run(streams[0], streams[1], mcp_app.mcp_server.create_initialization_options()) - return Response() - - def _request_public_mcp_url(request) -> str: - port = os.environ.get("PORT") or os.environ.get("MCP_SERVER_PORT") or "3000" - return public_url_for_request( - request, - path=endpoint.rstrip("/") or "/mcp", - fallback_host=f"localhost:{port}", - ) - - async def health_check(request): - return JSONResponse( - { - "status": "ok", - "transport": "streamable-http", - "protocolVersion": protocol_version_for_era(protocol_era), - "protocolEra": protocol_era, - "statelessCapable": http_engine == "sessionless", - "stateless": stateless, - "jsonResponse": json_response, - "sessions": session_cap.active_session_count if session_cap else None, - "uptimeSeconds": round(time.monotonic() - _PROCESS_START, 2), - "publicUrl": _request_public_mcp_url(request), - } - ) - - async def root_page(request): - meta = _server_meta(mcp_app) - return HTMLResponse( - render_landing_page( - name=meta["name"], - version=meta["version"], - description=getattr(getattr(mcp_app, "server_config", None), "description", None), - mcp_endpoint=_request_public_mcp_url(request), - tools=_landing_tools(mcp_app), - ) - ) - - async def oauth_not_supported(request): - """Inspector DCR posts `/register` when Authentication is on. - - Return JSON (not the HTML 404 page) so the client shows a clear - OAuth-off message instead of `Unexpected token '<'`. - """ - connect_url = _request_public_mcp_url(request) - return JSONResponse( - { - "error": "invalid_request", - "error_description": ( - "This MCP server does not use OAuth. In MCP Inspector turn " - "Authentication off, then connect with Streamable HTTP to " - f"{connect_url}." - ), - }, - status_code=404, - ) - - async def widgets_preview(request): - catalog = [] - for name, entry in getattr(mcp_app, "_tools", {}).items(): - component = getattr(entry, "component", None) - if component is None: - continue - catalog.append( - { - "name": name, - "resourceUri": component.resource_uri, - "arguments": _preview_default_arguments(entry), - } - ) - return HTMLResponse(render_preview_page(catalog)) - - async def widgets_preview_call(request): - try: - body = await request.json() - except Exception: - return JSONResponse({"error": "Invalid JSON body"}, status_code=400) - if not isinstance(body, dict): - return JSONResponse({"error": "JSON body must be an object"}, status_code=400) - name = body.get("tool") or "" - arguments = body.get("arguments") or {} - if not isinstance(arguments, dict): - return JSONResponse({"error": "arguments must be an object"}, status_code=400) - entry = getattr(mcp_app, "_tools", {}).get(name) - if entry is None or getattr(entry, "component", None) is None: - return JSONResponse({"error": f"No widget tool named {name!r}"}, status_code=404) - try: - result = await mcp_app._call_tool(name, arguments) - except Exception as exc: - logger.exception("Widget preview tool call failed for %s", name) - return JSONResponse({"error": str(exc)}, status_code=400) - structured = getattr(result, "structured_content", None) - if structured is None: - structured = getattr(result, "structuredContent", None) - try: - html = entry.component.html_with_data(structured) - except Exception as exc: - logger.exception("Widget preview render failed for %s", name) - return JSONResponse( - { - "error": f"Widget render failed: {exc}", - "structuredContent": structured, - "html": None, - "resourceUri": entry.component.resource_uri, - "isError": True, - }, - status_code=400, - ) - return JSONResponse( - { - "structuredContent": structured, - "html": html, - "resourceUri": entry.component.resource_uri, - "isError": bool(getattr(result, "is_error", None) if getattr(result, "is_error", None) is not None else getattr(result, "isError", False)), - } - ) - - async def json_version(request): - """Chrome/Cursor DevTools probe `/json/version` when a tab opens localhost.""" - meta = _server_meta(mcp_app) - health_path = f"{endpoint.rstrip('/')}/health" - return JSONResponse( - { - "Browser": meta["name"], - "Protocol-Version": protocol_version_for_era(protocol_era), - "User-Agent": f"NitroStack/{meta['version']}", - "webSocketDebuggerUrl": "", - "transport": "mcp", - "publicUrl": _request_public_mcp_url(request), - "endpoints": { - "mcp": endpoint, - "sse": "/sse", - "health": health_path, - }, - } - ) - - async def json_list(request): - """Chrome DevTools `/json` and `/json/list` expect a page list; empty = not CDP.""" - return JSONResponse([]) - - async def favicon(request): - return Response(status_code=204) - - @contextlib.asynccontextmanager - async def lifespan(app): - async with session_manager.run(): - logger.info( - "StreamableHTTP session manager started (stateless=%s, max_sessions=%s, " - "session_idle_timeout=%s)", - stateless, - max_sessions, - session_idle_timeout, - ) - yield - - oauth_stub_routes: List[Route] = [] - if not _oauth_is_configured(): - # Inspector DCR / discovery stubs. Omit when OAuthModule is registered so - # a real protected-resource document is not replaced with "no OAuth". - oauth_stub_routes = [ - Route("/.well-known/oauth-authorization-server", endpoint=oauth_not_supported, methods=["GET", "POST"]), - Route("/.well-known/oauth-protected-resource", endpoint=oauth_not_supported, methods=["GET", "POST"]), - Route("/register", endpoint=oauth_not_supported, methods=["GET", "POST"]), - Route("/oauth/v2/register", endpoint=oauth_not_supported, methods=["GET", "POST"]), - ] - - routes = [ - # More specific paths MUST come before the catch-all `Mount(endpoint, ...)` - # below — Starlette matches routes in order, and a `Mount` matches any - # path under its prefix, so `/mcp/health` would otherwise be swallowed - # by the `/mcp` mount before ever reaching the health route. - Route("/", endpoint=root_page, methods=["GET"]), - Route("/widgets/preview", endpoint=widgets_preview, methods=["GET"]), - Route("/widgets/preview/call", endpoint=widgets_preview_call, methods=["POST"]), - *oauth_stub_routes, - Route("/json/version", endpoint=json_version, methods=["GET"]), - Route("/json/list", endpoint=json_list, methods=["GET"]), - Route("/json", endpoint=json_list, methods=["GET"]), - Route("/favicon.ico", endpoint=favicon, methods=["GET"]), - Route(f"{endpoint}/health", endpoint=health_check, methods=["GET"]), - Mount(sse_messages_path, app=sse_transport.handle_post_message), - # `handle_streamable_http`/`sse_transport.handle_post_message` are raw - # ASGI apps (scope, receive, send), so they must be `Mount`ed rather - # than used as `Route` endpoints (which expect `Request -> Response`). - Mount(endpoint, app=mcp_asgi_app), - Route("/sse", endpoint=handle_sse, methods=["GET"]), - ] - if protocol_era != "legacy": - routes.append( - Route( - SSE_SUBSCRIPTIONS_PATH, - endpoint=subscriptions_listen_endpoint(mcp_app), - methods=["GET", "POST"], - ) - ) - - # Rewrite `/mcp` → `/mcp/` *before* routing so Inspector never sees a 307. - # CORS stays outermost so preflight still works on the original path. - middleware = [ - Middleware(ExactEndpointSlashMiddleware, endpoint=endpoint), - ] - if enable_cors: - expose_headers = list(CORS_EXPOSE_HEADER_NAMES) - if http_engine == "sessionful": - expose_headers.append(LEGACY_SESSION_HEADER) - # Single CORS layer for `/mcp`: the sidecar that used to add a second - # one has been removed (#22), so `MCP_CORS_ALLOWED_ORIGINS` is honored - # here and nowhere else. - allow_origins = list(configured_cors_origins()) or ["*"] - middleware.insert( - 0, - Middleware( - CORSMiddleware, - allow_origins=allow_origins, - allow_methods=["GET", "POST", "DELETE", "OPTIONS"], - # SEP-2243 permits application-defined Mcp-Param-* names. - # Starlette mirrors requested names when '*' is enabled. - allow_headers=[*CORS_ALLOW_HEADERS, "*"], - expose_headers=expose_headers, - ), - ) - - if _env_flag("NITROSTACK_HTTP_DEBUG"): - _enable_trace_logging() - middleware.insert(0, Middleware(RequestTraceMiddleware)) - - app = Starlette(routes=routes, middleware=middleware, lifespan=lifespan) - app.state.protocol_era = protocol_era - app.state.wire_mode = wire_mode - app.state.stateless = stateless - app.state.http_engine = http_engine - app.state.sessionful = http_engine == "sessionful" - app.state.session_manager = session_manager - app.state.streamable_http_manager_count = 1 - app.state.subscription_bus = getattr(mcp_app.mcp_server, "subscription_bus", None) - app.state.protocol_version = protocol_version_for_era(protocol_era) - return app diff --git a/nitrostack/transports/http/__init__.py b/nitrostack/transports/http/__init__.py new file mode 100644 index 0000000..99d39cc --- /dev/null +++ b/nitrostack/transports/http/__init__.py @@ -0,0 +1,65 @@ +""" +Streamable HTTP transport for NitroStack (Phase 3). + +The official `mcp` SDK's `StreamableHTTPSessionManager` already provides +per-session isolation (one transport + one `Server.run()` task per session), +SSE streaming, resumability via an event store, idle-session timeouts, and +DNS-rebinding protection via `TransportSecuritySettings`. This package does +NOT reimplement any of that — it wires those existing features through +NitroStack's config/env vars and adds the handful of pieces the manager does +not provide out of the box: + +- CORS headers for browser-based MCP clients +- A concurrent-session cap with a `429` response (the manager has no public + session-count API or creation hook, so this is tracked via a thin ASGI + middleware watching the `mcp-session-id` header) +- A `/mcp/health` endpoint +- A documentation landing page at `GET /` (connection setup + tool catalog) +- Chrome DevTools discovery stubs at `GET /json` and `GET /json/version` so + inspector probes do not 404 +- JSON 404s for OAuth discovery / DCR (`/register`) so MCP Inspector does not + treat the HTML landing page as an OAuth error +- Legacy SSE (`/sse` + `/mcp/messages/`) for older HTTP+SSE-only clients + +Module layout (dependencies point one way, top to bottom): + constants, env -> middleware, tracing, handlers -> app -> __init__ + +This package replaces the former single module `nitrostack/transports/http.py`. +Names are re-exported here so existing imports keep working. + +See `dev-plan/PHASE-3-http-transport.md` for the full scope. +""" +from nitrostack.transports.http.app import _oauth_is_configured, build_http_app +from nitrostack.transports.http.constants import ( + CORS_ALLOW_HEADERS, + DEFAULT_ENDPOINT, + MCP_ACCEPT, + _PROCESS_START, + logger, +) +from nitrostack.transports.http.env import _env_flag, _env_list +from nitrostack.transports.http.handlers import ( + _landing_tools, + _preview_default_arguments, + _server_meta, +) +from nitrostack.transports.http.middleware import ( + ExactEndpointSlashMiddleware, + HeaderCompatMiddleware, + SessionCapMiddleware, +) +from nitrostack.transports.http.tracing import ( + RequestTraceMiddleware, + _enable_trace_logging, +) + +__all__ = [ + "build_http_app", + "DEFAULT_ENDPOINT", + "CORS_ALLOW_HEADERS", + "MCP_ACCEPT", + "ExactEndpointSlashMiddleware", + "HeaderCompatMiddleware", + "SessionCapMiddleware", + "RequestTraceMiddleware", +] \ No newline at end of file diff --git a/nitrostack/transports/http/app.py b/nitrostack/transports/http/app.py new file mode 100644 index 0000000..57e10c8 --- /dev/null +++ b/nitrostack/transports/http/app.py @@ -0,0 +1,277 @@ +"""HTTP app assembly: `build_http_app`.""" +from __future__ import annotations + +import contextlib +from typing import TYPE_CHECKING, List, Optional + +from mcp.server.sse import SseServerTransport +from mcp.server.streamable_http_manager import StreamableHTTPSessionManager +from mcp.server.transport_security import TransportSecuritySettings +from starlette.applications import Starlette +from starlette.middleware import Middleware +from starlette.middleware.cors import CORSMiddleware +from starlette.responses import Response +from starlette.routing import Mount, Route +from starlette.types import ASGIApp, Receive, Scope, Send + +from nitrostack.core.di import DIContainer +from nitrostack.protocol.constants import LEGACY_SESSION_HEADER +from nitrostack.protocol.version import ( + HttpEngine, + ProtocolEra, + WireMode, + protocol_version_for_era, + resolve_http_engine, +) +from nitrostack.transports.cors import configured_cors_origins +from nitrostack.transports.headers import ( + CORS_EXPOSE_HEADER_NAMES, + SSE_SUBSCRIPTIONS_PATH, +) +from nitrostack.transports.http.constants import ( + CORS_ALLOW_HEADERS, + DEFAULT_ENDPOINT, + logger, +) +from nitrostack.transports.http.env import _env_flag, _env_list +from nitrostack.transports.http.handlers import make_handlers +from nitrostack.transports.http.middleware import ( + ExactEndpointSlashMiddleware, + HeaderCompatMiddleware, + SessionCapMiddleware, +) +from nitrostack.transports.http.tracing import ( + RequestTraceMiddleware, + _enable_trace_logging, +) +from nitrostack.transports.subscriptions import subscriptions_listen_endpoint + +if TYPE_CHECKING: + from nitrostack.core.app import McpApplication + + +def _oauth_is_configured() -> bool: + """True when ``OAuthModule.for_root`` registered an ``OAuthService`` instance.""" + try: + from nitrostack.auth.oauth import OAuthService + + return DIContainer.get_instance().has_value(OAuthService) + except Exception: + return False + + +def build_http_app( + mcp_app: "McpApplication", + *, + endpoint: str = DEFAULT_ENDPOINT, + max_sessions: Optional[int] = None, + session_idle_timeout: Optional[float] = None, + enable_cors: bool = True, + stateless: bool = False, + json_response: bool = False, + protocol_era: ProtocolEra = "auto", + wire_mode: WireMode = "stateless", + http_engine: Optional[HttpEngine] = None, +) -> Starlette: + """ + Build the Starlette app exposing NitroStack's owned low-level server over + Streamable HTTP (`/mcp`), legacy SSE (`/sse` + `/mcp/messages/`), and a + health check (`/mcp/health`). + + Args: + mcp_app: The bootstrapped `McpApplication` whose `mcp_server` (and + registered tools/resources/prompts) this app serves. + endpoint: Streamable HTTP mount path (default `/mcp`). + max_sessions: Optional concurrent-session cap; `None`/`0` disables the cap. + session_idle_timeout: Optional idle timeout in seconds for stateful + sessions (ignored when `stateless=True`). + enable_cors: Whether to add permissive CORS headers (default `True`). + When `False`, DNS-rebinding + protection (Origin/Host validation) is enabled instead, configured + via `MCP_ALLOWED_HOSTS`/`MCP_ALLOWED_ORIGINS` env vars. + stateless: When `True`, every request gets a fresh transport with no + session id and no session tracking (see `StreamableHTTPSessionManager`). + This is the primitive the `2026-07-28` stateless MCP spec needs; + exposed here as a config knob so adopting that spec later doesn't + require touching this wiring again. + json_response: When `True`, a POST carrying a JSON-RPC request is + answered with a plain `application/json` body instead of a + `text/event-stream` SSE frame. The spec allows either, but a client + that doesn't implement SSE parsing for POST responses sees the SSE + form as a stream that ended without a result. Server-initiated + streaming (progress, notifications) is unavailable in this mode. + protocol_era: ``legacy`` / ``modern`` / ``auto``. Distinct from ``stateless``. + wire_mode: Dual-spec policy for 2025 traffic (``sessionful``, ``stateless`` + fallback, or ``reject``). ``auto`` uses ``stateless``; ``modern`` uses + ``reject``. + http_engine: Era factory result. ``sessionless`` for modern/auto, + ``sessionful`` only for legacy. ``auto`` / ``modern`` never start + a sessionful manager, even if ``stateless=False``. + """ + http_engine = resolve_http_engine( + protocol_era, http_engine=http_engine, stateless=stateless + ) + stateless = http_engine == "sessionless" + + server = mcp_app.mcp_server + if server is not None: + server.http_engine = http_engine + server.sessionful = http_engine == "sessionful" + server.protocol_era = protocol_era + + security_settings = None + if not enable_cors: + allowed_hosts = _env_list("MCP_ALLOWED_HOSTS") or ["localhost:*", "127.0.0.1:*"] + allowed_origins = _env_list("MCP_ALLOWED_ORIGINS") + security_settings = TransportSecuritySettings( + enable_dns_rebinding_protection=True, + allowed_hosts=allowed_hosts, + allowed_origins=allowed_origins, + ) + else: + security_settings = TransportSecuritySettings(enable_dns_rebinding_protection=False) + + # Official mcp 2.x owns /mcp (streamable HTTP, both protocol eras). + # One manager only; auto/modern are sessionless and legacy is sessionful. + session_manager = StreamableHTTPSessionManager( + app=mcp_app.mcp_server, + stateless=stateless, + json_response=json_response, + session_idle_timeout=None if stateless else session_idle_timeout, + security_settings=security_settings, + ) + # Trailing slash is required: Starlette's Mount("/mcp/messages") only matches + # "/mcp/messages/" (or deeper), NOT bare "/mcp/messages". Without the slash the + # endpoint event points at a path that falls through to Mount("/mcp") (Streamable + # HTTP), which then 406s SSE clients that don't send Streamable Accept headers. + # Matches the mcp SDK's own SseServerTransport example ("/messages/"). + sse_messages_path = f"{endpoint.rstrip('/')}/messages/" + sse_transport = SseServerTransport(sse_messages_path) + + async def handle_streamable_http(scope: Scope, receive: Receive, send: Send) -> None: + await session_manager.handle_request(scope, receive, send) + + # Wraps only the Streamable HTTP mount, so `/mcp/health` and the legacy SSE + # routes keep their own (correct) content negotiation. +# Line 156 + mcp_asgi_app: ASGIApp = HeaderCompatMiddleware( + handle_streamable_http, + drop_session_headers=stateless, + require_protocol_version=protocol_era == "modern", +) + session_cap: Optional[SessionCapMiddleware] = None + if max_sessions and not stateless: + session_cap = SessionCapMiddleware( + mcp_asgi_app, max_sessions=max_sessions, session_idle_timeout=session_idle_timeout + ) + mcp_asgi_app = session_cap + + async def handle_sse(request): + async with sse_transport.connect_sse(request.scope, request.receive, request._send) as streams: + await mcp_app.mcp_server.run(streams[0], streams[1], mcp_app.mcp_server.create_initialization_options()) + return Response() + + h = make_handlers( + mcp_app, + endpoint=endpoint, + protocol_era=protocol_era, + http_engine=http_engine, + stateless=stateless, + json_response=json_response, + session_cap=session_cap, + ) + + @contextlib.asynccontextmanager + async def lifespan(app): + async with session_manager.run(): + logger.info( + "StreamableHTTP session manager started (stateless=%s, max_sessions=%s, " + "session_idle_timeout=%s)", + stateless, + max_sessions, + session_idle_timeout, + ) + yield + + oauth_stub_routes: List[Route] = [] + if not _oauth_is_configured(): + # Inspector DCR / discovery stubs. Omit when OAuthModule is registered so + # a real protected-resource document is not replaced with "no OAuth". + oauth_stub_routes = [ + Route("/.well-known/oauth-authorization-server", endpoint=h["oauth_not_supported"], methods=["GET", "POST"]), + Route("/.well-known/oauth-protected-resource", endpoint=h["oauth_not_supported"], methods=["GET", "POST"]), + Route("/register", endpoint=h["oauth_not_supported"], methods=["GET", "POST"]), + Route("/oauth/v2/register", endpoint=h["oauth_not_supported"], methods=["GET", "POST"]), + ] + + routes = [ + # More specific paths MUST come before the catch-all `Mount(endpoint, ...)` + # below — Starlette matches routes in order, and a `Mount` matches any + # path under its prefix, so `/mcp/health` would otherwise be swallowed + # by the `/mcp` mount before ever reaching the health route. + Route("/", endpoint=h["root_page"], methods=["GET"]), + Route("/widgets/preview", endpoint=h["widgets_preview"], methods=["GET"]), + Route("/widgets/preview/call", endpoint=h["widgets_preview_call"], methods=["POST"]), + *oauth_stub_routes, + Route("/json/version", endpoint=h["json_version"], methods=["GET"]), + Route("/json/list", endpoint=h["json_list"], methods=["GET"]), + Route("/json", endpoint=h["json_list"], methods=["GET"]), + Route("/favicon.ico", endpoint=h["favicon"], methods=["GET"]), + Route(f"{endpoint}/health", endpoint=h["health_check"], methods=["GET"]), + Mount(sse_messages_path, app=sse_transport.handle_post_message), + # `handle_streamable_http`/`sse_transport.handle_post_message` are raw + # ASGI apps (scope, receive, send), so they must be `Mount`ed rather + # than used as `Route` endpoints (which expect `Request -> Response`). + Mount(endpoint, app=mcp_asgi_app), + Route("/sse", endpoint=handle_sse, methods=["GET"]), + ] + if protocol_era != "legacy": + routes.append( + Route( + SSE_SUBSCRIPTIONS_PATH, + endpoint=subscriptions_listen_endpoint(mcp_app), + methods=["GET", "POST"], + ) + ) + + # Rewrite `/mcp` → `/mcp/` *before* routing so Inspector never sees a 307. + # CORS stays outermost so preflight still works on the original path. + middleware = [ + Middleware(ExactEndpointSlashMiddleware, endpoint=endpoint), + ] + if enable_cors: + expose_headers = list(CORS_EXPOSE_HEADER_NAMES) + if http_engine == "sessionful": + expose_headers.append(LEGACY_SESSION_HEADER) + # Single CORS layer for `/mcp`: the sidecar that used to add a second + # one has been removed (#22), so `MCP_CORS_ALLOWED_ORIGINS` is honored + # here and nowhere else. + allow_origins = list(configured_cors_origins()) or ["*"] + middleware.insert( + 0, + Middleware( + CORSMiddleware, + allow_origins=allow_origins, + allow_methods=["GET", "POST", "DELETE", "OPTIONS"], + # SEP-2243 permits application-defined Mcp-Param-* names. + # Starlette mirrors requested names when '*' is enabled. + allow_headers=[*CORS_ALLOW_HEADERS, "*"], + expose_headers=expose_headers, + ), + ) + + if _env_flag("NITROSTACK_HTTP_DEBUG"): + _enable_trace_logging() + middleware.insert(0, Middleware(RequestTraceMiddleware)) + + app = Starlette(routes=routes, middleware=middleware, lifespan=lifespan) + app.state.protocol_era = protocol_era + app.state.wire_mode = wire_mode + app.state.stateless = stateless + app.state.http_engine = http_engine + app.state.sessionful = http_engine == "sessionful" + app.state.session_manager = session_manager + app.state.streamable_http_manager_count = 1 + app.state.subscription_bus = getattr(mcp_app.mcp_server, "subscription_bus", None) + app.state.protocol_version = protocol_version_for_era(protocol_era) + return app \ No newline at end of file diff --git a/nitrostack/transports/http/constants.py b/nitrostack/transports/http/constants.py new file mode 100644 index 0000000..d93ba42 --- /dev/null +++ b/nitrostack/transports/http/constants.py @@ -0,0 +1,20 @@ +"""Shared constants for the HTTP transport.""" +from __future__ import annotations + +import logging +import time + +from nitrostack.transports.headers import CORS_ALLOW_HEADER_NAMES + +logger = logging.getLogger("nitrostack.transports.http") + +DEFAULT_ENDPOINT = "/mcp" + +# Shared 2026 allow-headers. Session id is exposed only on the sessionful engine. +CORS_ALLOW_HEADERS = list(CORS_ALLOW_HEADER_NAMES) + +# The Accept value `StreamableHTTPServerTransport` requires: it needs +# `application/json` on POST and `text/event-stream` on both POST and GET. +MCP_ACCEPT = "application/json, text/event-stream" + +_PROCESS_START = time.monotonic() \ No newline at end of file diff --git a/nitrostack/transports/http/env.py b/nitrostack/transports/http/env.py new file mode 100644 index 0000000..e205dc1 --- /dev/null +++ b/nitrostack/transports/http/env.py @@ -0,0 +1,16 @@ +"""Environment variable helpers for the HTTP transport.""" +from __future__ import annotations + +import os +from typing import List + + +def _env_list(name: str) -> List[str]: + raw = os.environ.get(name) + if not raw: + return [] + return [item.strip() for item in raw.split(",") if item.strip()] + + +def _env_flag(name: str) -> bool: + return (os.environ.get(name) or "").strip().lower() in {"1", "true", "yes", "on"} \ No newline at end of file diff --git a/nitrostack/transports/http/handlers.py b/nitrostack/transports/http/handlers.py new file mode 100644 index 0000000..45c07ab --- /dev/null +++ b/nitrostack/transports/http/handlers.py @@ -0,0 +1,251 @@ +"""Route handlers: landing page, widget preview, health, discovery stubs.""" +from __future__ import annotations + +import os +import time +from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional + +from pydantic_core import PydanticUndefined +from starlette.responses import HTMLResponse, JSONResponse, Response + +from nitrostack.protocol.version import ProtocolEra, protocol_version_for_era +from nitrostack.transports.http.constants import _PROCESS_START, logger +from nitrostack.transports.landing_page import render_landing_page +from nitrostack.transports.proxy import public_url_for_request +from nitrostack.widgets.preview_page import render_preview_page + +if TYPE_CHECKING: + from nitrostack.core.app import McpApplication + from nitrostack.transports.http.middleware import SessionCapMiddleware + + +def _server_meta(mcp_app: "McpApplication") -> Dict[str, str]: + cfg = getattr(mcp_app, "server_config", None) + return { + "name": getattr(cfg, "name", None) or "NitroStack MCP Server", + "version": getattr(cfg, "version", None) or "1.0.0", + } + + +def _landing_tools(mcp_app: "McpApplication") -> List[Dict[str, Any]]: + tools: List[Dict[str, Any]] = [] + for entry in getattr(mcp_app, "_tools", {}).values(): + try: + schema = mcp_app._tool_input_schema(entry.input_model) + except Exception: + logger.exception("Landing page schema failed for %s", entry.config.name) + schema = None + tools.append( + { + "name": entry.config.name, + "description": entry.config.description or "", + "inputSchema": schema, + } + ) + return tools + + +def _preview_default_arguments(entry: Any) -> Dict[str, Any]: + """Prefill live preview with tool examples (shopId, openNow, …).""" + examples = getattr(getattr(entry, "config", None), "examples", None) + raw = getattr(examples, "input", None) if examples is not None else None + if isinstance(raw, dict): + return dict(raw) + model = getattr(entry, "input_model", None) + if model is None: + return {} + data: Dict[str, Any] = {} + for fname, field in getattr(model, "model_fields", {}).items(): + default = getattr(field, "default", PydanticUndefined) + if default is not PydanticUndefined and default is not None: + data[fname] = default + continue + if fname in ("shopId", "shop_id"): + data[fname] = "tonys-pizza" + elif fname == "product_id": + data[fname] = "sku-1" + elif fname == "filter": + data[fname] = "all" + elif fname == "openNow": + data[fname] = True + elif fname == "origin": + data[fname] = "JFK" + elif fname == "destination": + data[fname] = "LAX" + elif fname in ("departureDate", "departure_date"): + data[fname] = "2026-09-15" + elif fname in ("offerId", "offer_id"): + data[fname] = "off_mock123456" + elif fname in ("orderId", "order_id"): + data[fname] = "ord_mock123456" + elif fname == "query": + data[fname] = "London" + return data + + +def make_handlers( + mcp_app: "McpApplication", + *, + endpoint: str, + protocol_era: ProtocolEra, + http_engine: str, + stateless: bool, + json_response: bool, + session_cap: Optional["SessionCapMiddleware"], +) -> Dict[str, Callable]: + """Build the route handlers. Bodies are unchanged from the original + `build_http_app`; they close over the arguments above.""" + + def _request_public_mcp_url(request) -> str: + port = os.environ.get("PORT") or os.environ.get("MCP_SERVER_PORT") or "3000" + return public_url_for_request( + request, + path=endpoint.rstrip("/") or "/mcp", + fallback_host=f"localhost:{port}", + ) + + async def health_check(request): + return JSONResponse( + { + "status": "ok", + "transport": "streamable-http", + "protocolVersion": protocol_version_for_era(protocol_era), + "protocolEra": protocol_era, + "statelessCapable": http_engine == "sessionless", + "stateless": stateless, + "jsonResponse": json_response, + "sessions": session_cap.active_session_count if session_cap else None, + "uptimeSeconds": round(time.monotonic() - _PROCESS_START, 2), + "publicUrl": _request_public_mcp_url(request), + } + ) + + async def root_page(request): + meta = _server_meta(mcp_app) + return HTMLResponse( + render_landing_page( + name=meta["name"], + version=meta["version"], + description=getattr(getattr(mcp_app, "server_config", None), "description", None), + mcp_endpoint=_request_public_mcp_url(request), + tools=_landing_tools(mcp_app), + ) + ) + + async def oauth_not_supported(request): + """Inspector DCR posts `/register` when Authentication is on. + + Return JSON (not the HTML 404 page) so the client shows a clear + OAuth-off message instead of `Unexpected token '<'`. + """ + connect_url = _request_public_mcp_url(request) + return JSONResponse( + { + "error": "invalid_request", + "error_description": ( + "This MCP server does not use OAuth. In MCP Inspector turn " + "Authentication off, then connect with Streamable HTTP to " + f"{connect_url}." + ), + }, + status_code=404, + ) + + async def widgets_preview(request): + catalog = [] + for name, entry in getattr(mcp_app, "_tools", {}).items(): + component = getattr(entry, "component", None) + if component is None: + continue + catalog.append( + { + "name": name, + "resourceUri": component.resource_uri, + "arguments": _preview_default_arguments(entry), + } + ) + return HTMLResponse(render_preview_page(catalog)) + + async def widgets_preview_call(request): + try: + body = await request.json() + except Exception: + return JSONResponse({"error": "Invalid JSON body"}, status_code=400) + if not isinstance(body, dict): + return JSONResponse({"error": "JSON body must be an object"}, status_code=400) + name = body.get("tool") or "" + arguments = body.get("arguments") or {} + if not isinstance(arguments, dict): + return JSONResponse({"error": "arguments must be an object"}, status_code=400) + entry = getattr(mcp_app, "_tools", {}).get(name) + if entry is None or getattr(entry, "component", None) is None: + return JSONResponse({"error": f"No widget tool named {name!r}"}, status_code=404) + try: + result = await mcp_app._call_tool(name, arguments) + except Exception as exc: + logger.exception("Widget preview tool call failed for %s", name) + return JSONResponse({"error": str(exc)}, status_code=400) + structured = getattr(result, "structured_content", None) + if structured is None: + structured = getattr(result, "structuredContent", None) + try: + html = entry.component.html_with_data(structured) + except Exception as exc: + logger.exception("Widget preview render failed for %s", name) + return JSONResponse( + { + "error": f"Widget render failed: {exc}", + "structuredContent": structured, + "html": None, + "resourceUri": entry.component.resource_uri, + "isError": True, + }, + status_code=400, + ) + return JSONResponse( + { + "structuredContent": structured, + "html": html, + "resourceUri": entry.component.resource_uri, + "isError": bool(getattr(result, "is_error", None) if getattr(result, "is_error", None) is not None else getattr(result, "isError", False)), + } + ) + + async def json_version(request): + """Chrome/Cursor DevTools probe `/json/version` when a tab opens localhost.""" + meta = _server_meta(mcp_app) + health_path = f"{endpoint.rstrip('/')}/health" + return JSONResponse( + { + "Browser": meta["name"], + "Protocol-Version": protocol_version_for_era(protocol_era), + "User-Agent": f"NitroStack/{meta['version']}", + "webSocketDebuggerUrl": "", + "transport": "mcp", + "publicUrl": _request_public_mcp_url(request), + "endpoints": { + "mcp": endpoint, + "sse": "/sse", + "health": health_path, + }, + } + ) + + async def json_list(request): + """Chrome DevTools `/json` and `/json/list` expect a page list; empty = not CDP.""" + return JSONResponse([]) + + async def favicon(request): + return Response(status_code=204) + + return { + "request_public_mcp_url": _request_public_mcp_url, + "health_check": health_check, + "root_page": root_page, + "oauth_not_supported": oauth_not_supported, + "widgets_preview": widgets_preview, + "widgets_preview_call": widgets_preview_call, + "json_version": json_version, + "json_list": json_list, + "favicon": favicon, + } \ No newline at end of file diff --git a/nitrostack/transports/http/middleware.py b/nitrostack/transports/http/middleware.py new file mode 100644 index 0000000..5fbf314 --- /dev/null +++ b/nitrostack/transports/http/middleware.py @@ -0,0 +1,180 @@ +"""ASGI middleware for the HTTP transport.""" +from __future__ import annotations + +import time +from typing import Any, Dict, List, Optional +from starlette.responses import JSONResponse, Response +from starlette.types import ASGIApp, Receive, Scope, Send + +from nitrostack.transports.headers import strip_legacy_session_headers_asgi +from nitrostack.transports.http.constants import MCP_ACCEPT, logger + + +class ExactEndpointSlashMiddleware: + """Internally rewrite `/mcp` -> `/mcp/` so Starlette does not 307.""" + + def __init__(self, app: ASGIApp, endpoint: str) -> None: + self.app = app + self._exact = endpoint.rstrip("/") or "/" + + async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: + if scope["type"] == "http" and scope.get("path") == self._exact: + scope = dict(scope) + scope["path"] = self._exact + "/" + raw = scope.get("raw_path") + if isinstance(raw, (bytes, bytearray)): + scope["raw_path"] = raw.rstrip(b"/") + b"/" + await self.app(scope, receive, send) + + +class HeaderCompatMiddleware: + """Normalize Accept and version headers; JSON-RPC stays with the MCP manager.""" + + def __init__(self, app: ASGIApp, *, drop_session_headers: bool = False, + require_protocol_version: bool = False) -> None: + self.app = app + self.drop_session_headers = drop_session_headers + self.require_protocol_version = require_protocol_version + + @staticmethod + def _normalize_accept(value: Optional[str]) -> Optional[str]: + if value is None or not value.strip(): + return MCP_ACCEPT + media_types = [m.strip() for m in value.split(",")] + has_json = any(m.startswith("application/json") for m in media_types) + has_sse = any(m.startswith("text/event-stream") for m in media_types) + if has_json and has_sse: + return None + if any(m.startswith("*/*") for m in media_types): + return MCP_ACCEPT + return None + + @staticmethod + def _canonicalize_protocol_version(headers: List[Any]) -> List[Any]: + """Normalize casing without hiding duplicates from MCP's validator.""" + version_values: List[bytes] = [] + kept: List[Any] = [] + for key, value in headers: + if key.lower() == b"mcp-protocol-version": + version_values.append(value) + else: + kept.append((key, value)) + if not version_values: + return headers + kept.extend((b"mcp-protocol-version", v) for v in version_values) + return kept + + async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: + if scope["type"] != "http": + await self.app(scope, receive, send) + return + + headers: List[Any] = list(scope.get("headers") or []) + if self.require_protocol_version and scope.get("method") == "POST" and not any( + key.lower() == b"mcp-protocol-version" and value.strip() for key, value in headers + ): + response = JSONResponse( + {"jsonrpc": "2.0", "id": None, "error": { + "code": -32020, "message": "MCP-Protocol-Version header is required", + }}, status_code=400, + ) + await response(scope, receive, send) + return + if self.drop_session_headers: + headers = strip_legacy_session_headers_asgi(headers) + headers = self._canonicalize_protocol_version(headers) + + raw_accept = next((v for k, v in headers if k.lower() == b"accept"), None) + accept = self._normalize_accept(raw_accept.decode("latin-1") if raw_accept is not None else None) + if accept is not None: + headers = [(k, v) for k, v in headers if k.lower() != b"accept"] + headers.append((b"accept", accept.encode("latin-1"))) + logger.debug("Rewrote Accept %r -> %r for %s", raw_accept, accept, scope.get("path")) + + scope = dict(scope) + scope["headers"] = headers + await self.app(scope, receive, send) + + +class SessionCapMiddleware: + """ + Enforce a `max_sessions` concurrent-session cap on the Streamable HTTP + mount, returning a `429` JSON-RPC error once at capacity. + + `StreamableHTTPSessionManager` doesn't expose a public session count or a + session-created/closed hook, so this middleware tracks session ids itself + by observing the `mcp-session-id` request header (existing sessions) and + the `Mcp-Session-Id` response header (newly created sessions), and prunes + entries locally after `session_idle_timeout` so the count self-heals even + if a client disconnects without sending `DELETE`. + """ + + def __init__( + self, + app: ASGIApp, + max_sessions: Optional[int], + session_idle_timeout: Optional[float] = None, + ) -> None: + self.app = app + self.max_sessions = max_sessions + self.session_idle_timeout = session_idle_timeout + self._sessions: Dict[str, float] = {} + + def _prune_stale(self) -> None: + if not self.session_idle_timeout: + return + cutoff = time.monotonic() - self.session_idle_timeout + for sid in [s for s, seen in self._sessions.items() if seen < cutoff]: + self._sessions.pop(sid, None) + + async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: + if scope["type"] != "http" or not self.max_sessions: + await self.app(scope, receive, send) + return + + self._prune_stale() + + headers = dict(scope.get("headers") or []) + raw_session_id = headers.get(b"mcp-session-id") + session_id = raw_session_id.decode() if raw_session_id else None + is_known = session_id is not None and session_id in self._sessions + + if not is_known and len(self._sessions) >= self.max_sessions: + response = JSONResponse( + { + "jsonrpc": "2.0", + "error": { + "code": -32000, + "message": "Too many sessions: server at capacity, retry later", + }, + "id": None, + }, + status_code=429, + ) + await response(scope, receive, send) + return + + if is_known: + self._sessions[session_id] = time.monotonic() + + new_session_id: Dict[str, Optional[str]] = {"value": None} + + async def send_wrapper(message: Any) -> None: + if message["type"] == "http.response.start": + for key, value in message.get("headers", []): + if key.lower() == b"mcp-session-id": + new_session_id["value"] = value.decode() + await send(message) + + await self.app(scope, receive, send_wrapper) + + if new_session_id["value"]: + self._sessions[new_session_id["value"]] = time.monotonic() + + if scope.get("method") == "DELETE" and session_id: + self._sessions.pop(session_id, None) + + @property + def active_session_count(self) -> int: + self._prune_stale() + return len(self._sessions) \ No newline at end of file diff --git a/nitrostack/transports/http/tracing.py b/nitrostack/transports/http/tracing.py new file mode 100644 index 0000000..5d3bf4f --- /dev/null +++ b/nitrostack/transports/http/tracing.py @@ -0,0 +1,97 @@ +"""Opt-in request tracing, enabled with NITROSTACK_HTTP_DEBUG=1.""" +from __future__ import annotations + +import logging +import sys +from typing import Any, Dict + +from starlette.types import ASGIApp, Receive, Scope, Send + +from nitrostack.core.log_emitter import install_log_handler +from nitrostack.transports.http.constants import logger + + +def _enable_trace_logging() -> None: + """ + Give `logger` its own stderr handler so tracing works regardless of how the + host application configured logging. + + `FileLogger` only attaches handlers to the `nitrostack` logger when it is + first instantiated, which for an HTTP server may not happen until a tool + runs. Until then this module's records fall through to `logging`'s + last-resort handler and INFO is discarded. Propagation is disabled so the + traces are not emitted twice once `FileLogger` does attach its handler. + stderr keeps them off stdout, which dual mode uses for JSON-RPC. + """ + install_log_handler("nitrostack.transports.http") + if any(getattr(handler, "_nitrostack_trace", False) for handler in logger.handlers): + return + handler = logging.StreamHandler(sys.stderr) + handler.setFormatter(logging.Formatter("%(asctime)s [%(levelname)s] (%(name)s): %(message)s")) + handler._nitrostack_trace = True # type: ignore[attr-defined] + logger.addHandler(handler) + logger.setLevel(logging.INFO) + logger.propagate = False + + +class RequestTraceMiddleware: + """ + Log the raw request line, headers and body of every HTTP request, plus the + response status and headers. + + Enabled only when `NITROSTACK_HTTP_DEBUG=1`. uvicorn's access log has no + timestamps and no headers, which makes it impossible to tell *why* the + `mcp` SDK rejected a client request (a `406` and a `400` from the SDK are + both header-driven) or even to correlate a failed client connection with a + log line. This middleware is the outermost layer so it sees requests + exactly as the client sent them, before CORS or any path rewriting. + """ + + MAX_BODY_CHARS = 2000 + REDACTED_HEADERS = {"authorization", "proxy-authorization", "cookie", "set-cookie"} + + def __init__(self, app: ASGIApp) -> None: + self.app = app + + @classmethod + def _decode_headers(cls, raw: Any) -> Dict[str, str]: + headers = {} + for key, value in raw or []: + name = key.decode("latin-1") + headers[name] = "" if name.lower() in cls.REDACTED_HEADERS else value.decode("latin-1") + return headers + + async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: + if scope["type"] != "http": + await self.app(scope, receive, send) + return + + method = scope.get("method") + path = scope.get("path") + query = (scope.get("query_string") or b"").decode("latin-1") + target = f"{path}?{query}" if query else path + logger.info("trace >> %s %s headers=%s", method, target, self._decode_headers(scope.get("headers"))) + + async def traced_receive() -> Any: + message = await receive() + if message.get("type") == "http.request": + body = message.get("body") or b"" + if body: + text = body.decode("utf-8", errors="replace") + if len(text) > self.MAX_BODY_CHARS: + text = text[: self.MAX_BODY_CHARS] + "..." + logger.info("trace >> %s %s body=%s", method, target, text) + return message + + async def traced_send(message: Any) -> None: + if message.get("type") == "http.response.start": + logger.info( + "trace << %s %s status=%s headers=%s", + method, + target, + message.get("status"), + self._decode_headers(message.get("headers")), + ) + await send(message) + + await self.app(scope, traced_receive, traced_send) \ No newline at end of file