@novorb/mcp-core 2.1.2 → 3.0.1

package/dist/bootstrap.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @novorb/mcp-core - Bootstrap
+ *
+ * `runMcpServer` is the one entry point shape for every MCP server:
+ *
+ *   1. logger init (name, rootDir)
+ *   2. env load (`loadEnv(schema)`, then the logger is reconfigured so LOG_* from the env file apply)
+ *   3. `setup` ONCE per process: clients, caches, DB handles, rate limiters (the shared state)
+ *   4. transport start: `create(shared, req)` builds a server per connection (stdio) / per request (HTTP)
+ *   2b. credentials: every declared credential registered, the env `check`s run once in parallel
+ *       (bounded by MCP_CREDENTIAL_CHECK_TIMEOUT_MS, skipped with MCP_CREDENTIAL_CHECKS=false; never fatal)
+ *   5. ONE "started" line (transport, version, http url) after the listener is bound
+ *
+ * Signals are owned here: SIGINT/SIGTERM close the transport, then `dispose(shared)`, then exit 0.
+ * Consumers install no handlers of their own. Name and version come from `<rootDir>/package.json`.
+ *
+ *   await runMcpServer({
+ *     rootDir: packageRootFrom(import.meta.url),
+ *     env: ENV_SCHEMA,
+ *     setup: ({ env }) => ({ client: new ApiClient(env.get('API_URL')) }),
+ *     create: (shared, req, { env, info }) => {
+ *       const server = createMcpServer(info.name, info.version);
+ *       registerTools(server, buildTools(shared), { env, serverName: info.name });
+ *       return server;
+ *     },
+ *   });
+ */
+import type { Implementation, ServerEventBus, ServerNotifier } from '@modelcontextprotocol/server';
+import { type CredentialRegistry } from './credentials.js';
+import { type CreateMcpServerOptions, type McpServer, type Server } from './server.js';
+import { type RequestContext, type TransportMode, type TransportOptions } from './transport.js';
+import { type EnvSchema, type LoadedEnv } from './utils/envLoader.js';
+import { type Logger, type LoggerOptions } from './utils/logger.js';
+export interface PackageInfo {
+    name: string;
+    version: string;
+    description?: string;
+}
+/** Read name, version and description from `<rootDir>/package.json`. Throws when it is missing or invalid. */
+export declare function readPackageInfo(rootDir: string): PackageInfo;
+/** What `setup` and `create` receive. */
+export interface SetupContext {
+    env: LoadedEnv;
+    logger: Logger;
+    info: PackageInfo;
+    rootDir: string;
+    /** The change-event bus every transport connection is served from (`RunMcpServerOptions.bus`). */
+    bus: ServerEventBus;
+    /** Publish list-changed / resource-updated events to every connection (see `notifications.ts`). */
+    notify: ServerNotifier;
+    /**
+     * The credential registry (startup checks already run). It is the process registry unless
+     * `RunMcpServerOptions.credentials` is set; pass it to `registerTools({ credentials })` in that case.
+     */
+    credentials: CredentialRegistry;
+    /**
+     * A fresh `McpServer` for this server: `createMcpServer` with the package identity (`name`,
+     * `version`, `description`) plus `RunMcpServerOptions.server` (Implementation fields and
+     * `McpServerOptions`). Call it once per `create`.
+     */
+    createServer(): McpServer;
+}
+/** Server identity and options `runMcpServer` passes to every `createServer()`. */
+export interface RunServerOptions extends CreateMcpServerOptions {
+    /** Implementation fields beyond name/version/description. */
+    title?: string;
+    websiteUrl?: string;
+    icons?: Implementation['icons'];
+}
+export interface RunMcpServerOptions<S> {
+    /** The server's package root: `packageRootFrom(import.meta.url)`. */
+    rootDir: string;
+    /** The server's own env schema (mcp-core's keys are merged in). */
+    env: EnvSchema;
+    /** Overrides package.json `name` (used for the logger and the started line). */
+    name?: string;
+    /** Overrides package.json `version`. */
+    version?: string;
+    /** Once per process: build the shared state (clients, caches, DB handles, rate limiters). */
+    setup?: (ctx: SetupContext) => Promise<S> | S;
+    /** Per connection (stdio) / per HTTP request: build a server over the shared state. */
+    create: (shared: S, req: RequestContext, ctx: SetupContext) => McpServer | Server;
+    /** On shutdown, after the transport is closed: release the shared state. */
+    dispose?: (shared: S) => Promise<void> | void;
+    /** Log uncaught exceptions / unhandled rejections, then exit 1 (default false). */
+    captureProcessErrors?: boolean;
+    /** Extra logger options (name and rootDir are set by runMcpServer). */
+    logger?: Omit<LoggerOptions, 'name' | 'rootDir' | 'captureProcessErrors'>;
+    /** Server identity and `McpServerOptions` for `ctx.createServer()`. */
+    server?: RunServerOptions;
+    /**
+     * Transport overrides; otherwise from the loaded env (MCP_TRANSPORT, PORT, MCP_HTTP_HOST,
+     * MCP_MAX_BODY_BYTES, MCP_ALLOWED_HOSTS, MCP_ALLOWED_ORIGINS, MCP_API_KEY). `auth.verifier` plugs a
+     * token verifier (for example JWTs) in place of the static key.
+     */
+    transport?: Omit<TransportOptions, 'handleSignals'>;
+    /** Throw on env validation errors instead of logging them (default false). */
+    strictEnv?: boolean;
+    /** Install SIGINT/SIGTERM handlers (default true). */
+    handleSignals?: boolean;
+    /** The environment to read and populate (default `process.env`). */
+    processEnv?: NodeJS.ProcessEnv;
+    /** The change-event bus (default the process bus; a shared pub/sub on multi-instance hosts). */
+    bus?: ServerEventBus;
+    /** The credential registry the startup checks fill (default the process registry). */
+    credentials?: CredentialRegistry;
+}
+export interface RunningServer<S> {
+    info: PackageInfo;
+    env: LoadedEnv;
+    shared: S;
+    /** The credential registry (startup check results, then live health). */
+    credentials: CredentialRegistry;
+    mode: TransportMode;
+    /** http only. */
+    host?: string;
+    port?: number;
+    url?: string;
+    /** Close the transport, then dispose the shared state. Idempotent; does not exit the process. */
+    close(): Promise<void>;
+}
+/**
+ * The transport options from the LOADED env (so `processEnv` and the env file reach the transport, and
+ * an invalid MCP_TRANSPORT throws), with explicit `overrides` winning.
+ */
+export declare function transportFromEnv(env: LoadedEnv, overrides?: Omit<TransportOptions, 'handleSignals'>): Omit<TransportOptions, 'handleSignals'>;
+/** Bootstrap an MCP server: logger, env, shared state, transport, started line, signals. */
+export declare function runMcpServer<S = undefined>(opts: RunMcpServerOptions<S>): Promise<RunningServer<S>>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

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

