@dokebi/mcp 0.0.0-stage → 0.1.1

package/dist/calls.d.ts

@@ -0,0 +1,36 @@
+import type { Logger } from '@dokebi/core';
+import type { FastifyRequest } from 'fastify';
+import type { McpCallEntry, McpHookContext, McpHooks } from './extension.js';
+/** What the reporter has done so far (`McpApi.callStats()`). */
+export interface McpCallStats {
+    /** Entries handed to `onCall` (a throw counts too). */
+    readonly delivered: number;
+    /** Promises returned by `onCall` that have not settled yet. */
+    readonly pending: number;
+    /** Throws and rejections of `onCall` (each logged at warn, MCP_ON_CALL_FAILED). */
+    readonly failed: number;
+    /** Entries dropped because `onCallMaxPending` promises were pending (MCP_ON_CALL_DROPPED). */
+    readonly dropped: number;
+}
+export interface CallReporterSettings {
+    readonly hooks: McpHooks;
+    readonly logger: Logger;
+    readonly hookContext: Pick<McpHookContext, 'app' | 'getDependency' | 'logger'>;
+    /** Aborted when the app stops (the hook's `context.signal`); absent: never aborted. */
+    readonly appSignal: AbortSignal | undefined;
+    /** `onCallMaxPending`. */
+    readonly maxPending: number;
+    /** Window of the repeated warn lines (`logRepeatWindowMs`). */
+    readonly logRepeatWindowMs: number;
+}
+export declare class McpCallReporter {
+    #private;
+    constructor(settings: CallReporterSettings);
+    stats(): McpCallStats;
+    /** The entries of one answered request: delivered one setImmediate later, in their order. */
+    later(entries: readonly McpCallEntry[], request: FastifyRequest | undefined): void;
+    /** Hands each entry to `onCall` once (the route calls `later`; tests may call this). */
+    deliver(entries: readonly McpCallEntry[], request: FastifyRequest | undefined): void;
+    /** At stop: the counted repeats, and a warn when hook promises are still pending. */
+    close(): void;
+}

package/dist/calls.js

@@ -0,0 +1,103 @@
+import { diagnostics } from '@dokebi/core/libraries';
+const never = new AbortController().signal;
+function thenable(value) {
+    return (value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
+export class McpCallReporter {
+    #s;
+    #repeats;
+    #delivered = 0;
+    #pending = 0;
+    #failed = 0;
+    #dropped = 0;
+    constructor(settings) {
+        this.#s = settings;
+        this.#repeats = new diagnostics.Repeats({
+            logger: settings.logger,
+            intervalMs: settings.logRepeatWindowMs,
+        });
+    }
+    stats() {
+        return Object.freeze({
+            delivered: this.#delivered,
+            pending: this.#pending,
+            failed: this.#failed,
+            dropped: this.#dropped,
+        });
+    }
+    /** The entries of one answered request: delivered one setImmediate later, in their order. */
+    later(entries, request) {
+        if (entries.length === 0)
+            return;
+        setImmediate(() => this.deliver(entries, request));
+    }
+    /** Hands each entry to `onCall` once (the route calls `later`; tests may call this). */
+    deliver(entries, request) {
+        const context = Object.freeze({
+            ...this.#s.hookContext,
+            signal: this.#s.appSignal ?? never,
+            request,
+        });
+        for (const entry of entries)
+            this.#one(entry, context);
+    }
+    #one(entry, context) {
+        if (this.#pending >= this.#s.maxPending) {
+            this.#dropped++;
+            this.#repeats.log('warn', 'MCP onCall entry dropped', 'MCP_ON_CALL_DROPPED', undefined, {
+                method: entry.method,
+                name: entry.name,
+                grant: entry.grant,
+                result: entry.result,
+                pending: this.#pending,
+                maxPending: this.#s.maxPending,
+                dropped: this.#dropped,
+                fix: 'onCall returns promises faster than they settle: make it cheaper (batch the writes) or raise options.dokebi-mcp.onCallMaxPending.',
+            }, 'dropped');
+            return;
+        }
+        this.#delivered++;
+        let returned;
+        try {
+            returned = this.#s.hooks.onCall(entry, context);
+        }
+        catch (error) {
+            this.#failure(error, entry, 'threw');
+            return;
+        }
+        if (!thenable(returned))
+            return;
+        this.#pending++;
+        Promise.resolve(returned).then(() => {
+            this.#pending--;
+        }, (error) => {
+            this.#pending--;
+            this.#failure(error, entry, 'rejected');
+        });
+    }
+    #failure(error, entry, how) {
+        this.#failed++;
+        this.#repeats.log('warn', 'MCP onCall hook failed', 'MCP_ON_CALL_FAILED', error, {
+            hook: 'onCall',
+            how,
+            method: entry.method,
+            name: entry.name,
+            grant: entry.grant,
+            result: entry.result,
+            failed: this.#failed,
+        }, `${entry.method} ${entry.name}`);
+    }
+    /** At stop: the counted repeats, and a warn when hook promises are still pending. */
+    close() {
+        this.#repeats.flush();
+        if (this.#pending > 0)
+            this.#s.logger.log('warn', 'MCP onCall promises still pending at stop', {
+                code: 'MCP_ON_CALL_PENDING',
+                pending: this.#pending,
+                fix: 'onCall is not awaited at stop: listen to context.signal (aborted at stop) to finish or give up a write.',
+            });
+        diagnostics.logDebug(this.#s.logger, 'MCP onCall closed', () => ({ ...this.stats() }));
+    }
+}

