Skip to content

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

Merged
willleeney merged 55 commits into
mainfrom
chore/remove-nix-toolchain
Sep 29, 2026
Merged

willleeney merged 55 commits into
mainfrom
chore/remove-nix-toolchain

Conversation

@willleeney

@willleeney willleeney commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

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

willleeney and others added 24 commits September 14, 2026 14:52
The mock server was bun-specific in two ways beyond its shebang: it read
Bun.argv and relied on Bun's default-export server convention, which Node
ignores entirely. Replace both with process.argv and @hono/node-server.

Add a root package.json pinning the mock's dependencies to the exact
versions the vendored submodule resolves (sdk 1.24.3, zod 4.1.13,
hono 4.10.7, @hono/mcp 0.1.5). Caret ranges resolve sdk to 1.30.0, which
rejects the raw inputSchema objects the vendor mock passes.

These 38 tests previously skipped because the submodule was never
initialised; they now run and pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
just was supplied by the nix flake and by CI's setup-nix action, both of
which are being removed. make is preinstalled on macOS and Linux, so the
task runner no longer needs a package manager to bootstrap.

Positional arguments become variables: `just install --all-extras` is now
`make install EXTRAS="--all-extras"`, and `just run-example foo.py` is
`make run-example FILE=foo.py`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The flake provided four things: treefmt formatting, pre-commit hooks, the
devShell toolchain, and agent skills delivery. Replace each:

- Formatting: ruff is already a dev dependency, so `make lint` and
  `make format` call it directly. nixfmt is no longer needed (no .nix
  files remain) and oxfmt is dropped, so non-Python files are now
  unformatted.
- Hooks: removed. Lint, type check and tests run in CI on every push.
- CI: setup-nix replaced with astral-sh/setup-uv, plus pnpm and Node for
  the MCP mock server. gitleaks now uses its official action rather than
  installing the binary through nix.
- Skills: dropped. They were gitignored and only materialised inside
  `nix develop`, so they were never visible outside a nix shell.

Also drops the nix-flake and nix-flake-update workflows, the nix-workflow
rule, and the stale .pre-commit-config.yaml ignore entry.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
AGENTS.md is the cross-tool standard that Cursor and other agents read
natively; Claude Code reads CLAUDE.md. Symlinking one to the other gives
both a single source of truth with no duplicated content, matching the
pattern already used in stackone-ai-node.

Also removes the two Available Skills tables (the section was duplicated,
listing different skills each time) and the nix-workflow row now that
skills and the nix rule are gone.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Fold the seven .claude/rules/ files into CLAUDE.md and delete .claude/
and .cursor/ entirely. AGENTS.md already symlinks to CLAUDE.md, so a
single file now serves every agent with no symlink tree to maintain.

Condensed rather than concatenated: a verbatim merge came to ~505 lines,
against the 200-line target above which adherence drops. Dropped the
illustrative good/bad code blocks and the sample UV script, keeping every
actual rule. Result is 192 lines.

Two corrections made while merging, both previously contradicted by the
repo itself:

- Line length was documented as 88 ("ruff default"); pyproject.toml sets
  110.
- The pre-commit hooks section described hooks that no longer exist.

Trade-off: the four path-scoped rules (examples, scripts, pyproject, *.py)
previously loaded only when touching matching files. They now load every
session.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
scripts/ held only benchmark_search.py, a manual latency benchmark that
required STACKONE_API_KEY and STACKONE_ACCOUNT_ID to run. Nothing
referenced it: no CI job, no test, no Makefile target.

Also drops the now-dead scripts/ ruff per-file-ignore and the Scripts
section of CLAUDE.md.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
.envrc contained `use flake`, the nix-direnv hook that activates the nix
devShell on cd. flake.nix was removed in 3bf1a27, so the file errors for
anyone with direnv installed. It was tracked, so it affected everyone.

uv manages the virtualenv directly, so there is nothing left for direnv
to load.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Python 3.11 minimum. The CI matrix claimed to test 3.10-3.13 but the old
setup-nix action ignored matrix.python-version entirely, so every leg ran
on the same devShell interpreter. setup-uv honours it, which exposed that
the examples extra cannot install on 3.10 (onnxruntime 1.24.3 ships no
cp310 wheels).

CI fixes:
- gitleaks: the GitHub Action requires a paid licence for org-owned repos
  and would have exited 1 on every run. Install the free CLI and call
  `make gitleaks`, which also revives a Makefile target nothing installed.
- Scope pages/id-token write permissions to the coverage jobs instead of
  granting them workflow-wide, so the job running PR code can no longer
  mint an OIDC token.

Security: _build_action_headers stripped only exact-case "Authorization",
but header names are case-insensitive and tool arguments are
model-controlled, so headers_authorization passed straight through into
the RPC envelope. x-account-id was likewise overridable, allowing a
prompt-injected call to retarget another tenant. Both are now reserved and
filtered case-insensitively, with the account id applied after merging.
Adds regression tests for the case variants and the account override.

Also removes the dead epilogue in StackOneTool.execute: two discarded
datetime.now() calls and a metadata dict built in a finally block and
thrown away, left over from the removed implicit-feedback path. Dropping
TYPE_CHECKING means to_pydantic_ai_tool returns Any, since pydantic-ai is
optional and must not be imported at module level.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…hrough

Reduce stackone_ai to three modules built around one property: the toolset is
the served catalog. The schema listed to a model is the schema the MCP server
sent, and the request sent to /actions/rpc matches it.

- types.py: ToolParameters, ExecuteConfig, ParameterLocation, error hierarchy,
  shared aliases, DEFAULT_BASE_URL
- tools.py: StackOneTool, Tools, StackOneRpcTool, the MCP listing client
- toolset.py: StackOneToolSet

BREAKING: to_openai_function no longer filters the schema. It copied only
type/description/enum, silently discarding format, pattern, default,
minimum/maximum, oneOf/anyOf and nested required, so a model could not generate
valid arguments for any constrained field. The served schema now passes through
verbatim; only the SDK's internal `nullable` marker is stripped, becoming the
JSON Schema `required` list. This is what the conformance suite's
--strict-schema gate checks.

