@cyanheads/openalex-mcp-server 0.9.0 → 0.10.0

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Server:** openalex-mcp-server
-**Version:** 0.9.0
+**Version:** 0.10.0
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
@@ -42,6 +42,8 @@ No resources — entity lookups need `select` for payload control, which fits to
 | `OPENALEX_API_KEY` | No | OpenAlex account API key, sent as `api_key=` (free from https://openalex.org/settings/api); omit for anonymous access |
 | `OPENALEX_MAILTO` | No | Email sent as `mailto=` to identify yourself to OpenAlex (the "polite pool"); a courtesy identifier, separate from the API key |
 | `OPENALEX_BASE_URL` | No | Default: `https://api.openalex.org` |
+| `OPENALEX_FILTER_STRING_INPUT` | No | Default: `true`; accept unambiguous native filter strings on `openalex_search_entities`; `false` restores record-only input. Strict boolean parsing rejects invalid values. |
+| `OPENALEX_CLAMP_PER_PAGE` | No | Default: `true`; clamp positive integer `per_page` to 100 for search/citation and 200 for analysis, with a notice, log, and counter. `false` restores rejecting advertised maxima. Strict boolean parsing; semantic cap 50 and sample maxima still reject. |
 
 **Session mode:** `createApp({ sessionMode: 'stateless' })` in `src/index.ts` — no tool gates on `ctx.requestInput`, so every call completes in one round trip. An explicit `MCP_SESSION_MODE` still overrides it; `.env.example` and the `Dockerfile` set the same value. No service holds a watcher, socket, or ref'd timer, so there is no `teardown` hook.
 
@@ -189,6 +191,8 @@ async handler(input, ctx) {
 
 **Declare contracts inline on each tool, even when similar across tools.** The contract is part of the tool's documented public surface — reading one tool definition file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
 
+Native-filter parser failures raised during schema preprocessing carry explicit recovery guidance: the handler boundary has not run yet, so handler-contract hint filling cannot supply it.
+
 The OpenAlex service throws factory errors (`notFound`, `rateLimited`, etc.) based on upstream status codes, carrying the contract `reason` on `data.reason` and nothing else of the contract; the framework fills the calling tool's `recovery` for that reason at the handler boundary, and the errors bubble through and are auto-classified. Three service throws set their own `recovery: { hint }`, which wins over the fill: the PMCID 404, since the generic "verify the ID" recovery would send the caller back to retry an identifier OpenAlex never indexes; `upstream_budget_exhausted` on a server with no `OPENALEX_API_KEY`, whose hint adds the free-key advice to the contract's key-neutral midnight-UTC recovery (a keyed server's budget is already the larger one, so it gets the contract text alone); and `upstream_unavailable` on a semantic search — including the HTTP 400 `Failed to embed query:` and `Semantic search is not configured` bodies, relabelled from caller errors to that outage — whose hint adds the keyword-search fallback the generic outage recovery cannot name. One status is read past its code: an HTTP 429 whose body `error` is `Plan upgrade required` — a filter OpenAlex serves only on a paid plan — is thrown as `Forbidden` with `upstream_plan_required` and `retryable: false` under a message of the server's own, so it fails on its first request — no wait clears a plan gate. Every service-thrown entry carries `thrownBy: 'service'` — lint-only metadata that tells `error-contract-unthrown`, whose scan reads the handler body alone, to skip a reason produced a layer below it. Handler-local precondition throws stay inline and unmarked so the rule keeps checking them: `semantic_without_query`, `semantic_per_page_cap`, `semantic_with_cursor`, `page_without_semantic`, `sample_with_cursor`, `sample_with_page`, `sample_with_semantic`, `sample_with_sort`, `seed_without_sample`, `slice_without_id`, and `slice_field_not_array` on `openalex_search_entities`; `reserved_filter_key` and the seed-lookup `entity_not_found` on `openalex_get_citation_graph`; `filters_without_entity_type` on `openalex_resolve_name`. Recovery assertions belong on the contract path (`runToolContract`), where the fill applies — a direct `definition.handler(...)` or service throw carries only what the throw site wrote.
 
 **Fallback for ad-hoc throws:** error factories or plain `Error`.
@@ -210,12 +214,12 @@ See framework CLAUDE.md for the full auto-classification table and all available
 src/
   index.ts                              # createApp() entry point
   config/
-    server-config.ts                    # OPENALEX_API_KEY, OPENALEX_MAILTO, OPENALEX_BASE_URL
+    server-config.ts                    # OpenAlex API access and input compatibility switches
   services/
     openalex/
       openalex-service.ts               # API client (init/accessor pattern)
       types.ts                          # Domain types
-      filter-values.ts                  # Filter values as OpenAlex reads them: country/language codes, quoted multi-word names, `+` as AND
+      filter-values.ts                  # Native filter-string parsing and filter values: country/language codes, quoted phrases, `+` as AND
       iso-codes.json                    # ISO 3166-1 / 639-2 lookups (generated by scripts/generate-iso-codes.ts)
       provider-text.ts                  # Cleanup of provider text: entities, markup, MathType blobs
       html-entities.json                # WHATWG named-entity table provider-text.ts decodes against
@@ -229,6 +233,7 @@ src/
       render-entity-record.ts           # Entity records as content[] markdown
       render-budget.ts                  # The budget trailer line
       response-budget.ts                # 64,000-byte response budget and its disclosures
+      page-size.ts                      # Configurable page-size validation and disclosed clamping
     tools/definitions/
       search-entities.tool.ts           # openalex_search_entities
       analyze-trends.tool.ts            # openalex_analyze_trends

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Server:** openalex-mcp-server
-**Version:** 0.9.0
+**Version:** 0.10.0
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
@@ -42,6 +42,8 @@ No resources — entity lookups need `select` for payload control, which fits to
 | `OPENALEX_API_KEY` | No | OpenAlex account API key, sent as `api_key=` (free from https://openalex.org/settings/api); omit for anonymous access |
 | `OPENALEX_MAILTO` | No | Email sent as `mailto=` to identify yourself to OpenAlex (the "polite pool"); a courtesy identifier, separate from the API key |
 | `OPENALEX_BASE_URL` | No | Default: `https://api.openalex.org` |
+| `OPENALEX_FILTER_STRING_INPUT` | No | Default: `true`; accept unambiguous native filter strings on `openalex_search_entities`; `false` restores record-only input. Strict boolean parsing rejects invalid values. |
+| `OPENALEX_CLAMP_PER_PAGE` | No | Default: `true`; clamp positive integer `per_page` to 100 for search/citation and 200 for analysis, with a notice, log, and counter. `false` restores rejecting advertised maxima. Strict boolean parsing; semantic cap 50 and sample maxima still reject. |
 
 **Session mode:** `createApp({ sessionMode: 'stateless' })` in `src/index.ts` — no tool gates on `ctx.requestInput`, so every call completes in one round trip. An explicit `MCP_SESSION_MODE` still overrides it; `.env.example` and the `Dockerfile` set the same value. No service holds a watcher, socket, or ref'd timer, so there is no `teardown` hook.
 
@@ -189,6 +191,8 @@ async handler(input, ctx) {
 
 **Declare contracts inline on each tool, even when similar across tools.** The contract is part of the tool's documented public surface — reading one tool definition file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
 
+Native-filter parser failures raised during schema preprocessing carry explicit recovery guidance: the handler boundary has not run yet, so handler-contract hint filling cannot supply it.
+
 The OpenAlex service throws factory errors (`notFound`, `rateLimited`, etc.) based on upstream status codes, carrying the contract `reason` on `data.reason` and nothing else of the contract; the framework fills the calling tool's `recovery` for that reason at the handler boundary, and the errors bubble through and are auto-classified. Three service throws set their own `recovery: { hint }`, which wins over the fill: the PMCID 404, since the generic "verify the ID" recovery would send the caller back to retry an identifier OpenAlex never indexes; `upstream_budget_exhausted` on a server with no `OPENALEX_API_KEY`, whose hint adds the free-key advice to the contract's key-neutral midnight-UTC recovery (a keyed server's budget is already the larger one, so it gets the contract text alone); and `upstream_unavailable` on a semantic search — including the HTTP 400 `Failed to embed query:` and `Semantic search is not configured` bodies, relabelled from caller errors to that outage — whose hint adds the keyword-search fallback the generic outage recovery cannot name. One status is read past its code: an HTTP 429 whose body `error` is `Plan upgrade required` — a filter OpenAlex serves only on a paid plan — is thrown as `Forbidden` with `upstream_plan_required` and `retryable: false` under a message of the server's own, so it fails on its first request — no wait clears a plan gate. Every service-thrown entry carries `thrownBy: 'service'` — lint-only metadata that tells `error-contract-unthrown`, whose scan reads the handler body alone, to skip a reason produced a layer below it. Handler-local precondition throws stay inline and unmarked so the rule keeps checking them: `semantic_without_query`, `semantic_per_page_cap`, `semantic_with_cursor`, `page_without_semantic`, `sample_with_cursor`, `sample_with_page`, `sample_with_semantic`, `sample_with_sort`, `seed_without_sample`, `slice_without_id`, and `slice_field_not_array` on `openalex_search_entities`; `reserved_filter_key` and the seed-lookup `entity_not_found` on `openalex_get_citation_graph`; `filters_without_entity_type` on `openalex_resolve_name`. Recovery assertions belong on the contract path (`runToolContract`), where the fill applies — a direct `definition.handler(...)` or service throw carries only what the throw site wrote.
 
 **Fallback for ad-hoc throws:** error factories or plain `Error`.
@@ -210,12 +214,12 @@ See framework CLAUDE.md for the full auto-classification table and all available
 src/
   index.ts                              # createApp() entry point
   config/
-    server-config.ts                    # OPENALEX_API_KEY, OPENALEX_MAILTO, OPENALEX_BASE_URL
+    server-config.ts                    # OpenAlex API access and input compatibility switches
   services/
     openalex/
       openalex-service.ts               # API client (init/accessor pattern)
       types.ts                          # Domain types
-      filter-values.ts                  # Filter values as OpenAlex reads them: country/language codes, quoted multi-word names, `+` as AND
+      filter-values.ts                  # Native filter-string parsing and filter values: country/language codes, quoted phrases, `+` as AND
       iso-codes.json                    # ISO 3166-1 / 639-2 lookups (generated by scripts/generate-iso-codes.ts)
       provider-text.ts                  # Cleanup of provider text: entities, markup, MathType blobs
       html-entities.json                # WHATWG named-entity table provider-text.ts decodes against
@@ -229,6 +233,7 @@ src/
       render-entity-record.ts           # Entity records as content[] markdown
       render-budget.ts                  # The budget trailer line
       response-budget.ts                # 64,000-byte response budget and its disclosures
+      page-size.ts                      # Configurable page-size validation and disclosed clamping
     tools/definitions/
       search-entities.tool.ts           # openalex_search_entities
       analyze-trends.tool.ts            # openalex_analyze_trends

package/Dockerfile

@@ -14,7 +14,7 @@
 # output. A stage that compiles a native addon needs the target-arch toolchain
 # and cannot cross-compile this way — drop the flag there.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS build
 
 WORKDIR /usr/src/app
 
@@ -46,7 +46,7 @@ RUN bun run build
 # A clean image rather than `FROM build`: the build stage's node_modules holds
 # devDependencies.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS deps
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS deps
 
 WORKDIR /usr/src/app
 
@@ -114,7 +114,7 @@ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
 # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
 # and CMD, which run on the real target at container start.
 # ==============================================================================
-FROM oven/bun:1.4.3-slim AS production
+FROM oven/bun:1.4.4-slim AS production
 
 WORKDIR /usr/src/app
 

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.9.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/openalex-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/openalex-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openalex-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.10.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/openalex-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/openalex-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openalex-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -54,13 +54,16 @@ Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90
 
 - Retrieve a single entity by ID — OpenAlex ID, DOI, ORCID, ROR, PMID, ISSN, or PMCID (bare or URL form, including OpenAlex record-page and API URLs such as `https://openalex.org/works/W2741809807`), or a keyword by its slug or keyword URL. Under `entity_type: "funders"`, a funder's Crossref Funder Registry DOI (`10.13039/…`) resolves through a one-result list request. OpenAlex does not bill a lookup by ID, with three exceptions it bills like one list call: a keyword looked up by its slug or URL, an `id` carrying characters past the identifier itself (`W2741809807#x` still returns W2741809807), and that funder-DOI request. `id` takes precedence: search parameters passed alongside it are dropped, and the response names which ones. An OpenAlex ID whose letter names another entity type than `entity_type` fails as `id_type_mismatch` before any upstream call, and an `id` holding a `.` or `..` path segment, plain or percent-encoded, fails as `id_dot_segment`; a `?`, `#`, `\`, tab, or line break inside an identifier (SICI DOIs end in `#`) is sent percent-encoded as part of it. A PMCID resolves nothing (OpenAlex indexes none) — use the work's PMID or DOI instead
 - Keyword search (boolean operators, quoted phrases, wildcards, fuzzy match) plus `exact` and `semantic` search modes — semantic ranks a query-dependent candidate set at ~1 req/sec (up to 50 per page), and its `meta.count` reports the candidate count rather than a match total
+- `filters` accepts a record object or an unambiguous native string (`"issn:0920-8542"`), including through the `filter` alias. Conversion is disclosed in `notice`; commas outside paired double quotes separate clauses, and the first colon separates a key from its value, preserving DOI/URL colons and quoted comma phrases. Exact duplicate keys, bare fragments, and unmatched quotes are rejected with record-form recovery guidance. A record holds one value per key; distinct aliases of the same upstream field still AND together. Set `OPENALEX_FILTER_STRING_INPUT=false` to require record objects. Native strings apply only to this tool's filters, with the record form remaining the advertised schema
+- Filter values sent unquoted must have paired double quotes on all four filter-taking tools (`unmatched_quote_in_filter_value`); citation filters are checked before the seed lookup. Balanced search phrases such as `"graph neural" networks` remain valid, including `.search.exact`. A value sent double-quoted still cannot contain its own interior double quote (`quote_in_filter_value`)
 - Rich filter syntax: AND across fields, OR within a field (`|`), AND within a field (`+`), NOT (`!`), ranges, comparisons. One value cannot hold `|` beside an AND operator — a `+`, or a space between values on an ID, code, or `language` key (a space inside a language name is part of the name, and on a country field a space is always part of a country name, never AND: `DE US|FR` fails as `invalid_country_code`): OpenAlex splits a value on `|` first and drops every alternative that ANDs more than one value, so `DE|FR+US` and `authorships.author.id: A1 A2|A3` both fail as `mixed_and_or_in_filter_value` before any request — put the AND in a second key instead (`institutions.country_code: US` beside `authorships.institutions.country_code: DE|FR` on works). A comma inside a free-text search filter (any `.search` key — `title.search`, `abstract.search.exact`, `title_abstract_keywords.search`) or a field OpenAlex matches as whole text (listed below) is sent double-quoted as part of the phrase, while a comma in any other filter value fails as `comma_in_filter_value` (use `|` for OR); inside a `.search` value, a DOI, a date (a timestamp's `+00:00` offset), a URL (`landing_page_url`; not the boolean `has_pdf_url`), an exactly matched name (`display_name`, `awards.funder_display_name` — `C++`, `Erasmus+`), a `biblio` field (issue `1+2`), or `awards.funder_award_id`, a `+` is a literal character; a value with spaces on a field OpenAlex matches as whole text (`display_name`, `awards.funder_display_name`, `awards.funder_award_id`, `geo.city`, `geo.region`, `raw_affiliation_strings`, `block_key`, a `biblio` field) is sent double-quoted, so it matches as one phrase (`awards.funder_display_name: National Science Foundation`) — `!` and `|` work with it (`geo.city: New York|Boston`), but `+` cannot AND it with another value in the same field. A comma is part of such a value too (`raw_affiliation_strings: Associazione Meteonetwork OdV, Milano, Italy`): a value holding one goes out quoted with its `+` as a literal character. A double quote inside the outer pair of any value sent quoted this way, or of a value you wrap in double quotes on any filter but a free-text search, fails as `quote_in_filter_value`
 - Country and language values are converted to the codes OpenAlex stores, here and in every other tool that takes `filters`: on a country field (a key ending in `country_code`, `country_codes`, or `countries`), an ISO 3166-1 alpha-3 code, numeric code, or English name — ISO's, or the one OpenAlex's own country facets display (`Russia`, `Ivory Coast`, `Trinidad & Tobago`) — becomes its alpha-2 code (`DEU`, `276`, `Germany` → `DE`) and `UK` becomes `GB`, while a value that cannot be a country code (`Germanyy`, `999`, `unknown`, or two codes joined by a space, `DE US`) fails as `invalid_country_code` without the filter being sent; on `language`, an ISO 639-2 code becomes its ISO 639-1 code and an English name becomes its code (`eng`, `English` → `en`; `Cebuano` → `ceb`). Each `|`/`+` segment is trimmed and converted on its own, so a multi-word name is one value (`South Korea|Japan` → `KR|JP`, `Scottish Gaelic|English` → `gd|en`), and anything else — `null`, `XK`, `ceb`, `zh-cn`, the `countries/DEU` path form — is sent as given
 - `select` returns a curated per-entity-type default unless overridden, or `["*"]` for the full record; invalid field names error with the valid set. On works, `author_list` returns each author in authorship order as `{id, display_name, orcid}` — about a tenth the size of `authorships`, which adds institutions and affiliations — and is never part of the default or `["*"]`
 - Cursor pagination for keyword and exact search, up to 100 results per page (default 25); semantic search walks its candidates with `page` (1-based) instead, and mixing either knob with the wrong `search_mode` is rejected before the upstream call
 - `sample` (up to 100, single page only — neither `cursor` nor `page` applies) plus a deterministic `seed` for reproducible random sampling; keyword and exact modes only, and never alongside `sort` — OpenAlex does not sample a semantic search and refuses a sorted sample, so both combinations are rejected before the upstream call
 - Each response holds to 64,000 bytes per surface (`structuredContent`, and `content[]` with its trailer) unless the least it can return is larger, which it flags as `over_budget`: a page that would run over keeps its leading records whole and names the rest in `omitted` with the one call that returns them (as a set, in OpenAlex's order), without disturbing `next_cursor`; a record too large on its own comes back with its largest arrays windowed, filled in turn so each shows what fits and labeled with how much of the array it holds, and `slice: {field, offset}` on an `id` lookup pages any array to the end
-- A list record carrying exactly 100 `authorships` or `author_list` entries — the most OpenAlex returns in a list response — is flagged as possibly capped, with the unbilled `id` + `slice` call that fetches the rest of that array
+- A list record carrying exactly 100 `authorships` or `author_list` entries is flagged as possibly capped, with an `id` + `slice` call to retrieve more stored authors. Singleton lookups and snapshots retain at most 5,000 authorships per work; at that ceiling both author fields remain possibly capped on every slice. `total` counts stored entries rather than a complete byline, and `next` becomes null when those entries are exhausted. Another OpenAlex fetch or snapshot cannot recover authors beyond the storage ceiling
+- Positive integer `per_page` values above 100 for search/citation or 200 for analysis clamp to the maximum, with requested/applied sizes in `notice`, a log, and a counter. Set `OPENALEX_CLAMP_PER_PAGE=false` to restore rejecting advertised maxima. Zero, negatives, fractions, semantic search above 50, and oversized samples still reject. An `id` ignores page size and `sample` overrides it
 - `display_name` is nullable for untitled records; every call reports OpenAlex daily-budget cost and remaining balance
 
 ---
@@ -68,8 +71,9 @@ Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90
 ### `openalex_analyze_trends` <sub>tool</sub>
 
 - Group any supported field for trend, distribution, or comparative analysis; combine with `filters` to scope the population before aggregation
-- Up to 200 groups per page (default). `order: "count"` (default) returns the top-N by count with no further pages; `order: "key"` enumerates all distinct values key-ascending with cursor pagination
-- `include_unknown` (default `false`) adds a group for entities with no value for the grouped field, flagged `is_unknown: true` and labeled as unknown in the text output. OpenAlex keys it `-111`/`-111.0` (numeric fields), `unknown` (text fields and `order: "key"`), or an ID ending in `/unknown`; the key is a sentinel, not a filter value. Boolean fields have no such group — a missing value counts as `false`
+- Up to 200 groups per page (default). Without a cursor, `order: "count"` (default) returns the top-N by count with no further pages; `order: "key"` enumerates distinct values key-ascending with cursor pagination. Boolean fields keep count order even with `"key"` and do not support cursor pagination. A supplied `cursor` selects key order even when `order` is omitted or `"count"`. OpenAlex can wrap a key-ordered walk to earlier groups: stop when a page's first key repeats an earlier key, or when a page is short or empty, even if `next_cursor` is still present
+- `include_unknown` (default `false`) adds a group for entities with no value for the grouped field, flagged `is_unknown: true` and labeled as unknown in the text output. The native `:include_unknown` suffix on `group_by` also enables it, even with an explicit `false`; passing both adds the suffix once. OpenAlex keys it `-111`/`-111.0` (numeric fields), `unknown` (text fields and `order: "key"`), or an ID ending in `/unknown`; the key is a sentinel, not a filter value. Boolean fields have no such group — a missing value counts as `false`
+- `key_display_name` remains present but can be `null` when OpenAlex supplies no label; text output renders the group key in that case, including unknown buckets
 - Not every field is groupable — raw date fields, `.search` operators, `from_*`/`to_*` range modifiers, decimal scores such as `fwci`, `display_name`, external-ID fields such as `doi`, and fields OpenAlex looks up from a related entity such as `primary_location.source.country_code` are rejected; `openalex_describe_fields(entity_type, "group_by")` lists the fields that group
 - A works group_by on `authorships.countries` says in its notice that OpenAlex counts only each work's first 100 authorships for that field, and names `authorships.institutions.country_code` as the field that counts all of them
 - Reports OpenAlex daily-budget cost and remaining balance — aggregation is priced far below paging the same entities
@@ -273,6 +277,8 @@ cp .env.example .env
 | `OPENALEX_API_KEY` | OpenAlex account API key, sent upstream as `api_key=` (free from [openalex.org/settings/api](https://openalex.org/settings/api)). Without it, anonymous rate limits apply. | — |
 | `OPENALEX_MAILTO` | Email sent upstream as `mailto=` to identify yourself to OpenAlex (the "polite pool"); a courtesy identifier, separate from the API key. | — |
 | `OPENALEX_BASE_URL` | OpenAlex API base URL. | `https://api.openalex.org` |
+| `OPENALEX_FILTER_STRING_INPUT` | Accept unambiguous native filter strings on `openalex_search_entities`. Set `false` to require record objects; invalid boolean values fail startup. | `true` |
+| `OPENALEX_CLAMP_PER_PAGE` | Clamp oversized positive integer `per_page` with a requested/applied notice (100 search/citation, 200 analysis). Set `false` to restore rejecting advertised maxima; invalid boolean values fail startup. Semantic and sample caps still reject. | `true` |
 | `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |
 
 See [`.env.example`](./.env.example) for the full list of optional overrides.

package/changelog/0.10.x/0.10.0.md

@@ -0,0 +1,30 @@
+---
+summary: "Preserve nullable aggregation labels, correct filter handling, and disclose pagination and author-storage limits."
+breaking: true
+security: false
+---
+
+# 0.10.0 — 2026-10-22
+
+## Changed
+
+- Allow required `key_display_name` to be `null` in aggregation results, rendering the group key when its label is absent. (#119)
+- **Native filter strings** are accepted by `openalex_search_entities`, with conversion disclosed in `notice`; set `OPENALEX_FILTER_STRING_INPUT=false` to require record objects. ([#118](https://github.com/cyanheads/openalex-mcp-server/issues/118))
+- **Ordinary read pages** clamp oversized `per_page` to 100 for search/citation or 200 for analysis, with requested/applied notices; `OPENALEX_CLAMP_PER_PAGE=false` restores rejection. Semantic search retains its 50-result cap; `id` and `sample` take precedence. ([#121](https://github.com/cyanheads/openalex-mcp-server/issues/121))
+- **Bun** 1.4.3 → 1.4.4 for package management, container images, and the README badge.
+- **Regression coverage** checks filter scanner growth and stored author sequences; entity-like Markdown escaping is measured with thread CPU time.
+
+## Fixed
+
+- **Aggregation ordering** notices and echoes follow supplied cursors and the boolean-field count-order exception. ([#41](https://github.com/cyanheads/openalex-mcp-server/issues/41))
+- **Unknown aggregation groups** are flagged when `group_by` carries `:include_unknown`; combining the suffix and boolean sends the suffix once. ([#75](https://github.com/cyanheads/openalex-mcp-server/issues/75))
+- **Key-ordered pagination** warns that OpenAlex can wrap and directs callers to stop on a repeated first key or a short/empty page. ([#108](https://github.com/cyanheads/openalex-mcp-server/issues/108))
+- **Unmatched filter quotes** fail before any upstream request on all four filter-taking tools, including the citation seed lookup, with recovery guidance. ([#116](https://github.com/cyanheads/openalex-mcp-server/issues/116))
+- **Author windows** disclose OpenAlex's 5,000-author storage ceiling on singleton lookups and slices, retaining `possibly_capped:true` while ending continuation at the stored-array boundary. ([#120](https://github.com/cyanheads/openalex-mcp-server/issues/120))
+
+## Dependencies
+
+- `ignore` ^7.0.12 → ^7.0.13.
+- `tsc-alias` ^1.9.7 → ^1.9.8.
+- `vitest` ^5.0.4 → ^5.0.5.
+- Lockfile: `postcss` 8.5.30 → 8.5.31.

package/dist/config/server-config.d.ts

@@ -7,6 +7,8 @@ declare const ServerConfigSchema: z.ZodObject<{
     apiKey: z.ZodDefault<z.ZodString>;
     mailto: z.ZodDefault<z.ZodString>;
     baseUrl: z.ZodDefault<z.ZodString>;
+    filterStringInput: z.ZodDefault<z.ZodCodec<z.ZodString, z.ZodBoolean>>;
+    clampPerPage: z.ZodDefault<z.ZodCodec<z.ZodString, z.ZodBoolean>>;
 }, z.core.$strip>;
 export type ServerConfig = z.infer<typeof ServerConfigSchema>;
 export declare function getServerConfig(): ServerConfig;

package/dist/config/server-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;iBActB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAO9C"}
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;iBAsBtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAS9C"}

package/dist/config/server-config.js

@@ -14,6 +14,14 @@ const ServerConfigSchema = z.object({
         .default('')
         .describe('Optional email sent upstream as mailto= to identify yourself to OpenAlex (the "polite pool"); a courtesy identifier, separate from and not a substitute for the API key'),
     baseUrl: z.string().url().default('https://api.openalex.org').describe('OpenAlex API base URL'),
+    filterStringInput: z
+        .stringbool()
+        .default(true)
+        .describe('Accept unambiguous native filter strings on openalex_search_entities'),
+    clampPerPage: z
+        .stringbool()
+        .default(true)
+        .describe('Clamp oversized per_page values to each tool maximum, with a notice'),
 });
 let _config;
 export function getServerConfig() {
@@ -21,6 +29,8 @@ export function getServerConfig() {
         apiKey: 'OPENALEX_API_KEY',
         mailto: 'OPENALEX_MAILTO',
         baseUrl: 'OPENALEX_BASE_URL',
+        filterStringInput: 'OPENALEX_FILTER_STRING_INPUT',
+        clampPerPage: 'OPENALEX_CLAMP_PER_PAGE',
     });
     return _config;
 }

package/dist/config/server-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CACP,sMAAsM,CACvM;IACH,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CACP,yKAAyK,CAC1K;IACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC;CAChG,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,MAAM,EAAE,kBAAkB;QAC1B,MAAM,EAAE,iBAAiB;QACzB,OAAO,EAAE,mBAAmB;KAC7B,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CACP,sMAAsM,CACvM;IACH,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CACP,yKAAyK,CAC1K;IACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC;IAC/F,iBAAiB,EAAE,CAAC;SACjB,UAAU,EAAE;SACZ,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,sEAAsE,CAAC;IACnF,YAAY,EAAE,CAAC;SACZ,UAAU,EAAE;SACZ,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,qEAAqE,CAAC;CACnF,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,MAAM,EAAE,kBAAkB;QAC1B,MAAM,EAAE,iBAAiB;QACzB,OAAO,EAAE,mBAAmB;QAC5B,iBAAiB,EAAE,8BAA8B;QACjD,YAAY,EAAE,yBAAyB;KACxC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.js

@@ -25,7 +25,7 @@ await createApp({
         describeFieldsTool,
     ],
     prompts: [literatureReviewPrompt, researchLandscapePrompt],
-    instructions: "Use the openalex_* tools to query the OpenAlex scholarly catalog (works, authors, sources, institutions, topics, keywords, publishers, funders): resolve names to IDs, search/filter/sort or fetch by ID, and group_by for trends. Names are ambiguous and IDs are not — call openalex_resolve_name before filtering by entity. Record responses hold to 64,000 bytes per surface: a cut page names its `omitted` IDs and the call that returns them (in OpenAlex's order), and an array too long to fit comes back as a window that an `id` lookup pages with `slice`.",
+    instructions: "Use the openalex_* tools to query the OpenAlex scholarly catalog (works, authors, sources, institutions, topics, keywords, publishers, funders): resolve names to IDs, search/filter/sort or fetch by ID, and group_by for trends. Names are ambiguous and IDs are not — call openalex_resolve_name before filtering by entity. Record responses hold to 64,000 bytes per surface: a cut page names its `omitted` IDs and the call that returns them (in OpenAlex's order), and an array too long to fit comes back as a window that an `id` lookup pages with `slice`. Author arrays may be capped at 100 on list records or 5,000 on singleton records and snapshots; `total` counts stored entries, and `next` is null once those entries are exhausted even when the byline may be longer. Oversized positive integer `per_page` values clamp with a notice to 100 for search/citation or 200 for analysis unless OPENALEX_CLAMP_PER_PAGE=false restores rejection. Semantic search above 50 and oversized samples still reject.",
     landing: {
         tagline: 'Search the OpenAlex catalog — 270M+ works, 90M+ authors, 100K+ sources.',
         requireAuth: false,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAC;AACtG,OAAO,EAAE,uBAAuB,EAAE,MAAM,+DAA+D,CAAC;AACxG,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,oBAAoB,EAAE,MAAM,uDAAuD,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,MAAM,qDAAqD,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAE9E,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,qBAAqB;IAC3B,KAAK,EAAE,qBAAqB;IAC5B,qFAAqF;IACrF,WAAW,EAAE,WAAW;IACxB,KAAK,EAAE;QACL,eAAe;QACf,kBAAkB;QAClB,iBAAiB;QACjB,oBAAoB;QACpB,kBAAkB;KACnB;IACD,OAAO,EAAE,CAAC,sBAAsB,EAAE,uBAAuB,CAAC;IAC1D,YAAY,EACV,yiBAAyiB;IAC3iB,OAAO,EAAE;QACP,OAAO,EAAE,yEAAyE;QAClF,WAAW,EAAE,KAAK;QAClB,QAAQ,EAAE,kDAAkD;QAC5D,UAAU,EAAE;YACV,gBAAgB,EAAE,uBAAuB;SAC1C;QACD,KAAK,EAAE;YACL,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,sBAAsB,EAAE;YACnD,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,iCAAiC,EAAE;SAC/D;KACF;IACD,KAAK;QACH,mBAAmB,EAAE,CAAC;IACxB,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAC;AACtG,OAAO,EAAE,uBAAuB,EAAE,MAAM,+DAA+D,CAAC;AACxG,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,oBAAoB,EAAE,MAAM,uDAAuD,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,MAAM,qDAAqD,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAE9E,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,qBAAqB;IAC3B,KAAK,EAAE,qBAAqB;IAC5B,qFAAqF;IACrF,WAAW,EAAE,WAAW;IACxB,KAAK,EAAE;QACL,eAAe;QACf,kBAAkB;QAClB,iBAAiB;QACjB,oBAAoB;QACpB,kBAAkB;KACnB;IACD,OAAO,EAAE,CAAC,sBAAsB,EAAE,uBAAuB,CAAC;IAC1D,YAAY,EACV,s+BAAs+B;IACx+B,OAAO,EAAE;QACP,OAAO,EAAE,yEAAyE;QAClF,WAAW,EAAE,KAAK;QAClB,QAAQ,EAAE,kDAAkD;QAC5D,UAAU,EAAE;YACV,gBAAgB,EAAE,uBAAuB;SAC1C;QACD,KAAK,EAAE;YACL,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,sBAAsB,EAAE;YACnD,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,iCAAiC,EAAE;SAC/D;KACF;IACD,KAAK;QACH,mBAAmB,EAAE,CAAC;IACxB,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/analyze-trends.tool.d.ts

@@ -18,7 +18,7 @@ export declare const analyzeTrendsTool: import("@cyanheads/mcp-ts-core").ToolDef
     group_by: z.ZodString;
     filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     include_unknown: z.ZodDefault<z.ZodBoolean>;
-    per_page: z.ZodDefault<z.ZodNumber>;
+    per_page: z.ZodDefault<z.ZodLazy<z.ZodNumber>>;
     order: z.ZodOptional<z.ZodEnum<{
         count: "count";
         key: "key";
@@ -32,11 +32,17 @@ export declare const analyzeTrendsTool: import("@cyanheads/mcp-ts-core").ToolDef
     }, z.core.$strip>;
     groups: z.ZodArray<z.ZodObject<{
         key: z.ZodString;
-        key_display_name: z.ZodString;
+        key_display_name: z.ZodNullable<z.ZodString>;
         count: z.ZodNumber;
         is_unknown: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>>;
 }, z.core.$strip>, readonly [{
+    readonly reason: "unmatched_quote_in_filter_value";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "A filter value sent unquoted has an unmatched double quote.";
+    readonly recovery: "Pair double quotes used for a search phrase, or remove the stray quote.";
+    readonly thrownBy: "service";
+}, {
     readonly reason: "rate_limited";
     readonly code: JsonRpcErrorCode.RateLimited;
     readonly when: "OpenAlex throttled the request for exceeding its per-second ceiling (HTTP 429).";

package/dist/mcp-server/tools/definitions/analyze-trends.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze-trends.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/analyze-trends.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAWjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2Y5B,CAAC"}
+{"version":3,"file":"analyze-trends.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/analyze-trends.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAgBjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkZ5B,CAAC"}

package/dist/mcp-server/tools/definitions/analyze-trends.tool.js

@@ -5,17 +5,27 @@
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { escapeMarkdown } from '../escape-markdown.js';
+import { clampPageSize, pageSizeSchema } from '../page-size.js';
 import { renderBudgetTrailer } from '../render-budget.js';
 import { joinNotices } from '../response-budget.js';
-import { getOpenAlexService } from '../../../services/openalex/openalex-service.js';
+import { getOpenAlexService, isBooleanGroupBy } from '../../../services/openalex/openalex-service.js';
 import { ENTITY_TYPES } from '../../../services/openalex/types.js';
 /** Disclosure for a works group_by over `authorships.countries` (see the handler). */
 const COUNTRIES_CAP_NOTICE = 'OpenAlex builds authorships.countries groups from only the first 100 authorships of each work, so a country that appears only past position 100 on a large collaboration is not counted. Group by authorships.institutions.country_code to count every authorship.';
+/** Upstream cursors can wrap even after a short page; callers own the stopping decision. */
+const KEY_ORDER_GUIDANCE = "OpenAlex can wrap a key-ordered walk to earlier groups. Stop when a page's first key repeats an earlier key, or when a page is short or empty.";
 export const analyzeTrendsTool = tool('openalex_analyze_trends', {
-    description: 'Aggregate OpenAlex entities into groups and count them. Use for trend analysis (group works by publication_year), distribution analysis (group by oa_status, type, country), and comparative analysis (group by institution or topic). Combine with filters to scope the analysis. Returns up to 200 groups per page — use cursor pagination for fields with many distinct values.',
+    description: `Aggregate OpenAlex entities into groups and count them. Use for trend analysis (group works by publication_year), distribution analysis (group by oa_status, type, country), and comparative analysis (group by institution or topic). Combine with filters to scope the analysis. Returns up to 200 groups per page — use order "key" and cursor pagination for fields with many distinct values. ${KEY_ORDER_GUIDANCE}`,
     sourceUrl: 'https://github.com/cyanheads/openalex-mcp-server/blob/main/src/mcp-server/tools/definitions/analyze-trends.tool.ts',
     annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     errors: [
+        {
+            reason: 'unmatched_quote_in_filter_value',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A filter value sent unquoted has an unmatched double quote.',
+            recovery: 'Pair double quotes used for a search phrase, or remove the stray quote.',
+            thrownBy: 'service',
+        },
         {
             reason: 'rate_limited',
             code: JsonRpcErrorCode.RateLimited,
@@ -148,31 +158,27 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
         group_by: z
             .string()
             .min(1)
-            .describe('Field to group by. Works examples: "publication_year", "type", "oa_status", "primary_topic.field.id", "authorships.institutions.country_code", "is_retracted". OpenAlex builds authorships.countries groups from only the first 100 authorships of each work; authorships.institutions.country_code counts every authorship. Authors: "last_known_institutions.country_code", "has_orcid". Sources: "type", "is_oa", "country_code". Not all fields support group_by — call openalex_describe_fields(entity_type, "group_by") for the groupable set.'),
+            .describe('Field to group by. Works examples: "publication_year", "type", "oa_status", "primary_topic.field.id", "authorships.institutions.country_code", "is_retracted". The native ":include_unknown" suffix also enables include_unknown, even when the boolean is false; passing both adds the suffix once. OpenAlex builds authorships.countries groups from only the first 100 authorships of each work; authorships.institutions.country_code counts every authorship. Authors: "last_known_institutions.country_code", "has_orcid". Sources: "type", "is_oa", "country_code". Not all fields support group_by — call openalex_describe_fields(entity_type, "group_by") for the groupable set.'),
         filters: z
             .record(z.string(), z.string())
             .optional()
-            .describe('Filter criteria (same syntax as openalex_search_entities filters). Narrows the population before aggregation. Country fields take ISO 3166-1 alpha-2 codes ("DE") and `language` takes ISO 639-1 codes ("en"); alpha-3, numeric, ISO 639-2, and English-name forms are converted — a multi-word name is one value, so "South Korea|Japan" ORs two countries — and a value that cannot be a country code is rejected. A multi-word value on a field matched as whole text (display_name, awards.funder_display_name, geo.city, raw_affiliation_strings) matches as one phrase ("National Science Foundation"; a comma, as in "University of California, Berkeley", is part of it, and it cannot contain a double quote of its own), "!" and "|" included, but cannot be ANDed with "+" in the same field. A value mixing "|" with an AND operator — a "+", or a space on a field where words mean AND — is rejected, since OpenAlex drops every "|" alternative that ANDs more than one value; put the AND in a second key instead. For full-text within filters, use abstract.search, title.search, or default.search — there is no bare \'search\' filter key. Example: group works by year filtered to a specific topic.'),
+            .describe('Filter record object, using the same value syntax as openalex_search_entities; native string input is unavailable here. Narrows the population before aggregation. Country fields take ISO 3166-1 alpha-2 codes ("DE") and `language` takes ISO 639-1 codes ("en"); alpha-3, numeric, ISO 639-2, and English-name forms are converted — a multi-word name is one value, so "South Korea|Japan" ORs two countries — and a value that cannot be a country code is rejected. A multi-word value on a field matched as whole text (display_name, awards.funder_display_name, geo.city, raw_affiliation_strings) matches as one phrase ("National Science Foundation"; a comma, as in "University of California, Berkeley", is part of it, and it cannot contain a double quote of its own), "!" and "|" included, but cannot be ANDed with "+" in the same field. A value sent unquoted must have paired double quotes; balanced search phrases remain valid. A value mixing "|" with an AND operator — a "+", or a space on a field where words mean AND — is rejected, since OpenAlex drops every "|" alternative that ANDs more than one value; put the AND in a second key instead. For full-text within filters, use abstract.search, title.search, or default.search — there is no bare \'search\' filter key. Example: group works by year filtered to a specific topic.'),
         include_unknown: z
             .boolean()
             .default(false)
-            .describe('Add a group for entities with no value for the grouped field. Hidden by default. That group carries `is_unknown: true`; OpenAlex keys it -111 or -111.0 on numeric fields, "unknown" on text fields and under order "key", and an ID ending in /unknown on ID fields — a sentinel, not a measured value. The key is not a filter value: passing -111 as a filter matches a numeric range, not the entities with no value. Boolean fields have no separate group — a missing value counts as false.'),
-        per_page: z
-            .number()
-            .int()
-            .min(1)
-            .max(200)
+            .describe('Add a group for entities with no value for the grouped field. Hidden by default unless group_by has the native ":include_unknown" suffix, which enables this setting even when the boolean is false; passing both adds the suffix once. That group carries `is_unknown: true`; OpenAlex keys it -111 or -111.0 on numeric fields, "unknown" on text fields and under order "key", and an ID ending in /unknown on ID fields — a sentinel, not a measured value. The key is not a filter value: passing -111 as a filter matches a numeric range, not the entities with no value. Boolean fields have no separate group — a missing value counts as false.'),
+        per_page: pageSizeSchema(200)
             .default(200)
-            .describe('Maximum groups per page (1-200). Default 200 (the upstream cap). A real top-N knob when order is count (the default) — reduce to return only the highest-count groups.'),
+            .describe('Maximum groups per page. Default 200 (the upstream cap); positive integers above 200 clamp to 200 with a notice unless OPENALEX_CLAMP_PER_PAGE=false restores rejection. A real top-N knob in count order without a cursor (the default) — reduce to return only the highest-count groups.'),
         order: z
             .enum(['count', 'key'])
             .optional()
-            .describe('Sort order for groups. Omit or pass "count" (default) to return the top-N groups by count descending — no further pages. Pass "key" to enumerate all distinct values in key-ascending order with cursor pagination. Use "key" only when you need a full traversal; most analysis calls want "count".'),
+            .describe(`Sort order for groups. Without a cursor, omit or pass "count" (default) to return the top-N groups by count descending — no further pages. Pass "key" to enumerate distinct values in key-ascending order with cursor pagination. Boolean fields keep count order even with "key" and do not support cursor pagination. A supplied cursor selects key order even if order is omitted or "count". ${KEY_ORDER_GUIDANCE}`),
         cursor: z
             .string()
             .min(1)
             .optional()
-            .describe('Pagination cursor from a previous response. Only relevant when order is "key" — count-descending results have no next page. Pass the next_cursor from the previous response to advance. Omit it on the first call — an empty string is rejected, since a supplied-but-blank cursor is a caller mistake rather than a request for the first page.'),
+            .describe(`Pagination cursor from a previous response. A supplied cursor selects key order even if order is omitted or "count". Pass the next_cursor from the previous response to advance, subject to the stop conditions below. Omit it on the first call — an empty string is rejected, since a supplied-but-blank cursor is a caller mistake rather than a request for the first page. ${KEY_ORDER_GUIDANCE}`),
     }),
     output: z.object({
         meta: z
@@ -182,7 +188,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             next_cursor: z
                 .string()
                 .nullable()
-                .describe('Cursor for next page of groups. null if no more groups.'),
+                .describe(`Upstream continuation cursor; null when OpenAlex supplies none. A non-null cursor does not guarantee unseen groups. ${KEY_ORDER_GUIDANCE}`),
         })
             .describe('Aggregation metadata.'),
         groups: z
@@ -193,7 +199,8 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
                 .describe('Group key (OpenAlex ID or raw value), exactly as OpenAlex returns it.'),
             key_display_name: z
                 .string()
-                .describe('Human-readable group label as plain text, with HTML entities decoded and markup removed.'),
+                .nullable()
+                .describe('Human-readable group label as plain text, with HTML entities decoded and markup removed; null when OpenAlex supplies no label. Text output uses the group key when the label is null.'),
             count: z.number().describe('Number of entities in this group.'),
             is_unknown: z
                 .literal(true)
@@ -209,14 +216,14 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
     enrichment: {
         echo: z
             .string()
-            .describe('Compact echo of the input criteria (entity_type, group_by, filters) — surfaces what was actually requested when no groups are returned.'),
+            .describe('Compact echo of the criteria (entity_type, group_by, filters) and effective include_unknown and order settings — surfaces what was actually requested when no groups are returned.'),
         totalCount: z
             .number()
             .describe('Total entities matching the filters before grouping (across all pages).'),
         notice: z
             .string()
             .optional()
-            .describe('Guidance notice. Set when a first call returns no groups (recovery suggestions), when a `cursor` continuation returns none because the traversal is already finished, when the page is full and more groups likely exist (truncation signal with narrowing advice), or when works are grouped by authorships.countries, which OpenAlex counts from only the first 100 authorships of each work. Absent otherwise.'),
+            .describe('Guidance notice. Set when per_page was clamped (requested and applied sizes), on every effective key-order call (upstream wrap warning and stopping conditions), when a first call returns no groups (recovery suggestions), when a cursor continuation returns none because the traversal is already finished, when a count-order page is full and more groups likely exist (truncation signal with narrowing advice), or when works are grouped by authorships.countries, which OpenAlex counts from only the first 100 authorships of each work. Absent otherwise.'),
         budget: z
             .object({
             costUsd: z
@@ -240,13 +247,14 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
         budget: { render: renderBudgetTrailer },
     },
     async handler(input, ctx) {
+        const pageSize = clampPageSize(input.per_page, 200, 'openalex_analyze_trends', ctx);
         const service = getOpenAlexService();
         const result = await service.analyze({
             entityType: input.entity_type,
             groupBy: input.group_by,
             filters: input.filters,
             includeUnknown: input.include_unknown,
-            perPage: input.per_page,
+            perPage: pageSize.applied,
             order: input.order,
             cursor: input.cursor,
         }, ctx);
@@ -256,10 +264,13 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             totalCount: result.meta.count,
             groupCount: result.groups.length,
         });
-        const echo = buildAnalyzeEcho(input);
+        const keyOrder = input.cursor !== undefined || (input.order === 'key' && !isBooleanGroupBy(input.group_by));
+        const echo = buildAnalyzeEcho(input, keyOrder);
         ctx.enrich({ echo, totalCount: result.meta.count });
         // `notice` is last-wins, so every sentence is collected and set once.
         const notices = [];
+        if (pageSize.notice)
+            notices.push(pageSize.notice);
         // An empty page on a `cursor` continuation means the key-ascending traversal already
         // enumerated every group, so there is nothing left to remove or regroup. On a first call
         // the same shape can still be an honest zero — including the all-values-unknown case,
@@ -269,16 +280,13 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
                 ? `No groups returned for ${echo}. Try removing filters or grouping by a different field.`
                 : `Pagination exhausted for ${echo} — the previous page held the last group, so this one came back empty. Stop paging rather than removing filters or regrouping.`);
         }
-        else if (input.order === 'key') {
-            // Key-ascending traversal: omitted groups sit beyond the cursor, not in a count tail, so
-            // the count-bound notice below would be false here (it would name the smallest keys as the
-            // "top by count"). The honest signal is whether OpenAlex returned a next_cursor; page-fill
-            // is irrelevant in this mode.
-            if (result.meta.next_cursor) {
-                notices.push(`Showing ${result.groups.length} groups in key-ascending order. Pass the returned \`next_cursor\` to continue the traversal.`);
-            }
+        if (keyOrder) {
+            // A cursor selects key order regardless of `order`; upstream can wrap without suppressing it.
+            notices.push(result.groups.length === 0
+                ? KEY_ORDER_GUIDANCE
+                : `Showing ${result.groups.length} groups in key-ascending order. ${KEY_ORDER_GUIDANCE}${result.meta.next_cursor ? ' Otherwise, pass the returned `next_cursor` to continue the traversal.' : ''}`);
         }
-        else if (result.groups.length === input.per_page) {
+        else if (result.groups.length > 0 && result.groups.length === pageSize.applied) {
             // Count-desc (the default): the page is filled to the limit, so more distinct groups likely
             // exist. The omitted groups all have counts ≤ the smallest group shown, so we can bound the
             // gap even though OpenAlex exposes no total group count.
@@ -308,11 +316,14 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
     },
     format: (result) => {
         const heading = `${result.meta.count} total entities across ${result.meta.groups_count ?? result.groups.length} groups on this page`;
+        const footer = result.meta.next_cursor
+            ? `\n\nUpstream next_cursor: \`${result.meta.next_cursor}\`. ${KEY_ORDER_GUIDANCE}`
+            : '';
         if (result.groups.length === 0) {
             return [
                 {
                     type: 'text',
-                    text: `No groups found. (count=${result.meta.count}, groups_count=${result.meta.groups_count ?? 0})`,
+                    text: `No groups found. (count=${result.meta.count}, groups_count=${result.meta.groups_count ?? 0})${footer}`,
                 },
             ];
         }
@@ -327,9 +338,6 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             ]
             : result.groups;
         const lines = renderOrder.map((g) => `${renderGroupLabel(g)}: ${g.count}`);
-        const footer = result.meta.next_cursor
-            ? `\n\n*More groups available — next_cursor: \`${result.meta.next_cursor}\`*`
-            : '';
         return [
             {
                 type: 'text',
@@ -351,23 +359,30 @@ function isTimeSeriesGrouping(groups) {
 function renderGroupLabel(g) {
     const key = escapeMarkdown(g.key);
     if (g.is_unknown) {
-        const redundant = g.key_display_name === g.key || g.key_display_name.toLowerCase() === 'unknown';
-        const label = redundant ? '' : `, label ${escapeMarkdown(g.key_display_name)}`;
+        const label = g.key_display_name === null ||
+            g.key_display_name === g.key ||
+            g.key_display_name.toLowerCase() === 'unknown'
+            ? ''
+            : `, label ${escapeMarkdown(g.key_display_name)}`;
         return `unknown (no value; key ${key}${label})`;
     }
+    if (g.key_display_name === null)
+        return escapeMarkdown(g.key, 'line-start');
     const display = escapeMarkdown(g.key_display_name, 'line-start');
     return g.key === g.key_display_name ? display : `${display} (${key})`;
 }
 /** The request as one line: caller text is JSON-encoded, so a line break in it stays escaped. */
-function buildAnalyzeEcho(input) {
+function buildAnalyzeEcho(input, keyOrder) {
     const parts = [`entity_type=${input.entity_type}`, `group_by=${JSON.stringify(input.group_by)}`];
     if (input.filters && Object.keys(input.filters).length > 0) {
         parts.push(`filters=${JSON.stringify(input.filters)}`);
     }
-    if (input.include_unknown)
+    if (input.include_unknown || input.group_by.endsWith(':include_unknown'))
         parts.push('include_unknown=true');
-    if (input.order)
-        parts.push(`order=${input.order}`);
+    if (keyOrder)
+        parts.push('order=key');
+    else if (input.order)
+        parts.push('order=count');
     return parts.join(' | ');
 }
 //# sourceMappingURL=analyze-trends.tool.js.map