package/dist/bootstrap.js

@@ -0,0 +1,206 @@
+/**
+ * @novorb/mcp-core - Bootstrap
+ *
+ * `runMcpServer` is the one entry point shape for every MCP server:
+ *
+ *   1. logger init (name, rootDir)
+ *   2. env load (`loadEnv(schema)`, then the logger is reconfigured so LOG_* from the env file apply)
+ *   3. `setup` ONCE per process: clients, caches, DB handles, rate limiters (the shared state)
+ *   4. transport start: `create(shared, req)` builds a server per connection (stdio) / per request (HTTP)
+ *   2b. credentials: every declared credential registered, the env `check`s run once in parallel
+ *       (bounded by MCP_CREDENTIAL_CHECK_TIMEOUT_MS, skipped with MCP_CREDENTIAL_CHECKS=false; never fatal)
+ *   5. ONE "started" line (transport, version, http url) after the listener is bound
+ *
+ * Signals are owned here: SIGINT/SIGTERM close the transport, then `dispose(shared)`, then exit 0.
+ * Consumers install no handlers of their own. Name and version come from `<rootDir>/package.json`.
+ *
+ *   await runMcpServer({
+ *     rootDir: packageRootFrom(import.meta.url),
+ *     env: ENV_SCHEMA,
+ *     setup: ({ env }) => ({ client: new ApiClient(env.get('API_URL')) }),
+ *     create: (shared, req, { env, info }) => {
+ *       const server = createMcpServer(info.name, info.version);
+ *       registerTools(server, buildTools(shared), { env, serverName: info.name });
+ *       return server;
+ *     },
+ *   });
+ */
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { runCredentialChecks } from './credential-checks.js';
+import { processCredentials } from './credentials.js';
+import { createNotifier, processBus } from './notifications.js';
+import { createMcpServer } from './server.js';
+import { parseList, resolveTransportMode, startMcpServer, } from './transport.js';
+import { loadEnv } from './utils/envLoader.js';
+import { getLogger, initLogger } from './utils/logger.js';
+/** Read name, version and description from `<rootDir>/package.json`. Throws when it is missing or invalid. */
+export function readPackageInfo(rootDir) {
+    const file = path.join(rootDir, 'package.json');
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw new Error(`readPackageInfo: cannot read ${file}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const pkg = (typeof parsed === 'object' && parsed !== null ? parsed : {});
+    if (typeof pkg.name !== 'string' || pkg.name === '' || typeof pkg.version !== 'string' || pkg.version === '') {
+        throw new Error(`readPackageInfo: ${file} has no name or version`);
+    }
+    const info = { name: pkg.name, version: pkg.version };
+    if (typeof pkg.description === 'string')
+        info.description = pkg.description;
+    return info;
+}
+/** The logger file name for a package name: the npm scope is dropped (`@scope/x-mcp` -> `x-mcp`). */
+function loggerName(name) {
+    return name.replace(/^@[^/]+\//, '');
+}
+/**
+ * The transport options from the LOADED env (so `processEnv` and the env file reach the transport, and
+ * an invalid MCP_TRANSPORT throws), with explicit `overrides` winning.
+ */
+export function transportFromEnv(env, overrides = {}) {
+    const mode = resolveTransportMode(overrides.mode ?? env.get('MCP_TRANSPORT'));
+    const out = { ...overrides, mode };
+    const port = env.int('PORT');
+    if (out.port === undefined && port !== undefined)
+        out.port = port;
+    const host = env.get('MCP_HTTP_HOST');
+    if (out.host === undefined && host !== undefined)
+        out.host = host;
+    const maxBody = env.int('MCP_MAX_BODY_BYTES');
+    if (out.maxBodyBytes === undefined && maxBody !== undefined)
+        out.maxBodyBytes = maxBody;
+    out.allowedHosts ??= parseList(env.get('MCP_ALLOWED_HOSTS'));
+    out.allowedOrigins ??= parseList(env.get('MCP_ALLOWED_ORIGINS'));
+    if (out.apiKey === undefined && !out.auth?.verifier) {
+        out.apiKey = env.bool('MCP_AUTH_DISABLED') === true ? null : (env.get('MCP_API_KEY') ?? '');
+    }
+    return out;
+}
+/** Bootstrap an MCP server: logger, env, shared state, transport, started line, signals. */
+export async function runMcpServer(opts) {
+    const rootDir = path.resolve(opts.rootDir);
+    const pkg = opts.name !== undefined && opts.version !== undefined ? undefined : readPackageInfo(rootDir);
+    const info = {
+        ...(pkg ?? {}),
+        name: opts.name ?? pkg?.name ?? 'mcp-server',
+        version: opts.version ?? pkg?.version ?? '0.0.0',
+    };
+    const loggerOptions = {
+        ...opts.logger,
+        name: loggerName(info.name),
+        rootDir,
+        captureProcessErrors: opts.captureProcessErrors === true,
+    };
+    // 1. logger, so env-loading warnings are logged; 2. env; then reconfigure for LOG_* from the file.
+    initLogger(loggerOptions);
+    const env = loadEnv(opts.env, { rootDir, env: opts.processEnv ?? process.env, strict: opts.strictEnv === true });
+    const logger = initLogger(loggerOptions);
+    for (const e of env.errors)
+        logger.warn(`env ${e.key} ${e.message}`, 'Env');
+    // Credentials: registered from the env schema and checked ONCE (parallel, bounded); never fatal.
+    const credentials = opts.credentials ?? processCredentials();
+    try {
+        await runCredentialChecks(env, credentials, { logger });
+    }
+    catch (e) {
+        // Never fatal: the server starts with the credentials it could register.
+        logger.warn(`credential checks failed: ${e instanceof Error ? e.name : 'error'}`, 'Credentials');
+    }
+    const serverOptions = opts.server ?? {};
+    const bus = opts.bus ?? processBus();
+    const ctx = {
+        env,
+        logger,
+        info,
+        rootDir,
+        bus,
+        notify: createNotifier(bus),
+        credentials,
+        createServer: () => {
+            const { title, websiteUrl, icons, ...mcpOptions } = serverOptions;
+            return createMcpServer({
+                name: info.name,
+                version: info.version,
+                ...(info.description !== undefined ? { description: info.description } : {}),
+                ...(title !== undefined ? { title } : {}),
+                ...(websiteUrl !== undefined ? { websiteUrl } : {}),
+                ...(icons !== undefined ? { icons } : {}),
+            }, mcpOptions);
+        },
+    };
+    const transportOptions = transportFromEnv(env, opts.transport);
+    const shared = (opts.setup ? await opts.setup(ctx) : undefined);
+    let transport;
+    try {
+        transport = await startMcpServer((req) => opts.create(shared, req, ctx), {
+            ...transportOptions,
+            bus,
+            handleSignals: false,
+        });
+    }
+    catch (err) {
+        await Promise.resolve(opts.dispose?.(shared)).catch(() => undefined);
+        throw err;
+    }
+    let closing;
+    const shutdownAndExit = (reason) => {
+        getLogger().info(`${info.name} stopping (${reason})`, 'Server');
+        let code = 0;
+        close()
+            .catch((e) => {
+            code = 1;
+            getLogger().error(`shutdown failed: ${e instanceof Error ? e.message : String(e)}`, 'Server');
+        })
+            .finally(() => process.exit(code));
+    };
+    const onSignal = (signal) => shutdownAndExit(signal);
+    // The client closed the connection (stdio EOF): dispose the shared state and exit, so keep-alive
+    // handles created in `setup` (timers, pools, watchers) never orphan the process.
+    transport.closed.then(() => {
+        if (closing)
+            return;
+        if (opts.handleSignals === false) {
+            getLogger().info(`${info.name} stopping (transport closed)`, 'Server');
+            close().catch((e) => getLogger().error(`shutdown failed: ${e instanceof Error ? e.message : String(e)}`, 'Server'));
+            return;
+        }
+        shutdownAndExit('transport closed');
+    });
+    const close = () => {
+        closing ??= (async () => {
+            process.off('SIGINT', onSignal);
+            process.off('SIGTERM', onSignal);
+            try {
+                await transport.close();
+            }
+            finally {
+                await opts.dispose?.(shared);
+            }
+        })();
+        return closing;
+    };
+    if (opts.handleSignals !== false) {
+        process.on('SIGINT', onSignal);
+        process.on('SIGTERM', onSignal);
+    }
+    const meta = { version: info.version, transport: transport.mode };
+    if (transport.url)
+        Object.assign(meta, { host: transport.host, port: transport.port, url: transport.url });
+    logger.info(`${info.name} started`, 'Server', meta);
+    return {
+        info,
+        env,
+        shared,
+        credentials,
+        mode: transport.mode,
+        ...(transport.host !== undefined ? { host: transport.host } : {}),
+        ...(transport.port !== undefined ? { port: transport.port } : {}),
+        ...(transport.url !== undefined ? { url: transport.url } : {}),
+        close,
+    };
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/bootstrap.js.map

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

package/dist/client-input.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @novorb/mcp-core - Client input (elicitation, sampling, roots)
+ *
+ * Era-blind helpers over the SDK's multi-round-trip mechanism (MRTR, `inputRequired(...)`): a handler
+ * asks for input by RETURNING an input-required result, and is re-entered with the client's answer in
+ * `ctx.mcpReq.inputResponses`. This is how the SDK serves both eras from one handler:
+ *
+ * - 2026-07-28: the client fulfils the embedded requests and retries the call;
+ * - 2025-era connections: the SDK's legacy shim (on by default) sends real server-to-client requests
+ *   and re-enters the handler itself.
+ *
+ * Each helper first reads the answer for its `key`; when there is none it checks the client's declared
+ * capability and answers either `{ status: 'pending', result }` (return `result` from the handler) or
+ * `{ status: 'unsupported', reason }` (never a throw). Stateless HTTP serves every 2025-era request on
+ * a fresh instance that never saw `initialize`, so no client capability is known there and every
+ * helper answers `unsupported`; stdio and 2026-07-28 clients declare theirs.
+ *
+ * Sampling and roots are deprecated by the 2026-07-28 revision (SEP-2577) but remain functional for at
+ * least twelve months; elicitation is not deprecated.
+ */
+import { type ClientCapabilities, type CreateMessageRequestParams, type CreateMessageResult, type CreateMessageResultWithTools, type ElicitInputParams, type ElicitRequestURLParams, type InputRequiredResult, type Root, type ServerContext, type StandardSchemaWithJSON } from '@modelcontextprotocol/server';
+/** The protocol era of the request being handled. */
+export type RequestEra = 'modern' | 'legacy';
+/** The outcome of asking the client for input. */
+export type InputOutcome<T> = 
+/** The client answered (an accepted elicitation, a sampling result, the roots). */
+{
+    status: 'accepted';
+    value: T;
+}
+/** The user declined the elicitation. */
+ | {
+    status: 'declined';
+}
+/** The user cancelled the elicitation. */
+ | {
+    status: 'cancelled';
+}
+/** An accepted elicitation whose content failed the requested schema. */
+ | {
+    status: 'invalid';
+}
+/** No answer yet: return `result` from the handler; the handler is re-entered with the answer. */
+ | {
+    status: 'pending';
+    result: InputRequiredResult;
+}
+/** The client cannot answer (capability not declared, or no capability information at all). */
+ | {
+    status: 'unsupported';
+    reason: string;
+};
+/** Elicitation parameters whose `requestedSchema` is a Standard Schema (the content is validated). */
+export type TypedElicitParams<S extends StandardSchemaWithJSON> = Omit<ElicitInputParams, 'requestedSchema'> & {
+    requestedSchema: S;
+};
+export type ClientFeature = 'elicitation' | 'elicitation.url' | 'sampling' | 'roots';
+/** The era of a request: modern when it carries the 2026-07-28 per-request envelope. */
+export declare function requestEra(sdk: ServerContext): RequestEra;
+/** Whether `caps` declares `feature`. A bare `elicitation: {}` means form mode only (2025-11-25). */
+export declare function supportsClientFeature(caps: ClientCapabilities | undefined, feature: ClientFeature): boolean;
+/** The per-request client input helpers; `caps` is the client's declared capabilities. */
+export interface ClientInput {
+    elicit<S extends StandardSchemaWithJSON>(key: string, params: TypedElicitParams<S>): InputOutcome<StandardSchemaWithJSON.InferOutput<S>>;
+    elicit(key: string, params: ElicitInputParams): InputOutcome<Record<string, unknown>>;
+    elicitUrl(key: string, params: Omit<ElicitRequestURLParams, 'mode' | 'elicitationId'>): InputOutcome<true>;
+    sample(key: string, params: CreateMessageRequestParams): InputOutcome<CreateMessageResult | CreateMessageResultWithTools>;
+    listRoots(key?: string): InputOutcome<Root[]>;
+}
+/** Build the helpers for one request. Without an SDK context every helper answers `unsupported`. */
+export declare function createClientInput(sdk: ServerContext | undefined, caps: ClientCapabilities | undefined): ClientInput;
+//# sourceMappingURL=client-input.d.ts.map

package/dist/client-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-input.d.ts","sourceRoot":"","sources":["../src/client-input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAE3B,KAAK,mBAAmB,EAIxB,KAAK,IAAI,EACT,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC5B,MAAM,8BAA8B,CAAC;AAEtC,qDAAqD;AACrD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7C,kDAAkD;AAClD,MAAM,MAAM,YAAY,CAAC,CAAC;AACxB,mFAAmF;AACjF;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE;AAClC,yCAAyC;GACvC;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE;AACxB,0CAA0C;GACxC;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE;AACzB,yEAAyE;GACvE;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE;AACvB,kGAAkG;GAChG;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE;AACpD,+FAA+F;GAC7F;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C,sGAAsG;AACtG,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,sBAAsB,IAAI,IAAI,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,GAAG;IAC7G,eAAe,EAAE,CAAC,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,iBAAiB,GAAG,UAAU,GAAG,OAAO,CAAC;AAErF,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,GAAG,UAAU,CAGzD;AAED,qGAAqG;AACrG,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,kBAAkB,GAAG,SAAS,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAa3G;AAkBD,0FAA0F;AAC1F,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,CAAC,SAAS,sBAAsB,EACrC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC3B,YAAY,CAAC,sBAAsB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACtF,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,eAAe,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC3G,MAAM,CACJ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,0BAA0B,GACjC,YAAY,CAAC,mBAAmB,GAAG,4BAA4B,CAAC,CAAC;IACpE,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;CAC/C;AAED,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,SAAS,EAAE,IAAI,EAAE,kBAAkB,GAAG,SAAS,GAAG,WAAW,CA4CnH"}

package/dist/client-input.js

@@ -0,0 +1,109 @@
+/**
+ * @novorb/mcp-core - Client input (elicitation, sampling, roots)
+ *
+ * Era-blind helpers over the SDK's multi-round-trip mechanism (MRTR, `inputRequired(...)`): a handler
+ * asks for input by RETURNING an input-required result, and is re-entered with the client's answer in
+ * `ctx.mcpReq.inputResponses`. This is how the SDK serves both eras from one handler:
+ *
+ * - 2026-07-28: the client fulfils the embedded requests and retries the call;
+ * - 2025-era connections: the SDK's legacy shim (on by default) sends real server-to-client requests
+ *   and re-enters the handler itself.
+ *
+ * Each helper first reads the answer for its `key`; when there is none it checks the client's declared
+ * capability and answers either `{ status: 'pending', result }` (return `result` from the handler) or
+ * `{ status: 'unsupported', reason }` (never a throw). Stateless HTTP serves every 2025-era request on
+ * a fresh instance that never saw `initialize`, so no client capability is known there and every
+ * helper answers `unsupported`; stdio and 2026-07-28 clients declare theirs.
+ *
+ * Sampling and roots are deprecated by the 2026-07-28 revision (SEP-2577) but remain functional for at
+ * least twelve months; elicitation is not deprecated.
+ */
+import { acceptedContent, inputRequired, inputResponse, PROTOCOL_VERSION_META_KEY, } from '@modelcontextprotocol/server';
+/** The era of a request: modern when it carries the 2026-07-28 per-request envelope. */
+export function requestEra(sdk) {
+    const envelope = sdk.mcpReq.envelope;
+    return envelope?.[PROTOCOL_VERSION_META_KEY] !== undefined ? 'modern' : 'legacy';
+}
+/** Whether `caps` declares `feature`. A bare `elicitation: {}` means form mode only (2025-11-25). */
+export function supportsClientFeature(caps, feature) {
+    if (!caps)
+        return false;
+    const elicitation = caps.elicitation;
+    switch (feature) {
+        case 'elicitation':
+            return elicitation !== undefined && (elicitation.form !== undefined || elicitation.url === undefined);
+        case 'elicitation.url':
+            return elicitation?.url !== undefined;
+        case 'sampling':
+            return caps.sampling !== undefined;
+        case 'roots':
+            return caps.roots !== undefined;
+    }
+}
+function unsupported(feature, caps) {
+    const reason = caps === undefined
+        ? `${feature} is not supported by this client: no client capabilities are known for this request (stateless HTTP 2025-era requests carry none)`
+        : `${feature} is not supported by this client: it did not declare the ${feature} capability`;
+    return { status: 'unsupported', reason };
+}
+function pending(key, request) {
+    return { status: 'pending', result: inputRequired({ inputRequests: { [key]: request } }) };
+}
+function isStandardSchema(value) {
+    return typeof value === 'object' && value !== null && '~standard' in value;
+}
+/** Build the helpers for one request. Without an SDK context every helper answers `unsupported`. */
+export function createClientInput(sdk, caps) {
+    const responses = sdk?.mcpReq.inputResponses;
+    const known = sdk ? caps : undefined;
+    function elicit(key, params) {
+        const view = inputResponse(responses, key);
+        if (view.kind === 'elicit') {
+            if (view.action === 'decline')
+                return { status: 'declined' };
+            if (view.action === 'cancel')
+                return { status: 'cancelled' };
+            if (isStandardSchema(params.requestedSchema)) {
+                const value = acceptedContent(responses, key, params.requestedSchema);
+                return value === undefined ? { status: 'invalid' } : { status: 'accepted', value };
+            }
+            return { status: 'accepted', value: view.content ?? {} };
+        }
+        if (!supportsClientFeature(known, 'elicitation'))
+            return unsupported('elicitation', known);
+        return pending(key, inputRequired.elicit(params));
+    }
+    return {
+        elicit: elicit,
+        elicitUrl(key, params) {
+            const view = inputResponse(responses, key);
+            if (view.kind === 'elicit') {
+                if (view.action === 'decline')
+                    return { status: 'declined' };
+                if (view.action === 'cancel')
+                    return { status: 'cancelled' };
+                return { status: 'accepted', value: true };
+            }
+            if (!supportsClientFeature(known, 'elicitation.url'))
+                return unsupported('elicitation.url', known);
+            return pending(key, inputRequired.elicitUrl(params));
+        },
+        sample(key, params) {
+            const view = inputResponse(responses, key);
+            if (view.kind === 'sampling')
+                return { status: 'accepted', value: view.result };
+            if (!supportsClientFeature(known, 'sampling'))
+                return unsupported('sampling', known);
+            return pending(key, inputRequired.createMessage(params));
+        },
+        listRoots(key = 'roots') {
+            const view = inputResponse(responses, key);
+            if (view.kind === 'roots')
+                return { status: 'accepted', value: view.roots };
+            if (!supportsClientFeature(known, 'roots'))
+                return unsupported('roots', known);
+            return pending(key, inputRequired.listRoots());
+        },
+    };
+}
+//# sourceMappingURL=client-input.js.map

package/dist/client-input.js.map

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

package/dist/credential-checks.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @novorb/mcp-core - Startup credential checks
+ *
+ * `runMcpServer` registers every credential the env schema declares (a server's own `secret` keys and
+ * every key with a `check`; each member of a `multi` family on its own, pooled under the family's base
+ * key) and then runs the declared checks ONCE, in parallel, each bounded by
+ * `MCP_CREDENTIAL_CHECK_TIMEOUT_MS` (default 5000). `MCP_CREDENTIAL_CHECKS=false` skips them. A check
+ * never stops the server: a throw, a timeout or a network error reads `unknown`, and the results are
+ * logged by key name and status only.
+ *
+ *   {
+ *     key: 'SEARCH_API_KEY', multi: true, secret: true,
+ *     check: async (value, { http, signal }) => {
+ *       await http({ baseURL: 'https://api.example.com', auth: { type: 'bearer', token: value } })
+ *         .get('/account', { signal });
+ *       return 'valid';
+ *     },
+ *   }
+ *
+ * A check may return a status, `{ status, reason?, retryAfterMs? }`, or throw: a thrown `HttpError`
+ * is classified like any HTTP outcome (401/403 invalid, 402/429 degraded, ...).
+ */
+import { type CredentialOutcomeInfo, type CredentialRegistry, type CredentialStatus } from './credentials.js';
+import { type HttpClientConfig, type McpHttpClient } from './http-client.js';
+import { type LoadedEnv } from './utils/envLoader.js';
+import { type Logger } from './utils/logger.js';
+export interface CredentialCheckContext {
+    /** The credential's key name (`KEY` or a family member `KEY_2`). */
+    key: string;
+    /** Aborted when the check times out. */
+    signal: AbortSignal;
+    /** A hardened http-client for the probe (retries off by default, the check timeout as its timeout). */
+    http(config: HttpClientConfig): McpHttpClient;
+    /**
+     * The loaded value of a sibling DECLARED env key (a multi-part credential: client id + secret, key +
+     * secret, user + password), or undefined when unset. Throws `UnknownCredentialError` for a key the
+     * schema does not declare. Values are never logged; declare the siblings `secret: true` so the logger
+     * masks them too.
+     */
+    get(key: string): string | undefined;
+}
+export interface CredentialCheckResult extends CredentialOutcomeInfo {
+    status: CredentialStatus;
+}
+/** A server-supplied probe for one credential value. */
+export type CredentialCheck = (value: string, ctx: CredentialCheckContext) => Promise<CredentialStatus | CredentialCheckResult>;
+export declare const DEFAULT_CREDENTIAL_CHECK_TIMEOUT_MS = 5000;
+/**
+ * Register the env's credentials in `registry`: every set value of a spec with a `check`, and of every
+ * `secret` spec that is not one of mcp-core's own keys. A multi family's members are pooled under the
+ * base key. Returns the registered key names with their checks.
+ */
+export declare function registerEnvCredentials(env: LoadedEnv, registry: CredentialRegistry): Array<{
+    key: string;
+    check?: CredentialCheck;
+}>;
+export interface RunCredentialChecksOptions {
+    /** Per-check timeout (default MCP_CREDENTIAL_CHECK_TIMEOUT_MS, else 5000 ms). */
+    timeoutMs?: number;
+    /** Run the checks (default MCP_CREDENTIAL_CHECKS, else true). */
+    enabled?: boolean;
+    /** How many checks run at once (default 4), so a large pool does not trip its provider's rate limit. */
+    concurrency?: number;
+    /** Re-check cool-down for invalid/expired keys (default MCP_CREDENTIAL_RECHECK_MS, else 300000 ms). */
+    recheckMs?: number;
+    logger?: Logger;
+}
+export declare const DEFAULT_CREDENTIAL_CHECK_CONCURRENCY = 4;
+/**
+ * Register the env's credentials and run their checks once (at most `concurrency` at a time, each with
+ * a timeout), then attach each check as the key's re-check probe (run again after the
+ * MCP_CREDENTIAL_RECHECK_MS cool-down while the key is invalid or expired). Never throws; logs one
+ * summary line (key names and statuses only). Resolves with the checked keys' results.
+ */
+export declare function runCredentialChecks(env: LoadedEnv, registry: CredentialRegistry, options?: RunCredentialChecksOptions): Promise<Array<{
+    key: string;
+    status: CredentialStatus;
+    reason?: string;
+}>>;
+//# sourceMappingURL=credential-checks.d.ts.map

package/dist/credential-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-checks.d.ts","sourceRoot":"","sources":["../src/credential-checks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EAGtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAoB,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC/F,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAa,KAAK,MAAM,EAAoB,MAAM,mBAAmB,CAAC;AAE7E,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,wCAAwC;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,uGAAuG;IACvG,IAAI,CAAC,MAAM,EAAE,gBAAgB,GAAG,aAAa,CAAC;IAC9C;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,qBAAsB,SAAQ,qBAAqB;IAClE,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,wDAAwD;AACxD,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,sBAAsB,KACxB,OAAO,CAAC,gBAAgB,GAAG,qBAAqB,CAAC,CAAC;AAEvD,eAAO,MAAM,mCAAmC,OAAO,CAAC;AAIxD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,kBAAkB,GAC3B,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,eAAe,CAAA;CAAE,CAAC,CAqBjD;AAED,MAAM,WAAW,0BAA0B;IACzC,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wGAAwG;IACxG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsED,eAAO,MAAM,oCAAoC,IAAI,CAAC;AAoBtD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CA+C5E"}