BREAKING: client-side search is removed — semantic_search, local_search, the
BM25/TF-IDF index, SearchConfig/SearchMode, the tool_search/tool_execute meta
tools and mode="search_and_execute". It is absent from the conformance contract
(the mock serves no /actions/search) and the contract docs flag client-side
search as something that should move server-side. Frees bm25s and numpy.

BREAKING: removes stackone_ai.integrations. LangGraph's own ToolNode and
bind_tools cover it; examples/langgraph_integration.py already used those
directly.

Replaces the vendored stackone-ai-node submodule with the one file the tests
actually used: mocks/mcp-server.ts, 275 lines with npm-only imports. Drops 764K
and 102 files, and the mock fixture now fails rather than skips when Node
dependencies are missing — a silent skip had let all 19 integration tests vanish
while CI stayed green.

Docs corrected against the code: stackone_ai/oas/, tests/snapshots/,
_process_response(), include_tools=, strict ty config, the context-window
warning, basic_usage/ and integrations/ example directories, and README's
configure_implicit_feedback section all described things that do not exist.

Also drops typing-extensions and pytest-snapshot (no references), the bin/**.py
ruff ignore (that directory has never existed), the T201/T203 codes (flake8-print
rules absent from `select`), and the redundant asyncio marker.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ke tests

One entry point for everything that consumes the SDK: example integrity, the
sdk-conformance wire contract (with --strict-schema), and the SDK / Pydantic AI /
Google ADK smoke suites.

Skips are never counted as passes. A section that cannot run says why and is
listed in the summary, so an absent sibling repo or missing credentials can never
read as green.

Two traps found while writing it, both the silent-green failure this repo keeps
hitting:

- Piping `ty` into grep is scored by `set -o pipefail`, which returns ty's
  non-zero exit even when grep matched — a successful detection read as "no
  match" and the check passed. Output is now captured before grepping.
- Grepping for `stackone_ai` matched ty's echoed source context, so every
  example's own import tripped it and a clean tree reported a failure. It now
  matches the diagnostic line itself.

Verified in both directions: injecting a reference to a removed symbol fails the
check, and a clean tree passes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Adds a conformance job running `pnpm test:python -- --strict-schema`, which
fails on any schema keyword the SDK drops between what the server serves and
what the model is shown. Locally this is the `make`-adjacent equivalent of
scripts/validate.sh conformance.

StackOneHQ/sdk-conformance is private, so the default GITHUB_TOKEN cannot check
it out. The job requires a CONFORMANCE_REPO_TOKEN secret (PAT or App token with
read access) and fails with an explicit message when it is absent, rather than
skipping — a contract check that skips reads as green while enforcing nothing.

Also adds mcp to the dev dependency group. fetch_tools() hard-requires the mcp
client and no test guards its import, so a bare `uv sync` produced a venv where
the suite errored instead of skipping. Found by reproducing the job's layout from
a clean checkout: it failed with "MCP dependencies are required for fetch_tools"
where the local run passed only because .venv had been synced with --all-extras.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The SDK told users to `pip install "stackone-ai[mcp]"` in its own ImportError,
and the README and pydantic-ai example did the same, while CLAUDE.md states uv
is used for all dependency management. Switched to `uv add`.

Also strengthens scripts/validate.sh. Running an example live and checking its
exit code proves almost nothing: every integration example filters on
`workday_*`, and against a linked account with no Workday connector they load
zero tools, call the model anyway, and exit 0. Verified against the live API —
all five reported "Loaded 0 tools" while the validator called it a pass. The
live-run check now fails when an example loads nothing and prints the line that
gave it away.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`make` with no arguments ran `install` because it was the first target. It now
prints the target list instead, which is both safer and more discoverable.

Help is generated from the `##` comments above each target, so it cannot drift
from the Makefile the way a hand-maintained list would.

Also surfaces three things that have caught people out: `publish` pushes to PyPI
for real, `gitleaks` needs a binary nothing installs locally, and
`test-examples` only imports each example — the `__main__` guard means no
example body ever runs, so it goes green without exercising anything.

Adds a `validate` target wrapping scripts/validate.sh.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`lint` and `format` were the same ruff invocation in opposite modes, which read
as two concerns rather than check-vs-fix. CI is the only caller that needs the
read-only mode, and it now runs ruff, ty and pytest directly instead of going
through make — so it verifies what was committed and cannot mutate the tree to
make itself pass.

`format` now fixes lint, formats, and type checks: one command before
committing.

Removes `lint` (CI runs the ruff commands itself), `ty` (folded into `format`),
`test-tools` (`test` already collects tests/ — verified, both give 174) and
`run-example` (`uv run examples/<file>` directly).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Publishing is release-please's job: merge to main, merge the release PR, and
release.yaml runs uv build + uv publish with PYPI_API_TOKEN. A local target
meant a developer machine could push to PyPI out of band, bypassing the version
bump, changelog and tag.

release.yaml already invokes uv directly, so nothing depended on the target.
`build` stays for checking the artifact locally.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The target invoked a bare `gitleaks` binary that nothing installed once the nix
shell went, so it failed with command-not-found on every machine. CI installs
the CLI and runs the same command itself, with fetch-depth 0 so it scans the
full history rather than a shallow slice — which a local run would not have done
anyway.

.gitleaks.toml stays; it is the config CI passes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ng the venv

`uv sync` makes the environment match the requested set exactly, so a bare
`uv sync` uninstalls every optional dependency. Measured: `make install` took
the venv from 207 packages to 56, removing openai, crewai, langgraph and
pydantic-ai — leaving the examples unable to import and the mcp-backed tests
unable to run.

The obvious command should not break the environment. EXTRAS now defaults to
--all-extras; EXTRAS="" still gets the minimal set, and the help says plainly
that it removes things.

`uv run` was not the culprit — the package count is unchanged across `make test`.

CI is unaffected: it runs `uv sync --all-extras --locked` directly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The dependency tiers were inverted. Every user installed langchain-core — and
transitively langsmith — for one of four adapters, while nobody could fetch a
tool out of the box because the MCP client was optional.

Measured on a clean venv:

  pydantic + httpx                 11 packages
  + langchain-core  (old core)     33 packages, and fetch_tools() still fails
  + mcp             (new core)     29 packages, and everything works

BREAKING: `stackone-ai[mcp]` no longer exists — mcp is a core dependency, since
fetch_tools() is the only route to a tool and it talks MCP. `to_langchain()` now
requires `stackone-ai[langchain]` and raises a clear ImportError without it,
mirroring how to_pydantic_ai_tool() already behaved.

Both misplacements were historical: mcp was genuinely optional when the SDK
shipped bundled OpenAPI specs and get_tools() worked offline, but d50d5fb
deleted that path and the extras never followed.

Verified on a bare install (30 packages, no langchain_core, no langsmith):
fetch_tools returns 22 live tools, to_openai works, to_langchain raises the
install hint. Conformance still passes with --strict-schema.

CLAUDE.md now records the rule so it does not drift back: core is what the SDK
needs to function, extras are per-framework adapters with lazy imports.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two tiers: core and extras. The PEP 735 dev group was a third mechanism for
declaring dependencies, and one tier fewer is easier to reason about than the
distinction it bought.

Also drops the `stackone-ai` self-reference from dev, which only ever meant
"install the project", something uv does anyway.

Trade-off, stated plainly: a dev group is never published, an extra is. The
wheel now advertises `Provides-Extra: dev`, so `uv add 'stackone-ai[dev]'`
installs pytest, ruff and ty for a consumer. That is the cost of the simpler
model, not an oversight.

`make install` defaults to --all-extras, so the tooling still arrives with one
command, and CI's `uv sync --all-extras --locked` is unaffected.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`make install` now syncs core only and `make extras` syncs everything, so
`make install extras` reads as the sentence it is. Replaces the EXTRAS variable,
which required knowing that a bare `make install` would silently uninstall
openai, crewai and the test tooling.

Measured: `make install` gives 30 packages (mcp yes, pytest no, openai no);
`make install extras` gives 207. The help says outright that `install` removes
anything outside the core set, since that is what `uv sync` does and it is not
obvious.

Also fixes the help parser: it ran `sed 's/:.*//'` over every line, so any
description containing a colon was truncated — "Install everything: adapters,
examples and dev tooling" rendered as "Install everything". Targets and
descriptions are now parsed separately.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`make install` and `make install extras=1`, one target instead of two. Any
non-empty value works, so extras=1 and extras=True both do.