package/dist/dependency.d.ts

@@ -0,0 +1,4 @@
+import type { McpApi } from './plugin.js';
+export declare const provider: import("@dokebi/core").ProviderDescriptor<McpApi>;
+/** Required: created from @dokebi/mcp when no `dokebi-mcp` plugin is registered. */
+export declare const dependency: import("@dokebi/core").PluginDependency<McpApi>;

package/dist/dependency.js

@@ -0,0 +1,14 @@
+import { defineProvider } from '@dokebi/core';
+/*
+ * The one place dokebi-mcp states its name, package and range (D-0063 §6). A plugin that needs
+ * the MCP plugin's API imports `dependency` from '@dokebi/mcp/dependency' (a small module: it
+ * loads nothing else). Contributing tools needs no dependency: declare the point instead.
+ */
+export const provider = defineProvider({
+    name: 'dokebi-mcp',
+    version: '^0.1.0',
+    packageName: '@dokebi/mcp',
+    load: () => import('./index.js'),
+});
+/** Required: created from @dokebi/mcp when no `dokebi-mcp` plugin is registered. */
+export const dependency = provider.dependency;

package/dist/envelope.d.ts

@@ -0,0 +1,124 @@
+/** Who wrote a piece of stored content. */
+export type McpWrittenBy = 'human' | 'ai' | 'tool';
+/** Where a piece of stored content comes from. */
+export interface McpSource {
+    /** What it is, in the application's words (`document`, `note`, `item`). 1-64 characters. */
+    readonly kind: string;
+    readonly id: string | number;
+    /** A human-facing code of the record (`DOC-12`), or null. */
+    readonly code?: string | null;
+    readonly written_by: McpWrittenBy;
+    /** True for text from outside the application's users (an imported page, a guest's report). */
+    readonly outside: boolean;
+}
+/** One piece of stored content. `data` is any JSON value. */
+export interface McpContentItem {
+    readonly data: unknown;
+    readonly source: McpSource;
+}
+/** A step only a person can take: the place on the screen and the button, as they read there. */
+export interface McpHumanTurn {
+    readonly where: string;
+    readonly button: string;
+}
+/** A value hidden before the answer left (`transformResult`). */
+export interface McpMasked {
+    /** Where in the envelope (`content[3].data.token`). */
+    readonly path: string;
+    readonly reason: string;
+}
+/** The image types a result may carry (D-0143): what MCP clients show a model. */
+export type McpImageMimeType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+/** The image types a result may carry, in the order of `McpImageMimeType`. */
+export declare const IMAGE_MIME_TYPES: readonly McpImageMimeType[];
+/**
+ * One picture for `envelope({ images })` (D-0143). Send a reduced copy (a @dokebi/image thumbnail,
+ * a storage variant), not the original: every byte travels as base64 to the model.
+ */
+export interface McpImageInput {
+    /** The bytes (a Uint8Array or Buffer, not copied: do not change them afterwards), or base64. */
+    readonly data: Uint8Array | string;
+    /** The type the bytes must be (checked from their first bytes, never trusted). */
+    readonly mimeType: McpImageMimeType;
+    /** What the picture shows, in words (1-1000 characters): for the model and text-only clients. */
+    readonly alt?: string;
+    /** Where the picture comes from: an upload is stored content like `content` items. */
+    readonly source?: McpSource;
+}
+/**
+ * The placeholder of a picture in an envelope (D-0143): what `structuredContent`, the text block,
+ * `transformResult` and `onCall` see. Never the bytes.
+ */
+export interface McpImage {
+    /** Its place among the result's images; its content block is `content[index + 1]`. */
+    readonly index: number;
+    readonly mimeType: McpImageMimeType;
+    /** The size of the picture in bytes (its base64 is about 4/3 of it). */
+    readonly bytes: number;
+    readonly alt?: string;
+    readonly source?: McpSource;
+}
+/** What `envelope()` takes. */
+export interface McpEnvelopeInput {
+    readonly content?: readonly McpContentItem[];
+    readonly note?: string;
+    readonly next?: string | readonly string[];
+    readonly human_turns?: readonly McpHumanTurn[];
+    readonly masked?: readonly McpMasked[];
+    readonly next_cursor?: string | null;
+    /**
+     * Other values the server computed (ids, counts, codes, a list of skipped rows), merged at the
+     * top level. Never stored text: that belongs in `content`. The envelope's own names are refused.
+     */
+    readonly fields?: Readonly<Record<string, unknown>>;
+    /**
+     * Pictures the model sees (D-0143): new ones (`{ data, mimeType, alt?, source? }`) or
+     * placeholders of `result.images` (in `amend`, to keep, reorder or drop some). At most
+     * `maxImages` per result, `imageMaxBytes` each and `imageTotalMaxBytes` in all (the route checks).
+     */
+    readonly images?: readonly (McpImageInput | McpImage)[];
+}
+/** A tool result made by `envelope()`: frozen, the only thing `handle` may return. */
+export interface McpEnvelope {
+    readonly content: readonly McpContentItem[];
+    readonly note?: string;
+    readonly next?: string | readonly string[];
+    readonly human_turns?: readonly McpHumanTurn[];
+    readonly masked: readonly McpMasked[];
+    readonly next_cursor?: string | null;
+    /** The placeholders of the result's pictures (D-0143); absent when there are none. */
+    readonly images?: readonly McpImage[];
+    readonly [field: string]: unknown;
+}
+/** One `{ data, source }` checked (the source in full; data is any JSON value). */
+export declare function item(data: unknown, source: McpSource): McpContentItem;
+/** The result envelope (see the top of this file). Throws INVALID_ARGUMENT on a wrong shape. */
+export declare function envelope(input?: McpEnvelopeInput): McpEnvelope;
+/**
+ * A changed copy of an envelope (for `transformResult`): `changes` replace the envelope's own
+ * slots (`content`, `note`, `next`, `human_turns`, `masked`, `next_cursor`, `images`) and add
+ * `fields`; the other fields of `result` stay. Its pictures stay unless `images` is given:
+ * `images: []` drops them, `images: result.images.filter(…)` keeps some (D-0143).
+ */
+export declare function amend(result: McpEnvelope, changes: McpEnvelopeInput): McpEnvelope;
+/** The bytes of a placeholder `envelope()` made (the route's, never exported to applications). */
+export declare function imageBytes(image: McpImage): Uint8Array | undefined;
+/** Whether `value` was made by `envelope()`. */
+export declare function isEnvelope(value: unknown): value is McpEnvelope;
+/** What `page()` returns: pass both to `envelope()`. */
+export interface McpPage {
+    readonly content: readonly McpContentItem[];
+    readonly next_cursor: string | null;
+}
+/** The default page size in characters (below the default `resultMaxChars` of 60,000). */
+export declare const PAGE_MAX_CHARS = 50000;
+/**
+ * One page of `items` that fits `maxChars` (the JSON of the items), from `cursor` on, with the
+ * cursor of the next page (null at the end). The cursor is an offset: for a list that changes
+ * between calls, page with a key of your own and pass it as `next_cursor`. A first item larger
+ * than `maxChars` is returned alone (the result size check may then refuse it).
+ */
+export declare function page(items: readonly McpContentItem[], settings?: {
+    readonly cursor?: string | undefined;
+    readonly maxChars?: number;
+}): McpPage;

