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

[willleeney]

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

[aikido-pr-checks]

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}

[aikido-pr-checks]

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]

10 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="stackone_ai/types.py">

<violation number="1" location="stackone_ai/types.py:78">
P2: When `ExecuteConfig` receives a non-string method, `validate_method` raises `AttributeError` before Pydantic can validate the `str` field. Reject non-string values explicitly so invalid configuration consistently raises `ValidationError`.</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="stackone_ai/tools.py">

<violation number="1" location="stackone_ai/tools.py:165">
P2: When a served nested schema uses its own `nullable` keyword, `_strip_internal_keys()` removes it even though normalization adds the SDK marker only to top-level properties. Strip only the SDK-added marker, or preserve nested `nullable` values.</violation>

<violation number="2" location="stackone_ai/tools.py:374">
P2: When a served input schema has root constraints such as `additionalProperties`, `to_openai_function()` drops them because it rebuilds `parameters` from only `type` and `properties`. Preserve the root schema, replacing only `required`, so strict-schema consumers receive the catalog unchanged.</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>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

[cubic-dev-ai]

P2: When ExecuteConfig receives a non-string method, validate_method raises AttributeError before Pydantic can validate the str field. Reject non-string values explicitly so invalid configuration consistently raises ValidationError.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At stackone_ai/types.py, line 78:

<comment>When `ExecuteConfig` receives a non-string method, `validate_method` raises `AttributeError` before Pydantic can validate the `str` field. Reject non-string values explicitly so invalid configuration consistently raises `ValidationError`.</comment>

<file context>
@@ -0,0 +1,149 @@
+
+def validate_method(v: str) -> str:
+    """Validate HTTP method is uppercase and supported"""
+    method = v.upper()
+    if method not in {"GET", "POST", "PUT", "DELETE", "PATCH"}:
+        raise ValueError(f"Unsupported HTTP method: {method}")
</file context>

Suggested change

	method = v.upper()
	if not isinstance(v, str):
	raise ValueError(f"Unsupported HTTP method: {v}")
	method = v.upper()

[cubic-dev-ai]

P2: When a served nested schema uses its own nullable keyword, _strip_internal_keys() removes it even though normalization adds the SDK marker only to top-level properties. Strip only the SDK-added marker, or preserve nested nullable values.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At stackone_ai/tools.py, line 165:

<comment>When a served nested schema uses its own `nullable` keyword, `_strip_internal_keys()` removes it even though normalization adds the SDK marker only to top-level properties. Strip only the SDK-added marker, or preserve nested `nullable` values.</comment>

<file context>
@@ -0,0 +1,666 @@
+        return {
+            key: _strip_internal_keys(value)
+            for key, value in schema.items()
+            if key not in _INTERNAL_SCHEMA_KEYS
+        }
+    if isinstance(schema, list):
</file context>

[cubic-dev-ai]

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>

[cubic-dev-ai]

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>

[cubic-dev-ai]

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>

[Copilot]

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

[cubic-dev-ai]

1 issue found across 5 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="scripts/validate.sh">

<violation number="1" location="scripts/validate.sh:124">
P2: Any smoke failure whose combined output contains this text is reported as a skip, even when the text came from a later runtime or assertion failure. Have `run_smoke.sh` return a distinct status for an unpublished SDK pin, or otherwise validate that the resolver failed before skipping, so unrelated consumer failures remain failures.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Any smoke failure whose combined output contains this text is reported as a skip, even when the text came from a later runtime or assertion failure. Have run_smoke.sh return a distinct status for an unpublished SDK pin, or otherwise validate that the resolver failed before skipping, so unrelated consumer failures remain failures.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/validate.sh, line 124:

<comment>Any smoke failure whose combined output contains this text is reported as a skip, even when the text came from a later runtime or assertion failure. Have `run_smoke.sh` return a distinct status for an unpublished SDK pin, or otherwise validate that the resolver failed before skipping, so unrelated consumer failures remain failures.</comment>

