Skip to content

refactor!: execute every tool over MCP tools/call, with session ids and submit_feedback() - #210

Merged
willleeney merged 161 commits into
mainfrom
fix/mcp-submit-feedback
Oct 6, 2026
Merged

willleeney merged 161 commits into
mainfrom
fix/mcp-submit-feedback

Conversation

@willleeney

@willleeney willleeney commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

refactor!: execute every tool over MCP tools/call, with session ids and submit_feedback()
main
Brings the Python SDK to parity with node #383. Every tool call goes over MCP tools/call, and GET /accounts is the only request outside MCP. The migration guide covers every breaking change since 2.10.1, including those from #199.

Changes

MCP-only execution

  • Per-action tools execute over tools/call on the endpoint and account that listed them, with the model's arguments sent unchanged. The server maps them itself.
  • Removed:
    • the /actions/rpc client;
    • the envelope splitting;
    • the base httpx executor;
    • binary download handling and filename cleanup;
    • the param-style=flat_prefixed pin.
  • A tool returns the server's result exactly as the server wrote it: {isError: false, result, defenderMetadata?, policyMetadata?} for action tools, bare JSON for search. isError still raises StackOneAPIError with the status from its payload.
  • A file action returns UCA's single-use download link as result, or raises with status 501 when no link can be issued.
  • tools/call is now sent without the mcp client's extra tools/list. Its output-schema check relisted the whole catalog before every call, and the Node SDK never did that.
  • The transport uses streamable_http_client; the deprecated streamablehttp_client warned on every call.

Header arguments

  • A header argument is an entry of a nested headers object or a top-level headers_<name>. Each is forwarded only if the served schema declares it in the same form. An open headers object (no properties, as *_execute_action serves it) declares every name.
  • Authorization, x-account-id and User-Agent are never forwarded. The warning says whether a header was undeclared or set by the SDK. Every other argument is sent unchanged.
  • As a result, toolset.execute() now forwards host-set headers through the open headers object.

Feedback and sessions

  • stackone_submit_feedback goes over tools/call only, and is listed once however many accounts serve it.
  • submit_feedback() lists one account in search_execute mode and makes one tools/call, through the lowest account id in scope (not the first given, nor GET /accounts order). It takes an optional action_run_id, sent only when given.
  • The search session_id is on every hit, and is forwarded by execute(..., session_id=) and submit_feedback(). A pinned action_id / session_id is moved to the end of the arguments.

Matches Node exactly

  • The served required is emitted verbatim and in the served order, and an empty one is omitted.
  • A tools/call result with only structuredContent is returned instead of coming back as {}.
  • Tools.get_tool() returns the first tool listed under a duplicated name, like Node's getTool().
  • The test mock serves schemas verbatim from a low-level MCP Server. The old one listed properties: {} for every per-action tool.

Also

  • FeedbackRating, FeedbackCategory, FeedbackSource and StackOneMcpTool are exported from stackone_ai. submit_feedback(tool_names=) takes any sequence of strings, but not a bare str.
  • The base StackOneTool no longer requires _api_key.
  • A PR-title check mirrors the Node SDK's.

Review fixes

  • A 429 is retried only when the wait ends before the request's deadline: the MCP exchange's timeout, or the toolset timeout from the first attempt for GET /accounts. Otherwise the 429 is raised at once, so a multi-account call can't time out a throttled account into a partial catalog.
  • An MCP timeout says "timed out after Ns" instead of "RuntimeError: no running event loop".
  • Nested header values are written as Node's headerText writes them (true, 1, compact JSON). Header names are trimmed as JavaScript's trim() trims them.
  • Unusable arguments raise the new ToolArgumentsError, a StackOneError and a ValueError. ToolParameters.required is declared. An account id that is not a string is rejected. An account list fetched across clear_catalog_cache() is discarded. A Retry-After date that overflows falls back to the backoff.