package/dist/envelope.js

@@ -0,0 +1,299 @@
+import { media } from '@dokebi/core/libraries';
+import { McpError } from './errors.js';
+/** The image types a result may carry, in the order of `McpImageMimeType`. */
+export const IMAGE_MIME_TYPES = Object.freeze([
+    'image/png',
+    'image/jpeg',
+    'image/webp',
+    'image/gif',
+]);
+const RESERVED = new Set([
+    'content',
+    'note',
+    'next',
+    'human_turns',
+    'masked',
+    'next_cursor',
+    'fields',
+    'images',
+    // The error shape (code, message, hint, data) and the limit answer: a success never looks like one.
+    'code',
+    'message',
+    'hint',
+    'retry_after',
+    // Would set the prototype instead of a field: refused, never dropped silently.
+    '__proto__',
+]);
+const WRITTEN_BY = new Set(['human', 'ai', 'tool']);
+const KIND = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/;
+const FIELD = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const MADE = new WeakSet();
+/** The bytes of each placeholder `envelope()` made (D-0143): kept out of the envelope itself. */
+const BYTES = new WeakMap();
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+const MIME = new Set(IMAGE_MIME_TYPES);
+function invalid(message, fix) {
+    return new McpError('INVALID_ARGUMENT', message, { fix });
+}
+function plain(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function text(value, where, max) {
+    if (typeof value !== 'string' || value === '' || value.length > max)
+        throw invalid(`${where} must be a non-empty string of at most ${max} characters`, `Pass a string to ${where}.`);
+    return value;
+}
+/** One `{ data, source }` checked (the source in full; data is any JSON value). */
+export function item(data, source) {
+    if (data === undefined || typeof data === 'function' || typeof data === 'bigint')
+        throw invalid('item data must be a JSON value', 'Pass the stored value (text, an object) as data.');
+    if (!plain(source))
+        throw invalid('item source must be { kind, id, written_by, outside }', 'Describe where the data comes from.');
+    if (typeof source.kind !== 'string' || !KIND.test(source.kind))
+        throw invalid('source.kind must be 1-64 letters, digits, _, ., : or - (starting with a letter or digit)', "Name what the data is, for example 'note'.");
+    if (!(typeof source.id === 'string' ? source.id !== '' : Number.isFinite(source.id)))
+        throw invalid('source.id must be a non-empty string or a number', 'Pass the record id.');
+    if (source.code !== undefined && source.code !== null && typeof source.code !== 'string')
+        throw invalid('source.code must be a string or null', 'Pass the record code or leave it out.');
+    if (!WRITTEN_BY.has(source.written_by))
+        throw invalid("source.written_by must be 'human', 'ai' or 'tool'", 'Say who wrote the data.');
+    if (typeof source.outside !== 'boolean')
+        throw invalid('source.outside must be a boolean', 'true for text from outside the users of the app.');
+    return Object.freeze({
+        data,
+        source: Object.freeze({
+            kind: source.kind,
+            id: source.id,
+            ...(source.code === undefined ? {} : { code: source.code }),
+            written_by: source.written_by,
+            outside: source.outside,
+        }),
+    });
+}
+/** The result envelope (see the top of this file). Throws INVALID_ARGUMENT on a wrong shape. */
+export function envelope(input = {}) {
+    if (!plain(input))
+        throw invalid('envelope() takes { content, note, next, … }', 'Pass an object to envelope().');
+    for (const key of Object.keys(input))
+        if (![
+            'content',
+            'note',
+            'next',
+            'human_turns',
+            'masked',
+            'next_cursor',
+            'fields',
+            'images',
+        ].includes(key))
+            throw invalid(`envelope() has no ${key}`, 'Put stored text in content (item(data, source)) and other computed values in fields.');
+    const content = input.content ?? [];
+    if (!Array.isArray(content))
+        throw invalid('envelope content must be a list of { data, source }', 'Use item(data, source).');
+    const result = {
+        content: Object.freeze(content.map((one) => {
+            if (!plain(one))
+                throw invalid('a content entry must be { data, source }', 'Use item(data, source).');
+            return item(one.data, one.source);
+        })),
+    };
+    if (input.note !== undefined)
+        result.note = text(input.note, 'note', 4_096);
+    if (input.next !== undefined) {
+        const next = input.next;
+        result.next = Array.isArray(next)
+            ? Object.freeze(next.map((one, index) => text(one, `next[${index}]`, 1_024)))
+            : text(next, 'next', 1_024);
+    }
+    if (input.human_turns !== undefined) {
+        if (!Array.isArray(input.human_turns))
+            throw invalid('human_turns must be a list of { where, button }', 'Name the place and the button.');
+        result.human_turns = Object.freeze(input.human_turns.map((turn, index) => Object.freeze({
+            where: text(plain(turn) ? turn.where : undefined, `human_turns[${index}].where`, 200),
+            button: text(plain(turn) ? turn.button : undefined, `human_turns[${index}].button`, 200),
+        })));
+    }
+    const masked = input.masked ?? [];
+    if (!Array.isArray(masked))
+        throw invalid('masked must be a list of { path, reason }', 'Say what was hidden and why.');
+    result.masked = Object.freeze(masked.map((entry, index) => Object.freeze({
+        path: text(plain(entry) ? entry.path : undefined, `masked[${index}].path`, 512),
+        reason: text(plain(entry) ? entry.reason : undefined, `masked[${index}].reason`, 200),
+    })));
+    if (input.next_cursor !== undefined) {
+        if (input.next_cursor !== null)
+            text(input.next_cursor, 'next_cursor', 1_024);
+        result.next_cursor = input.next_cursor;
+    }
+    if (input.fields !== undefined) {
+        if (!plain(input.fields))
+            throw invalid('fields must be an object', 'Pass computed values as { name: value }.');
+        for (const [key, value] of Object.entries(input.fields)) {
+            if (RESERVED.has(key) || !FIELD.test(key))
+                throw invalid(`fields.${key} is not allowed (reserved or not a plain name)`, 'Use a name of letters, digits and _ that the envelope does not use itself.');
+            if (value !== undefined)
+                result[key] = value;
+        }
+    }
+    if (input.images !== undefined) {
+        if (!Array.isArray(input.images))
+            throw invalid('images must be a list of { data, mimeType, alt?, source? }', 'Pass the pictures as a list, or leave images out.');
+        const images = Object.freeze(input.images.map((one, index) => image(one, index)));
+        if (images.length)
+            result.images = images;
+    }
+    const made = Object.freeze(result);
+    MADE.add(made);
+    return made;
+}
+const OWN = [
+    'content',
+    'note',
+    'next',
+    'human_turns',
+    'masked',
+    'next_cursor',
+    'images',
+];
+/**
+ * A changed copy of an envelope (for `transformResult`): `changes` replace the envelope's own
+ * slots (`content`, `note`, `next`, `human_turns`, `masked`, `next_cursor`, `images`) and add
+ * `fields`; the other fields of `result` stay. Its pictures stay unless `images` is given:
+ * `images: []` drops them, `images: result.images.filter(…)` keeps some (D-0143).
+ */
+export function amend(result, changes) {
+    if (!isEnvelope(result))
+        throw invalid('amend() takes an envelope', 'Pass the result the hook received.');
+    // Without a prototype: a key __proto__ of the changes stays a key (and envelope() refuses it).
+    const input = Object.create(null);
+    const fields = Object.create(null);
+    for (const [key, value] of Object.entries(result))
+        if (OWN.includes(key))
+            input[key] = value;
+        else
+            fields[key] = value;
+    if (changes !== undefined && !plain(changes))
+        throw invalid('amend() takes the changes as { content, masked, fields, … }', 'Pass an object of the slots to change.');
+    for (const [key, value] of Object.entries(changes ?? {}))
+        if (key === 'fields') {
+            if (!plain(value))
+                throw invalid('amend() fields must be an object', 'Pass computed values as { name: value }.');
+            for (const [name, one] of Object.entries(value))
+                Object.defineProperty(fields, name, {
+                    value: one,
+                    enumerable: true,
+                    writable: true,
+                    configurable: true,
+                });
+        }
+        else
+            input[key] = value;
+    return envelope({ ...input, fields });
+}
+/** One picture of `envelope({ images })` checked: its type from its own first bytes (D-0143). */
+function image(given, index) {
+    const where = `images[${index}]`;
+    if (!plain(given))
+        throw invalid(`${where} must be { data, mimeType, alt?, source? }`, 'Describe the picture.');
+    const kept = BYTES.get(given);
+    if (kept) {
+        // A placeholder of result.images (amend): the same picture at its new place.
+        const old = given;
+        return placeholder(kept, old.mimeType, index, old.alt, old.source);
+    }
+    const input = given;
+    if (!MIME.has(input.mimeType))
+        throw new McpError('IMAGE_TYPE_REFUSED', `${where} has the type ${typeof input.mimeType === 'string' ? input.mimeType : typeof input.mimeType}; a result carries ${IMAGE_MIME_TYPES.join(', ')} only`, {
+            hint: 'Describe the picture in words instead; it cannot be shown.',
+            fix: 'Send a PNG, JPEG, WebP or GIF copy (a @dokebi/image thumbnail is WebP).',
+            data: { index, allowed: [...IMAGE_MIME_TYPES] },
+        });
+    let bytes;
+    if (input.data instanceof Uint8Array)
+        bytes = input.data;
+    else if (typeof input.data === 'string') {
+        if (input.data.length % 4 !== 0 || !BASE64.test(input.data))
+            throw invalid(`${where}.data is not base64`, 'Pass the bytes as a Uint8Array (or Buffer), or their standard base64 with padding.');
+        bytes = Buffer.from(input.data, 'base64');
+    }
+    else
+        throw invalid(`${where}.data must be a Uint8Array or a base64 string`, 'Pass the bytes of the picture (a Buffer works).');
+    if (bytes.byteLength === 0)
+        throw invalid(`${where}.data is empty`, 'Pass the bytes of the picture.');
+    const format = media.sniffImage(bytes.subarray(0, media.IMAGE_SIGNATURE_BYTES));
+    const detected = format === undefined ? null : `image/${format}`;
+    if (detected !== input.mimeType)
+        throw new McpError('IMAGE_TYPE_MISMATCH', `${where} is declared ${input.mimeType} but its bytes are ${detected ?? 'no image of a known type'}`, {
+            hint: 'The picture could not be sent; tell the user it may be damaged.',
+            fix: 'Declare the type the bytes are (a @dokebi/image thumbnail is image/webp), or convert the file.',
+            data: { index, declared: input.mimeType, detected },
+        });
+    if (input.alt !== undefined)
+        text(input.alt, `${where}.alt`, 1_000);
+    const source = input.source === undefined ? undefined : item(null, input.source).source;
+    return placeholder(bytes, input.mimeType, index, input.alt, source);
+}
+function placeholder(bytes, mimeType, index, alt, source) {
+    const made = Object.freeze({
+        index,
+        mimeType,
+        bytes: bytes.byteLength,
+        ...(alt === undefined ? {} : { alt }),
+        ...(source === undefined ? {} : { source }),
+    });
+    BYTES.set(made, bytes);
+    return made;
+}
+/** The bytes of a placeholder `envelope()` made (the route's, never exported to applications). */
+export function imageBytes(image) {
+    return BYTES.get(image);
+}
+/** Whether `value` was made by `envelope()`. */
+export function isEnvelope(value) {
+    return value !== null && typeof value === 'object' && MADE.has(value);
+}
+/** The default page size in characters (below the default `resultMaxChars` of 60,000). */
+export const PAGE_MAX_CHARS = 50_000;
+const CURSOR = /^p1\.([0-9]{1,9})$/;
+function decodeCursor(cursor) {
+    // base64url decoding never throws; a cursor that is not ours fails the pattern below.
+    const decoded = Buffer.from(cursor, 'base64url').toString('utf8');
+    const match = CURSOR.exec(decoded);
+    if (!match)
+        throw new McpError('INVALID_CURSOR', 'The cursor is not one of this list', {
+            hint: 'Call the tool again without cursor to start from the first page.',
+        });
+    return Number(match[1]);
+}
+/**
+ * One page of `items` that fits `maxChars` (the JSON of the items), from `cursor` on, with the
+ * cursor of the next page (null at the end). The cursor is an offset: for a list that changes
+ * between calls, page with a key of your own and pass it as `next_cursor`. A first item larger
+ * than `maxChars` is returned alone (the result size check may then refuse it).
+ */
+export function page(items, settings = {}) {
+    if (!Array.isArray(items))
+        throw invalid('page() takes the list of items', 'Pass the content items to page.');
+    const maxChars = settings.maxChars ?? PAGE_MAX_CHARS;
+    if (!Number.isSafeInteger(maxChars) || maxChars < 1)
+        throw invalid('page() maxChars must be a whole number above 0', 'Pass a size in characters.');
+    const start = settings.cursor === undefined || settings.cursor === '' ? 0 : decodeCursor(settings.cursor);
+    if (start > items.length)
+        throw new McpError('INVALID_CURSOR', 'The cursor is past the end of this list', {
+            hint: 'Call the tool again without cursor to start from the first page.',
+        });
+    const content = [];
+    let used = 2;
+    let index = start;
+    for (; index < items.length; index++) {
+        const one = items[index];
+        const size = (JSON.stringify(one)?.length ?? 4) + 1;
+        if (content.length > 0 && used + size > maxChars)
+            break;
+        content.push(one);
+        used += size;
+    }
+    return Object.freeze({
+        content: Object.freeze(content),
+        next_cursor: index < items.length ? Buffer.from(`p1.${index}`, 'utf8').toString('base64url') : null,
+    });
+}

package/dist/era.d.ts

@@ -0,0 +1,17 @@
+import { type JsonRpcId, type JsonRpcMessage, type JsonRpcRefusal } from './jsonrpc.js';
+export type Era = 'modern' | 'legacy';
+export interface Version {
+    readonly kind: 'version';
+    readonly era: Era;
+    readonly version: string;
+}
+/** Fastify's request headers (lower-case names). */
+export type Headers = Readonly<Record<string, string | readonly string[] | undefined>>;
+export declare function headerOf(headers: Headers, name: string): string | undefined;
+/** `=?base64?…?=` decoded (other values as they are); undefined when the marker is broken. */
+export declare function decodeHeaderValue(raw: string): string | undefined;
+export declare function unsupported(id: JsonRpcId | null, requested: string): JsonRpcRefusal;
+/** The version of a message and the header checks of modern versions. */
+export declare function classify(message: JsonRpcMessage, headers: Headers): Version | JsonRpcRefusal;
+/** The version an `initialize` is answered with: the one asked for when known, else the newest. */
+export declare function negotiate(requested: unknown): string;