From 3b8576fc9d7db471ae14a92c7d5730b71ef7fd35 Mon Sep 17 00:00:00 2001 From: S2D2 Date: Tue, 10 Nov 2026 20:51:15 +0000 Subject: [PATCH 1/4] refactor: share the MCP session and end-user retry plumbing fetch_mcp_tools and call_mcp_tool each opened the transport, built a ClientSession, initialized it under the same deadline and mapped failures through _raise_mcp_failure. That now lives in one _run_mcp_session helper, import guard included; each function keeps only its own exchange. The retry-once-with-the-looked-up-end-user logic was written three times (per-account listing, search/execute listing, tool execution). It is now retry_for_end_user, with the same rules: only a 400 naming an account that was sent without an end user, and only if the lookup finds one. No behaviour change. Co-Authored-By: Claude Opus 5.5 Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com> --- stackone_ai/tools.py | 175 ++++++++++++++++++++--------------------- stackone_ai/toolset.py | 24 ++---- 2 files changed, 95 insertions(+), 104 deletions(-) diff --git a/stackone_ai/tools.py b/stackone_ai/tools.py index 486b6aa..4fccfe2 100644 --- a/stackone_ai/tools.py +++ b/stackone_ai/tools.py @@ -658,66 +658,81 @@ async def _mcp_transport( yield streams -def fetch_mcp_tools( - endpoint: str, headers: dict[str, str], *, timeout: float = 60.0 -) -> list[McpToolDefinition]: - """List every tool the MCP endpoint serves, following pagination. - - ``timeout`` bounds the whole exchange, handshake included. +def _run_mcp_session( + endpoint: str, + headers: dict[str, str], + timeout: float, + work: Callable[[Any], Coroutine[Any, Any, T]], +) -> T: + """Open an initialized MCP session to ``endpoint``, run ``work`` on it and close it. + + ``timeout`` bounds the whole exchange, handshake included. Any failure is raised + through :func:`_raise_mcp_failure`. """ try: from mcp import types as mcp_types # ty: ignore[unresolved-import] from mcp.client.session import ClientSession # ty: ignore[unresolved-import] - except ImportError as exc: # pragma: no cover - depends on optional extra + except ImportError as exc: # pragma: no cover - only a broken install gets here raise ToolsetConfigError( "mcp is a core dependency of stackone-ai but could not be imported — reinstall the package." ) from exc throttle = _Throttle() - async def _list() -> list[McpToolDefinition]: + async def _run() -> T: with anyio.fail_after(timeout): - return await _list_within_deadline() - - async def _list_within_deadline() -> list[McpToolDefinition]: - async with _mcp_transport(endpoint, headers, timeout, throttle) as ( - read_stream, - write_stream, - _, - ): - session = ClientSession( + async with _mcp_transport(endpoint, headers, timeout, throttle) as ( read_stream, write_stream, - client_info=mcp_types.Implementation(name="stackone-ai-python", version=_SDK_VERSION), - ) - async with session: - await session.initialize() - cursor: str | None = None - collected: list[McpToolDefinition] = [] - while True: - result = await session.list_tools(cursor) - for tool in result.tools: - input_schema = tool.inputSchema or {} - collected.append( - McpToolDefinition( - name=tool.name, - description=tool.description, - input_schema=dict(input_schema), - ) - ) - cursor = result.nextCursor - if cursor is None: - break - return collected + _, + ): + session = ClientSession( + read_stream, + write_stream, + client_info=mcp_types.Implementation(name="stackone-ai-python", version=_SDK_VERSION), + ) + async with session: + await session.initialize() + return await work(session) try: - return run_async(_list()) + return run_async(_run()) except Exception as exc: # Exception, not BaseException: Ctrl-C and SystemExit must stop the caller, not come # back as a ToolsetLoadError that an agent framework hands the model as a tool result. _raise_mcp_failure(exc, endpoint, timeout, throttle) +def fetch_mcp_tools( + endpoint: str, headers: dict[str, str], *, timeout: float = 60.0 +) -> list[McpToolDefinition]: + """List every tool the MCP endpoint serves, following pagination. + + ``timeout`` bounds the whole exchange, handshake included. + """ + + async def _list(session: Any) -> list[McpToolDefinition]: + cursor: str | None = None + collected: list[McpToolDefinition] = [] + while True: + result = await session.list_tools(cursor) + for tool in result.tools: + input_schema = tool.inputSchema or {} + collected.append( + McpToolDefinition( + name=tool.name, + description=tool.description, + input_schema=dict(input_schema), + ) + ) + cursor = result.nextCursor + if cursor is None: + break + return collected + + return _run_mcp_session(endpoint, headers, timeout, _list) + + def _response_body(response: httpx.Response) -> str: """Best-effort read of an error body. @@ -937,44 +952,21 @@ def call_mcp_tool( ``arguments`` are sent exactly as given; the server maps them onto the action. """ from mcp import types as mcp_types # ty: ignore[unresolved-import] - from mcp.client.session import ClientSession # ty: ignore[unresolved-import] - - throttle = _Throttle() - async def _call() -> JsonDict: - with anyio.fail_after(timeout): - return await _call_within_deadline() - - async def _call_within_deadline() -> JsonDict: - async with _mcp_transport(endpoint, headers, timeout, throttle) as ( - read_stream, - write_stream, - _, - ): - session = ClientSession( - read_stream, - write_stream, - client_info=mcp_types.Implementation(name="stackone-ai-python", version=_SDK_VERSION), + async def _call(session: Any) -> JsonDict: + # send_request rather than call_tool: call_tool validates structuredContent + # against the tool's output schema, and on a fresh session that means a + # tools/list first — relisting the whole catalog on every call, which the + # Node SDK never does. The result is parsed below either way. + request = mcp_types.ClientRequest( + mcp_types.CallToolRequest( + params=mcp_types.CallToolRequestParams(name=name, arguments=arguments), ) - async with session: - await session.initialize() - # send_request rather than call_tool: call_tool validates structuredContent - # against the tool's output schema, and on a fresh session that means a - # tools/list first — relisting the whole catalog on every call, which the - # Node SDK never does. The result is parsed below either way. - request = mcp_types.ClientRequest( - mcp_types.CallToolRequest( - params=mcp_types.CallToolRequestParams(name=name, arguments=arguments), - ) - ) - result = await session.send_request(request, mcp_types.CallToolResult) - return parse_tool_result(result, name) + ) + result = await session.send_request(request, mcp_types.CallToolResult) + return parse_tool_result(result, name) - try: - return run_async(_call()) - except Exception as exc: - # Not BaseException, as in fetch_mcp_tools: KeyboardInterrupt and SystemExit propagate. - _raise_mcp_failure(exc, endpoint, timeout, throttle) + return _run_mcp_session(endpoint, headers, timeout, _call) def is_end_user_refusal(exc: BaseException, account_id: str) -> bool: @@ -1001,6 +993,21 @@ def is_end_user_refusal(exc: BaseException, account_id: str) -> bool: return message.rstrip().rsplit(" ", 1)[-1].strip("\"'") == account_id +def retry_for_end_user( + call: Callable[[], T], accounts: Iterable[str], look_up: Callable[[str, Exception], bool] | None +) -> T: + """``call()``, made once more if the API refused it for want of the end user of one of + ``accounts`` (those it was sent without one for) and ``look_up`` then finds that end user. + """ + try: + return call() + except StackOneAPIError as exc: + refused = next((account for account in accounts if is_end_user_refusal(exc, account)), None) + if refused is None or look_up is None or not look_up(refused, exc): + raise + return call() + + def _strip_internal_keys(schema: Any) -> Any: """Recursively drop the SDK's internal markers from a property schema. @@ -1495,21 +1502,13 @@ def call() -> JsonDict: self._endpoint, self._prepare_headers(), self._served_name, parsed, timeout=timeout ) + # Sent with no recorded end user and refused for want of one: the account is + # non-shared and its end user can be looked up. Retried once, with it. account_id = self._account_id - without_end_user = account_id is not None and self._recorded_end_user_id() is None - try: - return call() - except StackOneAPIError as exc: - # Sent with no recorded end user and refused for want of one: the account is - # non-shared and its end user can be looked up. Retried once, with it. - if not ( - without_end_user - and account_id is not None - and self._look_up_end_user is not None - and self._look_up_end_user(account_id, exc) - ): - raise - return call() + without_end_user = ( + [account_id] if account_id is not None and self._recorded_end_user_id() is None else [] + ) + return retry_for_end_user(call, without_end_user, self._look_up_end_user) @dataclass(frozen=True) diff --git a/stackone_ai/toolset.py b/stackone_ai/toolset.py index 0780659..011c22a 100644 --- a/stackone_ai/toolset.py +++ b/stackone_ai/toolset.py @@ -35,6 +35,7 @@ is_end_user_refusal, is_rate_limited, is_sdk_owned_header, + retry_for_end_user, ) from stackone_ai.types import ( DEFAULT_BASE_URL, @@ -497,15 +498,12 @@ def _catalog( def _fetch_for_account( account: str | None, ) -> list[_Listing]: - without_end_user = account is not None and self._end_user_id(account) is None - try: - listed = fetch_mcp_tools(endpoint, self._build_mcp_headers(account), timeout=self._timeout) - except StackOneAPIError as exc: - # Refused for want of an end user it was sent without: look it up, and retry - # once with it. - if not (without_end_user and account is not None and self._look_up_end_user(account, exc)): - raise - listed = fetch_mcp_tools(endpoint, self._build_mcp_headers(account), timeout=self._timeout) + without_end_user = [account] if account is not None and self._end_user_id(account) is None else [] + listed = retry_for_end_user( + lambda: fetch_mcp_tools(endpoint, self._build_mcp_headers(account), timeout=self._timeout), + without_end_user, + self._look_up_end_user, + ) return [(tool_def, account, endpoint) for tool_def in listed] def _store(catalog: _Catalog) -> None: @@ -582,13 +580,7 @@ def _list() -> list[_Listing]: return [(tool_def, None, endpoint) for tool_def in listed] without_end_user = [account for account in account_scope if self._end_user_id(account) is None] - try: - listings = _list() - except StackOneAPIError as exc: - refused = next((a for a in without_end_user if is_end_user_refusal(exc, a)), None) - if refused is None or not self._look_up_end_user(refused, exc): - raise - listings = _list() + listings = retry_for_end_user(_list, without_end_user, self._look_up_end_user) with self._cache_lock: if generation == self._cache_generation: From 9b559417d454bb40e2bb1775ea41bc3a1abac486 Mon Sep 17 00:00:00 2001 From: S2D2 Date: Wed, 11 Nov 2026 00:34:25 +0000 Subject: [PATCH 2/4] refactor: drop the comment retry_for_end_user's docstring now states The retry condition is documented once, on retry_for_end_user, as the toolset callers already rely on; the copy above the tool's call site restated it. Co-Authored-By: Claude Opus 5.5 Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com> --- stackone_ai/tools.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/stackone_ai/tools.py b/stackone_ai/tools.py index 4fccfe2..2e88b1b 100644 --- a/stackone_ai/tools.py +++ b/stackone_ai/tools.py @@ -1502,8 +1502,6 @@ def call() -> JsonDict: self._endpoint, self._prepare_headers(), self._served_name, parsed, timeout=timeout ) - # Sent with no recorded end user and refused for want of one: the account is - # non-shared and its end user can be looked up. Retried once, with it. account_id = self._account_id without_end_user = ( [account_id] if account_id is not None and self._recorded_end_user_id() is None else [] From e53d02b6c3311bc77e786891735e97275b80f2b0 Mon Sep 17 00:00:00 2001 From: S2D2 Date: Wed, 11 Nov 2026 00:46:32 +0000 Subject: [PATCH 3/4] refactor: check the end-user refusal in one place retry_for_end_user already checks is_end_user_refusal before it calls the look-up, and every caller goes through it, so the look-up's own check was a second copy that could drift. Co-Authored-By: Claude Opus 5.5 Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com> --- stackone_ai/toolset.py | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/stackone_ai/toolset.py b/stackone_ai/toolset.py index 011c22a..2542ac3 100644 --- a/stackone_ai/toolset.py +++ b/stackone_ai/toolset.py @@ -32,7 +32,6 @@ _json_type, build_request_headers, fetch_mcp_tools, - is_end_user_refusal, is_rate_limited, is_sdk_owned_header, retry_for_end_user, @@ -1007,13 +1006,10 @@ def _look_up_end_user(self, account_id: str, refusal: Exception) -> bool: """Given the API's refusal of an account's request for want of its end user, list the accounts and say whether that one now has an end user recorded to retry with. - Only the API's 400 naming this account counts. A GET /accounts already in flight is - joined rather than another made. If it fails, the refusal is raised with that failure - as its cause: a key without the scope to list accounts would otherwise be told only - that the header does not match. + A GET /accounts already in flight is joined rather than another made. If it fails, the + refusal is raised with that failure as its cause: a key without the scope to list + accounts would otherwise be told only that the header does not match. """ - if not is_end_user_refusal(refusal, account_id): - return False try: self._join_accounts_listing() except Exception as exc: From 2494d18f40f79cb8488bc3862525bacf02aa4086 Mon Sep 17 00:00:00 2001 From: S2D2 Date: Wed, 11 Nov 2026 11:46:38 +0000 Subject: [PATCH 4/4] test: assert list_tools pagination params The pagination test only counted calls, so a regression to the old positional cursor argument would still pass. Assert the first call sends params=None and the second carries the next cursor. Co-Authored-By: Claude Opus 5.5 Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com> --- tests/test_fetch_tools.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/test_fetch_tools.py b/tests/test_fetch_tools.py index e849270..fd59adc 100644 --- a/tests/test_fetch_tools.py +++ b/tests/test_fetch_tools.py @@ -690,7 +690,9 @@ async def mock_streamable_client(endpoint, **_kwargs: object): assert result[0].name == "tool_1" assert result[1].name == "tool_2" assert result[1].input_schema == {} # None should become empty dict - assert mock_session.list_tools.call_count == 2 + first_call, second_call = mock_session.list_tools.call_args_list + assert first_call.kwargs == {"params": None} + assert second_call.kwargs["params"].cursor == "cursor_page_2" class TestCatalogCache: