refactor!: MCP-only toolset with account discovery, search/execute, and hardened security

Merged
WI
2mo ago
+5501-10211

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 /accounts and uses every active one. Before, every call to /mcp went out without x-account-id and 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. mcp is 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, so timeout=2 against a host that never answered hung for over five minutes.

Security (tool arguments are attacker-controlled under prompt injection)

  • A model-supplied action_id inside execute()'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's headers object.
  • Download filenames came from an attacker-controllable header unchecked, so ../../.ssh/authorized_keys was returned as-is. They are now reduced to a safe basename.

Testing and CI

  • Mocks now reject what the real API rejects: an unscoped /mcp or /actions/rpc request 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 pypi environment and re-runs the tests first; before, a red main could still ship.
  • nix removed; the toolchain is uv, ruff, ty and make. CI type-checks examples/, and a new ci-ok job 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 pins stackone-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 pypi environment
  • Make ci-ok the single required status check
  • The release workflow pushes its uv.lock commit with GITHUB_TOKEN, which doesn't trigger CI. It needs a personal access token or GitHub App token.
  • Set the CONFORMANCE_REPO_TOKEN secret

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