@mcp-layer/gateway 0.2.1 → 0.2.3

package/README.md

@@ -35,7 +35,7 @@ Use this package when you are building an interface layer on top of MCP that nee
 
 This example demonstrates how adapter packages bootstrap runtime state once and reuse it per request. This matters because repeated catalog extraction and ad-hoc breaker creation quickly cause drift between adapters.
 
-Expected behavior: one runtime context is created per bootstrap session, with a stable prefix/version and reusable resolver/validator/executor primitives.
+Expected behavior: one runtime context is created per bootstrap session or precomputed catalog, with a stable prefix/version and reusable resolver/validator/executor primitives.
 
 ```js
 import { createRuntime, createMap } from '@mcp-layer/gateway';
@@ -81,7 +81,8 @@ Signature:
 ```ts
 createRuntime(
   options: {
-    session: Session | Session[];
+    session?: Session | Session[];
+    catalog?: { server?: { info?: Record<string, unknown> }, items?: Array<Record<string, unknown>> };
     manager?: { get(request): Promise<Session>; close?(): Promise<void> };
     prefix?: string | ((version, info, sessionName) => string);
     validation?: {
@@ -117,7 +118,7 @@ createRuntime(
 ): Promise<{
   config;
   contexts: Array<{
-    session;
+    session | undefined;
     catalog;
     info;
     version;
@@ -136,7 +137,9 @@ createRuntime(
 
 Behavior notes:
 
-- `manager` requires a bootstrap `session` (catalog extraction source).
+- `manager` requires either a bootstrap `session` or a precomputed `catalog`.
+- when a bootstrap `session` exists, runtime metadata is always extracted from that live session.
+- `catalog` bootstrap is only used when manager mode has no bootstrap session yet.
 - manager mode does not support `session` arrays.
 - `close()` shuts down breaker instances and calls `manager.close()` when available.
 - validation registration is preloaded from catalog tool/prompt input schemas.
@@ -278,12 +281,12 @@ Thrown from: `validateRuntimeOptions`
 This happens when `manager` is provided with `session` as an array.
 
 Step-by-step resolution:
-1. In manager mode, provide exactly one bootstrap session.
+1. In manager mode, provide exactly one bootstrap session or one precomputed catalog.
 2. If you need multiple static sessions, remove manager mode.
 3. Register separate adapter instances for each static session surface.
 4. Add explicit startup tests for manager mode vs multi-session mode.
 
-This example demonstrates valid manager-mode bootstrapping. This matters because manager mode resolves sessions per request and needs one catalog source at startup. Expected behavior: runtime initializes and delegates per-request resolution through manager.
+This example demonstrates valid manager-mode bootstrapping. This matters because manager mode resolves sessions per request and still needs one catalog source at startup. Expected behavior: runtime initializes and delegates per-request resolution through manager.
 
 <details>
 <summary>Fix Example: manager mode with one bootstrap session</summary>
@@ -297,20 +300,20 @@ await createRuntime({
 
 </details>
 
-<a id="error-c773d9"></a>
-### `session is required when manager is provided (used for catalog bootstrap).`
+<a id="error-b010d3"></a>
+### `session or catalog is required when manager is provided (used for catalog bootstrap).`
 
 Thrown from: `validateRuntimeOptions`
 
-This happens when `manager` is configured without a bootstrap `session`.
+This happens when `manager` is configured without a bootstrap `session` or a precomputed `catalog`.
 
 Step-by-step resolution:
-1. Provide a bootstrap session alongside manager.
-2. Ensure bootstrap session connects before runtime creation.
-3. Keep bootstrap session aligned with manager-provided session capabilities.
+1. Provide a bootstrap `session` or a precomputed `catalog` alongside manager.
+2. Ensure bootstrap session connects before runtime creation, or ensure the catalog matches the manager-provided session surface.
+3. Keep the catalog aligned with manager-provided session capabilities.
 4. Add a startup test that asserts this requirement.
 
-This example shows manager mode with explicit bootstrap catalog source. This matters because the runtime must extract catalog metadata at initialization time. Expected behavior: runtime can build validators and route metadata before serving requests.
+This example shows manager mode with explicit bootstrap catalog source. This matters because the runtime must know route and validator metadata before serving requests. Expected behavior: runtime can build validators and route metadata before request execution begins.
 
 <details>
 <summary>Fix Example: include bootstrap session when manager is enabled</summary>
@@ -324,6 +327,50 @@ await createRuntime({
 
 </details>
 
+<details>
+<summary>Fix Example: include catalog when manager is enabled</summary>
+
+```js
+await createRuntime({
+  catalog,
+  manager
+});
+```
+
+</details>
+
+<a id="error-17712f"></a>
+### `catalog must be an object.`
+
+Thrown from: `validateRuntimeOptions`
+
+This happens when `catalog` is provided as a primitive, array, or other non-object value.
+
+Step-by-step resolution:
+1. Pass the extracted or composed catalog as a plain object.
+2. Do not pass serialized JSON strings or arrays in place of the catalog root.
+3. Ensure the object shape includes `server` and `items` only where needed.
+4. Add tests that reject malformed catalog bootstrap values.
+
+This example shows valid catalog bootstrap input. This matters because manager mode can depend on catalog metadata before any request-scoped session exists. Expected behavior: runtime accepts the catalog and registers validators and route metadata from it.
+
+<details>
+<summary>Fix Example: pass catalog as an object</summary>
+
+```js
+await createRuntime({
+  catalog: {
+    server: {
+      info: { name: 'example-server', version: '1.0.0' }
+    },
+    items: []
+  },
+  manager
+});
+```
+
+</details>
+
 <a id="error-6e22f2"></a>
 ### `session or manager option is required.`
 
@@ -333,7 +380,7 @@ This happens when runtime options include neither `session` nor `manager`.
 
 Step-by-step resolution:
 1. Pass a connected `session` for static mode.
-2. Or pass `manager` plus a bootstrap `session` for dynamic mode.
+2. Or pass `manager` plus a bootstrap `session` or `catalog` for dynamic mode.
 3. Add adapter-level assertions before calling `createRuntime`.
 4. Add tests that verify startup failure without session sources.
 
@@ -463,6 +510,40 @@ await createRuntime({
 
 </details>
 
+<a id="error-a05713"></a>
+### `No session available for request resolution.`
+
+Thrown from: `resolveSession`
+
+This happens when request-time session resolution returns `undefined` and no bootstrap session was available to fall back to.
+
+Step-by-step resolution:
+1. Verify manager mode always returns a `Session` from `get(request)`.
+2. Ensure static mode passes a connected bootstrap `session`.
+3. Confirm request routing reaches the adapter instance backed by the expected manager or session.
+4. Add a request-path test that exercises the failing resolution path directly.
+
+This example demonstrates a manager that always resolves a concrete session. This matters because runtime execution cannot validate or execute MCP methods without a request-scoped target session. Expected behavior: each request resolves a session and proceeds to breaker-backed execution.
+
+<details>
+<summary>Fix Example: always return a session from manager.get</summary>
+
+```js
+const manager = {
+  async get(request) {
+    const session = await lookupSession(request);
+    if (!session) throw new Error('session lookup failed');
+    return session;
+  }
+};
+await createRuntime({
+  catalog,
+  manager
+});
+```
+
+</details>
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-layer/gateway",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Shared runtime primitives for MCP HTTP/GraphQL adapters with validation, resilience, telemetry, and catalog mapping.",
   "repository": {
     "type": "git",
@@ -36,13 +36,13 @@
     "access": "public"
   },
   "dependencies": {
-    "ajv": "^8.17.0",
+    "ajv": "^8.20.0",
     "ajv-formats": "^3.0.0",
     "json-schema-traverse": "^1.0.0",
     "opossum": "^8.1.0",
     "safe-regex2": "^2.0.0",
     "@mcp-layer/error": "0.2.1",
-    "@mcp-layer/schema": "1.0.3"
+    "@mcp-layer/schema": "2.0.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0"
@@ -53,8 +53,8 @@
     }
   },
   "devDependencies": {
-    "fastify": "^5.7.4",
-    "@mcp-layer/attach": "1.1.2",
+    "fastify": "^5.12.6",
+    "@mcp-layer/attach": "1.2.0",
     "@mcp-layer/manager": "0.2.1",
     "@mcp-layer/test-server": "1.0.4"
   },

package/src/config/validate.js

@@ -59,7 +59,7 @@ function trustMode(value, pack) {
  * Validate base runtime options and apply defaults.
  * @param {Record<string, unknown>} opts - User-supplied options.
  * @param {{ name?: string, serviceName?: string }} [meta] - Validation metadata.
- * @returns {{ session: unknown, manager?: { get: (request: import('fastify').FastifyRequest) => Promise<import('@mcp-layer/session').Session>, close?: () => Promise<void> }, prefix?: string | ((version: string, info: Record<string, unknown> | undefined, name: string) => string), validation: { trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }, resilience: { enabled: boolean, timeout: number, errorThresholdPercentage: number, resetTimeout: number, volumeThreshold: number }, telemetry: { enabled: boolean, serviceName: string, metricPrefix: string, api?: import('@opentelemetry/api') }, errors: { exposeDetails: boolean }, normalizeError?: (error: Error & { code?: string | number }, instance: string, requestId?: string, options?: { exposeDetails?: boolean }) => unknown }}
+ * @returns {{ session?: unknown, catalog?: { server?: { info?: Record<string, unknown> }, items?: Array<Record<string, unknown>> }, manager?: { get: (request: import('fastify').FastifyRequest) => Promise<import('@mcp-layer/session').Session>, close?: () => Promise<void> }, prefix?: string | ((version: string, info: Record<string, unknown> | undefined, name: string) => string), validation: { trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }, resilience: { enabled: boolean, timeout: number, errorThresholdPercentage: number, resetTimeout: number, volumeThreshold: number }, telemetry: { enabled: boolean, serviceName: string, metricPrefix: string, api?: import('@opentelemetry/api') }, errors: { exposeDetails: boolean }, normalizeError?: (error: Error & { code?: string | number }, instance: string, requestId?: string, options?: { exposeDetails?: boolean }) => unknown }}
  */
 export function validateRuntimeOptions(opts, meta = {}) {
   const pack = typeof meta.name === 'string' && meta.name.length > 0 ? meta.name : 'gateway';
@@ -69,6 +69,7 @@ export function validateRuntimeOptions(opts, meta = {}) {
   const base = defaults(serviceName);
   const input = isrecord(opts) ? opts : {};
   const session = input.session;
+  const catalog = input.catalog;
   const manager = input.manager;
 
   if (!session && !manager) {
@@ -79,6 +80,14 @@ export function validateRuntimeOptions(opts, meta = {}) {
     });
   }
 
+  if (catalog !== undefined && !isrecord(catalog)) {
+    throw new LayerError({
+      name: pack,
+      method: 'validateRuntimeOptions',
+      message: 'catalog must be an object.',
+    });
+  }
+
   if (manager !== undefined) {
     if (!isrecord(manager) || typeof manager.get !== 'function') {
       throw new LayerError({
@@ -87,11 +96,11 @@ export function validateRuntimeOptions(opts, meta = {}) {
         message: 'manager must be an object with a get(request) function.',
       });
     }
-    if (!session) {
+    if (!session && !catalog) {
       throw new LayerError({
         name: pack,
         method: 'validateRuntimeOptions',
-        message: 'session is required when manager is provided (used for catalog bootstrap).',
+        message: 'session or catalog is required when manager is provided (used for catalog bootstrap).',
       });
     }
     if (Array.isArray(session)) {
@@ -154,6 +163,7 @@ export function validateRuntimeOptions(opts, meta = {}) {
 
   return {
     session,
+    catalog: /** @type {{ server?: { info?: Record<string, unknown> }, items?: Array<Record<string, unknown>> } | undefined} */ (catalog),
     manager: /** @type {{ get: (request: import('fastify').FastifyRequest) => Promise<import('@mcp-layer/session').Session>, close?: () => Promise<void> } | undefined} */ (manager),
     prefix: input.prefix,
     validation: normalizedValidation,

package/src/runtime.js

@@ -1,4 +1,5 @@
 import { extract } from '@mcp-layer/schema';
+import { LayerError } from '@mcp-layer/error';
 import { createValidator } from './validation/validator.js';
 import { createCircuitBreaker, executeWithBreaker } from './resilience/breaker.js';
 import { deriveApiVersion, resolvePrefix } from './version.js';
@@ -14,6 +15,28 @@ function list(session) {
   return Array.isArray(session) ? session : [session];
 }
 
+/**
+ * Resolve the logical context name used for prefix callbacks.
+ * Prefer the explicit session name, then the catalog server name, and finally a
+ * stable fallback so catalog-driven manager mode can register routes without a
+ * bootstrap session.
+ *
+ * @param {import('@mcp-layer/session').Session | undefined} session - Optional bootstrap session.
+ * @param {Record<string, unknown> | undefined} info - Catalog server metadata.
+ * @returns {string}
+ */
+function contextName(session, info) {
+  if (session && typeof session.name === 'string' && session.name.length > 0) {
+    return session.name;
+  }
+
+  if (info && typeof info.name === 'string' && info.name.length > 0) {
+    return String(info.name);
+  }
+
+  return 'session';
+}
+
 /**
  * Register tool and prompt validators from a catalog.
  * @param {import('./validation/validator.js').SchemaValidator} validator - Schema validator.
@@ -69,7 +92,7 @@ function ensureBreaker(breakers, session, config, telemetry) {
 
 /**
  * Resolve request-scoped session and breaker.
- * @param {import('@mcp-layer/session').Session} bootstrap - Bootstrap session.
+ * @param {import('@mcp-layer/session').Session | undefined} bootstrap - Optional bootstrap session.
  * @param {{ manager?: { get: (request: import('fastify').FastifyRequest) => Promise<import('@mcp-layer/session').Session> }, resilience: { enabled: boolean, timeout: number, errorThresholdPercentage: number, resetTimeout: number, volumeThreshold: number } }} config - Runtime config.
  * @param {Map<string, import('opossum')>} breakers - Breaker storage.
  * @param {ReturnType<import('./telemetry/index.js').createTelemetry> | null} telemetry - Telemetry helper.
@@ -78,6 +101,13 @@ function ensureBreaker(breakers, session, config, telemetry) {
  */
 async function resolveSession(bootstrap, config, breakers, telemetry, request) {
   const target = config.manager ? await config.manager.get(request) : bootstrap;
+  if (!target) {
+    throw new LayerError({
+      name: 'gateway',
+      method: 'resolveSession',
+      message: 'No session available for request resolution.',
+    });
+  }
   const breaker = ensureBreaker(breakers, target, config.resilience, telemetry);
   return { session: target, breaker };
 }
@@ -86,11 +116,13 @@ async function resolveSession(bootstrap, config, breakers, telemetry, request) {
  * Create shared runtime contexts for MCP adapters.
  * @param {Record<string, unknown>} opts - Runtime options.
  * @param {{ name?: string, serviceName?: string }} [meta] - Runtime metadata.
- * @returns {Promise<{ config: ReturnType<typeof validateRuntimeOptions>, contexts: Array<{ session: import('@mcp-layer/session').Session, catalog: { server?: { info?: Record<string, unknown> }, items?: Array<Record<string, unknown>> }, info: Record<string, unknown> | undefined, version: string, prefix: string, validator: import('./validation/validator.js').SchemaValidator, telemetry: ReturnType<typeof createTelemetry> | null, resolve: (request: import('fastify').FastifyRequest) => Promise<{ session: import('@mcp-layer/session').Session, breaker: import('opossum') | null }>, execute: (request: import('fastify').FastifyRequest, method: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>, normalize: (error: Error & { code?: string | number }, instance: string, requestId?: string) => unknown }>, breakers: Map<string, import('opossum')>, normalize: (error: Error & { code?: string | number }, instance: string, requestId?: string) => unknown, close: () => Promise<void> }>}
+ * @returns {Promise<{ config: ReturnType<typeof validateRuntimeOptions>, contexts: Array<{ session: import('@mcp-layer/session').Session | undefined, catalog: { server?: { info?: Record<string, unknown> }, items?: Array<Record<string, unknown>> }, info: Record<string, unknown> | undefined, version: string, prefix: string, validator: import('./validation/validator.js').SchemaValidator, telemetry: ReturnType<typeof createTelemetry> | null, resolve: (request: import('fastify').FastifyRequest) => Promise<{ session: import('@mcp-layer/session').Session, breaker: import('opossum') | null }>, execute: (request: import('fastify').FastifyRequest, method: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>, normalize: (error: Error & { code?: string | number }, instance: string, requestId?: string) => unknown }>, breakers: Map<string, import('opossum')>, normalize: (error: Error & { code?: string | number }, instance: string, requestId?: string) => unknown, close: () => Promise<void> }>}
  */
 export async function createRuntime(opts, meta = {}) {
   const config = validateRuntimeOptions(opts, meta);
-  const sessions = config.manager ? [config.session] : list(config.session);
+  const sessions = config.manager
+    ? (config.session ? [config.session] : [])
+    : list(config.session);
   const breakers = new Map();
   const contexts = [];
 
@@ -114,11 +146,19 @@ export async function createRuntime(opts, meta = {}) {
     };
   }
 
-  for (const session of sessions) {
-    const catalog = await extract(session);
+  /**
+   * Build and store one runtime context from a bootstrap session or a
+   * precomputed catalog. Manager mode can omit the session entirely when a
+   * catalog was provided explicitly.
+   *
+   * @param {import('@mcp-layer/session').Session | undefined} session - Optional bootstrap session.
+   * @param {{ server?: { info?: Record<string, unknown> }, items?: Array<Record<string, unknown>> }} catalog - Extracted or precomputed catalog.
+   * @returns {void}
+   */
+  function pushContext(session, catalog) {
     const info = catalog.server?.info;
     const version = deriveApiVersion(info);
-    const prefix = resolvePrefix(config.prefix, version, info, session.name);
+    const prefix = resolvePrefix(config.prefix, version, info, contextName(session, info));
     const validator = createValidator(config.validation, session);
     const telemetry = createTelemetry(config.telemetry);
 
@@ -170,6 +210,18 @@ export async function createRuntime(opts, meta = {}) {
     });
   }
 
+  if (config.manager && !config.session) {
+    pushContext(undefined, config.catalog);
+  } else {
+    for (const session of sessions) {
+      // A live bootstrap session is the source of truth for route metadata.
+      // Explicit catalogs are only for manager mode when no bootstrap session
+      // exists yet.
+      const catalog = await extract(session);
+      pushContext(session, catalog);
+    }
+  }
+
   /**
    * Close runtime resources.
    * @returns {Promise<void>}

package/src/validation/trust.js

@@ -1,12 +1,16 @@
 /**
  * Determine whether schemas from a session should be trusted.
- * @param {import('@mcp-layer/session').Session} session - MCP session to evaluate.
+ * Missing bootstrap sessions are treated conservatively because catalog-only
+ * manager mode may be registering schemas sourced from a remote runtime.
+ *
+ * @param {import('@mcp-layer/session').Session | undefined} session - Optional MCP session to evaluate.
  * @param {'auto' | true | false} policy - Trust policy.
  * @returns {boolean}
  */
 export function shouldTrustSchemas(session, policy) {
   if (policy === true) return true;
   if (policy === false) return false;
+  if (!session) return false;
 
   const type = session?.transport?.constructor?.name;
   const remote = type === 'StreamableHTTPClientTransport';

package/src/validation/validator.js

@@ -9,7 +9,7 @@ import { checkSchemaSafety } from './safety.js';
 export class SchemaValidator {
   /**
    * @param {{ trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }} config - Validation configuration.
-   * @param {import('@mcp-layer/session').Session} session - MCP session.
+   * @param {import('@mcp-layer/session').Session | undefined} session - Optional bootstrap session.
    */
   constructor(config, session) {
     this.#config = config;
@@ -139,7 +139,7 @@ export class SchemaValidator {
 /**
  * Create a schema validator instance.
  * @param {{ trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }} config - Validation configuration.
- * @param {import('@mcp-layer/session').Session} session - MCP session.
+ * @param {import('@mcp-layer/session').Session | undefined} session - Optional bootstrap session.
  * @returns {SchemaValidator}
  */
 export function createValidator(config, session) {

package/types/config/validate.d.ts

@@ -2,13 +2,19 @@
  * Validate base runtime options and apply defaults.
  * @param {Record<string, unknown>} opts - User-supplied options.
  * @param {{ name?: string, serviceName?: string }} [meta] - Validation metadata.
- * @returns {{ session: unknown, manager?: { get: (request: import('fastify').FastifyRequest) => Promise<import('@mcp-layer/session').Session>, close?: () => Promise<void> }, prefix?: string | ((version: string, info: Record<string, unknown> | undefined, name: string) => string), validation: { trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }, resilience: { enabled: boolean, timeout: number, errorThresholdPercentage: number, resetTimeout: number, volumeThreshold: number }, telemetry: { enabled: boolean, serviceName: string, metricPrefix: string, api?: import('@opentelemetry/api') }, errors: { exposeDetails: boolean }, normalizeError?: (error: Error & { code?: string | number }, instance: string, requestId?: string, options?: { exposeDetails?: boolean }) => unknown }}
+ * @returns {{ session?: unknown, catalog?: { server?: { info?: Record<string, unknown> }, items?: Array<Record<string, unknown>> }, manager?: { get: (request: import('fastify').FastifyRequest) => Promise<import('@mcp-layer/session').Session>, close?: () => Promise<void> }, prefix?: string | ((version: string, info: Record<string, unknown> | undefined, name: string) => string), validation: { trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }, resilience: { enabled: boolean, timeout: number, errorThresholdPercentage: number, resetTimeout: number, volumeThreshold: number }, telemetry: { enabled: boolean, serviceName: string, metricPrefix: string, api?: import('@opentelemetry/api') }, errors: { exposeDetails: boolean }, normalizeError?: (error: Error & { code?: string | number }, instance: string, requestId?: string, options?: { exposeDetails?: boolean }) => unknown }}
  */
 export function validateRuntimeOptions(opts: Record<string, unknown>, meta?: {
     name?: string;
     serviceName?: string;
 }): {
-    session: unknown;
+    session?: unknown;
+    catalog?: {
+        server?: {
+            info?: Record<string, unknown>;
+        };
+        items?: Array<Record<string, unknown>>;
+    };
     manager?: {
         get: (request: import("fastify").FastifyRequest) => Promise<any>;
         close?: () => Promise<void>;

package/types/runtime.d.ts

@@ -2,7 +2,7 @@
  * Create shared runtime contexts for MCP adapters.
  * @param {Record<string, unknown>} opts - Runtime options.
  * @param {{ name?: string, serviceName?: string }} [meta] - Runtime metadata.
- * @returns {Promise<{ config: ReturnType<typeof validateRuntimeOptions>, contexts: Array<{ session: import('@mcp-layer/session').Session, catalog: { server?: { info?: Record<string, unknown> }, items?: Array<Record<string, unknown>> }, info: Record<string, unknown> | undefined, version: string, prefix: string, validator: import('./validation/validator.js').SchemaValidator, telemetry: ReturnType<typeof createTelemetry> | null, resolve: (request: import('fastify').FastifyRequest) => Promise<{ session: import('@mcp-layer/session').Session, breaker: import('opossum') | null }>, execute: (request: import('fastify').FastifyRequest, method: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>, normalize: (error: Error & { code?: string | number }, instance: string, requestId?: string) => unknown }>, breakers: Map<string, import('opossum')>, normalize: (error: Error & { code?: string | number }, instance: string, requestId?: string) => unknown, close: () => Promise<void> }>}
+ * @returns {Promise<{ config: ReturnType<typeof validateRuntimeOptions>, contexts: Array<{ session: import('@mcp-layer/session').Session | undefined, catalog: { server?: { info?: Record<string, unknown> }, items?: Array<Record<string, unknown>> }, info: Record<string, unknown> | undefined, version: string, prefix: string, validator: import('./validation/validator.js').SchemaValidator, telemetry: ReturnType<typeof createTelemetry> | null, resolve: (request: import('fastify').FastifyRequest) => Promise<{ session: import('@mcp-layer/session').Session, breaker: import('opossum') | null }>, execute: (request: import('fastify').FastifyRequest, method: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>, normalize: (error: Error & { code?: string | number }, instance: string, requestId?: string) => unknown }>, breakers: Map<string, import('opossum')>, normalize: (error: Error & { code?: string | number }, instance: string, requestId?: string) => unknown, close: () => Promise<void> }>}
  */
 export function createRuntime(opts: Record<string, unknown>, meta?: {
     name?: string;
@@ -10,7 +10,7 @@ export function createRuntime(opts: Record<string, unknown>, meta?: {
 }): Promise<{
     config: ReturnType<typeof validateRuntimeOptions>;
     contexts: Array<{
-        session: any;
+        session: any | undefined;
         catalog: {
             server?: {
                 info?: Record<string, unknown>;

package/types/validation/trust.d.ts

@@ -1,7 +1,10 @@
 /**
  * Determine whether schemas from a session should be trusted.
- * @param {import('@mcp-layer/session').Session} session - MCP session to evaluate.
+ * Missing bootstrap sessions are treated conservatively because catalog-only
+ * manager mode may be registering schemas sourced from a remote runtime.
+ *
+ * @param {import('@mcp-layer/session').Session | undefined} session - Optional MCP session to evaluate.
  * @param {'auto' | true | false} policy - Trust policy.
  * @returns {boolean}
  */
-export function shouldTrustSchemas(session: any, policy: "auto" | true | false): boolean;
+export function shouldTrustSchemas(session: any | undefined, policy: "auto" | true | false): boolean;

package/types/validation/validator.d.ts

@@ -1,7 +1,7 @@
 /**
  * Create a schema validator instance.
  * @param {{ trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }} config - Validation configuration.
- * @param {import('@mcp-layer/session').Session} session - MCP session.
+ * @param {import('@mcp-layer/session').Session | undefined} session - Optional bootstrap session.
  * @returns {SchemaValidator}
  */
 export function createValidator(config: {
@@ -11,14 +11,14 @@ export function createValidator(config: {
     maxPatternLength: number;
     maxToolNameLength: number;
     maxTemplateParamLength: number;
-}, session: any): SchemaValidator;
+}, session: any | undefined): SchemaValidator;
 /**
  * Schema validator for MCP tool and prompt inputs.
  */
 export class SchemaValidator {
     /**
      * @param {{ trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }} config - Validation configuration.
-     * @param {import('@mcp-layer/session').Session} session - MCP session.
+     * @param {import('@mcp-layer/session').Session | undefined} session - Optional bootstrap session.
      */
     constructor(config: {
         trustSchemas: "auto" | true | false;
@@ -27,7 +27,7 @@ export class SchemaValidator {
         maxPatternLength: number;
         maxToolNameLength: number;
         maxTemplateParamLength: number;
-    }, session: any);
+    }, session: any | undefined);
     /**
      * Register a tool schema for validation.
      * @param {string} name - Tool name.