<file context>
@@ -110,11 +109,23 @@ smoke() {
+    # A consumer pinned to an unpublished major cannot be installed, which says
+    # nothing about this SDK. Report it as not-run rather than as a failure here;
+    # it resolves itself once that version is on PyPI.
+    if grep -q 'only the following versions of stackone-ai are available' <<<"$out"; then
+        skip "$label" "consumer pins a stackone-ai version that is not on PyPI yet"
+        return
</file context>

[cubic-dev-ai]

5 issues found across 8 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="stackone_ai/tools.py">

<violation number="1" location="stackone_ai/tools.py:155">
P2: Catching `BaseException` turns interrupts and cancellation into `ToolsetLoadError`. Catch `Exception` instead; ordinary `ExceptionGroup` failures from the MCP task group are still handled.</violation>

<violation number="2" location="stackone_ai/tools.py:227">
P2: When an MCP `tools/call` result uses `structuredContent` without a text part, this parser drops the result. Read `structuredContent` as the primary result or as a fallback before parsing text content.</violation>

<violation number="3" location="stackone_ai/tools.py:774">
P2: When a caller passes a falsey non-dict argument such as `[]`, `arguments or {}` bypasses validation and invokes the tool with `{}`. Preserve non-`None` values before checking their type.</violation>

<violation number="4" location="stackone_ai/tools.py:777">
P1: After `Tools.set_account_id()` changes the inherited account ID, MCP calls still send the constructor's `_mcp_headers` and can target the previous tenant. Build the MCP headers from `get_account_id()` for each call, or update them in an overridden setter.</violation>
</file>

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

<violation number="1" location="stackone_ai/toolset.py:270">
P1: When the same connector is linked to multiple accounts, `execute()` can run a searched action against the wrong tenant. `search()` drops the originating account and this routing keeps only the connector, so carry account context with each result and execute through that account (or require an explicit account selection).</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: After Tools.set_account_id() changes the inherited account ID, MCP calls still send the constructor's _mcp_headers and can target the previous tenant. Build the MCP headers from get_account_id() for each call, or update them in an overridden setter.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At stackone_ai/tools.py, line 777:

<comment>After `Tools.set_account_id()` changes the inherited account ID, MCP calls still send the constructor's `_mcp_headers` and can target the previous tenant. Build the MCP headers from `get_account_id()` for each call, or update them in an overridden setter.</comment>

<file context>
@@ -605,6 +737,46 @@ def _build_action_headers(self, additional_headers: dict[str, Any] | None) -> di
+            parsed = arguments or {}
+        if not isinstance(parsed, dict):
+            raise ValueError("Tool arguments must be a JSON object")
+        return call_mcp_tool(self._endpoint, self._mcp_headers, self.name, parsed)
+
+
</file context>

Suggested change

	return call_mcp_tool(self._endpoint, self._mcp_headers, self.name, parsed)
	headers = dict(self._mcp_headers)
	account_id = self.get_account_id()
	if account_id:
	headers["x-account-id"] = account_id
	else:
	headers.pop("x-account-id", None)
	return call_mcp_tool(self._endpoint, headers, self.name, parsed)

[cubic-dev-ai]

P1: When the same connector is linked to multiple accounts, execute() can run a searched action against the wrong tenant. search() drops the originating account and this routing keeps only the connector, so carry account context with each result and execute through that account (or require an explicit account selection).

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 270:

<comment>When the same connector is linked to multiple accounts, `execute()` can run a searched action against the wrong tenant. `search()` drops the originating account and this routing keeps only the connector, so carry account context with each result and execute through that account (or require an explicit account selection).</comment>

<file context>
@@ -175,21 +200,81 @@ def _fetch_for_account(account: str | None) -> list[StackOneTool]:
-        if tool is None:
-            raise ToolsetLoadError(f'Tool "{tool_name}" not found')
-        return tool.execute(arguments or {})
+        connector = action_id.split("_")[0].lower()
+        for tool in self._meta_tools("_execute_action", account_ids):
+            if tool.name.split("_")[0].lower() == connector:
</file context>

[cubic-dev-ai]

P2: Catching BaseException turns interrupts and cancellation into ToolsetLoadError. Catch Exception instead; ordinary ExceptionGroup failures from the MCP task group are still handled.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At stackone_ai/tools.py, line 155:

<comment>Catching `BaseException` turns interrupts and cancellation into `ToolsetLoadError`. Catch `Exception` instead; ordinary `ExceptionGroup` failures from the MCP task group are still handled.</comment>

<file context>
@@ -148,7 +150,127 @@ async def _list() -> list[McpToolDefinition]:
-    return run_async(_list())
+    try:
+        return run_async(_list())
+    except BaseException as exc:
+        raise _describe_mcp_failure(exc, endpoint) from exc
+
</file context>

Suggested change

	except BaseException as exc:
	except Exception as exc:

[cubic-dev-ai]

P2: When a caller passes a falsey non-dict argument such as [], arguments or {} bypasses validation and invokes the tool with {}. Preserve non-None values before checking their type.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At stackone_ai/tools.py, line 774:

<comment>When a caller passes a falsey non-dict argument such as `[]`, `arguments or {}` bypasses validation and invokes the tool with `{}`. Preserve non-`None` values before checking their type.</comment>

<file context>
@@ -605,6 +737,46 @@ def _build_action_headers(self, additional_headers: dict[str, Any] | None) -> di
+        if isinstance(arguments, str):
+            parsed = json.loads(arguments)
+        else:
+            parsed = arguments or {}
+        if not isinstance(parsed, dict):
+            raise ValueError("Tool arguments must be a JSON object")
</file context>

Suggested change

	parsed = arguments or {}
	parsed = {} if arguments is None else arguments

[cubic-dev-ai]

P2: When an MCP tools/call result uses structuredContent without a text part, this parser drops the result. Read structuredContent as the primary result or as a fallback before parsing text content.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At stackone_ai/tools.py, line 227:

<comment>When an MCP `tools/call` result uses `structuredContent` without a text part, this parser drops the result. Read `structuredContent` as the primary result or as a fallback before parsing text content.</comment>

<file context>
@@ -148,7 +150,127 @@ async def _list() -> list[McpToolDefinition]:
+            back as an ordinary response with that flag set, so without this check the
+            error body is handed to the caller as though it were a success.
+    """
+    texts = [getattr(part, "text", "") for part in result.content]
+    payload = "".join(t for t in texts if t)
+    # Parts that are not text (images, embedded resources) have no `.text`; keep them
</file context>

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

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

Re-trigger cubic</sub>

[cubic-dev-ai]

10 issues found across 20 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=".github/workflows/ci.yaml">

<violation number="1" location=".github/workflows/ci.yaml:79">
P3: The new CI gate type-checks examples/, but the documented local pre-commit command (`make format`) still runs only `uv run ty check stackone_ai`. A contributor who follows the repo instructions can push example code that fails this new CI step without any local warning. Add `uv run ty check examples` to the Makefile `format` target (after the existing `ty check stackone_ai`) so the local fix-before-commit loop matches CI.</violation>
</file>

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

<violation number="1" location="tests/mocks/mcp-server.ts:79">
P3: The `MockMcpServerOptions.accountTools` docstring still says "Use 'default' for tools when no account header is provided", but this change makes that wrong: a missing header returns 400 before the lookup, and an unknown id returns 404. The `default` key now only matches a literal `x-account-id: default` request, which happens only because serve.ts's `/accounts` discovery lists id "default". Update the comment (and the createMcpApp example framing) to describe this so a future test author doesn't rely on the removed fallback.</violation>

<violation number="2" location="tests/mocks/mcp-server.ts:79">
P3: When an unknown account ID is a prototype property such as `constructor` or `__proto__`, `in` treats it as configured and the later tool loop throws a 500 instead of returning the intended 404. Use an own-property check for the account map.</violation>
</file>

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

<violation number="1" location="stackone_ai/tools.py:477">
P2: When a server labels invalid UTF-8 as JSON, `response.json()` raises `UnicodeDecodeError`, so malformed responses bypass this new error conversion. Catch `UnicodeDecodeError` alongside `JSONDecodeError` and preserve the `StackOneAPIError` response contract.</violation>

<violation number="2" location="stackone_ai/tools.py:640">
P2: When a LangChain MCP tool hits a transport failure, `_run` still propagates `ToolsetLoadError` because this handler catches only `StackOneError`. Catch `ToolsetError` too so `handle_tool_error` can process all MCP execution failures.</violation>
</file>

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

<violation number="1" location="tests/test_fetch_tools.py:828">
P2: This test cannot pass as written: the SDK raises `StackOneAPIError` for the mock's 404 on an unknown account, but the assertion expects `ToolsetError`. `_describe_mcp_failure` maps the HTTP 404 to `StackOneAPIError` (subclass of `StackOneError`, not `ToolsetError`), and `fetch_tools` re-raises it unchanged. Assert `StackOneAPIError` and check `status_code == 404`, matching the PR's goal of preserving MCP status codes.</violation>
</file>

<file name="examples/search_and_execute.py">

<violation number="1" location="examples/search_and_execute.py:57">
P2: The recommended generic example hard-codes `body.variables` after selecting an arbitrary action, so its `first` filter is silently ignored for most schemas. Build the arguments from `best['input_schema']` or use an action-specific request.</violation>
</file>

<file name="examples/openai_integration.py">

<violation number="1" location="examples/openai_integration.py:63">
P1: When multiple linked accounts expose the same action, this unscoped fetch lets name-only dispatch execute the model call against the last account. Scope the example to one account or preserve account-aware dispatch.</violation>
</file>

<file name="README.md">

<violation number="1" location="README.md:128">
P2: The new claim that every integration runs against any linked account is false for three advertised scripts, which still require `STACKONE_ACCOUNT_ID`. Update those scripts to use discovery or qualify this guidance.</violation>
</file>

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

<violation number="1" location="stackone_ai/toolset.py:355">
P1: When `execute()` uses the production `*_execute_action` MCP tool, it sends `action_id`, but the served schema requires `action_name`, so the call cannot execute the selected action. Send the selector field required by the served schema and update the mock to match the production contract.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: When multiple linked accounts expose the same action, this unscoped fetch lets name-only dispatch execute the model call against the last account. Scope the example to one account or preserve account-aware dispatch.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At examples/openai_integration.py, line 63:

<comment>When multiple linked accounts expose the same action, this unscoped fetch lets name-only dispatch execute the model call against the last account. Scope the example to one account or preserve account-aware dispatch.</comment>

<file context>
@@ -23,55 +32,56 @@
+    # Read-only list actions, whichever provider this key happens to reach. Keeping
+    # the filter narrow matters: an unfiltered catalog is hundreds of tools and will
+    # not fit a model's context.
+    tools = toolset.fetch_tools(actions=["*_list_*"])
+    if not tools:
+        raise SystemExit(
</file context>

[cubic-dev-ai]

P1: When execute() uses the production *_execute_action MCP tool, it sends action_id, but the served schema requires action_name, so the call cannot execute the selected action. Send the selector field required by the served schema and update the mock to match the production contract.

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 355:

<comment>When `execute()` uses the production `*_execute_action` MCP tool, it sends `action_id`, but the served schema requires `action_name`, so the call cannot execute the selected action. Send the selector field required by the served schema and update the mock to match the production contract.</comment>

<file context>
@@ -267,10 +336,23 @@ def execute(
+            # action_id LAST. Spreading arguments over it let a model-supplied
+            # "action_id" silently replace the action the caller pinned — the exact
+            # thing a host app pins it for.
+            return tool.execute({**(arguments or {}), "action_id": action_id})
 
         raise ToolsetLoadError(
</file context>

[cubic-dev-ai]

P3: The MockMcpServerOptions.accountTools docstring still says "Use 'default' for tools when no account header is provided", but this change makes that wrong: a missing header returns 400 before the lookup, and an unknown id returns 404. The default key now only matches a literal x-account-id: default request, which happens only because serve.ts's /accounts discovery lists id "default". Update the comment (and the createMcpApp example framing) to describe this so a future test author doesn't rely on the removed fallback.

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 79:

<comment>The `MockMcpServerOptions.accountTools` docstring still says "Use 'default' for tools when no account header is provided", but this change makes that wrong: a missing header returns 400 before the lookup, and an unknown id returns 404. The `default` key now only matches a literal `x-account-id: default` request, which happens only because serve.ts's `/accounts` discovery lists id "default". Update the comment (and the createMcpApp example framing) to describe this so a future test author doesn't rely on the removed fallback.</comment>

<file context>
@@ -72,7 +72,14 @@ export function createMcpApp(options: MockMcpServerOptions): HonoApp {
+		// that does not exist is the same permissiveness that hid the missing-header bug
+		// one line further up: any bug that sends a wrong, stale or mangled account id
+		// would be invisible. The real API refuses.
+		if (!(accountId in accountTools)) {
+			return c.json({ statusCode: 404, message: `Unknown account ${accountId}` }, 404);
+		}
</file context>

[cubic-dev-ai]

P3: When an unknown account ID is a prototype property such as constructor or __proto__, in treats it as configured and the later tool loop throws a 500 instead of returning the intended 404. Use an own-property check for the account map.

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 79:

<comment>When an unknown account ID is a prototype property such as `constructor` or `__proto__`, `in` treats it as configured and the later tool loop throws a 500 instead of returning the intended 404. Use an own-property check for the account map.</comment>

<file context>
@@ -72,7 +72,14 @@ export function createMcpApp(options: MockMcpServerOptions): HonoApp {
+		// that does not exist is the same permissiveness that hid the missing-header bug
+		// one line further up: any bug that sends a wrong, stale or mangled account id
+		// would be invisible. The real API refuses.
+		if (!(accountId in accountTools)) {
+			return c.json({ statusCode: 404, message: `Unknown account ${accountId}` }, 404);
+		}
</file context>

Suggested change

	if (!(accountId in accountTools)) {
	if (!Object.prototype.hasOwnProperty.call(accountTools, accountId)) {

[cubic-dev-ai]

4 issues found across 8 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="scripts/validate.sh">

<violation number="1" location="scripts/validate.sh:22">
P2: The new default ADK path `$SDK/../adk-26-ci` no longer matches the canonical downstream repo. The script's own header (line 8) still documents `ADK=/path/to/stackone-adk-plugin`, and this PR's migration notes name `stackone-adk-plugin` as the repo with prepared branches. A name like `adk-26-ci` reads as a CI/testing fork. Consequence: a local `make validate` run with the plugin checked out under the documented name `stackone-adk-plugin` finds no `adk-26-ci` directory and silently SKIPs the ADK smoke while still exiting 0 ("VALIDATE: PASS (with N skipped)"), so ADK coverage drops without any signal. If the fork is the intended default, update the header usage comment and confirm `adk-26-ci` is a stable repo; otherwise revert the default to `stackone-adk-plugin`.</violation>
</file>

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

<violation number="1" location="stackone_ai/types.py:131">
P2: When a provider returns a filename longer than 255 bytes without a short ASCII suffix, this guard still returns an overlong filename. Callers saving the download can then hit filesystem name-length errors; calculate the retained suffix in bytes or truncate the complete UTF-8 byte string.</violation>
</file>

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

<violation number="1" location="tests/test_models.py:230">
P2: Lines 230-231 exceed the configured ruff line length of 110 (measured 111 and 113 chars) and would be rewritten by `make format`, so the CI ruff format/lint check fails as committed. Wrap the comparison operands so each line stays within the limit.</violation>
</file>

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

<violation number="1" location="stackone_ai/toolset.py:449">
P2: When `base_url` is malformed, `fetch_accounts()` still leaks `httpx.InvalidURL` because this handler catches only `httpx.HTTPError`. Catch `httpx.InvalidURL` as well so direct account discovery consistently raises `ToolsetLoadError.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The new default ADK path $SDK/../adk-26-ci no longer matches the canonical downstream repo. The script's own header (line 8) still documents ADK=/path/to/stackone-adk-plugin, and this PR's migration notes name stackone-adk-plugin as the repo with prepared branches. A name like adk-26-ci reads as a CI/testing fork. Consequence: a local make validate run with the plugin checked out under the documented name stackone-adk-plugin finds no adk-26-ci directory and silently SKIPs the ADK smoke while still exiting 0 ("VALIDATE: PASS (with N skipped)"), so ADK coverage drops without any signal. If the fork is the intended default, update the header usage comment and confirm adk-26-ci is a stable repo; otherwise revert the default to stackone-adk-plugin.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/validate.sh, line 22:

<comment>The new default ADK path `$SDK/../adk-26-ci` no longer matches the canonical downstream repo. The script's own header (line 8) still documents `ADK=/path/to/stackone-adk-plugin`, and this PR's migration notes name `stackone-adk-plugin` as the repo with prepared branches. A name like `adk-26-ci` reads as a CI/testing fork. Consequence: a local `make validate` run with the plugin checked out under the documented name `stackone-adk-plugin` finds no `adk-26-ci` directory and silently SKIPs the ADK smoke while still exiting 0 ("VALIDATE: PASS (with N skipped)"), so ADK coverage drops without any signal. If the fork is the intended default, update the header usage comment and confirm `adk-26-ci` is a stable repo; otherwise revert the default to `stackone-adk-plugin`.</comment>

<file context>
@@ -19,7 +19,7 @@ set -uo pipefail
 SDK="$(dirname "$HERE")"
 CONFORMANCE="${CONFORMANCE:-$SDK/../sdk-conformance}"
-ADK="${ADK:-$SDK/../stackone-adk-plugin}"
+ADK="${ADK:-$SDK/../adk-26-ci}"
 
 failed=0
</file context>

Suggested change

	ADK="${ADK:-$SDK/../adk-26-ci}"
	ADK="${ADK:-$SDK/../stackone-adk-plugin}"

[cubic-dev-ai]

P2: When a provider returns a filename longer than 255 bytes without a short ASCII suffix, this guard still returns an overlong filename. Callers saving the download can then hit filesystem name-length errors; calculate the retained suffix in bytes or truncate the complete UTF-8 byte string.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At stackone_ai/types.py, line 131:

<comment>When a provider returns a filename longer than 255 bytes without a short ASCII suffix, this guard still returns an overlong filename. Callers saving the download can then hit filesystem name-length errors; calculate the retained suffix in bytes or truncate the complete UTF-8 byte string.</comment>

<file context>
@@ -118,8 +120,19 @@ def _safe_basename(name: str | None) -> str | None:
+    base = "".join(ch for ch in base if unicodedata.category(ch) not in ("Cc", "Cf")).strip()
+    if base in ("", ".", ".."):
+        return None
+    if len(base.encode("utf-8", "ignore")) > 255:
+        stem, dot, suffix = base.rpartition(".")
+        keep = 255 - len(dot + suffix)
</file context>

Suggested change

	if len(base.encode("utf-8", "ignore")) > 255:
	stem, dot, suffix = base.rpartition(".")
	keep = 255 - len(dot + suffix)
	base = (stem.encode("utf-8")[: max(keep, 1)].decode("utf-8", "ignore")) + dot + suffix
	if len(base.encode("utf-8", "ignore")) > 255:
	stem, dot, suffix = base.rpartition(".")
	suffix_bytes = (dot + suffix).encode("utf-8", "ignore")
	if len(suffix_bytes) >= 255:
	base = suffix_bytes[:255].decode("utf-8", "ignore")
	else:
	keep = 255 - len(suffix_bytes)
	stem = stem.encode("utf-8", "ignore")[:keep].decode("utf-8", "ignore")
	base = stem + dot + suffix

[cubic-dev-ai]

P2: Lines 230-231 exceed the configured ruff line length of 110 (measured 111 and 113 chars) and would be rewritten by make format, so the CI ruff format/lint check fails as committed. Wrap the comparison operands so each line stays within the limit.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At tests/test_models.py, line 230:

<comment>Lines 230-231 exceed the configured ruff line length of 110 (measured 111 and 113 chars) and would be rewritten by `make format`, so the CI ruff format/lint check fails as committed. Wrap the comparison operands so each line stays within the limit.</comment>

<file context>
@@ -229,12 +227,8 @@ def test_to_langchain_multiple_tools(mock_tool):
-    assert set(langchain_tools[1].args_schema.__annotations__.keys()) == set(
-        second_tool.parameters.properties.keys()
-    )
+    assert set(langchain_tools[0].args_schema["properties"]) == set(mock_tool.parameters.properties.keys())
+    assert set(langchain_tools[1].args_schema["properties"]) == set(second_tool.parameters.properties.keys())
 
</file context>

Suggested change

	assert set(langchain_tools[0].args_schema["properties"]) == set(mock_tool.parameters.properties.keys())
	assert set(langchain_tools[1].args_schema["properties"]) == set(second_tool.parameters.properties.keys())
	assert set(langchain_tools[0].args_schema["properties"]) == set(
	mock_tool.parameters.properties.keys()
	)
	assert set(langchain_tools[1].args_schema["properties"]) == set(
	second_tool.parameters.properties.keys()
	)

[cubic-dev-ai]

P2: When base_url is malformed, fetch_accounts() still leaks httpx.InvalidURL because this handler catches only httpx.HTTPError. Catch httpx.InvalidURL as well so direct account discovery consistently raises `ToolsetLoadError.

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 449:

<comment>When `base_url` is malformed, `fetch_accounts()` still leaks `httpx.InvalidURL` because this handler catches only `httpx.HTTPError`. Catch `httpx.InvalidURL` as well so direct account discovery consistently raises `ToolsetLoadError.</comment>

<file context>
@@ -401,14 +437,21 @@ def fetch_accounts(self) -> list[JsonDict]:
+                },
+                timeout=self._timeout,
+            )
+        except httpx.HTTPError as exc:
+            # The only public method with no error handling at all: a dead host, a bad
+            # scheme or a timeout leaked httpx's own exception type straight out of the
</file context>

Suggested change

	except httpx.HTTPError as exc:
	except (httpx.HTTPError, httpx.InvalidURL) as exc:

[cubic-dev-ai]

1 issue found across 2 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="stackone_ai/toolset.py">

<violation number="1" location="stackone_ai/toolset.py:137">
P2: When an account discovery is in flight during `clear_catalog_cache()`, the stale discovery can repopulate the cache after the clear. Make discovery generation-aware: capture the generation before `fetch_accounts()` and retry instead of publishing or caching results when the generation changes.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When an account discovery is in flight during clear_catalog_cache(), the stale discovery can repopulate the cache after the clear. Make discovery generation-aware: capture the generation before fetch_accounts() and retry instead of publishing or caching results when the generation changes.

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 137:

<comment>When an account discovery is in flight during `clear_catalog_cache()`, the stale discovery can repopulate the cache after the clear. Make discovery generation-aware: capture the generation before `fetch_accounts()` and retry instead of publishing or caching results when the generation changes.</comment>

<file context>
@@ -124,8 +133,10 @@ def clear_catalog_cache(self) -> None:
-        self._catalog_cache.clear()
-        self._discovered_account_ids = None
+        with self._cache_lock:
+            self._cache_generation += 1
+            self._catalog_cache.clear()
+            self._discovered_account_ids = None
</file context>

[cubic-dev-ai]

8 issues found across 14 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=".env.example">

<violation number="1" location=".env.example:4">
P3: The comment is inaccurate: langchain_integration.py, langgraph_integration.py, and pydantic_ai_integration.py each require STACKONE_ACCOUNT_ID (they print "Set STACKONE_ACCOUNT_ID..." and return when absent), not just auth_management.py. Only openai_integration.py actually runs without it, since fetch_tools() discovers accounts from the key. Update the comment so users don't skip the variable and hit failures in the listed examples.</violation>
</file>

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

<violation number="1" location=".github/workflows/release.yaml:71">
P1: A failed repository CI gate can still publish to PyPI because this job depends only on `release-please` and reruns pytest, not `ci-ok` or the strict-schema conformance checks. Gate `uv publish` on the complete required CI result, or run the same conformance and quality checks in this workflow before publishing.</violation>

<violation number="2" location=".github/workflows/release.yaml:72">
P1: When release-please reports no release, this job still runs because the `"false"` output string is truthy in a GitHub Actions condition. Compare the output with `'true'` before starting the publish job.</violation>
</file>

<file name="CLAUDE.md">

<violation number="1" location="CLAUDE.md:210">
P3: This sentence inaccurately states that str(StackOneAPIError) leads with the server's own message. In the code, every StackOneAPIError message is prefixed with SDK-side text ("MCP request to ... failed with", "Tool 'name' failed:", "Listing accounts at ... failed with") and the server body only follows that prefix. Reword to reflect that the message prefixes the SDK's own context, or drop the claim.</violation>
</file>

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

<violation number="1" location=".github/workflows/ci.yaml:5">
P2: Pushes to non-main branches no longer run CI. A branch pushed before opening a PR, or one never opened as a PR, gets no tests, lint, or secret scan despite the repository's documented every-push CI contract. Run this workflow for all branch pushes (or change the documented contract).</violation>

<violation number="2" location=".github/workflows/ci.yaml:151">
P1: Fork pull requests cannot pass `ci-ok`: GitHub withholds `CONFORMANCE_REPO_TOKEN` from fork-triggered workflows, the conformance job exits for the missing token, and this new `needs` list propagates that failure. Make the required gate fork-safe by running the private conformance check in a trusted context or handling fork PRs without treating the unavailable secret-dependent result as a failure.</violation>
</file>

<file name="README.md">

<violation number="1" location="README.md:232">
P2: The LangGraph example now installs `langchain` but drops `langgraph`, while the code below it calls `create_agent` from `langchain.agents`, which requires langgraph at runtime. A user following the README will hit an import error. Restore `langgraph` in the install line.</violation>

<violation number="2" location="README.md:261">
P2: Without an `account_ids` filter, this action can produce one tool per active account, not exactly one. Add an account scope to make the example deterministic or describe the per-account result; otherwise `get_tool()` can route to the last account listed.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: A failed repository CI gate can still publish to PyPI because this job depends only on release-please and reruns pytest, not ci-ok or the strict-schema conformance checks. Gate uv publish on the complete required CI result, or run the same conformance and quality checks in this workflow before publishing.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .github/workflows/release.yaml, line 71:

<comment>A failed repository CI gate can still publish to PyPI because this job depends only on `release-please` and reruns pytest, not `ci-ok` or the strict-schema conformance checks. Gate `uv publish` on the complete required CI result, or run the same conformance and quality checks in this workflow before publishing.</comment>

<file context>
@@ -44,17 +63,46 @@ jobs:
+  # so a red main still merged the release PR and shipped to PyPI. The suite runs
+  # again here against the exact commit being published.
+  publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created }}
+    runs-on: ubuntu-latest
</file context>

[cubic-dev-ai]

P1: Fork pull requests cannot pass ci-ok: GitHub withholds CONFORMANCE_REPO_TOKEN from fork-triggered workflows, the conformance job exits for the missing token, and this new needs list propagates that failure. Make the required gate fork-safe by running the private conformance check in a trusted context or handling fork PRs without treating the unavailable secret-dependent result as a failure.

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 151:

<comment>Fork pull requests cannot pass `ci-ok`: GitHub withholds `CONFORMANCE_REPO_TOKEN` from fork-triggered workflows, the conformance job exits for the missing token, and this new `needs` list propagates that failure. Make the required gate fork-safe by running the private conformance check in a trusted context or handling fork PRs without treating the unavailable secret-dependent result as a failure.</comment>

<file context>
@@ -138,13 +144,25 @@ jobs:
+  # missing when a job is renamed or a matrix entry is added, and nothing notices.
+  ci-ok:
+    if: always()
+    needs: [gitleaks, ci, conformance]
+    runs-on: ubuntu-latest
+    steps:
</file context>

[cubic-dev-ai]

P1: When release-please reports no release, this job still runs because the "false" output string is truthy in a GitHub Actions condition. Compare the output with 'true' before starting the publish job.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .github/workflows/release.yaml, line 72:

<comment>When release-please reports no release, this job still runs because the `"false"` output string is truthy in a GitHub Actions condition. Compare the output with `'true'` before starting the publish job.</comment>

<file context>
@@ -44,17 +63,46 @@ jobs:
+  # again here against the exact commit being published.
+  publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created }}
+    runs-on: ubuntu-latest
+    # Configure a required reviewer on this environment in the repository settings.
</file context>

Suggested change

	if: ${{ needs.release-please.outputs.release_created }}
	if: ${{ needs.release-please.outputs.release_created == 'true' }}

[cubic-dev-ai]

P2: The LangGraph example now installs langchain but drops langgraph, while the code below it calls create_agent from langchain.agents, which requires langgraph at runtime. A user following the README will hit an import error. Restore langgraph in the install line.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At README.md, line 232:

<comment>The LangGraph example now installs `langchain` but drops `langgraph`, while the code below it calls `create_agent` from `langchain.agents`, which requires langgraph at runtime. A user following the README will hit an import error. Restore `langgraph` in the install line.</comment>

<file context>
@@ -214,7 +229,7 @@ print(agent.run_sync("Use a tool to list a few records, then summarise them.").o
 
 ```bash
-uv add 'stackone-ai[langchain]' langgraph langchain-openai
+uv add 'stackone-ai[langchain]' langchain langchain-openai

</file context>

</details>

```suggestion
uv add 'stackone-ai[langchain]' langchain langchain-openai langgraph

[cubic-dev-ai]

P2: Pushes to non-main branches no longer run CI. A branch pushed before opening a PR, or one never opened as a PR, gets no tests, lint, or secret scan despite the repository's documented every-push CI contract. Run this workflow for all branch pushes (or change the documented contract).

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 5:

<comment>Pushes to non-main branches no longer run CI. A branch pushed before opening a PR, or one never opened as a PR, gets no tests, lint, or secret scan despite the repository's documented every-push CI contract. Run this workflow for all branch pushes (or change the documented contract).</comment>

<file context>
@@ -2,6 +2,8 @@ name: CI
 
 on:
   push:
+    branches:
+      - main
   pull_request:
</file context>

[cubic-dev-ai]

P2: Without an account_ids filter, this action can produce one tool per active account, not exactly one. Add an account scope to make the example deterministic or describe the per-account result; otherwise get_tool() can route to the last account listed.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At README.md, line 261:

<comment>Without an `account_ids` filter, this action can produce one tool per active account, not exactly one. Add an account scope to make the example deterministic or describe the per-account result; otherwise `get_tool()` can route to the last account listed.</comment>

<file context>
@@ -240,12 +255,12 @@ applied locally to one cached listing — changing a filter never refetches.
+toolset.fetch_tools()                                    # every tool, every active account
+toolset.fetch_tools(providers=["linear"])                # one connector
+toolset.fetch_tools(actions=["linear_list_*"])           # one connector's list actions
+toolset.fetch_tools(actions=["linear_get_issue"])        # exactly one tool
 toolset.fetch_tools(providers=["linear"],
-                    actions=["*_get_*"])                 #  23  (AND)
</file context>

Suggested change

	toolset.fetch_tools(actions=["linear_get_issue"]) # exactly one tool
	toolset.fetch_tools(actions=["linear_get_issue"], account_ids=["acc-123"]) # exactly one tool for this account

[cubic-dev-ai]

P3: The comment is inaccurate: langchain_integration.py, langgraph_integration.py, and pydantic_ai_integration.py each require STACKONE_ACCOUNT_ID (they print "Set STACKONE_ACCOUNT_ID..." and return when absent), not just auth_management.py. Only openai_integration.py actually runs without it, since fetch_tools() discovers accounts from the key. Update the comment so users don't skip the variable and hit failures in the listed examples.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .env.example, line 4:

<comment>The comment is inaccurate: langchain_integration.py, langgraph_integration.py, and pydantic_ai_integration.py each require STACKONE_ACCOUNT_ID (they print "Set STACKONE_ACCOUNT_ID..." and return when absent), not just auth_management.py. Only openai_integration.py actually runs without it, since fetch_tools() discovers accounts from the key. Update the comment so users don't skip the variable and hit failures in the listed examples.</comment>

<file context>
@@ -1,6 +1,8 @@
+# Required for all examples. Account ids are discovered from the key.
 STACKONE_API_KEY=your-stackone-api-key
+
+# Only examples/auth_management.py needs a specific account
 STACKONE_ACCOUNT_ID=your-account-id
 
</file context>

Suggested change

	# Only examples/auth_management.py needs a specific account
	# Needed by examples that scope to one account (auth_management, langchain_integration, langgraph_integration, pydantic_ai_integration); openai_integration discovers accounts from the key

[cubic-dev-ai]

P3: This sentence inaccurately states that str(StackOneAPIError) leads with the server's own message. In the code, every StackOneAPIError message is prefixed with SDK-side text ("MCP request to ... failed with", "Tool 'name' failed:", "Listing accounts at ... failed with") and the server body only follows that prefix. Reword to reflect that the message prefixes the SDK's own context, or drop the claim.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At CLAUDE.md, line 210:

<comment>This sentence inaccurately states that str(StackOneAPIError) leads with the server's own message. In the code, every StackOneAPIError message is prefixed with SDK-side text ("MCP request to ... failed with", "Tool 'name' failed:", "Listing accounts at ... failed with") and the server body only follows that prefix. Reword to reflect that the message prefixes the SDK's own context, or drop the claim.</comment>

<file context>
@@ -159,28 +190,43 @@ via release-please after a merge to main, never from a developer machine.
-- **File downloads**: non-JSON responses return raw bytes plus metadata, not decoded text
+- **Error handling**: `StackOneError`/`StackOneAPIError` and `ToolsetError`/
+  `ToolsetConfigError`/`ToolsetLoadError` are two **unrelated** hierarchies in
+  `types.py`. `str(StackOneAPIError)` leads with the server's own message.
+- **File downloads**: non-JSON responses return raw bytes plus metadata. The filename
+  comes from an attacker-controllable header and is reduced to a safe basename.
</file context>

Suggested change

	`types.py`. `str(StackOneAPIError)` leads with the server's own message.
	`types.py`. `str(StackOneAPIError)` prefixes its own context and appends the server's body.

[cubic-dev-ai]

4 issues found across 15 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=".github/dependabot.yaml">

<violation number="1" location=".github/dependabot.yaml:42">
P3: The npm `ignore` covers only `@modelcontextprotocol/sdk`, but `zod`, `hono`, and `@hono/mcp` are pinned exactly in `package.json` under the mock-server policy that these pins must never be changed (mock must model what the real API demands). Dependabot will open weekly PRs bumping those three exact pins, churning the very dependencies the repo pins for behavioral stability and raising the risk of silent mock drift. Either add them to `ignore` too, or document in the comment why they are safe to bump (e.g. CI integration tests cover them).</violation>

<violation number="2" location=".github/dependabot.yaml:42">
P2: This ignore rule blocks all Dependabot updates for `@modelcontextprotocol/sdk`, not just major releases. Patch and security updates will never be proposed; add `version-update:semver-major` under `update-types` if only major upgrades must remain blocked.</violation>
</file>

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

<violation number="1" location="stackone_ai/tools.py:1074">
P1: When the catalog contains the same action name for multiple active accounts, this lookup silently executes the last-listed account's tool. Require an account-scoped catalog or reject ambiguous names before dispatching OpenAI calls.</violation>
</file>

<file name="CLAUDE.md">

<violation number="1" location="CLAUDE.md:210">
P2: The new error-handling rule is false for public tool methods: invalid tool arguments raise `ValueError`, and missing optional adapters raise `ImportError`. Either wrap those failures in `StackOneError` or document these exceptions instead of telling callers that only `StackOneError` can escape.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: When the catalog contains the same action name for multiple active accounts, this lookup silently executes the last-listed account's tool. Require an account-scoped catalog or reject ambiguous names before dispatching OpenAI calls.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At stackone_ai/tools.py, line 1074:

<comment>When the catalog contains the same action name for multiple active accounts, this lookup silently executes the last-listed account's tool. Require an account-scoped catalog or reject ambiguous names before dispatching OpenAI calls.</comment>

<file context>
@@ -990,6 +1050,40 @@ def to_openai(self) -> list[JsonDict]:
+        messages: list[JsonDict] = []
+        for call in tool_calls or []:
+            call_id, name, arguments = _read_openai_tool_call(call)
+            tool = self.get_tool(name)
+            if tool is None:
+                result: Any = {"error": f"Unknown tool {name!r}"}
</file context>

[cubic-dev-ai]

P2: This ignore rule blocks all Dependabot updates for @modelcontextprotocol/sdk, not just major releases. Patch and security updates will never be proposed; add version-update:semver-major under update-types if only major upgrades must remain blocked.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .github/dependabot.yaml, line 42:

<comment>This ignore rule blocks all Dependabot updates for `@modelcontextprotocol/sdk`, not just major releases. Patch and security updates will never be proposed; add `version-update:semver-major` under `update-types` if only major upgrades must remain blocked.</comment>

<file context>
@@ -23,6 +24,23 @@ updates:
+    labels:
+      - dependencies
+    ignore:
+      - dependency-name: "@modelcontextprotocol/sdk"
+
   # GitHub Actions
</file context>

Suggested change

	- dependency-name: "@modelcontextprotocol/sdk"
	- dependency-name: "@modelcontextprotocol/sdk"
	update-types:
	- version-update:semver-major

[cubic-dev-ai]

P2: The new error-handling rule is false for public tool methods: invalid tool arguments raise ValueError, and missing optional adapters raise ImportError. Either wrap those failures in StackOneError or document these exceptions instead of telling callers that only StackOneError can escape.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At CLAUDE.md, line 210:

<comment>The new error-handling rule is false for public tool methods: invalid tool arguments raise `ValueError`, and missing optional adapters raise `ImportError`. Either wrap those failures in `StackOneError` or document these exceptions instead of telling callers that only `StackOneError` can escape.</comment>

<file context>
@@ -205,9 +205,10 @@ tools = toolset.fetch_tools(providers=["linear"], actions=["*_list_*"])
-  `types.py`. `str(StackOneAPIError)` leads with the server's own message.
+- **Error handling**: everything derives from `StackOneError` (`types.py`) — both
+  `StackOneAPIError` and the `ToolsetError` family. Nothing outside that hierarchy
+  should escape a public method. `str(StackOneAPIError)` leads with the server's own
+  message.
 - **File downloads**: non-JSON responses return raw bytes plus metadata. The filename
</file context>

[cubic-dev-ai]

P3: The npm ignore covers only @modelcontextprotocol/sdk, but zod, hono, and @hono/mcp are pinned exactly in package.json under the mock-server policy that these pins must never be changed (mock must model what the real API demands). Dependabot will open weekly PRs bumping those three exact pins, churning the very dependencies the repo pins for behavioral stability and raising the risk of silent mock drift. Either add them to ignore too, or document in the comment why they are safe to bump (e.g. CI integration tests cover them).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .github/dependabot.yaml, line 42:

<comment>The npm `ignore` covers only `@modelcontextprotocol/sdk`, but `zod`, `hono`, and `@hono/mcp` are pinned exactly in `package.json` under the mock-server policy that these pins must never be changed (mock must model what the real API demands). Dependabot will open weekly PRs bumping those three exact pins, churning the very dependencies the repo pins for behavioral stability and raising the risk of silent mock drift. Either add them to `ignore` too, or document in the comment why they are safe to bump (e.g. CI integration tests cover them).</comment>

<file context>
@@ -23,6 +24,23 @@ updates:
+    labels:
+      - dependencies
+    ignore:
+      - dependency-name: "@modelcontextprotocol/sdk"
+
   # GitHub Actions
</file context>

[StuBehan]

Ran this locally: 247 tests pass, ruff and ty clean, and py.typed still ships in the wheel (checked, dropping the force-include is fine). pnpm test:python in the conformance repo is a clean PASS too - 11/11, inv 9, inv 10, schema pass-through. Security fixes all look right to me and the comments explaining why are solid.

Three things I'd want before merge, left inline. The schema one is the main one, I don't think the byte-for-byte claim holds against the real server. The other two are that the conformance gate has never actually run in CI - missing secret, and a pnpm setup break sitting behind it.

I'd do the fixture fix in StackOneHQ/sdk-conformance#2 first so the schema regression fails the harness rather than being fixed on trust.

[StuBehan]

This only carries type and properties, so to_openai_function() rebuilds the root as {type, properties, required} and anything else at the root goes. UCA emits $schema: 2020-12 at the root of every non-empty tool's inputSchema (input-json-schema.util.ts:264), so we're dropping that on every tool today.

Worse - I fed it a schema with $defs and a property using $ref: "#/$defs/Money". The $ref survives and $defs doesn't, so the model gets a dangling ref that OpenAI strict mode won't take.

Can we keep the served root here and only swap required? Also want to double check what the 139-tool byte-for-byte comparison was actually comparing, feels like it must have been normalising the root away 🤔

[StuBehan]

Dependabot and fork PRs never get repo secrets, so conformance exits 1 on the token check and this needs takes ci-ok down with it. If ci-ok is the single required check then every dependabot PR is blocked forever, which is a shame given we just moved the python ecosystem to uv so they could actually pass. Can we treat "this context can't have the secret" as not-run rather than a failure?

[StuBehan]

There's no version: here and sdk-conformance's package.json has no packageManager or devEngines, so action-setup's readTargetVersion throws No pnpm version is specified. We haven't seen it because the token check fails first. Worth fixing on the conformance side (StackOneHQ/sdk-conformance#2) or pinning version: here, otherwise this job still won't run once the secret is set.

[StuBehan]

On a *_execute_action meta tool self.parameters.properties is action_id/path/query/body/headers, so the headers_* allowlist is always empty and every header gets dropped. Checked it - meta tool keeps {}, an rpc tool with a declared headers_x-custom-tenant keeps it.

Fine as a default. But the comment says it'll work with no SDK release the day an action needs a header, and on the search/execute path it won't. Correct the comment, or build the allowlist from the target action's schema?

[StuBehan]

This still splits on the first _, so browser_linkedin_search_people comes out as browser - the same thing _filter_by_provider and _connector_of got fixed for. get_connectors() feeds off it. Worth pulling the three into one helper?

[StuBehan]

If the server ever serves one property that isn't path|query|body|headers-prefixed, this flips off for the whole schema and every prefixed key falls into the body. Tried it with {path_id, raw_extra} and arg path_id, got body: {path_id: 'abc'} with path empty. Agree all is right over any, but should we log when it flips? Silent is rough on whoever's debugging a missing path param.

[StuBehan]

This is the headline "api key is enough" path, and it's one MCP listing per active account, 10 at a time. /accounts has no limit on the bare-array branch so we'll see all of them - an org with 50 linked accounts pays 50 round trips on the first fetch_tools() and gets 50x the catalog into the model. Do we want a cap, or at least a note in the README?