Reverts the separate `extras` target added in f2acc61 — it was a second command
in the list for something that is a property of how you install, not a different
thing to run.

  make install            30 packages, no pytest
  make install extras=1   207 packages, pytest present

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Nothing called it. CI runs the command inline, and the three report formats
exist for CI alone: coverage/coverage.json feeds the badge action and
coverage/html is uploaded to Pages. Locally `uv run pytest --cov` is the useful
form and needs no target.

Also trims coverage exclude_lines to the one pattern that still matches
anything. `if TYPE_CHECKING:` went when the adapter imports became lazy, and
there is no __repr__ or NotImplementedError in the package — verified 0 hits
each.

Coverage is unchanged at 96%.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The live example run was skipping for want of credentials that were sitting in
.env two directories up from the check. validate.sh now sources .env when
present and prints which path it used; when absent it says so, so a skip is
always attributable rather than mysterious.

Only that one check needs credentials — conformance and the smoke suites drive a
mock API on 127.0.0.1 with a dummy key (conformance-key / smoke-key), which is
what lets the oracle assert that the schema an SDK listed matches the request it
sent.

With credentials loaded the examples check now fails rather than skipping, which
is correct: all five load 0 tools because they filter workday_* against accounts
that have no Workday connector.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
validate now runs only against the sdk-conformance mock on 127.0.0.1 with a
dummy key, so it is deterministic, needs no credentials, and cannot spend real
API calls or OpenAI tokens.

Removes the live example run and the .env loading added a commit earlier. The
live run was the one section that called StackOne, and it was also the least
informative: it drove each example against whatever account happened to be
linked, so its result depended on the connectors on that key rather than on
anything in this repo.

The static example checks stay — they catch a removed or renamed SDK symbol,
which is the regression the restructure could actually cause.

  6 passed, 0 failed, 0 skipped.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings September 16, 2026 12:04
Comment thread .github/workflows/ci.yaml
Comment on lines +29 to +31
run: |
curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \
| tar -xz -C /usr/local/bin gitleaks

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Binary, code or archive is pulled from a remote source without integrity verification - medium severity
A GitHub Actions Workflow was built using an artifact from a remote source without any integrity verification. If the remote artifact were silently replaced with a malicious version (for example, through a supply chain attack), the integrity and confidentiality of the environment in which the container is deployed could be compromised.

Show fix

Remediation: Validate the artifact against a trusted SHA-512 checksum in the CI/CD pipeline using sha512sum in check mode. Store the expected checksum in a file (e.g., artifact.sha512), then verify it with: sha512sum -c artifact.sha512. Enable strict error handling (for example, set -e in shell scripts) so the pipeline fails if verification fails or outputs errors.

Reply @AikidoSec ignore: [REASON] to ignore this issue.
More info

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.

@AikidoSec ignore: Gitleaks installer in CI

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

✅ Based on your feedback, we ignored this issue because of the following reason:

Gitleaks installer in CI

Comment thread uv.lock

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

CVE-2025-71176 in pytest - medium severity
pytest through 9.0.2 on UNIX relies on directories with the /tmp/pytest-of-{user} name pattern, which allows local users to cause a denial of service or possibly gain privileges.

Details

Remediation Aikido suggests bumping this package to version 9.0.3 to resolve this issue

Reply @AikidoSec ignore: [REASON] to ignore this issue.
More info

@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.

7 issues found across 70 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="tests/mocks/serve.ts">

<violation number="1" location="tests/mocks/serve.ts:20">
P3: The header comment still says the file "Imports createMcpApp from stackone-ai-node vendor submodule," but this refactor removed the vendor submodule (no vendor/ dir remains) and the import now resolves to ./mcp-server in the same directory. Update the comment so it doesn't mislead readers about where the mock app comes from.</violation>
</file>

