@cyanheads/openalex-mcp-server 0.7.15 → 0.8.0

package/dist/services/openalex/openalex-service.d.ts

@@ -58,6 +58,12 @@ export declare function inferIdentifier(query: string): ResolvedIdentifier | und
  * a work has no works of its own, which is the same thing autocomplete reports.
  */
 export declare function toAutocompleteRecord(entityType: EntityType, record: EntityRecord): AutocompleteRecord;
+/**
+ * The upstream field one caller-supplied `select` name projects to — `authors` → `authorships`
+ * on works, `h_index` → `summary_stats` where that object exists; any other name unchanged.
+ * Exported so a tool can find the record key a one-field projection lands under.
+ */
+export declare function translateSelectField(entityType: SearchParams['entityType'], field: string): string;
 /**
  * Rewrite one caller-supplied filter key to the upstream OpenAlex name, before the
  * value-dependent `id` rewrite. Exported so the citation-graph tool can check a caller's key
@@ -68,6 +74,13 @@ export declare function toAutocompleteRecord(entityType: EntityType, record: Ent
  * typos no map can preempt.
  */
 export declare function translateFilterKey(entityType: SearchParams['entityType'], key: string): string;
+/**
+ * Recovery for a spent daily budget on a server that sends no API key. It runs on the smaller
+ * anonymous budget, so a key is the one fix besides waiting. A keyed server's budget is already
+ * the larger one, and a caller of a shared endpoint cannot set the server's environment, so that
+ * case keeps the key-neutral recovery each tool's contract declares.
+ */
+export declare const BUDGET_EXHAUSTED_KEYLESS_HINT = "This server's daily OpenAlex budget is spent and refills at midnight UTC \u2014 retrying before then will not succeed. The server sends no OpenAlex API key, so it runs on the smaller anonymous budget; setting OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) raises it.";
 declare class OpenAlexService {
     private readonly baseUrl;
     private readonly apiKey;
@@ -104,7 +117,7 @@ export declare function getOpenAlexService(): OpenAlexService;
  * Return the typed field catalog keyed by entity type → context → field list.
  * Only `filter` and `select` arrays are stored. `group_by` resolves to the `filter` key here;
  * the describe-fields handler then prunes the fields group_by cannot target (raw dates,
- * `*.search` operators, and `from_*`/`to_*` range modifiers).
+ * `*.search` operators, `from_*`/`to_*` range modifiers, and a per-type set from a live sweep).
  */
 export declare function getFieldCatalog(): Record<EntityType, {
     filter: string[];

package/dist/services/openalex/openalex-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openalex-service.d.ts","sourceRoot":"","sources":["../../../src/services/openalex/openalex-service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAsBtD,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EAGvB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAwFpB;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,8OACgM,CAAC;AA0BpO;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAuF9C;AAuBD,8FAA8F;AAC9F,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,UAAU,CAAC;IACvB,gGAAgG;IAChG,EAAE,EAAE,MAAM,CAAC;IACX,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAkB7E;AAuJD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,YAAY,GACnB,kBAAkB,CAUpB;AAoHD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9F;AAiYD,cAAM,eAAe;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,cAKC;IAED,yFAAyF;IACzF,OAAO,CAAC,OAAO;IAgDf,OAAO,CAAC,2BAA2B;IA2EnC,OAAO,CAAC,aAAa;IAqCrB,sEAAsE;IAChE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CA6FtE;IAED,4BAA4B;IACtB,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAkEzE;IAED;;;;;;;;;;;;OAYG;IACG,iBAAiB,CACrB,UAAU,EAAE,kBAAkB,EAC9B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,kBAAkB,CAAC,CAkB7B;IAED,oCAAoC;IAC9B,YAAY,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsBxF;CACF;AAID,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAIpD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAAC,UAAU,EAAE;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAE5F"}
+{"version":3,"file":"openalex-service.d.ts","sourceRoot":"","sources":["../../../src/services/openalex/openalex-service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAuBtD,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EAGvB,KAAK,YAAY,EACjB,KAAK,UAAU,EAEf,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAoFpB;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,8OACgM,CAAC;AA0BpO;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAuF9C;AAuBD,8FAA8F;AAC9F,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,UAAU,CAAC;IACvB,gGAAgG;IAChG,EAAE,EAAE,MAAM,CAAC;IACX,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAkB7E;AA4HD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,YAAY,GACnB,kBAAkB,CAUpB;AA2ED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,EACtC,KAAK,EAAE,MAAM,GACZ,MAAM,CAQR;AA+CD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9F;AAqSD;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,mSACmP,CAAC;AAsJ9R,cAAM,eAAe;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,cAKC;IAED,yFAAyF;IACzF,OAAO,CAAC,OAAO;IAgDf,OAAO,CAAC,2BAA2B;IAgGnC,OAAO,CAAC,aAAa;IAqCrB,sEAAsE;IAChE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CA6FtE;IAED,4BAA4B;IACtB,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CA2DzE;IAED;;;;;;;;;;;;OAYG;IACG,iBAAiB,CACrB,UAAU,EAAE,kBAAkB,EAC9B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,kBAAkB,CAAC,CAkB7B;IAED,oCAAoC;IAC9B,YAAY,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsBxF;CACF;AAID,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAIpD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAAC,UAAU,EAAE;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAE5F"}

package/dist/services/openalex/openalex-service.js

@@ -8,6 +8,7 @@ import { getServerConfig } from '../../config/server-config.js';
 import { mergeUpstreamBudget, parseUpstreamBudget } from './budget.js';
 import fieldCatalog from './field-catalog.json' with { type: 'json' };
 import { rankFields } from './field-ranker.js';
+import { normalizeProviderText, normalizeProviderValue } from './provider-text.js';
 import { DEFAULT_SELECT, ENTITY_TYPES, } from './types.js';
 import { redactUrlsInMessage } from './url-redaction.js';
 /**
@@ -40,7 +41,7 @@ const BOOLEAN_GROUP_BY_FIELDS = new Set([
  *   (skip if already quoted).
  * - All other keys: throw a pre-flight validation error — OpenAlex OR-lists use `|`, not commas.
  */
-function buildFilterString(filters, ctx) {
+function buildFilterString(filters) {
     return filters
         .map(([key, value]) => {
         if (value.includes(',')) {
@@ -50,11 +51,7 @@ function buildFilterString(filters, ctx) {
                 return `${key}:${quoted}`;
             }
             // Non-search key: comma is a caller error — OpenAlex uses | for OR, not comma.
-            throw invalidParams(`Filter \`${key}\` value contains a comma, which OpenAlex reads as a filter separator. Use \`|\` for OR (e.g. \`2020|2021\`), or a \`.search\` filter or the \`query\` parameter for free text.`, {
-                ...ctx.recoveryFor('comma_in_filter_value'),
-                reason: 'comma_in_filter_value',
-                filterKey: key,
-            });
+            throw invalidParams(`Filter \`${key}\` value contains a comma, which OpenAlex reads as a filter separator. Use \`|\` for OR (e.g. \`2020|2021\`), or a \`.search\` filter or the \`query\` parameter for free text.`, { reason: 'comma_in_filter_value', filterKey: key });
         }
         return `${key}:${value}`;
     })
@@ -243,7 +240,7 @@ export function inferIdentifier(query) {
     const colon = normalized.indexOf(':');
     if (colon > 0) {
         const scheme = normalized.slice(0, colon).toLowerCase();
-        const entityType = ENTITY_TYPE_BY_ID_PREFIX[scheme];
+        const entityType = ownEntry(ENTITY_TYPE_BY_ID_PREFIX, scheme);
         return entityType ? { entityType, id: normalized, scheme } : undefined;
     }
     const letter = ROUTABLE_OPENALEX_ID.exec(normalized)?.[1];
@@ -266,80 +263,54 @@ function reconstructAbstract(invertedIndex) {
     words.sort((a, b) => a[0] - b[0]);
     return words.map(([, word]) => word).join(' ');
 }
-const NAMED_HTML_ENTITIES = {
-    amp: '&',
-    apos: "'",
-    gt: '>',
-    lt: '<',
-    nbsp: ' ',
-    quot: '"',
-};
-const MAX_UNICODE_CODE_POINT = 0x10ffff;
-function codePointToString(code, fallback) {
-    return Number.isInteger(code) && code >= 0 && code <= MAX_UNICODE_CODE_POINT
-        ? String.fromCodePoint(code)
-        : fallback;
-}
-/**
- * Decode HTML entities that OpenAlex sometimes returns in `display_name` and similar fields
- * (e.g. `Nature Clinical Practice Gastroenterology &#38; Hepatology`). Handles numeric
- * (`&#38;`), hex (`&#x27E9;`), and the common named entities. The trailing semicolon is
- * optional — upstream sometimes drops it (`&#38 Hepatology`) and HTML5 parsers tolerate
- * this; matching strictly would leave malformed entities literal in the output. Unknown or
- * out-of-range entities pass through unchanged so we never silently corrupt data.
- */
-function decodeHtmlEntities(input) {
-    if (!input.includes('&'))
-        return input;
-    return input.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);?/gi, (match, body) => {
-        const lower = body.toLowerCase();
-        if (lower.startsWith('#x')) {
-            return codePointToString(Number.parseInt(lower.slice(2), 16), match);
-        }
-        if (lower.startsWith('#')) {
-            return codePointToString(Number.parseInt(lower.slice(1), 10), match);
-        }
-        return NAMED_HTML_ENTITIES[lower] ?? match;
-    });
-}
-/** Recursively decode HTML entities in every string leaf of a JSON value. */
-function deepDecodeHtmlEntities(value) {
-    if (typeof value === 'string')
-        return decodeHtmlEntities(value);
-    if (Array.isArray(value))
-        return value.map(deepDecodeHtmlEntities);
-    if (isRecord(value)) {
-        const next = {};
-        for (const [k, v] of Object.entries(value)) {
-            next[k] = deepDecodeHtmlEntities(v);
-        }
-        return next;
-    }
-    return value;
-}
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 function hasAbstractInvertedIndex(record) {
     return isRecord(record.abstract_inverted_index);
 }
+/**
+ * Normalize provider text on one record, once, at the service boundary — both response surfaces
+ * read the result, and nothing downstream normalizes again.
+ */
 function normalizeEntityRecord(record) {
     if (!hasAbstractInvertedIndex(record))
-        return deepDecodeHtmlEntities(record);
+        return normalizeProviderValue(record);
     const { abstract_inverted_index, ...rest } = record;
-    // Decode keys via the reconstructed abstract — `deepDecodeHtmlEntities` only walks
-    // values, so entities living in inverted-index word keys (e.g. `"&amp;"`) would
-    // otherwise survive into the plaintext output.
+    // Normalize the reconstructed abstract, not the index — `normalizeProviderValue` only walks
+    // values, so entities and markup living in inverted-index word keys (`"&amp;"`, `"<!--"`)
+    // would otherwise survive, and a tag split across words only exists once they are joined.
     return {
-        ...deepDecodeHtmlEntities(rest),
-        abstract: decodeHtmlEntities(reconstructAbstract(abstract_inverted_index)),
+        ...normalizeProviderValue(rest),
+        abstract: normalizeProviderText(reconstructAbstract(abstract_inverted_index)),
     };
 }
 function normalizeEntityRecords(results) {
     return results.map(normalizeEntityRecord);
 }
 function normalizeAutocompleteRecords(results) {
-    return results.map((r) => deepDecodeHtmlEntities(r));
+    return results.map((r) => normalizeProviderValue(r));
+}
+/**
+ * Keys OpenAlex gives the missing-value bucket `:include_unknown` adds: `-111`/`-111.0` on
+ * numeric fields in count order, `unknown` on string fields and under key-ascending traversal,
+ * and `https://openalex.org/<type>/unknown` on ID fields.
+ */
+function isUnknownGroupKey(key) {
+    return key === '-111' || key === '-111.0' || key === 'unknown' || key.endsWith('/unknown');
+}
+/**
+ * Normalize one aggregation group. `key` stays byte-identical to upstream — it is what a caller
+ * matches and filters on — while the label is provider text. The unknown bucket is flagged only
+ * when it was requested, since no other page can carry one.
+ */
+function normalizeGroup(group, includeUnknown) {
+    return {
+        key: group.key,
+        key_display_name: normalizeProviderValue(group.key_display_name),
+        count: group.count,
+        ...(includeUnknown && isUnknownGroupKey(group.key) ? { is_unknown: true } : {}),
+    };
 }
 /** Entity type → the record field holding its canonical external identifier. */
 const EXTERNAL_ID_FIELD = {
@@ -461,15 +432,29 @@ const FILTER_ALIASES_WORKS = {
  * aliasing rather than before.
  */
 function translateSelect(entityType, fields) {
-    const withRequired = Array.from(new Set([...REQUIRED_SEARCH_FIELDS, ...fields]));
+    const upstream = [...REQUIRED_SEARCH_FIELDS, ...fields].map((field) => translateSelectField(entityType, field));
+    return Array.from(new Set(upstream));
+}
+/**
+ * The upstream field one caller-supplied `select` name projects to — `authors` → `authorships`
+ * on works, `h_index` → `summary_stats` where that object exists; any other name unchanged.
+ * Exported so a tool can find the record key a one-field projection lands under.
+ */
+export function translateSelectField(entityType, field) {
     const aliases = entityType === 'works'
         ? SELECT_ALIASES_WORKS
         : SUMMARY_STATS_ENTITY_TYPES.has(entityType)
             ? SELECT_ALIASES_SUMMARY_STATS
             : undefined;
-    if (!aliases)
-        return withRequired;
-    return Array.from(new Set(withRequired.map((field) => aliases[field] ?? field)));
+    return ownEntry(aliases, field) ?? field;
+}
+/**
+ * A table's own entry for `key`, or undefined. The alias and scheme tables are plain object
+ * literals, so a bracket read of a caller-supplied `constructor` or `__proto__` returns the
+ * inherited `Object.prototype` member instead of missing.
+ */
+function ownEntry(table, key) {
+    return table !== undefined && Object.hasOwn(table, key) ? table[key] : undefined;
 }
 /**
  * Resolve the upstream `select` projection for an entity request — applied identically to
@@ -512,7 +497,7 @@ function isOpenAlexFilterValue(value) {
  * typos no map can preempt.
  */
 export function translateFilterKey(entityType, key) {
-    return entityType === 'works' ? (FILTER_ALIASES_WORKS[key] ?? key) : key;
+    return entityType === 'works' ? (ownEntry(FILTER_ALIASES_WORKS, key) ?? key) : key;
 }
 /**
  * Rewrite caller-supplied filter keys to the upstream OpenAlex names. Works-only key map plus
@@ -544,8 +529,8 @@ const KNOWN_AUTOCOMPLETE_TYPES = new Set(ENTITY_TYPES.map((type) => type.replace
 /**
  * `JsonRpcErrorCode` → `{ factory, reason }` for shaping normalized OpenAlex throws.
  * Driven by `httpStatusToErrorCode` so the status-table stays in lockstep with the
- * framework. `reason` is the literal carried on `data.reason` and matched against
- * tool contracts via `ctx.recoveryFor`.
+ * framework. `reason` is the literal carried on `data.reason`; the framework matches it
+ * against the calling tool's contract and fills that entry's recovery hint.
  */
 const NORMALIZED_THROW_BY_CODE = {
     [JsonRpcErrorCode.InvalidParams]: { factory: invalidParams, reason: 'upstream_invalid_params' },
@@ -681,17 +666,33 @@ const REJECTED_FIELD_RE = /^([a-z0-9_.]+)\s+is not a valid/i;
 const SORT_REQUIRES_SEARCH_RE = /must include a search query/i;
 /**
  * OpenAlex 400 emitted when group_by targets a field it cannot aggregate — a raw date, a
- * float, or a `*.search` operator: "Cannot group by date, number, or search fields." Names
- * no rejected field; the caller needs a categorical/year field, not a corrected name.
+ * float, or a `*.search` operator ("Cannot group by date, number, or search fields."), a
+ * field it refuses by name ("Cannot group by display_name."), or one it has not built
+ * ("Group by referenced_works is not supported at this time."). Either way the field name is
+ * valid; the caller needs a groupable field, not a corrected name.
  */
-const UNGROUPABLE_GROUP_BY_RE = /cannot group by/i;
+const UNGROUPABLE_GROUP_BY_RE = /cannot group by|\bgroup by \S+ is not supported\b/i;
 /**
  * OpenAlex 400 emitted when an entity-ID filter receives something that isn't an ID —
  * typically a name: "'Albert' is not a valid OpenAlex ID." (upstream splits the value on
  * whitespace before validating, so only the first token is named). The fix is to resolve
- * the name to an ID first, which no other 400 shape's recovery says.
+ * the name to an ID first, which no other 400 shape's recovery says. Capture group 1 is the
+ * quoted value, when present — `isGroupByIdRejection` reads it.
  */
-const INVALID_ID_VALUE_RE = /is not a valid OpenAlex ID/i;
+const INVALID_ID_VALUE_RE = /(?:'([^']*)'\s+)?is not a valid OpenAlex ID/i;
+/**
+ * The same invalid-ID 400 also answers a group_by upstream cannot aggregate: authors grouped
+ * by `concepts.id`, `concept.id`, or `x_concepts.id` gets "'41008148' is not a valid OpenAlex
+ * ID.", naming a concept ID from upstream's own aggregation. Upstream validates `filter` before
+ * `group_by`, so a quoted value the request's filter carries is the caller's bad ID; anything
+ * else on a group_by request — including a request with no filter at all — is the group_by.
+ */
+function isGroupByIdRejection(quotedValue, requestParams) {
+    if (!requestParams.group_by)
+        return false;
+    const filter = requestParams.filter;
+    return !filter || (quotedValue !== undefined && !filter.includes(quotedValue));
+}
 /**
  * OpenAlex 400 emitted when the search text exceeds the length it accepts: the body's `error`
  * reads "Search query too long" and its `message` quotes both the submitted length and the
@@ -703,18 +704,24 @@ const QUERY_TOO_LONG_RE = /\bsearch\b(?: query)?(?: is)? too long\b/i;
 /**
  * A single upstream HTTP 400 spans several distinct failure shapes, each needing a different
  * caller recovery. Pick the declared tool reason from the message shape so the per-tool
- * `recovery` hint (resolved via `ctx.recoveryFor`) matches the actual failure instead of
+ * `recovery` hint (filled by the framework from the reason) matches the actual failure instead of
  * always claiming a rejected field name. Ordering: the over-long-query and ID-value checks run
  * first because they are the shapes naming a concrete upstream concept; the field-name check is
  * anchored at string start; the rest are keyword probes; anything unmatched falls through to a
- * neutral `_other` reason so no shape inherits the field-name recovery by default.
+ * neutral `_other` reason so no shape inherits the field-name recovery by default. The
+ * invalid-ID shape alone also reads the request's own `filter`/`group_by` params, because
+ * upstream sends it for two different mistakes.
  */
-function classifyInvalidParamsReason(rawMessage) {
+function classifyInvalidParamsReason(rawMessage, requestParams) {
     if (rawMessage !== undefined) {
         if (QUERY_TOO_LONG_RE.test(rawMessage))
             return 'query_too_long';
-        if (INVALID_ID_VALUE_RE.test(rawMessage))
-            return 'upstream_invalid_id_value';
+        const invalidId = INVALID_ID_VALUE_RE.exec(rawMessage);
+        if (invalidId) {
+            return isGroupByIdRejection(invalidId[1], requestParams)
+                ? 'upstream_ungroupable_group_by'
+                : 'upstream_invalid_id_value';
+        }
         if (REJECTED_FIELD_RE.test(rawMessage))
             return 'upstream_invalid_params';
         if (SORT_REQUIRES_SEARCH_RE.test(rawMessage))
@@ -724,8 +731,34 @@ function classifyInvalidParamsReason(rawMessage) {
     }
     return 'upstream_invalid_params_other';
 }
+/**
+ * Longest `q`, in Unicode code points, that `/autocomplete/{entity_type}` answers. Past it, a
+ * query holding an ASCII letter gets an HTML 500 on every attempt, on all eight typed endpoints;
+ * cross-entity `/autocomplete` has no such bound. The bound is upstream's to move, so it only
+ * relabels a 500 that already happened rather than rejecting input: if OpenAlex raises it, the
+ * branch never fires; if it lowers it, the shorter failures stay `upstream_unavailable`.
+ */
+const AUTOCOMPLETE_QUERY_MAX_CODE_POINTS = 1000;
+/**
+ * The code-point length of a typed autocomplete `q` past `AUTOCOMPLETE_QUERY_MAX_CODE_POINTS` —
+ * the one request shape whose HTTP 500 is a caller error rather than an outage — or undefined.
+ * Counted in code points, as upstream counts: `length` would count an emoji twice.
+ */
+function overLongAutocompleteQuery(path, params) {
+    if (!path.startsWith('/autocomplete/') || params.q === undefined)
+        return;
+    const codePoints = [...params.q].length;
+    return codePoints > AUTOCOMPLETE_QUERY_MAX_CODE_POINTS ? codePoints : undefined;
+}
 /** Reason for a 429 caused by daily-budget exhaustion rather than burst throttling. */
 const BUDGET_EXHAUSTED_REASON = 'upstream_budget_exhausted';
+/**
+ * Recovery for a spent daily budget on a server that sends no API key. It runs on the smaller
+ * anonymous budget, so a key is the one fix besides waiting. A keyed server's budget is already
+ * the larger one, and a caller of a shared endpoint cannot set the server's environment, so that
+ * case keeps the key-neutral recovery each tool's contract declares.
+ */
+export const BUDGET_EXHAUSTED_KEYLESS_HINT = "This server's daily OpenAlex budget is spent and refills at midnight UTC — retrying before then will not succeed. The server sends no OpenAlex API key, so it runs on the smaller anonymous budget; setting OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) raises it.";
 /**
  * OpenAlex returns 429 for two unrelated conditions: bursting past its per-second ceiling,
  * and spending the daily usage budget. The recoveries are opposites — one clears in seconds,
@@ -748,11 +781,13 @@ function classifyRateLimitReason(rawMessage) {
  * failure shapes under one error code — 400 (rejected field / relevance sort without a
  * search / ungroupable group_by / non-ID filter value) and 429 (burst throttle vs. spent
  * daily budget) — and each shape needs its own caller recovery, so both discriminate on the
- * upstream message. Every other code maps to a single reason.
+ * upstream message, and the 400 invalid-ID shape on the request params too. Every other code
+ * maps to a single reason.
  */
-function resolveThrowReason(code, mappedReason, rawMessage) {
-    if (code === JsonRpcErrorCode.InvalidParams)
-        return classifyInvalidParamsReason(rawMessage);
+function resolveThrowReason(code, mappedReason, rawMessage, requestParams) {
+    if (code === JsonRpcErrorCode.InvalidParams) {
+        return classifyInvalidParamsReason(rawMessage, requestParams);
+    }
     if (code === JsonRpcErrorCode.RateLimited)
         return classifyRateLimitReason(rawMessage);
     return mappedReason;
@@ -905,7 +940,7 @@ class OpenAlexService {
                 return parsed;
             }
             catch (error) {
-                this.throwNormalizedRequestError(error, path, ctx);
+                this.throwNormalizedRequestError(error, path, params);
             }
         }, {
             operation,
@@ -915,11 +950,18 @@ class OpenAlexService {
             signal: ctx.signal,
         });
     }
-    throwNormalizedRequestError(error, path, ctx) {
+    throwNormalizedRequestError(error, path, params) {
         if (!(error instanceof McpError)) {
             throw error;
         }
         const statusCode = typeof error.data?.statusCode === 'number' ? error.data.statusCode : undefined;
+        // A typed autocomplete `q` past the bound 500s on every attempt, with an HTML body that
+        // names nothing — read as ServiceUnavailable it would be retried and reported as an outage.
+        // `retryable: false` keeps it out of `withRetry`, and the recovery says to shorten the name.
+        const overLongQuery = statusCode === 500 ? overLongAutocompleteQuery(path, params) : undefined;
+        if (overLongQuery !== undefined) {
+            throw invalidParams(`OpenAlex autocomplete failed on a ${overLongQuery.toLocaleString('en-US')}-character query — ${path} accepts at most ${AUTOCOMPLETE_QUERY_MAX_CODE_POINTS.toLocaleString('en-US')} characters.`, { ...error.data, path, reason: 'query_too_long', retryable: false }, { cause: error });
+        }
         // Status-mapped failures classify off the HTTP status. Everything else — the client-side
         // `REQUEST_TIMEOUT_MS` abort, DNS/connection failures, and the `parseResponse` throws
         // (empty body, HTML, invalid JSON) — never carries a status, so the error's own code is
@@ -940,7 +982,7 @@ class OpenAlexService {
         const { factory } = normalized;
         const upstream = parseOpenAlexErrorBody(error.data?.responseBody);
         const rawMessage = upstream?.message ?? upstream?.error;
-        const reason = resolveThrowReason(code, normalized.reason, rawMessage);
+        const reason = resolveThrowReason(code, normalized.reason, rawMessage, params);
         // A truncated body's appended valid-fields list is misleading. For an invalid-field
         // 400, replace it with catalog-backed ranked suggestions; otherwise strip it. The two
         // are mutually exclusive — appendFieldSuggestions already drops the partial list, so it
@@ -964,10 +1006,10 @@ class OpenAlexService {
             ...error.data,
             path,
             reason,
-            ...ctx.recoveryFor(reason),
             // A PMCID lookup that 404s is not a miss to verify and retry — OpenAlex indexes no
             // PMCIDs, so every tool's generic "verify the ID" recovery hands back the one instruction
-            // that cannot help. Substituted here, where all three ID-accepting tools inherit it.
+            // that cannot help. Substituted here, where all three ID-accepting tools inherit it; an
+            // explicit hint wins over the one the framework would fill from the contract.
             ...(code === JsonRpcErrorCode.NotFound && isPmcidLookup(path)
                 ? { recovery: { hint: PMCID_NOT_INDEXED_HINT } }
                 : {}),
@@ -976,6 +1018,11 @@ class OpenAlexService {
             // flag is the framework's per-error opt-out from that loop; the contract's own
             // `retryable` field only informs the client and cannot stop our own retries.
             ...(reason === BUDGET_EXHAUSTED_REASON ? { retryable: false } : {}),
+            // Only a keyless server can raise its budget with a key; an explicit hint wins over the
+            // key-neutral one the framework fills from the contract.
+            ...(reason === BUDGET_EXHAUSTED_REASON && !this.apiKey
+                ? { recovery: { hint: BUDGET_EXHAUSTED_KEYLESS_HINT } }
+                : {}),
             ...(upstream?.error ? { upstreamError: upstream.error } : {}),
             ...(upstream?.message ? { upstreamMessage: upstream.message } : {}),
         };
@@ -1029,7 +1076,7 @@ class OpenAlexService {
             queryParams[getSearchParamKey(params.searchMode)] = params.query;
         }
         if (hasEntries(params.filters)) {
-            queryParams.filter = buildFilterString(translateFilters(params.entityType, params.filters), ctx);
+            queryParams.filter = buildFilterString(translateFilters(params.entityType, params.filters));
         }
         const sort = normalizeSort(params.sort);
         if (sort) {
@@ -1056,6 +1103,9 @@ class OpenAlexService {
         // plus a cursor with a 400 — so it walks its candidate set with `page`/`per_page` instead.
         // Sampling returns one page only, so cursor is mutually exclusive there too. Both
         // combinations are rejected at the tool layer; the service never sends them together.
+        // The tool also rejects `sample` under semantic mode (OpenAlex ignores it there, and the
+        // population request below would pair `search.semantic` with `cursor=*`) and `sample`
+        // beside `sort` (OpenAlex refuses the pair), so neither reaches this method.
         if (params.searchMode === 'semantic') {
             if (params.page !== undefined)
                 queryParams.page = String(params.page);
@@ -1090,7 +1140,7 @@ class OpenAlexService {
             ? `${params.groupBy}:include_unknown`
             : params.groupBy;
         if (hasEntries(params.filters)) {
-            queryParams.filter = buildFilterString(translateFilters(params.entityType, params.filters), ctx);
+            queryParams.filter = buildFilterString(translateFilters(params.entityType, params.filters));
         }
         if (params.perPage !== undefined) {
             queryParams.per_page = String(params.perPage);
@@ -1120,11 +1170,7 @@ class OpenAlexService {
         // as "the filters matched no groups". A present-but-empty array is that honest answer and
         // passes through.
         if (data.group_by === undefined) {
-            throw serviceUnavailable(`OpenAlex returned no group_by aggregation for ${path} (group_by=${params.groupBy})`, {
-                path,
-                reason: 'upstream_missing_group_by',
-                ...ctx.recoveryFor('upstream_missing_group_by'),
-            });
+            throw serviceUnavailable(`OpenAlex returned no group_by aggregation for ${path} (group_by=${params.groupBy})`, { path, reason: 'upstream_missing_group_by' });
         }
         return {
             meta: {
@@ -1132,7 +1178,7 @@ class OpenAlexService {
                 groups_count: data.meta.groups_count ?? data.group_by.length,
                 next_cursor: data.meta.next_cursor ?? null,
             },
-            groups: deepDecodeHtmlEntities(data.group_by),
+            groups: data.group_by.map((group) => normalizeGroup(group, params.includeUnknown === true)),
         };
     }
     /**
@@ -1172,7 +1218,7 @@ class OpenAlexService {
             q: params.query,
         };
         if (hasEntries(params.filters)) {
-            queryParams.filter = buildFilterString(Object.entries(params.filters), ctx);
+            queryParams.filter = buildFilterString(Object.entries(params.filters));
         }
         const data = (await this.request(path, queryParams, ctx));
         // Cross-entity autocomplete can return types not in our enum (country, license, etc.).
@@ -1196,7 +1242,7 @@ export function getOpenAlexService() {
  * Return the typed field catalog keyed by entity type → context → field list.
  * Only `filter` and `select` arrays are stored. `group_by` resolves to the `filter` key here;
  * the describe-fields handler then prunes the fields group_by cannot target (raw dates,
- * `*.search` operators, and `from_*`/`to_*` range modifiers).
+ * `*.search` operators, `from_*`/`to_*` range modifiers, and a per-type set from a live sweep).
  */
 export function getFieldCatalog() {
     return fieldCatalog;