@cyanheads/openalex-mcp-server 0.10.1 → 0.11.0

package/dist/mcp-server/tools/record-page.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @fileoverview Record pages for the tools that return OpenAlex entity records
+ * (`openalex_search_entities`, `openalex_get_citation_graph`). A page holds every record of the
+ * upstream page, and an `id` lookup every selected array whole. `windows` discloses OpenAlex's
+ * author caps — 100 authorships on a list record, 5,000 stored on a singleton — and every
+ * count-based `slice` window, each with the call that continues it. A response whose
+ * `structuredContent` or `content[]` text would exceed 8,000,000 bytes is refused, never
+ * shortened, so both surfaces and the JSON-RPC envelope stay under the 16 MiB an HTTP client
+ * such as Claude Code reads from one response.
+ * @module mcp-server/tools/record-page
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import type { EntityRecord, EntityType } from '../../services/openalex/types.js';
+/** Per-surface ceiling: serialized `structuredContent`, and summed `content[]` text. */
+export declare const RESPONSE_CEILING_BYTES = 8000000;
+/**
+ * Bytes reserved on each surface for the `budget` enrichment field (the OpenAlex usage budget,
+ * not a size limit). The service writes it from OpenAlex's rate-limit headers through
+ * `ctx.enrich`, so its value is not in the handler's hands when the response is measured. The
+ * allowance covers its widest realistic form — every number at full double precision, with a
+ * prepaid balance — measured at 176 bytes as a JSON member and 108 as a trailer line with its
+ * separator.
+ */
+export declare const BUDGET_FIELD_ALLOWANCE_BYTES = 256;
+declare const arrayWindowSchema: 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>;
+/** Output field: arrays returned in part, or possibly in part, each with its continuation. */
+export declare const windowsOutputSchema: 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>>>;
+type ArrayWindow = z.infer<typeof arrayWindowSchema>;
+/** A record page as both tools return it: upstream meta, records, and any windows. */
+export interface RecordPage {
+    meta: {
+        count: number;
+        next_cursor: string | null;
+        per_page: number;
+    };
+    results: EntityRecord[];
+    windows?: ArrayWindow[] | undefined;
+}
+/** Enrichment the handler writes, which the framework renders into the `content[]` trailer. */
+export interface PageEnrichment {
+    echo: string;
+    notice: string | undefined;
+    totalCount: number;
+    /** The tool's `enrichmentTrailer.totalCount.label`. */
+    totalLabel: string;
+}
+/** `https://openalex.org/W123` → `W123`. Any other form (a keyword URL) passes through whole. */
+export declare function bareId(id: string): string;
+/** Join notice sentences, dropping empty ones; undefined when none remain. */
+export declare function joinNotices(parts: readonly (string | undefined)[]): string | undefined;
+/**
+ * `format()` for a record page: a count header, each record, then each window.
+ * `noun` names what `meta.count` counts ("result(s)", "edge(s)").
+ */
+export declare function formatRecordPage(page: RecordPage, noun: string): {
+    type: 'text';
+    text: string;
+}[];
+/**
+ * Byte-exact copy of the framework's inline code span (`codeSpan` in mcp-ts-core's formatting
+ * utils, which the package does not export), the form a one-line trailer string takes: the
+ * fence runs one backtick past the value's longest backtick run, and a space pads each side when
+ * a backtick touches an end or the value both begins and ends with a space. The echo is always
+ * one line — caller text in it is JSON-encoded — so the fenced-block form never applies here.
+ * Authored code spans around one-line values use it too, so a backtick in the value cannot close
+ * the span early.
+ */
+export declare function codeSpan(value: string): string;
+/**
+ * The enrichment trailer's bytes, minus the service-written `budget` line. Fields render as the
+ * framework renders them for these tools: `echo` as a code span under its `Query` label,
+ * `totalCount` under `totalLabel`, and `notice` as a block quote with every line quoted, joined
+ * after a leading blank line.
+ */
+export declare function trailerTextBytes(enrichment: PageEnrichment): number;
+/** What a record page is built from, besides its records. */
+interface PageContext {
+    echo: string;
+    entityType: EntityType;
+    meta: RecordPage['meta'];
+    /** The tool's own notice sentences, joined ahead of the page's. */
+    notices: readonly (string | undefined)[];
+    /** What `meta.count` counts in the rendered header ("result(s)", "edge(s)"). */
+    noun: string;
+    totalCount: number;
+    /** The tool's `enrichmentTrailer.totalCount.label`. */
+    totalLabel: string;
+}
+/** A page within the ceiling, or the typed refusal of one that is not. */
+export type PageOutcome = {
+    kind: 'page';
+    page: RecordPage;
+    notice: string | undefined;
+} | {
+    kind: 'too_large';
+    message: string;
+    data: TooLargeData;
+};
+/** `data` for a `response_too_large` failure. */
+export interface TooLargeData {
+    ceilingBytes: number;
+    /** The largest value of the named input whose response fits; absent when none does. */
+    largestFitting?: {
+        input: 'per_page' | 'slice.limit';
+        value: number;
+    };
+    recovery: {
+        hint: string;
+    };
+    structuredBytes: number;
+    textBytes: number;
+    [key: string]: unknown;
+}
+export interface RecordPageRequest extends PageContext {
+    /**
+     * How the listing continues past this page, for the hint naming a smaller `per_page`: a
+     * `cursor`, or the next `page` of a semantic search or a sample.
+     */
+    continuation: 'cursor' | 'page';
+    /** The 1-based `page` of a listing that continues by `page`, whose boundaries move with per_page. */
+    page?: number;
+    /**
+     * `list` checks the 100-author list cap; a `lookup` holds one record and checks the
+     * 5,000-author storage cap.
+     */
+    path: 'list' | 'lookup';
+    records: readonly EntityRecord[];
+}
+/**
+ * Every record of the upstream page, with the windows that disclose OpenAlex's author caps —
+ * or, when that response would run over the ceiling on either surface, its refusal naming the
+ * largest page that fits. Returns new arrays, never the caller's mutated.
+ */
+export declare function buildRecordPage(request: RecordPageRequest): PageOutcome;
+export interface SlicePageRequest extends PageContext {
+    /** Record key of the array to page (a `select` alias already resolved); must hold an array. */
+    field: string;
+    /** Elements to return, already clamped. */
+    limit: number;
+    /** Requested start index; past the end yields an empty, final window. */
+    offset: number;
+    /** The record from a one-field projection: `id`, `display_name`, and `field`. */
+    record: EntityRecord;
+}
+/**
+ * One count-based window of an `id` lookup's array: `limit` elements of `field` from `offset`,
+ * fewer only at the array end, whose `next` repeats `limit` — or, when that response would run
+ * over the ceiling, its refusal naming the largest `slice.limit` that fits.
+ */
+export declare function buildSlicePage(request: SlicePageRequest): PageOutcome;
+export {};
+//# sourceMappingURL=record-page.d.ts.map

