refactor!: MCP-only toolset with account discovery, search/execute, and hardened security
Merged
WI
2mo ago+5501+5501+0123456789012345678901234567890123456789-10211-10211-01234567890123456789012345678901234567890123456789
Summary
A major (3.0.0) rewrite. The SDK is now a thin wrapper over the StackOne MCP endpoint, it works with just an API key, and it has been tested against the live API rather than only against mocks. The previous release could not list a single tool while its whole test suite passed — most of this PR is about making sure that can't happen again.
What changed for users
- An API key is enough. With no account given, the toolset calls
GET /accountsand uses everyactiveone. Before, every call to/mcpwent out withoutx-account-idand was rejected. search()+execute()— find an action in plain English and run it, without loading the full tool catalog into the model's context.- Package reduced to three modules —
types.py,tools.py,toolset.py. Client-side search, OpenAPI parsing,tool.connector,tools.get_connectors()and the CrewAI integration are gone.mcpis now a core dependency; framework adapters are lazy extras. - Schemas reach the model unchanged. Across all 139 live tools,
to_openai_function()matches the served schema byte for byte. The LangChain adapter now passes the same schema through; before, it dropped every nested field, and every call made through it failed with a 400. - Errors: everything derives from
StackOneError. An API error's message now leads with the server's own explanation instead of generic httpx text. timeout=now actually applies to MCP calls. Before, it was ignored, sotimeout=2against a host that never answered hung for over five minutes.
Security (tool arguments are attacker-controlled under prompt injection)
- A model-supplied
action_idinsideexecute()'s arguments could replace the action the caller had pinned. - Headers were filtered by a two-name denylist that
" authorization"bypassed, and not filtered at all on the MCP path. They now go through an allowlist built from the served schema. Zero live actions declare a header, and the server was found to ignore the envelope'sheadersobject. - Download filenames came from an attacker-controllable header unchecked, so
../../.ssh/authorized_keyswas returned as-is. They are now reduced to a safe basename.
Testing and CI
- Mocks now reject what the real API rejects: an unscoped
/mcpor/actions/rpcrequest gets a 400, an unknown account a 404. The old mock filled in a missing account as'default', which is how the original bug stayed invisible. - Every fix was mutation-tested. Each was reverted in turn and the suite re-run; all 13 now fail the suite if undone. Three of them initially went unnoticed and got new tests.
- Publishing to PyPI is gated. It now runs in a
pypienvironment and re-runs the tests first; before, a redmaincould still ship. - nix removed; the toolchain is uv, ruff, ty and make. CI type-checks
examples/, and a newci-okjob aggregates the required checks.
Test plan
-
make test: 241 passed -
make format: ruff and ty clean,examples/included -
make validate: conformance with strict schema (now the default), SDK smoke, Pydantic AI 1.x and 2.x. The ADK smoke skips because the plugin pinsstackone-ai>=3.0.0, which isn't on PyPI yet. - Live against the eu1 API:
fetch_accounts,fetch_tools,search,execute, pagination, and write actions (create → read → update → delete, all cleaned up) - Every README code block run live
- Every example run live, 3 runs each: 18/18 passed
- Conformance harness verified by reverting fixes in a scratch copy of the SDK: both prompt-injection fixes, routing and ranking are all caught
Needs repo-settings changes
- Add a required reviewer to the new
pypienvironment - Make
ci-okthe single required status check - The release workflow pushes its
uv.lockcommit withGITHUB_TOKEN, which doesn't trigger CI. It needs a personal access token or GitHub App token. - Set the
CONFORMANCE_REPO_TOKENsecret
Known gaps, not in this PR
- There's no async API, so calling the SDK from async code blocks the event loop
- Each call opens a new HTTP connection instead of reusing one
- The Node SDK still has no account discovery or
search/execute; the conformance harness reports both as failures
Pairs with StackOneHQ/sdk-conformance#2.
🤖 Generated with Claude Code