@cyanheads/openalex-mcp-server 0.7.15 → 0.8.0

package/changelog/0.7.x/0.7.16.md

@@ -0,0 +1,32 @@
+---
+summary: "Provider text arrives clean on both surfaces (entities decoded, markup removed, Markdown escaped in content[]), plus a flagged unknown group_by bucket, local rejection of sample with semantic search or sort, and corrected group_by field lists and error reasons."
+breaking: false
+security: false
+---
+
+# 0.7.16 — 2026-09-24
+
+## Added
+
+- **`is_unknown`** on `openalex_analyze_trends` groups — set on the missing-value bucket `include_unknown` adds (keyed `-111`, `-111.0`, `unknown`, or an ID ending in `/unknown`). The text output labels it `unknown (no value; key …)` and renders it after the last year of a time series. ([#75](https://github.com/cyanheads/openalex-mcp-server/issues/75))
+- **`sample_with_semantic`** and **`sample_with_sort`** error reasons on `openalex_search_entities` — `sample` with `search_mode: "semantic"` (which OpenAlex does not sample) or with any `sort` (which OpenAlex refuses) is rejected before the upstream call. `id` lookups still drop both with a notice. ([#83](https://github.com/cyanheads/openalex-mcp-server/issues/83), [#85](https://github.com/cyanheads/openalex-mcp-server/issues/85))
+
+## Changed
+
+- **Provider text in `structuredContent`** — string values now carry decoded HTML entities (full WHATWG table) with HTML comments removed and HTML/JATS/MathML formatting tags unwrapped; literal text such as `A < B` or `Fish <Actinopterygii>` is kept. Affected records return different values than before. ([#76](https://github.com/cyanheads/openalex-mcp-server/issues/76))
+- **`content[]` escaping** — every `format()` backslash-escapes provider text for Markdown, so a stray `*`, `<tag>`, or `[x](y)` renders as written; IDs and URLs that render as links stay byte-identical. ([#76](https://github.com/cyanheads/openalex-mcp-server/issues/76))
+- **`openalex_analyze_trends` group `key`** is passed through raw, exactly as OpenAlex returns it (it was entity-decoded before); `key_display_name` gets the provider-text normalization. ([#76](https://github.com/cyanheads/openalex-mcp-server/issues/76))
+
+## Fixed
+
+- **Named-entity decoding** no longer resolves `Object.prototype` names — `&constructor;` stays literal instead of becoming `function Object() { [native code] }`. ([#76](https://github.com/cyanheads/openalex-mcp-server/issues/76))
+- **`openalex_describe_fields` `group_by` view** drops the fields OpenAlex refuses to aggregate — decimal scores such as `fwci`, several source year fields, `display_name`, external-ID fields, and the concept keys on authors — and five works fields whose grouping fails with an HTTP 500 on every attempt (`cites`, `has_embeddings`, and the three `raw_type` location fields), per a live sweep of every listed field on all eight entity types; they stay valid filters. ([#86](https://github.com/cyanheads/openalex-mcp-server/issues/86))
+- **`group_by` rejections** on authors' concept keys (reported upstream as an invalid ID) and on `referenced_works` now surface as `upstream_ungroupable_group_by`, whose recovery points at `openalex_describe_fields`; an invalid-ID 400 quoting a value from the request's `filter` keeps `upstream_invalid_id_value`. ([#87](https://github.com/cyanheads/openalex-mcp-server/issues/87))
+- **`openalex_resolve_name`** reports the HTTP 500 that typed autocomplete returns for a `query` over 1,000 code points as `query_too_long` after one attempt, instead of a retried `upstream_unavailable` outage. ([#81](https://github.com/cyanheads/openalex-mcp-server/issues/81))
+- **Semantic `meta.count`** — descriptions and the runtime notice no longer claim a 50-candidate ceiling; the candidate count is query-dependent and can exceed 50 (the 50-per-page cap stands). ([#84](https://github.com/cyanheads/openalex-mcp-server/issues/84))
+
+## Dependencies
+
+- `mdast-util-from-markdown` ^2.0.3 (new devDependency)
+- `mdast-util-gfm` ^3.1.0 (new devDependency)
+- `micromark-extension-gfm` ^3.0.0 (new devDependency)

package/changelog/0.8.x/0.8.0.md

@@ -0,0 +1,38 @@
+---
+summary: "Search and citation-graph responses hold to a 64,000-byte budget, with continuations for cut records and a new slice input for windowed arrays, alongside provider-text and identifier fixes."
+breaking: false
+security: false
+---
+
+# 0.8.0 — 2026-09-30
+
+## Added
+
+- **`slice: {field, offset}`** on `openalex_search_entities` `id` lookups — pages one top-level array of the record from `offset`, as many elements as fit the budget (at least one), with the window and its `next` call in `windows`; it replaces `select`. `slice_without_id` and `slice_field_not_array` reject a `slice` with no `id`, or one naming `*` or a field that is not an array. ([#72](https://github.com/cyanheads/openalex-mcp-server/issues/72))
+
+## Changed
+
+- **Response budget on `openalex_search_entities` and `openalex_get_citation_graph`** — `structuredContent` and `content[]` each hold to 64,000 bytes. An oversized page returns fewer records and names the rest in a new `omitted` field, whose `next` is the `openalex_search_entities` call that returns them (an `openalex` ID filter, `id` for keywords); `next_cursor` is unchanged. ([#72](https://github.com/cyanheads/openalex-mcp-server/issues/72))
+- **Array windows** — a record too large on its own keeps its non-array fields and returns its largest arrays in part, each listed in a new `windows` field with an `id` + `slice` `next` call; `over_budget: true` marks a response whose smallest form still exceeds the budget. ([#72](https://github.com/cyanheads/openalex-mcp-server/issues/72))
+- **`openalex_literature_review`** step 3 names the `slice` call that pages a windowed `authorships` array. ([#72](https://github.com/cyanheads/openalex-mcp-server/issues/72))
+- **Error envelopes** carry `data.requestId`, and a tool error's `content[]` closes with the request ID (mcp-ts-core 0.13.10).
+- **Docker image** — production dependencies and the OTel peers install in a `$BUILDPLATFORM` `deps` stage that cross-targets the image platform; the image gains a `HEALTHCHECK` on `/healthz` and an `org.opencontainers.image.version` label, and no longer sets `MCP_FORCE_CONSOLE_LOGGING`.
+- **Packaging** — the npm package no longer ships `dist/*.mcpb`, the Docker build context excludes the MCP Registry token files and `.env.bak-*` backups, and the `.mcpb` bundle excludes `docs/idea.md` and `logs/`.
+
+## Fixed
+
+- **Provider-text delimiters** — CDATA sections, including unterminated ones and ones closed by a bare `]]`, and IOP's `<?CDATA …?>` are unwrapped with their TeX kept, the `<?MML …?>` restating them is removed, an unclosed `<!--inline-formula>` opener is removed as a tag, and a literal `\n` becomes a space; TeX such as `\nu` is kept. ([#89](https://github.com/cyanheads/openalex-mcp-server/issues/89))
+- **Identifier and URL fields** (such as `id`, `doi`, `ids`, `orcid`, `ror`, `issn_l`, and every `*_url`) are returned exactly as OpenAlex stores them rather than entity-decoded, so a returned DOI resolves when passed back. ([#94](https://github.com/cyanheads/openalex-mcp-server/issues/94))
+- **Possibly capped authorships** — a search or citation-graph work carrying exactly 100 `authorships`, the most OpenAlex returns on a list record, gets a `windows` entry with `possibly_capped: true` whose `next` is the `id` + `slice` call for the rest. ([#73](https://github.com/cyanheads/openalex-mcp-server/issues/73))
+- **`openalex_analyze_trends` on `authorships.countries`** — a works group_by on it notes that OpenAlex counts only each work's first 100 authorships and names `authorships.institutions.country_code`, which counts every one. ([#91](https://github.com/cyanheads/openalex-mcp-server/issues/91))
+- **`upstream_budget_exhausted` recovery** on all four tools says only that the server's daily budget refills at midnight UTC; the `OPENALEX_API_KEY` advice is added only when the server sends no key. ([#90](https://github.com/cyanheads/openalex-mcp-server/issues/90))
+- **`Object.prototype` names** — `select` fields and works `filter` keys such as `constructor` or `__proto__` pass through unchanged instead of resolving to the inherited member, `openalex_resolve_name` sends a `constructor:`-prefixed query to autocomplete, and a record key named `__proto__` survives normalization. ([#93](https://github.com/cyanheads/openalex-mcp-server/issues/93))
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.6 → ^0.13.10 (framework skills and scripts resynced)
+- `@socketsecurity/bun-security-scanner` ^1.1.2 → ^1.1.3 (dev)
+- `@types/node` ^26.6.2 → ^26.6.3 (dev)
+- `ignore` ^7.0.9 → ^7.0.10 (dev)
+- `vitest` ^5.0.1 → ^5.0.2 (dev)
+- `packageManager` and Docker base images bun 1.4.0 → 1.4.2

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.',
+    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`.",
     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,iUAAiU;IACnU,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,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"}

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.
+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.
 
 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/tools/definitions/analyze-trends.tool.d.ts

@@ -34,6 +34,7 @@ export declare const analyzeTrendsTool: import("@cyanheads/mcp-ts-core").ToolDef
         key: z.ZodString;
         key_display_name: z.ZodString;
         count: z.ZodNumber;
+        is_unknown: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>>;
 }, z.core.$strip>, readonly [{
     readonly reason: "rate_limited";
@@ -47,7 +48,7 @@ export declare const analyzeTrendsTool: import("@cyanheads/mcp-ts-core").ToolDef
     readonly code: JsonRpcErrorCode.RateLimited;
     readonly when: "The OpenAlex daily usage budget is spent (HTTP 429).";
     readonly retryable: false;
-    readonly recovery: "The daily budget refills at midnight UTC — retrying sooner will not succeed. Set OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) for a larger daily budget than anonymous access, or wait for the reset.";
+    readonly recovery: "This server's daily OpenAlex budget is spent and refills at midnight UTC — retrying before then will not succeed.";
     readonly thrownBy: "service";
 }, {
     readonly reason: "upstream_timeout";
@@ -96,8 +97,8 @@ export declare const analyzeTrendsTool: import("@cyanheads/mcp-ts-core").ToolDef
 }, {
     readonly reason: "upstream_ungroupable_group_by";
     readonly code: JsonRpcErrorCode.InvalidParams;
-    readonly when: "group_by targets a raw date, float, or *.search field OpenAlex cannot aggregate (HTTP 400).";
-    readonly recovery: "Group by a categorical or year field (e.g. publication_year, type, oa_status, or an integer count field) — raw date fields and *.search operators cannot be grouped. Call openalex_describe_fields(entity_type, \"group_by\") for the groupable set.";
+    readonly when: "group_by targets a field OpenAlex cannot aggregate — a raw date, a decimal score, a *.search operator, a field such as display_name, doi, or referenced_works, or a concept key on authors, which OpenAlex reports as an invalid OpenAlex ID (HTTP 400).";
+    readonly recovery: "Group by a field OpenAlex can aggregate, such as publication_year, type, or oa_status — call openalex_describe_fields(entity_type, \"group_by\") for the full groupable set of this entity type.";
     readonly thrownBy: "service";
 }, {
     readonly reason: "upstream_invalid_params_other";

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;AAKjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4U5B,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;AAWjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0W5B,CAAC"}

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

@@ -4,9 +4,13 @@
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { escapeMarkdown } from '../escape-markdown.js';
 import { renderBudgetTrailer } from '../render-budget.js';
+import { joinNotices } from '../response-budget.js';
 import { getOpenAlexService } 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.';
 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.',
     sourceUrl: 'https://github.com/cyanheads/openalex-mcp-server/blob/main/src/mcp-server/tools/definitions/analyze-trends.tool.ts',
@@ -25,7 +29,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             code: JsonRpcErrorCode.RateLimited,
             when: 'The OpenAlex daily usage budget is spent (HTTP 429).',
             retryable: false,
-            recovery: 'The daily budget refills at midnight UTC — retrying sooner will not succeed. Set OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) for a larger daily budget than anonymous access, or wait for the reset.',
+            recovery: "This server's daily OpenAlex budget is spent and refills at midnight UTC — retrying before then will not succeed.",
             thrownBy: 'service',
         },
         {
@@ -82,8 +86,8 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
         {
             reason: 'upstream_ungroupable_group_by',
             code: JsonRpcErrorCode.InvalidParams,
-            when: 'group_by targets a raw date, float, or *.search field OpenAlex cannot aggregate (HTTP 400).',
-            recovery: 'Group by a categorical or year field (e.g. publication_year, type, oa_status, or an integer count field) — raw date fields and *.search operators cannot be grouped. Call openalex_describe_fields(entity_type, "group_by") for the groupable set.',
+            when: 'group_by targets a field OpenAlex cannot aggregate — a raw date, a decimal score, a *.search operator, a field such as display_name, doi, or referenced_works, or a concept key on authors, which OpenAlex reports as an invalid OpenAlex ID (HTTP 400).',
+            recovery: 'Group by a field OpenAlex can aggregate, such as publication_year, type, or oa_status — call openalex_describe_fields(entity_type, "group_by") for the full groupable set of this entity type.',
             thrownBy: 'service',
         },
         {
@@ -115,7 +119,7 @@ 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". Authors: "last_known_institutions.country_code", "has_orcid". Sources: "type", "is_oa", "country_code". Not all fields support group_by — check entity docs if unsure.'),
+            .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.'),
         filters: z
             .record(z.string(), z.string())
             .optional()
@@ -123,7 +127,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
         include_unknown: z
             .boolean()
             .default(false)
-            .describe('Include a group for entities with no value for the grouped field. Hidden by default.'),
+            .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()
@@ -155,9 +159,17 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
         groups: z
             .array(z
             .object({
-            key: z.string().describe('Group key (OpenAlex ID or raw value).'),
-            key_display_name: z.string().describe('Human-readable group label.'),
+            key: z
+                .string()
+                .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.'),
             count: z.number().describe('Number of entities in this group.'),
+            is_unknown: z
+                .literal(true)
+                .optional()
+                .describe('Present only on the group include_unknown adds for entities with no value; its key is an OpenAlex sentinel (-111, -111.0, unknown, or an ID ending in /unknown), not a measured value.'),
         })
             .describe('A single aggregation group with its key, display label, and entity count.'))
             .describe('Aggregation groups with counts.'),
@@ -175,7 +187,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
         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, or when the page is full and more groups likely exist (truncation signal with narrowing advice). Absent otherwise.'),
+            .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.'),
         budget: z
             .object({
             costUsd: z
@@ -217,12 +229,14 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
         });
         const echo = buildAnalyzeEcho(input);
         ctx.enrich({ echo, totalCount: result.meta.count });
+        // `notice` is last-wins, so every sentence is collected and set once.
+        const notices = [];
         // 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,
         // where `count` is nonzero but every matched entity is null for the grouped field.
         if (result.groups.length === 0) {
-            ctx.enrich.notice(input.cursor === undefined
+            notices.push(input.cursor === undefined
                 ? `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.`);
         }
@@ -232,7 +246,7 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             // "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) {
-                ctx.enrich.notice(`Showing ${result.groups.length} groups in key-ascending order. Pass the returned \`next_cursor\` to continue the traversal.`);
+                notices.push(`Showing ${result.groups.length} groups in key-ascending order. Pass the returned \`next_cursor\` to continue the traversal.`);
             }
         }
         else if (result.groups.length === input.per_page) {
@@ -240,8 +254,20 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             // 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.
             const smallestCount = result.groups[result.groups.length - 1]?.count ?? 0;
-            ctx.enrich.notice(`Showing the top ${result.groups.length} groups by count. Smallest shown has count = ${smallestCount}; any omitted group has count ≤ ${smallestCount}. Narrow with \`filters\`, raise \`per_page\` (max 200), or enumerate all with \`order: "key"\`.`);
+            notices.push(`Showing the top ${result.groups.length} groups by count. Smallest shown has count = ${smallestCount}; any omitted group has count ≤ ${smallestCount}. Narrow with \`filters\`, raise \`per_page\` (max 200), or enumerate all with \`order: "key"\`.`);
         }
+        // OpenAlex aggregates authorships.countries from the first-100 window its list records carry,
+        // so the counts undercount large collaborations with nothing upstream saying so; every other
+        // authorships.* group_by counts all authorships. An empty page is included: a work whose first
+        // 100 authorships carry no country contributes no group. The service also accepts OpenAlex's
+        // own `:include_unknown` suffix in group_by.
+        if (input.entity_type === 'works' &&
+            input.group_by.replace(/:include_unknown$/, '') === 'authorships.countries') {
+            notices.push(COUNTRIES_CAP_NOTICE);
+        }
+        const notice = joinNotices(notices);
+        if (notice)
+            ctx.enrich.notice(notice);
         return {
             meta: {
                 count: result.meta.count,
@@ -262,15 +288,16 @@ export const analyzeTrendsTool = tool('openalex_analyze_trends', {
             ];
         }
         // Time-series groupings are returned upstream in count-desc — useful for "top N years"
-        // but jarring when reading a trend. Only the rendered text is reordered;
-        // structuredContent stays in upstream order for callers that want it.
-        const renderOrder = isTimeSeriesGrouping(result.groups)
-            ? [...result.groups].sort((a, b) => a.key.localeCompare(b.key))
+        // but jarring when reading a trend. Only the rendered text is reordered, with the
+        // unknown bucket after the last period; structuredContent stays in upstream order.
+        const known = result.groups.filter((g) => !g.is_unknown);
+        const renderOrder = isTimeSeriesGrouping(known)
+            ? [
+                ...known.sort((a, b) => a.key.localeCompare(b.key)),
+                ...result.groups.filter((g) => g.is_unknown),
+            ]
             : result.groups;
-        const lines = renderOrder.map((g) => {
-            const label = g.key === g.key_display_name ? g.key_display_name : `${g.key_display_name} (${g.key})`;
-            return `${label}: ${g.count}`;
-        });
+        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}\`*`
             : '';
@@ -286,6 +313,22 @@ const YEAR_OR_DATE_PATTERN = /^\d{4}(-\d{2}-\d{2})?$/;
 function isTimeSeriesGrouping(groups) {
     return groups.length > 1 && groups.every((g) => YEAR_OR_DATE_PATTERN.test(g.key));
 }
+/**
+ * The label a group line opens with. The unknown bucket is named as such — its key is a
+ * sentinel, and `-111.0: 48777` reads as a measured value. A label that begins the line is
+ * escaped for that position; the key is upstream's own and stays byte-identical unless it
+ * carries Markdown syntax.
+ */
+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)}`;
+        return `unknown (no value; key ${key}${label})`;
+    }
+    const display = escapeMarkdown(g.key_display_name, 'line-start');
+    return g.key === g.key_display_name ? display : `${display} (${key})`;
+}
 function buildAnalyzeEcho(input) {
     const parts = [`entity_type=${input.entity_type}`, `group_by=${input.group_by}`];
     if (input.filters && Object.keys(input.filters).length > 0) {

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

@@ -1 +1 @@
-{"version":3,"file":"analyze-trends.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/analyze-trends.tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"analyze-trends.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/analyze-trends.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/citation-graph.tool.d.ts

@@ -26,6 +26,26 @@ export declare const getCitationGraphTool: import("@cyanheads/mcp-ts-core").Tool
         id: z.ZodString;
         display_name: z.ZodNullable<z.ZodString>;
     }, z.core.$loose>>;
+    omitted: z.ZodOptional<z.ZodObject<{
+        ids: z.ZodArray<z.ZodString>;
+        next: z.ZodObject<{
+            tool: z.ZodLiteral<"openalex_search_entities">;
+            arguments: z.ZodObject<{}, z.core.$loose>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    windows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        field: z.ZodString;
+        offset: z.ZodNumber;
+        shown: z.ZodNumber;
+        total: z.ZodNumber;
+        possibly_capped: z.ZodBoolean;
+        next: z.ZodNullable<z.ZodObject<{
+            tool: z.ZodLiteral<"openalex_search_entities">;
+            arguments: z.ZodObject<{}, z.core.$loose>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    over_budget: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, readonly [{
     readonly reason: "rate_limited";
     readonly code: JsonRpcErrorCode.RateLimited;
@@ -38,7 +58,7 @@ export declare const getCitationGraphTool: import("@cyanheads/mcp-ts-core").Tool
     readonly code: JsonRpcErrorCode.RateLimited;
     readonly when: "The OpenAlex daily usage budget is spent (HTTP 429).";
     readonly retryable: false;
-    readonly recovery: "The daily budget refills at midnight UTC — retrying sooner will not succeed. Set OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) for a larger daily budget than anonymous access, or wait for the reset.";
+    readonly recovery: "This server's daily OpenAlex budget is spent and refills at midnight UTC — retrying before then will not succeed.";
     readonly thrownBy: "service";
 }, {
     readonly reason: "upstream_timeout";

package/dist/mcp-server/tools/definitions/citation-graph.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"citation-graph.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/citation-graph.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA2BjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmW/B,CAAC"}
+{"version":3,"file":"citation-graph.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/citation-graph.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAoCjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqW/B,CAAC"}

package/dist/mcp-server/tools/definitions/citation-graph.tool.js

@@ -5,9 +5,11 @@
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { renderBudgetTrailer } from '../render-budget.js';
-import { renderEntityRecord } from '../render-entity-record.js';
+import { fitRecordsToBudget, formatRecordPage, joinNotices, measurePageFrame, omittedOutputSchema, overBudgetOutputSchema, windowsOutputSchema, } from '../response-budget.js';
 import { getOpenAlexService, translateFilterKey } from '../../../services/openalex/openalex-service.js';
 const OPENALEX_URL_PREFIX = 'https://openalex.org/';
+/** What `meta.count` counts, in the rendered header. */
+const EDGE_NOUN = 'edge(s)';
 const DIRECTIONS = ['cites', 'cited_by', 'related_to'];
 const RESERVED_FILTER_KEYS = new Set(DIRECTIONS);
 function buildCitationEcho(input) {
@@ -20,7 +22,7 @@ function buildCitationEcho(input) {
     return parts.join(' | ');
 }
 export const getCitationGraphTool = tool('openalex_get_citation_graph', {
-    description: "Walk the citation graph one hop from a seed work. Direction picks the edge: incoming citations (`cites`), the seed's own references (`cited_by`), or OpenAlex's algorithmically-related works (`related_to`). Note: `direction` follows OpenAlex's filter convention, which inverts the common English reading — `cites` returns works that cite the seed; `cited_by` returns works the seed cites. Results use the works schema; combine with filters/sort to narrow further.",
+    description: "Walk the citation graph one hop from a seed work. Direction picks the edge: incoming citations (`cites`), the seed's own references (`cited_by`), or OpenAlex's algorithmically-related works (`related_to`). Note: `direction` follows OpenAlex's filter convention, which inverts the common English reading — `cites` returns works that cite the seed; `cited_by` returns works the seed cites. Results use the works schema; combine with filters/sort to narrow further. Responses cap at 64,000 bytes per surface unless the least a call can return is larger (`over_budget`); `omitted` and `windows` give the openalex_search_entities calls that continue a cut.",
     sourceUrl: 'https://github.com/cyanheads/openalex-mcp-server/blob/main/src/mcp-server/tools/definitions/citation-graph.tool.ts',
     annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     errors: [
@@ -37,7 +39,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
             code: JsonRpcErrorCode.RateLimited,
             when: 'The OpenAlex daily usage budget is spent (HTTP 429).',
             retryable: false,
-            recovery: 'The daily budget refills at midnight UTC — retrying sooner will not succeed. Set OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) for a larger daily budget than anonymous access, or wait for the reset.',
+            recovery: "This server's daily OpenAlex budget is spent and refills at midnight UTC — retrying before then will not succeed.",
             thrownBy: 'service',
         },
         {
@@ -138,14 +140,14 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
         select: z
             .array(z.string())
             .optional()
-            .describe('OpenAlex work field names to return. Always returned: id, display_name. Defaults to the curated works select if omitted.'),
+            .describe('OpenAlex work field names to return. Always returned: id, display_name. Defaults to the curated works select if omitted. Large projections may be cut to fit the response budget (`omitted`, `windows`).'),
         per_page: z
             .number()
             .int()
             .min(1)
             .max(100)
             .default(25)
-            .describe('Results per page (1-100). Default 25.'),
+            .describe('Results per page (1-100). Default 25. A budget-cut page returns fewer (`omitted`).'),
         cursor: z
             .string()
             .min(1)
@@ -160,11 +162,11 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
                 .describe('Total edges from seed_id in this direction (across all pages).'),
             per_page: z
                 .number()
-                .describe('Page size OpenAlex echoed for this request — the requested per_page, not the number of records returned. A short or exhausted page carries fewer records than this.'),
+                .describe('Page size OpenAlex echoed for this request — the requested per_page, not the number of records returned. A short or exhausted page carries fewer records than this, as does a page the response budget cut (`omitted`).'),
             next_cursor: z
                 .string()
                 .nullable()
-                .describe('Cursor for next page. null if no more results.'),
+                .describe('Cursor for next page. null if no more results. Continues after the full upstream page, `omitted` works included.'),
         })
             .describe('Result metadata including pagination.'),
         results: z
@@ -176,9 +178,12 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
                 .nullable()
                 .describe('Work title. null when OpenAlex holds no title for the record (paratext works and other untitled entries) — use `id` to identify it.'),
         })
-            .passthrough()
+            .loose()
             .describe('A single OpenAlex work record on the citation graph. Additional fields vary by `select`.'))
-            .describe('Works on the citation graph in this direction.'),
+            .describe('Works on the citation graph in this direction. Text values are plain text — HTML entities decoded, HTML/JATS/MathML markup removed — except identifier and URL fields such as `id`, `doi`, `ids`, and `*_url`, returned exactly as OpenAlex stores them. Works cut by the response budget are in `omitted`; partial or possibly capped arrays are in `windows`.'),
+        omitted: omittedOutputSchema,
+        windows: windowsOutputSchema,
+        over_budget: overBudgetOutputSchema,
     }),
     // Agent-facing context for the success path — the query as parsed (seed + direction),
     // the total edge count, and recovery guidance for empty traversals. Populated via
@@ -191,7 +196,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
         notice: z
             .string()
             .optional()
-            .describe('Guidance when no edges are returned. A first call suggests verifying the seed_id, broadening filters, or trying a different direction; a `cursor` continuation says the walk is already past its last edge instead. Absent when results are present.'),
+            .describe('Guidance notice. Set when no edges are returned — a first call suggests verifying the seed_id, broadening filters, or trying a different direction; a `cursor` continuation says the walk is already past its last edge instead — when the response budget cut works, windowed an array, or ran over, and when a work carries exactly 100 authorships (possibly capped). Absent otherwise.'),
         budget: z
             .object({
             costUsd: z
@@ -225,11 +230,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
         if (reserved !== undefined) {
             const upstreamKey = translateFilterKey('works', reserved);
             const resolution = upstreamKey === reserved ? '' : ` — it resolves to \`${upstreamKey}\``;
-            throw ctx.fail('reserved_filter_key', `${reserved} cannot be passed in filters${resolution}, and direction reserves cites/cited_by/related_to.`, {
-                ...ctx.recoveryFor('reserved_filter_key'),
-                reservedKey: reserved,
-                direction: input.direction,
-            });
+            throw ctx.fail('reserved_filter_key', `${reserved} cannot be passed in filters${resolution}, and direction reserves cites/cited_by/related_to.`, { reservedKey: reserved, direction: input.direction });
         }
         const service = getOpenAlexService();
         /**
@@ -243,7 +244,7 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
         const seedLookup = await service.search({ entityType: 'works', id: input.seed_id, select: ['id'] }, ctx);
         const seedRecord = seedLookup.results[0];
         if (!seedRecord?.id) {
-            throw ctx.fail('entity_not_found', `Could not resolve seed_id "${input.seed_id}" to an OpenAlex work ID.`, { ...ctx.recoveryFor('entity_not_found'), seedId: input.seed_id });
+            throw ctx.fail('entity_not_found', `Could not resolve seed_id "${input.seed_id}" to an OpenAlex work ID.`, { seedId: input.seed_id });
         }
         const workId = seedRecord.id.replace(OPENALEX_URL_PREFIX, '');
         const mergedFilters = {
@@ -268,34 +269,33 @@ export const getCitationGraphTool = tool('openalex_get_citation_graph', {
         ctx.enrich({ echo, totalCount: result.meta.count });
         // An empty page on a `cursor` continuation means the walk already returned every edge it
         // had, so the verify-the-seed advice would send the caller after a seed that is fine.
-        if (result.results.length === 0) {
-            ctx.enrich.notice(input.cursor === undefined
+        const emptyNotice = result.results.length > 0
+            ? undefined
+            : input.cursor === undefined
                 ? `No edges for ${echo}. Verify the seed_id with openalex_resolve_name, broaden filters, or try a different direction.`
-                : `Pagination exhausted for ${echo} — the previous page held the last edge, so this one came back empty. Stop paging rather than broadening filters or changing direction.`);
-        }
-        return {
-            meta: {
-                count: result.meta.count,
-                per_page: result.meta.per_page,
-                next_cursor: result.meta.next_cursor,
-            },
-            results: result.results,
+                : `Pagination exhausted for ${echo} — the previous page held the last edge, so this one came back empty. Stop paging rather than broadening filters or changing direction.`;
+        const meta = {
+            count: result.meta.count,
+            per_page: result.meta.per_page,
+            next_cursor: result.meta.next_cursor,
         };
+        const page = fitRecordsToBudget({
+            records: result.results,
+            entityType: 'works',
+            path: 'list',
+            select: input.select,
+            measureFrame: (disclosure, budgetNotice) => measurePageFrame({ meta, results: [], ...disclosure }, EDGE_NOUN, {
+                echo,
+                totalCount: result.meta.count,
+                totalLabel: 'Total Edges',
+                notice: joinNotices([emptyNotice, budgetNotice]),
+            }),
+        });
+        const notice = joinNotices([emptyNotice, page.notice]);
+        if (notice)
+            ctx.enrich.notice(notice);
+        return { meta, results: page.results, ...page.disclosure };
     },
-    format: (result) => {
-        const lines = [];
-        const countLabel = `${result.meta.count} edge(s) — ${result.meta.per_page} per page`;
-        const header = result.meta.next_cursor
-            ? `**${countLabel}** — next cursor: \`${result.meta.next_cursor}\``
-            : `**${countLabel}**`;
-        lines.push(header);
-        if (result.results.length === 0) {
-            return [{ type: 'text', text: lines.join('\n') }];
-        }
-        for (const record of result.results) {
-            lines.push(...renderEntityRecord(record));
-        }
-        return [{ type: 'text', text: lines.join('\n') }];
-    },
+    format: (result) => formatRecordPage(result, EDGE_NOUN),
 });
 //# sourceMappingURL=citation-graph.tool.js.map