@cyanheads/openalex-mcp-server 0.7.15 → 0.8.0

package/dist/mcp-server/tools/escape-markdown.js

@@ -0,0 +1,389 @@
+/**
+ * @fileoverview Markdown escaping for provider text at the `content[]` boundary. Every `format()`
+ * that interpolates OpenAlex text routes it through `escapeMarkdown`, so the surfaces cannot
+ * drift. Escapes use backslashes, never HTML entities, and cover only what a CommonMark + GFM
+ * renderer would read as structure; a URL that GFM links cleanly renders byte-identical, as the
+ * autolink it is. `structuredContent` never passes through here — it carries the plain text.
+ * @module mcp-server/tools/escape-markdown
+ */
+import { isNamedCharacterReference } from '../../services/openalex/provider-text.js';
+/** Line breaks and tabs would start new blocks or indent code; every position is one line. */
+const LINE_BREAKS = /[\r\n\t]+/g;
+const ASCII_ALPHA = /[A-Za-z]/;
+const ASCII_ALPHANUMERIC = /[A-Za-z\d]/;
+const ASCII_PUNCTUATION = /[!-/:-@[-`{-~]/;
+const WORD_CHARACTER = /[\p{L}\p{N}]/u;
+/** `<` opens raw HTML or a URI autolink only before these. */
+const TAG_START = /[A-Za-z/!?]/;
+/**
+ * The shape of a CommonMark email autolink, whose local part may also open with a digit or a
+ * symbol (`<1@a.co>`); checked only there, so `P<0.05` keeps its `<` unescaped. Looser than the
+ * spec's domain rule, which only costs a spare backslash.
+ */
+const EMAIL_AUTOLINK = /<[\w.!#$%&'*+/=?^`{|}~-]+@[a-zA-Z\d][a-zA-Z\d.-]*>/y;
+/** An ordered-list marker: up to nine digits, `.` or `)`, then a space or the end. */
+const ORDERED_LIST_MARKER = /^\d{1,9}[.)](?: |$)/;
+/** Character references CommonMark decodes; the longest WHATWG name is 31 characters. */
+const NUMERIC_REFERENCE = /&#(?:\d{1,7}|[xX][0-9a-fA-F]{1,6});/y;
+const NAMED_REFERENCE = /&([A-Za-z][A-Za-z0-9]{0,31});/y;
+/*
+ * GFM autolink literals, recognized the way micromark-extension-gfm-autolink-literal does. A
+ * backslash inside a link would become part of its text and href, so the linked span passes
+ * through untouched — which is only safe if the span is exactly what the renderer links.
+ */
+const HTTP_PREFIX = /^https?:\/\//i;
+const WWW_PREFIX = /^www\./i;
+/** Characters GFM trims from the end of an autolink literal. */
+const TRAILING_PUNCTUATION = new Set([
+    '!',
+    '"',
+    "'",
+    ')',
+    '*',
+    ',',
+    '.',
+    ':',
+    ';',
+    '?',
+    '_',
+    '~',
+]);
+/** Path characters at which GFM checks whether everything left is trailing punctuation. */
+const PATH_TRAIL_CANDIDATES = new Set([
+    ...TRAILING_PUNCTUATION,
+    '&',
+    '<',
+    ']',
+]);
+/** Characters a `www.` literal may follow; a protocol literal may follow anything but a letter. */
+const WWW_PREVIOUS = new Set(['(', '*', '_', '[', ']', '~', ' ']);
+/**
+ * Trailing punctuation a link leaves unescaped — escaped, the backslash would join the link. It
+ * is inert when it holds no `&name;` a renderer would decode and no `*`, and any `_` or `~` forms
+ * one run straight after a letter or digit: such a run can close emphasis but never open it, and
+ * no other `_` or `~` in the output is left unescaped to open one. A `*` run could close the
+ * `**` a caller wraps a name in.
+ */
+const INERT_TRAIL = /^(?:_+|~+)?[^*_~&]*$/;
+const WHITESPACE = /\s/;
+/**
+ * For each index, where the trailing punctuation starting there ends — at whitespace, `<`, the
+ * end, or after a `]` that such a character or a `(`/`[` follows — or -1 when a character that
+ * is not trailing punctuation comes first. Built right to left so the scan stays linear.
+ */
+function trailEnds(s) {
+    const ends = new Int32Array(s.length + 1);
+    const alphaEnds = new Int32Array(s.length + 1);
+    ends[s.length] = s.length;
+    alphaEnds[s.length] = s.length;
+    for (let j = s.length - 1; j >= 0; j--) {
+        const c = s[j];
+        alphaEnds[j] = ASCII_ALPHA.test(c) ? alphaEnds[j + 1] : j;
+        if (c === '<' || WHITESPACE.test(c)) {
+            ends[j] = j;
+        }
+        else if (TRAILING_PUNCTUATION.has(c)) {
+            ends[j] = ends[j + 1];
+        }
+        else if (c === ']') {
+            const next = s[j + 1];
+            ends[j] =
+                next === undefined || next === '(' || next === '[' || WHITESPACE.test(next)
+                    ? j + 1
+                    : ends[j + 1];
+        }
+        else if (c === '&') {
+            // A trailing `&name;` belongs to the trail too.
+            const nameEnd = alphaEnds[j + 1];
+            ends[j] = nameEnd > j + 1 && s[nameEnd] === ';' ? ends[nameEnd + 1] : -1;
+        }
+        else {
+            ends[j] = -1;
+        }
+    }
+    return ends;
+}
+/**
+ * End of a valid domain starting at `start`, or -1. Renderers disagree on how non-ASCII
+ * characters classify here, so a domain holding one is treated as one no renderer links.
+ */
+function domainEnd(s, start, trail) {
+    let seen = false;
+    let underscoreInLast = false;
+    let underscoreInLastButOne = false;
+    let j = start;
+    for (; j < s.length; j++) {
+        const c = s[j];
+        if (c.charCodeAt(0) > 127)
+            return -1;
+        if (c === '.' || c === '_') {
+            if (trail[j] !== -1)
+                break;
+            if (c === '_') {
+                underscoreInLast = true;
+            }
+            else {
+                underscoreInLastButOne = underscoreInLast;
+                underscoreInLast = false;
+            }
+        }
+        else if (WHITESPACE.test(c) || (c !== '-' && ASCII_PUNCTUATION.test(c))) {
+            break;
+        }
+        else {
+            seen = true;
+        }
+    }
+    return seen && !underscoreInLast && !underscoreInLastButOne ? j : -1;
+}
+/** End of the path starting at `start`: whitespace, or trailing punctuation to the end. */
+function pathEnd(s, start, trail) {
+    let opened = 0;
+    let closed = 0;
+    for (let j = start; j < s.length; j++) {
+        const c = s[j];
+        if (c === '(') {
+            opened++;
+        }
+        else if (c === ')' && closed < opened) {
+            closed++;
+        }
+        else if (PATH_TRAIL_CANDIDATES.has(c)) {
+            if (trail[j] !== -1)
+                return j;
+            if (c === ')')
+                closed++;
+        }
+        else if (WHITESPACE.test(c)) {
+            return j;
+        }
+    }
+    return s.length;
+}
+/**
+ * Where a GFM autolink literal could begin at `i`: the index of the `:` or `.` whose escape
+ * keeps it from linking, or -1 when no literal can start here.
+ */
+function autolinkPrefixIndex(s, i) {
+    const previous = s[i - 1];
+    const rest = s.slice(i, i + 8);
+    if (HTTP_PREFIX.test(rest) && (previous === undefined || !ASCII_ALPHA.test(previous))) {
+        return rest.indexOf(':') + i;
+    }
+    if (WWW_PREFIX.test(rest) &&
+        s.length > i + 4 &&
+        (previous === undefined || WWW_PREVIOUS.has(previous))) {
+        return i + 3;
+    }
+    return -1;
+}
+/**
+ * A GFM email literal: it starts where an atext run does and must end on a letter. GFM matches
+ * one before a `www.` literal at the same `w`, and its domain can run on into `http`
+ * (`a@b.co-https://…`), so a prefix inside one never starts a link of its own.
+ */
+const EMAIL_LITERAL = /(?<![\w+./-])[\w+.-]+@[\w-]*(?:\.[A-Za-z\d][\w-]*)+/g;
+/** `[start, end)` spans GFM would link as email literals. */
+function emailLiteralSpans(s) {
+    if (!s.includes('@'))
+        return [];
+    const spans = [];
+    for (const email of s.matchAll(EMAIL_LITERAL)) {
+        if (ASCII_ALPHA.test(email[0].at(-1))) {
+            spans.push([email.index, email.index + email[0].length]);
+        }
+    }
+    return spans;
+}
+/** End of the autolink literal whose prefix is at `i`, or -1 when the renderer would not link. */
+function autolinkEnd(s, i, prefix, trail) {
+    // A `www.` literal's domain starts at the `w`; a protocol's after `//`, on neither a control
+    // character nor punctuation — not even the `-` a domain may hold later.
+    let domainStart = i;
+    if (s[prefix] === ':') {
+        domainStart = prefix + 3;
+        const first = s[domainStart] ?? '';
+        const code = first.charCodeAt(0);
+        if (code < 32 || code === 127 || ASCII_PUNCTUATION.test(first))
+            return -1;
+    }
+    const domain = domainEnd(s, domainStart, trail);
+    return domain === -1 ? -1 : pathEnd(s, domain, trail);
+}
+/**
+ * Indices of the `[` characters to escape: those ahead of a `](` pair, where a link needs the
+ * `[` to open its label, the one a line starts with, and any the text never closes. Left open, a
+ * `[` stays an unbalanced label across everything interpolated after it on the line, and GFM
+ * links no URL inside an unbalanced label.
+ */
+function escapedBrackets(s, blockMarker) {
+    const lastLinkClose = s.lastIndexOf('](');
+    const escaped = new Set();
+    const open = [];
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === '[') {
+            if (i < lastLinkClose || i === blockMarker)
+                escaped.add(i);
+            else
+                open.push(i);
+        }
+        else if (s[i] === ']') {
+            open.pop();
+        }
+    }
+    for (const i of open)
+        escaped.add(i);
+    return escaped;
+}
+/** Whether the `<` at `index` opens raw HTML or an autolink. */
+function opensTagOrAutolink(text, index) {
+    if (TAG_START.test(text[index + 1] ?? ''))
+        return true;
+    EMAIL_AUTOLINK.lastIndex = index;
+    return EMAIL_AUTOLINK.test(text);
+}
+/** Whether the `&` at `index` starts a reference a Markdown renderer would decode. */
+function startsCharacterReference(text, index) {
+    NUMERIC_REFERENCE.lastIndex = index;
+    if (NUMERIC_REFERENCE.test(text))
+        return true;
+    NAMED_REFERENCE.lastIndex = index;
+    const named = NAMED_REFERENCE.exec(text);
+    return named !== null && isNamedCharacterReference(named[1]);
+}
+/**
+ * Index of the `#` that would open an ATX closing sequence — a trailing run of `#` preceded by a
+ * space or standing alone — or -1 when the text has none.
+ */
+function closingHashIndex(text) {
+    const end = text.trimEnd().length;
+    let start = end;
+    while (start > 0 && text[start - 1] === '#')
+        start--;
+    if (start === end)
+        return -1;
+    return start === 0 || text[start - 1] === ' ' ? start : -1;
+}
+/** Index of the character to escape so the text cannot open a block at the start of a line. */
+function blockMarkerIndex(text) {
+    const first = text[0];
+    if (first === '#' || first === '>' || first === '[')
+        return 0;
+    if ((first === '-' || first === '+') && (text.length === 1 || text[1] === ' '))
+        return 0;
+    const ordered = ORDERED_LIST_MARKER.exec(text);
+    return ordered ? ordered[0].trimEnd().length - 1 : -1;
+}
+/**
+ * Escape provider text for Markdown so a renderer shows exactly the characters it holds.
+ *
+ * Escaped everywhere: `*`, backticks, `~` (GFM strikethrough), `<` before a letter, `/`, `!`, or
+ * `?`, `_` unless it sits between two letters or digits, `&` when it starts a character reference
+ * a renderer would decode, a backslash before punctuation or at the end, a `<` that opens an
+ * email autolink, and any `[` ahead of a `](` pair (a link needs it to open its label) or never
+ * closed. Closed citation brackets with no `](` after them stay as they are. At a line start,
+ * also the block markers; in a heading, a trailing `#` run. Line breaks and tabs collapse to a
+ * space.
+ *
+ * A span GFM links as an autolink literal passes through untouched. When it cannot — trailing
+ * punctuation that needs an escape would join the link, an open `[` or an email literal holds
+ * it, or GFM would not link it at all — the `:` or `.` of its prefix is escaped instead, which
+ * reads the same but links nothing in any renderer, and the span is escaped like any other text.
+ */
+export function escapeMarkdown(text, position = 'inline') {
+    let s = text.replace(LINE_BREAKS, ' ');
+    if (position === 'line-start')
+        s = s.trimStart();
+    const blockMarker = position === 'line-start' ? blockMarkerIndex(s) : -1;
+    const closingHash = position === 'heading' ? closingHashIndex(s) : -1;
+    const brackets = escapedBrackets(s, blockMarker);
+    let trail;
+    let emails;
+    let nextEmail = 0;
+    let openBrackets = 0;
+    /**
+     * Whether the autolink literal ending at `end`, with its trailing punctuation up to `trailEnd`,
+     * renders as exactly those characters: no open `[` before it, inert trailing punctuation, and
+     * no escape needed on the character past it, whose backslash would join the link.
+     */
+    const linksCleanly = (end, trailEnd) => {
+        if (openBrackets > 0)
+            return false;
+        const trailing = s.slice(end, trailEnd);
+        if (!INERT_TRAIL.test(trailing))
+            return false;
+        if (/^[_~]/.test(trailing) && !ASCII_ALPHANUMERIC.test(s[end - 1]))
+            return false;
+        const after = s[trailEnd];
+        if (after === '<')
+            return !opensTagOrAutolink(s, trailEnd);
+        return after !== '[' || !brackets.has(trailEnd);
+    };
+    // Unescaped runs are copied as slices; `copied` marks where the pending run begins.
+    const parts = [];
+    let copied = 0;
+    let prefixToEscape = -1;
+    // Autolink prefixes before this index sit inside a span that could not link as a whole.
+    let unlinkedUntil = -1;
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        const next = s[i + 1];
+        if (ch === 'h' || ch === 'H' || ch === 'w' || ch === 'W') {
+            const prefix = autolinkPrefixIndex(s, i);
+            if (prefix !== -1) {
+                trail ??= trailEnds(s);
+                emails ??= emailLiteralSpans(s);
+                while ((emails[nextEmail]?.[1] ?? Number.POSITIVE_INFINITY) <= i)
+                    nextEmail++;
+                const inEmail = (emails[nextEmail]?.[0] ?? Number.POSITIVE_INFINITY) <= i;
+                const end = i < unlinkedUntil || inEmail ? -1 : autolinkEnd(s, i, prefix, trail);
+                // The link and its inert trailing punctuation pass through as they are.
+                if (end !== -1 && linksCleanly(end, trail[end])) {
+                    i = trail[end] - 1;
+                    continue;
+                }
+                prefixToEscape = prefix;
+                unlinkedUntil = Math.max(unlinkedUntil, end);
+            }
+        }
+        let needsEscape;
+        switch (ch) {
+            case '*':
+            case '`':
+            case '~':
+                needsEscape = true;
+                break;
+            case '_':
+                needsEscape = !(WORD_CHARACTER.test(s[i - 1] ?? '') && WORD_CHARACTER.test(next ?? ''));
+                break;
+            case '\\':
+                needsEscape = next === undefined || ASCII_PUNCTUATION.test(next);
+                break;
+            case '<':
+                needsEscape = opensTagOrAutolink(s, i);
+                break;
+            case '[':
+                needsEscape = brackets.has(i);
+                if (!needsEscape)
+                    openBrackets++;
+                break;
+            case ']':
+                needsEscape = false;
+                if (openBrackets > 0)
+                    openBrackets--;
+                break;
+            case '&':
+                needsEscape = startsCharacterReference(s, i);
+                break;
+            default:
+                needsEscape = i === blockMarker || i === closingHash || i === prefixToEscape;
+        }
+        if (needsEscape) {
+            parts.push(s.slice(copied, i), '\\');
+            copied = i;
+        }
+    }
+    parts.push(s.slice(copied));
+    return parts.join('');
+}
+//# sourceMappingURL=escape-markdown.js.map

