@novorb/mcp-core 2.1.1 → 3.0.0

package/dist/notifications.js

@@ -0,0 +1,173 @@
+/**
+ * @novorb/mcp-core - Change notifications (list changed, resource updated) and the server event bus
+ *
+ * The SDK sources change events from a `ServerEventBus` (`publish` / `subscribe`): `createMcpHandler`
+ * serves 2026-07-28 `subscriptions/listen` streams from it (ack, filtering and subscription ids are the
+ * SDK's). mcp-core makes that bus process-wide and connects it to every transport, so one call reaches
+ * every connection this process serves:
+ *
+ *   const notify = createNotifier();           // or ctx.notify in runMcpServer's setup
+ *   notify.toolsChanged();                      // notifications/tools/list_changed
+ *   notify.resourceUpdated('gitlab://repo/README.md');
+ *
+ * Delivery per era (what the SDK can carry; mcp-core adds no transport of its own):
+ *
+ * | Connection | Delivery |
+ * |---|---|
+ * | HTTP, 2026-07-28 | `subscriptions/listen` SSE streams on this process (the SDK listen router filters by the client's honored filter) |
+ * | stdio, 2026-07-28 | the pinned instance's change notifications, rewritten by the SDK onto the connection's open subscriptions |
+ * | stdio, 2025-era | unsolicited notifications on the connection; `resources/updated` only for URIs the client subscribed to |
+ * | HTTP, 2025-era stateless | none: every request is answered by a fresh instance and the standalone GET stream is 405, so there is no channel |
+ *
+ * Multi-instance hosts replace the in-memory bus with a shared one (`setProcessBus`, or `bus` on the
+ * transport options). A shared `ServerEventBus` implementation must: fan `publish(event)` out to the
+ * listeners of EVERY instance (its own included); return an idempotent unsubscribe from `subscribe`;
+ * never throw from `publish` (a failing listener must not stop the others); never echo an event back
+ * to the listener that published it from inside that listener; and carry the event value as is
+ * (`{ kind }` or `{ kind: 'resource_updated', uri }`, JSON-serialisable). No persistence or replay is
+ * needed: listen streams are live and a client re-lists after reconnecting. Events are not addressed to
+ * a caller: every open stream that opted in receives them (the SDK event has no principal).
+ */
+import { InMemoryServerEventBus, McpServer, } from '@modelcontextprotocol/server';
+import { getLogger } from './utils/logger.js';
+export { InMemoryServerEventBus } from '@modelcontextprotocol/server';
+function reportListenerError(error) {
+    getLogger().warn(`notification listener failed: ${error.message}`, 'Notifications');
+}
+let current;
+/** The process-wide bus every mcp-core transport uses by default (in memory unless replaced). */
+export function processBus() {
+    current ??= new InMemoryServerEventBus(reportListenerError);
+    return current;
+}
+/**
+ * Replace the process bus (a shared pub/sub on multi-instance hosts). Call it before starting the
+ * transport; `undefined` restores a fresh in-memory bus on next use.
+ */
+export function setProcessBus(bus) {
+    current = bus;
+}
+/** The typed publish facade over a bus (the same shape as the SDK's `handler.notify`). */
+export function createNotifier(bus = processBus()) {
+    return {
+        toolsChanged: () => bus.publish({ kind: 'tools_list_changed' }),
+        promptsChanged: () => bus.publish({ kind: 'prompts_list_changed' }),
+        resourcesChanged: () => bus.publish({ kind: 'resources_list_changed' }),
+        resourceUpdated: (uri) => bus.publish({ kind: 'resource_updated', uri }),
+    };
+}
+const SUBSCRIPTIONS = Symbol.for('@novorb/mcp-core/resourceSubscriptions');
+function lowLevel(server) {
+    return server instanceof McpServer ? server.server : server;
+}
+/** The URIs a 2025-era client subscribed to on this instance (`resources/subscribe`). */
+export function resourceSubscriptions(server) {
+    const target = lowLevel(server);
+    target[SUBSCRIPTIONS] ??= new Set();
+    return target[SUBSCRIPTIONS];
+}
+function send(server, event, era) {
+    switch (event.kind) {
+        case 'tools_list_changed':
+            return server.sendToolListChanged();
+        case 'prompts_list_changed':
+            return server.sendPromptListChanged();
+        case 'resources_list_changed':
+            return server.sendResourceListChanged();
+        case 'resource_updated':
+            // On a 2025-era connection only subscribed URIs are sent; on 2026-07-28 the SDK router filters.
+            if (era === 'legacy' && !resourceSubscriptions(server).has(event.uri))
+                return undefined;
+            return server.sendResourceUpdated({ uri: event.uri });
+    }
+}
+/**
+ * Forward bus events to a long-lived instance (a stdio connection): each event becomes the instance's
+ * own change notification. Detaches when the instance closes; returns the detach function. A send that
+ * fails (not connected, capability not advertised) is dropped: notifications never fail the server.
+ */
+export function attachNotifications(server, era, bus = processBus()) {
+    const target = lowLevel(server);
+    const unsubscribe = bus.subscribe((event) => {
+        try {
+            send(target, event, era)?.catch(() => undefined);
+        }
+        catch {
+            // A notification the instance cannot send (capability not advertised) is dropped.
+        }
+    });
+    let detached = false;
+    const detach = () => {
+        if (detached)
+            return;
+        detached = true;
+        unsubscribe();
+    };
+    const previous = target.onclose;
+    target.onclose = () => {
+        detach();
+        previous?.();
+    };
+    return detach;
+}
+/**
+ * Process-level enable/disable state for tools, prompts and resources, so a runtime change works the
+ * same in both serving models: per-request HTTP instances read it when they are built, live stdio
+ * instances have their SDK handles toggled in place, and ONE list-changed event goes out on the bus.
+ * Pass it as `surface` to `registerTools` / `registerResources` / `registerPrompts`.
+ */
+export function createRuntimeSurface(notifier = createNotifier()) {
+    const disabled = new Set();
+    const listeners = new Set();
+    const key = (kind, name) => `${kind}\0${name}`;
+    const publish = (kind) => {
+        if (kind === 'tool')
+            notifier.toolsChanged();
+        else if (kind === 'prompt')
+            notifier.promptsChanged();
+        else
+            notifier.resourcesChanged();
+    };
+    const set = (kind, name, enabled) => {
+        const k = key(kind, name);
+        if (enabled === !disabled.has(k))
+            return;
+        if (enabled)
+            disabled.delete(k);
+        else
+            disabled.add(k);
+        for (const listener of [...listeners])
+            listener(kind, name, enabled);
+        publish(kind);
+    };
+    return {
+        isEnabled: (kind, name) => !disabled.has(key(kind, name)),
+        enable: (kind, name) => set(kind, name, true),
+        disable: (kind, name) => set(kind, name, false),
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}
+/**
+ * Bind one SDK handle (a registered tool, prompt, resource or template) to a surface: its `enabled`
+ * flag follows the surface, set directly so the instance itself sends no list-changed notification
+ * (the surface publishes exactly one on the bus). The binding is released when the instance closes.
+ */
+export function bindToSurface(server, surface, kind, name, handle) {
+    handle.enabled = surface.isEnabled(kind, name);
+    const unsubscribe = surface.subscribe((k, n, enabled) => {
+        if (k === kind && n === name)
+            handle.enabled = enabled;
+    });
+    const target = server.server;
+    const previous = target.onclose;
+    target.onclose = () => {
+        unsubscribe();
+        previous?.();
+    };
+}
+//# sourceMappingURL=notifications.js.map

package/dist/notifications.js.map

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

package/dist/pagination.d.ts

@@ -1,8 +1,17 @@
 /**
- * @novorb/mcp-core — Pagination utilities
+ * @novorb/mcp-core - Pagination utilities
  *
- * Normalize and compute pagination metadata across MCP servers.
+ * Three groups:
+ * - page-number helpers for list tools (`normalizePagination`, `createPaginationMetadata`,
+ *   `pageToOffset`, `paginateArray`);
+ * - HTTP-side strategies that walk an upstream API's pages (`pagePerPage`, `nextPageHeader`,
+ *   `offsetLimit`, `linkHeader`, `nextLinkField`, `continuationToken`), run by `paginateRequests`
+ *   (and `McpHttpClient.paginate`) with a stop condition per strategy and a hard page cap;
+ * - MCP-side opaque cursors and one paged result contract for list tools (`encodeCursor`,
+ *   `decodeCursor`, `invalidCursorResult`, `paginateArrayByCursor`, `PagedResult`,
+ *   `pagedResultSchema`).
  */
+import type { HttpResponse, RequestOptions } from './http-client.js';
 export interface PaginationParams {
     /** Page number (1-based, default: 1) */
     page?: number;
@@ -19,14 +28,22 @@ export interface PaginationMetadata {
     perPage: number;
     totalPages: number;
 }
+export interface NormalizePaginationOptions {
+    /** Maximum allowed per_page (default: 100). */
+    maxPerPage?: number;
+    /** Default per_page (default: 20). */
+    defaultPerPage?: number;
+    /** `clamp` (default) bounds out-of-range values; `throw` rejects them with a RangeError. */
+    onInvalid?: 'clamp' | 'throw';
+}
 /**
  * Normalize pagination parameters with sensible bounds.
  *
  * @param params - Raw pagination params
- * @param maxPerPage - Maximum allowed per_page (default: 100)
- * @param defaultPerPage - Default per_page (default: 20)
+ * @param maxPerPageOrOptions - Maximum per_page (default: 100), or an options object
+ * @param defaultPerPage - Default per_page (default: 20; ignored when an options object is passed)
  */
-export declare function normalizePagination(params?: PaginationParams, maxPerPage?: number, defaultPerPage?: number): NormalizedPagination;
+export declare function normalizePagination(params?: PaginationParams, maxPerPageOrOptions?: number | NormalizePaginationOptions, defaultPerPage?: number): NormalizedPagination;
 /**
  * Create pagination metadata from total count and normalized params.
  */
@@ -42,4 +59,218 @@ export declare function paginateArray<T>(items: T[], params: NormalizedPaginatio
     data: T[];
     metadata: PaginationMetadata;
 };
+/** One fetched page. */
+export interface Page<T> {
+    items: T[];
+    /** 0-based index of the page in this walk. */
+    pageIndex: number;
+    /** Total item count when the API reports one. */
+    total?: number;
+}
+/** What a strategy extracts from one response. `next` absent = the last page. */
+export interface PageParseResult<T> {
+    items: T[];
+    total?: number;
+    next?: RequestOptions;
+}
+/** How to walk one API's pages. */
+export interface PaginationStrategy<T> {
+    readonly name: string;
+    /** Decorates the caller's first request (page size, start page). */
+    first(request: RequestOptions): RequestOptions;
+    /** Extracts the page's items, the total, and the next request (absent = stop). */
+    parse(response: HttpResponse<unknown>, request: RequestOptions): PageParseResult<T>;
+}
+export interface PaginateOptions {
+    /** Stop after this many pages (default 100, never above HARD_MAX_PAGES). */
+    maxPages?: number;
+    /**
+     * Stop once this many items are collected (the last page is trimmed). Default MCP_MAX_RESULT_ITEMS
+     * (100); never above HARD_MAX_COLLECT_ITEMS (100000). `collect()` reports `truncated` when it stopped.
+     */
+    maxItems?: number;
+}
+export type PaginationStopReason = 'end' | 'maxPages' | 'maxItems' | 'repeated';
+export interface CollectResult<T> {
+    items: T[];
+    total?: number;
+    pages: number;
+    /** Why the walk stopped. `repeated` = the API sent the same next request twice. */
+    stopReason: PaginationStopReason;
+    /** True when the walk stopped before the API's last page. */
+    truncated: boolean;
+}
+export interface PageIterator<T> extends AsyncIterable<Page<T>> {
+    /** Iterate items across pages. */
+    items(): AsyncIterable<T>;
+    /** Walk every page (within the caps) and gather the items. */
+    collect(): Promise<CollectResult<T>>;
+}
+export declare const DEFAULT_MAX_PAGES = 100;
+/** Absolute ceiling on any walk, whatever the caller asks for. */
+export declare const HARD_MAX_PAGES = 10000;
+/** Extracts the items of a response body. */
+export type ItemsExtractor<T> = (body: unknown) => T[];
+/** Default items extractor: an array body, else the first array under value/items/data/results. */
+export declare function defaultItems<T>(body: unknown): T[];
+/** Reads a non-negative integer header (e.g. `X-Total`, `X-Total-Count`); undefined when absent. */
+export declare function readHeaderTotal(headers: Record<string, string>, name: string): number | undefined;
+interface TotalSource {
+    /** Response header carrying the total (e.g. `x-total`, `x-total-count`). */
+    totalHeader?: string;
+    /** Body field carrying the total (e.g. `@odata.count`, `total`). */
+    totalField?: string;
+}
+export interface PagePerPageOptions<T> extends TotalSource {
+    /** Page query parameter (default `page`). */
+    pageParam?: string;
+    /** Page size query parameter (default `per_page`). */
+    sizeParam?: string;
+    /** Page size (default 100). */
+    pageSize?: number;
+    /** First page number (default 1). */
+    startPage?: number;
+    /** Items field name or extractor (default `defaultItems`). */
+    items?: string | ItemsExtractor<T>;
+}
+/**
+ * Page-number pagination (`page` + `per_page`). Stops on an empty or short page, or once
+ * page * size reaches the total (from `totalHeader` / `totalField`).
+ */
+export declare function pagePerPage<T>(options?: PagePerPageOptions<T>): PaginationStrategy<T>;
+export interface NextPageHeaderOptions<T> extends TotalSource {
+    /** Header naming the next page number (default `x-next-page`); empty or absent = last page. */
+    header?: string;
+    pageParam?: string;
+    sizeParam?: string;
+    pageSize?: number;
+    items?: string | ItemsExtractor<T>;
+}
+/**
+ * Next-page header pagination (GitLab: `X-Next-Page`, empty on the last page; total from `X-Total`,
+ * which gitlab.com omits above 10k rows, so the header and not the total drives the walk).
+ */
+export declare function nextPageHeader<T>(options?: NextPageHeaderOptions<T>): PaginationStrategy<T>;
+export interface OffsetLimitOptions<T> extends TotalSource {
+    offsetParam?: string;
+    limitParam?: string;
+    /** Page size (default 100). */
+    limit?: number;
+    /** First offset (default 0). */
+    startOffset?: number;
+    items?: string | ItemsExtractor<T>;
+}
+/** Offset/limit pagination. Stops on an empty or short page, or once offset + items reaches the total. */
+export declare function offsetLimit<T>(options?: OffsetLimitOptions<T>): PaginationStrategy<T>;
+/** Parses an RFC 8288 (RFC 5988) `Link` header into rel -> URL. Space-separated rels map each. */
+export declare function parseLinkHeader(value: string | undefined): Record<string, string>;
+export interface LinkHeaderOptions<T> extends TotalSource {
+    /** Link relation to follow (default `next`). */
+    rel?: string;
+    items?: string | ItemsExtractor<T>;
+}
+/**
+ * RFC 5988 `Link: <url>; rel="next"` pagination (GitLab keyset, GitHub). The next URL is used as-is
+ * (it carries its own query), so the caller's query is dropped on follow-up requests.
+ */
+export declare function linkHeader<T>(options?: LinkHeaderOptions<T>): PaginationStrategy<T>;
+export interface NextLinkFieldOptions<T> extends TotalSource {
+    /** Body field holding the absolute next URL (default `@odata.nextLink`). */
+    field?: string;
+    /** Items field (default `value`). */
+    items?: string | ItemsExtractor<T>;
+}
+/**
+ * Body next-link pagination (Microsoft Graph `@odata.nextLink`, total `@odata.count`). The next link
+ * is absolute and already contains the API version segment, so it is requested as-is.
+ */
+export declare function nextLinkField<T>(options?: NextLinkFieldOptions<T>): PaginationStrategy<T>;
+export interface ContinuationTokenOptions<T> extends TotalSource {
+    /** Query parameter that carries the token on the next request (default `continuationToken`). */
+    requestParam?: string;
+    /** Body field holding the token, or a function of (body, items) (default `continuationToken`). */
+    token?: string | ((body: unknown, items: T[]) => string | undefined);
+    /** Items field (default `items`). */
+    items?: string | ItemsExtractor<T>;
+}
+/**
+ * Continuation-token pagination (Nexus `continuationToken`; Trello `before=<last id>` via a token
+ * function). Stops when the token is absent or empty, or the page is empty.
+ */
+export declare function continuationToken<T>(options?: ContinuationTokenOptions<T>): PaginationStrategy<T>;
+/**
+ * Walks pages with a strategy. Each iteration of the returned iterator restarts the walk. Stops at the
+ * strategy's last page, `maxPages` (default 100, capped at HARD_MAX_PAGES), `maxItems`, or when the API
+ * repeats a next request (a loop).
+ */
+export declare function paginateRequests<T>(fetchPage: (request: RequestOptions) => Promise<HttpResponse<unknown>>, request: RequestOptions, strategy: PaginationStrategy<T>, options?: PaginateOptions): PageIterator<T>;
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare const CURSOR_VERSION = 1;
+/** Longest cursor `decodeCursor` accepts (bounded input). */
+export declare const MAX_CURSOR_LENGTH = 2048;
+/** Thrown by `decodeCursor` for a malformed, foreign, or stale cursor. */
+export declare class InvalidCursorError extends Error {
+    constructor(reason: string);
+}
+/** Encodes cursor state as an opaque, versioned base64url JSON string. */
+export declare function encodeCursor(data: JsonValue, version?: number): string;
+export interface DecodeCursorOptions<T extends JsonValue> {
+    /** Expected version (default CURSOR_VERSION); another version is rejected as stale. */
+    version?: number;
+    /** Type guard for the payload; a false result is rejected. */
+    validate?: (data: JsonValue) => data is T;
+}
+/**
+ * Decodes a cursor made by `encodeCursor`. Throws `InvalidCursorError` (message starts with
+ * `Invalid cursor:`) for anything else.
+ */
+export declare function decodeCursor<T extends JsonValue = JsonValue>(cursor: string, options?: DecodeCursorOptions<T>): T;
+/** Tool result for a bad cursor: `isError` with the error's message (a generic one otherwise). */
+export declare function invalidCursorResult(error: unknown): {
+    isError: true;
+    content: [{
+        type: 'text';
+        text: string;
+    }];
+};
+/** The one paged result shape list tools return. */
+export interface PagedResult<T> {
+    items: T[];
+    /** Opaque cursor for the next page; absent on the last page. */
+    nextCursor?: string;
+    /** Total item count when known. */
+    total?: number;
+}
+/**
+ * The zod members `pagedResultSchema` uses, as a structural contract: any zod 4.x namespace satisfies
+ * it, so a consumer on a different zod copy typechecks without sharing mcp-core's zod identity.
+ */
+export interface PagedResultZod {
+    object: (...args: never[]) => unknown;
+    array: (...args: never[]) => unknown;
+    string: (...args: never[]) => unknown;
+    number: (...args: never[]) => unknown;
+}
+/**
+ * The zod output schema of `PagedResult<item>`. Takes the consumer's `z` so mcp-core never loads zod
+ * at runtime: `outputSchema: pagedResultSchema(z, Project)`. The result is the caller's own `z.object`
+ * type (its members are not narrowed to the paged shape).
+ */
+export declare function pagedResultSchema<Z extends PagedResultZod>(z: Z, item: unknown): ReturnType<Z['object']>;
+export interface CursorPageOptions {
+    /** Cursor from the previous page (absent = first page). */
+    cursor?: string;
+    /** Requested page size (default `defaultLimit`, clamped to 1..maxLimit). */
+    limit?: number;
+    defaultLimit?: number;
+    maxLimit?: number;
+}
+/**
+ * Cursor pagination over an in-memory array: returns a `PagedResult` whose `nextCursor` encodes the
+ * next offset. Throws `InvalidCursorError` for a bad or out-of-range cursor.
+ */
+export declare function paginateArrayByCursor<T>(items: T[], options?: CursorPageOptions): PagedResult<T>;
+export {};
 //# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,CAAC,EAAE,gBAAgB,EACzB,UAAU,SAAM,EAChB,cAAc,SAAK,GAClB,oBAAoB,CAItB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,oBAAoB,GAC3B,kBAAkB,CAOpB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,MAAM,EAAE,oBAAoB,GAC3B;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,QAAQ,EAAE,kBAAkB,CAAA;CAAE,CAO7C"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"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"}