<file name="tests/mocks/mcp-server.ts">

<violation number="1" location="tests/mocks/mcp-server.ts:35">
P3: The docstring example references a `createMcpHandler` export and a `./mocks/node` module that do not exist (the file exports `createMcpApp`, and only `mcp-server.ts`/`serve.ts` exist under tests/mocks). Update the example to use `createMcpApp` and the real import path so it doesn't mislead future test authors.</violation>

<violation number="2" location="tests/mocks/mcp-server.ts:81">
P2: When an MCP client calls any registered tool through `/mcp`, `params` is undefined because the SDK passes arguments directly. Use the direct arguments object for `structuredContent` so the mock can serve tool calls.</violation>
</file>

<file name="tests/conftest.py">

<violation number="1" location="tests/conftest.py:69">
P3: The check verifies only that `node_modules` exists, but the mock server actually requires `pnpm` on PATH: `serve.ts` runs through the shebang `#!/usr/bin/env -S pnpm exec tsx`. When `node_modules` was installed by another tool and `pnpm` is missing, the check passes, then the fixture burns the 30 s wait and raises a generic "failed to start" RuntimeError instead of the actionable failure this change is meant to provide. Check for the real prerequisite (`pnpm exec`/`tsx` availability) so the fail-fast diagnostic fires whenever the server cannot launch.</violation>
</file>

<file name="scripts/validate.sh">

<violation number="1" location="scripts/validate.sh:43">
P2: When `make validate` follows the documented core-only `make install`, the examples section reports missing optional framework packages as failures instead of the SKIP behavior promised by this script. Detect missing example dependencies and call `skip`, matching `test_examples.py`.</violation>
</file>

<file name=".github/workflows/ci.yaml">

<violation number="1" location=".github/workflows/ci.yaml:31">
P1: The gitleaks job cannot install its binary because the unprivileged runner cannot write to `/usr/local/bin`. Extract into a writable bin directory or run the tar extraction with `sudo`.</violation>
</file>

<file name="CLAUDE.md">

<violation number="1" location="CLAUDE.md:183">
P2: The documented pass-through contract is false for root schema keywords such as `additionalProperties`. Preserve the served root schema when building OpenAI parameters, or narrow this statement until the converter retains those constraints.</violation>
</file>

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread .github/workflows/ci.yaml Resolved
Comment thread .github/workflows/ci.yaml
- name: Install gitleaks
run: |
curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \
| tar -xz -C /usr/local/bin gitleaks

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1: The gitleaks job cannot install its binary because the unprivileged runner cannot write to /usr/local/bin. Extract into a writable bin directory or run the tar extraction with sudo.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At .github/workflows/ci.yaml, line 31:

<comment>The gitleaks job cannot install its binary because the unprivileged runner cannot write to `/usr/local/bin`. Extract into a writable bin directory or run the tar extraction with `sudo`.</comment>

<file context>
@@ -24,11 +22,15 @@ jobs:
+      - name: Install gitleaks
+        run: |
+          curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \
+            | tar -xz -C /usr/local/bin gitleaks
+        env:
+          GITLEAKS_VERSION: 8.29.0
</file context>
Suggested change
| tar -xz -C /usr/local/bin gitleaks
+ | sudo tar -xz -C /usr/local/bin gitleaks

Comment thread README.md Resolved
Comment thread stackone_ai/types.py Resolved
Comment thread stackone_ai/tools.py Resolved
Comment thread CLAUDE.md Resolved
Comment thread tests/mocks/serve.ts
exampleBamboohrTools,
mixedProviderTools,
} from "../../vendor/stackone-ai-node/mocks/mcp-server";
} from "./mcp-server";

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P3: The header comment still says the file "Imports createMcpApp from stackone-ai-node vendor submodule," but this refactor removed the vendor submodule (no vendor/ dir remains) and the import now resolves to ./mcp-server in the same directory. Update the comment so it doesn't mislead readers about where the mock app comes from.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At tests/mocks/serve.ts, line 20:

<comment>The header comment still says the file "Imports createMcpApp from stackone-ai-node vendor submodule," but this refactor removed the vendor submodule (no vendor/ dir remains) and the import now resolves to ./mcp-server in the same directory. Update the comment so it doesn't mislead readers about where the mock app comes from.</comment>

<file context>
@@ -16,9 +17,9 @@ import {
   exampleBamboohrTools,
   mixedProviderTools,
-} from "../../vendor/stackone-ai-node/mocks/mcp-server";
+} from "./mcp-server";
 
-const port = parseInt(process.env.PORT || Bun.argv[2] || "8787", 10);
</file context>

Comment thread tests/mocks/mcp-server.ts
* @example
* ```ts
* import { server } from './mocks/node';
* import { createMcpHandler, defaultMcpTools, accountMcpTools } from './mocks/mcp-server';

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P3: The docstring example references a createMcpHandler export and a ./mocks/node module that do not exist (the file exports createMcpApp, and only mcp-server.ts/serve.ts exist under tests/mocks). Update the example to use createMcpApp and the real import path so it doesn't mislead future test authors.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At tests/mocks/mcp-server.ts, line 35:

<comment>The docstring example references a `createMcpHandler` export and a `./mocks/node` module that do not exist (the file exports `createMcpApp`, and only `mcp-server.ts`/`serve.ts` exist under tests/mocks). Update the example to use `createMcpApp` and the real import path so it doesn't mislead future test authors.</comment>

<file context>
@@ -0,0 +1,275 @@
+ * @example
+ * ```ts
+ * import { server } from './mocks/node';
+ * import { createMcpHandler, defaultMcpTools, accountMcpTools } from './mocks/mcp-server';
+ *
+ * // In your test setup
</file context>

