common/hermes
2
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

fix(mcp): consolidate OAuth handling, pick up external token refreshes (#11383)

Browse Source 
* feat(mcp-oauth): scaffold MCPOAuthManager

Central manager for per-server MCP OAuth state. Provides
get_or_build_provider (cached), remove (evicts cache + deletes
disk), invalidate_if_disk_changed (mtime watch, core fix for
external-refresh workflow), and handle_401 (dedup'd recovery).

No behavior change yet — existing call sites still use
build_oauth_auth directly. Task 1 of 8 in the MCP OAuth
consolidation (fixes Cthulhu's BetterStack reliability issues).

* feat(mcp-oauth): add HermesMCPOAuthProvider with pre-flow disk watch

Subclasses the MCP SDK's OAuthClientProvider to inject a disk
mtime check before every async_auth_flow, via the central
manager. When a subclass instance is used, external token
refreshes (cron, another CLI instance) are picked up before
the next API call.

Still dead code: the manager's _build_provider still delegates
to build_oauth_auth and returns the plain OAuthClientProvider.
Task 4 wires this subclass in. Task 2 of 8.

* refactor(mcp-oauth): extract build_oauth_auth helpers

Decomposes build_oauth_auth into _configure_callback_port,
_build_client_metadata, _maybe_preregister_client, and
_parse_base_url. Public API preserved. These helpers let
MCPOAuthManager._build_provider reuse the same logic in Task 4
instead of duplicating the construction dance.

Also updates the SDK version hint in the warning from 1.10.0 to
1.26.0 (which is what we actually require for the OAuth types
used here). Task 3 of 8.

* feat(mcp-oauth): manager now builds HermesMCPOAuthProvider directly

_build_provider constructs the disk-watching subclass using the
helpers from Task 3, instead of delegating to the plain
build_oauth_auth factory. Any consumer using the manager now gets
pre-flow disk-freshness checks automatically.

build_oauth_auth is preserved as the public API for backwards
compatibility. The code path is now:

    MCPOAuthManager.get_or_build_provider  ->
      _build_provider  ->
        _configure_callback_port
        _build_client_metadata
        _maybe_preregister_client
        _parse_base_url
        HermesMCPOAuthProvider(...)

Task 4 of 8.

* feat(mcp): wire OAuth manager + add _reconnect_event

MCPServerTask gains _reconnect_event alongside _shutdown_event.
When set, _run_http / _run_stdio exit their async-with blocks
cleanly (no exception), and the outer run() loop re-enters the
transport to rebuild the MCP session with fresh credentials.
This is the recovery path for OAuth failures that the SDK's
in-place httpx.Auth cannot handle (e.g. cron externally consumed
the refresh_token, or server-side session invalidation).

_run_http now asks MCPOAuthManager for the OAuth provider
instead of calling build_oauth_auth directly. Config-time,
runtime, and reconnect paths all share one provider instance
with pre-flow disk-watch active.

shutdown() defensively sets both events so there is no race
between reconnect and shutdown signalling.

Task 5 of 8.

* feat(mcp): detect auth failures in tool handlers, trigger reconnect

All 5 MCP tool handlers (tool call, list_resources, read_resource,
list_prompts, get_prompt) now detect auth failures and route
through MCPOAuthManager.handle_401:

  1. If the manager says recovery is viable (disk has fresh tokens,
     or SDK can refresh in-place), signal MCPServerTask._reconnect_event
     to tear down and rebuild the MCP session with fresh credentials,
     then retry the tool call once.

  2. If no recovery path exists, return a structured needs_reauth
     JSON error so the model stops hallucinating manual refresh
     attempts (the 'let me curl the token endpoint' loop Cthulhu
     pasted from Discord).

_is_auth_error catches OAuthFlowError, OAuthTokenError,
OAuthNonInteractiveError, and httpx.HTTPStatusError(401). Non-auth
exceptions still surface via the generic error path unchanged.

Task 6 of 8.

* feat(mcp-cli): route add/remove through manager, add 'hermes mcp login'

cmd_mcp_add and cmd_mcp_remove now go through MCPOAuthManager
instead of calling build_oauth_auth / remove_oauth_tokens
directly. This means CLI config-time state and runtime MCP
session state are backed by the same provider cache — removing
a server evicts the live provider, adding a server populates
the same cache the MCP session will read from.

New 'hermes mcp login <name>' command:
  - Wipes both the on-disk tokens file and the in-memory
    MCPOAuthManager cache
  - Triggers a fresh OAuth browser flow via the existing probe
    path
  - Intended target for the needs_reauth error Task 6 returns
    to the model

Task 7 of 8.

* test(mcp-oauth): end-to-end integration tests

Five new tests exercising the full consolidation with real file
I/O and real imports (no transport mocks):

  1. external_refresh_picked_up_without_restart — Cthulhu's cron
     workflow. External process writes fresh tokens to disk;
     on the next auth flow the manager's mtime-watch flips
     _initialized and the SDK re-reads from storage.

  2. handle_401_deduplicates_concurrent_callers — 10 concurrent
     handlers for the same failed token fire exactly ONE recovery
     attempt (thundering-herd protection).

  3. handle_401_returns_false_when_no_provider — defensive path
     for unknown servers.

  4. invalidate_if_disk_changed_handles_missing_file — pre-auth
     state returns False cleanly.

  5. provider_is_reused_across_reconnects — cache stickiness so
     reconnects preserve the disk-watch baseline mtime.

Task 8 of 8 — consolidation complete.
This commit is contained in:
Teknium
2026-04-16 21:57:10 -07:00
committed by GitHub
parent 436a7359cd
commit 70768665a4
11 changed files with 1566 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
tests/hermes_cli/test_mcp_config.py
View File

@@ -539,3 +539,64 @@ class TestDispatcher:
mcp_command(_make_args(mcp_action=None))
out = capsys.readouterr().out
assert "Commands:" in out or "No MCP servers" in out
# ---------------------------------------------------------------------------
# Tests: Task 7 consolidation — cmd_mcp_remove evicts manager cache,
# cmd_mcp_login forces re-auth
# ---------------------------------------------------------------------------
class TestMcpRemoveEvictsManager:
def test_remove_evicts_in_memory_provider(self, tmp_path, capsys, monkeypatch):
"""After cmd_mcp_remove, the MCPOAuthManager no longer caches the provider."""
_seed_config(tmp_path, {
"oauth-srv": {"url": "https://example.com/mcp", "auth": "oauth"},
})
monkeypatch.setattr("builtins.input", lambda _: "y")
monkeypatch.setattr(
"hermes_cli.mcp_config.get_hermes_home", lambda: tmp_path
)
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
from tools.mcp_oauth_manager import get_manager, reset_manager_for_tests
reset_manager_for_tests()
mgr = get_manager()
mgr.get_or_build_provider(
"oauth-srv", "https://example.com/mcp", None,
)
assert "oauth-srv" in mgr._entries
from hermes_cli.mcp_config import cmd_mcp_remove
cmd_mcp_remove(_make_args(name="oauth-srv"))
assert "oauth-srv" not in mgr._entries
class TestMcpLogin:
def test_login_rejects_unknown_server(self, tmp_path, capsys):
_seed_config(tmp_path, {})
from hermes_cli.mcp_config import cmd_mcp_login
cmd_mcp_login(_make_args(name="ghost"))
out = capsys.readouterr().out
assert "not found" in out
def test_login_rejects_non_oauth_server(self, tmp_path, capsys):
_seed_config(tmp_path, {
"srv": {"url": "https://example.com/mcp", "auth": "header"},
})
from hermes_cli.mcp_config import cmd_mcp_login
cmd_mcp_login(_make_args(name="srv"))
out = capsys.readouterr().out
assert "not configured for OAuth" in out
def test_login_rejects_stdio_server(self, tmp_path, capsys):
_seed_config(tmp_path, {
"srv": {"command": "npx", "args": ["some-server"]},
})
from hermes_cli.mcp_config import cmd_mcp_login
cmd_mcp_login(_make_args(name="srv"))
out = capsys.readouterr().out
assert "no URL" in out or "not an OAuth" in out

68
tests/tools/test_mcp_oauth.py
View File

@@ -431,3 +431,71 @@ class TestBuildOAuthAuthNonInteractive:
assert auth is not None
assert "no cached tokens found" not in caplog.text.lower()
# ---------------------------------------------------------------------------
# Extracted helper tests (Task 3 of MCP OAuth consolidation)
# ---------------------------------------------------------------------------
def test_build_client_metadata_basic():
"""_build_client_metadata returns metadata with expected defaults."""
from tools.mcp_oauth import _build_client_metadata, _configure_callback_port
cfg = {"client_name": "Test Client"}
_configure_callback_port(cfg)
md = _build_client_metadata(cfg)
assert md.client_name == "Test Client"
assert "authorization_code" in md.grant_types
assert "refresh_token" in md.grant_types
def test_build_client_metadata_without_secret_is_public():
"""Without client_secret, token endpoint auth is 'none' (public client)."""
from tools.mcp_oauth import _build_client_metadata, _configure_callback_port
cfg = {}
_configure_callback_port(cfg)
md = _build_client_metadata(cfg)
assert md.token_endpoint_auth_method == "none"
def test_build_client_metadata_with_secret_is_confidential():
"""With client_secret, token endpoint auth is 'client_secret_post'."""
from tools.mcp_oauth import _build_client_metadata, _configure_callback_port
cfg = {"client_secret": "shh"}
_configure_callback_port(cfg)
md = _build_client_metadata(cfg)
assert md.token_endpoint_auth_method == "client_secret_post"
def test_configure_callback_port_picks_free_port():
"""_configure_callback_port(0) picks a free port in the ephemeral range."""
from tools.mcp_oauth import _configure_callback_port
cfg = {"redirect_port": 0}
port = _configure_callback_port(cfg)
assert 1024 < port < 65536
assert cfg["_resolved_port"] == port
def test_configure_callback_port_uses_explicit_port():
"""An explicit redirect_port is preserved."""
from tools.mcp_oauth import _configure_callback_port
cfg = {"redirect_port": 54321}
port = _configure_callback_port(cfg)
assert port == 54321
assert cfg["_resolved_port"] == 54321
def test_parse_base_url_strips_path():
"""_parse_base_url drops path components for OAuth discovery."""
from tools.mcp_oauth import _parse_base_url
assert _parse_base_url("https://example.com/mcp/v1") == "https://example.com"
assert _parse_base_url("https://example.com") == "https://example.com"
assert _parse_base_url("https://host.example.com:8080/api") == "https://host.example.com:8080"

193
tests/tools/test_mcp_oauth_integration.py Normal file
View File

@@ -0,0 +1,193 @@
"""End-to-end integration tests for the MCP OAuth consolidation.
Exercises the full chain — manager, provider subclass, disk watch, 401
dedup — with real file I/O and real imports (no transport mocks, no
subprocesses). These are the tests that would catch Cthulhu's original
BetterStack bug: an external process rewrites the tokens file on disk,
and the running Hermes session picks up the new tokens on the next auth
flow without requiring a restart.
"""
import asyncio
import json
import os
import time
import pytest
pytest.importorskip("mcp.client.auth.oauth2", reason="MCP SDK 1.26.0+ required")
@pytest.mark.asyncio
async def test_external_refresh_picked_up_without_restart(tmp_path, monkeypatch):
"""Simulate Cthulhu's cron workflow end-to-end.
1. A running Hermes session has OAuth tokens loaded in memory.
2. An external process (cron) writes fresh tokens to disk.
3. On the next auth flow, the manager's disk-watch invalidates the
in-memory state so the SDK re-reads from storage.
4. ``provider.context.current_tokens`` now reflects the new tokens
with no process restart required.
"""
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
from tools.mcp_oauth_manager import MCPOAuthManager, reset_manager_for_tests
reset_manager_for_tests()
token_dir = tmp_path / "mcp-tokens"
token_dir.mkdir(parents=True)
tokens_file = token_dir / "srv.json"
client_info_file = token_dir / "srv.client.json"
# Pre-seed the baseline state: valid tokens the session loaded at startup.
tokens_file.write_text(json.dumps({
"access_token": "OLD_ACCESS",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "OLD_REFRESH",
}))
client_info_file.write_text(json.dumps({
"client_id": "test-client",
"redirect_uris": ["http://127.0.0.1:12345/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"token_endpoint_auth_method": "none",
}))
mgr = MCPOAuthManager()
provider = mgr.get_or_build_provider(
"srv", "https://example.com/mcp", None,
)
assert provider is not None
# The SDK's _initialize reads tokens from storage into memory. This
# is what happens on the first http request under normal operation.
await provider._initialize()
assert provider.context.current_tokens.access_token == "OLD_ACCESS"
# Now record the baseline mtime in the manager (this happens
# automatically via the HermesMCPOAuthProvider.async_auth_flow
# pre-hook on the first real request, but we exercise it directly
# here for test determinism).
await mgr.invalidate_if_disk_changed("srv")
# EXTERNAL PROCESS: cron rewrites the tokens file with fresh creds.
# The old refresh_token has been consumed by this external exchange.
future_mtime = time.time() + 1
tokens_file.write_text(json.dumps({
"access_token": "NEW_ACCESS",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "NEW_REFRESH",
}))
os.utime(tokens_file, (future_mtime, future_mtime))
# The next auth flow should detect the mtime change and reload.
changed = await mgr.invalidate_if_disk_changed("srv")
assert changed, "manager must detect the disk mtime change"
assert provider._initialized is False, "_initialized must flip so SDK re-reads storage"
# Simulate the next async_auth_flow: _initialize runs because _initialized=False.
await provider._initialize()
assert provider.context.current_tokens.access_token == "NEW_ACCESS"
assert provider.context.current_tokens.refresh_token == "NEW_REFRESH"
@pytest.mark.asyncio
async def test_handle_401_deduplicates_concurrent_callers(tmp_path, monkeypatch):
"""Ten concurrent 401 handlers for the same token should fire one recovery.
Mirrors Claude Code's pending401Handlers dedup pattern — prevents N MCP
tool calls hitting 401 simultaneously from all independently clearing
caches and re-reading the keychain (which thrashes the storage and
bogs down startup per CC-1096).
"""
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
from tools.mcp_oauth_manager import MCPOAuthManager, reset_manager_for_tests
reset_manager_for_tests()
token_dir = tmp_path / "mcp-tokens"
token_dir.mkdir(parents=True)
(token_dir / "srv.json").write_text(json.dumps({
"access_token": "TOK",
"token_type": "Bearer",
"expires_in": 3600,
}))
mgr = MCPOAuthManager()
provider = mgr.get_or_build_provider(
"srv", "https://example.com/mcp", None,
)
assert provider is not None
# Count how many times invalidate_if_disk_changed is called — proxy for
# how many actual recovery attempts fire.
call_count = 0
real_invalidate = mgr.invalidate_if_disk_changed
async def counting(name):
nonlocal call_count
call_count += 1
return await real_invalidate(name)
monkeypatch.setattr(mgr, "invalidate_if_disk_changed", counting)
# Fire 10 concurrent handlers with the same failed token.
results = await asyncio.gather(*(
mgr.handle_401("srv", "SAME_FAILED_TOKEN") for _ in range(10)
))
# All callers get the same result (the shared future's resolution).
assert all(r == results[0] for r in results), "dedup must return identical result"
# Exactly ONE recovery ran — the rest awaited the same pending future.
assert call_count == 1, f"expected 1 recovery attempt, got {call_count}"
@pytest.mark.asyncio
async def test_handle_401_returns_false_when_no_provider(tmp_path, monkeypatch):
"""handle_401 for an unknown server returns False cleanly."""
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
from tools.mcp_oauth_manager import MCPOAuthManager, reset_manager_for_tests
reset_manager_for_tests()
mgr = MCPOAuthManager()
result = await mgr.handle_401("nonexistent", "any_token")
assert result is False
@pytest.mark.asyncio
async def test_invalidate_if_disk_changed_handles_missing_file(tmp_path, monkeypatch):
"""invalidate_if_disk_changed returns False when tokens file doesn't exist."""
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
from tools.mcp_oauth_manager import MCPOAuthManager, reset_manager_for_tests
reset_manager_for_tests()
mgr = MCPOAuthManager()
mgr.get_or_build_provider("srv", "https://example.com/mcp", None)
# No tokens file exists yet — this is the pre-auth state
result = await mgr.invalidate_if_disk_changed("srv")
assert result is False
@pytest.mark.asyncio
async def test_provider_is_reused_across_reconnects(tmp_path, monkeypatch):
"""The manager caches providers; multiple reconnects reuse the same instance.
This is what makes the disk-watch stick across reconnects: tearing down
the MCP session and rebuilding it (Task 5's _reconnect_event path) must
not create a new provider, otherwise ``last_mtime_ns`` resets and the
first post-reconnect auth flow would spuriously "detect" a change.
"""
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
from tools.mcp_oauth_manager import MCPOAuthManager, reset_manager_for_tests
reset_manager_for_tests()
mgr = MCPOAuthManager()
p1 = mgr.get_or_build_provider("srv", "https://example.com/mcp", None)
# Simulate a reconnect: _run_http calls get_or_build_provider again
p2 = mgr.get_or_build_provider("srv", "https://example.com/mcp", None)
assert p1 is p2, "manager must cache the provider across reconnects"

141
tests/tools/test_mcp_oauth_manager.py Normal file
View File

@@ -0,0 +1,141 @@
"""Tests for the MCP OAuth manager (tools/mcp_oauth_manager.py).
The manager consolidates the eight scattered MCP-OAuth call sites into a
single object with disk-mtime watch, dedup'd 401 handling, and a provider
cache. See `tools/mcp_oauth_manager.py` for design rationale.
"""
import json
import os
import time
import pytest
pytest.importorskip(
"mcp.client.auth.oauth2",
reason="MCP SDK 1.26.0+ required for OAuth support",
)
def test_manager_is_singleton():
"""get_manager() returns the same instance across calls."""
from tools.mcp_oauth_manager import get_manager, reset_manager_for_tests
reset_manager_for_tests()
m1 = get_manager()
m2 = get_manager()
assert m1 is m2
def test_manager_get_or_build_provider_caches(tmp_path, monkeypatch):
"""Calling get_or_build_provider twice with same name returns same provider."""
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
from tools.mcp_oauth_manager import MCPOAuthManager
mgr = MCPOAuthManager()
p1 = mgr.get_or_build_provider("srv", "https://example.com/mcp", None)
p2 = mgr.get_or_build_provider("srv", "https://example.com/mcp", None)
assert p1 is p2
def test_manager_get_or_build_rebuilds_on_url_change(tmp_path, monkeypatch):
"""Changing the URL discards the cached provider."""
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
from tools.mcp_oauth_manager import MCPOAuthManager
mgr = MCPOAuthManager()
p1 = mgr.get_or_build_provider("srv", "https://a.example.com/mcp", None)
p2 = mgr.get_or_build_provider("srv", "https://b.example.com/mcp", None)
assert p1 is not p2
def test_manager_remove_evicts_cache(tmp_path, monkeypatch):
"""remove(name) evicts the provider from cache AND deletes disk files."""
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
from tools.mcp_oauth_manager import MCPOAuthManager
# Pre-seed tokens on disk
token_dir = tmp_path / "mcp-tokens"
token_dir.mkdir(parents=True)
(token_dir / "srv.json").write_text(json.dumps({
"access_token": "TOK",
"token_type": "Bearer",
}))
mgr = MCPOAuthManager()
p1 = mgr.get_or_build_provider("srv", "https://example.com/mcp", None)
assert p1 is not None
assert (token_dir / "srv.json").exists()
mgr.remove("srv")
assert not (token_dir / "srv.json").exists()
p2 = mgr.get_or_build_provider("srv", "https://example.com/mcp", None)
assert p1 is not p2
def test_hermes_provider_subclass_exists():
"""HermesMCPOAuthProvider is defined and subclasses OAuthClientProvider."""
from tools.mcp_oauth_manager import _HERMES_PROVIDER_CLS
from mcp.client.auth.oauth2 import OAuthClientProvider
assert _HERMES_PROVIDER_CLS is not None
assert issubclass(_HERMES_PROVIDER_CLS, OAuthClientProvider)
@pytest.mark.asyncio
async def test_disk_watch_invalidates_on_mtime_change(tmp_path, monkeypatch):
"""When the tokens file mtime changes, provider._initialized flips False.
This is the behaviour Claude Code ships as
invalidateOAuthCacheIfDiskChanged (CC-1096 / GH#24317) and is the core
fix for Cthulhu's external-cron refresh workflow.
"""
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
from tools.mcp_oauth_manager import MCPOAuthManager, reset_manager_for_tests
reset_manager_for_tests()
token_dir = tmp_path / "mcp-tokens"
token_dir.mkdir(parents=True)
tokens_file = token_dir / "srv.json"
tokens_file.write_text(json.dumps({
"access_token": "OLD",
"token_type": "Bearer",
}))
mgr = MCPOAuthManager()
provider = mgr.get_or_build_provider("srv", "https://example.com/mcp", None)
assert provider is not None
# First call: records mtime (zero -> real) -> returns True
changed1 = await mgr.invalidate_if_disk_changed("srv")
assert changed1 is True
# No file change -> False
changed2 = await mgr.invalidate_if_disk_changed("srv")
assert changed2 is False
# Touch file with a newer mtime
future_mtime = time.time() + 10
os.utime(tokens_file, (future_mtime, future_mtime))
changed3 = await mgr.invalidate_if_disk_changed("srv")
assert changed3 is True
# _initialized flipped — next async_auth_flow will re-read from disk
assert provider._initialized is False
def test_manager_builds_hermes_provider_subclass(tmp_path, monkeypatch):
"""get_or_build_provider returns HermesMCPOAuthProvider, not plain OAuthClientProvider."""
from tools.mcp_oauth_manager import (
MCPOAuthManager, _HERMES_PROVIDER_CLS, reset_manager_for_tests,
)
reset_manager_for_tests()
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
mgr = MCPOAuthManager()
provider = mgr.get_or_build_provider("srv", "https://example.com/mcp", None)
assert _HERMES_PROVIDER_CLS is not None
assert isinstance(provider, _HERMES_PROVIDER_CLS)
assert provider._hermes_server_name == "srv"

57
tests/tools/test_mcp_reconnect_signal.py Normal file
View File

@@ -0,0 +1,57 @@
"""Tests for the MCPServerTask reconnect signal.
When the OAuth layer cannot recover in-place (e.g., external refresh of a
single-use refresh_token made the SDK's in-memory refresh fail), the tool
handler signals MCPServerTask to tear down the current MCP session and
reconnect with fresh credentials. This file exercises the signal plumbing
in isolation from the full stdio/http transport machinery.
"""
import asyncio
import pytest
@pytest.mark.asyncio
async def test_reconnect_event_attribute_exists():
"""MCPServerTask has a _reconnect_event alongside _shutdown_event."""
from tools.mcp_tool import MCPServerTask
task = MCPServerTask("test")
assert hasattr(task, "_reconnect_event")
assert isinstance(task._reconnect_event, asyncio.Event)
assert not task._reconnect_event.is_set()
@pytest.mark.asyncio
async def test_wait_for_lifecycle_event_returns_reconnect():
"""When _reconnect_event fires, helper returns 'reconnect' and clears it."""
from tools.mcp_tool import MCPServerTask
task = MCPServerTask("test")
task._reconnect_event.set()
reason = await task._wait_for_lifecycle_event()
assert reason == "reconnect"
# Should have cleared so the next cycle starts fresh
assert not task._reconnect_event.is_set()
@pytest.mark.asyncio
async def test_wait_for_lifecycle_event_returns_shutdown():
"""When _shutdown_event fires, helper returns 'shutdown'."""
from tools.mcp_tool import MCPServerTask
task = MCPServerTask("test")
task._shutdown_event.set()
reason = await task._wait_for_lifecycle_event()
assert reason == "shutdown"
@pytest.mark.asyncio
async def test_wait_for_lifecycle_event_shutdown_wins_when_both_set():
"""If both events are set simultaneously, shutdown takes precedence."""
from tools.mcp_tool import MCPServerTask
task = MCPServerTask("test")
task._shutdown_event.set()
task._reconnect_event.set()
reason = await task._wait_for_lifecycle_event()
assert reason == "shutdown"

139
tests/tools/test_mcp_tool_401_handling.py Normal file
View File

@@ -0,0 +1,139 @@
"""Tests for MCP tool-handler auth-failure detection.
When a tool call raises UnauthorizedError / OAuthNonInteractiveError /
httpx.HTTPStatusError(401), the handler should:
1. Ask MCPOAuthManager.handle_401 if recovery is viable.
2. If yes, trigger MCPServerTask._reconnect_event and retry once.
3. If no, return a structured needs_reauth error so the model stops
hallucinating manual refresh attempts.
"""
import json
from unittest.mock import MagicMock
import pytest
pytest.importorskip("mcp.client.auth.oauth2")
def test_is_auth_error_detects_oauth_flow_error():
from tools.mcp_tool import _is_auth_error
from mcp.client.auth import OAuthFlowError
assert _is_auth_error(OAuthFlowError("expired")) is True
def test_is_auth_error_detects_oauth_non_interactive():
from tools.mcp_tool import _is_auth_error
from tools.mcp_oauth import OAuthNonInteractiveError
assert _is_auth_error(OAuthNonInteractiveError("no browser")) is True
def test_is_auth_error_detects_httpx_401():
from tools.mcp_tool import _is_auth_error
import httpx
response = MagicMock()
response.status_code = 401
exc = httpx.HTTPStatusError("unauth", request=MagicMock(), response=response)
assert _is_auth_error(exc) is True
def test_is_auth_error_rejects_httpx_500():
from tools.mcp_tool import _is_auth_error
import httpx
response = MagicMock()
response.status_code = 500
exc = httpx.HTTPStatusError("oops", request=MagicMock(), response=response)
assert _is_auth_error(exc) is False
def test_is_auth_error_rejects_generic_exception():
from tools.mcp_tool import _is_auth_error
assert _is_auth_error(ValueError("not auth")) is False
assert _is_auth_error(RuntimeError("not auth")) is False
def test_call_tool_handler_returns_needs_reauth_on_unrecoverable_401(monkeypatch, tmp_path):
"""When session.call_tool raises 401 and handle_401 returns False,
handler returns a structured needs_reauth error (not a generic failure)."""
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
from tools.mcp_tool import _make_tool_handler
from tools.mcp_oauth_manager import get_manager, reset_manager_for_tests
from mcp.client.auth import OAuthFlowError
reset_manager_for_tests()
# Stub server
server = MagicMock()
server.name = "srv"
session = MagicMock()
async def _call_tool_raises(*a, **kw):
raise OAuthFlowError("token expired")
session.call_tool = _call_tool_raises
server.session = session
server._reconnect_event = MagicMock()
server._ready = MagicMock()
server._ready.is_set.return_value = True
from tools import mcp_tool
mcp_tool._servers["srv"] = server
mcp_tool._server_error_counts.pop("srv", None)
# Ensure the MCP loop exists (run_on_mcp_loop needs it)
mcp_tool._ensure_mcp_loop()
# Force handle_401 to return False (no recovery available)
mgr = get_manager()
async def _h401(name, token=None):
return False
monkeypatch.setattr(mgr, "handle_401", _h401)
try:
handler = _make_tool_handler("srv", "tool1", 10.0)
result = handler({"arg": "v"})
parsed = json.loads(result)
assert parsed.get("needs_reauth") is True, f"expected needs_reauth, got: {parsed}"
assert parsed.get("server") == "srv"
assert "re-auth" in parsed.get("error", "").lower() or "reauth" in parsed.get("error", "").lower()
finally:
mcp_tool._servers.pop("srv", None)
mcp_tool._server_error_counts.pop("srv", None)
def test_call_tool_handler_non_auth_error_still_generic(monkeypatch, tmp_path):
"""Non-auth exceptions still surface via the generic error path, not needs_reauth."""
monkeypatch.setenv("HERMES_HOME", str(tmp_path))
from tools.mcp_tool import _make_tool_handler
server = MagicMock()
server.name = "srv"
session = MagicMock()
async def _raises(*a, **kw):
raise RuntimeError("unrelated")
session.call_tool = _raises
server.session = session
from tools import mcp_tool
mcp_tool._servers["srv"] = server
mcp_tool._server_error_counts.pop("srv", None)
mcp_tool._ensure_mcp_loop()
try:
handler = _make_tool_handler("srv", "tool1", 10.0)
result = handler({"arg": "v"})
parsed = json.loads(result)
assert "needs_reauth" not in parsed
assert "MCP call failed" in parsed.get("error", "")
finally:
mcp_tool._servers.pop("srv", None)
mcp_tool._server_error_counts.pop("srv", None)