@cyanheads/openalex-mcp-server 0.7.14 → 0.7.16

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

@@ -25,6 +25,7 @@ export declare const PMCID_NOT_INDEXED_HINT = "OpenAlex indexes no PMCIDs, so a
  * "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1234567/" → "pmcid:PMC1234567"
  * "https://pubmed.ncbi.nlm.nih.gov/21491125" → "pmid:21491125"
  * "PMID:21491125" → "pmid:21491125"
+ * "https://openalex.org/keywords/groundwater" → "groundwater"
  * "W2741809807" → "W2741809807"
  */
 export declare function normalizeId(id: string): string;
@@ -43,6 +44,11 @@ export interface ResolvedIdentifier {
  * and stamps external ones with their scheme prefix — so detection reduces to reading back what
  * it produced. Names never survive that: a name with a colon in it yields a prefix that is in no
  * scheme table, and anything else fails the native-ID pattern.
+ *
+ * Keywords are the exception, and are read from the raw query instead: their IDs are slugs, so
+ * `normalizeId()` reduces the URL to a bare word that no longer names an entity type. The URL
+ * form is the only keyword spelling that identifies itself — a bare slug is indistinguishable
+ * from any other name, and autocomplete is the right answer for it.
  */
 export declare function inferIdentifier(query: string): ResolvedIdentifier | undefined;
 /**
@@ -52,6 +58,16 @@ 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;
+/**
+ * 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
+ * against the ones `direction` reserves: checking the raw key alone let `cited_works` past the
+ * guard, and it then aliased onto `cites` and collided with the direction's own value.
+ *
+ * Misses fall through unchanged so upstream's 400 with the valid-field list still fires for
+ * typos no map can preempt.
+ */
+export declare function translateFilterKey(entityType: SearchParams['entityType'], key: string): string;
 declare class OpenAlexService {
     private readonly baseUrl;
     private readonly apiKey;
@@ -88,7 +104,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;AAiFpB;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,8OACgM,CAAC;AAgBpO;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAgF9C;AAsBD,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;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAa7E;AAuJD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,YAAY,GACnB,kBAAkB,CAUpB;AAmeD,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,CA0FtE;IAED,4BAA4B;IACtB,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAkDzE;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;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;AA4HD;;;;;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;AAybD,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;IAkGnC,OAAO,CAAC,aAAa;IAqCrB,sEAAsE;IAChE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAgGtE;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"}

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';
 /**
@@ -27,17 +28,21 @@ const BOOLEAN_GROUP_BY_FIELDS = new Set([
     'has_fulltext',
 ]);
 /**
- * Build an OpenAlex filter string from a key-value record.
- * Input: { "cited_by_count": ">100", "is_oa": "true" }
+ * Build an OpenAlex filter string from ordered key-value clauses.
+ * Input: [["cited_by_count", ">100"], ["is_oa", "true"]]
  * Output: "cited_by_count:>100,is_oa:true"
  *
+ * Clauses, not a record: OpenAlex ANDs a repeated key (`publication_year:2020,publication_year:2024`
+ * matches works in both years, which is nothing), and two caller filters can resolve to one
+ * canonical key. A record would hold only the last of them.
+ *
  * Comma handling (commas collide with OpenAlex's filter clause separator):
  * - `*.search` keys: wrap the value in double quotes for faithful phrase passthrough
  *   (skip if already quoted).
  * - All other keys: throw a pre-flight validation error — OpenAlex OR-lists use `|`, not commas.
  */
 function buildFilterString(filters, ctx) {
-    return Object.entries(filters)
+    return filters
         .map(([key, value]) => {
         if (value.includes(',')) {
             if (key.endsWith('.search')) {
@@ -87,6 +92,15 @@ const PMC_URL_PATTERN = /^https?:\/\/(?:www\.)?(?:pmc\.ncbi\.nlm\.nih\.gov|ncbi\
  * mapping here and the `openalex_resolve_name` miss notice so both say the same thing.
  */
 export const PMCID_NOT_INDEXED_HINT = 'OpenAlex indexes no PMCIDs, so a PMCID resolves nothing however it is written. Convert it to a PMID or DOI — the NCBI ID Converter (https://www.ncbi.nlm.nih.gov/pmc/tools/idconv/) does this — and retry with that identifier.';
+/**
+ * A keyword's own OpenAlex URL. Keywords are the only `ENTITY_TYPES` member OpenAlex addresses
+ * by slug rather than a native letter-and-number ID, and their URL spells out the `keywords/`
+ * path segment the endpoint already supplies — so stripping the host alone builds
+ * `/keywords/keywords/<slug>`, which 404s, and the ID a search returns cannot be fed back into
+ * its own lookup. The host is anchored on both ends so a look-alike domain is never read as
+ * OpenAlex, and the slug group requires at least one character so a slugless path stays unrouted.
+ */
+const OPENALEX_KEYWORD_URL_PATTERN = /^https:\/\/openalex\.org\/keywords\/([^/?#]+)\/?$/i;
 /**
  * Prefix `normalizeId()` emits → the single entity type that identifier scheme addresses.
  * Every external scheme OpenAlex indexes belongs to exactly one entity type, which is what
@@ -113,10 +127,17 @@ const ENTITY_TYPE_BY_ID_PREFIX = {
  * "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1234567/" → "pmcid:PMC1234567"
  * "https://pubmed.ncbi.nlm.nih.gov/21491125" → "pmid:21491125"
  * "PMID:21491125" → "pmid:21491125"
+ * "https://openalex.org/keywords/groundwater" → "groundwater"
  * "W2741809807" → "W2741809807"
  */
 export function normalizeId(id) {
     const trimmed = id.trim();
+    // Keyword URL → its bare slug. Runs ahead of the generic OpenAlex strip, which would leave
+    // the `keywords/` segment in place and double it against the endpoint path.
+    const keywordSlug = OPENALEX_KEYWORD_URL_PATTERN.exec(trimmed)?.[1];
+    if (keywordSlug) {
+        return keywordSlug;
+    }
     // Full OpenAlex URL
     if (trimmed.startsWith('https://openalex.org/')) {
         return trimmed.replace('https://openalex.org/', '');
@@ -187,19 +208,20 @@ const ENTITY_TYPE_BY_ID_LETTER = {
     A: 'authors',
     F: 'funders',
     I: 'institutions',
-    K: 'keywords',
     P: 'publishers',
     S: 'sources',
     T: 'topics',
     W: 'works',
 };
 /**
- * Native OpenAlex IDs this server can route. `C` (the deprecated Concepts entity) and `G` are
- * deliberately absent even though `OPENALEX_ID_VALUE_PATTERN` accepts them as *filter values*:
- * neither is in `ENTITY_TYPES`, so there is no endpoint to fetch one from. They fall through to
- * autocomplete rather than being routed to a path that would 404.
+ * Native OpenAlex IDs this server can route. Three letters `OPENALEX_ID_VALUE_PATTERN` accepts
+ * as *filter values* are deliberately absent here. `C` (the deprecated Concepts entity) and `G`
+ * are not in `ENTITY_TYPES`, so there is no endpoint to fetch one from. `K` is in `ENTITY_TYPES`,
+ * but OpenAlex identifies keywords by slug and emits no numeric K-prefixed IDs, so routing that
+ * shape addressed nothing — `OPENALEX_KEYWORD_URL_PATTERN` is the keyword identifier. All three
+ * fall through to autocomplete rather than being routed to a path that would 404.
  */
-const ROUTABLE_OPENALEX_ID = /^([AFIKPSTW])\d+$/;
+const ROUTABLE_OPENALEX_ID = /^([AFIPSTW])\d+$/;
 /**
  * Classify a query as an identifier, or return `undefined` for a name.
  *
@@ -207,8 +229,17 @@ const ROUTABLE_OPENALEX_ID = /^([AFIKPSTW])\d+$/;
  * and stamps external ones with their scheme prefix — so detection reduces to reading back what
  * it produced. Names never survive that: a name with a colon in it yields a prefix that is in no
  * scheme table, and anything else fails the native-ID pattern.
+ *
+ * Keywords are the exception, and are read from the raw query instead: their IDs are slugs, so
+ * `normalizeId()` reduces the URL to a bare word that no longer names an entity type. The URL
+ * form is the only keyword spelling that identifies itself — a bare slug is indistinguishable
+ * from any other name, and autocomplete is the right answer for it.
  */
 export function inferIdentifier(query) {
+    const keywordSlug = OPENALEX_KEYWORD_URL_PATTERN.exec(query.trim())?.[1];
+    if (keywordSlug) {
+        return { entityType: 'keywords', id: keywordSlug, scheme: 'openalex' };
+    }
     const normalized = normalizeId(query);
     const colon = normalized.indexOf(':');
     if (colon > 0) {
@@ -236,80 +267,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 = {
@@ -472,19 +477,38 @@ const OPENALEX_ID_VALUE_PATTERN = /^(?:https:\/\/openalex\.org\/)?[WAISTKPFCG]\d
 function isOpenAlexFilterValue(value) {
     return value.split('|').every((seg) => OPENALEX_ID_VALUE_PATTERN.test(seg));
 }
+/**
+ * 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
+ * against the ones `direction` reserves: checking the raw key alone let `cited_works` past the
+ * guard, and it then aliased onto `cites` and collided with the direction's own value.
+ *
+ * Misses fall through unchanged so upstream's 400 with the valid-field list still fires for
+ * typos no map can preempt.
+ */
+export function translateFilterKey(entityType, key) {
+    return entityType === 'works' ? (FILTER_ALIASES_WORKS[key] ?? key) : key;
+}
 /**
  * Rewrite caller-supplied filter keys to the upstream OpenAlex names. Works-only key map plus
  * a universal `id` → `openalex` rewrite when the value looks like an OpenAlex ID. Values pass
- * through unchanged. Misses fall through so upstream's 400 with the valid-field list still
- * fires for typos no map can preempt.
+ * through unchanged.
+ *
+ * Emits clauses rather than a record because an alias and its canonical name are two separate
+ * constraints that resolve to one key — `{year: "2020", publication_year: "2024"}` is a request
+ * for works in both years. A record kept only whichever came last, so JSON property order
+ * silently decided the result set. Both are sent, matching OpenAlex's own repeated-key AND.
+ * Clauses that resolve to an identical key *and* value are deduplicated: restating one
+ * constraint changes nothing upstream.
  */
 function translateFilters(entityType, filters) {
-    const aliases = entityType === 'works' ? FILTER_ALIASES_WORKS : undefined;
-    const out = {};
+    const out = [];
     for (const [rawKey, value] of Object.entries(filters)) {
-        const aliased = aliases?.[rawKey] ?? rawKey;
+        const aliased = translateFilterKey(entityType, rawKey);
         const finalKey = aliased === 'id' && isOpenAlexFilterValue(value) ? 'openalex' : aliased;
-        out[finalKey] = value;
+        if (out.some(([key, existing]) => key === finalKey && existing === value))
+            continue;
+        out.push([finalKey, value]);
     }
     return out;
 }
@@ -632,30 +656,62 @@ 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
+ * ceiling — "Your search is too long (1890 characters; the limit is 1500)." The bound is
+ * upstream's to move (its docs still say 2,000 characters with truncation), so it is reported
+ * from the message rather than pinned as a local `.max()` that would drift.
+ */
+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
- * always claiming a rejected field name. Ordering: the ID-value check runs first because it
- * is the only shape 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.
+ * 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. 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 (INVALID_ID_VALUE_RE.test(rawMessage))
-            return 'upstream_invalid_id_value';
+        if (QUERY_TOO_LONG_RE.test(rawMessage))
+            return 'query_too_long';
+        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))
@@ -665,6 +721,25 @@ 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';
 /**
@@ -689,11 +764,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;
@@ -846,7 +923,7 @@ class OpenAlexService {
                 return parsed;
             }
             catch (error) {
-                this.throwNormalizedRequestError(error, path, ctx);
+                this.throwNormalizedRequestError(error, path, params, ctx);
             }
         }, {
             operation,
@@ -856,11 +933,24 @@ class OpenAlexService {
             signal: ctx.signal,
         });
     }
-    throwNormalizedRequestError(error, path, ctx) {
+    throwNormalizedRequestError(error, path, params, ctx) {
         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',
+                ...ctx.recoveryFor('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
@@ -881,7 +971,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
@@ -993,10 +1083,18 @@ class OpenAlexService {
         else {
             queryParams.per_page = String(params.perPage ?? 25);
         }
-        // Semantic search doesn't support cursor pagination — use page/per_page only.
-        // Sampling returns one page only — cursor is mutually exclusive (enforced at the tool
-        // layer; the service never sends both).
-        if (params.searchMode !== 'semantic' && params.sample === undefined) {
+        // Semantic search doesn't support cursor pagination — OpenAlex answers `search.semantic`
+        // 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);
+        }
+        else if (params.sample === undefined) {
             queryParams.cursor = params.cursor ?? '*';
         }
         const searchRequest = this.request(`/${params.entityType}`, queryParams, ctx);
@@ -1049,14 +1147,26 @@ class OpenAlexService {
         else if (keyAscOrder) {
             queryParams.cursor = '*';
         }
-        const data = (await this.request(`/${params.entityType}`, queryParams, ctx));
+        const path = `/${params.entityType}`;
+        const data = (await this.request(path, queryParams, ctx));
+        // No `group_by` key at all is OpenAlex's plain *list* shape — the aggregation never ran.
+        // Defaulting it to `[]` reported a successful aggregation of nothing, which a caller reads
+        // 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'),
+            });
+        }
         return {
             meta: {
                 count: data.meta.count,
-                groups_count: data.meta.groups_count ?? data.group_by?.length ?? null,
+                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)),
         };
     }
     /**
@@ -1096,7 +1206,7 @@ class OpenAlexService {
             q: params.query,
         };
         if (hasEntries(params.filters)) {
-            queryParams.filter = buildFilterString(params.filters, ctx);
+            queryParams.filter = buildFilterString(Object.entries(params.filters), ctx);
         }
         const data = (await this.request(path, queryParams, ctx));
         // Cross-entity autocomplete can return types not in our enum (country, license, etc.).
@@ -1120,7 +1230,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;