Comment thread tests/conftest.py
if not (vendor_dir / "package.json").exists():
pytest.skip("stackone-ai-node submodule not initialized. Run 'git submodule update --init'")
if not (project_root / "node_modules").is_dir():
pytest.fail("Node dependencies missing for the MCP mock server. Run 'pnpm install'.")

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P3: The check verifies only that node_modules exists, but the mock server actually requires pnpm on PATH: serve.ts runs through the shebang #!/usr/bin/env -S pnpm exec tsx. When node_modules was installed by another tool and pnpm is missing, the check passes, then the fixture burns the 30 s wait and raises a generic "failed to start" RuntimeError instead of the actionable failure this change is meant to provide. Check for the real prerequisite (pnpm exec/tsx availability) so the fail-fast diagnostic fires whenever the server cannot launch.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At tests/conftest.py, line 69:

<comment>The check verifies only that `node_modules` exists, but the mock server actually requires `pnpm` on PATH: `serve.ts` runs through the shebang `#!/usr/bin/env -S pnpm exec tsx`. When `node_modules` was installed by another tool and `pnpm` is missing, the check passes, then the fixture burns the 30 s wait and raises a generic "failed to start" RuntimeError instead of the actionable failure this change is meant to provide. Check for the real prerequisite (`pnpm exec`/`tsx` availability) so the fail-fast diagnostic fires whenever the server cannot launch.</comment>

<file context>
@@ -58,13 +57,16 @@ def test_mcp_integration(mcp_mock_server):
-    if not (vendor_dir / "package.json").exists():
-        pytest.skip("stackone-ai-node submodule not initialized. Run 'git submodule update --init'")
+    if not (project_root / "node_modules").is_dir():
+        pytest.fail("Node dependencies missing for the MCP mock server. Run 'pnpm install'.")
 
     # find port
</file context>

Comment thread stackone_ai/tools.py Resolved

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.

🟡 Changes recommended

One or more issues must be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Refactors the SDK around an MCP-served catalog, removes client-side search, and replaces the Nix toolchain with uv/make and conformance CI.

Changes:

  • Consolidates runtime code into types.py, tools.py, and toolset.py.
  • Adds flat-prefixed RPC handling, schema tests, and case-insensitive header protections.
  • Updates dependencies, examples, mocks, CI, and validation tooling.
File summaries
File Description
tests/test_toolset.py Updated as part of this pull request.
tests/test_tool_calling.py Updated as part of this pull request.
tests/test_tfidf_index.py Updated as part of this pull request.
tests/test_models.py Updated as part of this pull request.
tests/test_local_search.py Updated as part of this pull request.
tests/test_integrations_pydantic_ai.py Updated as part of this pull request.
tests/test_integrations_langgraph.py Updated as part of this pull request.
tests/test_fetch_tools.py Updated as part of this pull request.
tests/test_feedback.py Updated as part of this pull request.
tests/test_agent_tools.py Updated as part of this pull request.
tests/mocks/serve.ts Updated as part of this pull request.
tests/mocks/mcp-server.ts Updated as part of this pull request.
tests/conftest.py Updated as part of this pull request.
stackone_ai/utils/tfidf_index.py Updated as part of this pull request.
stackone_ai/utils/normalize.py Updated as part of this pull request.
stackone_ai/utils/init.py Updated as part of this pull request.
stackone_ai/types.py Updated as part of this pull request.
stackone_ai/semantic_search.py Updated as part of this pull request.
stackone_ai/models.py Updated as part of this pull request.
stackone_ai/local_search.py Updated as part of this pull request.
stackone_ai/integrations/langgraph.py Updated as part of this pull request.
stackone_ai/integrations/init.py Updated as part of this pull request.
stackone_ai/feedback/tool.py Updated as part of this pull request.
stackone_ai/feedback/init.py Updated as part of this pull request.
stackone_ai/constants.py Updated as part of this pull request.
stackone_ai/init.py Updated as part of this pull request.
scripts/validate.sh Updated as part of this pull request.
scripts/benchmark_search.py Updated as part of this pull request.
README.md Updated as part of this pull request.
pyproject.toml Updated as part of this pull request.
package.json Updated as part of this pull request.
Makefile Updated as part of this pull request.
justfile Updated as part of this pull request.
flake.nix Updated as part of this pull request.
flake.lock Updated as part of this pull request.
examples/test_examples.py Updated as part of this pull request.
examples/search_tools.py Updated as part of this pull request.
examples/pydantic_ai_integration.py Updated as part of this pull request.
CLAUDE.md Updated as part of this pull request.
.mcp.json Updated as part of this pull request.
.gitmodules Updated as part of this pull request.
.gitignore Updated as part of this pull request.
.github/workflows/release.yaml Updated as part of this pull request.
.github/workflows/nix-flake.yaml Updated as part of this pull request.
.github/workflows/nix-flake-update.yaml Updated as part of this pull request.
.github/workflows/ci.yaml Updated as part of this pull request.
.github/actions/setup-nix/action.yaml Updated as part of this pull request.
.envrc Updated as part of this pull request.
.claude/rules/uv-scripts.md Updated as part of this pull request.
.claude/rules/release-please-standards.md Updated as part of this pull request.
.claude/rules/package-installation.md Updated as part of this pull request.
.claude/rules/no-relative-imports.md Updated as part of this pull request.
.claude/rules/nix-workflow.md Updated as part of this pull request.
.claude/rules/git-workflow.md Updated as part of this pull request.
.claude/rules/examples-standards.md Updated as part of this pull request.
.claude/rules/development-workflow.md Updated as part of this pull request.
Review details

Files not reviewed (1)

  • pnpm-lock.yaml: Generated file

Suppressed comments (2)