Second review round (decided once with node #383 and sdk-conformance)

  • KeyboardInterrupt and SystemExit propagate out of an MCP request; only Exception becomes a ToolsetLoadError.
  • The langchain extra requires langchain-core>=0.3.36, the first that takes a dict args_schema.
  • A root type that is not a string, such as ["object", "null"], is read as "object", as Node does, instead of "['object', 'null']".
  • A timeout on a request retried after a 429 is that 429 (StackOneAPIError 429, fatal to a multi-account call), on MCP and GET /accounts, worded as Node words it.
  • Non-text content parts (image, audio, resource) are returned under content_parts as plain JSON, so json.dumps and execute_openai_tool_calls() work.
  • Search hits carry the account_id that found them; top_k limits the merged, globally sorted list; the same action on two accounts is two hits.
  • execute() raises ToolsetConfigError when the action's connector is linked on more than one account in scope; a hit's account_id in account_ids routes to it.
  • to_openai(), to_langchain() and to_pydantic_ai() keep the first tool of each name (the lowest account id) and warn once.
  • When some accounts fail to list, the healthy accounts' listings are cached and a failed account is retried only after FAILED_ACCOUNT_RETRY_SECONDS (30). When every account fails, the shared StackOneAPIError is raised if they all have one status, else a ToolsetLoadError raised from an ExceptionGroup of the failures, which it also keeps in .failures.
  • Constructing a toolset with no account while STACKONE_ACCOUNT_ID is set warns that it is ignored.
  • Every GET /accounts (discovery or fetch_accounts()) records the origin_username of each account with shared: false, and every MCP request for that account carries it as x-end-user-id, set after caller headers. Explicit account ids make no GET /accounts. A model-supplied x-end-user-id header argument is dropped as set by the SDK.
  • Tests pin the partial-failure caching, the move of a pinned session_id to the end in execute() and the SDK-owned-name filter on headers= in _prepare_headers; each fails under its mutation.

CI: the conformance pin moves to sdk-conformance ec4dcfb (StackOneHQ/sdk-conformance#5), which grades all of the above, and the conformance job now runs the full suite with the Node SDK (NODE_SDK_REF, refactor/mcp-only-toolset until node #383 merges) beside this one.

Verification

  • 815 tests pass; ruff check, ruff format --check and ty (package and examples) are clean, and uv lock --locked passes. The MIGRATION.md hand-built-tool recipe passes ty and pyright.
  • tests/vectors/ is byte-identical to sdk-conformance 7347926, the pinned commit, and every shared vector case passes.
  • The full conformance suite at 7347926 (pnpm test -- --strict-schema, both SDKs, with Node at c2b8736) passes: 139 checks, and all 68 scenarios give identical results in Python and Node, warnings included. CI runs the same full suite against a pinned Node commit.
  • The override block below was run through release-please 17.11.2's parseConventionalCommits: 45 entries, 23 breaking, each BREAKING CHANGE note on its own entry and none on the others, no junk entries, and next version 3.0.0 from 2.10.1. It covers refactor!: MCP-only toolset with account discovery, search/execute, and hardened security #199's breaking changes too, except the removal of StackOneTool.connector and Tools.get_connectors(), which refactor!: MCP-only toolset with account discovery, search/execute, and hardened security #199's own squash commit already carries as a BREAKING CHANGE footer.

BEGIN_COMMIT_OVERRIDE
refactor: execute every tool over MCP tools/call

BREAKING CHANGE: StackOneRpcTool, MCP_PARAM_STYLE, ParameterLocation, validate_method, is_json_content_type and filename_from_content_disposition are removed. Every tool fetch_tools() returns is a StackOneMcpTool that executes over MCP tools/call on the endpoint and account that listed it, with its arguments sent unchanged; nothing posts to /actions/rpc.

refactor(tools): remove the HTTP executor from the base StackOneTool

BREAKING CHANGE: StackOneTool.execute() no longer makes HTTP requests. On the base class it raises StackOneError, so a hand-built tool must override execute().

refactor(types): reduce ExecuteConfig to name, headers and timeout

BREAKING CHANGE: ExecuteConfig is extra="forbid" and keeps only name, headers and timeout. Passing method, url, body_type or parameter_locations raises a pydantic ValidationError.

refactor(toolset): return every result exactly as the server wrote it

BREAKING CHANGE: StackOneToolSet.execute() and tool.execute() return the server's {isError, result, defenderMetadata?, policyMetadata?} object rather than the unwrapped payload or the /actions/rpc body, so result["data"] becomes result["result"]["data"].

refactor(tools): return a download link from file actions

BREAKING CHANGE: a file action returns {download_url, expires_at, file} as result instead of {content, content_type, status_code, headers, file_name}, and raises StackOneAPIError with status 501 when no link can be issued. Tools.execute_openai_tool_calls() no longer base64-encodes bytes.

refactor(toolset): stop pinning param-style=flat_prefixed on the MCP endpoint

BREAKING CHANGE: the /mcp URL no longer carries ?param-style=flat_prefixed, so per-action tools from fetch_tools() take whichever argument style the server serves by default instead of flat, prefixed keys such as body_variables.

refactor(tools): treat StackOneMcpTool headers as extra headers

BREAKING CHANGE: StackOneMcpTool(headers=...) is now optional and means extra request headers, not the full header set. The SDK always sets Authorization, x-account-id and User-Agent itself, after them.

fix(tools): emit the served required list in served order

BREAKING CHANGE: to_openai_function() no longer derives required from the per-property nullable markers. It emits the served root required list verbatim, in the served order, and omits it when absent or empty, so a hand-built ToolParameters without required now has no required fields.

fix(toolset): route stackone_submit_feedback over MCP and list it once

BREAKING CHANGE: fetch_tools(), openai(), langchain() and pydantic_ai() include the stackone_submit_feedback tool, once, whenever the server serves it.

fix(tools): guard every header argument by its own declaration

BREAKING CHANGE: a top-level headers_<name> argument is dropped unless the tool's schema declares that property, and always for Authorization, x-account-id and User-Agent. A declared flat headers_<name> property no longer admits the same name inside a nested headers object. An open headers object, as *_execute_action serves it, forwards any other header, so StackOneToolSet.execute(..., {"headers": {...}}) passes host-set headers through where it previously dropped them all. A top-level headers argument that isn't a plain object is dropped too, unless the schema declares headers itself as a non-object field, in which case it is an ordinary argument sent as given. A declared flat headers_<name> argument whose value is a list or dict is dropped as well; only a string, number or boolean can be a header value.

fix(tools): return the first listing from get_tool(), as Node does

BREAKING CHANGE: when more than one account serves a tool name, Tools.get_tool() returns the first one listed (listings merge in sorted account order) rather than the last.

build: require Python 3.11 or later

BREAKING CHANGE: Python 3.10 is no longer supported. stackone-ai requires Python 3.11 or later.

build: make mcp a core dependency and remove the mcp extra

BREAKING CHANGE: the stackone-ai[mcp] extra no longer exists. mcp is a core dependency, so install plain stackone-ai.

build: make langchain-core an optional dependency

BREAKING CHANGE: langchain-core is no longer installed with stackone-ai. StackOneTool.to_langchain(), Tools.to_langchain() and StackOneToolSet.langchain() need the stackone-ai[langchain] extra, which requires langchain-core 0.3.36 or later, and raise an ImportError that names it without it.

refactor: split stackone_ai.models into stackone_ai.tools and stackone_ai.types

BREAKING CHANGE: stackone_ai.models, stackone_ai.constants and stackone_ai.utils no longer exist. Import StackOneTool and Tools from stackone_ai.tools; ToolParameters, ExecuteConfig, DEFAULT_BASE_URL and the errors from stackone_ai.types; or any public name from stackone_ai. ToolDefinition and DEFAULT_HYBRID_ALPHA are removed.

refactor(toolset): remove client-side search

BREAKING CHANGE: client-side search is removed: SearchConfig, SearchMode, SearchTool, SemanticSearchClient, SemanticSearchResult, SemanticSearchResponse and SemanticSearchError, the search= constructor argument, search_tools(), search_action_names(), get_search_tool(), semantic_client, the tool_search and tool_execute meta tools, and the bm25s and numpy dependencies. StackOneToolSet.search() runs the server's *_search_actions tools instead.

refactor: remove stackone_ai.integrations

BREAKING CHANGE: stackone_ai.integrations, with to_tool_node(), to_tool_executor(), bind_model_with_tools() and create_react_agent(), is removed. Pass tools.to_langchain() to LangGraph's own ToolNode and bind_tools().

refactor(tools): remove the client-side feedback tool

BREAKING CHANGE: the tool_feedback tool, stackone_ai.feedback, create_feedback_tool() and the implicit feedback_* execution options are removed, and StackOneTool.execute() and call() no longer take options=. Use StackOneToolSet.submit_feedback() and a search hit's session_id instead.

refactor(toolset): run an action by id with execute()

BREAKING CHANGE: StackOneToolSet.execute() takes (action_id, arguments=None, *, account_ids=None, session_id=None) instead of a meta tool name with arguments as a JSON string or dict. arguments must be a dict in the nested form an action's example_request shows, and a failure raises (ToolsetConfigError, ToolArgumentsError, ToolsetLoadError or StackOneAPIError) instead of returning {"error": ...}.

refactor(tools): pass the served schema through to every adapter

BREAKING CHANGE: to_openai_function(), to_langchain() and to_pydantic_ai_tool() give the model the served JSON Schema instead of only type, description, enum and a shallow copy of items and properties, so format, pattern, default, bounds, oneOf/anyOf and nested required reach it. to_langchain() sets that schema as args_schema instead of a pydantic model built from it.

refactor(toolset): remove mode= from openai(), langchain() and pydantic_ai()

BREAKING CHANGE: openai(), langchain() and pydantic_ai() no longer take mode=. Set tool_mode="search_execute" on StackOneToolSet to give a model the server's search and execute tools.

fix(toolset): reject an empty or non-string account id

BREAKING CHANGE: StackOneToolSet(account_id="") raises ToolsetConfigError instead of being treated as no account, which now lists every active account, so an account id read from an environment variable that is set but empty raises. An empty or non-string entry in account_ids, set_accounts() or execute={"account_ids": [...]} raises too, instead of being sent with no x-account-id.

feat(toolset): link calls with session_id and add submit_feedback()

fix(toolset): send feedback once, through the first account

fix(toolset): move a pinned action_id and session_id to the end of the arguments

fix(tools): return structuredContent from a tools/call result with no text

fix(tools): send tools/call without relisting the catalog first

feat: export the feedback types and StackOneMcpTool, and take any sequence of tool names

refactor(tools): make the base StackOneTool's API key optional

feat: retry HTTP 429 on every request, honouring Retry-After, and raise a 429 that outlasts the retries or the timeout instead of skipping the account

feat(tools): raise ToolArgumentsError, a StackOneError and a ValueError, for unusable tool arguments

fix(types): declare ToolParameters.required so a hand-built tool type-checks

fix(tools): write nested header values as Node writes them

fix(tools): report an MCP timeout as a timeout

feat(toolset): read STACKONE_BASE_URL

fix(toolset): accept account ids only as a list

BREAKING CHANGE: account_ids, set_accounts() and execute={"account_ids": ...} accept only a list of strings. A tuple or any other non-list, which 2.10.1 accepted, raises ToolsetConfigError; pass list(ids) instead.

feat(toolset): tag each search hit with its account_id and apply top_k to the merged ranking

fix(toolset): refuse an action whose connector is linked on more than one account

fix(tools): build every adapter from the first tool of each name

fix(toolset): cache the healthy accounts when one fails, and retry a failed one after 30 seconds

fix(toolset): raise the shared error when every account fails, and keep each failure

feat(toolset): add action_run_id to submit_feedback(), and send feedback through the lowest account id

feat(toolset): warn when STACKONE_ACCOUNT_ID is set but ignored

feat(toolset): send x-end-user-id for non-shared accounts

feat(toolset): add a headers option sent on every request

feat(toolset): skip non-shared accounts during discovery unless include_non_shared

fix(toolset): refuse to execute while a matching account failed to list

fix(toolset): look up a non-shared account's end user when the API asks for it

fix(toolset): re-list only the failed accounts that could serve the action in execute()

fix(toolset): learn a failed account's provider with one GET /accounts before execute() refuses

fix(toolset): chain a failed end-user lookup onto the 400 it was looking up for

fix(toolset): raise when every active account on the key is non-shared and not opted in

fix(toolset): name shared accounts in the STACKONE_ACCOUNT_ID warning

fix(tools): keep a retried 429 on record while another request in the exchange is answered

A timeout on a tools/list retried after a 429 is reported as that 429, even when another request in the MCP exchange is answered meanwhile, rather than as a plain timeout that skips the account.

fix(toolset): hold a provider lookup's miss for the failed-account window in execute()

When GET /accounts fails to name a failed account, execute() neither looks it up again nor lists it again early for 30 seconds, and still refuses with the cached failure.
END_COMMIT_OVERRIDE


Summary by cubic

Brings the Python SDK to parity with the Node SDK (#383): every tool now executes over MCP tools/call on the endpoint and account that listed it, with GET /accounts the only non-MCP request. This is the 3.0 release; MIGRATION.md (linked from README, shipped in the sdist) covers every change since 2.10.1.

Behavior changes

  • Tools return the server's result verbatim; a no-text result falls back to structuredContent, non-text parts come back as plain JSON, and isError raises StackOneAPIError. Adapters emit the served required list verbatim and in order.
  • File actions return the download link or raise 501; download filenames are reduced exactly as Node's TextDecoder does. NaN, Infinity, and unencodable arguments raise ToolArgumentsError; JSON integers above 2^53 keep their exact value.
  • tools/call goes through send_request over streamable_http_client, buffering the server's error body on failure; MCP timeouts are reported as timeouts and KeyboardInterrupt/SystemExit propagate. A call never relists the catalog first.
  • Only HTTP 429 is retried (up to three), honoring Retry-After as seconds or a strict RFC 9110 HTTP-date (capped at 30s, else jittered backoff); a retry that would overrun the deadline is skipped and a 429 that outlasts retries aborts the call. Failed accounts retry after 30s; when every account fails, the shared StackOneAPIError is raised if they all share one status, else a ToolsetLoadError raised from an ExceptionGroup kept in .failures. Concurrent fetch_tools()/search() share one in-flight GET /accounts.
  • Header arguments are forwarded only when the schema declares them; Authorization, x-account-id, User-Agent, and x-end-user-id never are. A non-object headers argument is dropped unless the schema declares headers itself as an ordinary field; a flat list/dict header or a self-referential value is refused. A toolset-level headers= option goes on every request; non-shared accounts carry an x-end-user-id.
  • Base URL resolves argument → STACKONE_BASE_URL → default, and a set-but-unused STACKONE_ACCOUNT_ID warns.
  • submit_feedback() is served over tools/call only, in every mode, listed once regardless of how many accounts serve it, and goes through the lowest account id in scope with an optional action_run_id. Search hits carry session_id and account_id; top_k limits the merged ranking; execute(..., session_id=) forwards the hit's session id. An action linked on more than one account raises unless a hit's account_id routes it.
  • New exports: FeedbackRating, FeedbackCategory, FeedbackSource, StackOneMcpTool, ToolArgumentsError. fetch_tools(tool_names=...) accepts any sequence; the langchain extra requires langchain-core>=0.3.36.
  • CI pins sdk-conformance, runs the full suite against this and the Node SDK side by side, vendors shared test vectors byte-for-byte, and adds a PR-title check. The mock serves per-action schemas verbatim from a low-level MCP Server.

Breaking changes

  • Removed StackOneRpcTool, MCP_PARAM_STYLE, ParameterLocation, validate_method, is_json_content_type, and filename_from_content_disposition. StackOneTool.execute() no longer makes HTTP requests; the base class raises StackOneError and _api_key is optional.
  • ExecuteConfig keeps only name, headers, timeout; other fields raise ValidationError. Action results are the server's {isError, result, ...} object; downloads return a link, not bytes.
  • An empty or non-string account id, or a non-list account_ids, raises ToolsetConfigError. A top-level headers_<name> argument is dropped unless declared; with duplicate tool names, get_tool(), to_openai(), to_langchain(), and to_pydantic_ai() return the first listing.
  • Python 3.11 or later is required, and mcp is now a core dependency (the stackone-ai[mcp] extra is gone).

Written for commit 441a0ca. Summary will update on new commits.

Review in cubic Turn on auto-fix

_create_tool picked a transport by tool mode alone, so outside
search_execute the server's global feedback tool was built as an RPC tool
and sent to /actions/rpc, the path that executes connector actions,
instead of the MCP tools/call it was listed from. The server accepts it on
both, but it is served over MCP and is not a connector action, so the SDK
now calls it over tools/call only, in every mode.

The tool is global, not account-scoped, so every account's listing
carries an identical copy. N accounts produced N same-named tools and a
duplicate-name warning about a clash that cannot misroute anything. The
listing now keeps the first copy only; genuine clashes still warn.

The mock serves the tool in both modes (off with MOCK_SUBMIT_FEEDBACK=off,
exposed as the mcp_mock_server_without_feedback fixture), returns a
session_id from *_search_actions, and logs every tools/call and
/actions/rpc request as sent at /__requests, so tests can assert the wire
rather than a handler's zod-parsed view of it.
*_search_actions returns a session_id beside its actions, but search()
merged and re-ranked hits across connectors and dropped it, so there was
no way to tie a later call back to the search that found the action.
Each hit now carries the session_id of the search that produced it
(omitted when the server sent none).

execute() takes session_id= and forwards it as a top-level argument of
the *_execute_action call only when given; an explicit null would fail
the served schema. action_id is still written last, so neither arguments
nor session_id can displace it, and envelope headers are still
allowlisted.

submit_feedback() finds stackone_submit_feedback in the served catalog
(any mode) and calls it over tools/call with snake_case arguments,
omitting unset optionals rather than sending null. It never builds the
tool itself: when the server does not serve it, feedback is not enabled
for the project and it raises ToolsetLoadError saying so.
…erver

The mock registered each per-action tool with McpServer.registerTool, which
expects a Zod shape. Given a plain JSON Schema it listed `properties: {}` with
no `required`, so no test against the mock ever saw a declared parameter:
dummy_action's `foo`, its `required` and `additionalProperties: false` never
reached the SDK. The Zod-shaped feedback and meta tools were unaffected, which
is why the catalog still looked healthy.

Re-vendored the Node SDK's approach: a low-level Server whose tools/list
returns each inputSchema as given. The feedback and meta tool schemas are now
the plain JSON Schemas the real endpoint serves. The 400 on an unscoped
request, 404 on an unknown account, feedback toggle, session_id, echoed_query
and /__requests recording are unchanged. An unknown tool now comes back as
isError, and per-action tools still answer with structuredContent only.
to_openai_function() rebuilt `required` from the per-property `nullable`
markers. Walking the properties re-sorted it into property order, so a model
was shown a `required` the server never sent, and the LangChain and Pydantic
AI adapters, which reuse that schema, inherited it. The Node SDK emits the
served list, so the two SDKs disagreed for the same tool.

`required` now comes from the served root verbatim, in order, with
non-string entries dropped, and is omitted when absent, empty or not a list,
as in Node's toJsonSchema(). tool.parameters is unchanged: the markers stay
for the ADK plugin, and they now skip a non-string entry too, so they cannot
disagree with the emitted list.

A hand-built ToolParameters that relied on the markers alone no longer gets a
`required`; it has to declare one at the root, as a served schema does.
… text

A tools/call result may carry its payload only as structuredContent. The
parser read text parts alone, so such a result came back as `{}`: a success
with the whole payload missing. The Node SDK falls back to structuredContent
when there is no text, and so does this now.

The rest of parse_tool_result() now matches Node's parseToolResult() case for
case. Text wins when both are present. An isError result reads its status and
body from structuredContent when there is no text, and its message is
`Tool "name" failed: <text or compact JSON>` instead of a Python repr. NaN and
Infinity are no longer parsed as JSON, since JSON.parse rejects them and Node
returns that payload as text. The table in TestToolResultParity was generated
from Node's implementation.
The two SDKs disagreed on what a downloaded file may be called:

- `:` was only a separator as a drive letter, so "report.pdf:hidden.exe"
  survived whole. On NTFS that writes an alternate data stream. `:` now
  splits wherever it appears, as `/` and `\` do.
- A name with no dot, an overlong extension or a leading dot was never
  capped, and an extension was counted in characters rather than bytes, so
  multi-byte extensions overshot 255 bytes.
- `filename*=` charsets resolved as Python codec names rather than the labels
  Node's TextDecoder accepts. ISO-8859-1 and ASCII mean windows-1252 there, a
  code page's unassigned 0x80-0x9F byte is its C1 control, and a label Node
  refuses (iso-8859-16) falls back to UTF-8. Each run of escapes is decoded
  on its own, as in Node.
- The parameter grammar used Python's `\s` and Unicode case folding, so
  "fılename=" and a U+001C separator matched here and not there.
- Unicode 15's format characters passed on Python 3.11, and surrogate halves
  rejoined by stripping stayed two characters.

TestDownloadFilenamesAreSafe carries the shared table. Every row is Node's
output for that input, checked against Node's implementation. A differential
fuzz of ~180k inputs found no remaining difference outside CJK charsets,
where Node's ICU converters depart from the Encoding Standard in ways the
stdlib codecs cannot reproduce.
Per-action tools were StackOneRpcTool, posting an envelope to /actions/rpc,
while the meta tools and stackone_submit_feedback went over MCP tools/call.
Every tool the toolset builds is now a StackOneMcpTool and executes over
tools/call on the /mcp endpoint that listed it, with the x-account-id of the
account that listed it. The only non-MCP request left is GET /accounts.

- Arguments are sent verbatim. There is no envelope splitting and no prefix
  routing; the server maps them with its own reverse map. A nested `headers`
  argument is still filtered to the headers the tool's schema declares, now
  read from a flat `headers_*` property or a nested `headers` object, and
  Authorization, x-account-id and User-Agent are refused even when declared.
- The SDK sets User-Agent, Authorization and x-account-id itself, after any
  headers configured on the tool. The account is read at call time, so
  set_account_id() still retargets a tool.
- The /mcp URL no longer pins param-style=flat_prefixed. It existed only so
  the envelope split matched the listed schema. The endpoint is {base}/mcp,
  plus ?tool-mode= when a mode is set.
- A tool returns the server's result exactly as the server wrote it: for an
  action tool, *_execute_action and feedback that is {isError: false,
  result, defenderMetadata?, policyMetadata?}; search results are bare JSON.
  isError still raises. The execute()-only unwrap in the toolset is gone, so
  execute() and tool.execute() return the same shape for the same action.
- A file action returns UCA's download link unchanged. When no link can be
  issued UCA answers isError with status 501, which raises StackOneAPIError.

The mock serves per-action tools the way UCA does: the wrapper as
structuredContent plus the same JSON as text. It adds a files account for
the download link, the 501, defender metadata and a non-object result, and
records each tools/call's query string. /actions/rpc is gone from it.

BREAKING CHANGE: StackOneRpcTool, MCP_PARAM_STYLE, ParameterLocation,
validate_method, is_json_content_type and filename_from_content_disposition
(with its helpers) are removed. StackOneTool.execute() no longer makes HTTP
requests: on the base class it raises StackOneError, so a hand-built tool
must override it. ExecuteConfig keeps only name, headers and timeout, and
refuses method, url, body_type and parameter_locations rather than ignoring
them. Action results are the server's {isError, result, ...} object rather
than the /actions/rpc body. Download actions return a download link, as
`result`, instead of
{content, content_type, status_code, headers, file_name}, and
Tools.execute_openai_tool_calls() no longer base64-encodes bytes.
StackOneMcpTool's `headers` argument is now extra request headers, not the
full header set.
respx intercepted the httpx requests the HTTP and /actions/rpc executors
made. Both are gone, so nothing imports it. Also drops TEST_BASE_URL from
conftest, which existed only for respx routes.
README and CLAUDE.md said per-action tools ran over /actions/rpc with
flat-prefixed arguments, that tools were listed with a param-style pin, and
that downloads returned raw bytes with a sanitised filename. None of that is
true any more.

Both surfaces are now described as tools/call with arguments sent as given.
A fetch_tools() tool takes the keys its served schema names, since the
server picks the param-style. File actions return a download link, and 501
raises. CLAUDE.md also records the result rule and where the unwrap lives.
The mcp client's call_tool validates structuredContent against the
tool's output schema, and to find that schema it sends a tools/list on
any session that has not listed yet. Every call opens a fresh session,
so every tool call relisted the account's whole catalog, which can be
hundreds of tools in individual mode. The Node SDK sends only the
tools/call. The conformance suite caught the difference by comparing
the two SDKs' wire recordings.

The request now goes through the session's public send_request, which
does no output validation. parse_tool_result handles the result the
same way as before.
StackOneHQ/sdk-conformance#5 grades execution over tools/call, forbids /actions/rpc (invariant 13) and grades results as the server wrote them. The previous pin still graded /actions/rpc envelopes, which this SDK no longer sends.
Copilot AI balanced review requested due to automatic review settings September 29, 2026 15:56

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 17 files

Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic

Comment thread stackone_ai/tools.py Resolved
Comment thread CLAUDE.md Resolved
Comment thread tests/mocks/mcp-server.ts Resolved
Comment thread README.md Resolved
Comment thread tests/test_feedback.py Resolved
A header argument is an entry of a nested `headers` object or a top-level
`headers_<name>`. Each is forwarded only if the served schema declares it in
the same form: `headers.properties.<name>` (an open `headers` object with no
`properties` declares every name) or the `headers_<name>` property.
Authorization, x-account-id and User-Agent are never forwarded, and the
warning now says which of the two reasons applied. Every other argument is
sent unchanged.

Top-level `headers_<name>` arguments used to go through unchecked, so a
flat `headers_x-account-id` reached the server.

BREAKING CHANGE: a top-level `headers_<name>` argument is dropped unless the tool's schema declares that property, and always for Authorization, x-account-id and User-Agent. A declared flat `headers_<name>` property no longer admits the same name inside a nested `headers` object. An open `headers` object, as `*_execute_action` serves it, now forwards any header other than those three, so `StackOneToolSet.execute(..., {"headers": {...}})` passes host-set headers through where it previously dropped them all.
submit_feedback() listed the catalog of every scoped account in the
toolset's mode, which in individual mode means one tool per action per
account, only to find one global tool. It now lists a single account in
search_execute mode (the server serves the feedback tool in every mode)
and makes one tools/call with that account's x-account-id: the first of
account_ids as given, else the toolset's own, else the first active
account in GET /accounts order. Previously the account was the first in
sorted order, not the first the caller named.
When two accounts serve the same tool name, Tools.get_tool() kept the
last one listed; Node's getTool() finds the first. The duplicate-name
warning now says the first one is returned.

BREAKING CHANGE: when more than one account serves a tool name, Tools.get_tool() returns the first one listed (listings merge in sorted account order) rather than the last. Pass account_ids to choose explicitly.
CLAUDE.md still described the removed _unwrap_success() and a result unwrap that no longer happens, and a comment about the nullable marker had been left above McpToolDefinition, which has nothing to do with it.
…uence of tool names

submit_feedback() is typed with FeedbackRating, FeedbackCategory and FeedbackSource, and every tool fetch_tools() returns is a StackOneMcpTool, but none of them could be imported from the package root. tool_names now accepts any Sequence[str]; a bare str is still refused.
…e arguments

A model-supplied action_id or session_id kept its original position when execute() overwrote it, so the pinned key was not last in key order. Remove each before setting it, as the Node SDK does.
The base class cannot execute, so it has nothing to authenticate, yet its constructor required _api_key. It is now optional and still accepted, so existing hand-built tools and overrides that read it keep working. _prepare_headers(), its only reader, moves to StackOneMcpTool, whose constructor still requires the key.
streamablehttp_client is deprecated and warned on every listing and call. Its replacement takes an httpx client instead of headers and timeouts, so the transport builds one with the same settings the mcp package's own factory uses, and the caller's timeout on every leg. Both functions are identical in every mcp release the pin allows.
release-please builds the changelog and version bump from the squashed PR title, so a non-conventional title silently drops the change from both. Mirrors the Node SDK's check-title workflow.
Covers every breaking change since 2.10.1 with before/after code: the removals in #199 (client-side search, SearchConfig and the semantic client, stackone_ai.integrations, the feedback tool, the mcp extra, Python 3.10) and those in this branch (MCP-only execution, the result shape, download links, ExecuteConfig, the header rule, get_tool() duplicates, the served required list and the served feedback tool). Linked from the README and shipped in the sdist.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 20 files

Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic

Comment thread README.md Resolved
Comment thread MIGRATION.md Resolved
Comment thread MIGRATION.md Resolved
Comment thread tests/test_fetch_tools.py Resolved
Comment thread stackone_ai/tools.py Resolved
Comment thread stackone_ai/tools.py Resolved
Comment thread stackone_ai/toolset.py Resolved
Comment thread .github/workflows/check-title.yaml Resolved
Comment thread CLAUDE.md Resolved
Comment thread CLAUDE.md Resolved
… its value as given

Matches Node: a headers_<name> argument is a top-level property, so it is declared
only under its own key, and like every other top-level argument its value reaches
tools/call unchanged rather than stringified.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 3 files (changes from recent commits).

Requires human review: Auto-approval blocked by 13 unresolved issues from previous reviews.

Re-trigger cubic

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 3 files (changes from recent commits).

Requires human review: Auto-approval blocked by 3 unresolved issues from previous reviews.

Re-trigger cubic

@StuBehan StuBehan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-ran against e70161e (only vectors and pins since) and everything from last round checks out, broke each fix again and the tests caught every one, and the timings match node now. Two small test ones below, and the provider-lookup miss on node #383 applies here too.

toolset.fetch_tools(mode="search_execute")
assert listing.listed == []

def test_an_account_that_fails_during_the_call_is_not_listed_again_in_it(self, monkeypatch, clock):

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one doesn't stub GET /accounts, so the provider lookup goes out to the real api.stackone.com and only passes because prod 401s key "k". Same for _connector_account_unavailable in test_shared_vectors.py. Could they stub it (or block non-localhost in conftest so it can't happen again)?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stubbed in d6739a9 (that test) and a8b825c (the _connector_account_unavailable vector). a8b825c also adds an autouse conftest fixture that refuses any socket connection beyond loopback, naming the host, and fails the test even if the code swallows the refusal; tests/test_no_network.py proves it with httpx.get("https://api.stackone.com/accounts"). Those two were the only tests it caught.

Comment thread tests/test_shared_vectors.py Outdated
"stackone_ai.toolset.fetch_mcp_tools",
_failing_for({"acc-2"}, ToolsetLoadError("boom"), "linear_{account}_execute_action"),
)
# Explicit ids: no GET /accounts, so acc-2's provider is unknown and it blocks.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment's been stale since 084322b, the provider lookup does a GET /accounts now (and it goes to prod, see the other comment).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in aefa3cd: the comment now says execute() makes one GET /accounts to learn acc-2's provider, and acc-2 blocks because that answer (stubbed since a8b825c) does not list it.

Comment thread stackone_ai/toolset.py
try:
self._join_accounts_listing()
except Exception as exc:
if is_rate_limited(exc):

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a test for this? Swallowing the 429 here still passes all 851, though it does the right thing when I tried it. Node swallows it at the same spot (toolsets.ts:1186) so maybe worth pinning in conformance too?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pinned in 044153c: test_a_rate_limited_lookup_is_raised has a failed account of unknown provider with explicit ids and GET /accounts answering 429 every time, and expects execute() to raise StackOneAPIError 429. It fails with the re-raise swapped for a swallow.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 4 files (changes from recent commits).

Requires human review: Breaking 3.0 refactor moves every call onto MCP tools/call and adds x-end-user-id capture, caller-header forwarding, and new account-failure semantics; public-contract, privacy, and operational tradeoffs still need human sign-off.

Re-trigger cubic

@willleeney

Copy link
Copy Markdown
Contributor Author

Done for Stu's comment on stackone-ai-node#383 (StackOneHQ/stackone-ai-node#383 (comment)), which said Python was the same, in 8ed9cc7. When the provider lookup fails to name a failed account (GET /accounts fails with anything but a 429, or does not list it), the miss is recorded, and for FAILED_ACCOUNT_RETRY_SECONDS execute() neither looks that account up again nor lists it again early. It still refuses with connector-account-unavailable using the cached failure, and clear_catalog_cache() forgets the miss. test_a_lookup_that_misses_waits_out_the_failure_window makes three calls with one GET /accounts and acc2 listed once between them, then checks both happen again once 30s have passed.

… and drop one across a clear

The call whose GET /accounts missed an account still listed it again, as did concurrent calls sharing that lookup; and a clear_catalog_cache() during the lookup was undone by the miss written after it. As in Node.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 7 files (changes from recent commits).

Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic

Comment thread tests/test_no_network.py Resolved
Whether the guard sees the hostname or a resolved IP depends on the connect path, and a configured proxy would be the host refused instead; the test now bypasses proxies and asserts the refusal itself.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 1 file (changes from recent commits).

Requires human review: The delta refines account-retry and test tooling but keeps the breaking 3.0 MCP-only contract, caller-header/end-user-id forwarding, and account-routing changes; those public-contract, privacy, and operational tradeoffs are decisive.

Re-trigger cubic

@StuBehan StuBehan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-ran against 9a35e2e and all three from last round check out, the loopback guard caught everything I threw at it (raw sockets, async httpx, the mcp client) and a full run made no non-loopback lookups at all. The lookup-miss port matches node call for call. One tiny test gap below, otherwise good to go.

Comment thread stackone_ai/toolset.py
return {
account
for account in account_ids
if account not in self._providers

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is what forgets a miss once GET /accounts names the account, and it works, but nothing tests it, keeping a named account held out still passes all 860. Node has "forgets the miss once GET /accounts names the account" for the same thing, worth a matching one here?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added in 441a0ca: test_a_miss_is_forgotten_once_get_accounts_names_the_account, matching Node's. Dropping the not in self._providers check fails it.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 1 file (changes from recent commits).

Requires human review: Breaking 3.0 refactor sends every tool call through MCP tools/call, removes /actions/rpc and client-side search, and changes result, header, account, session, and feedback behavior. The public-contract, privacy, and operational tradeoffs need human sign-off.

Turn on auto-fix | Re-trigger cubic

@willleeney
willleeney merged commit 049abf5 into main Oct 6, 2026
@willleeney
willleeney deleted the fix/mcp-submit-feedback branch October 6, 2026 12:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants