mcp-oauth-remote-gateway

1#!/usr/bin/env python32"""Diagnose an OAuth-gated remote MCP server's connection state.3 4Decides which recovery branch you're in WITHOUT mutating disk by default:5  1. Smoke-test the stored access_token against the MCP endpoint (initialize).6  2. If 401, attempt a refresh and smoke-test the freshly-minted token.7 8Branches printed at the end:9  TOKEN_OK            -> stored token works; "not connected" is the circuit10                         breaker (SKILL pitfall 7) -> restart the gateway.11  REFRESH_FIXED       -> refresh minted a working token; pass --write to persist12                         it (atomic, 0600), then restart to clear the breaker.13  SESSION_REVOKED     -> refresh succeeds but new token STILL gets -3200214                         "Session expired" (pitfall 10) -> full interactive15                         re-auth required; refresh loop will NOT help.16  REFRESH_DEAD        -> refresh grant itself returns invalid_grant (pitfall 9)17                         -> full interactive re-auth, or switch to a static API key.18 19Usage:20  python3 diagnose-oauth-mcp.py <server_name> [--mcp-url URL] [--token-endpoint URL] [--write]21 22  <server_name> matches the files in $HERMES_HOME/mcp-tokens/<server>.json etc.23  If --mcp-url / --token-endpoint are omitted, they're read from the token's24  `resource` field and the AS .well-known metadata respectively.25 26NEVER prints secret values — only lengths, scope, expiry, and HTTP status.27"""28import json, os, sys, time, argparse, urllib.request, urllib.error, urllib.parse29 30UA = "python-httpx/0.27"  # CF blocks default urllib UA on many providers31 32 33def _hermes_home():34    # Prefer Hermes' own resolver (profile-safe); fall back to env then ~/.hermes.35    try:36        from hermes_constants import get_hermes_home37        return str(get_hermes_home())38    except Exception:39        return os.environ.get("HERMES_HOME") or os.path.expanduser("~/.hermes")40 41 42def _tokens_dir():43    return os.path.join(_hermes_home(), "mcp-tokens")44 45 46def _post(url, data=None, headers=None, form=False, timeout=30):47    if form:48        body = urllib.parse.urlencode(data).encode()49    else:50        body = json.dumps(data).encode() if data is not None else None51    req = urllib.request.Request(url, data=body, method="POST")52    for k, v in (headers or {}).items():53        req.add_header(k, v)54    req.add_header("User-Agent", UA)55    try:56        r = urllib.request.urlopen(req, timeout=timeout)57        return r.status, dict(r.headers), r.read()58    except urllib.error.HTTPError as e:59        return e.code, dict(e.headers), e.read()60 61 62def _get_json(url, timeout=20):63    req = urllib.request.Request(url, headers={"User-Agent": UA})64    return json.loads(urllib.request.urlopen(req, timeout=timeout).read())65 66 67def _mcp_initialize(mcp_url, access_token):68    status, hdrs, body = _post(69        mcp_url,70        data={71            "jsonrpc": "2.0", "id": 1, "method": "initialize",72            "params": {"protocolVersion": "2025-06-18", "capabilities": {},73                       "clientInfo": {"name": "hermes-diag", "version": "1.0"}},74        },75        headers={76            "Authorization": "Bearer " + access_token,77            "Accept": "application/json, text/event-stream",78            "Content-Type": "application/json",79            "MCP-Protocol-Version": "2025-06-18",80        },81    )82    txt = body[:400].decode(errors="replace")83    ok = status == 200 and ("serverInfo" in txt or '"result"' in txt)84    expired = "-32002" in txt or "Session expired" in txt or "invalid_token" in (hdrs.get("WWW-Authenticate") or "")85    return ok, expired, status, txt86 87 88def main():89    ap = argparse.ArgumentParser()90    ap.add_argument("server")91    ap.add_argument("--mcp-url")92    ap.add_argument("--token-endpoint")93    ap.add_argument("--write", action="store_true", help="persist a working refreshed token")94    args = ap.parse_args()95 96    tdir = _tokens_dir()97    tpath = os.path.join(tdir, args.server + ".json")98    cpath = os.path.join(tdir, args.server + ".client.json")99    tok = json.load(open(tpath))100    client = json.load(open(cpath))101 102    mcp_url = args.mcp_url or tok.get("resource")103    if not mcp_url:104        print("FATAL: no --mcp-url and no `resource` in token file"); sys.exit(2)105    resource = tok.get("resource") or mcp_url106 107    print(f"server={args.server} mcp_url={mcp_url}")108    exp = tok.get("expires_at")109    if isinstance(exp, (int, float)):110        print(f"stored expires_at in {round((exp - time.time())/60)} min")111 112    # Step 1: stored token113    ok, expired, status, txt = _mcp_initialize(mcp_url, tok["access_token"])114    print(f"[1] stored-token initialize -> HTTP {status} ok={ok} expired={expired}")115    if ok:116        print("BRANCH=TOKEN_OK  -> stored token works; 'not connected' is the breaker (7). Restart the gateway.")117        return118 119    # Step 2: refresh120    if not tok.get("refresh_token"):121        print("BRANCH=REFRESH_DEAD  -> no refresh_token present; full re-auth required.")122        return123    token_ep = args.token_endpoint124    if not token_ep:125        # derive AS metadata from the host root126        host = urllib.parse.urlsplit(mcp_url)127        as_url = f"{host.scheme}://{host.netloc}/.well-known/oauth-authorization-server"128        try:129            token_ep = _get_json(as_url)["token_endpoint"]130        except Exception as e:131            print(f"FATAL: cannot discover token_endpoint ({e}); pass --token-endpoint"); sys.exit(2)132    print(f"[2] token_endpoint={token_ep}")133 134    rstatus, _rh, rbody = _post(135        token_ep, form=True,136        data={"grant_type": "refresh_token", "refresh_token": tok["refresh_token"],137              "client_id": client["client_id"], "resource": resource},138        headers={"Content-Type": "application/x-www-form-urlencoded"},139    )140    if rstatus != 200:141        print(f"[2] refresh -> HTTP {rstatus} {rbody[:200].decode(errors='replace')}")142        print("BRANCH=REFRESH_DEAD  -> refresh grant rejected (9). Full re-auth or switch to static API key.")143        return144    j = json.loads(rbody)145    new_at = j["access_token"]146    print(f"[2] refresh -> HTTP 200 new_token_len={len(new_at)} scope={j.get('scope')} "147          f"expires_in={j.get('expires_in')} rotated_refresh={bool(j.get('refresh_token'))}")148 149    # Step 2b: smoke-test the freshly-minted token150    ok2, expired2, status2, txt2 = _mcp_initialize(mcp_url, new_at)151    print(f"[2b] new-token initialize -> HTTP {status2} ok={ok2} expired={expired2}")152    if ok2:153        if args.write:154            new = dict(tok)155            new.update({"access_token": new_at, "token_type": j.get("token_type", "Bearer"),156                        "expires_in": j.get("expires_in", tok.get("expires_in")),157                        "scope": j.get("scope", tok.get("scope")),158                        "expires_at": time.time() + float(j.get("expires_in", 3600))})159            if j.get("refresh_token"):160                new["refresh_token"] = j["refresh_token"]161            tmp = tpath + ".tmp"162            open(tmp, "w").write(json.dumps(new, indent=2))163            os.chmod(tmp, 0o600)164            os.replace(tmp, tpath)165            print(f"     wrote {tpath} (0600). NOW RESTART the gateway to clear the breaker.")166        print("BRANCH=REFRESH_FIXED  -> refreshed token works. Persist (--write) + restart gateway.")167        return168 169    if expired2:170        print("BRANCH=SESSION_REVOKED  -> refresh succeeds but new token STILL -32002 'Session expired' (10).")171        print("     Refresh loop will NOT help. Full interactive authorization_code re-auth required.")172        print("     For an unattended gateway, prefer a static Personal API key instead.")173        return174    print(f"BRANCH=UNKNOWN  -> new token failed for a non-session reason: {txt2[:200]}")175 176 177if __name__ == "__main__":178    main()179