package/dist/mcp-server/tools/record-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-page.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/record-page.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/record-page.js

@@ -0,0 +1,392 @@
+/**
+ * @fileoverview Record pages for the tools that return OpenAlex entity records
+ * (`openalex_search_entities`, `openalex_get_citation_graph`). A page holds every record of the
+ * upstream page, and an `id` lookup every selected array whole. `windows` discloses OpenAlex's
+ * author caps — 100 authorships on a list record, 5,000 stored on a singleton — and every
+ * count-based `slice` window, each with the call that continues it. A response whose
+ * `structuredContent` or `content[]` text would exceed 8,000,000 bytes is refused, never
+ * shortened, so both surfaces and the JSON-RPC envelope stay under the 16 MiB an HTTP client
+ * such as Claude Code reads from one response.
+ * @module mcp-server/tools/record-page
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { escapeMarkdown } from './escape-markdown.js';
+import { renderEntityRecord, } from './render-entity-record.js';
+/** Per-surface ceiling: serialized `structuredContent`, and summed `content[]` text. */
+export const RESPONSE_CEILING_BYTES = 8_000_000;
+const CEILING_LABEL = `${RESPONSE_CEILING_BYTES.toLocaleString('en-US')}-byte`;
+/**
+ * The most authorships OpenAlex returns on a list record. An `id` lookup can return more,
+ * up to the separate storage ceiling.
+ */
+const LIST_AUTHORSHIPS_CAP = 100;
+const STORED_AUTHORSHIPS_CAP = 5000;
+const STORAGE_CAP_NOTICE = 'OpenAlex stores at most 5,000 authorships per work in singleton records and snapshots; this author array may omit part of the byline. `total` counts stored entries, not the complete byline. Further OpenAlex fetches or snapshots cannot recover authors beyond this storage ceiling.';
+/** Record arrays the cap applies to: `authorships`, and the `author_list` derived from it. */
+const CAPPED_AUTHOR_FIELDS = ['authorships', 'author_list'];
+/**
+ * Bytes reserved on each surface for the `budget` enrichment field (the OpenAlex usage budget,
+ * not a size limit). The service writes it from OpenAlex's rate-limit headers through
+ * `ctx.enrich`, so its value is not in the handler's hands when the response is measured. The
+ * allowance covers its widest realistic form — every number at full double precision, with a
+ * prepaid balance — measured at 176 bytes as a JSON member and 108 as a trailer line with its
+ * separator.
+ */
+export const BUDGET_FIELD_ALLOWANCE_BYTES = 256;
+const CONTINUATION_TOOL = 'openalex_search_entities';
+const OPENALEX_ID_PREFIX = 'https://openalex.org/';
+const NATIVE_OPENALEX_ID = /^[A-Z]\d+$/;
+/**
+ * The call that continues a window. Its arguments are data to pass back unchanged, so the
+ * schema leaves them loosely typed rather than spelling out the search tool's input a second
+ * time.
+ */
+const continuationCallSchema = z.object({
+    tool: z.literal(CONTINUATION_TOOL).describe('Tool to call.'),
+    arguments: z.object({}).loose().describe('Arguments to pass as-is.'),
+});
+const arrayWindowSchema = z
+    .object({
+    id: z.string().describe('Bare ID of the record.'),
+    field: z.string().describe('Array field.'),
+    offset: z.number().describe('Index of the first element shown.'),
+    shown: z.number().describe('Elements shown.'),
+    total: z
+        .number()
+        .describe('Stored array length returned to this call, not a complete byline total.'),
+    possibly_capped: z
+        .boolean()
+        .describe('True for exactly 100 authorships or author_list entries on a list record, or 5,000 on a singleton lookup: the byline may be longer than the returned array.'),
+    next: continuationCallSchema
+        .nullable()
+        .describe('`id` + `slice` call for the next elements; null at the array end.'),
+})
+    .describe('An array returned in part, or possibly in part.');
+/** Output field: arrays returned in part, or possibly in part, each with its continuation. */
+export const windowsOutputSchema = z
+    .array(arrayWindowSchema)
+    .optional()
+    .describe("Author arrays possibly capped at 100 on a list record or 5,000 stored on a singleton, and the window of every `slice` call — present even when the slice holds the whole array. A slice window's `next` repeats its `slice.limit` from the following offset; `next` is null at the stored-array end, including a possibly capped singleton.");
+const utf8Bytes = (text) => Buffer.byteLength(text, 'utf8');
+const count = (n) => n.toLocaleString('en-US');
+/** `https://openalex.org/W123` → `W123`. Any other form (a keyword URL) passes through whole. */
+export function bareId(id) {
+    const tail = id.startsWith(OPENALEX_ID_PREFIX) ? id.slice(OPENALEX_ID_PREFIX.length) : id;
+    return NATIVE_OPENALEX_ID.test(tail) ? tail : id;
+}
+/** Join notice sentences, dropping empty ones; undefined when none remain. */
+export function joinNotices(parts) {
+    return parts.filter(Boolean).join(' ') || undefined;
+}
+// ---------------------------------------------------------------------------
+// Rendering — shared by both tools' format() and by the ceiling's measurement
+// ---------------------------------------------------------------------------
+/** A continuation call as code spans, which hold any backtick its arguments carry. */
+const renderCall = (call) => `${codeSpan(call.tool)} ${codeSpan(JSON.stringify(call.arguments))}`;
+function renderWindow(window) {
+    const capped = window.possibly_capped
+        ? window.total >= STORED_AUTHORSHIPS_CAP
+            ? ' — possibly capped: OpenAlex stores at most 5,000 authorships per work; total counts stored entries, not the complete byline'
+            : ` — possibly capped: OpenAlex returns at most ${LIST_AUTHORSHIPS_CAP} authorships on a list record`
+        : '';
+    const next = window.next ? `next: ${renderCall(window.next)}` : 'end of array';
+    return `**Window:** ${escapeMarkdown(window.id)} ${codeSpan(window.field)} — offset ${window.offset}, ${window.shown} shown of ${window.total}${capped} — ${next}`;
+}
+/**
+ * Each windowed array's place in its full array, per record ID, so a slice numbers its items
+ * at their real index and its line says how much of the array it shows.
+ */
+function windowViewsByRecord(windows) {
+    const views = new Map();
+    for (const window of windows ?? []) {
+        const fields = views.get(window.id) ?? new Map();
+        fields.set(window.field, { offset: window.offset, total: window.total });
+        views.set(window.id, fields);
+    }
+    return views;
+}
+/**
+ * `format()` for a record page: a count header, each record, then each window.
+ * `noun` names what `meta.count` counts ("result(s)", "edge(s)").
+ */
+export function formatRecordPage(page, noun) {
+    const countLabel = `${page.meta.count} ${noun} — ${page.meta.per_page} per page`;
+    const lines = [
+        page.meta.next_cursor
+            ? `**${countLabel}** — next cursor: \`${page.meta.next_cursor}\``
+            : `**${countLabel}**`,
+    ];
+    const views = windowViewsByRecord(page.windows);
+    for (const record of page.results) {
+        lines.push(...renderEntityRecord(record, views.get(bareId(record.id))));
+    }
+    if (page.windows?.length)
+        lines.push('', ...page.windows.map(renderWindow));
+    return [{ type: 'text', text: lines.join('\n') }];
+}
+// ---------------------------------------------------------------------------
+// Measurement — both surfaces as the framework emits them
+// ---------------------------------------------------------------------------
+/**
+ * Byte-exact copy of the framework's trailer join (`joinTrailerFields` in mcp-ts-core's tool
+ * handler factory, which the package does not export — cyanheads/mcp-ts-core#538). A line opening
+ * a block quote or list item is followed by a blank line instead of a single newline. The
+ * record-page test compares the modelled trailer with the one `runToolContract` renders.
+ */
+const OPENS_LAZY_CONTAINER = /^ {0,3}(?:>|(?:[-+*]|\d{1,9}[.)])(?: |$))/;
+function joinTrailerFields(fields) {
+    let text = '';
+    for (const field of fields) {
+        if (text.length > 0) {
+            text += OPENS_LAZY_CONTAINER.test(text.slice(text.lastIndexOf('\n') + 1)) ? '\n\n' : '\n';
+        }
+        text += field;
+    }
+    return text;
+}
+/**
+ * Byte-exact copy of the framework's inline code span (`codeSpan` in mcp-ts-core's formatting
+ * utils, which the package does not export), the form a one-line trailer string takes: the
+ * fence runs one backtick past the value's longest backtick run, and a space pads each side when
+ * a backtick touches an end or the value both begins and ends with a space. The echo is always
+ * one line — caller text in it is JSON-encoded — so the fenced-block form never applies here.
+ * Authored code spans around one-line values use it too, so a backtick in the value cannot close
+ * the span early.
+ */
+export function codeSpan(value) {
+    let longestRun = 0;
+    for (const [run] of value.matchAll(/`+/g))
+        longestRun = Math.max(longestRun, run.length);
+    const fence = '`'.repeat(longestRun + 1);
+    const pad = value.startsWith('`') ||
+        value.endsWith('`') ||
+        (value.startsWith(' ') && value.endsWith(' ') && /[^ ]/.test(value))
+        ? ' '
+        : '';
+    return `${fence}${pad}${value}${pad}${fence}`;
+}
+/**
+ * The enrichment trailer's bytes, minus the service-written `budget` line. Fields render as the
+ * framework renders them for these tools: `echo` as a code span under its `Query` label,
+ * `totalCount` under `totalLabel`, and `notice` as a block quote with every line quoted, joined
+ * after a leading blank line.
+ */
+export function trailerTextBytes(enrichment) {
+    const fields = [
+        `**Query:** ${codeSpan(enrichment.echo)}`,
+        `**${enrichment.totalLabel}:** ${enrichment.totalCount}`,
+        ...(enrichment.notice === undefined
+            ? []
+            : [
+                enrichment.notice
+                    .split(/\r\n|\r|\n/)
+                    .map((line) => (line === '' ? '>' : `> ${line}`))
+                    .join('\n'),
+            ]),
+    ];
+    return utf8Bytes(`\n\n${joinTrailerFields(fields)}`);
+}
+/**
+ * Both surfaces' bytes for a page as the client receives it: `structuredContent` with the
+ * enrichment the handler writes, `content[]` with the trailer the framework renders, and on
+ * each the allowance for the service's `budget` field.
+ */
+function measurePage(page, noun, enrichment) {
+    const { echo, notice, totalCount } = enrichment;
+    const structured = utf8Bytes(JSON.stringify({ ...page, echo, totalCount, ...(notice !== undefined && { notice }) }));
+    const text = formatRecordPage(page, noun).reduce((sum, block) => sum + utf8Bytes(block.text), 0);
+    return {
+        structured: structured + BUDGET_FIELD_ALLOWANCE_BYTES,
+        text: text + trailerTextBytes(enrichment) + BUDGET_FIELD_ALLOWANCE_BYTES,
+    };
+}
+const withinCeiling = (bytes) => bytes.structured <= RESPONSE_CEILING_BYTES && bytes.text <= RESPONSE_CEILING_BYTES;
+/**
+ * Largest n in [0, limit] with `fits(n)`, given `fits(0)` holds and `fits` stays false once
+ * it turns false. Gallops up from 0 before bisecting, so each probe measures about as many
+ * elements as the answer holds rather than half the array.
+ */
+function largestFitting(limit, fits) {
+    let low = 0;
+    let high = 1;
+    while (high <= limit && fits(high)) {
+        low = high;
+        high *= 2;
+    }
+    high = Math.min(high, limit + 1);
+    while (high - low > 1) {
+        const mid = Math.floor((low + high) / 2);
+        if (fits(mid))
+            low = mid;
+        else
+            high = mid;
+    }
+    return low;
+}
+function arrayWindow(entityType, record, field, view) {
+    const id = bareId(record.id);
+    const end = Math.min(view.offset, view.total) + view.shown;
+    return {
+        id,
+        field,
+        offset: view.offset,
+        shown: view.shown,
+        total: view.total,
+        possibly_capped: view.possiblyCapped,
+        next: end < view.total || view.recoverable
+            ? {
+                tool: CONTINUATION_TOOL,
+                arguments: {
+                    entity_type: entityType,
+                    id,
+                    slice: { field, offset: end, ...(view.limit !== undefined && { limit: view.limit }) },
+                },
+            }
+            : null,
+    };
+}
+/** Author arrays holding exactly the cap for this request path. */
+function cappedAuthorFields(record, cap) {
+    if (cap === undefined)
+        return [];
+    return CAPPED_AUTHOR_FIELDS.filter((field) => {
+        const items = record[field];
+        return Array.isArray(items) && items.length === cap;
+    });
+}
+function capWindow(entityType, record, field) {
+    const total = record[field].length;
+    return arrayWindow(entityType, record, field, {
+        offset: 0,
+        shown: total,
+        total,
+        possiblyCapped: true,
+        recoverable: total === LIST_AUTHORSHIPS_CAP,
+    });
+}
+function capNotice(listCapped, windows) {
+    return joinNotices([
+        listCapped > 0
+            ? `${listCapped} record(s) carry exactly ${LIST_AUTHORSHIPS_CAP} authorships or author_list entries, the most OpenAlex returns on a list record, so the author list may be longer; each such array's \`windows\` entry gives the \`id\` + \`slice\` call for more stored authors, up to the singleton storage ceiling of 5,000.`
+            : undefined,
+        windows.some((window) => window.possibly_capped && window.total >= STORED_AUTHORSHIPS_CAP)
+            ? STORAGE_CAP_NOTICE
+            : undefined,
+    ]);
+}
+function tooLarge(subject, bytes, hint, largest) {
+    return {
+        kind: 'too_large',
+        message: `${subject} would return ${count(bytes.structured)} bytes of structuredContent and ${count(bytes.text)} bytes of content[] text, over the ${CEILING_LABEL} response ceiling.`,
+        data: {
+            structuredBytes: bytes.structured,
+            textBytes: bytes.text,
+            ceilingBytes: RESPONSE_CEILING_BYTES,
+            ...(largest && { largestFitting: largest }),
+            recovery: { hint },
+        },
+    };
+}
+/**
+ * Every record of the upstream page, with the windows that disclose OpenAlex's author caps —
+ * or, when that response would run over the ceiling on either surface, its refusal naming the
+ * largest page that fits. Returns new arrays, never the caller's mutated.
+ */
+export function buildRecordPage(request) {
+    const { continuation, entityType, meta, noun, path, records } = request;
+    const cap = entityType === 'works'
+        ? path === 'list'
+            ? LIST_AUTHORSHIPS_CAP
+            : STORED_AUTHORSHIPS_CAP
+        : undefined;
+    const pageFor = (kept) => {
+        const results = records.slice(0, kept);
+        const capped = results
+            .map((record) => ({ record, fields: cappedAuthorFields(record, cap) }))
+            .filter(({ fields }) => fields.length > 0);
+        const windows = capped.flatMap(({ record, fields }) => fields.map((field) => capWindow(entityType, record, field)));
+        return {
+            page: { meta, results, ...(windows.length > 0 && { windows }) },
+            notice: joinNotices([
+                ...request.notices,
+                capNotice(path === 'list' ? capped.length : 0, windows),
+            ]),
+        };
+    };
+    /**
+     * Each record's bytes on each surface plus the separator joining it to its neighbour: a comma
+     * in `results`, a newline in the rendered text. `format()` renders a page record with no
+     * window note — a cap window shows its whole array — so the bare render is the one it emits.
+     */
+    const sizes = records.map((record) => ({
+        structured: utf8Bytes(JSON.stringify(record)) + 1,
+        text: utf8Bytes(renderEntityRecord(record).join('\n')) + 1,
+    }));
+    const bytesFor = (kept) => {
+        const { page, notice } = pageFor(kept);
+        const frame = measurePage({ ...page, results: [] }, noun, { ...request, notice });
+        // `kept` records carry `kept - 1` commas, not `kept`.
+        const bytes = { structured: frame.structured - (kept > 0 ? 1 : 0), text: frame.text };
+        for (const size of sizes.slice(0, kept)) {
+            bytes.structured += size.structured;
+            bytes.text += size.text;
+        }
+        return bytes;
+    };
+    const bytes = bytesFor(records.length);
+    if (withinCeiling(bytes))
+        return { kind: 'page', ...pageFor(records.length) };
+    const [record] = records;
+    if (path === 'lookup' && record) {
+        const largest = Object.entries(record)
+            .filter((entry) => Array.isArray(entry[1]))
+            .map(([field, items]) => ({ field, items, bytes: utf8Bytes(JSON.stringify(items)) }))
+            .sort((a, b) => b.bytes - a.bytes)[0];
+        return tooLarge(`The record at \`${bareId(record.id)}\``, bytes, largest
+            ? `Narrow \`select\` to the fields you need, or page \`${largest.field}\` (${count(largest.items.length)} elements, its largest array) with \`slice\`.`
+            : 'Narrow `select` to the fields you need.');
+    }
+    const fits = largestFitting(records.length - 1, (kept) => withinCeiling(bytesFor(kept)));
+    const subject = records.length === 1 ? 'This record' : `These ${records.length} records`;
+    if (fits === 0) {
+        return tooLarge(subject, bytes, 'The first record alone exceeds the ceiling. Narrow `select` to the fields you need, or fetch the record by `id` and page its largest array with `slice`.');
+    }
+    // Past page 1, the same `page` at a smaller per_page holds other records, so the named size
+    // holds only from page 1.
+    const page = request.page ?? 1;
+    return tooLarge(subject, bytes, continuation === 'page' && page > 1
+        ? `per_page ${fits} is the most of these records that fit, but page boundaries move with per_page, so \`page: ${page}\` at that size holds other records; walk the listing from page 1 at per_page ${fits}, or narrow \`select\` to the fields you need.`
+        : `Rerun with per_page ${fits}, the most of these records that fit, and continue ${continuation === 'cursor' ? 'from the cursor that page returns' : 'with the next `page`'}; or narrow \`select\` to the fields you need.`, { input: 'per_page', value: fits });
+}
+/**
+ * One count-based window of an `id` lookup's array: `limit` elements of `field` from `offset`,
+ * fewer only at the array end, whose `next` repeats `limit` — or, when that response would run
+ * over the ceiling, its refusal naming the largest `slice.limit` that fits.
+ */
+export function buildSlicePage(request) {
+    const { entityType, field, limit, meta, noun, offset, record } = request;
+    const items = record[field];
+    const total = items.length;
+    const start = Math.min(offset, total);
+    const possiblyCapped = cappedAuthorFields(record, entityType === 'works' ? STORED_AUTHORSHIPS_CAP : undefined).includes(field);
+    const notice = joinNotices([...request.notices, possiblyCapped ? STORAGE_CAP_NOTICE : undefined]);
+    const pageFor = (shown) => ({
+        meta,
+        results: [{ ...record, [field]: items.slice(start, start + shown) }],
+        windows: [
+            arrayWindow(entityType, record, field, { offset, shown, total, possiblyCapped, limit }),
+        ],
+    });
+    const bytesFor = (shown) => measurePage(pageFor(shown), noun, { ...request, notice });
+    const shown = Math.min(limit, total - start);
+    const bytes = bytesFor(shown);
+    if (withinCeiling(bytes))
+        return { kind: 'page', page: pageFor(shown), notice };
+    const fits = largestFitting(shown - 1, (n) => withinCeiling(bytesFor(n)));
+    const subject = `This slice of ${shown} \`${field}\` elements`;
+    if (fits === 0) {
+        return tooLarge(subject, bytes, `The element at offset ${start} alone exceeds the ceiling; continue past it with slice.offset ${start + 1}.`);
+    }
+    return tooLarge(subject, bytes, `Rerun with slice.limit ${fits}, the most of these elements that fit, and continue from the offset its window's \`next\` names.`, { input: 'slice.limit', value: fits });
+}
+//# sourceMappingURL=record-page.js.map

package/dist/mcp-server/tools/record-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-page.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/record-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,EAEL,kBAAkB,GACnB,MAAM,4CAA4C,CAAC;AAGpD,wFAAwF;AACxF,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC;AAChD,MAAM,aAAa,GAAG,GAAG,sBAAsB,CAAC,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC;AAE/E;;;GAGG;AACH,MAAM,oBAAoB,GAAG,GAAG,CAAC;AACjC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AACpC,MAAM,kBAAkB,GACtB,yRAAyR,CAAC;AAE5R,8FAA8F;AAC9F,MAAM,oBAAoB,GAAG,CAAC,aAAa,EAAE,aAAa,CAAU,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD,MAAM,iBAAiB,GAAG,0BAA0B,CAAC;AACrD,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AACnD,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAExC;;;;GAIG;AACH,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC;IAC5D,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;CACrE,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAG,CAAC;KACxB,MAAM,CAAC;IACN,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IACjD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;IAC1C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;IAChE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IAC7C,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,CAAC,yEAAyE,CAAC;IACtF,eAAe,EAAE,CAAC;SACf,OAAO,EAAE;SACT,QAAQ,CACP,6JAA6J,CAC9J;IACH,IAAI,EAAE,sBAAsB;SACzB,QAAQ,EAAE;SACV,QAAQ,CAAC,mEAAmE,CAAC;CACjF,CAAC;KACD,QAAQ,CAAC,iDAAiD,CAAC,CAAC;AAE/D,8FAA8F;AAC9F,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,KAAK,CAAC,iBAAiB,CAAC;KACxB,QAAQ,EAAE;KACV,QAAQ,CACP,6UAA6U,CAC9U,CAAC;AA0BJ,MAAM,SAAS,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC5E,MAAM,KAAK,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;AAE/D,iGAAiG;AACjG,MAAM,UAAU,MAAM,CAAC,EAAU;IAC/B,MAAM,IAAI,GAAG,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1F,OAAO,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AACnD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,WAAW,CAAC,KAAsC;IAChE,OAAO,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC;AACtD,CAAC;AAED,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAE9E,sFAAsF;AACtF,MAAM,UAAU,GAAG,CAAC,IAAsB,EAAU,EAAE,CACpD,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;AAEvE,SAAS,YAAY,CAAC,MAAmB;IACvC,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe;QACnC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,sBAAsB;YACtC,CAAC,CAAC,8HAA8H;YAChI,CAAC,CAAC,gDAAgD,oBAAoB,+BAA+B;QACvG,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC;IAC/E,OAAO,eAAe,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,KAAK,aAAa,MAAM,CAAC,KAAK,GAAG,MAAM,MAAM,IAAI,EAAE,CAAC;AACrK,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB,CAC1B,OAA2C;IAE3C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAwC,CAAC;IAC9D,KAAK,MAAM,MAAM,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,IAAI,GAAG,EAA2B,CAAC;QAC1E,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QACzE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAgB,EAAE,IAAY;IAC7D,MAAM,UAAU,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,WAAW,CAAC;IACjF,MAAM,KAAK,GAAG;QACZ,IAAI,CAAC,IAAI,CAAC,WAAW;YACnB,CAAC,CAAC,KAAK,UAAU,uBAAuB,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI;YACjE,CAAC,CAAC,KAAK,UAAU,IAAI;KACxB,CAAC;IACF,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChD,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC;IAC5E,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACpD,CAAC;AAED,8EAA8E;AAC9E,0DAA0D;AAC1D,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,oBAAoB,GAAG,2CAA2C,CAAC;AAEzE,SAAS,iBAAiB,CAAC,MAAyB;IAClD,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,IAAI,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5F,CAAC;QACD,IAAI,IAAI,KAAK,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzF,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;IACzC,MAAM,GAAG,GACP,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QACrB,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QACnB,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClE,CAAC,CAAC,GAAG;QACL,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,GAAG,KAAK,GAAG,GAAG,GAAG,KAAK,GAAG,GAAG,GAAG,KAAK,EAAE,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAA0B;IACzD,MAAM,MAAM,GAAG;QACb,cAAc,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE;QACzC,KAAK,UAAU,CAAC,UAAU,OAAO,UAAU,CAAC,UAAU,EAAE;QACxD,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,SAAS;YACjC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,UAAU,CAAC,MAAM;qBACd,KAAK,CAAC,YAAY,CAAC;qBACnB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;qBAChD,IAAI,CAAC,IAAI,CAAC;aACd,CAAC;KACP,CAAC;IACF,OAAO,SAAS,CAAC,OAAO,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,IAAgB,EAAE,IAAY,EAAE,UAA0B;IAC7E,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,CAAC;IAChD,MAAM,UAAU,GAAG,SAAS,CAC1B,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CACvF,CAAC;IACF,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IACjG,OAAO;QACL,UAAU,EAAE,UAAU,GAAG,4BAA4B;QACrD,IAAI,EAAE,IAAI,GAAG,gBAAgB,CAAC,UAAU,CAAC,GAAG,4BAA4B;KACzE,CAAC;AACJ,CAAC;AAED,MAAM,aAAa,GAAG,CAAC,KAAmB,EAAW,EAAE,CACrD,KAAK,CAAC,UAAU,IAAI,sBAAsB,IAAI,KAAK,CAAC,IAAI,IAAI,sBAAsB,CAAC;AAErF;;;;GAIG;AACH,SAAS,cAAc,CAAC,KAAa,EAAE,IAA4B;IACjE,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,OAAO,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,GAAG,GAAG,IAAI,CAAC;QACX,IAAI,IAAI,CAAC,CAAC;IACZ,CAAC;IACD,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IACjC,OAAO,IAAI,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACzC,IAAI,IAAI,CAAC,GAAG,CAAC;YAAE,GAAG,GAAG,GAAG,CAAC;;YACpB,IAAI,GAAG,GAAG,CAAC;IAClB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAiBD,SAAS,WAAW,CAClB,UAAsB,EACtB,MAAoB,EACpB,KAAa,EACb,IAAgB;IAEhB,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;IAC3D,OAAO;QACL,EAAE;QACF,KAAK;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,eAAe,EAAE,IAAI,CAAC,cAAc;QACpC,IAAI,EACF,GAAG,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,WAAW;YAClC,CAAC,CAAC;gBACE,IAAI,EAAE,iBAAiB;gBACvB,SAAS,EAAE;oBACT,WAAW,EAAE,UAAU;oBACvB,EAAE;oBACF,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE;iBACtF;aACF;YACH,CAAC,CAAC,IAAI;KACX,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,SAAS,kBAAkB,CAAC,MAAoB,EAAE,GAAuB;IACvE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACjC,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5B,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,CAAC;IACtD,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,SAAS,CAAC,UAAsB,EAAE,MAAoB,EAAE,KAAa;IAC5E,MAAM,KAAK,GAAI,MAAM,CAAC,KAAK,CAAe,CAAC,MAAM,CAAC;IAClD,OAAO,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE;QAC5C,MAAM,EAAE,CAAC;QACT,KAAK,EAAE,KAAK;QACZ,KAAK;QACL,cAAc,EAAE,IAAI;QACpB,WAAW,EAAE,KAAK,KAAK,oBAAoB;KAC5C,CAAC,CAAC;AACL,CAAC;AAED,SAAS,SAAS,CAAC,UAAkB,EAAE,OAA+B;IACpE,OAAO,WAAW,CAAC;QACjB,UAAU,GAAG,CAAC;YACZ,CAAC,CAAC,GAAG,UAAU,4BAA4B,oBAAoB,iQAAiQ;YAChU,CAAC,CAAC,SAAS;QACb,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,eAAe,IAAI,MAAM,CAAC,KAAK,IAAI,sBAAsB,CAAC;YACxF,CAAC,CAAC,kBAAkB;YACpB,CAAC,CAAC,SAAS;KACd,CAAC,CAAC;AACL,CAAC;AAoCD,SAAS,QAAQ,CACf,OAAe,EACf,KAAmB,EACnB,IAAY,EACZ,OAAwC;IAExC,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,GAAG,OAAO,iBAAiB,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,mCAAmC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,sCAAsC,aAAa,oBAAoB;QACtL,IAAI,EAAE;YACJ,eAAe,EAAE,KAAK,CAAC,UAAU;YACjC,SAAS,EAAE,KAAK,CAAC,IAAI;YACrB,YAAY,EAAE,sBAAsB;YACpC,GAAG,CAAC,OAAO,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC;YAC3C,QAAQ,EAAE,EAAE,IAAI,EAAE;SACnB;KACF,CAAC;AACJ,CAAC;AAkBD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAA0B;IACxD,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACxE,MAAM,GAAG,GACP,UAAU,KAAK,OAAO;QACpB,CAAC,CAAC,IAAI,KAAK,MAAM;YACf,CAAC,CAAC,oBAAoB;YACtB,CAAC,CAAC,sBAAsB;QAC1B,CAAC,CAAC,SAAS,CAAC;IAEhB,MAAM,OAAO,GAAG,CAAC,IAAY,EAAoD,EAAE;QACjF,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,OAAO;aACnB,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;aACtE,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CACpD,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAC5D,CAAC;QACF,OAAO;YACL,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE;YAC/D,MAAM,EAAE,WAAW,CAAC;gBAClB,GAAG,OAAO,CAAC,OAAO;gBAClB,SAAS,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC;aACxD,CAAC;SACH,CAAC;IACJ,CAAC,CAAC;IAEF;;;;OAIG;IACH,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACrC,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC;QACjD,IAAI,EAAE,SAAS,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC;KAC3D,CAAC,CAAC,CAAC;IACJ,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAgB,EAAE;QAC9C,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAClF,sDAAsD;QACtD,MAAM,KAAK,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QACtF,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;YACxC,KAAK,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC;YACpC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC;QAC1B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;IAE9E,MAAM,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;IACzB,IAAI,IAAI,KAAK,QAAQ,IAAI,MAAM,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;aACnC,MAAM,CAAC,CAAC,KAAK,EAAgC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;aACxE,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;aACpF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,OAAO,QAAQ,CACb,mBAAmB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EACxC,KAAK,EACL,OAAO;YACL,CAAC,CAAC,uDAAuD,OAAO,CAAC,KAAK,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,+CAA+C;YACvJ,CAAC,CAAC,yCAAyC,CAC9C,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACzF,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,UAAU,CAAC;IACzF,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;QACf,OAAO,QAAQ,CACb,OAAO,EACP,KAAK,EACL,0JAA0J,CAC3J,CAAC;IACJ,CAAC;IACD,4FAA4F;IAC5F,0BAA0B;IAC1B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;IAC/B,OAAO,QAAQ,CACb,OAAO,EACP,KAAK,EACL,YAAY,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC;QACjC,CAAC,CAAC,YAAY,IAAI,8FAA8F,IAAI,iFAAiF,IAAI,gDAAgD;QACzP,CAAC,CAAC,uBAAuB,IAAI,sDAAsD,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,mCAAmC,CAAC,CAAC,CAAC,sBAAsB,gDAAgD,EAC7N,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,CACnC,CAAC;AACJ,CAAC;AAaD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAyB;IACtD,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACzE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAc,CAAC;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;IAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACtC,MAAM,cAAc,GAAG,kBAAkB,CACvC,MAAM,EACN,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,SAAS,CAC5D,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClB,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAElG,MAAM,OAAO,GAAG,CAAC,KAAa,EAAc,EAAE,CAAC,CAAC;QAC9C,IAAI;QACJ,OAAO,EAAE,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC;QACpE,OAAO,EAAE;YACP,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;SACxF;KACF,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAE9F,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhF,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAG,iBAAiB,KAAK,MAAM,KAAK,aAAa,CAAC;IAC/D,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;QACf,OAAO,QAAQ,CACb,OAAO,EACP,KAAK,EACL,yBAAyB,KAAK,kEAAkE,KAAK,GAAG,CAAC,GAAG,CAC7G,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CACb,OAAO,EACP,KAAK,EACL,0BAA0B,IAAI,kGAAkG,EAChI,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,IAAI,EAAE,CACtC,CAAC;AACJ,CAAC"}

package/dist/mcp-server/tools/render-entity-record.d.ts

@@ -17,7 +17,9 @@ export interface ArrayWindowView {
  * Render an OpenAlex entity record as markdown lines: a `### display_name` header,
  * the ID, then each remaining field as a labeled line. Caller joins the lines into
  * the final text block. Provider text is escaped for Markdown; field names are OpenAlex
- * schema keys and render as they are.
+ * schema keys and render as they are. A heading holds one line, so a `display_name` with a
+ * line break heads the record with the ID, as a missing one does, and takes a
+ * `**Display Name:**` line of its own.
  *
  * `windows` maps an array field returned in part to where it sits in the full array: its items
  * are numbered from `offset`, and its line says how many of `total` it shows, so a window never

package/dist/mcp-server/tools/render-entity-record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-entity-record.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/render-entity-record.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAqFjE,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;CACf;AAgCD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GAC7C,MAAM,EAAE,CAWV"}
+{"version":3,"file":"render-entity-record.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/render-entity-record.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAqFjE,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;CACf;AAgCD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GAC7C,MAAM,EAAE,CAaV"}

package/dist/mcp-server/tools/render-entity-record.js

@@ -115,7 +115,9 @@ function renderField(field, value, view) {
  * Render an OpenAlex entity record as markdown lines: a `### display_name` header,
  * the ID, then each remaining field as a labeled line. Caller joins the lines into
  * the final text block. Provider text is escaped for Markdown; field names are OpenAlex
- * schema keys and render as they are.
+ * schema keys and render as they are. A heading holds one line, so a `display_name` with a
+ * line break heads the record with the ID, as a missing one does, and takes a
+ * `**Display Name:**` line of its own.
  *
  * `windows` maps an array field returned in part to where it sits in the full array: its items
  * are numbered from `offset`, and its line says how many of `total` it shows, so a window never
@@ -123,11 +125,14 @@ function renderField(field, value, view) {
  */
 export function renderEntityRecord(record, windows) {
     const { id, display_name, ...rest } = record;
+    const multiLineName = display_name != null && /[\r\n]/.test(display_name);
     const lines = [
         '',
-        `### ${escapeMarkdown(display_name || id, 'heading')}`,
+        `### ${escapeMarkdown((!multiLineName && display_name) || id, 'heading')}`,
         `**ID:** ${escapeMarkdown(id)}`,
     ];
+    if (multiLineName)
+        lines.push(renderField('display_name', display_name, undefined));
     for (const [field, value] of Object.entries(rest)) {
         lines.push(renderField(field, value, windows?.get(field)));
     }