From df47b7f1abbe584e07a29fba7cc0d4b1d1c39340 Mon Sep 17 00:00:00 2001 From: S2D2 Date: Tue, 10 Nov 2026 20:28:40 +0000 Subject: [PATCH 1/3] docs: align CLAUDE.md and make format with the code and CI - The Key Patterns sample read hit["account_id"], which no search hit has; hits carry available_accounts, as README and MIGRATION show. It raised KeyError. - top_k caps the merged result (toolset.search slices hits[:top_k]), not per connector. - submit_feedback() goes through min(scope), the lowest account id, not the first. - Dev tools live in the dev extra, so the add command is uv add --optional dev. - CI type checks examples too; make format now does the same, so a clean local run cannot still fail CI. Co-Authored-By: Claude Opus 5.5 Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com> --- CLAUDE.md | 8 ++++---- Makefile | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ecb952f2..0d4dd011 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -101,7 +101,7 @@ Order: standard library, then third-party, then local. Use `uv` for all dependency management. ```bash -uv add --dev pytest # dev dependency +uv add --optional dev pytest # dev dependency (the `dev` extra) uv add pydantic # package dependency uv run pytest # run from root ``` @@ -213,7 +213,7 @@ toolset = StackOneToolSet() # reads STACKONE_API_KEY; accounts are discovered hits = toolset.search("list recent comments", top_k=3) hit = hits[0] if hits else None session_id = hit.get("session_id") if hit else None -account_ids = [hit["account_id"]] if hit else None +account_ids = [hit["available_accounts"][0]["id"]] if hit else None toolset.execute( "linear_list_comments", {"body": {"variables": {"first": 25}}}, account_ids=account_ids, session_id=session_id ) @@ -225,13 +225,13 @@ tools = toolset.fetch_tools(providers=["linear"], actions=["*_list_*"]) - `providers` matches a full connector prefix, case-insensitively. `actions` is a case-sensitive glob. **A leading `!` is not exclusion syntax** — it is a literal character, so `["*", "!*_delete_*"]` matches every tool. -- `top_k` is per connector, and must be 1..50. +- `top_k` caps the whole result, and must be 1..50. - `stackone_submit_feedback` is one global tool the server lists with every account's catalog, in both modes, when feedback is enabled. Like every tool it is a `StackOneMcpTool`; unlike the others it is deduped to one across accounts. It is never invented client-side — when the server omits it, `submit_feedback()` raises. `submit_feedback()` lists one account in `search_execute` mode and makes one - `tools/call`, through the first account (as given, else in `GET /accounts` order). + `tools/call`, through the lowest account id in scope. - `Tools.get_tool()` returns the first tool listed under a name, as Node's `getTool()`. - `session_id` is copied onto each `search()` hit and forwarded by `execute()` / `submit_feedback()` only when given. Optional wire keys are omitted, never null. diff --git a/Makefile b/Makefile index 61569c83..6ddb589e 100644 --- a/Makefile +++ b/Makefile @@ -30,7 +30,7 @@ install: format: uv run ruff check --fix . uv run ruff format . - uv run ty check stackone_ai + uv run ty check stackone_ai examples ## Run all tests test: From 32e0fed78b58c5f2d8a506983f0e0a925a83d6df Mon Sep 17 00:00:00 2001 From: S2D2 Date: Wed, 11 Nov 2026 00:54:15 +0000 Subject: [PATCH 2/3] docs: name the global meta tools and run the hit's own action CLAUDE.md still described per-connector _search_actions / _execute_action tools, while the toolset uses one stackone_search_actions / stackone_execute_action pair across every account in scope. The Key Patterns example pinned the first hit's account but ran a hardcoded Linear action, so the account and action could come from different connectors. make format now type-checks examples, which needs the dev and examples extras. Co-Authored-By: Claude Opus 5.5 Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com> --- CLAUDE.md | 28 +++++++++++++++------------- Makefile | 2 +- 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0d4dd011..da461109 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,8 +37,9 @@ account is used. There is no OpenAPI parsing and no client-side search. The same actions are reachable two ways, with **different argument shapes**: -- `toolset.search()` + `toolset.execute(action_id, args)` drives the per-connector - `_search_actions` / `_execute_action` meta tools (`?tool-mode=search_execute`). +- `toolset.search()` + `toolset.execute(action_id, args)` drives the + `stackone_search_actions` / `stackone_execute_action` meta tools, one pair across every + account in scope (`?tool-mode=search_execute`). Arguments are the **nested** form: `{"body": {"variables": {...}}}`. - `toolset.fetch_tools()` + `tool.execute(args)` calls per-action tools. Arguments are the keys the tool's served schema names. @@ -50,7 +51,7 @@ a wrong key returns a normal-looking success with your filter ignored. Results follow one rule for every tool (`parse_tool_result`): text parts win, else `structuredContent`; `isError` raises `StackOneAPIError` with the payload's status. A success is returned exactly as the server wrote it, never unwrapped: for an action -tool, `*_execute_action` and feedback that is UCA's `{"isError": false, "result": ...}` +tool, `stackone_execute_action` and feedback that is UCA's `{"isError": false, "result": ...}` (optionally with `defenderMetadata` / `policyMetadata`); search results are bare JSON. Keep the result shape identical to the Node SDK's. @@ -62,7 +63,7 @@ make install # Core dependencies only make install extras=1 # Adds adapters, examples and dev tooling make format # Fix lint, format, and type check — run this before committing make test # Run all tests -make validate # Validate against conformance, ADK and Pydantic AI consumers +make validate # Type-check examples, then validate against conformance, ADK and Pydantic AI consumers make build # Build package ``` @@ -119,7 +120,7 @@ import, never in core. ## Testing - Async tests use `pytest-asyncio` -- Examples are type-checked against the current SDK by `make validate` and in CI; +- Examples are type-checked against the current SDK by `make format`, `make validate` and in CI; each must fail loudly rather than succeed with an empty catalog **Test doubles must model what the server demands, not what the client happens to @@ -211,13 +212,14 @@ via release-please after a merge to main, never from a developer machine. toolset = StackOneToolSet() # reads STACKONE_API_KEY; accounts are discovered hits = toolset.search("list recent comments", top_k=3) -hit = hits[0] if hits else None -session_id = hit.get("session_id") if hit else None -account_ids = [hit["available_accounts"][0]["id"]] if hit else None -toolset.execute( - "linear_list_comments", {"body": {"variables": {"first": 25}}}, account_ids=account_ids, session_id=session_id -) -toolset.submit_feedback("positive", ["linear_list_comments"], session_id=session_id) +if hits: + hit = hits[0] + account_ids = [hit["available_accounts"][0]["id"]] + session_id = hit.get("session_id") + toolset.execute( + hit["action_id"], {"body": {"variables": {"first": 25}}}, account_ids=account_ids, session_id=session_id + ) + toolset.submit_feedback("positive", [hit["action_id"]], session_id=session_id) tools = toolset.fetch_tools(providers=["linear"], actions=["*_list_*"]) ``` @@ -248,7 +250,7 @@ tools = toolset.fetch_tools(providers=["linear"], actions=["*_list_*"]) - **Headers**: header arguments — entries of a nested `headers` object, and top-level `headers_` arguments — are an **allowlist** driven by the served schema. A nested entry passes if `headers.properties` declares it, or if `headers` is an object with no - `properties` (open, as `*_execute_action` serves it); a flat one passes if the + `properties` (open, as `stackone_execute_action` serves it); a flat one passes if the `headers_` property is declared. `Authorization` / `x-account-id` / `User-Agent` never do. Every other argument is sent unchanged. The SDK sets those three itself, after any configured headers. Match header grammar with diff --git a/Makefile b/Makefile index 6ddb589e..6c1e13a3 100644 --- a/Makefile +++ b/Makefile @@ -26,7 +26,7 @@ help: install: uv sync --locked $(if $(extras),--all-extras,) -## Fix lint, format, and type check +## Fix lint, format, and type check (needs make install extras=1) format: uv run ruff check --fix . uv run ruff format . From e702e5b7e65d3ac93cfcfc7afb2ec029ffb59f64 Mon Sep 17 00:00:00 2001 From: S2D2 Date: Wed, 11 Nov 2026 11:54:04 +0000 Subject: [PATCH 3/3] docs: scope the feedback example to the executed account submit_feedback() routes through the lowest account in scope, so the example could send feedback through a different account than the one that ran the action. Pass the same account_ids. Co-Authored-By: Claude Opus 5.5 Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com> --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 55d9af3a..228417bc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -222,7 +222,7 @@ if hits: account_ids=account_ids, session_id=session_id, ) - toolset.submit_feedback("positive", [hit["action_id"]], session_id=session_id) + toolset.submit_feedback("positive", [hit["action_id"]], session_id=session_id, account_ids=account_ids) tools = toolset.fetch_tools(providers=["linear"], actions=["*_list_*"]) ```