@juspay/neurolink 13.0.2 → 13.1.0

package/dist/client/reactHooks.d.ts

@@ -14,8 +14,7 @@
  *
  * @module @neurolink/react
  */
-import type { ReactNode } from "react";
-import type { NeuroLinkProviderProps, UseChatOptions, UseChatReturn, UseAgentOptions, UseAgentReturn, UseWorkflowOptions, UseWorkflowReturn, UseVoiceOptions, UseVoiceReturn, UseStreamOptions, UseStreamReturn, UseToolsOptions, UseToolsReturn, SpeechRecognitionInternal } from "../types/index.js";
+import type { ClientReactElement, NeuroLinkProviderProps, UseChatOptions, UseChatReturn, UseAgentOptions, UseAgentReturn, UseWorkflowOptions, UseWorkflowReturn, UseVoiceOptions, UseVoiceReturn, UseStreamOptions, UseStreamReturn, UseToolsOptions, UseToolsReturn, SpeechRecognitionInternal } from "../types/index.js";
 import { NeuroLinkClient } from "./httpClient.js";
 /**
  * Provider component for NeuroLink client
@@ -40,9 +39,7 @@ import { NeuroLinkClient } from "./httpClient.js";
  * }
  * ```
  */
-export declare function NeuroLinkProvider({ config, children, }: NeuroLinkProviderProps & {
-    children: ReactNode;
-}): ReactNode;
+export declare function NeuroLinkProvider({ config, children, }: NeuroLinkProviderProps): ClientReactElement;
 /**
  * Hook to access the NeuroLink client
  *

package/dist/constants/enums.d.ts

@@ -1540,7 +1540,8 @@ export declare enum PrimeIntellectModels {
 export declare enum RekaModels {
     REKA_FLASH = "reka-flash",
     REKA_EDGE = "reka-edge",
-    REKA_EDGE_2603 = "reka-edge-2603"
+    REKA_EDGE_2603 = "reka-edge-2603",
+    REKA_FLASH_3 = "reka-flash-3"
 }
 export declare enum RunInfraModels {
     NEMOTRON_3_5_LIGHTNING_30B = "nemotron-3-5-lightning-30b"

package/dist/constants/enums.js

@@ -1842,6 +1842,7 @@ export var RekaModels;
     RekaModels["REKA_FLASH"] = "reka-flash";
     RekaModels["REKA_EDGE"] = "reka-edge";
     RekaModels["REKA_EDGE_2603"] = "reka-edge-2603";
+    RekaModels["REKA_FLASH_3"] = "reka-flash-3";
 })(RekaModels || (RekaModels = {}));
 export var RunInfraModels;
 (function (RunInfraModels) {

package/dist/core/toolRouting.js

@@ -48,12 +48,15 @@ const DEFAULT_EMBEDDING_MIN_TOOLS = 20;
 const DEFAULT_EMBEDDING_TOP_K = 20;
 /**
  * Upper bound on the user-query text interpolated into the router prompt.
- * The query is untrusted and can attempt prompt injection — the blast radius
- * is already bounded (the worst a successful injection achieves is making the
- * router keep MORE already-registered tools; out-of-catalog ids are filtered),
- * but without a cap an arbitrarily large query is sent to the router LLM every
- * turn. 10K chars is far more than enough to classify routing intent while
- * leaving room for a window of recent conversation turns.
+ * The query is untrusted and can attempt prompt injection. The reach is
+ * bounded, not zero: out-of-catalog ids are filtered, so an injected query
+ * cannot name a tool that was not already registered, and an empty pick fails
+ * open. But the router returns the servers to KEEP and every unselected
+ * routable server is excluded for the turn with no confidence bar, so a
+ * steered pick can withhold tools. Without a cap an arbitrarily large query is
+ * sent to the router LLM every turn. 10K chars is far more than enough to
+ * classify routing intent while leaving room for a window of recent
+ * conversation turns.
  */
 const MAX_ROUTER_QUERY_CHARS = 10000;
 /**

package/dist/core/toolRoutingDecision.js

@@ -33,9 +33,11 @@ const SERVER_NAMESPACE = "server";
 const DEFAULT_MIN_DROP_CONFIDENCE = 0.6;
 /**
  * Upper bound on the query text sent as state. The query is untrusted and may
- * attempt injection; the blast radius is bounded (the worst outcome is keeping
- * MORE already-registered tools, since ids are never read back off the wire —
- * answers are matched by position), but an unbounded state would still be
+ * attempt injection. Ids are never read back off the wire — answers are matched
+ * by position — so an injected query cannot name a tool that was not already
+ * registered, and the result is only a denylist appended to `excludeTools`. It
+ * can still steer a verdict: a confident `false` drops that server's tools for
+ * the turn. The reach is bounded, not zero. An unbounded state would also be
  * billed and could push the request past the model's input ceiling.
  */
 const MAX_STATE_CHARS = 10000;

package/dist/localUsage/grokReader.js

@@ -239,7 +239,9 @@ function completedTurn(parsed) {
 }
 async function foldStream(filePath, totals, unpriced, errors) {
     // Insertion-ordered, so the delta rule below sees turns in the order Grok
-    // wrote them, with a re-emitted prompt replacing its earlier record.
+    // wrote them. A re-emitted prompt replaces its earlier record and moves to
+    // where the re-emit was written: Map.set on an existing key keeps the old
+    // position, so the key is deleted first.
     const turns = new Map();
     let unrecognised = 0;
     const rl = createInterface({
@@ -274,7 +276,9 @@ async function foldStream(filePath, totals, unpriced, errors) {
                 }
                 continue;
             }
-            turns.set(turn.promptId ?? `line:${lineNo}`, readTurn(turn.usage));
+            const key = turn.promptId ?? `line:${lineNo}`;
+            turns.delete(key);
+            turns.set(key, readTurn(turn.usage));
         }
     }
     finally {

package/dist/mcp/mcpRegistryClient.d.ts

@@ -1,12 +1,14 @@
 /**
  * MCP Registry Client
  *
- * Client for discovering MCP servers from centralized registries.
- * Supports multiple registry sources including:
- * - Official MCP Registry
- * - NPM packages
- * - GitHub repositories
- * - Custom registries
+ * Client for discovering MCP servers. It always knows a built-in catalog of
+ * well-known servers plus any custom entries. When remote lookup is enabled
+ * (`remoteLookup: true`, off by default) it also consults:
+ * - the official MCP Registry (https://registry.modelcontextprotocol.io)
+ * - custom registries that serve the same `/v0.1` API
+ *
+ * `npm` and `github` registry sources are accepted in configuration but not
+ * queried.
  *
  * @module mcp/mcpRegistryClient
  * @since 8.39.0
@@ -30,6 +32,10 @@ import type { MCPServerInfo, MCPRegistryClientConfig, RegistryConfig, RegistrySe
  *
  * // Convert to MCPServerInfo
  * const serverInfo = client.toServerInfo(entry);
+ *
+ * // Opt in to the official MCP Registry (remote entries are never `verified`)
+ * const remote = new MCPRegistryClient({ remoteLookup: true });
+ * const found = await remote.getEntry("io.github.example/my-server");
  * ```
  */
 export declare class MCPRegistryClient extends EventEmitter {
@@ -42,13 +48,63 @@ export declare class MCPRegistryClient extends EventEmitter {
      */
     search(options?: RegistrySearchOptions): Promise<RegistrySearchResult>;
     /**
-     * Get a specific entry by ID
+     * Get a specific entry by ID.
+     *
+     * Checks custom entries, then the built-in catalog. Only when remote
+     * lookup is enabled does a miss fall through to the configured registries
+     * (first hit wins); a registry that fails or answers with something
+     * unreadable is skipped, so the result is `undefined` rather than an error.
      */
     getEntry(id: string): Promise<McpRegistryEntry | undefined>;
     /**
-     * Get all available entries
+     * Get all available entries.
+     *
+     * Lists the built-in catalog, then the custom entries (a custom entry
+     * replaces a built-in one with the same id), then, when remote lookup is
+     * enabled, the servers of each configured registry. A remote entry never
+     * replaces a local one. A registry that cannot be read contributes nothing.
      */
     getAllEntries(): Promise<McpRegistryEntry[]>;
+    /**
+     * Collect local entries and, when remote lookup is on, each registry's
+     * servers. `query` narrows the remote lists with the registry's own
+     * `search` parameter (substring match on server name); `search()` still
+     * applies its full filter afterwards.
+     *
+     * The merged list is cached only when every registry answered, so a
+     * transient failure is not pinned for the whole TTL.
+     */
+    private collectEntries;
+    /**
+     * Registries the client may query: `official` and `custom` sources with a
+     * usable URL. Other sources are skipped.
+     */
+    private getRemoteTargets;
+    private fetchRemoteEntry;
+    private fetchRemoteList;
+    /**
+     * GET a JSON document from a registry, bounded by its timeout. A 404
+     * resolves with an undefined body (a normal "not found"); any other
+     * non-2xx status, a network error, a timeout or a body that is not JSON
+     * rejects.
+     */
+    private requestJson;
+    /**
+     * Parse a JSON body, refusing to buffer more than
+     * `REMOTE_MAX_RESPONSE_BYTES`. The request timeout bounds duration, not
+     * memory, so the size is checked while reading.
+     */
+    private readBoundedJson;
+    private reportRemoteError;
+    private readCache;
+    private readRemoteCache;
+    private writeRemoteCache;
+    /**
+     * The client-wide `enableCache: false` is a ceiling: a registry can switch
+     * its own caching off but cannot turn it back on.
+     */
+    private isRemoteCacheEnabled;
+    private writeCache;
     /**
      * Get entries by category
      */
@@ -81,6 +137,12 @@ export declare class MCPRegistryClient extends EventEmitter {
      * Add a registry configuration
      */
     addRegistry(config: RegistryConfig): void;
+    /**
+     * Turn remote lookup on or off at runtime, e.g. on the client returned by
+     * `NeuroLink.getMCPRegistryClient()`. Off is the default. Clears the cache
+     * so the next lookup reflects the new setting.
+     */
+    setRemoteLookup(enabled: boolean): void;
     /**
      * Clear the cache
      */

package/dist/mcp/mcpRegistryClient.js

@@ -1,17 +1,27 @@
 /**
  * MCP Registry Client
  *
- * Client for discovering MCP servers from centralized registries.
- * Supports multiple registry sources including:
- * - Official MCP Registry
- * - NPM packages
- * - GitHub repositories
- * - Custom registries
+ * Client for discovering MCP servers. It always knows a built-in catalog of
+ * well-known servers plus any custom entries. When remote lookup is enabled
+ * (`remoteLookup: true`, off by default) it also consults:
+ * - the official MCP Registry (https://registry.modelcontextprotocol.io)
+ * - custom registries that serve the same `/v0.1` API
+ *
+ * `npm` and `github` registry sources are accepted in configuration but not
+ * queried.
  *
  * @module mcp/mcpRegistryClient
  * @since 8.39.0
  */
 import { EventEmitter } from "events";
+import { mcpLogger } from "../utils/logger.js";
+import { mapRemoteRecord, parseRemotePage, parseRemoteRecord, resolveRemoteTarget, } from "./mcpRegistryRemote.js";
+const REMOTE_PAGE_SIZE = 100;
+const REMOTE_DEFAULT_MAX_PAGES = 5;
+// A list page of 100 servers is well under 2 MiB; the cap only stops a hostile
+// or broken registry from filling memory within the timeout.
+const REMOTE_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+const CACHE_MAX_ENTRIES = 500;
 /**
  * Well-known MCP servers catalog
  */
@@ -183,6 +193,10 @@ const WELL_KNOWN_SERVERS = [
  *
  * // Convert to MCPServerInfo
  * const serverInfo = client.toServerInfo(entry);
+ *
+ * // Opt in to the official MCP Registry (remote entries are never `verified`)
+ * const remote = new MCPRegistryClient({ remoteLookup: true });
+ * const found = await remote.getEntry("io.github.example/my-server");
  * ```
  */
 export class MCPRegistryClient extends EventEmitter {
@@ -192,9 +206,10 @@ export class MCPRegistryClient extends EventEmitter {
     constructor(config = {}) {
         super();
         this.config = {
-            registries: config.registries ?? [
-                { type: "official", enableCache: true },
+            registries: [
+                ...(config.registries ?? [{ type: "official", enableCache: true }]),
             ],
+            remoteLookup: config.remoteLookup ?? false,
             enableCache: config.enableCache ?? true,
             defaultCacheTTL: config.defaultCacheTTL ?? 3600000, // 1 hour
             timeout: config.timeout ?? 10000,
@@ -208,8 +223,12 @@ export class MCPRegistryClient extends EventEmitter {
         const { query, categories, tags, transport, verifiedOnly = false, sortBy = "downloads", sortDirection = "desc", limit: rawLimit = 25, offset: rawOffset = 0, } = options;
         const limit = Math.max(1, rawLimit);
         const offset = Math.max(0, rawOffset);
-        // Get all entries (from cache or fetch)
-        let entries = await this.getAllEntries();
+        // Get all entries (from cache or fetch). Copy: the sort below must not
+        // reorder the cached list.
+        const listed = query
+            ? await this.collectEntries(query)
+            : await this.getAllEntries();
+        let entries = [...listed];
         // Apply filters
         if (query) {
             const searchLower = query.toLowerCase();
@@ -260,7 +279,12 @@ export class MCPRegistryClient extends EventEmitter {
         };
     }
     /**
-     * Get a specific entry by ID
+     * Get a specific entry by ID.
+     *
+     * Checks custom entries, then the built-in catalog. Only when remote
+     * lookup is enabled does a miss fall through to the configured registries
+     * (first hit wins); a registry that fails or answers with something
+     * unreadable is skipped, so the result is `undefined` rather than an error.
      */
     async getEntry(id) {
         // Check custom entries first
@@ -272,35 +296,291 @@ export class MCPRegistryClient extends EventEmitter {
         if (wellKnown) {
             return wellKnown;
         }
-        // TODO(#1956): Fetch from remote registry
+        if (!this.config.remoteLookup) {
+            return undefined;
+        }
+        // An empty id, "." and ".." are path segments: URL normalisation would
+        // turn them into a different registry endpoint, so they are a miss.
+        if (id === "" || id === "." || id === "..") {
+            return undefined;
+        }
+        for (const target of this.getRemoteTargets()) {
+            const entry = await this.fetchRemoteEntry(target, id);
+            if (entry) {
+                return entry;
+            }
+        }
         return undefined;
     }
     /**
-     * Get all available entries
+     * Get all available entries.
+     *
+     * Lists the built-in catalog, then the custom entries (a custom entry
+     * replaces a built-in one with the same id), then, when remote lookup is
+     * enabled, the servers of each configured registry. A remote entry never
+     * replaces a local one. A registry that cannot be read contributes nothing.
      */
     async getAllEntries() {
-        const cacheKey = "all-entries";
+        return this.collectEntries();
+    }
+    /**
+     * Collect local entries and, when remote lookup is on, each registry's
+     * servers. `query` narrows the remote lists with the registry's own
+     * `search` parameter (substring match on server name); `search()` still
+     * applies its full filter afterwards.
+     *
+     * The merged list is cached only when every registry answered, so a
+     * transient failure is not pinned for the whole TTL.
+     */
+    async collectEntries(query) {
+        // Without remote lookup the query changes nothing, so share one entry.
+        const cacheKey = query === undefined || !this.config.remoteLookup
+            ? "all-entries"
+            : `all-entries:${query.toLowerCase()}`;
+        // The merged list must not outlive the shortest-lived registry cache, and
+        // is not cached at all if any registry has caching switched off.
+        const targets = this.config.remoteLookup ? this.getRemoteTargets() : [];
+        const cacheable = this.config.enableCache &&
+            targets.every((t) => this.isRemoteCacheEnabled(t));
+        const ttl = Math.min(this.config.defaultCacheTTL, ...targets.map((t) => t.config.cacheTTL ?? this.config.defaultCacheTTL));
         // Check cache
-        if (this.config.enableCache) {
-            const cached = this.cache.get(cacheKey);
-            if (cached &&
-                Date.now() - cached.timestamp < this.config.defaultCacheTTL) {
-                return cached.data;
-            }
+        const cached = cacheable
+            ? this.readCache(cacheKey, ttl)
+            : undefined;
+        if (cached) {
+            return cached;
         }
         // Combine well-known servers and custom entries, deduplicating by ID.
         // Custom entries take precedence over well-known servers.
         const customIds = new Set(this.customEntries.keys());
-        const allEntries = [
+        const localEntries = [
             ...WELL_KNOWN_SERVERS.filter((entry) => !customIds.has(entry.id)),
             ...Array.from(this.customEntries.values()),
         ];
+        let allEntries = localEntries;
+        let complete = true;
+        if (this.config.remoteLookup) {
+            const lists = await Promise.all(targets.map((target) => this.fetchRemoteList(target, query)));
+            const seen = new Set(localEntries.map((entry) => entry.id));
+            const remoteEntries = [];
+            for (const list of lists) {
+                complete = complete && list.ok;
+                for (const entry of list.entries) {
+                    if (!seen.has(entry.id)) {
+                        seen.add(entry.id);
+                        remoteEntries.push(entry);
+                    }
+                }
+            }
+            allEntries = [...localEntries, ...remoteEntries];
+        }
         // Cache the result
-        if (this.config.enableCache) {
-            this.cache.set(cacheKey, { data: allEntries, timestamp: Date.now() });
+        if (cacheable && complete) {
+            this.writeCache(cacheKey, allEntries);
         }
         return allEntries;
     }
+    /**
+     * Registries the client may query: `official` and `custom` sources with a
+     * usable URL. Other sources are skipped.
+     */
+    getRemoteTargets() {
+        return this.config.registries.flatMap((registry) => {
+            const target = resolveRemoteTarget(registry);
+            if (target === undefined) {
+                mcpLogger.debug(`[MCPRegistryClient] Skipping registry of type "${registry.type}": not queryable (unsupported type, missing or unusable URL, or a bearer token on plain http to a non-loopback host)`);
+                return [];
+            }
+            return [target];
+        });
+    }
+    async fetchRemoteEntry(target, id) {
+        const cacheKey = `remote-entry:${target.apiBase}:${id}`;
+        const cached = this.readRemoteCache(cacheKey, target);
+        if (cached) {
+            return cached;
+        }
+        try {
+            const response = await this.requestJson(target, `/servers/${encodeURIComponent(id)}/versions/latest`);
+            if (response.body === undefined) {
+                return undefined;
+            }
+            const record = parseRemoteRecord(response.body);
+            if (record === undefined ||
+                record.status === "deleted" ||
+                record.server.name.toLowerCase() !== id.toLowerCase()) {
+                throw new Error("registry returned no record for the requested server");
+            }
+            const entry = mapRemoteRecord(record, target.apiBase);
+            this.writeRemoteCache(cacheKey, entry, target);
+            return entry;
+        }
+        catch (error) {
+            this.reportRemoteError(target, "getEntry", error);
+            return undefined;
+        }
+    }
+    async fetchRemoteList(target, query) {
+        const cacheKey = `remote-list:${target.apiBase}:${(query ?? "").toLowerCase()}`;
+        const cached = this.readRemoteCache(cacheKey, target);
+        if (cached) {
+            return { entries: cached, ok: true };
+        }
+        try {
+            const configuredPages = target.config.maxPages;
+            const maxPages = configuredPages !== undefined && Number.isFinite(configuredPages)
+                ? Math.max(1, Math.floor(configuredPages))
+                : REMOTE_DEFAULT_MAX_PAGES;
+            const entries = [];
+            const seenCursors = new Set();
+            let cursor;
+            for (let page = 0; page < maxPages; page++) {
+                const params = new URLSearchParams({
+                    version: "latest",
+                    limit: String(REMOTE_PAGE_SIZE),
+                });
+                if (query) {
+                    params.set("search", query);
+                }
+                if (cursor) {
+                    params.set("cursor", cursor);
+                }
+                const response = await this.requestJson(target, "/servers", params);
+                const { records, nextCursor } = parseRemotePage(response.body);
+                entries.push(...records
+                    .filter((record) => record.status !== "deleted")
+                    .map((record) => mapRemoteRecord(record, target.apiBase)));
+                if (nextCursor === undefined || seenCursors.has(nextCursor)) {
+                    break;
+                }
+                if (page === maxPages - 1) {
+                    mcpLogger.debug(`[MCPRegistryClient] ${target.apiBase}: stopped after ${maxPages} page(s); more servers are available`);
+                    break;
+                }
+                seenCursors.add(nextCursor);
+                cursor = nextCursor;
+            }
+            this.writeRemoteCache(cacheKey, entries, target);
+            return { entries, ok: true };
+        }
+        catch (error) {
+            this.reportRemoteError(target, "list", error);
+            return { entries: [], ok: false };
+        }
+    }
+    /**
+     * GET a JSON document from a registry, bounded by its timeout. A 404
+     * resolves with an undefined body (a normal "not found"); any other
+     * non-2xx status, a network error, a timeout or a body that is not JSON
+     * rejects.
+     */
+    async requestJson(target, path, params) {
+        const url = new URL(`${target.apiBase}${path}`);
+        params?.forEach((value, key) => url.searchParams.set(key, value));
+        const headers = {
+            Accept: "application/json",
+            "User-Agent": this.config.userAgent,
+            ...(target.config.authToken
+                ? { Authorization: `Bearer ${target.config.authToken}` }
+                : {}),
+        };
+        const response = await globalThis.fetch(url, {
+            method: "GET",
+            headers,
+            signal: AbortSignal.timeout(target.config.timeout ?? this.config.timeout),
+        });
+        if (response.status === 404) {
+            await response.body?.cancel();
+            return { body: undefined };
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new Error(`registry responded with HTTP ${response.status}`);
+        }
+        return { body: await this.readBoundedJson(response) };
+    }
+    /**
+     * Parse a JSON body, refusing to buffer more than
+     * `REMOTE_MAX_RESPONSE_BYTES`. The request timeout bounds duration, not
+     * memory, so the size is checked while reading.
+     */
+    async readBoundedJson(response) {
+        const chunks = [];
+        let size = 0;
+        if (response.body) {
+            const reader = response.body.getReader();
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                size += value.byteLength;
+                if (size > REMOTE_MAX_RESPONSE_BYTES) {
+                    await reader.cancel();
+                    throw new Error(`registry response exceeds ${REMOTE_MAX_RESPONSE_BYTES} bytes`);
+                }
+                chunks.push(value);
+            }
+        }
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    reportRemoteError(target, operation, error) {
+        const baseMessage = error instanceof Error ? error.message : String(error);
+        // fetch() reports every connection failure as "fetch failed"; the code
+        // (ECONNREFUSED, ENOTFOUND, ...) sits on the cause.
+        const cause = error instanceof Error ? error.cause : undefined;
+        const causeCode = typeof cause === "object" && cause !== null && "code" in cause
+            ? String(cause.code)
+            : undefined;
+        const message = causeCode === undefined ? baseMessage : `${baseMessage} (${causeCode})`;
+        mcpLogger.debug(`[MCPRegistryClient] ${operation} failed for ${target.apiBase}: ${message}`);
+        try {
+            this.emit("registryError", {
+                registry: target.apiBase,
+                operation,
+                message,
+            });
+        }
+        catch (listenerError) {
+            // A throwing listener must not turn a degraded lookup into an error.
+            mcpLogger.debug(`[MCPRegistryClient] registryError listener threw: ${String(listenerError)}`);
+        }
+    }
+    readCache(key, ttl) {
+        const cached = this.cache.get(key);
+        // Each key is written with one shape only, so the cast matches the writer.
+        return cached && Date.now() - cached.timestamp < ttl
+            ? cached.data
+            : undefined;
+    }
+    readRemoteCache(key, target) {
+        return this.isRemoteCacheEnabled(target)
+            ? this.readCache(key, target.config.cacheTTL ?? this.config.defaultCacheTTL)
+            : undefined;
+    }
+    writeRemoteCache(key, data, target) {
+        if (this.isRemoteCacheEnabled(target)) {
+            this.writeCache(key, data);
+        }
+    }
+    /**
+     * The client-wide `enableCache: false` is a ceiling: a registry can switch
+     * its own caching off but cannot turn it back on.
+     */
+    isRemoteCacheEnabled(target) {
+        return this.config.enableCache && (target.config.enableCache ?? true);
+    }
+    writeCache(key, data) {
+        // Bound the cache: a long-lived client that searches many different
+        // queries must not grow without limit. Map iterates oldest first.
+        if (!this.cache.has(key) && this.cache.size >= CACHE_MAX_ENTRIES) {
+            const oldest = this.cache.keys().next();
+            if (!oldest.done) {
+                this.cache.delete(oldest.value);
+            }
+        }
+        this.cache.set(key, { data, timestamp: Date.now() });
+    }
     /**
      * Get entries by category
      */
@@ -400,6 +680,16 @@ export class MCPRegistryClient extends EventEmitter {
         const { authToken: _, ...safeConfig } = config;
         this.emit("registryAdded", { config: safeConfig });
     }
+    /**
+     * Turn remote lookup on or off at runtime, e.g. on the client returned by
+     * `NeuroLink.getMCPRegistryClient()`. Off is the default. Clears the cache
+     * so the next lookup reflects the new setting.
+     */
+    setRemoteLookup(enabled) {
+        this.config.remoteLookup = enabled;
+        this.clearCache();
+        this.emit("remoteLookupChanged", { enabled });
+    }
     /**
      * Clear the cache
      */

package/dist/mcp/mcpRegistryRemote.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Remote registry helpers for MCPRegistryClient
+ *
+ * Pure functions that resolve a registry configuration to an API base URL,
+ * validate responses from the official MCP Registry API (`/v0.1`) and map its
+ * server records to `McpRegistryEntry`. Nothing here performs I/O.
+ *
+ * API reference (spec `2025-12-01`):
+ * https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/openapi.yaml
+ *
+ * @module mcp/mcpRegistryRemote
+ */
+import type { McpRegistryEntry, RegistryConfig, RemoteRegistryPage, RemoteRegistryRecord, RemoteRegistryTarget } from "../types/index.js";
+/**
+ * Base URL of the official MCP Registry
+ */
+export declare const OFFICIAL_REGISTRY_URL = "https://registry.modelcontextprotocol.io";
+/**
+ * Resolve a registry configuration to the API base URL the client queries.
+ *
+ * Returns `undefined` for registries the client does not query: `npm` and
+ * `github` sources, a `custom` registry without a URL, any URL that is not
+ * plain `http(s)` or that embeds credentials (fetch rejects those, and they
+ * would end up in logs), and a registry with an `authToken` on plain `http:`
+ * to a non-loopback host (the bearer token would cross the network in clear).
+ */
+export declare function resolveRemoteTarget(config: RegistryConfig): RemoteRegistryTarget | undefined;
+/**
+ * Validate one `ServerResponse` (`{ server, _meta }`) from the registry.
+ * Returns `undefined` when it carries no usable server, so a bad record can
+ * be skipped without discarding its neighbours.
+ */
+export declare function parseRemoteRecord(value: unknown): RemoteRegistryRecord | undefined;
+/**
+ * Validate a `ServerList` response (`{ servers, metadata: { nextCursor } }`).
+ * Throws when `servers` is not an array, which the caller reports as a
+ * malformed registry; individual bad records are skipped.
+ */
+export declare function parseRemotePage(value: unknown): RemoteRegistryPage;
+/**
+ * Map a registry record to a catalog entry.
+ *
+ * Remote entries are never `verified`: that flag means "reviewed by NeuroLink"
+ * for the built-in catalog, and the registry's contents are the publishers'
+ * own claims. Only an `npm` package whose identifier and version are valid
+ * npm names gets a runnable `command`; anything else (other package types such
+ * as pypi, oci or nuget, or an npm package with a malformed identifier or
+ * version) is listed in `metadata.packages` only, for the caller to act on.
+ */
+export declare function mapRemoteRecord(record: RemoteRegistryRecord, apiBase: string): McpRegistryEntry;