@cyanheads/openalex-mcp-server 0.8.0 → 0.10.0

package/AGENTS.md

@@ -1,11 +1,11 @@
 # Developer Protocol
 
 **Server:** openalex-mcp-server
-**Version:** 0.8.0
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.10`
+**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.1.0
-**Zod:** ^4.6.5
+**MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
+**Zod:** ^4.6.7
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -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,7 +191,9 @@ 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.
 
-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. Two 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; and `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). 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`. 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.
+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,26 @@ 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_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                  # 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
+      field-catalog.json                # Valid filter/select fields per entity type (generated by scripts/generate-field-catalog.ts)
+      field-ranker.ts                   # Similarity ranking for field suggestions
+      budget.ts                         # Per-call OpenAlex budget from the X-RateLimit-* headers
+      url-redaction.ts                  # Strips api_key/mailto from URLs in error text
   mcp-server/
+    tools/
+      escape-markdown.ts                # Markdown escaping for provider text in content[]
+      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
@@ -339,7 +357,7 @@ Each per-version file opens with YAML frontmatter: `summary` (required, ≤350 c
 
 ## Publishing
 
-**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
+**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
 
 Run the `release-and-publish` skill — it runs the verification gate (`devcheck`, `rebuild`, `test`), pushes commits and tags, then publishes to every applicable destination. The full reference:
 

package/CLAUDE.md

@@ -1,11 +1,11 @@
 # Developer Protocol
 
 **Server:** openalex-mcp-server
-**Version:** 0.8.0
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.10`
+**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.1.0
-**Zod:** ^4.6.5
+**MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
+**Zod:** ^4.6.7
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -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,7 +191,9 @@ 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.
 
-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. Two 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; and `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). 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`. 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.
+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,26 @@ 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_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                  # 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
+      field-catalog.json                # Valid filter/select fields per entity type (generated by scripts/generate-field-catalog.ts)
+      field-ranker.ts                   # Similarity ranking for field suggestions
+      budget.ts                         # Per-call OpenAlex budget from the X-RateLimit-* headers
+      url-redaction.ts                  # Strips api_key/mailto from URLs in error text
   mcp-server/
+    tools/
+      escape-markdown.ts                # Markdown escaping for provider text in content[]
+      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
@@ -339,7 +357,7 @@ Each per-version file opens with YAML frontmatter: `summary` (required, ≤350 c
 
 ## Publishing
 
-**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
+**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
 
 Run the `release-and-publish` skill — it runs the verification gate (`devcheck`, `rebuild`, `test`), pushes commits and tags, then publishes to every applicable destination. The full reference:
 

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.2 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS build
 
 WORKDIR /usr/src/app
 
@@ -38,15 +38,15 @@ RUN bun run build
 #
 # Installs the production dependency tree for the target platform. Every step
 # here can run JavaScript — bunfig.toml's security scanner runs as a Bun
-# program, and so does the OTel script — so the stage runs on $BUILDPLATFORM
-# and cross-installs with `--os`/`--cpu`, which pick each platform-specific
-# optional dependency (native bindings such as DuckDB's) for the target. Only
-# `node_modules` leaves this stage.
+# program, and so do the OTel and musl-prune scripts — so the stage runs on
+# $BUILDPLATFORM and cross-installs with `--os`/`--cpu`, which pick each
+# platform-specific optional dependency (native bindings such as DuckDB's) for
+# the target. Only `node_modules` leaves this stage.
 #
 # A clean image rather than `FROM build`: the build stage's node_modules holds
 # devDependencies.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS deps
 
 WORKDIR /usr/src/app
 
@@ -93,6 +93,15 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
       bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
     fi
 
+# `--os`/`--cpu` have no libc counterpart, so a native dependency published in
+# glibc and musl variants (DuckDB's bindings, for one) installs both. The
+# runtime image is Debian (glibc) and never loads the musl copy; the script
+# deletes every package whose own `libc` admits only musl. It follows every
+# install, since a later `bun install` restores what it removes. A server on a
+# musl (Alpine) runtime image drops these two lines.
+COPY scripts/prune-musl-packages.ts ./scripts/
+RUN bun scripts/prune-musl-packages.ts
+
 # The seeded scanner served only the installs above; keep it out of the image.
 RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
 
@@ -105,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.2-slim AS production
+FROM oven/bun:1.4.4-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -115,7 +124,7 @@ ENV NODE_ENV=production
 # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
 ARG APP_VERSION
 LABEL org.opencontainers.image.title="openalex-mcp-server"
-LABEL org.opencontainers.image.description="Access the OpenAlex academic research catalog - 270M+ publications through MCP. STDIO & Streamable HTTP."
+LABEL org.opencontainers.image.description="Access the OpenAlex academic research catalog — 270M+ publications — via MCP. STDIO or Streamable HTTP."
 LABEL org.opencontainers.image.source="https://github.com/cyanheads/openalex-mcp-server"
 LABEL org.opencontainers.image.licenses="Apache-2.0"
 LABEL org.opencontainers.image.version="${APP_VERSION}"

package/README.md

@@ -1,13 +1,13 @@
 <div align="center">
   <h1>@cyanheads/openalex-mcp-server</h1>
-  <p><b>Access the OpenAlex academic research catalog - 270M+ publications through MCP. STDIO & Streamable HTTP.</b>
+  <p><b>Access the OpenAlex academic research catalog — 270M+ publications — via MCP. STDIO or Streamable HTTP.</b>
   <div>5 Tools &bull; 2 Prompts</div>
   </p>
 </div>
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.8.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.1.0-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.2-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>
 
@@ -29,7 +29,7 @@
 
 ## Overview
 
-Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90M+ authors, 100K+ sources, plus institutions, topics, keywords, publishers, and funders. Search, filter, and aggregate across all eight entity types, resolve ambiguous names to canonical IDs, and walk the citation graph one hop at a time. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
+Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90M+ authors, 100K+ sources, plus institutions, topics, keywords, publishers, and funders. Search, filter, and aggregate across all eight entity types, resolve ambiguous names to canonical IDs, and walk the citation graph one hop at a time.
 
 ### Tools
 
@@ -52,14 +52,18 @@ Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90
 
 ### `openalex_search_entities` <sub>tool</sub>
 
-- Retrieve a single entity by ID — OpenAlex ID, DOI, ORCID, ROR, PMID, ISSN, or PMCID (bare or URL form), or a keyword by its slug or keyword URL. `id` takes precedence: search parameters passed alongside it are dropped, and the response names which ones. A PMCID resolves nothing (OpenAlex indexes none) — use the work's PMID or DOI instead
+- 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
-- Rich filter syntax: AND across fields, OR within a field (`|`), NOT (`!`), ranges, comparisons; a comma inside a filter value is rejected (use `|`, or a `.search` filter for free text)
-- `select` returns a curated per-entity-type default unless overridden, or `["*"]` for the full record; invalid field names error with the valid set
+- `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` — the most OpenAlex returns in a list response — is flagged as possibly capped, with the unbilled `id` + `slice` call that fetches the rest
+- 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
 
 ---
@@ -67,9 +71,10 @@ 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`
-- Not every field is groupable — raw date fields, `.search` operators, `from_*`/`to_*` range modifiers, decimal scores such as `fwci`, `display_name`, and external-ID fields such as `doi` are rejected; `openalex_describe_fields(entity_type, "group_by")` lists the fields that group
+- 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
 
@@ -78,8 +83,9 @@ Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90
 ### `openalex_resolve_name` <sub>tool</sub>
 
 - A name or partial name runs an autocomplete search: up to 10 matches with disambiguation hints (last institution, host organization, place, etc.)
-- An identifier — OpenAlex ID, DOI, ORCID, ROR, PMID, ISSN, or keyword URL, bare or in URL form — resolves directly to the one record it addresses; no `entity_type` needed, since the identifier determines its own. A PMCID is recognized but resolves nothing — OpenAlex indexes none
-- `filters` narrows autocomplete only; on an identifier lookup they're ignored and named in a notice
+- An identifier — OpenAlex ID, DOI, ORCID, ROR, PMID, ISSN, or keyword URL, bare or in URL form — resolves directly to the record it addresses, as the entity type it belongs to. A ROR can name an organization's institution, funder, and publisher records at once: with no `entity_type` (or any other type) all three are looked up in parallel as unbilled singleton fetches and every record found is returned, institution first; `entity_type` `institutions`, `funders`, or `publishers` narrows it to that one. A Crossref Funder Registry DOI (`10.13039/…`) resolves to the funder unless `entity_type` is `works`. A PMCID is recognized but resolves nothing — OpenAlex indexes none
+- Short names share the bare OpenAlex ID shape (keyword `p53` reads as publisher `P53`), so a bare OpenAlex ID that resolves nothing is searched as a name next, under `entity_type` when given, and the notice names both outcomes; a real ID still resolves with its one request. Under `entity_type: "keywords"` the shape is searched as a keyword name from the start
+- `filters` narrows autocomplete only and requires `entity_type` — a name query passing `filters` without it is rejected before any request (`filters_without_entity_type`). On an identifier lookup they're ignored and named in a notice; a name search that matches nothing under `filters` echoes them and suggests loosening them first
 - With `entity_type` set, OpenAlex autocomplete fails on a name over 1,000 characters; that failure is reported once as `query_too_long` with advice to shorten the name, not retried as an outage
 - Reports OpenAlex daily-budget cost and remaining balance
 
@@ -88,8 +94,8 @@ Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90
 ### `openalex_get_citation_graph` <sub>tool</sub>
 
 - `direction` sets the edge: `cites` (works citing the seed), `cited_by` (the seed's own reference list), `related_to` (OpenAlex's algorithmic related works, ~8-30 typical, may be empty)
-- `seed_id` accepts an OpenAlex ID, DOI, or PMID (PMCID recognized but resolves nothing); validated against a live lookup first, so a non-existent seed fails as `NotFound` rather than returning an empty graph
-- Stacks with `filters`/`sort`/`select` to narrow the graph; `filters` cannot set `cites`/`cited_by`/`related_to`, nor an alias of one such as `cited_works` — those keys are reserved for `direction`
+- `seed_id` accepts an OpenAlex work ID (bare, or its OpenAlex record-page or API URL), DOI, or PMID (PMCID recognized but resolves nothing); validated against a live lookup first, so a non-existent seed fails as `NotFound` rather than returning an empty graph, and the ID of another entity type fails as `id_type_mismatch` before any upstream call
+- Stacks with `filters`/`sort`/`select` (`author_list` included) to narrow the graph; `filters` cannot set `cites`/`cited_by`/`related_to`, nor an alias of one such as `cited_works` — those keys are reserved for `direction`
 - Cursor pagination, up to 100 results per page (default 25)
 - The same 64,000-byte response budget and 100-authorship cap disclosure as `openalex_search_entities`; works cut from a page are named in `omitted` with the `openalex_search_entities` call that returns them, in OpenAlex's order
 - Reports OpenAlex daily-budget cost, covering both the seed-validation lookup and the graph page, plus remaining balance
@@ -100,6 +106,7 @@ Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90
 
 - Lists every valid field name for an entity type + context (`filter`, `group_by`, `select`) — the complete pool, never truncated
 - `group_by` is the filter set minus what OpenAlex rejects as an aggregation key: raw date fields, `.search`/`.search.exact` operators, `from_*`/`to_*` range modifiers, and a per-entity-type set found by grouping every listed field against the live API — decimal scores such as `fwci`, several source year fields, `display_name`, and external-ID fields among them
+- `created_date`, `updated_date`, and their `from_`/`to_` forms are listed filters that OpenAlex serves only on a paid plan; without one, a filter on them fails on its first request as `upstream_plan_required`, with no retry
 - Optional `query` reorders results by name similarity without dropping any field — a nested value's parent object stays reachable further down the list
 - Backed by a generated field catalog — no live API calls
 
@@ -117,7 +124,7 @@ Scholarly catalog data from [OpenAlex](https://openalex.org) — 270M+ works, 90
 
 - Arguments: `topic` required
 - Returns one user message walking a 7-step quantitative workflow: resolve the topic ID, volume trends, top contributors (institutions/countries/journals), open access rate, funding sources, most-cited works, emerging fronts
-- The funding step groups by `awards.funder_id` (resolve names via `openalex_resolve_name`) or `awards.funder_display_name` for readable labels in a single hop
+- The funding step groups by `funders.id`, which counts every work that lists a funder and labels each group with the funder's name; `awards.*` fields stay the route for grant-level questions such as award numbers
 
 ## Features
 
@@ -125,9 +132,9 @@ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): s
 
 OpenAlex-specific:
 
-- Typed API client with automatic ID normalization (DOI, ORCID, ROR, PMID, PMCID, ISSN, OpenAlex and PubMed/PubMed Central URLs); a PMCID normalizes but resolves nothing since OpenAlex indexes none
+- Typed API client with automatic ID normalization (DOI, ORCID, ROR, PMID, PMCID, ISSN, OpenAlex record-page and API URLs over `http`, `https`, or no scheme, PubMed/PubMed Central URLs); a PMCID normalizes but resolves nothing since OpenAlex indexes none
 - Keyless by default — an optional API key raises rate and daily-budget limits, and an optional `mailto` identifies the caller to OpenAlex's polite pool
-- HTTP status codes mapped to specific MCP error classes (400 → InvalidParams, 422 → ValidationError, 429 → RateLimited) with upstream messages surfaced
+- HTTP status codes mapped to specific MCP error classes (400 → InvalidParams, or ServiceUnavailable when a semantic search's query embedding failed upstream; 422 → ValidationError; 429 → RateLimited, or Forbidden when the 429 refuses a paid-plan filter) with upstream messages surfaced
 - Timeout-aware request retries and cancellation support via `AbortSignal`
 
 Agent-friendly output:
@@ -136,13 +143,13 @@ Agent-friendly output:
 - Effective-query echo — search, trends, and citation-graph responses echo the criteria that actually ran, so an empty result is diagnosable without re-reading the request
 - Discriminated output contracts — typed error reasons (`entity_not_found`, `upstream_budget_exhausted`, `semantic_per_page_cap`, `reserved_filter_key`, and more) each carrying an explicit recovery hint
 - Response shaping — abstracts are reconstructed from OpenAlex's inverted-index encoding into plaintext, and `display_name` stays `null` for untitled or paratext records instead of being backfilled
-- Clean provider text — OpenAlex passes titles, abstracts, and names through unsanitized; HTML entities are decoded against the full WHATWG table, comments and HTML/JATS/MathML formatting tags are removed, CDATA wrappers and IOP's `<?CDATA …?>` math markers are unwrapped with their TeX kept, and a double-escaped line break (a literal `\n`) becomes a space; literal text such as `A < B` and TeX such as `\nu` is kept. Identifier and URL fields (`id`, `doi`, `ids`, `orcid`, `ror`, `issn`, `*_url`, lineages) are returned exactly as OpenAlex stores them, so each one resolves when passed back. The text output escapes that text for Markdown, so a stray `*`, `<tag>`, or `[x](y)` renders as written; IDs, and URLs that render as links, stay byte-identical
+- Clean provider text — OpenAlex passes titles, abstracts, and names through unsanitized; HTML entities are decoded against the full WHATWG table, comments and HTML/JATS/MathML formatting tags are removed, CDATA wrappers and IOP's `<?CDATA …?>` math markers are unwrapped with their TeX kept, MathType equation blobs (`% MathType!MTEF!…!44A1!`) are removed while the TeX that restates them stays, and a double-escaped line break (a literal `\n`) becomes a space; literal text such as `A < B`, `95% CI`, and TeX such as `\nu` is kept. Identifier and URL fields (`id`, `doi`, `ids`, `orcid`, `ror`, `issn`, `*_url`, lineages) are returned exactly as OpenAlex stores them, so each one resolves when passed back. The text output escapes that text for Markdown, so a stray `*`, `<tag>`, or `[x](y)` renders as written; IDs, and URLs that render as links, stay byte-identical
 
 ## Getting started
 
 ### Public Hosted Instance
 
-A public instance is available at `https://openalex.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:
+A public instance is available at `https://openalex.caseyjhand.com/mcp` — no installation required. Point an MCP client that supports remote servers at it via Streamable HTTP (Claude Desktop adds remote servers under Customize > Connectors > Add custom connector; its `claude_desktop_config.json` holds local servers only):
 
 ```json
 {
@@ -270,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/changelog/0.9.x/0.9.0.md

@@ -0,0 +1,48 @@
+---
+summary: "Filter values reach OpenAlex as it reads them (AND with +, country and language codes, quoted names), mixed OR/AND values are rejected up front, identifiers route to the record they name, and provider-text cleanup converges in one pass."
+breaking: true
+security: false
+---
+
+# 0.9.0 — 2026-10-18
+
+## Added
+
+- **`author_list`** works `select` field on `openalex_search_entities` and `openalex_get_citation_graph` — each author in authorship order as `{id, display_name, orcid}`, about a tenth the size of `authorships`; never part of the default or `["*"]`. ([#102](https://github.com/cyanheads/openalex-mcp-server/issues/102))
+- **`publisher`** sources `select` alias for `host_organization_name`. ([#97](https://github.com/cyanheads/openalex-mcp-server/issues/97))
+- **Identifier forms** — OpenAlex record-page and API URLs (`https://openalex.org/works/W…`, `https://api.openalex.org/works/W…`, `http`, or no scheme) resolve as IDs; a ROR resolves to its institution, funder, and publisher records, and a Crossref Funder Registry DOI (`10.13039/…`) to its funder. ([#98](https://github.com/cyanheads/openalex-mcp-server/issues/98), [#99](https://github.com/cyanheads/openalex-mcp-server/issues/99))
+- **`generate:iso-codes`** script, which builds `iso-codes.json`, and a **`start`** script.
+
+## Changed
+
+- A filter value that mixes `|` (OR) with an AND — a `+`, or a space on a field where words mean AND — now fails before any request as `mixed_and_or_in_filter_value` on all four filter-taking tools. OpenAlex drops every `|` alternative that ANDs more than one value, so on a multi-valued field such a value returned a partial set (`authorships.institutions.country_code: DE|FR+US` returned only the German works); on a single-valued field such as `type`, `article+review|book` happened to return the right set, and that call is now rejected too. The recovery puts the AND in a second key. ([#107](https://github.com/cyanheads/openalex-mcp-server/issues/107))
+- **`upstream_unavailable`** replaces `upstream_invalid_params_other` when a semantic search's query embedding fails upstream, with a keyword-search fallback in the recovery. ([#96](https://github.com/cyanheads/openalex-mcp-server/issues/96))
+- **`upstream_plan_required`** replaces `rate_limited` for a filter OpenAlex serves only on a paid plan (`created_date`, `updated_date`, and their `from_`/`to_` forms); it fails on the first request instead of retrying. ([#114](https://github.com/cyanheads/openalex-mcp-server/issues/114))
+- **`openalex_research_landscape`** funding step groups by `funders.id`, which counts every work that lists a funder. ([#100](https://github.com/cyanheads/openalex-mcp-server/issues/100))
+- **`openalex_describe_fields`** field catalog regenerated against OpenAlex's current field lists. ([#104](https://github.com/cyanheads/openalex-mcp-server/issues/104))
+- **`openalex_resolve_name`** no-match notice names the `filters` that excluded the match. ([#103](https://github.com/cyanheads/openalex-mcp-server/issues/103))
+- **Docker image** prunes musl-only native packages from the production dependencies; `server.json` npm entries launch the package bin through `npx`, and the HTTP entry sets `MCP_TRANSPORT_TYPE`.
+
+## Fixed
+
+- **`+` (AND within a field)** now ANDs; it went out percent-encoded and matched nothing. ([#107](https://github.com/cyanheads/openalex-mcp-server/issues/107))
+- **Country and language filter values** are converted to the codes OpenAlex stores: on `country_code`, `country_codes`, and `countries` keys an alpha-3 code, numeric code, or English name becomes its alpha-2 code (`UK` becomes `GB`), and a `language` ISO 639-2 code or English name becomes its ISO 639-1 code. A country value that cannot be a code (`Germanyy`, `999`, `unknown`, `DE US`) fails as `invalid_country_code`; it used to match nothing, and its negation matched everything. ([#101](https://github.com/cyanheads/openalex-mcp-server/issues/101))
+- **Multi-word values on exact-match keys** (`awards.funder_display_name`, `geo.city`, `raw_affiliation_strings`, and the like) are sent as one quoted phrase instead of matching nothing; a comma in them, or in a `.search.exact` value, is quoted rather than rejected. A `"` inside the outer pair of any value the server quotes, or of a caller-quoted value outside a free-text search filter, fails as `quote_in_filter_value`. ([#113](https://github.com/cyanheads/openalex-mcp-server/issues/113), [#115](https://github.com/cyanheads/openalex-mcp-server/issues/115))
+- **By-ID lookups stay on their entity type's path**: a `.` or `..` segment in `id`, `seed_id`, or an `openalex_resolve_name` identifier, plain or percent-encoded, fails as `id_dot_segment` before any request, and a `?`, `#`, `\`, tab, or line break inside an identifier is sent percent-encoded as part of it. ([#109](https://github.com/cyanheads/openalex-mcp-server/issues/109))
+- **An OpenAlex ID of another entity type** than the lookup's on `id` or `seed_id` (or a concept ID) fails as `id_type_mismatch` before any request. ([#99](https://github.com/cyanheads/openalex-mcp-server/issues/99))
+- **A name `query` with `filters` but no `entity_type`** on `openalex_resolve_name` fails as `filters_without_entity_type` before any request; every such call failed upstream. ([#105](https://github.com/cyanheads/openalex-mcp-server/issues/105))
+- **Short names shaped like OpenAlex IDs** (keyword `p53`, `F1`, `S1`) fall through to the name search when the ID lookup misses. ([#106](https://github.com/cyanheads/openalex-mcp-server/issues/106))
+- **Provider text** — MathType MTEF equation blobs and End lines are removed, keeping the TeX that restates each equation; a second cleanup pass no longer changes a result: an instruction target ended by a no-break space, an `<?MML` span measured before trimming, and a removal that joins text into a construct all converge in one pass. ([#92](https://github.com/cyanheads/openalex-mcp-server/issues/92), [#110](https://github.com/cyanheads/openalex-mcp-server/issues/110), [#111](https://github.com/cyanheads/openalex-mcp-server/issues/111), [#112](https://github.com/cyanheads/openalex-mcp-server/issues/112))
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.10 → ^0.13.15 (framework skills and scripts resynced)
+- `pino-pretty` ^13.1.3 → ^13.2.0
+- `zod` ^4.6.5 → ^4.6.7
+- `@biomejs/biome` ^2.5.14 → ^2.5.15 (dev)
+- `@types/node` ^26.6.3 → ^26.6.5 (dev)
+- `ignore` ^7.0.10 → ^7.0.12 (dev)
+- `mdast-util-from-markdown` ^2.0.3 → ^2.1.0 (dev)
+- `tsc-alias` ^1.9.5 → ^1.9.7 (dev)
+- `vitest` ^5.0.2 → ^5.0.4 (dev)
+- `packageManager` and Docker base images bun 1.4.2 → 1.4.3

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/prompts/definitions/literature-review.prompt.js

@@ -41,7 +41,7 @@ Follow this workflow using the OpenAlex tools:
    - Search with multiple related topic IDs to capture adjacent areas`}
    Use select to keep payloads manageable.
 
-3. **Identify key papers** — Re-run the step 2 search with sort: "-cited_by_count" to surface landmark works, keeping the topical filters in place: an explicit sort replaces relevance ranking, so without them you get the most-cited works in the catalog rather than in "${args.topic}". Then call openalex_search_entities with id and a select naming the fields you need (e.g. ["abstract", "authorships", "primary_location"]) for the most important ones — an id lookup on its own returns the curated default projection. A long array such as authorships on a large collaboration comes back as a window listed in the response's windows; page the rest with slice: {"field": "authorships", "offset": <the next offset it names>} on the same id.
+3. **Identify key papers** — Re-run the step 2 search with sort: "-cited_by_count" to surface landmark works, keeping the topical filters in place: an explicit sort replaces relevance ranking, so without them you get the most-cited works in the catalog rather than in "${args.topic}". Then call openalex_search_entities with id and a select naming the fields you need (e.g. ["abstract", "author_list", "primary_location"]) for the most important ones — an id lookup on its own returns the curated default projection. author_list gives each author's name, ID, and ORCID; select authorships instead when you need affiliations, at several times the size. A long array such as author_list on a large collaboration comes back as a window listed in the response's windows; page the rest with slice: {"field": "author_list", "offset": <the next offset it names>} on the same id.
 
 4. **Trace citations** — For each key paper, use openalex_get_citation_graph with direction "cites" to find subsequent work that cites it, and direction "cited_by" to find foundational work it references.
 

package/dist/mcp-server/prompts/definitions/research-landscape.prompt.js

@@ -29,7 +29,7 @@ Use the OpenAlex tools to build a quantitative profile:
 
 4. **Open access** — Group by oa_status. What fraction is freely available?
 
-5. **Funding** — Group by awards.funder_id to identify major funders. The group keys are OpenAlex funder IDs, not names: pass the top ones to openalex_resolve_name to get human-readable names — it takes an identifier directly and needs no entity_type. When readable labels suffice and exact counts are not critical, group by awards.funder_display_name instead to get names in a single hop.
+5. **Funding** — Group by funders.id to identify major funders. It counts every work that lists a funder and labels each group with the funder's name. For grant-level questions such as award numbers, use the awards.* fields.
 
 6. **Impact** — Search for the most-cited works (sort by -cited_by_count). Get details on the top 5.