Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
161 commits
Select commit Hold shift + click to select a range
48ff7d9
fix(toolset): route stackone_submit_feedback over MCP and list it once
willleeney Sep 29, 2026
9dda69f
feat(toolset): link calls with session_id and add submit_feedback()
willleeney Sep 29, 2026
f2fce60
test(mocks): serve per-action schemas verbatim from a low-level MCP S…
willleeney Sep 29, 2026
2282223
fix(tools): emit the served required list in served order
willleeney Sep 29, 2026
7fa339a
fix(tools): return structuredContent from a tools/call result with no…
willleeney Sep 29, 2026
4fdacb0
fix(types): reduce download filenames exactly as the Node SDK does
willleeney Sep 29, 2026
f6dc5b3
refactor!: execute every tool over MCP tools/call
willleeney Sep 29, 2026
109d729
build: drop respx, which no test uses any more
willleeney Sep 29, 2026
fb180a4
docs: describe MCP-only execution
willleeney Sep 29, 2026
7d8bd94
fix(tools): send tools/call without relisting the catalog first
willleeney Sep 29, 2026
da0d1fd
ci: pin sdk-conformance to the MCP-only suite
willleeney Sep 29, 2026
7d7c04a
fix(tools)!: guard every header argument by its own declaration
willleeney Sep 30, 2026
16c8baa
fix(toolset): send feedback once, through the first account
willleeney Sep 30, 2026
6390cc9
fix(tools)!: return the first listing from get_tool(), as Node does
willleeney Sep 30, 2026
a5c8b12
docs: drop the stale unwrap references and an orphaned nullable comment
willleeney Sep 30, 2026
fadc574
feat: export the feedback types and StackOneMcpTool, and take any seq…
willleeney Sep 30, 2026
122a280
fix(toolset): move a pinned action_id and session_id to the end of th…
willleeney Sep 30, 2026
2b045ad
refactor(tools): make the base StackOneTool's API key optional
willleeney Sep 30, 2026
81edf7e
refactor(tools): open the MCP transport with streamable_http_client
willleeney Sep 30, 2026
8d279b8
ci: check that PR titles are conventional commits
willleeney Sep 30, 2026
92abaf6
docs: add a 2.x to 3.0 migration guide
willleeney Sep 30, 2026
dc03977
fix(tools): match a flat header argument by its exact key and forward…
willleeney Sep 30, 2026
3851842
ci: pin sdk-conformance to 9b5605a
willleeney Sep 30, 2026
b05f232
fix(tools): treat a headers schema as open only when it is an object …
willleeney Oct 1, 2026
549cf87
fix(tools): reject NaN and Infinity arguments instead of sending them…
willleeney Oct 1, 2026
5a9ebfc
fix(toolset): validate submit_feedback() session_id as execute() does
willleeney Oct 1, 2026
a7421af
test: dispatch mock meta tools only in search_execute mode
willleeney Oct 1, 2026
e462ae9
test: assert an omitted required key is absent on every adapter
willleeney Oct 1, 2026
0ddc28b
docs: match the README, migration guide and CLAUDE.md to what the cod…
willleeney Oct 1, 2026
50246f6
fix(toolset): reject an empty account id, as Node does
willleeney Oct 1, 2026
88d046b
ci: re-check the PR title when a draft is marked ready, as Node does
willleeney Oct 1, 2026
883f6e5
ci: pin sdk-conformance to 6a6991d
willleeney Oct 1, 2026
bf2d8d5
fix(toolset): reject an empty account_id instead of widening to every…
willleeney Oct 1, 2026
90508a7
fix(tools): keep the server's explanation when an MCP request fails
willleeney Oct 1, 2026
4986c59
feat(tools): retry a 429 on every request, honouring Retry-After
willleeney Oct 1, 2026
336b423
fix(toolset): raise a 429 that outlasts its retries instead of skippi…
willleeney Oct 1, 2026
666af26
docs: document how the SDK handles rate limits
willleeney Oct 1, 2026
4445836
fix(tools): end a call only on an HTTP 429, and read Retry-After as N…
willleeney Oct 1, 2026
eca441d
ci: pin sdk-conformance to 9d5efab
willleeney Oct 1, 2026
4df82b4
fix(tools): read Retry-After as a date only when it starts with a wee…
willleeney Oct 1, 2026
15f99fd
fix(tools): raise a 429 at once when its retry would outlast the dead…
willleeney Oct 1, 2026
2934947
fix(tools): fall back to the backoff on a Retry-After date that overf…
willleeney Oct 1, 2026
f623f0c
fix(toolset): discard an account list fetched across clear_catalog_ca…
willleeney Oct 1, 2026
6952f9f
fix(tools): report an MCP timeout as a timeout
willleeney Oct 1, 2026
1683ea1
fix(tools): write nested header values as Node writes them
willleeney Oct 1, 2026
84483bf
fix(tools): trim header names exactly as JavaScript's trim() does
willleeney Oct 1, 2026
2991836
fix(toolset): reject a non-string account id
willleeney Oct 1, 2026
f29e31b
fix(tools): raise ToolArgumentsError for unusable tool arguments
willleeney Oct 1, 2026
30341e1
fix(types): declare ToolParameters.required
willleeney Oct 1, 2026
e9fb912
fix(examples): build the call from example_request and tolerate a non…
willleeney Oct 1, 2026
948cf67
docs(examples): list every example that needs STACKONE_ACCOUNT_ID
willleeney Oct 1, 2026
b4354e6
docs(migration): say that an empty account id now raises
willleeney Oct 1, 2026
797f6df
fix(headers): drop a non-object headers argument unless declared, and…
willleeney Oct 1, 2026
6a3cbb3
ci: pin sdk-conformance to 67103ca
willleeney Oct 1, 2026
d8a5ebb
fix: raise ToolArgumentsError on self-referential header values
willleeney Oct 1, 2026
35da92d
fix: avoid caching a catalog resolved before a mid-discovery cache clear
willleeney Oct 1, 2026
1c42c1f
docs: narrow MIGRATION.md header claims
willleeney Oct 1, 2026
5a466cc
feat(toolset): read STACKONE_BASE_URL
willleeney Oct 1, 2026
a965484
fix(toolset): share one in-flight GET /accounts across concurrent dis…
willleeney Oct 1, 2026
2e58b2f
docs: document every ToolArgumentsError site in its docstring and MIG…
willleeney Oct 1, 2026
3ddf966
docs: note that integers above 2^53 keep their exact value, unlike Node
willleeney Oct 1, 2026
80be144
fix(tools): read Retry-After as a strict RFC 9110 HTTP-date
willleeney Oct 2, 2026
b6c0ce6
fix(tools): refuse NaN in argument JSON text, and compare SDK-owned h…
willleeney Oct 2, 2026
dbe74a1
fix(toolset): refuse a non-list account_ids with ToolsetConfigError
willleeney Oct 2, 2026
fd39798
fix: align error and warning messages with the Node SDK
willleeney Oct 2, 2026
700314e
fix(tools): word the 429 deadline warning as the Node SDK does
willleeney Oct 2, 2026
72a5ef2
test(vectors): vendor sdk-conformance's shared vectors at b8c2871
willleeney Oct 2, 2026
37b0047
test(vectors): grade the SDK against every shared vector
willleeney Oct 2, 2026
2fd4e73
ci: fail when tests/vectors differs from the pinned sdk-conformance
willleeney Oct 2, 2026
1f80e0f
test(vectors): sync the shared vectors to sdk-conformance daf1140
willleeney Oct 2, 2026
6a7db6c
ci: pin sdk-conformance to daf1140
willleeney Oct 2, 2026
f3f1fd6
fix(toolset): reject tuple account ids and raise instead of assert
willleeney Oct 2, 2026
f1173de
fix(tools): avoid OverflowError on a leap-second Retry-After at the m…
willleeney Oct 2, 2026
8147881
test(fetch_tools): synchronize the concurrent discovery failure test
willleeney Oct 2, 2026
9782676
fix(scripts): harden sync_vectors.sh
willleeney Oct 2, 2026
a9d7cd8
test(vectors): sync the shared vectors to sdk-conformance 0906f4d
willleeney Oct 2, 2026
63a4dd7
ci: pin sdk-conformance to 0906f4d
willleeney Oct 2, 2026
731218a
docs(migration): an ordinary headers field still passes the JSON-valu…
willleeney Oct 2, 2026
c334066
test(vectors): sync the shared vectors to sdk-conformance dfdaca1
willleeney Oct 2, 2026
ea69dd3
ci: pin sdk-conformance to dfdaca1
willleeney Oct 2, 2026
ae0c43f
test(vectors): sync the shared vectors to sdk-conformance ee0bb06
willleeney Oct 2, 2026
95748bd
ci: pin sdk-conformance to ee0bb06
willleeney Oct 2, 2026
9b3bbea
fix(tools): let KeyboardInterrupt and SystemExit through an MCP request
willleeney Oct 2, 2026
f072fe8
build: require langchain-core 0.3.36 or later for a dict args_schema
willleeney Oct 2, 2026
949a01f
fix(toolset): read a root type that is not a string as object, as Nod…
willleeney Oct 2, 2026
c363f28
fix(tools): return non-text content parts as plain JSON, as Node does
willleeney Oct 2, 2026
249957b
fix(tools): report a timeout on a request retried after a 429 as the 429
willleeney Oct 2, 2026
c17bf6b
fix(toolset): cache the healthy accounts when one fails, and keep eve…
willleeney Oct 2, 2026
f82acd3
feat(toolset): tag each search hit with its account_id and apply top_…
willleeney Oct 2, 2026
47846af
fix(toolset): refuse an action whose connector is linked on more than…
willleeney Oct 2, 2026
1d8ddcd
test(toolset): pin the session_id move and the SDK-owned header filter
willleeney Oct 2, 2026
ee83c44
fix(tools): build every adapter from the first tool of each name
willleeney Oct 2, 2026
959bcc8
feat(toolset): warn when STACKONE_ACCOUNT_ID is set but ignored
willleeney Oct 2, 2026
1047753
feat(toolset): add action_run_id to submit_feedback, and send it thro…
willleeney Oct 2, 2026
89e647c
docs: describe account_id on search hits, top_k across connectors and…
willleeney Oct 2, 2026
6288a3a
ci: run the full conformance suite against the Node SDK too
willleeney Oct 2, 2026
82dcb6b
fix(toolset): raise an all-accounts failure from an ExceptionGroup of…
willleeney Oct 2, 2026
666877c
test(vectors): sync the shared vectors to sdk-conformance ec4dcfb
willleeney Oct 2, 2026
9581aa3
ci: pin sdk-conformance to ec4dcfb
willleeney Oct 2, 2026
54a2260
fix(tools): word a timeout after a retried 429 as Node does
willleeney Oct 2, 2026
2cdac07
test(vectors): grade the 429-timeout messages
willleeney Oct 2, 2026
54322a3
ci: pin sdk-conformance to db6b908
willleeney Oct 2, 2026
e3139c2
fix(tools): clear the throttle marker after a 429 retry succeeds
willleeney Oct 2, 2026
486ab4c
docs(migration): qualify the partial-catalog and account-id-warning w…
willleeney Oct 2, 2026
66fb7be
ci: pin the Node SDK checkout to a commit SHA
willleeney Oct 2, 2026
b1b695b
fix(toolset): warn for STACKONE_ACCOUNT_ID even with an empty account…
willleeney Oct 2, 2026
a1095c0
fix(toolset): merge concurrent catalog updates instead of overwriting
willleeney Oct 2, 2026
b9743df
docs: pass account_ids in the feedback-section and CLAUDE.md execute(…
willleeney Oct 2, 2026
d7696d8
chore(vectors): sync shared vectors to sdk-conformance 2f4a655
willleeney Oct 2, 2026
7e9b3ef
test(vectors): sync to sdk-conformance c794e56, where messages.json s…
willleeney Oct 2, 2026
e2ea2c2
ci: run conformance against stackone-ai-node 00da255
willleeney Oct 2, 2026
cf3f620
feat(toolset): send x-end-user-id for non-shared accounts
willleeney Oct 2, 2026
27c0dfd
test(vectors): sync to sdk-conformance f46905f, where x-end-user-id i…
willleeney Oct 2, 2026
9d81979
feat(toolset): add a headers option sent on every request, as Node has
willleeney Oct 2, 2026
b342550
docs: describe the toolset headers option
willleeney Oct 2, 2026
ea540f8
ci: pin sdk-conformance to 0d72282
willleeney Oct 2, 2026
c816fe9
test(vectors): sync to sdk-conformance 88c9400
willleeney Oct 5, 2026
6ad8c25
ci: pin sdk-conformance to 88c9400
willleeney Oct 5, 2026
508ee6e
ci: run conformance against stackone-ai-node 8030159
willleeney Oct 5, 2026
2a4b192
fix(mocks): resolve x-account-id from the query string under MOCK_END…
willleeney Oct 5, 2026
e19c351
test(toolset): assert explicit account ids make no GET /accounts request
willleeney Oct 5, 2026
0c1174d
fix(toolset): order overlapping fetch_accounts() records by start time
willleeney Oct 5, 2026
599be45
docs: fetch_accounts() records end users in start order
willleeney Oct 5, 2026
658571a
test(end-user): surface failures from the racing fetch_accounts() thr…
willleeney Oct 5, 2026
d87ecd1
test(vectors): sync to sdk-conformance 7347926
willleeney Oct 5, 2026
b9d0b5f
ci: pin sdk-conformance to 7347926
willleeney Oct 5, 2026
d307ed8
ci: run conformance against stackone-ai-node c2b8736
willleeney Oct 5, 2026
f0a8acb
fix(toolset): address the second review on multiple and non-shared ac…
willleeney Oct 5, 2026
64d1dcd
docs: describe non-shared discovery, the failed-account refusal and t…
willleeney Oct 5, 2026
a7c6960
fix(toolset): quote the action id in the failed-account error, as Nod…
willleeney Oct 5, 2026
bddfcf0
test(vectors): sync to sdk-conformance python-198-examples f36bb79 an…
willleeney Oct 5, 2026
7db755c
ci: run conformance against stackone-ai-node c5f2537
willleeney Oct 5, 2026
3872385
fix(toolset): refuse only for a failed account on the action's own co…
willleeney Oct 5, 2026
d178117
ci: pin sdk-conformance to 27796bb
willleeney Oct 5, 2026
8ab4a17
ci: run conformance against stackone-ai-node 9d332ab
willleeney Oct 5, 2026
2c338b1
fix(toolset): re-list only the failed accounts that could serve the a…
willleeney Oct 5, 2026
084322b
fix(toolset): learn a failed account's provider with one GET /account…
willleeney Oct 5, 2026
70007de
fix(toolset): chain a failed end-user lookup onto the 400 it was look…
willleeney Oct 5, 2026
a940f34
fix(toolset): raise when every active account discovery finds is non-…
willleeney Oct 5, 2026
0abe0c0
fix(toolset): say the toolset uses every active shared account, and t…
willleeney Oct 5, 2026
748ae08
fix(tools): keep a retried 429 on record while another request in the…
willleeney Oct 5, 2026
e70161e
test(toolset): an account that fails during an execute() is not liste…
willleeney Oct 5, 2026
f5cebbf
test(vectors): sync to sdk-conformance 7369b74, with a no-shared-acco…
willleeney Oct 5, 2026
276da2e
ci: pin sdk-conformance to 7369b74
willleeney Oct 5, 2026
80b580b
ci: run conformance against stackone-ai-node 9d7f2af
willleeney Oct 5, 2026
d6739a9
test: stub GET /accounts in the same-call re-list test, and bound the…
willleeney Oct 5, 2026
7f1835b
docs: a failed account on another provider is listed again when due, …
willleeney Oct 5, 2026
33dc91c
ci: pin sdk-conformance to ddd2074
willleeney Oct 5, 2026
b9bf8ea
ci: run conformance against stackone-ai-node 023dbea
willleeney Oct 5, 2026
a8b825c
test: refuse any connection beyond loopback, and stub GET /accounts i…
willleeney Oct 6, 2026
aefa3cd
test: say the connector-account-unavailable vector's lookup does a GE…
willleeney Oct 6, 2026
044153c
test: pin that execute() raises a rate-limited provider lookup
willleeney Oct 6, 2026
8ed9cc7
fix: hold a provider lookup's miss for the failed-account window, so …
willleeney Oct 6, 2026
f5f4d51
ci: pin sdk-conformance to 960a542
willleeney Oct 6, 2026
970d7b8
ci: run conformance against stackone-ai-node 92b23de
willleeney Oct 6, 2026
91e0a3a
fix(toolset): act on a provider-lookup miss in the call that made it,…
willleeney Oct 6, 2026
9a84c2b
ci: run conformance against stackone-ai-node dbee8bd
willleeney Oct 6, 2026
5f91933
ci: pin sdk-conformance to 55bd126
willleeney Oct 6, 2026
eeef2c0
ci: run conformance against stackone-ai-node 2253466
willleeney Oct 6, 2026
9a35e2e
test: pin the network guard's refusal, not the name it sees
willleeney Oct 6, 2026
441a0ca
test(toolset): a provider-lookup miss is forgotten once GET /accounts…
willleeney Oct 6, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .env.example
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
# 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
# Optional: override the API host. Falls back to https://api.stackone.com.
# STACKONE_BASE_URL=https://api.stackone.com

# Needed by the examples that pin one account: auth_management, langchain_integration,
# langgraph_integration and pydantic_ai_integration
STACKONE_ACCOUNT_ID=your-account-id

# Required for OpenAI-based examples (openai_integration, langchain_integration, langgraph_integration, pydantic_ai_integration)
Expand Down
26 changes: 26 additions & 0 deletions .github/workflows/check-title.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
name: 'Check PR title'

on:
pull_request:
types:
- opened
- reopened
- edited
- synchronize
Comment thread
willleeney marked this conversation as resolved.
Resolved
- ready_for_review

permissions:
pull-requests: read

jobs:
main:
name: Validate PR title
runs-on: ubuntu-slim
steps:
- uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
ignoreLabels: |
autorelease: pending
dependencies
40 changes: 37 additions & 3 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -105,10 +105,18 @@ jobs:
echo "can-skip=false" >> "$GITHUB_OUTPUT"
fi

# Runs the full suite, both SDKs side by side, so a change here that the Node SDK does not
# match fails here rather than drifting.
conformance:
needs: check-secret
if: needs.check-secret.outputs.can-skip != 'true'
runs-on: ubuntu-latest
env:
# Pinned to a commit on refactor/mcp-only-toolset, not the branch: a force-push or the
# branch's deletion on merge must not silently change what this job grades. Bump
# deliberately while StackOneHQ/stackone-ai-node#383 is open; switch to a main commit
# once it merges.
NODE_SDK_REF: 2253466371a22c839524d008a635ceb9f2c0959b
steps:
- name: Check conformance token is configured
env:
Expand All @@ -128,11 +136,25 @@ jobs:
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
repository: StackOneHQ/sdk-conformance
ref: 7e3b471ac947c9dd743ff6d47ad535afd5804a86
ref: 55bd126b0187a0f28f187803ecf48e791d157bfc
token: ${{ secrets.CONFORMANCE_REPO_TOKEN }}
path: sdk-conformance
persist-credentials: false

# Public, so no token.
- name: Checkout Node SDK
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
repository: StackOneHQ/stackone-ai-node
ref: ${{ env.NODE_SDK_REF }}
path: stackone-ai-node
persist-credentials: false

# tests/test_shared_vectors.py grades the SDK against this copy; it must be the
# pinned commit's vectors/ byte for byte. Refresh with scripts/sync_vectors.sh.
- name: Vendored vectors match the pinned sdk-conformance
run: diff -r sdk/tests/vectors sdk-conformance/vectors

- name: Setup uv
uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
with:
Expand All @@ -145,10 +167,21 @@ jobs:
version: 10.26.0
package_json_file: sdk-conformance/package.json

# 24, not 22: the Node SDK's devEngines pins Node ^24.11.0, and the suite runs on it too.
- name: Setup Node
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: 22
node-version: 24

- name: Install Node SDK dependencies
working-directory: stackone-ai-node
run: pnpm install --frozen-lockfile

# The runner imports the built dist, not src, so the harness grades the publishable
# artifact. It refuses a dist older than src.
- name: Build Node SDK
working-directory: stackone-ai-node
run: pnpm run build

- name: Install conformance dependencies
working-directory: sdk-conformance
Expand All @@ -157,8 +190,9 @@ jobs:
- name: Run conformance suite
working-directory: sdk-conformance
env:
NODE_SDK_DIST: ${{ github.workspace }}/stackone-ai-node/dist/index.mjs
PYTHON_SDK_DIR: ${{ github.workspace }}/sdk
run: pnpm test:python -- --strict-schema
run: pnpm test -- --strict-schema

# Make this the one required status check. Individually required checks go
# missing when a job is renamed or a matrix entry is added, and nothing notices.
Expand Down
106 changes: 74 additions & 32 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,35 +15,44 @@ Requires Python >= 3.11.

The package is three modules. The guiding property is that **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. Nothing invented, nothing lost.

1. **`types.py`** — `ToolParameters`, `ToolMode`, the error hierarchy, filename
sanitising, shared aliases and `DEFAULT_BASE_URL`.
2. **`tools.py`** — `StackOneTool` (execution, header sanitising, framework
converters), `Tools` (container), `StackOneRpcTool` (per-action tools over
`/actions/rpc`), `StackOneMcpTool` (meta tools over MCP `tools/call`), and the
MCP client.
and a call sends the model's arguments, as given, over MCP `tools/call` to the
endpoint and account that listed the tool. Nothing invented, nothing lost. The only
non-MCP request is `GET /accounts`.

1. **`types.py`** — `ToolParameters`, `ToolMode`, `ExecuteConfig`, the error
hierarchy, shared aliases and `DEFAULT_BASE_URL`.
2. **`tools.py`** — `StackOneTool` (schema, header sanitising, framework converters;
its `execute()` raises — a hand-built tool must override it), `Tools` (container),
`StackOneMcpTool` (every tool the toolset builds, executed over MCP `tools/call`),
and the MCP client, including `parse_tool_result`.
3. **`toolset.py`** — `StackOneToolSet`: account discovery, the cached catalog,
`search()` and `execute()`.

Tools are listed from `/mcp?param-style=flat_prefixed`. An API key alone is enough:
with no account given, `GET /accounts` is called and every `active` account is used.
There is no OpenAPI parsing and no client-side search.
Tools are listed from `/mcp` (plus `?tool-mode=` when a mode is set; there is no
param-style pin, so the model sees whatever style the server serves). An API key
alone is enough: with no account given, `GET /accounts` is called and every `active`
account is used. There is no OpenAPI parsing and no client-side search.

### Two calling surfaces

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`).
Arguments are the **nested** envelope: `{"body": {"variables": {...}}}`.
- `toolset.fetch_tools()` + `tool.execute(args)` uses per-action tools over
`/actions/rpc`. Arguments are **flat-prefixed**: `body_variables`, `path_id`.
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.

Both return the payload itself. The server **silently drops** arguments that do not
match the schema — a wrong key returns a normal-looking success with your filter
ignored. Flat keys passed to `toolset.execute()` fail this way; nested keys passed to
a `fetch_tools()` tool are accepted.
Both go over `tools/call` with arguments sent verbatim — the SDK never splits or
renames them. The server **silently drops** arguments that do not match the schema —
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": ...}`
(optionally with `defenderMetadata` / `policyMetadata`); search results are bare JSON.
Keep the result shape identical to the Node SDK's.

## Commands

Expand Down Expand Up @@ -116,11 +125,17 @@ import, never in core.
**Test doubles must model what the server demands, not what the client happens to
send.** The SDK once shipped unable to list a single tool while every test passed,
because the mock defaulted a missing `x-account-id` to `'default'` — inventing an
account the real API would have rejected. The mock now 400s an unscoped `/mcp` or
`/actions/rpc` request and 404s an unknown account. When adding a mock behaviour,
account the real API would have rejected. The mock now 400s an unscoped `/mcp`
request and 404s an unknown account. When adding a mock behaviour,
make it refuse what the real API refuses. A fake whose signature has no failure mode
cannot catch a bug.

The mock logs every MCP `tools/call` request as sent — with its account and query
string, before the
MCP SDK parses it — at `GET /__requests` (`DELETE` clears it). Assert wire shape there, not
on a handler's echo, which cannot show a stripped or null key. `MOCK_SUBMIT_FEEDBACK=off`
(the `mcp_mock_server_without_feedback` fixture) serves a project without feedback.

Verify live behaviour against a real key before claiming it works — a green suite is
not evidence. Put credentials in the gitignored `.env` and run
`uv run --env-file .env python ...`.
Expand All @@ -134,9 +149,12 @@ pnpm install
These tests **fail** rather than skip if Node dependencies are missing — a silent
skip previously let them vanish while CI stayed green.

The mock lists every `inputSchema` verbatim through the MCP SDK's low-level `Server`.
Do not move it to `McpServer.registerTool`: that expects a Zod shape and lists a plain
JSON Schema as `properties: {}`, so no test sees a declared parameter.

The mock's dependencies are pinned exactly (`@modelcontextprotocol/sdk`, `zod`,
`hono`, `@hono/mcp`). Do not loosen them to caret ranges: a newer MCP SDK rejects
the raw `inputSchema` objects the mock passes.
`hono`, `@hono/mcp`). Do not loosen them to caret ranges.

