refactor(mcp): compact mcp_oauth module docstring, helpers and CIMD constants by hand
- config-key reference folded into the module docstring (all WHY kept) - _park_reserved_socket / _pick_cimd_port / _is_valid_cimd_url / _can_open_browser / _resolve_redirect_uri / token_request_user_agent tightened, same results - _maybe_preregister_client optional keys via dict unpacking
This commit is contained in:
+26
-75
@@ -1,31 +1,18 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
MCP OAuth 2.1 Client Support
|
||||
"""MCP OAuth 2.1 client support: browser authorization-code flow with PKCE.
|
||||
|
||||
Browser-based OAuth 2.1 authorization-code flow with PKCE for MCP servers. The
|
||||
MCP SDK's ``OAuthClientProvider`` (an ``httpx.Auth``) does discovery, client
|
||||
The MCP SDK's ``OAuthClientProvider`` (an ``httpx.Auth``) does discovery, client
|
||||
identification, PKCE, exchange, refresh and step-up; this module supplies
|
||||
``HermesTokenStorage`` (on-disk persistence), the localhost callback listener,
|
||||
and ``build_oauth_auth()`` (legacy entry point). Per the MCP 2026-07-28 spec the
|
||||
client_id is Hermes' published Client ID Metadata Document URL (CIMD) when the
|
||||
server advertises support, else RFC 7591 dynamic client registration (DCR).
|
||||
|
||||
Configuration in config.yaml::
|
||||
|
||||
mcp_servers:
|
||||
my_server:
|
||||
url: "https://mcp.example.com/mcp"
|
||||
auth: oauth
|
||||
oauth: # all fields optional
|
||||
client_id: "pre-registered-id" # skip dynamic registration
|
||||
client_secret: "secret" # confidential clients only
|
||||
scope: "read write" # default: server-provided
|
||||
redirect_port: 0 # 0 = auto-pick free port
|
||||
redirect_uri: "https://proxy/callback" # default: loopback callback
|
||||
redirect_host: "localhost" # loopback hostname (WAF-safe)
|
||||
client_name: "My Custom Client" # default: "Hermes Agent"
|
||||
client_metadata_url: "https://me/cimd.json" # self-hosted CIMD
|
||||
cimd: false # force DCR for this server
|
||||
``mcp_servers.<name>.oauth`` keys (all optional): ``client_id`` (skip DCR),
|
||||
``client_secret`` (confidential clients), ``scope``, ``redirect_port`` (0 =
|
||||
auto), ``redirect_uri`` (proxy callback), ``redirect_host`` (loopback hostname,
|
||||
WAF-safe), ``client_name`` (default "Hermes Agent"), ``client_metadata_url``
|
||||
(self-hosted CIMD), ``cimd: false`` (force DCR), ``user_agent``, ``timeout``.
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
@@ -54,7 +41,9 @@ logger = logging.getLogger(__name__)
|
||||
|
||||
# Lazy SDK imports: availability is detected WITHOUT importing mcp (~170 ms).
|
||||
# Module-level names stay None placeholders so tests can patch.object them;
|
||||
# _ensure_sdk_loaded() binds the real classes on first use.
|
||||
# _ensure_sdk_loaded() binds the real classes on first use. _SDK_CLASSES caches
|
||||
# them so a test that patches a name and restores it to None afterwards doesn't
|
||||
# strand the module in a broken state.
|
||||
_OAUTH_AVAILABLE = _importlib_util.find_spec("mcp") is not None
|
||||
if not _OAUTH_AVAILABLE:
|
||||
logger.debug("MCP OAuth types not available -- OAuth MCP auth disabled")
|
||||
@@ -65,8 +54,6 @@ OAuthClientMetadata: Any = None
|
||||
OAuthMetadata: Any = None
|
||||
OAuthToken: Any = None
|
||||
|
||||
# Cache of the real SDK classes so a test that patches a name and restores it
|
||||
# to None afterwards doesn't strand the module in a broken state.
|
||||
_SDK_CLASSES: dict[str, Any] = {}
|
||||
_SDK_LOAD_FAILED = False
|
||||
|
||||
@@ -123,16 +110,12 @@ _oauth_port: int | None = None
|
||||
# background MCP discovery sets them on the discovery thread while connect+OAuth
|
||||
# runs on the `mcp-event-loop` thread via run_coroutine_threadsafe, which copies
|
||||
# the calling context into the coroutine — a threading.local would not cross.
|
||||
_oauth_interactive_enabled: "contextvars.ContextVar[bool]" = contextvars.ContextVar(
|
||||
"_oauth_interactive_enabled", default=True
|
||||
)
|
||||
_oauth_interactive_enabled = contextvars.ContextVar("_oauth_interactive_enabled", default=True)
|
||||
# Forces _is_interactive() past the stdin-TTY check for GUI-driven flows
|
||||
# (dashboard/desktop REST): the browser + callback server do the work and the
|
||||
# stdin paste fallback degrades harmlessly (EOF swallowed). Suppression wins —
|
||||
# background discovery must never start a browser flow.
|
||||
_oauth_interactive_forced: "contextvars.ContextVar[bool]" = contextvars.ContextVar(
|
||||
"_oauth_interactive_forced", default=False
|
||||
)
|
||||
_oauth_interactive_forced = contextvars.ContextVar("_oauth_interactive_forced", default=False)
|
||||
|
||||
# Skip tokens accepted at the paste prompt — exit OAuth without auth.
|
||||
_SKIP_TOKENS = frozenset({"skip", "cancel", "s", "n", "no", "q", "quit"})
|
||||
@@ -175,11 +158,8 @@ def _park_reserved_socket(port: int, sock: socket.socket) -> None:
|
||||
stale_port = next((p for p in _reserved_sockets if p not in _CIMD_PORTS), None)
|
||||
if stale_port is None:
|
||||
break # only pinned sockets remain — never evict those
|
||||
stale = _reserved_sockets.pop(stale_port, None)
|
||||
if stale is None:
|
||||
continue
|
||||
try:
|
||||
stale.close()
|
||||
_reserved_sockets.pop(stale_port).close()
|
||||
except OSError:
|
||||
pass
|
||||
_reserved_sockets[port] = sock
|
||||
@@ -298,13 +278,8 @@ def _can_open_browser() -> bool:
|
||||
"""True if opening a browser is likely to work."""
|
||||
if os.environ.get("SSH_CLIENT") or os.environ.get("SSH_TTY"):
|
||||
return False # explicit SSH session → no local display
|
||||
if os.name == "nt":
|
||||
if os.name == "nt" or (hasattr(os, "uname") and os.uname().sysname == "Darwin"):
|
||||
return True
|
||||
try:
|
||||
if os.uname().sysname == "Darwin":
|
||||
return True
|
||||
except AttributeError:
|
||||
pass
|
||||
return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
|
||||
|
||||
|
||||
@@ -599,10 +574,7 @@ def _result_taken(result: dict) -> bool:
|
||||
|
||||
|
||||
def _fill_result(result: dict, parsed: dict[str, Any]) -> None:
|
||||
result["auth_code"] = parsed["code"]
|
||||
result["state"] = parsed["state"]
|
||||
result["error"] = parsed["error"]
|
||||
result["iss"] = parsed["iss"]
|
||||
result.update(auth_code=parsed["code"], state=parsed["state"], error=parsed["error"], iss=parsed["iss"])
|
||||
|
||||
|
||||
def _make_callback_handler() -> tuple[type, dict]:
|
||||
@@ -912,17 +884,12 @@ def remove_oauth_tokens(server_name: str, *, hermes_home: str | Path | None = No
|
||||
# deploy. The github.io origin is deliberate: an authorization server MUST NOT
|
||||
# follow HTTP redirects when fetching the document, and
|
||||
# hermes-agent.nousresearch.com/docs/* 301s here.
|
||||
_CIMD_CLIENT_METADATA_URL = (
|
||||
"https://nousresearch.github.io/hermes-agent/docs/oauth/client-metadata.json"
|
||||
)
|
||||
|
||||
# Loopback callback ports declared in that document. The redirect URI must be
|
||||
# an exact string match against a listed one, so a CIMD flow cannot use an
|
||||
# ephemeral port. Below Linux's 32768 ephemeral floor so the kernel never hands
|
||||
# one to another process. Keep in sync with the document
|
||||
_CIMD_CLIENT_METADATA_URL = "https://nousresearch.github.io/hermes-agent/docs/oauth/client-metadata.json"
|
||||
# Loopback callback ports declared in that document (exact string match, so a
|
||||
# CIMD flow cannot use an ephemeral port). Below Linux's 32768 ephemeral floor so
|
||||
# the kernel never hands one to another process. Keep in sync with the document
|
||||
# (tests/tools/test_mcp_cimd.py enforces it).
|
||||
_CIMD_PORTS = (27890, 27891, 27892, 27893, 27894)
|
||||
|
||||
# Loopback hostnames the document lists alongside each port, so the
|
||||
# ``oauth.redirect_host: localhost`` WAF workaround still works under CIMD.
|
||||
_CIMD_REDIRECT_HOSTS = frozenset({"127.0.0.1", "localhost"})
|
||||
@@ -947,9 +914,7 @@ def _is_valid_cimd_url(url: str) -> bool:
|
||||
has_userinfo = bool(parsed.username or parsed.password) # netloc parse can raise
|
||||
except ValueError:
|
||||
return False
|
||||
if has_userinfo or parsed.fragment:
|
||||
return False
|
||||
return not any(seg in {".", ".."} for seg in parsed.path.split("/"))
|
||||
return not (has_userinfo or parsed.fragment or any(seg in {".", ".."} for seg in parsed.path.split("/")))
|
||||
|
||||
|
||||
# Pinned ports this process has committed to, in order taken. A provider is
|
||||
@@ -977,9 +942,7 @@ def _pick_cimd_port() -> int | None:
|
||||
unsupported by the server entirely.
|
||||
"""
|
||||
for port in _CIMD_PORTS:
|
||||
if port in _assigned_cimd_ports:
|
||||
continue
|
||||
if _bind_reserved(port) is not None:
|
||||
if port not in _assigned_cimd_ports and _bind_reserved(port) is not None:
|
||||
_assigned_cimd_ports.append(port)
|
||||
return port
|
||||
return _assigned_cimd_ports[0] if _assigned_cimd_ports else None
|
||||
@@ -1053,9 +1016,7 @@ def token_request_user_agent(cfg: dict) -> str | None:
|
||||
no other headers are configurable (secrets would land in config.yaml).
|
||||
"""
|
||||
ua = cfg.get("user_agent")
|
||||
if isinstance(ua, str) and ua.strip():
|
||||
return ua.strip()
|
||||
return None
|
||||
return ua.strip() if isinstance(ua, str) and ua.strip() else None
|
||||
|
||||
|
||||
def _configure_callback_port(cfg: dict, storage: "HermesTokenStorage | None" = None) -> int:
|
||||
@@ -1100,11 +1061,7 @@ def _resolve_redirect_uri(cfg: dict, port: int) -> str:
|
||||
authorize query, and ``localhost`` works around it. The listener still binds
|
||||
``127.0.0.1``.
|
||||
"""
|
||||
configured = cfg.get("redirect_uri")
|
||||
if configured:
|
||||
return configured
|
||||
host = cfg.get("redirect_host") or "127.0.0.1"
|
||||
return f"http://{host}:{port}/callback"
|
||||
return cfg.get("redirect_uri") or f"http://{cfg.get('redirect_host') or '127.0.0.1'}:{port}/callback"
|
||||
|
||||
|
||||
# Figma's remote MCP implements DCR as a client_name *allowlist*: "Claude Code"
|
||||
@@ -1119,9 +1076,7 @@ def _is_figma_remote_mcp(server_name: str | None = None, server_url: str | None
|
||||
url = (server_url or "").lower()
|
||||
name = (server_name or "").lower()
|
||||
from utils import base_url_host_matches, base_url_hostname
|
||||
if base_url_host_matches(url, "mcp.figma.com") or (
|
||||
base_url_host_matches(url, "figma.com") and "/mcp" in url
|
||||
):
|
||||
if base_url_host_matches(url, "mcp.figma.com") or (base_url_host_matches(url, "figma.com") and "/mcp" in url):
|
||||
return True
|
||||
# Name-only match only when the URL isn't some other host called figma-*.
|
||||
return "figma" in name and (not url or "figma" in base_url_hostname(url))
|
||||
@@ -1156,9 +1111,7 @@ def _build_client_metadata(cfg: dict) -> "OAuthClientMetadata":
|
||||
"""Build OAuthClientMetadata; requires ``_configure_callback_port`` first."""
|
||||
port = cfg.get("_resolved_port")
|
||||
if port is None:
|
||||
raise ValueError(
|
||||
"_configure_callback_port() must be called before _build_client_metadata()"
|
||||
)
|
||||
raise ValueError("_configure_callback_port() must be called before _build_client_metadata()")
|
||||
if OAuthClientMetadata is None:
|
||||
_ensure_sdk_loaded()
|
||||
# Public client by default; confidential only with a known secret or a
|
||||
@@ -1241,10 +1194,8 @@ def _maybe_preregister_client(storage: "HermesTokenStorage", cfg: dict, client_m
|
||||
"grant_types": client_metadata.grant_types,
|
||||
"response_types": client_metadata.response_types,
|
||||
"token_endpoint_auth_method": client_metadata.token_endpoint_auth_method,
|
||||
**{key: cfg[key] for key in ("client_secret", "client_name", "scope") if cfg.get(key)},
|
||||
}
|
||||
for key in ("client_secret", "client_name", "scope"):
|
||||
if cfg.get(key):
|
||||
info_dict[key] = cfg[key]
|
||||
client_info = OAuthClientInformationFull.model_validate(info_dict)
|
||||
_write_json(storage._client_info_path(), client_info.model_dump(mode="json", exclude_none=True))
|
||||
logger.debug("Pre-registered client_id=%s for '%s'", client_id, storage._server_name)
|
||||
|
||||
Reference in New Issue
Block a user