package/dist/mcp-server/tools/escape-markdown.js.map

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

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

@@ -6,10 +6,22 @@
  * @module mcp-server/tools/render-entity-record
  */
 import type { EntityRecord } from '../../services/openalex/types.js';
+/** Where an array returned in part sits in the full array. */
+export interface ArrayWindowView {
+    /** Index in the full array of the first element shown. */
+    offset: number;
+    /** Elements in the full array. */
+    total: number;
+}
 /**
  * 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.
+ * the final text block. Provider text is escaped for Markdown; field names are OpenAlex
+ * schema keys and render as they are.
+ *
+ * `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
+ * reads as a complete or empty array.
  */
-export declare function renderEntityRecord(record: EntityRecord): string[];
+export declare function renderEntityRecord(record: EntityRecord, windows?: ReadonlyMap<string, ArrayWindowView>): string[];
 //# sourceMappingURL=render-entity-record.d.ts.map

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;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AA4FjE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,CAOjE"}
+{"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"}

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

@@ -5,6 +5,7 @@
  * "label: value" lines that mirror `structuredContent` field-for-field.
  * @module mcp-server/tools/render-entity-record
  */
+import { escapeMarkdown } from './escape-markdown.js';
 const ACRONYMS = new Set([
     'apc',
     'doi',
@@ -36,6 +37,17 @@ function isScalarOrNull(value) {
 function isPlainObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+/**
+ * A scalar leaf as Markdown. Strings are provider text and go through `escapeMarkdown`; numbers
+ * and booleans carry no syntax. Every leaf lands mid-line — after a label, a path, or a list
+ * marker — so the inline position applies.
+ */
+function renderScalar(value) {
+    return typeof value === 'string' ? escapeMarkdown(value) : String(value);
+}
+function renderScalarList(values) {
+    return values.map((item) => (item === null ? '—' : renderScalar(item))).join(', ');
+}
 /**
  * Flatten a value to "path: value" strings, one per scalar leaf. Nested objects use dot
  * notation (`subfield.display_name`); arrays of scalars collapse to a single comma-joined
@@ -47,12 +59,12 @@ function flattenLeaves(value, prefix = '') {
     if (value === null || value === undefined)
         return prefix ? [`${prefix}: —`] : [];
     if (isScalar(value))
-        return [prefix ? `${prefix}: ${String(value)}` : String(value)];
+        return [prefix ? `${prefix}: ${renderScalar(value)}` : renderScalar(value)];
     if (Array.isArray(value)) {
         if (value.length === 0)
             return [`${prefix || 'value'}: (empty)`];
         if (value.every(isScalarOrNull)) {
-            const joined = value.map((item) => (item === null ? '—' : String(item))).join(', ');
+            const joined = renderScalarList(value);
             return [prefix ? `${prefix}: ${joined}` : joined];
         }
         return value.flatMap((item, i) => flattenLeaves(item, `${prefix}[${i}]`));
@@ -68,22 +80,32 @@ function flattenLeaves(value, prefix = '') {
 function compactPairs(value) {
     return flattenLeaves(value).join(', ');
 }
-function renderField(field, value) {
+const count = (n) => n.toLocaleString('en-US');
+/** The note a partly shown array carries on its label line; undefined when it shows every element. */
+function windowNote(shown, view) {
+    if (!view || shown >= view.total)
+        return;
+    const from = view.offset > 0 ? ` from offset ${count(view.offset)}` : '';
+    return `(${count(shown)} of ${count(view.total)} shown${from} — windowed; see Window)`;
+}
+function renderField(field, value, view) {
     const label = toFieldLabel(field);
     if (value == null)
         return `**${label}:** —`;
     if (isScalar(value))
-        return `**${label}:** ${String(value)}`;
+        return `**${label}:** ${renderScalar(value)}`;
     if (Array.isArray(value)) {
+        const note = windowNote(value.length, view);
+        const head = note ? `**${label}:** ${note}` : `**${label}:**`;
         if (value.length === 0)
-            return `**${label}:** (empty)`;
-        if (value.every(isScalarOrNull)) {
-            return `**${label}:** ${value.map((item) => (item === null ? '—' : String(item))).join(', ')}`;
-        }
+            return note ? head : `**${label}:** (empty)`;
+        if (value.every(isScalarOrNull))
+            return `${head} ${renderScalarList(value)}`;
+        const first = view?.offset ?? 0;
         const items = value.map((item, i) => isPlainObject(item)
-            ? `- [${i}] ${compactPairs(item)}`
-            : `- [${i}] ${flattenLeaves(item).join(', ') || '—'}`);
-        return `**${label}:**\n${items.join('\n')}`;
+            ? `- [${first + i}] ${compactPairs(item)}`
+            : `- [${first + i}] ${flattenLeaves(item).join(', ') || '—'}`);
+        return `${head}\n${items.join('\n')}`;
     }
     if (isPlainObject(value))
         return `**${label}:** ${compactPairs(value)}`;
@@ -92,13 +114,22 @@ function renderField(field, value) {
 /**
  * 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.
+ * the final text block. Provider text is escaped for Markdown; field names are OpenAlex
+ * schema keys and render as they are.
+ *
+ * `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
+ * reads as a complete or empty array.
  */
-export function renderEntityRecord(record) {
+export function renderEntityRecord(record, windows) {
     const { id, display_name, ...rest } = record;
-    const lines = ['', `### ${display_name || id}`, `**ID:** ${id}`];
+    const lines = [
+        '',
+        `### ${escapeMarkdown(display_name || id, 'heading')}`,
+        `**ID:** ${escapeMarkdown(id)}`,
+    ];
     for (const [field, value] of Object.entries(rest)) {
-        lines.push(renderField(field, value));
+        lines.push(renderField(field, value, windows?.get(field)));
     }
     return lines;
 }

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

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