tests/mocks/mcp-server.ts:85

  • registerTool invokes its callback with the tool-arguments object as the first parameter, not { params: ... }. With this destructuring, a call containing {foo: ...} leaves params undefined and the mock returns empty structuredContent, so execution through this server does not reflect the submitted arguments.
    tests/mocks/serve.ts:20
  • The new local ./mcp-server import leaves the header comment claiming this file imports from the stackone-ai-node vendor submodule. Update that comment to match the source actually used by the test server, otherwise the mock setup documentation is misleading.
  • Files reviewed: 65/70 changed files
  • Comments generated: 9
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread .github/workflows/ci.yaml
- name: Install gitleaks
run: |
curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \
| tar -xz -C /usr/local/bin gitleaks
Comment thread stackone_ai/toolset.py Outdated
Comment on lines 142 to 144
@@ -1260,11 +143,11 @@ def fetch_tools(
if cached is not None:
return cached
Comment thread stackone_ai/toolset.py
Comment on lines 228 to 232
schema = tool_def.input_schema or {}
parameters = ToolParameters(
type=str(schema.get("type") or "object"),
properties=self._normalize_schema_properties(schema),
)
Comment thread examples/test_examples.py Outdated
Comment on lines 25 to 29
@@ -29,7 +29,6 @@ def get_example_files() -> list[str]:
"crewai_integration.py": ["crewai", "mcp"],
Comment thread pyproject.toml Outdated
[project.optional-dependencies]
mcp = ["mcp>=1.3.0,<2.0.0"]
langchain = ["langchain-core>=0.1.0"]
pydantic-ai = ["pydantic-ai-slim>=1.83.0,<2.0.0"]
Comment thread stackone_ai/tools.py Outdated
Comment on lines +413 to +417
if isinstance(details, dict):
type_str = details.get("type", "string")
is_nullable = details.get("nullable", False)
if type_str == "number":
python_type = float
Comment thread CLAUDE.md Resolved
Comment thread README.md Outdated
Comment on lines 215 to 216
# For agent-driven discovery, enable search on the constructor:
# toolset = StackOneToolSet(search={"method": "auto"})
Comment thread stackone_ai/tools.py
Comment on lines +119 to +122
except ImportError as exc: # pragma: no cover - depends on optional extra
raise ToolsetConfigError(
"MCP dependencies are required for fetch_tools. Install with 'uv add \"stackone-ai[mcp]\"'."
) from exc
@willleeney

Copy link
Copy Markdown
Contributor Author

Thanks Stu — addressed all of your points across both PRs:

  1. Root-level schema pass-through: Fixed. ToolParameters now preserves extra fields (ConfigDict(extra="allow")), toolset.py spreads the served schema through, and to_openai_function() preserves all root keywords ($schema, $defs, $ref, title, additionalProperties, oneOf, etc.) while only normalizing properties and updating required.
  2. CI for forks / Dependabot: Added a setup job check so conformance gracefully skips when CONFORMANCE_REPO_TOKEN is absent, and ci-ok only flags actual failures or cancellations.
  3. pnpm setup: Pinned version: 10.26.0 in CI and set packageManager on the conformance side.
  4. Meta-tool header comment: Clarified the comment in tools.py to note that meta tools drop headers because the target action schema is not fetched ahead of execution to build an allowlist.
  5. Connector splitting helper: Removed StackOneTool.connector and get_connectors() — leftover dead code from the search removal.
  6. Prefix detection flip: Added logger.debug when prefixed mode is disabled due to a bare parameter name.
  7. Discovery account cap: Added a docstring warning in _discover_account_ids() advising callers in large orgs to supply explicit account_ids.

@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 40 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.

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="stackone_ai/toolset.py">

<violation number="1" location="stackone_ai/toolset.py:171">
P3: This warning is incorrect when the toolset already has account scope: `fetch_tools()` uses `set_accounts()` or the constructor's `account_id` before discovering accounts. Qualify the note so scoped callers are not told that an omitted per-call `account_ids` always fans out to every active account.</violation>
</file>

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

Re-trigger cubic

Comment thread stackone_ai/toolset.py
Comment on lines +171 to +174
For organizations with multiple connected accounts, calling `fetch_tools()`
without `account_ids` discovers and fetches the catalog for every active account.
If your organization has many accounts, pass explicit `account_ids` to avoid
excessive round trips and blowing model context limits.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P3: This warning is incorrect when the toolset already has account scope: fetch_tools() uses set_accounts() or the constructor's account_id before discovering accounts. Qualify the note so scoped callers are not told that an omitted per-call account_ids always fans out to every active account.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At stackone_ai/toolset.py, line 171:

<comment>This warning is incorrect when the toolset already has account scope: `fetch_tools()` uses `set_accounts()` or the constructor's `account_id` before discovering accounts. Qualify the note so scoped callers are not told that an omitted per-call `account_ids` always fans out to every active account.</comment>

<file context>
@@ -166,6 +166,12 @@ def fetch_tools(
             tools = toolset.fetch_tools(actions=['*_list_employees'])
+
+        Note:
+            For organizations with multiple connected accounts, calling `fetch_tools()`
+            without `account_ids` discovers and fetches the catalog for every active account.
+            If your organization has many accounts, pass explicit `account_ids` to avoid
</file context>
Suggested change
For organizations with multiple connected accounts, calling `fetch_tools()`
without `account_ids` discovers and fetches the catalog for every active account.
If your organization has many accounts, pass explicit `account_ids` to avoid
excessive round trips and blowing model context limits.
For organizations with multiple connected accounts, calling `fetch_tools()`
without `account_ids` (and without accounts set via `set_accounts()` or
`StackOneToolSet(account_id=...)`) discovers and fetches the catalog for every
active account. If your organization has many accounts, pass explicit
`account_ids` to avoid excessive round trips and blowing model context limits.

@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.

Schema fix is spot on. Checked it against a UCA-shaped schema and $schema, $defs, additionalProperties, title and a root oneOf all come through now, with nullable still stripped from what the model actually sees. 247 tests, ruff and ty clean here too. Thanks for turning that round quickly.

One to go back on, left inline on ci-ok. Dropping get_connectors() along with the connector property is fine by me on a major, but worth a CHANGELOG line given it isn't in the description.

Comment thread .github/workflows/ci.yaml Resolved
Comment thread .github/workflows/ci.yaml Resolved
Comment thread stackone_ai/tools.py Resolved
@willleeney

Copy link
Copy Markdown
Contributor Author

Thanks Stu — updated all 4 items:

  1. Tightened CI skip gate: conformance now only skips if running on an external fork (github.event.pull_request.head.repo.fork == true) or triggered by Dependabot (github.actor == 'dependabot[bot]'). For internal branches/PRs, the secret is strictly required and fails fast if missing or expired.
  2. Updated CI comment: Fixed the header comment in ci.yaml to accurately document the fork/dependabot skip policy.
  3. Prefix detection logging: Bumped to logger.warning so that disabling flat prefix detection on bare property names is visible by default in production.
  4. Connector removal documented: Added a breaking change entry in CHANGELOG.md and updated the PR summary noting the removal of StackOneTool.connector and Tools.get_connectors() in favor of prefix-aware provider filtering.

@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.

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="CHANGELOG.md">

<violation number="1" location="CHANGELOG.md:3">
P3: This changelog is release-please-managed (release.yaml pins googleapis/release-please-action v4.4.0, and every existing entry is a generated `## [x.y.z](url)` heading), but this commit hand-writes a `## 3.0.0 (Unreleased)` heading in a different format. When the 3.0.0 release is cut, release-please regenerates the top of CHANGELOG.md from conventional commits and will either prepend a second 3.0.0 entry above this one or detect `3.0.0` already present and skip generating the release entry, leaving a stale `(Unreleased)` section permanently in the published changelog. Drop the versioned heading (keep the note under an unversioned `## Unreleased`, or as a comment) so release-please keeps owning the 3.0.0 entry, and verify the next release PR's changelog diff.</violation>
</file>

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

Re-trigger cubic

Comment thread CHANGELOG.md Outdated
@@ -1,5 +1,11 @@
# Changelog

## 3.0.0 (Unreleased)

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P3: This changelog is release-please-managed (release.yaml pins googleapis/release-please-action v4.4.0, and every existing entry is a generated ## [x.y.z](url) heading), but this commit hand-writes a ## 3.0.0 (Unreleased) heading in a different format. When the 3.0.0 release is cut, release-please regenerates the top of CHANGELOG.md from conventional commits and will either prepend a second 3.0.0 entry above this one or detect 3.0.0 already present and skip generating the release entry, leaving a stale (Unreleased) section permanently in the published changelog. Drop the versioned heading (keep the note under an unversioned ## Unreleased, or as a comment) so release-please keeps owning the 3.0.0 entry, and verify the next release PR's changelog diff.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At CHANGELOG.md, line 3:

<comment>This changelog is release-please-managed (release.yaml pins googleapis/release-please-action v4.4.0, and every existing entry is a generated `## [x.y.z](url)` heading), but this commit hand-writes a `## 3.0.0 (Unreleased)` heading in a different format. When the 3.0.0 release is cut, release-please regenerates the top of CHANGELOG.md from conventional commits and will either prepend a second 3.0.0 entry above this one or detect `3.0.0` already present and skip generating the release entry, leaving a stale `(Unreleased)` section permanently in the published changelog. Drop the versioned heading (keep the note under an unversioned `## Unreleased`, or as a comment) so release-please keeps owning the 3.0.0 entry, and verify the next release PR's changelog diff.</comment>

<file context>
@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.0.0 (Unreleased)
+
+### Breaking Changes
</file context>

@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.

Third pass at 66971f1. All ten threads hold up: 247 pass, ruff and ty clean, and reading the new check-secret gate through it does the right thing for forks, dependabot re-runs and check-secret itself falling over. Nice one.

Two to fix before merge and one that can be a follow-up, all inline.

Worth knowing the green conformance check here is graded by sdk-conformance main, which doesn't have inv 9, inv 10 or the new rich-schema fixture yet. This branch passes #2's harness locally too, so I'd merge #2 first then re-run conformance here before this goes in.

Comment thread pyproject.toml Outdated
"typing-extensions>=4.0.0",
# fetch_tools() is the only route to a tool and talks MCP, so the client is
# not optional: without it the SDK cannot do anything.
"mcp>=1.3.0,<2.0.0",

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 floor is lower than we can actually run on. mcp.client.streamable_http doesn't exist before 1.8.0, and from 1.8.0 to 1.9.3 every listing, search and execute fails with 'float' object has no attribute 'seconds', because _mcp_transport now passes timeout as a float and those versions want a timedelta. Ran the suite against each, 24 failures up to 1.9.3 and clean from 1.9.4.

Bump to mcp>=1.9.4,<2.0.0? Now its a core dep, anyone with an older mcp already pinned resolves fine and breaks on the first fetch_tools() (a --resolution lowest-direct leg in the matrix would stop it drifting again, but not gonna block on that).

Comment thread CHANGELOG.md Outdated
@@ -1,5 +1,11 @@
# Changelog

## 3.0.0 (Unreleased)

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.

My bad on this one, I didn't think about release-please when I asked for it. It drops the new release section in above the first version heading it finds, so we'd end up with this 3.0.0 (Unreleased) sitting under the real 3.0.0 for good. Could we drop it and put the removals in a BREAKING CHANGE: footer on the squash commit instead? That's the bit release-please actually reads.

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.

I think this one still wants to go. release-please searches for the first \n## <version> heading (DEFAULT_VERSION_HEADER_REGEX in its changelog updater) and inserts the new release above it, so on release this block ends up under the generated 3.0.0 for good. A BREAKING CHANGE: footer on the squash commit gets the same note in without the duplicate.

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.

Good call on release-please — reverted the manual header from CHANGELOG.md and added the BREAKING CHANGE footer to the commit message instead so release-please generates it cleanly on release.

Comment thread .github/workflows/ci.yaml
with:
path: sdk

- name: Checkout conformance suite

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 still checks out sdk-conformance main with no ref:, from my first pass on #2. Once this merges, any merge over there can turn main red here with nothing changing in this repo. Pin a sha and bump it on purpose? Happy for that to go in with ENG-2958 if you'd rather not hold this up.

@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.

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

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="pyproject.toml">

<violation number="1" location="pyproject.toml:41">
P3: The `langchain` extra floor was bumped to `langchain-core>=0.3.0`, but the `dev` extra still declares `langchain-core>=0.1.0`. The adapter and its tests cannot run on 0.1.x: `to_langchain()` passes a JSON Schema dict as `BaseTool.args_schema` (tools.py:677-679), which 0.1.x does not support, and `tests/test_models.py` reads `tool.args_schema["properties"]`, which only works once `args_schema` returns a schema dict. CI and `make install extras=1` use `uv sync --all-extras`, so resolution hides the stale floor, but anyone resolving `--extra dev` alone gets an unusable langchain-core. Bump the `dev` floor to match.</violation>
</file>

<file name="stackone_ai/toolset.py">

<violation number="1" location="stackone_ai/toolset.py:509">
P2: `fetch_accounts()` still leaks `UnicodeDecodeError` for a 2xx `/accounts` body containing invalid UTF-8. Catch it alongside `JSONDecodeError` so malformed responses remain `ToolsetLoadError`/`StackOneError`.</violation>
</file>

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

Re-trigger cubic

Comment thread stackone_ai/toolset.py Outdated
return cached
try:
body = response.json()
except json.JSONDecodeError as exc:

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2: fetch_accounts() still leaks UnicodeDecodeError for a 2xx /accounts body containing invalid UTF-8. Catch it alongside JSONDecodeError so malformed responses remain ToolsetLoadError/StackOneError.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At stackone_ai/toolset.py, line 509:

<comment>`fetch_accounts()` still leaks `UnicodeDecodeError` for a 2xx `/accounts` body containing invalid UTF-8. Catch it alongside `JSONDecodeError` so malformed responses remain `ToolsetLoadError`/`StackOneError`.</comment>

<file context>
@@ -503,7 +504,10 @@ def fetch_accounts(self) -> list[JsonDict]:
-        body = response.json()
+        try:
+            body = response.json()
+        except json.JSONDecodeError as exc:
+            raise ToolsetLoadError(f"Invalid JSON returned by {url}: {exc}") from exc
         accounts = body.get("data", body) if isinstance(body, dict) else body
</file context>
Suggested change
except json.JSONDecodeError as exc:
except (json.JSONDecodeError, UnicodeDecodeError) as exc:

Comment thread pyproject.toml
[project.optional-dependencies]
mcp = ["mcp>=1.3.0,<2.0.0"]
pydantic-ai = ["pydantic-ai-slim>=1.83.0,<2.0.0"]
langchain = ["langchain-core>=0.3.0"]

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P3: The langchain extra floor was bumped to langchain-core>=0.3.0, but the dev extra still declares langchain-core>=0.1.0. The adapter and its tests cannot run on 0.1.x: to_langchain() passes a JSON Schema dict as BaseTool.args_schema (tools.py:677-679), which 0.1.x does not support, and tests/test_models.py reads tool.args_schema["properties"], which only works once args_schema returns a schema dict. CI and make install extras=1 use uv sync --all-extras, so resolution hides the stale floor, but anyone resolving --extra dev alone gets an unusable langchain-core. Bump the dev floor to match.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At pyproject.toml, line 41:

<comment>The `langchain` extra floor was bumped to `langchain-core>=0.3.0`, but the `dev` extra still declares `langchain-core>=0.1.0`. The adapter and its tests cannot run on 0.1.x: `to_langchain()` passes a JSON Schema dict as `BaseTool.args_schema` (tools.py:677-679), which 0.1.x does not support, and `tests/test_models.py` reads `tool.args_schema["properties"]`, which only works once `args_schema` returns a schema dict. CI and `make install extras=1` use `uv sync --all-extras`, so resolution hides the stale floor, but anyone resolving `--extra dev` alone gets an unusable langchain-core. Bump the `dev` floor to match.</comment>

<file context>
@@ -38,7 +38,7 @@ include = ["stackone_ai", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.tom
 # it, so installing the SDK does not drag in a framework you do not use.
 [project.optional-dependencies]
-langchain = ["langchain-core>=0.1.0"]
+langchain = ["langchain-core>=0.3.0"]
 pydantic-ai = ["pydantic-ai-slim>=1.83.0"]
 examples = [
</file context>

@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.

Nothing on the three from earlier yet (the mcp floor, the CHANGELOG entry and pinning the conformance checkout), so not quite there. Did those get missed or are you pushing back on any of them?

New commit looks fine, and the nullable change is a good catch, a property actually called nullable was getting stripped before. cubic's UnicodeDecodeError one is real though: [\xff] from /accounts still comes out as a bare UnicodeDecodeError rather than a StackOneError (catching ValueError covers both). Neither that nor the nullable fix has a test, worth adding one each?

…SHA, add tests for nullable and non-JSON accounts
@willleeney

Copy link
Copy Markdown
Contributor Author

Thanks Stu — addressed all 4 points:

  1. MCP dependency floor: Bumped the dependency floor in pyproject.toml to mcp>=1.24.3,<2.0.0 to guarantee transport timeout and SSE timeout support.
  2. Pinned conformance checkout: Pinned the sdk-conformance checkout in .github/workflows/ci.yaml to full commit SHA 7e3b471ac947c9dd743ff6d47ad535afd5804a86 instead of unpinned HEAD.
  3. UnicodeDecodeError on /accounts + tests: Replaced json.JSONDecodeError with (ValueError, UnicodeDecodeError) in fetch_accounts() so invalid encoding or malformed JSON (like [\xff]) raises ToolsetLoadError. Added unit tests:
    • test_fetch_accounts_handles_invalid_or_malformed_encoding in tests/test_fetch_tools.py
    • test_preserves_field_named_nullable in tests/test_models.py
  4. CHANGELOG entry: Verified breaking changes entry in CHANGELOG.md under 3.0.0 (Unreleased) documenting the removal of connector and get_connectors().

@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.

1 existing issue remains and no new issues found across 6 files (changes from recent commits).

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

Re-trigger cubic

…NGE footer

BREAKING CHANGE: removed StackOneTool.connector property and Tools.get_connectors().

@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: Auto-approval blocked by 42 unresolved issues from previous reviews.

Re-trigger cubic

@willleeney
willleeney merged commit e53edf0 into main Sep 29, 2026
10 of 11 checks passed
@willleeney
willleeney deleted the chore/remove-nix-toolchain branch September 29, 2026 11:57
willleeney added a commit that referenced this pull request Sep 30, 2026
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.
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