## Examples

Expand Down Expand Up @@ -193,7 +211,13 @@ 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)
toolset.execute("linear_list_comments", {"body": {"variables": {"first": 25}}})
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
toolset.execute(
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
"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)

tools = toolset.fetch_tools(providers=["linear"], actions=["*_list_*"])
```
Expand All @@ -202,29 +226,47 @@ tools = toolset.fetch_tools(providers=["linear"], actions=["*_list_*"])
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.
- `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.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.

## Important Considerations

- **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
comes from an attacker-controllable header and is reduced to a safe basename.
- **Headers**: model-supplied headers are an **allowlist** driven by the served
schema — only a declared `headers_*` property passes. Match header grammar with
- **File downloads**: a file action returns a download link
(`{download_url, expires_at, file}`), unchanged; the SDK does not follow it. When no
link can be issued the server answers `isError` with status 501, which raises.
- **Headers**: header arguments — entries of a nested `headers` object, and top-level
`headers_<name>` 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
`headers_<name>` 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
`fullmatch`, never `match`: `$` also matches before a trailing newline, so `match`
lets `"value\n"` through.

### Modifying Tool Behaviour

- Core execution logic: `StackOneTool.execute()` in `tools.py`
- RPC envelope split: `StackOneRpcTool._split_envelope_params`
- Meta-tool execution: `StackOneMcpTool.execute()` and `StackOneToolSet.execute()`
- Execution: `StackOneMcpTool.execute()` and `call_mcp_tool()` in `tools.py`
- Result parsing: `parse_tool_result()`
- search/execute routing: `StackOneToolSet.execute()`
- Tool construction and the feedback-tool dedupe: `StackOneToolSet._create_tool` and
`_dedupe_global_tools`

Schemas must reach the model intact. `to_openai_function` passes the served schema
through verbatim, stripping only the SDK's internal `nullable` marker (which becomes
the JSON Schema `required` list). `to_langchain` and `to_pydantic_ai_tool` hand over
through verbatim, stripping only the SDK's internal `nullable` marker. Its `required`
is the served root list in the served order — never rebuilt from the markers, which
re-sorted it into property order. `to_langchain` and `to_pydantic_ai_tool` hand over
that same schema — never rebuild one from property types, which silently loses every
nested field, enum and bound. The conformance suite's `--strict-schema` gate checks
the OpenAI surface.
Expand Down
Loading