Repository navigation
refactor!: execute every tool over MCP tools/call, with session ids and submit_feedback() - #210
Conversation
_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.
There was a problem hiding this comment.
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
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.
There was a problem hiding this comment.
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
… 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.
There was a problem hiding this comment.
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
…not closed by additionalProperties
There was a problem hiding this comment.
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
left a comment
There was a problem hiding this comment.
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): |
There was a problem hiding this comment.
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)?
There was a problem hiding this comment.
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.
| "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. |
There was a problem hiding this comment.
This comment's been stale since 084322b, the provider lookup does a GET /accounts now (and it goes to prod, see the other comment).
| try: | ||
| self._join_accounts_listing() | ||
| except Exception as exc: | ||
| if is_rate_limited(exc): |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
… overlapping-request wait
…and a failed lookup is the 400's cause
There was a problem hiding this comment.
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
…n the connector-account-unavailable vector
…execute() neither looks it up nor lists it again early
|
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 |
… 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.
There was a problem hiding this comment.
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
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.
There was a problem hiding this comment.
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
left a comment
There was a problem hiding this comment.
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.
| return { | ||
| account | ||
| for account in account_ids | ||
| if account not in self._providers |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
… names the account
There was a problem hiding this comment.
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
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, andGET /accountsis the only request outside MCP. The migration guide covers every breaking change since 2.10.1, including those from #199.Changes
MCP-only execution
tools/callon the endpoint and account that listed them, with the model's arguments sent unchanged. The server maps them itself./actions/rpcclient;param-style=flat_prefixedpin.{isError: false, result, defenderMetadata?, policyMetadata?}for action tools, bare JSON for search.isErrorstill raisesStackOneAPIErrorwith the status from its payload.result, or raises with status 501 when no link can be issued.tools/callis now sent without themcpclient's extratools/list. Its output-schema check relisted the whole catalog before every call, and the Node SDK never did that.streamable_http_client; the deprecatedstreamablehttp_clientwarned on every call.Header arguments
headersobject or a top-levelheaders_<name>. Each is forwarded only if the served schema declares it in the same form. An openheadersobject (noproperties, as*_execute_actionserves it) declares every name.Authorization,x-account-idandUser-Agentare never forwarded. The warning says whether a header was undeclared or set by the SDK. Every other argument is sent unchanged.toolset.execute()now forwards host-set headers through the openheadersobject.Feedback and sessions
stackone_submit_feedbackgoes overtools/callonly, and is listed once however many accounts serve it.submit_feedback()lists one account insearch_executemode and makes onetools/call, through the lowest account id in scope (not the first given, norGET /accountsorder). It takes an optionalaction_run_id, sent only when given.session_idis on every hit, and is forwarded byexecute(..., session_id=)andsubmit_feedback(). A pinnedaction_id/session_idis moved to the end of the arguments.Matches Node exactly
requiredis emitted verbatim and in the served order, and an empty one is omitted.tools/callresult with onlystructuredContentis returned instead of coming back as{}.Tools.get_tool()returns the first tool listed under a duplicated name, like Node'sgetTool().Server. The old one listedproperties: {}for every per-action tool.Also
FeedbackRating,FeedbackCategory,FeedbackSourceandStackOneMcpToolare exported fromstackone_ai.submit_feedback(tool_names=)takes any sequence of strings, but not a barestr.StackOneToolno longer requires_api_key.Review fixes
timeout, or the toolsettimeoutfrom the first attempt forGET /accounts. Otherwise the 429 is raised at once, so a multi-account call can't time out a throttled account into a partial catalog.headerTextwrites them (true,1, compact JSON). Header names are trimmed as JavaScript'strim()trims them.ToolArgumentsError, aStackOneErrorand aValueError.ToolParameters.requiredis declared. An account id that is not a string is rejected. An account list fetched acrossclear_catalog_cache()is discarded. ARetry-Afterdate that overflows falls back to the backoff.Second review round (decided once with node #383 and sdk-conformance)
KeyboardInterruptandSystemExitpropagate out of an MCP request; onlyExceptionbecomes aToolsetLoadError.langchainextra requireslangchain-core>=0.3.36, the first that takes a dictargs_schema.typethat is not a string, such as["object", "null"], is read as"object", as Node does, instead of"['object', 'null']".StackOneAPIError429, fatal to a multi-account call), on MCP andGET /accounts, worded as Node words it.content_partsas plain JSON, sojson.dumpsandexecute_openai_tool_calls()work.account_idthat found them;top_klimits the merged, globally sorted list; the same action on two accounts is two hits.execute()raisesToolsetConfigErrorwhen the action's connector is linked on more than one account in scope; a hit'saccount_idinaccount_idsroutes to it.to_openai(),to_langchain()andto_pydantic_ai()keep the first tool of each name (the lowest account id) and warn once.FAILED_ACCOUNT_RETRY_SECONDS(30). When every account fails, the sharedStackOneAPIErroris raised if they all have one status, else aToolsetLoadErrorraised from anExceptionGroupof the failures, which it also keeps in.failures.STACKONE_ACCOUNT_IDis set warns that it is ignored.GET /accounts(discovery orfetch_accounts()) records theorigin_usernameof each account withshared: false, and every MCP request for that account carries it asx-end-user-id, set after caller headers. Explicit account ids make noGET /accounts. A model-suppliedx-end-user-idheader argument is dropped as set by the SDK.session_idto the end inexecute()and the SDK-owned-name filter onheaders=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-toolsetuntil node #383 merges) beside this one.Verification
ruff check,ruff format --checkandty(package and examples) are clean, anduv lock --lockedpasses. The MIGRATION.md hand-built-tool recipe passestyand pyright.tests/vectors/is byte-identical to sdk-conformance7347926, the pinned commit, and every shared vector case passes.7347926(pnpm test -- --strict-schema, both SDKs, with Node atc2b8736) 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.parseConventionalCommits: 45 entries, 23 breaking, eachBREAKING CHANGEnote 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 ofStackOneTool.connectorandTools.get_connectors(), which refactor!: MCP-only toolset with account discovery, search/execute, and hardened security #199's own squash commit already carries as aBREAKING CHANGEfooter.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
resultinstead 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
requiredfrom the per-property nullable markers. It emits the served rootrequiredlist verbatim, in the served order, and omits it when absent or empty, so a hand-built ToolParameters withoutrequirednow 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 flatheaders_<name>property no longer admits the same name inside a nestedheadersobject. An openheadersobject, as*_execute_actionserves it, forwards any other header, so StackOneToolSet.execute(..., {"headers": {...}}) passes host-set headers through where it previously dropped them all. A top-levelheadersargument that isn't a plain object is dropped too, unless the schema declaresheadersitself as a non-object field, in which case it is an ordinary argument sent as given. A declared flatheaders_<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 plainstackone-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/callon the endpoint and account that listed it, withGET /accountsthe 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
structuredContent, non-text parts come back as plain JSON, andisErrorraisesStackOneAPIError. Adapters emit the servedrequiredlist verbatim and in order.TextDecoderdoes.NaN,Infinity, and unencodable arguments raiseToolArgumentsError; JSON integers above 2^53 keep their exact value.tools/callgoes throughsend_requestoverstreamable_http_client, buffering the server's error body on failure; MCP timeouts are reported as timeouts andKeyboardInterrupt/SystemExitpropagate. A call never relists the catalog first.Retry-Afteras 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 sharedStackOneAPIErroris raised if they all share one status, else aToolsetLoadErrorraised from anExceptionGroupkept in.failures. Concurrentfetch_tools()/search()share one in-flightGET /accounts.Authorization,x-account-id,User-Agent, andx-end-user-idnever are. A non-objectheadersargument is dropped unless the schema declaresheadersitself as an ordinary field; a flat list/dict header or a self-referential value is refused. A toolset-levelheaders=option goes on every request; non-shared accounts carry anx-end-user-id.STACKONE_BASE_URL→ default, and a set-but-unusedSTACKONE_ACCOUNT_IDwarns.submit_feedback()is served overtools/callonly, in every mode, listed once regardless of how many accounts serve it, and goes through the lowest account id in scope with an optionalaction_run_id. Search hits carrysession_idandaccount_id;top_klimits the merged ranking;execute(..., session_id=)forwards the hit's session id. An action linked on more than one account raises unless a hit'saccount_idroutes it.FeedbackRating,FeedbackCategory,FeedbackSource,StackOneMcpTool,ToolArgumentsError.fetch_tools(tool_names=...)accepts any sequence; thelangchainextra requireslangchain-core>=0.3.36.Server.Breaking changes
StackOneRpcTool,MCP_PARAM_STYLE,ParameterLocation,validate_method,is_json_content_type, andfilename_from_content_disposition.StackOneTool.execute()no longer makes HTTP requests; the base class raisesStackOneErrorand_api_keyis optional.ExecuteConfigkeeps onlyname,headers,timeout; other fields raiseValidationError. Action results are the server's{isError, result, ...}object; downloads return a link, not bytes.account_ids, raisesToolsetConfigError. A top-levelheaders_<name>argument is dropped unless declared; with duplicate tool names,get_tool(),to_openai(),to_langchain(), andto_pydantic_ai()return the first listing.mcpis now a core dependency (thestackone-ai[mcp]extra is gone).Written for commit 441a0ca. Summary will update on new commits.