From c0fd8f6545409baacb608623a12da25a49d66028 Mon Sep 17 00:00:00 2001 From: Sava Znatnov Date: Sat, 10 Oct 2026 18:50:54 +0700 Subject: [PATCH] feat(mcp)!: a listing tool gives 50 items when no `limit` is asked A tool's answer is read whole into a model's context: `tracker_issues_list` with no `limit` took about 206 thousand tokens at the cap of 500 (#561). A tool now stops at `YCLI__HTTP__MAX_TOOL_ITEMS` (50), says `truncated: true` and gives `next` to go on; `limit` and `all` work as before. A command keeps its own cap, `YCLI__HTTP__MAX_ITEMS` (500). This changes #502 for the MCP server only (the owner's decision in #561, 2026-10-10): the default of a tool and of a command are no longer one number. An ast-grep rule, `tool-takes-the-tool-cap`, holds every tool to `config.http.tool_cap(...)`, so a new tool cannot take the command's cap; its fix was the codemod for the 48 tools. The live scenarios gain a step that reads a listing as `-o json` prints it and asserts where it stopped (`output: listing`), on a real reply. BREAKING CHANGE: a list tool of the MCP server called with no `limit` returns 50 items in place of 500. Pass `limit`, go on with `next`, or set `YCLI__HTTP__MAX_TOOL_ITEMS`. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/yandex-360/SKILL.md | 3 +- .../tool-takes-the-tool-cap-test.yml | 11 +++++ .ast-grep/rules/tool-takes-the-tool-cap.yml | 15 +++++++ .claude/skills/yandex-360/SKILL.md | 3 +- .opencode/skills/yandex-360/SKILL.md | 3 +- docs/en/how-to/script-the-cli.md | 2 +- docs/en/reference/configuration.md | 3 +- docs/en/reference/mcp/datalens.md | 40 +++++++++---------- docs/en/reference/mcp/forms.md | 4 +- docs/en/reference/mcp/tracker.md | 24 +++++------ docs/en/reference/mcp/wiki.md | 6 +-- docs/ru/how-to/script-the-cli.md | 2 +- docs/ru/reference/configuration.md | 3 +- e2e/README.md | 2 +- e2e/models.py | 8 ++-- e2e/runner.py | 3 +- e2e/scenarios/tracker/reads.yaml | 9 +++++ e2e/surfaces.py | 7 +++- plugins/yandex-360/skills/yandex-360/SKILL.md | 3 +- src/ycli/settings.py | 25 ++++++++++-- src/ycli/yandex/datalens/audit/mcp.py | 2 +- .../yandex/datalens/cloudenvironments/mcp.py | 2 +- .../datalens/cloudenvironmentstorage/mcp.py | 2 +- src/ycli/yandex/datalens/collections/mcp.py | 4 +- src/ycli/yandex/datalens/entries/mcp.py | 6 +-- src/ycli/yandex/datalens/licensing/mcp.py | 2 +- src/ycli/yandex/datalens/members/mcp.py | 2 +- src/ycli/yandex/datalens/restcatalogs/mcp.py | 2 +- src/ycli/yandex/datalens/sharedentries/mcp.py | 2 +- .../yandex/datalens/sparkapplications/mcp.py | 2 +- src/ycli/yandex/datalens/sparkclusters/mcp.py | 4 +- src/ycli/yandex/datalens/trinoclusters/mcp.py | 4 +- src/ycli/yandex/datalens/workbooks/mcp.py | 6 +-- src/ycli/yandex/forms/answers/mcp.py | 2 +- src/ycli/yandex/forms/history/mcp.py | 2 +- src/ycli/yandex/forms/notifications/mcp.py | 2 +- src/ycli/yandex/forms/surveys/mcp.py | 2 +- src/ycli/yandex/mcp.py | 4 +- src/ycli/yandex/tracker/boards/mcp.py | 2 +- src/ycli/yandex/tracker/changelog/mcp.py | 2 +- src/ycli/yandex/tracker/comments/mcp.py | 2 +- src/ycli/yandex/tracker/entities/mcp.py | 6 +-- src/ycli/yandex/tracker/gaps/mcp.py | 2 +- src/ycli/yandex/tracker/issues/mcp.py | 6 ++- src/ycli/yandex/tracker/links/mcp.py | 2 +- src/ycli/yandex/tracker/queues/mcp.py | 2 +- src/ycli/yandex/tracker/triggers/mcp.py | 2 +- src/ycli/yandex/tracker/users/mcp.py | 2 +- src/ycli/yandex/tracker/worklog/mcp.py | 2 +- src/ycli/yandex/wiki/attachments/mcp.py | 2 +- src/ycli/yandex/wiki/comments/mcp.py | 6 +-- src/ycli/yandex/wiki/pages/mcp.py | 10 ++--- src/ycli/yandex/wiki/resources/mcp.py | 2 +- tests/architecture/test_arch5.py | 2 +- tests/contract/test_contract.py | 4 ++ tests/tooling/test_e2e_runner.py | 9 +++++ tests/unit/cli/test_listing_handles.py | 20 +++++++++- tests/unit/yandex/test_settings.py | 3 ++ 58 files changed, 210 insertions(+), 106 deletions(-) create mode 100644 .ast-grep/rule-tests/tool-takes-the-tool-cap-test.yml create mode 100644 .ast-grep/rules/tool-takes-the-tool-cap.yml diff --git a/.agents/skills/yandex-360/SKILL.md b/.agents/skills/yandex-360/SKILL.md index 7eef191a3..f946b606b 100644 --- a/.agents/skills/yandex-360/SKILL.md +++ b/.agents/skills/yandex-360/SKILL.md @@ -120,7 +120,8 @@ semantics, a service ycli does not wrap yet), read the official docs directly, a adding it. `--dry-run` prints the write request instead of sending it, the JSON result pipes to `jq`, and the exit code says what failed (3 not found, 4 auth, 5 rate limited, 6 transient). -- **A long listing comes in pieces** — a list tool returns `{items, truncated, next}`; when +- **A long listing comes in pieces** — a list tool returns `{items, truncated, next}`, 50 + items unless you give `limit` (a command gives 500); when `truncated` is true, call it again with that `next`, its required arguments as they were and nothing else but `limit` (the token carries its listing; an argument that differs from it is refused by name). `all=true` returns everything at once and can overflow the context. diff --git a/.ast-grep/rule-tests/tool-takes-the-tool-cap-test.yml b/.ast-grep/rule-tests/tool-takes-the-tool-cap-test.yml new file mode 100644 index 000000000..3605a0c4e --- /dev/null +++ b/.ast-grep/rule-tests/tool-takes-the-tool-cap-test.yml @@ -0,0 +1,11 @@ +id: tool-takes-the-tool-cap +valid: + - | + cap = config.http.tool_cap(limit, all_=all) + - | + limit = config.http.tool_cap(limit) +invalid: + - | + cap = config.http.cap(limit, all_=all) + - | + return client.answers.list(survey_id, limit=config.http.cap(limit)) diff --git a/.ast-grep/rules/tool-takes-the-tool-cap.yml b/.ast-grep/rules/tool-takes-the-tool-cap.yml new file mode 100644 index 000000000..c3ee4074a --- /dev/null +++ b/.ast-grep/rules/tool-takes-the-tool-cap.yml @@ -0,0 +1,15 @@ +id: tool-takes-the-tool-cap +language: python +severity: error +message: A tool caps its listing with `config.http.tool_cap(...)`, not with the CLI's `cap(...)`. +note: |- + A tool's answer is read whole into a model's context, so a tool that is given no `limit` + gives `HTTPConfig.max_tool_items` (50), where a command gives `max_items` (500). The owner's + decision in #561 (2026-10-10), which changes #502 for the MCP server only. +url: https://github.com/bim-ba/ycli/issues/561 +files: + - src/ycli/**/mcp.py + - src/ycli/**/mcp/**/*.py +rule: + pattern: $CONFIG.http.cap($$$ARGUMENTS) +fix: $CONFIG.http.tool_cap($$$ARGUMENTS) diff --git a/.claude/skills/yandex-360/SKILL.md b/.claude/skills/yandex-360/SKILL.md index b59b858d1..dbd74d9a5 100644 --- a/.claude/skills/yandex-360/SKILL.md +++ b/.claude/skills/yandex-360/SKILL.md @@ -122,7 +122,8 @@ semantics, a service ycli does not wrap yet), read the official docs directly, a adding it. `--dry-run` prints the write request instead of sending it, the JSON result pipes to `jq`, and the exit code says what failed (3 not found, 4 auth, 5 rate limited, 6 transient). -- **A long listing comes in pieces** — a list tool returns `{items, truncated, next}`; when +- **A long listing comes in pieces** — a list tool returns `{items, truncated, next}`, 50 + items unless you give `limit` (a command gives 500); when `truncated` is true, call it again with that `next`, its required arguments as they were and nothing else but `limit` (the token carries its listing; an argument that differs from it is refused by name). `all=true` returns everything at once and can overflow the context. diff --git a/.opencode/skills/yandex-360/SKILL.md b/.opencode/skills/yandex-360/SKILL.md index b59b858d1..dbd74d9a5 100644 --- a/.opencode/skills/yandex-360/SKILL.md +++ b/.opencode/skills/yandex-360/SKILL.md @@ -122,7 +122,8 @@ semantics, a service ycli does not wrap yet), read the official docs directly, a adding it. `--dry-run` prints the write request instead of sending it, the JSON result pipes to `jq`, and the exit code says what failed (3 not found, 4 auth, 5 rate limited, 6 transient). -- **A long listing comes in pieces** — a list tool returns `{items, truncated, next}`; when +- **A long listing comes in pieces** — a list tool returns `{items, truncated, next}`, 50 + items unless you give `limit` (a command gives 500); when `truncated` is true, call it again with that `next`, its required arguments as they were and nothing else but `limit` (the token carries its listing; an argument that differs from it is refused by name). `all=true` returns everything at once and can overflow the context. diff --git a/docs/en/how-to/script-the-cli.md b/docs/en/how-to/script-the-cli.md index 1bca64501..c8edbdcce 100644 --- a/docs/en/how-to/script-the-cli.md +++ b/docs/en/how-to/script-the-cli.md @@ -38,7 +38,7 @@ stopped at 100 of 752; go on with: ycli tracker issues search 'Queue: DE' --next $ ycli tracker issues search 'Queue: DE' --limit 100 --next eyJ2IjoxLCJvZiI6… > second.json ``` -A token carries its listing: with `--next`, give nothing but the limit and what the command cannot be called without, and that as it was: an argument that differs from the token's is refused by its name, never passed over. A token of a Tracker issue search by a scroll (`--scroll-type`) works once; any other token works again. A listing that can no longer go on exits with `9`: start it again without the token. A run that asks more pages than `YCLI__HTTP__MAX_PAGES` stops there and says so the same way, with a token to go on from. +A token carries its listing: with `--next`, give nothing but the limit and what the command cannot be called without, and that as it was: an argument that differs from the token's is refused by its name, never passed over. A token of a Tracker issue search by a scroll (`--scroll-type`) works once; any other token works again. A listing that can no longer go on exits with `9`: start it again without the token. A run that asks more pages than `YCLI__HTTP__MAX_PAGES` stops there and says so the same way, with a token to go on from. A small first `--limit` sets the size of the pages for every piece after it, so take the first piece as large as the ones you mean to go on with. ## Delete without a prompt diff --git a/docs/en/reference/configuration.md b/docs/en/reference/configuration.md index 2de53312e..8ddff0440 100644 --- a/docs/en/reference/configuration.md +++ b/docs/en/reference/configuration.md @@ -34,7 +34,8 @@ Optional settings follow the `YCLI____` pattern. An empty one co |---|---|---| | `YCLI__HTTP__TIMEOUT_SECONDS` | `30` | per-request timeout, seconds (> 0) | | `YCLI__HTTP__RETRIES` | `3` | retries of an idempotent request after a 429 or a 5xx (≥ 0) | -| `YCLI__HTTP__MAX_ITEMS` | `500` | item cap of a listing without `--limit` or `--all` (> 0) | +| `YCLI__HTTP__MAX_ITEMS` | `500` | item cap of a listing command without `--limit` or `--all` (> 0) | +| `YCLI__HTTP__MAX_TOOL_ITEMS` | `50` | item cap of a listing tool of the MCP server without `limit` or `all`: its answer is read whole into a model's context (> 0) | | `YCLI__HTTP__MAX_PAGES` | `1000` | page cap of one listing: a listing that never ends stops here with a warning (> 0) | | `YCLI__HTTP__MAX_TOKEN_LENGTH` | `16384` | the longest `next` token read: a longer one is refused before it is decoded (> 0) | | `YCLI__HTTP__MAX_RETRY_AFTER_SECONDS` | `60` | longest pause a 429 may ask for in `Retry-After`; a longer one fails at once (> 0) | diff --git a/docs/en/reference/mcp/datalens.md b/docs/en/reference/mcp/datalens.md index 7cb154ff1..613029184 100644 --- a/docs/en/reference/mcp/datalens.md +++ b/docs/en/reference/mcp/datalens.md @@ -48,7 +48,7 @@ cap unless ``limit`` is given. | Parameter | Type | Required | Description | |---|---|:---:|---| | `collection_id` | string or null | | Collection id; `null` lists the root. | -| `limit` | integer or null | | Max items to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max items to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `filter_string` | string or null | | Keep the items whose title has this text. | @@ -84,7 +84,7 @@ Who has which role on a collection, auto-paginated. | Parameter | Type | Required | Description | |---|---|:---:|---| | `collection_id` | string | yes | Collection id. | -| `limit` | integer or null | | Max subjects to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max subjects to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `get_inherited_bindings` | boolean or null | | Also list the roles inherited from above. | @@ -192,7 +192,7 @@ collection holds. Capped at the configured item cap unless ``limit`` is given. | Parameter | Type | Required | Description | |---|---|:---:|---| -| `limit` | integer or null | | Max workbooks to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max workbooks to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `collection_id` | string or null | | Collection to list; the root when left out. | @@ -221,7 +221,7 @@ Who has which role on a workbook, auto-paginated. | Parameter | Type | Required | Description | |---|---|:---:|---| | `workbook_id` | string | yes | Workbook id. | -| `limit` | integer or null | | Max subjects to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max subjects to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `get_inherited_bindings` | boolean or null | | Also list the roles inherited from above. | @@ -238,7 +238,7 @@ at the configured item cap unless ``limit`` is given. | Parameter | Type | Required | Description | |---|---|:---:|---| | `workbook_id` | string | yes | Workbook id. | -| `limit` | integer or null | | Max entries to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max entries to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `include_permissions_info` | boolean or null | | Also say what the caller may do with it. | @@ -382,7 +382,7 @@ cap unless ``limit`` is given. | Parameter | Type | Required | Description | |---|---|:---:|---| -| `limit` | integer or null | | Max clusters to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max clusters to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `collection_id` | string or null | | Keep the clusters of one collection. | @@ -465,7 +465,7 @@ Experimental API, not measured. Capped at the configured item cap unless ``limit | Parameter | Type | Required | Description | |---|---|:---:|---| | `cloud_environment_id` | string | yes | The cloud environment the presets are for. | -| `limit` | integer or null | | Max presets to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max presets to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -563,7 +563,7 @@ the configured item cap unless ``limit`` is given. | Parameter | Type | Required | Description | |---|---|:---:|---| -| `limit` | integer or null | | Max members to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max members to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `language` | `en` · `ru` or string or null | | Language of the names. | @@ -583,7 +583,7 @@ cap unless ``limit`` is given. | Parameter | Type | Required | Description | |---|---|:---:|---| -| `limit` | integer or null | | Max entries to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max entries to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `ids` | array of string or null | | Keep the entries with these ids. | @@ -611,7 +611,7 @@ Use it before changing or deleting an entry, to see what depends on it. Auto-pag | Parameter | Type | Required | Description | |---|---|:---:|---| | `entry_ids` | array of string | yes | Entry ids. | -| `limit` | integer or null | | Max relations to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max relations to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `link_direction` | string or null | | `from`: what the entries use; `to`: what uses them. | @@ -639,7 +639,7 @@ The revisions of an entry: who saved it and when. Auto-paginated. | Parameter | Type | Required | Description | |---|---|:---:|---| | `entry_id` | string | yes | Entry id. | -| `limit` | integer or null | | Max revisions to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max revisions to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `rev_ids` | array of string or null | | Keep only these revisions. | @@ -1357,7 +1357,7 @@ An entry that lies in a workbook, or an id nothing knows, answers an empty list. | Parameter | Type | Required | Description | |---|---|:---:|---| | `entry_id` | string | yes | Id of a shared entry: one that lies in a collection. | -| `limit` | integer or null | | Max subjects to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max subjects to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `get_inherited_bindings` | boolean or null | | Also list the roles inherited from above. | @@ -1387,7 +1387,7 @@ A deleted entry is listed too, with ``isDeleted``. |---|---|:---:|---| | `from_` | string | yes | The start of the period: an ISO-8601 time with its zone. | | `to` | string or null | | The end of the period. | -| `limit` | integer or null | | Max entries to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max entries to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -1493,7 +1493,7 @@ its holder last signed in. | `status` | `active` · `expired` · `expiring` or string or null | | Only the licences in this state. | | `sort_by` | `createdAt` · `updatedAt` or string or null | | The field to sort by. | | `order` | `asc` · `desc` or string or null | | The order of the sort. | -| `limit` | integer or null | | Max licences to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max licences to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -1543,7 +1543,7 @@ Experimental in the DataLens API. An instance with none answers an empty list. |---|---|:---:|---| | `filter` | array of string or null | | Conditions, all of which must hold; each is ``field="value"`` over ``name``, ``cloud_id``, ``status`` or ``created_by_id``. | | `include_permissions` | boolean or null | | Also say what the caller may do with it. | -| `limit` | integer or null | | Max environments to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max environments to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -1621,7 +1621,7 @@ rights. |---|---|:---:|---| | `cloud_environment_id` | string | yes | Id of the cloud environment the bucket belongs to. | | `prefix` | string or null | | Only the paths that start with this. | -| `limit` | integer or null | | Max paths to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max paths to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -1686,7 +1686,7 @@ Experimental in the DataLens API. An instance with none answers an empty list. | `sort_by` | `name` · `createdAt` · `updatedAt` or string or null | | The field to sort by. | | `reverse_order` | boolean or null | | Sort the other way round. | | `include_permissions` | boolean or null | | Also say what the caller may do with it. | -| `limit` | integer or null | | Max catalogs to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max catalogs to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -1734,7 +1734,7 @@ Experimental in the DataLens API. An instance with none answers an empty list. | `filter` | array of string or null | | Conditions the clusters must meet. | | `collection_id` | string or null | | Only the clusters of this collection. | | `catalog_id` | string or null | | Only the clusters this REST catalog is attached to. | -| `limit` | integer or null | | Max clusters to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max clusters to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -1846,7 +1846,7 @@ environment nothing knows answers 403 Permission denied, not 404. | Parameter | Type | Required | Description | |---|---|:---:|---| | `cloud_environment_id` | string | yes | The cloud environment the presets are of. | -| `limit` | integer or null | | Max presets to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max presets to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -1876,7 +1876,7 @@ nothing knows answers 403 Permission denied, not 404: it is not a lack of rights |---|---|:---:|---| | `cluster_id` | string | yes | Id of the Spark cluster. | | `filter` | array of string or null | | Conditions, all of which must hold; each is ``field="value"`` over ``name``, ``created_by``, ``application_type`` or ``catalog_id``. | -| `limit` | integer or null | | Max applications to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max applications to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | diff --git a/docs/en/reference/mcp/forms.md b/docs/en/reference/mcp/forms.md index 5d1c76635..e95c5a67b 100644 --- a/docs/en/reference/mcp/forms.md +++ b/docs/en/reference/mcp/forms.md @@ -26,7 +26,7 @@ form id you pass to ``surveys_get`` / ``questions_list`` / ``answers_list``. | Parameter | Type | Required | Description | |---|---|:---:|---| -| `limit` | integer or null | | Max forms to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max forms to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `name` | string or null | | Keep the forms whose name matches. | @@ -596,7 +596,7 @@ in the merged result. | Parameter | Type | Required | Description | |---|---|:---:|---| | `survey_id` | string | yes | Form id (24-char hex), from ``surveys_list``. | -| `limit` | integer or null | | Max answers to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max answers to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `questions` | string or null | | Comma-separated question ids to return answers for. | | `use_slugs` | boolean or null | | Name questions and options by slug instead of id. | | `date_from` | string or null | | ISO-8601: answers given at or after. | diff --git a/docs/en/reference/mcp/tracker.md b/docs/en/reference/mcp/tracker.md index 5390d9a55..db5c059b5 100644 --- a/docs/en/reference/mcp/tracker.md +++ b/docs/en/reference/mcp/tracker.md @@ -43,7 +43,7 @@ filters or raise ``limit``. | `assignee` | string or null | | Assignee login or id. | | `epic` | string or null | | Epic issue key. | | `issue_type` | string or null | | Issue type key, e.g. bug or task. | -| `limit` | integer or null | | Max issues to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max issues to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -62,7 +62,7 @@ scroll (``scroll_type``) works once: used again, it gives the portion after. E.g | Parameter | Type | Required | Description | |---|---|:---:|---| | `body` | object | yes | Typed request body for ``POST /issues/_search`` and ``POST /issues/_count``. Give ``query`` (the query language) or ``filter`` (field name → value); a body with neither matches every issue the caller can see. ``extra="allow"`` passes the API's other keys (``keys``, ``queue``, ``order``) through. | -| `limit` | integer or null | | Max issues to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max issues to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `expand` | string or null | | Extra blocks to include in the reply. | @@ -221,7 +221,7 @@ are truncated at the cap rather than fetched forever. | Parameter | Type | Required | Description | |---|---|:---:|---| | `issue_key` | string | yes | Issue key, e.g. QUEUE-123. | -| `limit` | integer or null | | Max comments to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max comments to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `expand` | string or null | | Extra blocks to include in the reply. | @@ -328,7 +328,7 @@ or fields matter; it carries each link's author, dates, assignee and status. | `issue_key` | string | yes | Issue key, e.g. QUEUE-123. | | `link_types` | array of string or null | | Keep only links with these relationships, e.g. ``relates`` or ``is subtask for`` (the phrases of ``links_create``, not linktypes ids). | | `fields` | array of string or null | | Fields to include in each link; all when omitted. | -| `limit` | integer or null | | Max links to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max links to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -410,7 +410,7 @@ creation-time range) use ``worklog_search`` instead. | Parameter | Type | Required | Description | |---|---|:---:|---| | `issue_key` | string | yes | Issue key, e.g. QUEUE-123. | -| `limit` | integer or null | | Max records to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max records to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -505,7 +505,7 @@ is given. | Parameter | Type | Required | Description | |---|---|:---:|---| | `issue_key` | string | yes | Issue key, e.g. QUEUE-123. | -| `limit` | integer or null | | Max changes to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max changes to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `field` | string or null | | Keep the changes of this field, e.g. ``status``. | @@ -750,7 +750,7 @@ is given; use ``users_get`` instead when you already know the specific login or | Parameter | Type | Required | Description | |---|---|:---:|---| -| `limit` | integer or null | | Max users to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max users to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `expand` | string or null | | Extra data to include per user, e.g. groups. | @@ -844,7 +844,7 @@ queue key (e.g. TEST) you pass to ``queues_get`` and use as an issue prefix (TES | Parameter | Type | Required | Description | |---|---|:---:|---| -| `limit` | integer or null | | Max queues to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max queues to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `expand` | string or null | | Extra blocks to include in the reply. | @@ -1346,7 +1346,7 @@ board's sprints. | Parameter | Type | Required | Description | |---|---|:---:|---| -| `limit` | integer or null | | Max boards to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max boards to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -1671,7 +1671,7 @@ Auto-paginated and capped at the configured item cap unless ``limit`` is given. | Parameter | Type | Required | Description | |---|---|:---:|---| | `queue_id` | string | yes | Queue key (case-sensitive, e.g. DESIGN) or numeric queue id. | -| `limit` | integer or null | | Max triggers to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max triggers to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -1926,7 +1926,7 @@ Returns the entities, and whether there are more. ``body.input`` matches part of | `entity_type` | string | yes | Entity type: ``project``, ``portfolio``, ``goal`` or ``report`` (issue reports). | | `body` | object or null | | What to find: name substring, filter, sort order; omit for all. | | `fields` | string or null | | Comma-separated extra fields to include. | -| `limit` | integer or null | | Max entities to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max entities to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | @@ -2570,7 +2570,7 @@ with an empty ``gaps`` list when they are not absent. | `users` | array of string | yes | Logins or ids of the users to look up (up to 100). | | `date_from` | string or null | | Window start (ISO 8601); defaults to now. | | `date_to` | string or null | | Window end (ISO 8601); must be after ``date_from``. | -| `limit` | integer or null | | Max users to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max users to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | diff --git a/docs/en/reference/mcp/wiki.md b/docs/en/reference/mcp/wiki.md index 93812b988..78cc50015 100644 --- a/docs/en/reference/mcp/wiki.md +++ b/docs/en/reference/mcp/wiki.md @@ -48,7 +48,7 @@ Capped at the configured item cap unless ``limit`` is given; narrow by SLUG for | Parameter | Type | Required | Description | |---|---|:---:|---| | `slug` | string | yes | Wiki page slug (its path), e.g. ``users/something/abc``. | -| `limit` | integer or null | | Max descendant refs to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max descendant refs to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `include_self` | boolean or null | | Also return the ancestor page itself. | @@ -337,7 +337,7 @@ Capped at the configured item cap unless ``limit`` is given. Pair with | Parameter | Type | Required | Description | |---|---|:---:|---| | `page_id` | integer | yes | Numeric page id, from ``pages_get_meta`` or a page ref. | -| `limit` | integer or null | | Max comments to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max comments to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `order_by` | string or null | | Sort field: ``created_at``. | @@ -421,7 +421,7 @@ downloading an attachment's bytes is CLI/SDK-only (binary blobs are not an MCP p | Parameter | Type | Required | Description | |---|---|:---:|---| | `page_id` | integer | yes | Numeric page id, from ``pages_get_meta`` or a page ref. | -| `limit` | integer or null | | Max attachments to return; omitted means the configured cap (YCLI__HTTP__MAX_ITEMS). | +| `limit` | integer or null | | Max attachments to return; omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS). | | `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | | `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | | `order_by` | `name` · `size` · `created_at` or string or null | | Sort field. | diff --git a/docs/ru/how-to/script-the-cli.md b/docs/ru/how-to/script-the-cli.md index c4a65c167..a44f52512 100644 --- a/docs/ru/how-to/script-the-cli.md +++ b/docs/ru/how-to/script-the-cli.md @@ -38,7 +38,7 @@ stopped at 100 of 752; go on with: ycli tracker issues search 'Queue: DE' --next $ ycli tracker issues search 'Queue: DE' --limit 100 --next eyJ2IjoxLCJvZiI6… > second.json ``` -Токен несёт свой список: с `--next` задают только лимит и то, без чего команду не вызвать, причём таким же, как было: аргумент, который расходится с токеном, получает отказ с его именем, а не отбрасывается молча. Токен поиска задач Трекера с прокруткой (`--scroll-type`) работает один раз; любой другой токен можно использовать повторно. Список, который уже нельзя продолжить, завершается кодом `9`: начните его заново без токена. Запуск, которому нужно больше страниц, чем `YCLI__HTTP__MAX_PAGES`, останавливается на этом пределе и говорит об этом так же, с токеном для продолжения. +Токен несёт свой список: с `--next` задают только лимит и то, без чего команду не вызвать, причём таким же, как было: аргумент, который расходится с токеном, получает отказ с его именем, а не отбрасывается молча. Токен поиска задач Трекера с прокруткой (`--scroll-type`) работает один раз; любой другой токен можно использовать повторно. Список, который уже нельзя продолжить, завершается кодом `9`: начните его заново без токена. Запуск, которому нужно больше страниц, чем `YCLI__HTTP__MAX_PAGES`, останавливается на этом пределе и говорит об этом так же, с токеном для продолжения. Маленький первый `--limit` задаёт размер страниц для всех следующих частей, поэтому берите первую часть такой же величины, какими собираетесь продолжать. ## Удаление без запроса подтверждения diff --git a/docs/ru/reference/configuration.md b/docs/ru/reference/configuration.md index f31ee9434..03d3a6921 100644 --- a/docs/ru/reference/configuration.md +++ b/docs/ru/reference/configuration.md @@ -34,7 +34,8 @@ DataLens принимает IAM-токен или ключ сервисного |---|---|---| | `YCLI__HTTP__TIMEOUT_SECONDS` | `30` | тайм-аут одного запроса, секунды (> 0) | | `YCLI__HTTP__RETRIES` | `3` | число повторов идемпотентного запроса после ответа 429 или 5xx (≥ 0) | -| `YCLI__HTTP__MAX_ITEMS` | `500` | предел числа элементов в списке без `--limit` или `--all` (> 0) | +| `YCLI__HTTP__MAX_ITEMS` | `500` | предел числа элементов в списке команды без `--limit` или `--all` (> 0) | +| `YCLI__HTTP__MAX_TOOL_ITEMS` | `50` | предел числа элементов в списке инструмента MCP-сервера без `limit` или `all`: его ответ целиком попадает в контекст модели (> 0) | | `YCLI__HTTP__MAX_PAGES` | `1000` | предел числа страниц одного списка: бесконечный список останавливается здесь с предупреждением (> 0) | | `YCLI__HTTP__MAX_TOKEN_LENGTH` | `16384` | наибольшая длина токена `next`: более длинный отвергается до разбора (> 0) | | `YCLI__HTTP__MAX_RETRY_AFTER_SECONDS` | `60` | самая долгая пауза, которую ответ 429 может запросить в `Retry-After`; при более долгой запрос сразу завершается ошибкой (> 0) | diff --git a/e2e/README.md b/e2e/README.md index 2771a1740..fb800ea63 100644 --- a/e2e/README.md +++ b/e2e/README.md @@ -64,7 +64,7 @@ A log of the CI job is public. When a step fails, the runner prints its command | `name`, `smoke` | test id; `smoke: true` also runs on pull requests | | `permanent` | `true` for a scenario that makes what the API cannot delete: it is skipped unless the run is given `--permanent` | | `steps[].run` | arguments after `ycli -o json --yes`; `${RUN}`, `${TAG}` (the four hex digits of the run's name, for a key that takes no dash), `${QUEUE}`, `${FILES}` (the directory `e2e/files`) and saved names are substituted | -| `steps[].output` | `json` (default); `text` for a command that prints raw text, such as `wiki pages get`; `bytes` for one that prints a file: `expect` then sees `size` and `head`, the first 16 bytes in hex (`"starts_with(head, '89504e47')": true` for a PNG) | +| `steps[].output` | `json` (default; a listing is read as its items); `listing` for a listing as it is printed, `{items, truncated, next, total}`; `text` for a command that prints raw text, such as `wiki pages get`; `bytes` for one that prints a file: `expect` then sees `size` and `head`, the first 16 bytes in hex (`"starts_with(head, '89504e47')": true` for a PNG) | | `steps[].expect` | JMESPath expression → expected value; `unique(array)` is added for duplicate checks | | `steps[].save` | name → JMESPath expression; later steps use `${name}` | | `steps[].cleanup` | command run when the scenario ends, newest first, even after a failure | diff --git a/e2e/models.py b/e2e/models.py index 386fbab32..170c31fab 100644 --- a/e2e/models.py +++ b/e2e/models.py @@ -46,10 +46,12 @@ class Step(BaseModel): id: str run: str - output: Literal["json", "text", "bytes"] = Field( + output: Literal["json", "listing", "text", "bytes"] = Field( default="json", - description="text: the command prints raw text (e.g. page markdown). bytes: it prints " - "a file; `expect` sees `size` and `head` (the first 16 bytes, in hex).", + description="json: a listing is read as its items. listing: as it is printed, " + "`{items, truncated, next, total}`. text: the command prints raw text (e.g. page " + "markdown). bytes: it prints a file; `expect` sees `size` and `head` (the first 16 " + "bytes, in hex).", ) expect: dict[str, Any] = Field(default_factory=dict) save: dict[str, str] = Field(default_factory=dict) diff --git a/e2e/runner.py b/e2e/runner.py index 55abea3a8..21eddc398 100644 --- a/e2e/runner.py +++ b/e2e/runner.py @@ -318,9 +318,10 @@ def _parse(where: str, step: Step, completed: CommandResult) -> Any: if not stdout.strip(): return None try: - return items(json.loads(stdout)) + document = json.loads(stdout) except json.JSONDecodeError: raise ScenarioError(f"{where} output is not JSON: {scrub(stdout)}") from None + return document if step.output == "listing" else items(document) def _shape(document: Any) -> str: diff --git a/e2e/scenarios/tracker/reads.yaml b/e2e/scenarios/tracker/reads.yaml index ae0605078..a7ac2a2c7 100644 --- a/e2e/scenarios/tracker/reads.yaml +++ b/e2e/scenarios/tracker/reads.yaml @@ -32,6 +32,15 @@ steps: - tracker workflows list-for-queue ${QUEUE} - tracker worklog search --created-from 2026-01-01T00:00:00 --created-to 2026-01-02T00:00:00 - tracker worklog list-global + - id: where-a-listing-stopped + # A listing as `-o json` prints it, on a real reply: the items, and where it stopped. + run: tracker users list --limit 1 + output: listing + expect: + "length(items)": 1 + truncated: true + "type(next)": string + "contains(keys(@), 'total')": true - id: trigger-webhook-log needs: [TRIGGER] # The kept trigger is switched off, so its log may well be empty: only the reply's kind is diff --git a/e2e/surfaces.py b/e2e/surfaces.py index 301bdc804..f022fbe89 100644 --- a/e2e/surfaces.py +++ b/e2e/surfaces.py @@ -21,11 +21,13 @@ import importlib import inspect import json +import os import re import typing from collections.abc import Callable, Iterator, Sequence from dataclasses import dataclass, field from typing import Any, Literal +from unittest.mock import patch import httpx2 import pytest @@ -521,8 +523,11 @@ def _mcp(self, call: Call) -> Any: sent = self._tool_arguments(call, tool) if sent is None: return _NO_JSON + # The surfaces are compared at one cap: a tool gives fewer by default than a command. + cap = {"YCLI__HTTP__MAX_TOOL_ITEMS": str(AppConfig().http.max_items)} try: - data = self._runner.run(self._call_tool(tool.name, sent)) + with patch.dict(os.environ, cap): + data = self._runner.run(self._call_tool(tool.name, sent)) except ToolError as error: return _Failed(hidden(str(error), self._listener.variables)) return _unwrapped(tool, data) diff --git a/plugins/yandex-360/skills/yandex-360/SKILL.md b/plugins/yandex-360/skills/yandex-360/SKILL.md index 3edf99ac2..c82de6fcc 100644 --- a/plugins/yandex-360/skills/yandex-360/SKILL.md +++ b/plugins/yandex-360/skills/yandex-360/SKILL.md @@ -120,7 +120,8 @@ semantics, a service ycli does not wrap yet), read the official docs directly, a adding it. `--dry-run` prints the write request instead of sending it, the JSON result pipes to `jq`, and the exit code says what failed (3 not found, 4 auth, 5 rate limited, 6 transient). -- **A long listing comes in pieces** — a list tool returns `{items, truncated, next}`; when +- **A long listing comes in pieces** — a list tool returns `{items, truncated, next}`, 50 + items unless you give `limit` (a command gives 500); when `truncated` is true, call it again with that `next`, its required arguments as they were and nothing else but `limit` (the token carries its listing; an argument that differs from it is refused by name). `all=true` returns everything at once and can overflow the context. diff --git a/src/ycli/settings.py b/src/ycli/settings.py index 28ddf7b8b..bfaa37f30 100644 --- a/src/ycli/settings.py +++ b/src/ycli/settings.py @@ -124,6 +124,8 @@ class HTTPConfig(BaseModel): timeout_seconds: PositiveFloat = 30.0 retries: NonNegativeInt = 3 max_items: PositiveInt = 500 + # What a tool gives when no `limit` is asked: its answer is read whole into a context. + max_tool_items: PositiveInt = 50 # A listing that never ends by itself stops after this many pages. max_pages: PositiveInt = 1000 # The longest `next` token read: a caller far away sends it, so it is bounded before decoding. @@ -134,13 +136,13 @@ class HTTPConfig(BaseModel): max_wait_seconds: PositiveFloat = 1380.0 def cap(self, limit: int | None, *, all_: bool = False) -> int | None: - """A listing's item cap from ``limit`` and "everything", on the CLI and in a tool alike. + """A listing's item cap from ``limit`` and "everything", on the CLI. "Everything" uncaps (``None``); a given ``limit`` wins; otherwise ``max_items``. Args: - limit: The ``--limit`` option or a tool's ``limit``; ``None`` when not given. - all_: The CLI's ``--all`` flag, or a tool's ``all``. + limit: The ``--limit`` option; ``None`` when not given. + all_: The ``--all`` flag. Returns: The most items to fetch, or ``None`` for no cap. @@ -155,6 +157,23 @@ def cap(self, limit: int | None, *, all_: bool = False) -> int | None: """ return None if all_ else (self.max_items if limit is None else limit) + def tool_cap(self, limit: int | None, *, all_: bool = False) -> int | None: + """:meth:`cap` for a tool of the MCP server: ``max_tool_items`` where no limit is given. + + Args: + limit: The tool's ``limit``; ``None`` when not given. + all_: The tool's ``all``. + + Returns: + The most items to fetch, or ``None`` for no cap. + + Examples: + >>> tools = HTTPConfig() + >>> tools.tool_cap(None), tools.tool_cap(10), tools.tool_cap(1, all_=True) + (50, 10, None) + """ + return None if all_ else (self.max_tool_items if limit is None else limit) + # `ycli doctor` asks PyPI for the latest release: one short attempt, so it never holds the report. RELEASE_CHECK_HTTP = HTTPConfig(timeout_seconds=3.0, retries=0) diff --git a/src/ycli/yandex/datalens/audit/mcp.py b/src/ycli/yandex/datalens/audit/mcp.py index e3ca40a39..8b325a8ed 100644 --- a/src/ycli/yandex/datalens/audit/mcp.py +++ b/src/ycli/yandex/datalens/audit/mcp.py @@ -44,7 +44,7 @@ def entries_updates_list( A deleted entry is listed too, with ``isDeleted``. """ return client.audit.entries_updates_list( - from_, to=to, limit=config.http.cap(limit, all_=all), next=next + from_, to=to, limit=config.http.tool_cap(limit, all_=all), next=next ).collect() diff --git a/src/ycli/yandex/datalens/cloudenvironments/mcp.py b/src/ycli/yandex/datalens/cloudenvironments/mcp.py index f23bf1838..88525ef39 100644 --- a/src/ycli/yandex/datalens/cloudenvironments/mcp.py +++ b/src/ycli/yandex/datalens/cloudenvironments/mcp.py @@ -63,7 +63,7 @@ def list_( return client.cloudenvironments.list( filter=filter, include_permissions=include_permissions, - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, ).collect() diff --git a/src/ycli/yandex/datalens/cloudenvironmentstorage/mcp.py b/src/ycli/yandex/datalens/cloudenvironmentstorage/mcp.py index 5d16ea72d..c89709e9a 100644 --- a/src/ycli/yandex/datalens/cloudenvironmentstorage/mcp.py +++ b/src/ycli/yandex/datalens/cloudenvironmentstorage/mcp.py @@ -54,7 +54,7 @@ def bucket_objects_list( rights. """ return client.cloudenvironmentstorage.bucket_objects_list( - cloud_environment_id, prefix=prefix, limit=config.http.cap(limit, all_=all), next=next + cloud_environment_id, prefix=prefix, limit=config.http.tool_cap(limit, all_=all), next=next ).collect() diff --git a/src/ycli/yandex/datalens/collections/mcp.py b/src/ycli/yandex/datalens/collections/mcp.py index 2f5235e8a..bb03c7a9d 100644 --- a/src/ycli/yandex/datalens/collections/mcp.py +++ b/src/ycli/yandex/datalens/collections/mcp.py @@ -96,7 +96,7 @@ def content_list( """ return client.collections.content_list( collection_id, - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, filter_string=filter_string, order_field=order_field, @@ -151,7 +151,7 @@ def access_bindings_list( """Who has which role on a collection, auto-paginated.""" return client.collections.access_bindings_list( collection_id, - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, get_inherited_bindings=get_inherited_bindings, ).collect() diff --git a/src/ycli/yandex/datalens/entries/mcp.py b/src/ycli/yandex/datalens/entries/mcp.py index 0b5ef123f..ef8a79ccc 100644 --- a/src/ycli/yandex/datalens/entries/mcp.py +++ b/src/ycli/yandex/datalens/entries/mcp.py @@ -86,7 +86,7 @@ def list_( cap unless ``limit`` is given. """ return client.entries.list( - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, ids=ids, scope=scope, @@ -132,7 +132,7 @@ def relations_list( """ return client.entries.relations_list( entry_ids, - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, link_direction=link_direction, include_permissions_info=include_permissions_info, @@ -170,7 +170,7 @@ def revisions_list( ) -> Listed[Revision]: """The revisions of an entry: who saved it and when. Auto-paginated.""" return client.entries.revisions_list( - entry_id, limit=config.http.cap(limit, all_=all), next=next, rev_ids=rev_ids + entry_id, limit=config.http.tool_cap(limit, all_=all), next=next, rev_ids=rev_ids ).collect() diff --git a/src/ycli/yandex/datalens/licensing/mcp.py b/src/ycli/yandex/datalens/licensing/mcp.py index a85e1b3ce..1833a3f12 100644 --- a/src/ycli/yandex/datalens/licensing/mcp.py +++ b/src/ycli/yandex/datalens/licensing/mcp.py @@ -58,7 +58,7 @@ def licenses_list( status=status, sort_by=sort_by, order=order, - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, ).collect() diff --git a/src/ycli/yandex/datalens/members/mcp.py b/src/ycli/yandex/datalens/members/mcp.py index 7b87b1ba8..a437fb69d 100644 --- a/src/ycli/yandex/datalens/members/mcp.py +++ b/src/ycli/yandex/datalens/members/mcp.py @@ -47,7 +47,7 @@ def list_( the configured item cap unless ``limit`` is given. """ return client.members.list( - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, language=language, search=search, diff --git a/src/ycli/yandex/datalens/restcatalogs/mcp.py b/src/ycli/yandex/datalens/restcatalogs/mcp.py index 5369cbf07..8c0fbc336 100644 --- a/src/ycli/yandex/datalens/restcatalogs/mcp.py +++ b/src/ycli/yandex/datalens/restcatalogs/mcp.py @@ -61,7 +61,7 @@ def list_( sort_by=sort_by, reverse_order=reverse_order, include_permissions=include_permissions, - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, ).collect() diff --git a/src/ycli/yandex/datalens/sharedentries/mcp.py b/src/ycli/yandex/datalens/sharedentries/mcp.py index b30e878d3..4850597a3 100644 --- a/src/ycli/yandex/datalens/sharedentries/mcp.py +++ b/src/ycli/yandex/datalens/sharedentries/mcp.py @@ -50,7 +50,7 @@ def access_bindings_list( """ return client.sharedentries.access_bindings_list( entry_id, - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, get_inherited_bindings=get_inherited_bindings, ).collect() diff --git a/src/ycli/yandex/datalens/sparkapplications/mcp.py b/src/ycli/yandex/datalens/sparkapplications/mcp.py index ea4ec13b9..73cda306f 100644 --- a/src/ycli/yandex/datalens/sparkapplications/mcp.py +++ b/src/ycli/yandex/datalens/sparkapplications/mcp.py @@ -57,7 +57,7 @@ def list_( nothing knows answers 403 Permission denied, not 404: it is not a lack of rights. """ return client.sparkapplications.list( - cluster_id, filter=filter, limit=config.http.cap(limit, all_=all), next=next + cluster_id, filter=filter, limit=config.http.tool_cap(limit, all_=all), next=next ).collect() diff --git a/src/ycli/yandex/datalens/sparkclusters/mcp.py b/src/ycli/yandex/datalens/sparkclusters/mcp.py index db11d6a5a..9935b8f81 100644 --- a/src/ycli/yandex/datalens/sparkclusters/mcp.py +++ b/src/ycli/yandex/datalens/sparkclusters/mcp.py @@ -54,7 +54,7 @@ def list_( cap unless ``limit`` is given. """ return client.sparkclusters.list( - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, collection_id=collection_id, filter=filter, @@ -162,7 +162,7 @@ def resource_presets_list( Experimental API, not measured. Capped at the configured item cap unless ``limit`` is given. """ return client.sparkclusters.resource_presets_list( - cloud_environment_id, limit=config.http.cap(limit, all_=all), next=next + cloud_environment_id, limit=config.http.tool_cap(limit, all_=all), next=next ).collect() diff --git a/src/ycli/yandex/datalens/trinoclusters/mcp.py b/src/ycli/yandex/datalens/trinoclusters/mcp.py index b40135613..27beebbff 100644 --- a/src/ycli/yandex/datalens/trinoclusters/mcp.py +++ b/src/ycli/yandex/datalens/trinoclusters/mcp.py @@ -61,7 +61,7 @@ def list_( filter=filter, collection_id=collection_id, catalog_id=catalog_id, - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, ).collect() @@ -213,7 +213,7 @@ def resource_presets_list( environment nothing knows answers 403 Permission denied, not 404. """ return client.trinoclusters.resource_presets_list( - cloud_environment_id, limit=config.http.cap(limit, all_=all), next=next + cloud_environment_id, limit=config.http.tool_cap(limit, all_=all), next=next ).collect() diff --git a/src/ycli/yandex/datalens/workbooks/mcp.py b/src/ycli/yandex/datalens/workbooks/mcp.py index 06a36293b..85f8ba701 100644 --- a/src/ycli/yandex/datalens/workbooks/mcp.py +++ b/src/ycli/yandex/datalens/workbooks/mcp.py @@ -81,7 +81,7 @@ def list_( collection holds. Capped at the configured item cap unless ``limit`` is given. """ return client.workbooks.list( - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, collection_id=collection_id, filter_string=filter_string, @@ -123,7 +123,7 @@ def access_bindings_list( """Who has which role on a workbook, auto-paginated.""" return client.workbooks.access_bindings_list( workbook_id, - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, get_inherited_bindings=get_inherited_bindings, ).collect() @@ -170,7 +170,7 @@ def entries_list( """ return client.workbooks.entries_list( workbook_id, - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, include_permissions_info=include_permissions_info, only_my=only_my, diff --git a/src/ycli/yandex/forms/answers/mcp.py b/src/ycli/yandex/forms/answers/mcp.py index 87a27416b..17ffc86ce 100644 --- a/src/ycli/yandex/forms/answers/mcp.py +++ b/src/ycli/yandex/forms/answers/mcp.py @@ -97,7 +97,7 @@ def list_( """ return client.answers.list( survey_id, - limit=config.http.cap(limit), + limit=config.http.tool_cap(limit), questions=questions, use_slugs=use_slugs, date_from=date_from, diff --git a/src/ycli/yandex/forms/history/mcp.py b/src/ycli/yandex/forms/history/mcp.py index d392c1876..5ceffa963 100644 --- a/src/ycli/yandex/forms/history/mcp.py +++ b/src/ycli/yandex/forms/history/mcp.py @@ -33,5 +33,5 @@ def list_( Capped at the configured item cap unless ``limit`` is given. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.history.list(survey_id, ordering=ordering, limit=cap, next=next).collect() diff --git a/src/ycli/yandex/forms/notifications/mcp.py b/src/ycli/yandex/forms/notifications/mcp.py index 922deb335..4d48ed114 100644 --- a/src/ycli/yandex/forms/notifications/mcp.py +++ b/src/ycli/yandex/forms/notifications/mcp.py @@ -79,7 +79,7 @@ def list_( narrow that form's runs. Capped at the configured item cap unless ``limit`` is given. Read one run's context, response and error with ``notifications_get``. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.notifications.list( survey_id=survey_id, hook_id=hook_id, diff --git a/src/ycli/yandex/forms/surveys/mcp.py b/src/ycli/yandex/forms/surveys/mcp.py index 66f289b30..37c7aa527 100644 --- a/src/ycli/yandex/forms/surveys/mcp.py +++ b/src/ycli/yandex/forms/surveys/mcp.py @@ -59,7 +59,7 @@ def list_( Capped at the configured item cap unless ``limit`` is given. Each item's ``id`` is the form id you pass to ``surveys_get`` / ``questions_list`` / ``answers_list``. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.surveys.list( limit=cap, next=next, diff --git a/src/ycli/yandex/mcp.py b/src/ycli/yandex/mcp.py index 48ad14dda..5269efd2b 100644 --- a/src/ycli/yandex/mcp.py +++ b/src/ycli/yandex/mcp.py @@ -67,8 +67,8 @@ NEEDS_TOOLS = "ycli_needs_tools" REPEATS_TOOL = "ycli_repeats_tool" # The tail of every listing tool's `limit` description. It names the setting, not its value, -# so the text stays true when HTTPConfig.max_items or the environment changes the cap. -LIMIT_CAP = "omitted means the configured cap (YCLI__HTTP__MAX_ITEMS)." +# so the text stays true when HTTPConfig.max_tool_items or the environment changes the cap. +LIMIT_CAP = "omitted means the configured cap of a tool (YCLI__HTTP__MAX_TOOL_ITEMS)." # The other two handles of a listing, the same on every tool that has `limit` (#502). All = Annotated[ bool, diff --git a/src/ycli/yandex/tracker/boards/mcp.py b/src/ycli/yandex/tracker/boards/mcp.py index c0f82288b..2e92fd4cb 100644 --- a/src/ycli/yandex/tracker/boards/mcp.py +++ b/src/ycli/yandex/tracker/boards/mcp.py @@ -43,7 +43,7 @@ def list_( is given. Use ``boards_get`` when you know one board id, and ``sprints_list`` to list a board's sprints. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.boards.list(limit=cap, next=next).collect() diff --git a/src/ycli/yandex/tracker/changelog/mcp.py b/src/ycli/yandex/tracker/changelog/mcp.py index 79089edff..6a00eb7a2 100644 --- a/src/ycli/yandex/tracker/changelog/mcp.py +++ b/src/ycli/yandex/tracker/changelog/mcp.py @@ -47,7 +47,7 @@ def list_( Auto-paginated via the relative id-cursor. Capped at the configured item cap unless ``limit`` is given. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.changelog.list( issue_key, limit=cap, next=next, field=field, change_type=change_type, sort=sort ).collect() diff --git a/src/ycli/yandex/tracker/comments/mcp.py b/src/ycli/yandex/tracker/comments/mcp.py index a4c2037cc..f4c4edea9 100644 --- a/src/ycli/yandex/tracker/comments/mcp.py +++ b/src/ycli/yandex/tracker/comments/mcp.py @@ -47,7 +47,7 @@ def list_( Capped at the configured item cap unless ``limit`` is given, so very long threads are truncated at the cap rather than fetched forever. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.comments.list(issue_key, limit=cap, next=next, expand=expand).collect() diff --git a/src/ycli/yandex/tracker/entities/mcp.py b/src/ycli/yandex/tracker/entities/mcp.py index cb1c29f26..9530e155e 100644 --- a/src/ycli/yandex/tracker/entities/mcp.py +++ b/src/ycli/yandex/tracker/entities/mcp.py @@ -120,7 +120,7 @@ def search( ``body.filter`` is a field → value object (author, status, followers, …), ``body.orderBy`` with ``body.orderAsc`` sorts, and ``body.rootOnly`` keeps the entities with no parent. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.entities.search(entity_type, body, fields=fields, limit=cap, next=next).collect() @@ -152,7 +152,7 @@ def events_list( Each event carries an author, a timestamp, a display title and the individual field changes. Capped at the configured item cap unless ``limit`` is given. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.entities.events_list( entity_type, entity_id, @@ -311,7 +311,7 @@ def comments_list_relative( Prefer this over ``entities_comments_list`` when the comment thread is long — it drains pages up to ``limit`` (the configured item cap by default). """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.entities.comments_list_relative( entity_type, entity_id, limit=cap, next=next ).collect() diff --git a/src/ycli/yandex/tracker/gaps/mcp.py b/src/ycli/yandex/tracker/gaps/mcp.py index 271a5bada..ead278cdf 100644 --- a/src/ycli/yandex/tracker/gaps/mcp.py +++ b/src/ycli/yandex/tracker/gaps/mcp.py @@ -48,7 +48,7 @@ def search( A read done via POST; needs Tracker administrator rights. Every requested user appears, with an empty ``gaps`` list when they are not absent. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.gaps.search( users, date_from=date_from, date_to=date_to, limit=cap, next=next ).collect() diff --git a/src/ycli/yandex/tracker/issues/mcp.py b/src/ycli/yandex/tracker/issues/mcp.py index b13749333..43c9438a8 100644 --- a/src/ycli/yandex/tracker/issues/mcp.py +++ b/src/ycli/yandex/tracker/issues/mcp.py @@ -82,7 +82,9 @@ def list_( epic=epic, type_=issue_type, ) - return client.issues.search(body, limit=config.http.cap(limit, all_=all), next=next).collect() + return client.issues.search( + body, limit=config.http.tool_cap(limit, all_=all), next=next + ).collect() @mcp.tool(name="issues_search", annotations={**RO, "title": "Search Tracker issues"}) @@ -115,7 +117,7 @@ def search( """ return client.issues.search( body, - limit=config.http.cap(limit, all_=all), + limit=config.http.tool_cap(limit, all_=all), next=next, expand=expand, scroll_type=scroll_type, diff --git a/src/ycli/yandex/tracker/links/mcp.py b/src/ycli/yandex/tracker/links/mcp.py index 6c340099e..b9b7aa68f 100644 --- a/src/ycli/yandex/tracker/links/mcp.py +++ b/src/ycli/yandex/tracker/links/mcp.py @@ -59,7 +59,7 @@ def list_filtered( Prefer this over ``links_list`` for issues with many links or when only some link types or fields matter; it carries each link's author, dates, assignee and status. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.links.list_filtered( issue_key, link_types=link_types, fields=fields, limit=cap, next=next ).collect() diff --git a/src/ycli/yandex/tracker/queues/mcp.py b/src/ycli/yandex/tracker/queues/mcp.py index 6b0be240f..99db97e12 100644 --- a/src/ycli/yandex/tracker/queues/mcp.py +++ b/src/ycli/yandex/tracker/queues/mcp.py @@ -56,7 +56,7 @@ def list_( queue key (e.g. TEST) you pass to ``queues_get`` and use as an issue prefix (TEST-123). Use ``queues_get`` for a single queue's full configuration (types, workflows, resolutions). """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.queues.list(limit=cap, next=next, expand=expand).collect() diff --git a/src/ycli/yandex/tracker/triggers/mcp.py b/src/ycli/yandex/tracker/triggers/mcp.py index 15c17211a..2e3bf21a5 100644 --- a/src/ycli/yandex/tracker/triggers/mcp.py +++ b/src/ycli/yandex/tracker/triggers/mcp.py @@ -49,7 +49,7 @@ def list_( Auto-paginated and capped at the configured item cap unless ``limit`` is given. Use ``triggers_get`` for one trigger by id. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.triggers.list(queue_id, limit=cap, next=next).collect() diff --git a/src/ycli/yandex/tracker/users/mcp.py b/src/ycli/yandex/tracker/users/mcp.py index eb303d4ac..ec8788718 100644 --- a/src/ycli/yandex/tracker/users/mcp.py +++ b/src/ycli/yandex/tracker/users/mcp.py @@ -63,5 +63,5 @@ def list_( Auto-paginated via the relative id-cursor. Capped at the configured item cap unless ``limit`` is given; use ``users_get`` instead when you already know the specific login or uid. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.users.list(limit=cap, next=next, expand=expand).collect() diff --git a/src/ycli/yandex/tracker/worklog/mcp.py b/src/ycli/yandex/tracker/worklog/mcp.py index ae807b095..1ee2f751f 100644 --- a/src/ycli/yandex/tracker/worklog/mcp.py +++ b/src/ycli/yandex/tracker/worklog/mcp.py @@ -53,7 +53,7 @@ def list_( Scoped to one issue by ``issue_key``. To search worklog across the whole org (by author and/or a creation-time range) use ``worklog_search`` instead. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.worklog.list(issue_key, limit=cap, next=next).collect() diff --git a/src/ycli/yandex/wiki/attachments/mcp.py b/src/ycli/yandex/wiki/attachments/mcp.py index 35ca9e0dc..eca008ae4 100644 --- a/src/ycli/yandex/wiki/attachments/mcp.py +++ b/src/ycli/yandex/wiki/attachments/mcp.py @@ -49,7 +49,7 @@ def list_( Capped at the configured item cap unless ``limit`` is given. This is the list surface; downloading an attachment's bytes is CLI/SDK-only (binary blobs are not an MCP payload). """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.attachments.list( page_id=page_id, limit=cap, diff --git a/src/ycli/yandex/wiki/comments/mcp.py b/src/ycli/yandex/wiki/comments/mcp.py index d100289d6..d6d412aee 100644 --- a/src/ycli/yandex/wiki/comments/mcp.py +++ b/src/ycli/yandex/wiki/comments/mcp.py @@ -54,7 +54,7 @@ def list_( Capped at the configured item cap unless ``limit`` is given. Pair with ``pages_get_meta`` (its ``attributes.comments_count`` tells you how many exist). """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.comments.list( page_id=page_id, limit=cap, @@ -83,7 +83,7 @@ def thread_list( ``limit`` is given. Use ``comments_list`` first to discover a root comment id, then this to read its thread. """ - cap = config.http.cap(limit) + cap = config.http.tool_cap(limit) return client.comments.thread_list(page_id=page_id, comment_id=comment_id, limit=cap) @@ -108,7 +108,7 @@ def thread_get( root comment or a reply, plain or inline. Use ``comments_thread_list``, which rebuilds the thread from the page's comment list. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.comments.thread_get( page_id=page_id, comment_id=comment_id, limit=cap, next=next ).collect() diff --git a/src/ycli/yandex/wiki/pages/mcp.py b/src/ycli/yandex/wiki/pages/mcp.py index c8b783eb7..d0f9bf53f 100644 --- a/src/ycli/yandex/wiki/pages/mcp.py +++ b/src/ycli/yandex/wiki/pages/mcp.py @@ -102,7 +102,7 @@ def descendants_list( Capped at the configured item cap unless ``limit`` is given; narrow by SLUG for large trees. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.pages.descendants_list( slug=slug, limit=cap, @@ -132,7 +132,7 @@ def grids_list( unless ``limit`` is given. Reads a page's numeric id — pair with ``pages_get_meta`` / ``pages_descendants_list`` (whose refs carry the ids) to find one. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.pages.grids_list( page_id=page_id, limit=cap, @@ -194,7 +194,7 @@ def descendants_list_by_id( unless ``limit`` is given; each ref carries the child's numeric ``id`` and permanent ``slug``. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.pages.descendants_list_by_id( page_id=page_id, limit=cap, @@ -370,7 +370,7 @@ def revisions_list( ``created_at``, ``page_type`` and publication state. Yandex does not document this operation (it is in the live OpenAPI only) and may change it. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.pages.revisions_list(page_id=page_id, ids=ids, limit=cap, next=next).collect() @@ -400,7 +400,7 @@ def backlinks_list( Auto-paginated. Yandex does not document this operation (it is in the live OpenAPI only) and may change it. """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.pages.backlinks_list( page_id=page_id, for_cluster=for_cluster, show_all=show_all, limit=cap, next=next ).collect() diff --git a/src/ycli/yandex/wiki/resources/mcp.py b/src/ycli/yandex/wiki/resources/mcp.py index caf64eb72..42e7046ae 100644 --- a/src/ycli/yandex/wiki/resources/mcp.py +++ b/src/ycli/yandex/wiki/resources/mcp.py @@ -39,7 +39,7 @@ def list_( expose separately (drains ``next_cursor`` internally). Capped at the configured item cap unless ``limit`` is given; narrow with ``q`` (title) or ``types`` (``attachment,grid``). """ - cap = config.http.cap(limit, all_=all) + cap = config.http.tool_cap(limit, all_=all) return client.resources.list( page_id=page_id, limit=cap, diff --git a/tests/architecture/test_arch5.py b/tests/architecture/test_arch5.py index f03f35a45..3c4e622ab 100644 --- a/tests/architecture/test_arch5.py +++ b/tests/architecture/test_arch5.py @@ -9,7 +9,7 @@ # `timeout=30` as a keyword argument, or `timeout: float = 30.0` as an annotated default. _LITERAL_DEFAULT_RE = re.compile( - r"\b(timeout|timeout_seconds|retries|max_items|max_pages|max_retry_after_seconds|" + r"\b(timeout|timeout_seconds|retries|max_items|max_tool_items|max_pages|max_retry_after_seconds|" r"max_wait_seconds)" r"\s*(:[^=\n]+)?=\s*\d" ) diff --git a/tests/contract/test_contract.py b/tests/contract/test_contract.py index 641383ea2..986ebcf52 100644 --- a/tests/contract/test_contract.py +++ b/tests/contract/test_contract.py @@ -38,6 +38,7 @@ from tests.mock_api import MockAPI from tests.snapshots._surface import cli_tree from ycli.cli.app import app +from ycli.settings import AppConfig from ycli.yandex.core.auth import IAMTokenAuth from ycli.yandex.core.listing import Listing from ycli.yandex.core.resource import Resource @@ -72,6 +73,9 @@ def _serve(monkeypatch: pytest.MonkeyPatch, case: Case) -> MockAPI: # A service of Yandex Cloud names its organization with another id (``tests/conftest.py`` # sets the Yandex 360 one). monkeypatch.setenv("YANDEX_CLOUD_ORGANIZATION_ID", "c") + # One case states the requests of every surface, so a tool is given the cap of a command: + # what a tool gives by default is held by `test_listing_handles`. + monkeypatch.setenv("YCLI__HTTP__MAX_TOOL_ITEMS", str(AppConfig().http.max_items)) if not SERVICE_BY_NAME[case.domain].profile.oauth_token: # The service takes an IAM token only: one way to sign in, so the OAuth token goes. monkeypatch.delenv("YANDEX_ID_OAUTH_TOKEN", raising=False) diff --git a/tests/tooling/test_e2e_runner.py b/tests/tooling/test_e2e_runner.py index 34432bcad..75b485822 100644 --- a/tests/tooling/test_e2e_runner.py +++ b/tests/tooling/test_e2e_runner.py @@ -349,3 +349,12 @@ def test_a_listing_is_read_as_its_items_and_any_other_document_as_it_is(): # An object that only has a field called `items` is no listing. assert items({"items": [1], "name": "form"}) == {"items": [1], "name": "form"} assert items([1, 2]) == [1, 2] + + +def test_a_step_reads_a_listing_as_its_items_or_as_it_is_printed(): + printed = {"items": [{"id": 1}], "truncated": True, "next": "t", "total": None} + driver = ScriptedDriver({"boards": _ok(printed)}) + run_scenario(_scenario({"id": "a", "run": "boards", "expect": {"length(@)": 1}}), driver, {}) + held = {"length(items)": 1, "truncated": True, "type(next)": "string"} + whole: dict[str, object] = {"id": "a", "run": "boards", "output": "listing", "expect": held} + run_scenario(_scenario(whole), driver, {}) diff --git a/tests/unit/cli/test_listing_handles.py b/tests/unit/cli/test_listing_handles.py index bf34352f2..2e91c3873 100644 --- a/tests/unit/cli/test_listing_handles.py +++ b/tests/unit/cli/test_listing_handles.py @@ -152,7 +152,7 @@ def test_a_tool_returns_the_items_and_where_the_listing_stopped(boards): def test_a_tool_gives_everything_when_asked(boards, monkeypatch): - monkeypatch.setenv("YCLI__HTTP__MAX_ITEMS", "2") + monkeypatch.setenv("YCLI__HTTP__MAX_TOOL_ITEMS", "2") assert len(_tool()["items"]) == 2 # the cap, when nothing is said boards.calls.clear() everything = _tool(all=True) @@ -374,3 +374,21 @@ def test_every_listing_method_of_the_sdk_says_the_rule_in_its_words(name): def test_the_listing_methods_are_all_found(): assert len(LISTING_METHODS) > 40 + + +def test_a_tool_given_no_limit_gives_fewer_items_than_a_command(api): + """A tool's answer is read whole into a context: 50 by default, where a command gives 500.""" + sixty = [{"id": number, "name": f"B{number}"} for number in range(1, 61)] + for page in (sixty, sixty, []): # one page for the tool, then the command's listing + api.add("GET", BOARDS, json=page) + answered = _tool() + assert len(answered["items"]) == 50 and answered["truncated"] and answered["next"] + ids, said = _cli() + assert len(ids) == 60 and said == "" + + +def test_the_cap_of_a_tool_is_a_setting_of_its_own(boards, monkeypatch): + monkeypatch.setenv("YCLI__HTTP__MAX_TOOL_ITEMS", "1") + monkeypatch.setenv("YCLI__HTTP__MAX_ITEMS", "4") # the command's cap is another setting + answered = _tool() + assert [board["id"] for board in answered["items"]] == [1] and answered["truncated"] diff --git a/tests/unit/yandex/test_settings.py b/tests/unit/yandex/test_settings.py index dd6a20fcc..a125ce07b 100644 --- a/tests/unit/yandex/test_settings.py +++ b/tests/unit/yandex/test_settings.py @@ -21,6 +21,7 @@ def _isolated_env(monkeypatch): "YCLI__HTTP__TIMEOUT_SECONDS", "YCLI__HTTP__RETRIES", "YCLI__HTTP__MAX_ITEMS", + "YCLI__HTTP__MAX_TOOL_ITEMS", "YCLI__LOGGING__LEVEL", ): monkeypatch.delenv(name, raising=False) @@ -31,6 +32,7 @@ def test_app_config_defaults(): assert config.http.timeout_seconds == 30.0 assert config.http.retries == 3 assert config.http.max_items == 500 + assert config.http.max_tool_items == 50 assert config.logging.level == "WARNING" assert config.logging.format == "text" @@ -66,6 +68,7 @@ def test_app_config_keyword_arguments_win(): ("YCLI__HTTP__TIMEOUT_SECONDS", "abc"), ("YCLI__HTTP__RETRIES", "-1"), ("YCLI__HTTP__MAX_ITEMS", "0"), + ("YCLI__HTTP__MAX_TOOL_ITEMS", "0"), ("YCLI__LOGGING__LEVEL", "bogus"), ], )