@frontmcp/sdk 0.5.1 → 0.6.1

package/src/context/request-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.js","sourceRoot":"","sources":["../../../src/context/request-context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * RequestContext - Production-ready request context for FrontMCP\n *\n * Provides request-scoped state that flows through the entire async execution\n * chain via AsyncLocalStorage. Access via DI only using the REQUEST_CONTEXT token.\n */\n\nimport { randomUUID, createHash } from 'node:crypto';\nimport { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';\nimport { FrontMcpLogger } from '../common/interfaces/logger.interface';\nimport { TraceContext, generateTraceContext } from './trace-context';\nimport type { SessionIdPayload } from '../common/types';\n\n/**\n * Request metadata extracted from HTTP headers.\n */\nexport interface RequestMetadata {\n  /** User-Agent header */\n  userAgent?: string;\n  /** Content-Type header */\n  contentType?: string;\n  /** Accept header */\n  accept?: string;\n  /** Client IP address (from x-forwarded-for or socket) */\n  clientIp?: string;\n  /** Custom headers matching x-frontmcp-* pattern */\n  customHeaders: Record<string, string>;\n}\n\n/**\n * Arguments for creating a RequestContext.\n */\nexport interface RequestContextArgs {\n  /** Optional request ID (generated if not provided) */\n  requestId?: string;\n  /** Optional trace context (generated if not provided) */\n  traceContext?: TraceContext;\n  /** Session identifier (required) */\n  sessionId: string;\n  /** Authentication information (can be partial, progressively populated) */\n  authInfo: Partial<AuthInfo>;\n  /** Scope identifier (required) */\n  scopeId: string;\n  /** Optional timestamp (defaults to Date.now()) */\n  timestamp?: number;\n  /** Optional request metadata */\n  metadata?: RequestMetadata;\n}\n\n/**\n * RequestContext provides per-request state that flows through\n * the entire async execution chain via AsyncLocalStorage.\n *\n * Access via DI only using the REQUEST_CONTEXT token:\n * ```typescript\n * const ctx = this.get(REQUEST_CONTEXT);\n * console.log(ctx.requestId, ctx.traceContext.traceId);\n * ```\n */\nexport class RequestContext {\n  /** Unique request identifier (UUID v4) */\n  readonly requestId: string;\n\n  /** W3C Trace Context or generated trace ID */\n  readonly traceContext: TraceContext;\n\n  /** Session identifier (from mcp-session-id header or authorization) */\n  readonly sessionId: string;\n\n  /**\n   * Authentication information.\n   * Note: This is mutable to allow updating after authorization is verified.\n   * It's Partial<AuthInfo> because auth info is progressively populated\n   * throughout the request lifecycle (some fields like transport are only\n   * available after the transport is established).\n   */\n  private _authInfo: Partial<AuthInfo>;\n\n  /** Scope identifier */\n  readonly scopeId: string;\n\n  /** Request start timestamp */\n  readonly timestamp: number;\n\n  /** Request metadata (headers, user-agent, etc.) */\n  readonly metadata: RequestMetadata;\n\n  /** Timing marks for performance tracking */\n  private readonly marks: Map<string, number> = new Map();\n\n  /** Request-scoped data store */\n  private readonly store: Map<string | symbol, unknown> = new Map();\n\n  constructor(args: RequestContextArgs) {\n    this.requestId = args.requestId ?? randomUUID();\n    this.traceContext = args.traceContext ?? generateTraceContext();\n    this.sessionId = args.sessionId;\n    this._authInfo = args.authInfo;\n    this.scopeId = args.scopeId;\n    this.timestamp = args.timestamp ?? Date.now();\n    // Defensive normalization: ensure customHeaders is always an object\n    // even if args.metadata is partially defined at runtime (TS can't enforce this)\n    const metadata = args.metadata;\n    this.metadata = {\n      ...metadata,\n      customHeaders: metadata?.customHeaders ?? {},\n    };\n\n    // Initial mark\n    this.marks.set('init', this.timestamp);\n  }\n\n  /**\n   * Get authentication information.\n   * Returns Partial<AuthInfo> because auth info is progressively populated.\n   */\n  get authInfo(): Partial<AuthInfo> {\n    return this._authInfo;\n  }\n\n  /**\n   * Update auth info after authorization is verified.\n   * Called by checkAuthorization stage after session verification.\n   * Can be called multiple times to progressively add fields.\n   *\n   * @param authInfo - The auth info fields to set/update\n   * @internal\n   */\n  updateAuthInfo(authInfo: Partial<AuthInfo>): void {\n    // Merge with existing auth info to support progressive updates\n    this._authInfo = { ...this._authInfo, ...authInfo };\n  }\n\n  /**\n   * Session metadata including protocol, platform type, and node info.\n   * Only available after session verification in authenticated flows.\n   */\n  private _sessionMetadata?: SessionIdPayload;\n\n  /**\n   * Get session metadata.\n   *\n   * Contains protocol type, platform type, nodeId, and authSignature.\n   * Only available after session verification completes.\n   *\n   * @returns Session metadata or undefined if not yet verified\n   */\n  get sessionMetadata(): SessionIdPayload | undefined {\n    return this._sessionMetadata;\n  }\n\n  /**\n   * Update session metadata after session verification.\n   * Called by checkAuthorization stage after session verification.\n   *\n   * @param metadata - Session metadata from verified session\n   * @internal\n   */\n  updateSessionMetadata(metadata: SessionIdPayload): void {\n    this._sessionMetadata = metadata;\n  }\n\n  /**\n   * Get a child logger with request context attached.\n   *\n   * Creates a child logger with a prefix containing the request ID and trace ID\n   * for easy request tracing in logs.\n   *\n   * @param parentLogger - The parent logger to create a child from\n   * @returns A logger with requestId and traceId in the prefix\n   */\n  getLogger(parentLogger: FrontMcpLogger): FrontMcpLogger {\n    // FrontMcpLogger.child() takes a string prefix\n    const prefix = `[${this.requestId.slice(0, 8)}:${this.traceContext.traceId.slice(0, 8)}]`;\n    return parentLogger.child(prefix);\n  }\n\n  /**\n   * Mark a timing point for performance tracking.\n   *\n   * @param name - Name of the timing mark\n   */\n  mark(name: string): void {\n    this.marks.set(name, Date.now());\n  }\n\n  /**\n   * Get elapsed time in milliseconds between two marks.\n   *\n   * @param from - Start mark name (defaults to 'init')\n   * @param to - End mark name (defaults to current time)\n   * @returns Elapsed time in milliseconds\n   */\n  elapsed(from?: string, to?: string): number {\n    const fromTime = this.marks.get(from ?? 'init') ?? this.timestamp;\n    const toTime = to ? this.marks.get(to) ?? Date.now() : Date.now();\n    return toTime - fromTime;\n  }\n\n  /**\n   * Get all timing marks.\n   *\n   * @returns Read-only map of mark names to timestamps\n   */\n  getMarks(): ReadonlyMap<string, number> {\n    return this.marks;\n  }\n\n  /**\n   * Store request-scoped data.\n   *\n   * @param key - Storage key\n   * @param value - Value to store\n   */\n  set<T>(key: string | symbol, value: T): void {\n    this.store.set(key, value);\n  }\n\n  /**\n   * Retrieve request-scoped data.\n   *\n   * @param key - Storage key\n   * @returns Stored value or undefined\n   */\n  get<T>(key: string | symbol): T | undefined {\n    return this.store.get(key) as T | undefined;\n  }\n\n  /**\n   * Check if a key exists in the request-scoped store.\n   *\n   * @param key - Storage key\n   * @returns True if key exists\n   */\n  has(key: string | symbol): boolean {\n    return this.store.has(key);\n  }\n\n  /**\n   * Delete a key from the request-scoped store.\n   *\n   * @param key - Storage key\n   * @returns True if key was deleted\n   */\n  delete(key: string | symbol): boolean {\n    return this.store.delete(key);\n  }\n\n  /**\n   * Get a summary of the context for logging.\n   *\n   * Note: sessionId is hashed to prevent accidental exposure of user-identifying\n   * session identifiers in logs while still allowing correlation.\n   *\n   * @returns Object with key context fields\n   */\n  toLogContext(): Record<string, unknown> {\n    return {\n      requestId: this.requestId,\n      traceId: this.traceContext.traceId,\n      parentId: this.traceContext.parentId,\n      // Hash sessionId to prevent logging user-identifying information\n      // while preserving ability to correlate logs for the same session\n      sessionIdHash: createHash('sha256').update(this.sessionId).digest('hex').slice(0, 12),\n      scopeId: this.scopeId,\n      elapsed: this.elapsed(),\n    };\n  }\n}\n"]}

package/src/context/request-context.provider.d.ts

@@ -0,0 +1,37 @@
+/**
+ * REQUEST_CONTEXT Provider
+ *
+ * Defines the DI token and factory provider for accessing RequestContext.
+ * The context is retrieved from AsyncLocalStorage via RequestContextStorage.
+ */
+import { ProviderFactoryType } from '../common/interfaces/provider.interface';
+import { RequestContext } from './request-context';
+import { RequestContextStorage } from './request-context-storage';
+/**
+ * DI token for accessing the current RequestContext.
+ *
+ * Use this token to inject the current request context in any provider or context:
+ *
+ * @example
+ * ```typescript
+ * // In a tool/resource/prompt
+ * const ctx = this.get(REQUEST_CONTEXT);
+ * console.log(ctx.requestId, ctx.traceContext.traceId);
+ *
+ * // In a provider with constructor injection
+ * constructor(
+ *   @Inject(REQUEST_CONTEXT) private ctx: RequestContext
+ * ) {}
+ * ```
+ */
+export declare const REQUEST_CONTEXT: unique symbol;
+/**
+ * Factory provider for RequestContext.
+ *
+ * This provider is marked as REQUEST scope and retrieves the current
+ * RequestContext from AsyncLocalStorage via RequestContextStorage.
+ *
+ * Note: This provider will throw if called outside of a request scope
+ * (i.e., without first calling RequestContextStorage.run or runFromHeaders).
+ */
+export declare const RequestContextProvider: ProviderFactoryType<RequestContext, readonly [typeof RequestContextStorage]>;

package/src/context/request-context.provider.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * REQUEST_CONTEXT Provider
+ *
+ * Defines the DI token and factory provider for accessing RequestContext.
+ * The context is retrieved from AsyncLocalStorage via RequestContextStorage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestContextProvider = exports.REQUEST_CONTEXT = void 0;
+const metadata_1 = require("../common/metadata");
+const request_context_storage_1 = require("./request-context-storage");
+/**
+ * DI token for accessing the current RequestContext.
+ *
+ * Use this token to inject the current request context in any provider or context:
+ *
+ * @example
+ * ```typescript
+ * // In a tool/resource/prompt
+ * const ctx = this.get(REQUEST_CONTEXT);
+ * console.log(ctx.requestId, ctx.traceContext.traceId);
+ *
+ * // In a provider with constructor injection
+ * constructor(
+ *   @Inject(REQUEST_CONTEXT) private ctx: RequestContext
+ * ) {}
+ * ```
+ */
+exports.REQUEST_CONTEXT = Symbol.for('frontmcp:REQUEST_CONTEXT');
+/**
+ * Factory provider for RequestContext.
+ *
+ * This provider is marked as REQUEST scope and retrieves the current
+ * RequestContext from AsyncLocalStorage via RequestContextStorage.
+ *
+ * Note: This provider will throw if called outside of a request scope
+ * (i.e., without first calling RequestContextStorage.run or runFromHeaders).
+ */
+exports.RequestContextProvider = {
+    provide: exports.REQUEST_CONTEXT,
+    inject: () => [request_context_storage_1.RequestContextStorage],
+    useFactory: (storage) => {
+        return storage.getStoreOrThrow();
+    },
+    metadata: {
+        name: 'RequestContext',
+        description: 'Current request context from AsyncLocalStorage',
+        scope: metadata_1.ProviderScope.REQUEST,
+    },
+};
+//# sourceMappingURL=request-context.provider.js.map

package/src/context/request-context.provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.provider.js","sourceRoot":"","sources":["../../../src/context/request-context.provider.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,iDAAmD;AAGnD,uEAAkE;AAElE;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;AAEtE;;;;;;;;GAQG;AACU,QAAA,sBAAsB,GAAiF;IAClH,OAAO,EAAE,uBAAe;IACxB,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,+CAAqB,CAAU;IAC9C,UAAU,EAAE,CAAC,OAA8B,EAAkB,EAAE;QAC7D,OAAO,OAAO,CAAC,eAAe,EAAE,CAAC;IACnC,CAAC;IACD,QAAQ,EAAE;QACR,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,gDAAgD;QAC7D,KAAK,EAAE,wBAAa,CAAC,OAAO;KAC7B;CACK,CAAC","sourcesContent":["/**\n * REQUEST_CONTEXT Provider\n *\n * Defines the DI token and factory provider for accessing RequestContext.\n * The context is retrieved from AsyncLocalStorage via RequestContextStorage.\n */\n\nimport { ProviderScope } from '../common/metadata';\nimport { ProviderFactoryType } from '../common/interfaces/provider.interface';\nimport { RequestContext } from './request-context';\nimport { RequestContextStorage } from './request-context-storage';\n\n/**\n * DI token for accessing the current RequestContext.\n *\n * Use this token to inject the current request context in any provider or context:\n *\n * @example\n * ```typescript\n * // In a tool/resource/prompt\n * const ctx = this.get(REQUEST_CONTEXT);\n * console.log(ctx.requestId, ctx.traceContext.traceId);\n *\n * // In a provider with constructor injection\n * constructor(\n *   @Inject(REQUEST_CONTEXT) private ctx: RequestContext\n * ) {}\n * ```\n */\nexport const REQUEST_CONTEXT = Symbol.for('frontmcp:REQUEST_CONTEXT');\n\n/**\n * Factory provider for RequestContext.\n *\n * This provider is marked as REQUEST scope and retrieves the current\n * RequestContext from AsyncLocalStorage via RequestContextStorage.\n *\n * Note: This provider will throw if called outside of a request scope\n * (i.e., without first calling RequestContextStorage.run or runFromHeaders).\n */\nexport const RequestContextProvider: ProviderFactoryType<RequestContext, readonly [typeof RequestContextStorage]> = {\n  provide: REQUEST_CONTEXT,\n  inject: () => [RequestContextStorage] as const,\n  useFactory: (storage: RequestContextStorage): RequestContext => {\n    return storage.getStoreOrThrow();\n  },\n  metadata: {\n    name: 'RequestContext',\n    description: 'Current request context from AsyncLocalStorage',\n    scope: ProviderScope.REQUEST,\n  },\n} as any;\n"]}

package/src/context/session-key.provider.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Session key wrapper for DI injection in SESSION-scoped providers.
+ *
+ * FrontMCP's DI system uses class tokens (reads `design:paramtypes` from constructors).
+ * This class wraps the session ID so it can be injected via constructor parameters.
+ *
+ * The SessionKey is validated at construction to prevent:
+ * - Memory bombs (very long session IDs)
+ * - Log injection attacks (special characters)
+ * - Cache exhaustion (unique massive IDs)
+ *
+ * @example
+ * ```typescript
+ * import { Provider, ProviderScope, SessionKey } from '@frontmcp/sdk';
+ *
+ * @Provider({ scope: ProviderScope.SESSION })
+ * class SessionScopedCache {
+ *   constructor(private readonly sessionKey: SessionKey) {
+ *     // sessionKey.value available at construction time
+ *     const sessionId = sessionKey.value;
+ *   }
+ * }
+ * ```
+ */
+export declare class SessionKey {
+    readonly value: string;
+    /** Maximum allowed length for session keys */
+    static readonly MAX_LENGTH = 2048;
+    /**
+     * Valid characters for session keys:
+     * - Alphanumeric (a-z, A-Z, 0-9)
+     * - Hyphen, underscore, period
+     * - Colon (for namespaced IDs like "anon:uuid")
+     */
+    static readonly VALID_PATTERN: RegExp;
+    /**
+     * Validate a session key string without constructing.
+     * Use this for early validation before cache operations.
+     *
+     * @param value - The session key string to validate
+     * @throws InvalidInputError if validation fails (empty, too long, invalid characters)
+     */
+    static validate(value: string): void;
+    constructor(value: string);
+}

package/src/context/session-key.provider.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionKey = void 0;
+const mcp_error_1 = require("../errors/mcp.error");
+/**
+ * Session key wrapper for DI injection in SESSION-scoped providers.
+ *
+ * FrontMCP's DI system uses class tokens (reads `design:paramtypes` from constructors).
+ * This class wraps the session ID so it can be injected via constructor parameters.
+ *
+ * The SessionKey is validated at construction to prevent:
+ * - Memory bombs (very long session IDs)
+ * - Log injection attacks (special characters)
+ * - Cache exhaustion (unique massive IDs)
+ *
+ * @example
+ * ```typescript
+ * import { Provider, ProviderScope, SessionKey } from '@frontmcp/sdk';
+ *
+ * @Provider({ scope: ProviderScope.SESSION })
+ * class SessionScopedCache {
+ *   constructor(private readonly sessionKey: SessionKey) {
+ *     // sessionKey.value available at construction time
+ *     const sessionId = sessionKey.value;
+ *   }
+ * }
+ * ```
+ */
+class SessionKey {
+    value;
+    /** Maximum allowed length for session keys */
+    static MAX_LENGTH = 2048;
+    /**
+     * Valid characters for session keys:
+     * - Alphanumeric (a-z, A-Z, 0-9)
+     * - Hyphen, underscore, period
+     * - Colon (for namespaced IDs like "anon:uuid")
+     */
+    static VALID_PATTERN = /^[a-zA-Z0-9\-_.:]+$/;
+    /**
+     * Validate a session key string without constructing.
+     * Use this for early validation before cache operations.
+     *
+     * @param value - The session key string to validate
+     * @throws InvalidInputError if validation fails (empty, too long, invalid characters)
+     */
+    static validate(value) {
+        if (!value || value.length === 0) {
+            throw new mcp_error_1.InvalidInputError('SessionKey cannot be empty');
+        }
+        if (value.length > SessionKey.MAX_LENGTH) {
+            throw new mcp_error_1.InvalidInputError(`SessionKey exceeds maximum length of ${SessionKey.MAX_LENGTH} characters`);
+        }
+        if (!SessionKey.VALID_PATTERN.test(value)) {
+            throw new mcp_error_1.InvalidInputError('SessionKey contains invalid characters. Allowed: alphanumeric, hyphen, underscore, period, colon');
+        }
+    }
+    constructor(value) {
+        this.value = value;
+        // Delegate to static method to avoid code duplication
+        SessionKey.validate(value);
+    }
+}
+exports.SessionKey = SessionKey;
+//# sourceMappingURL=session-key.provider.js.map

package/src/context/session-key.provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-key.provider.js","sourceRoot":"","sources":["../../../src/context/session-key.provider.ts"],"names":[],"mappings":";;;AAAA,mDAAwD;AAExD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAa,UAAU;IAiCO;IAhC5B,8CAA8C;IAC9C,MAAM,CAAU,UAAU,GAAG,IAAI,CAAC;IAElC;;;;;OAKG;IACH,MAAM,CAAU,aAAa,GAAG,qBAAqB,CAAC;IAEtD;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,KAAa;QAC3B,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,6BAAiB,CAAC,4BAA4B,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC,UAAU,EAAE,CAAC;YACzC,MAAM,IAAI,6BAAiB,CAAC,wCAAwC,UAAU,CAAC,UAAU,aAAa,CAAC,CAAC;QAC1G,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,6BAAiB,CACzB,kGAAkG,CACnG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,YAA4B,KAAa;QAAb,UAAK,GAAL,KAAK,CAAQ;QACvC,sDAAsD;QACtD,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;;AApCH,gCAqCC","sourcesContent":["import { InvalidInputError } from '../errors/mcp.error';\n\n/**\n * Session key wrapper for DI injection in SESSION-scoped providers.\n *\n * FrontMCP's DI system uses class tokens (reads `design:paramtypes` from constructors).\n * This class wraps the session ID so it can be injected via constructor parameters.\n *\n * The SessionKey is validated at construction to prevent:\n * - Memory bombs (very long session IDs)\n * - Log injection attacks (special characters)\n * - Cache exhaustion (unique massive IDs)\n *\n * @example\n * ```typescript\n * import { Provider, ProviderScope, SessionKey } from '@frontmcp/sdk';\n *\n * @Provider({ scope: ProviderScope.SESSION })\n * class SessionScopedCache {\n *   constructor(private readonly sessionKey: SessionKey) {\n *     // sessionKey.value available at construction time\n *     const sessionId = sessionKey.value;\n *   }\n * }\n * ```\n */\nexport class SessionKey {\n  /** Maximum allowed length for session keys */\n  static readonly MAX_LENGTH = 2048;\n\n  /**\n   * Valid characters for session keys:\n   * - Alphanumeric (a-z, A-Z, 0-9)\n   * - Hyphen, underscore, period\n   * - Colon (for namespaced IDs like \"anon:uuid\")\n   */\n  static readonly VALID_PATTERN = /^[a-zA-Z0-9\\-_.:]+$/;\n\n  /**\n   * Validate a session key string without constructing.\n   * Use this for early validation before cache operations.\n   *\n   * @param value - The session key string to validate\n   * @throws InvalidInputError if validation fails (empty, too long, invalid characters)\n   */\n  static validate(value: string): void {\n    if (!value || value.length === 0) {\n      throw new InvalidInputError('SessionKey cannot be empty');\n    }\n    if (value.length > SessionKey.MAX_LENGTH) {\n      throw new InvalidInputError(`SessionKey exceeds maximum length of ${SessionKey.MAX_LENGTH} characters`);\n    }\n    if (!SessionKey.VALID_PATTERN.test(value)) {\n      throw new InvalidInputError(\n        'SessionKey contains invalid characters. Allowed: alphanumeric, hyphen, underscore, period, colon',\n      );\n    }\n  }\n\n  constructor(public readonly value: string) {\n    // Delegate to static method to avoid code duplication\n    SessionKey.validate(value);\n  }\n}\n"]}

package/src/context/trace-context.d.ts

@@ -0,0 +1,43 @@
+/**
+ * W3C Trace Context Parser
+ *
+ * Parses distributed tracing headers according to W3C Trace Context specification.
+ * Supports traceparent header with fallback to x-frontmcp-trace-id custom header.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ */
+/**
+ * W3C Trace Context parsed from traceparent header.
+ * Format: 00-<trace-id>-<parent-id>-<trace-flags>
+ */
+export interface TraceContext {
+    /** 128-bit trace identifier (32 hex chars) */
+    traceId: string;
+    /** 64-bit parent span identifier (16 hex chars) */
+    parentId: string;
+    /** 8-bit trace flags (sampled = 0x01) */
+    traceFlags: number;
+    /** Raw traceparent header value */
+    raw: string;
+}
+/**
+ * Parse trace context from HTTP headers.
+ *
+ * Priority:
+ * 1. W3C traceparent header
+ * 2. x-frontmcp-trace-id custom header
+ * 3. Generate new trace context
+ *
+ * @param headers - HTTP headers object
+ * @returns Parsed or generated TraceContext
+ */
+export declare function parseTraceContext(headers: Record<string, unknown>): TraceContext;
+/**
+ * Generate a new trace context with random IDs.
+ */
+export declare function generateTraceContext(): TraceContext;
+/**
+ * Create a child span context from a parent context.
+ * Generates a new parentId while preserving the traceId.
+ */
+export declare function createChildSpanContext(parent: TraceContext): TraceContext;

package/src/context/trace-context.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * W3C Trace Context Parser
+ *
+ * Parses distributed tracing headers according to W3C Trace Context specification.
+ * Supports traceparent header with fallback to x-frontmcp-trace-id custom header.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTraceContext = parseTraceContext;
+exports.generateTraceContext = generateTraceContext;
+exports.createChildSpanContext = createChildSpanContext;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Parse trace context from HTTP headers.
+ *
+ * Priority:
+ * 1. W3C traceparent header
+ * 2. x-frontmcp-trace-id custom header
+ * 3. Generate new trace context
+ *
+ * @param headers - HTTP headers object
+ * @returns Parsed or generated TraceContext
+ */
+function parseTraceContext(headers) {
+    // Priority 1: W3C traceparent header
+    const traceparent = getHeader(headers, 'traceparent');
+    if (traceparent) {
+        const parsed = parseTraceparent(traceparent);
+        if (parsed)
+            return parsed;
+    }
+    // Priority 2: x-frontmcp-trace-id custom header
+    const customTraceId = getHeader(headers, 'x-frontmcp-trace-id');
+    if (customTraceId && isValidTraceId(customTraceId)) {
+        const parentId = generateParentId();
+        return {
+            traceId: customTraceId.toLowerCase(),
+            parentId,
+            traceFlags: 0x01,
+            raw: `00-${customTraceId.toLowerCase()}-${parentId}-01`,
+        };
+    }
+    // Priority 3: Generate new trace context
+    return generateTraceContext();
+}
+/**
+ * Parse W3C traceparent header.
+ *
+ * Format: version-traceId-parentId-traceFlags
+ * Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
+ *
+ * @param value - traceparent header value
+ * @returns Parsed TraceContext or null if invalid
+ */
+function parseTraceparent(value) {
+    const parts = value.split('-');
+    if (parts.length !== 4)
+        return null;
+    const [version, traceId, parentId, flags] = parts;
+    // Validate version (must be 00 for current spec)
+    if (version !== '00')
+        return null;
+    // Validate trace-id (32 hex chars, not all zeros)
+    if (!isValidTraceId(traceId))
+        return null;
+    // Validate parent-id (16 hex chars, not all zeros)
+    if (!isValidParentId(parentId))
+        return null;
+    // Parse trace-flags
+    const traceFlags = parseInt(flags, 16);
+    if (isNaN(traceFlags))
+        return null;
+    return {
+        traceId: traceId.toLowerCase(),
+        parentId: parentId.toLowerCase(),
+        traceFlags,
+        raw: value,
+    };
+}
+/**
+ * Validate a trace ID according to W3C spec.
+ * Must be 32 lowercase hex characters, not all zeros.
+ */
+function isValidTraceId(id) {
+    return /^[a-f0-9]{32}$/i.test(id) && id !== '00000000000000000000000000000000';
+}
+/**
+ * Validate a parent ID according to W3C spec.
+ * Must be 16 lowercase hex characters, not all zeros.
+ */
+function isValidParentId(id) {
+    return /^[a-f0-9]{16}$/i.test(id) && id !== '0000000000000000';
+}
+/**
+ * Generate a new parent ID (16 hex chars).
+ */
+function generateParentId() {
+    return (0, node_crypto_1.randomUUID)().replace(/-/g, '').slice(0, 16);
+}
+/**
+ * Generate a new trace context with random IDs.
+ */
+function generateTraceContext() {
+    const traceId = (0, node_crypto_1.randomUUID)().replace(/-/g, '');
+    const parentId = generateParentId();
+    return {
+        traceId,
+        parentId,
+        traceFlags: 0x01, // sampled
+        raw: `00-${traceId}-${parentId}-01`,
+    };
+}
+/**
+ * Get a header value from headers object (case-insensitive).
+ */
+function getHeader(headers, name) {
+    // Try exact match first
+    const value = headers[name];
+    if (typeof value === 'string')
+        return value;
+    // Try lowercase
+    const lowerValue = headers[name.toLowerCase()];
+    if (typeof lowerValue === 'string')
+        return lowerValue;
+    return undefined;
+}
+/**
+ * Create a child span context from a parent context.
+ * Generates a new parentId while preserving the traceId.
+ */
+function createChildSpanContext(parent) {
+    const newParentId = generateParentId();
+    return {
+        traceId: parent.traceId,
+        parentId: newParentId,
+        traceFlags: parent.traceFlags,
+        raw: `00-${parent.traceId}-${newParentId}-${parent.traceFlags.toString(16).padStart(2, '0')}`,
+    };
+}
+//# sourceMappingURL=trace-context.js.map

package/src/context/trace-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context.js","sourceRoot":"","sources":["../../../src/context/trace-context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * W3C Trace Context Parser\n *\n * Parses distributed tracing headers according to W3C Trace Context specification.\n * Supports traceparent header with fallback to x-frontmcp-trace-id custom header.\n *\n * @see https://www.w3.org/TR/trace-context/\n */\n\nimport { randomUUID } from 'node:crypto';\n\n/**\n * W3C Trace Context parsed from traceparent header.\n * Format: 00-<trace-id>-<parent-id>-<trace-flags>\n */\nexport interface TraceContext {\n  /** 128-bit trace identifier (32 hex chars) */\n  traceId: string;\n  /** 64-bit parent span identifier (16 hex chars) */\n  parentId: string;\n  /** 8-bit trace flags (sampled = 0x01) */\n  traceFlags: number;\n  /** Raw traceparent header value */\n  raw: string;\n}\n\n/**\n * Parse trace context from HTTP headers.\n *\n * Priority:\n * 1. W3C traceparent header\n * 2. x-frontmcp-trace-id custom header\n * 3. Generate new trace context\n *\n * @param headers - HTTP headers object\n * @returns Parsed or generated TraceContext\n */\nexport function parseTraceContext(headers: Record<string, unknown>): TraceContext {\n  // Priority 1: W3C traceparent header\n  const traceparent = getHeader(headers, 'traceparent');\n  if (traceparent) {\n    const parsed = parseTraceparent(traceparent);\n    if (parsed) return parsed;\n  }\n\n  // Priority 2: x-frontmcp-trace-id custom header\n  const customTraceId = getHeader(headers, 'x-frontmcp-trace-id');\n  if (customTraceId && isValidTraceId(customTraceId)) {\n    const parentId = generateParentId();\n    return {\n      traceId: customTraceId.toLowerCase(),\n      parentId,\n      traceFlags: 0x01,\n      raw: `00-${customTraceId.toLowerCase()}-${parentId}-01`,\n    };\n  }\n\n  // Priority 3: Generate new trace context\n  return generateTraceContext();\n}\n\n/**\n * Parse W3C traceparent header.\n *\n * Format: version-traceId-parentId-traceFlags\n * Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01\n *\n * @param value - traceparent header value\n * @returns Parsed TraceContext or null if invalid\n */\nfunction parseTraceparent(value: string): TraceContext | null {\n  const parts = value.split('-');\n  if (parts.length !== 4) return null;\n\n  const [version, traceId, parentId, flags] = parts;\n\n  // Validate version (must be 00 for current spec)\n  if (version !== '00') return null;\n\n  // Validate trace-id (32 hex chars, not all zeros)\n  if (!isValidTraceId(traceId)) return null;\n\n  // Validate parent-id (16 hex chars, not all zeros)\n  if (!isValidParentId(parentId)) return null;\n\n  // Parse trace-flags\n  const traceFlags = parseInt(flags, 16);\n  if (isNaN(traceFlags)) return null;\n\n  return {\n    traceId: traceId.toLowerCase(),\n    parentId: parentId.toLowerCase(),\n    traceFlags,\n    raw: value,\n  };\n}\n\n/**\n * Validate a trace ID according to W3C spec.\n * Must be 32 lowercase hex characters, not all zeros.\n */\nfunction isValidTraceId(id: string): boolean {\n  return /^[a-f0-9]{32}$/i.test(id) && id !== '00000000000000000000000000000000';\n}\n\n/**\n * Validate a parent ID according to W3C spec.\n * Must be 16 lowercase hex characters, not all zeros.\n */\nfunction isValidParentId(id: string): boolean {\n  return /^[a-f0-9]{16}$/i.test(id) && id !== '0000000000000000';\n}\n\n/**\n * Generate a new parent ID (16 hex chars).\n */\nfunction generateParentId(): string {\n  return randomUUID().replace(/-/g, '').slice(0, 16);\n}\n\n/**\n * Generate a new trace context with random IDs.\n */\nexport function generateTraceContext(): TraceContext {\n  const traceId = randomUUID().replace(/-/g, '');\n  const parentId = generateParentId();\n  return {\n    traceId,\n    parentId,\n    traceFlags: 0x01, // sampled\n    raw: `00-${traceId}-${parentId}-01`,\n  };\n}\n\n/**\n * Get a header value from headers object (case-insensitive).\n */\nfunction getHeader(headers: Record<string, unknown>, name: string): string | undefined {\n  // Try exact match first\n  const value = headers[name];\n  if (typeof value === 'string') return value;\n\n  // Try lowercase\n  const lowerValue = headers[name.toLowerCase()];\n  if (typeof lowerValue === 'string') return lowerValue;\n\n  return undefined;\n}\n\n/**\n * Create a child span context from a parent context.\n * Generates a new parentId while preserving the traceId.\n */\nexport function createChildSpanContext(parent: TraceContext): TraceContext {\n  const newParentId = generateParentId();\n  return {\n    traceId: parent.traceId,\n    parentId: newParentId,\n    traceFlags: parent.traceFlags,\n    raw: `00-${parent.traceId}-${newParentId}-${parent.traceFlags.toString(16).padStart(2, '0')}`,\n  };\n}\n"]}

package/src/errors/index.d.ts

@@ -1,3 +1,3 @@
-export { McpError, PublicMcpError, InternalMcpError, ToolNotFoundError, ResourceNotFoundError, ResourceReadError, InvalidResourceUriError, InvalidInputError, InvalidOutputError, InvalidMethodError, ToolExecutionError, RateLimitError, QuotaExceededError, UnauthorizedError, GenericServerError, DependencyNotFoundError, InvalidHookFlowError, AuthConfigurationError, PromptNotFoundError, PromptExecutionError, isPublicError, toMcpError, formatMcpErrorResponse, } from './mcp.error';
+export { McpError, PublicMcpError, InternalMcpError, ToolNotFoundError, ResourceNotFoundError, ResourceReadError, InvalidResourceUriError, InvalidInputError, InvalidOutputError, InvalidMethodError, ToolExecutionError, RateLimitError, QuotaExceededError, UnauthorizedError, GenericServerError, DependencyNotFoundError, InvalidHookFlowError, AuthConfigurationError, PromptNotFoundError, PromptExecutionError, GlobalConfigNotFoundError, isPublicError, toMcpError, formatMcpErrorResponse, MCP_ERROR_CODES, type McpErrorCode, } from './mcp.error';
 export { authorizationRequiredDataSchema, authorizationRequiredParamsSchema, authorizationRequiredMetaSchema, AuthorizationRequiredData, AuthorizationRequiredParams, AuthorizationRequiredMeta, AuthorizationRequiredError, } from './authorization-required.error';
 export { ErrorHandler, ErrorHandlerOptions, createErrorHandler, shouldStopExecution } from './error-handler';

package/src/errors/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.shouldStopExecution = exports.createErrorHandler = exports.ErrorHandler = exports.AuthorizationRequiredError = exports.authorizationRequiredMetaSchema = exports.authorizationRequiredParamsSchema = exports.authorizationRequiredDataSchema = exports.formatMcpErrorResponse = exports.toMcpError = exports.isPublicError = exports.PromptExecutionError = exports.PromptNotFoundError = exports.AuthConfigurationError = exports.InvalidHookFlowError = exports.DependencyNotFoundError = exports.GenericServerError = exports.UnauthorizedError = exports.QuotaExceededError = exports.RateLimitError = exports.ToolExecutionError = exports.InvalidMethodError = exports.InvalidOutputError = exports.InvalidInputError = exports.InvalidResourceUriError = exports.ResourceReadError = exports.ResourceNotFoundError = exports.ToolNotFoundError = exports.InternalMcpError = exports.PublicMcpError = exports.McpError = void 0;
+exports.shouldStopExecution = exports.createErrorHandler = exports.ErrorHandler = exports.AuthorizationRequiredError = exports.authorizationRequiredMetaSchema = exports.authorizationRequiredParamsSchema = exports.authorizationRequiredDataSchema = exports.MCP_ERROR_CODES = exports.formatMcpErrorResponse = exports.toMcpError = exports.isPublicError = exports.GlobalConfigNotFoundError = exports.PromptExecutionError = exports.PromptNotFoundError = exports.AuthConfigurationError = exports.InvalidHookFlowError = exports.DependencyNotFoundError = exports.GenericServerError = exports.UnauthorizedError = exports.QuotaExceededError = exports.RateLimitError = exports.ToolExecutionError = exports.InvalidMethodError = exports.InvalidOutputError = exports.InvalidInputError = exports.InvalidResourceUriError = exports.ResourceReadError = exports.ResourceNotFoundError = exports.ToolNotFoundError = exports.InternalMcpError = exports.PublicMcpError = exports.McpError = void 0;
 // Export all error classes
 var mcp_error_1 = require("./mcp.error");
 Object.defineProperty(exports, "McpError", { enumerable: true, get: function () { return mcp_error_1.McpError; } });
@@ -23,9 +23,12 @@ Object.defineProperty(exports, "InvalidHookFlowError", { enumerable: true, get:
 Object.defineProperty(exports, "AuthConfigurationError", { enumerable: true, get: function () { return mcp_error_1.AuthConfigurationError; } });
 Object.defineProperty(exports, "PromptNotFoundError", { enumerable: true, get: function () { return mcp_error_1.PromptNotFoundError; } });
 Object.defineProperty(exports, "PromptExecutionError", { enumerable: true, get: function () { return mcp_error_1.PromptExecutionError; } });
+Object.defineProperty(exports, "GlobalConfigNotFoundError", { enumerable: true, get: function () { return mcp_error_1.GlobalConfigNotFoundError; } });
 Object.defineProperty(exports, "isPublicError", { enumerable: true, get: function () { return mcp_error_1.isPublicError; } });
 Object.defineProperty(exports, "toMcpError", { enumerable: true, get: function () { return mcp_error_1.toMcpError; } });
 Object.defineProperty(exports, "formatMcpErrorResponse", { enumerable: true, get: function () { return mcp_error_1.formatMcpErrorResponse; } });
+// Error codes
+Object.defineProperty(exports, "MCP_ERROR_CODES", { enumerable: true, get: function () { return mcp_error_1.MCP_ERROR_CODES; } });
 // Export authorization required error for progressive auth
 var authorization_required_error_1 = require("./authorization-required.error");
 // Schemas

package/src/errors/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/errors/index.ts"],"names":[],"mappings":";;;AAAA,2BAA2B;AAC3B,yCAwBqB;AAvBnB,qGAAA,QAAQ,OAAA;AACR,2GAAA,cAAc,OAAA;AACd,6GAAA,gBAAgB,OAAA;AAChB,8GAAA,iBAAiB,OAAA;AACjB,kHAAA,qBAAqB,OAAA;AACrB,8GAAA,iBAAiB,OAAA;AACjB,oHAAA,uBAAuB,OAAA;AACvB,8GAAA,iBAAiB,OAAA;AACjB,+GAAA,kBAAkB,OAAA;AAClB,+GAAA,kBAAkB,OAAA;AAClB,+GAAA,kBAAkB,OAAA;AAClB,2GAAA,cAAc,OAAA;AACd,+GAAA,kBAAkB,OAAA;AAClB,8GAAA,iBAAiB,OAAA;AACjB,+GAAA,kBAAkB,OAAA;AAClB,oHAAA,uBAAuB,OAAA;AACvB,iHAAA,oBAAoB,OAAA;AACpB,mHAAA,sBAAsB,OAAA;AACtB,gHAAA,mBAAmB,OAAA;AACnB,iHAAA,oBAAoB,OAAA;AACpB,0GAAA,aAAa,OAAA;AACb,uGAAA,UAAU,OAAA;AACV,mHAAA,sBAAsB,OAAA;AAGxB,2DAA2D;AAC3D,+EAWwC;AAVtC,UAAU;AACV,+IAAA,+BAA+B,OAAA;AAC/B,iJAAA,iCAAiC,OAAA;AACjC,+IAAA,+BAA+B,OAAA;AAK/B,cAAc;AACd,0IAAA,0BAA0B,OAAA;AAG5B,iCAAiC;AACjC,iDAA6G;AAApG,6GAAA,YAAY,OAAA;AAAuB,mHAAA,kBAAkB,OAAA;AAAE,oHAAA,mBAAmB,OAAA","sourcesContent":["// Export all error classes\nexport {\n  McpError,\n  PublicMcpError,\n  InternalMcpError,\n  ToolNotFoundError,\n  ResourceNotFoundError,\n  ResourceReadError,\n  InvalidResourceUriError,\n  InvalidInputError,\n  InvalidOutputError,\n  InvalidMethodError,\n  ToolExecutionError,\n  RateLimitError,\n  QuotaExceededError,\n  UnauthorizedError,\n  GenericServerError,\n  DependencyNotFoundError,\n  InvalidHookFlowError,\n  AuthConfigurationError,\n  PromptNotFoundError,\n  PromptExecutionError,\n  isPublicError,\n  toMcpError,\n  formatMcpErrorResponse,\n} from './mcp.error';\n\n// Export authorization required error for progressive auth\nexport {\n  // Schemas\n  authorizationRequiredDataSchema,\n  authorizationRequiredParamsSchema,\n  authorizationRequiredMetaSchema,\n  // Types (inferred from schemas)\n  AuthorizationRequiredData,\n  AuthorizationRequiredParams,\n  AuthorizationRequiredMeta,\n  // Error class\n  AuthorizationRequiredError,\n} from './authorization-required.error';\n\n// Export error handler utilities\nexport { ErrorHandler, ErrorHandlerOptions, createErrorHandler, shouldStopExecution } from './error-handler';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/errors/index.ts"],"names":[],"mappings":";;;AAAA,2BAA2B;AAC3B,yCA4BqB;AA3BnB,qGAAA,QAAQ,OAAA;AACR,2GAAA,cAAc,OAAA;AACd,6GAAA,gBAAgB,OAAA;AAChB,8GAAA,iBAAiB,OAAA;AACjB,kHAAA,qBAAqB,OAAA;AACrB,8GAAA,iBAAiB,OAAA;AACjB,oHAAA,uBAAuB,OAAA;AACvB,8GAAA,iBAAiB,OAAA;AACjB,+GAAA,kBAAkB,OAAA;AAClB,+GAAA,kBAAkB,OAAA;AAClB,+GAAA,kBAAkB,OAAA;AAClB,2GAAA,cAAc,OAAA;AACd,+GAAA,kBAAkB,OAAA;AAClB,8GAAA,iBAAiB,OAAA;AACjB,+GAAA,kBAAkB,OAAA;AAClB,oHAAA,uBAAuB,OAAA;AACvB,iHAAA,oBAAoB,OAAA;AACpB,mHAAA,sBAAsB,OAAA;AACtB,gHAAA,mBAAmB,OAAA;AACnB,iHAAA,oBAAoB,OAAA;AACpB,sHAAA,yBAAyB,OAAA;AACzB,0GAAA,aAAa,OAAA;AACb,uGAAA,UAAU,OAAA;AACV,mHAAA,sBAAsB,OAAA;AACtB,cAAc;AACd,4GAAA,eAAe,OAAA;AAIjB,2DAA2D;AAC3D,+EAWwC;AAVtC,UAAU;AACV,+IAAA,+BAA+B,OAAA;AAC/B,iJAAA,iCAAiC,OAAA;AACjC,+IAAA,+BAA+B,OAAA;AAK/B,cAAc;AACd,0IAAA,0BAA0B,OAAA;AAG5B,iCAAiC;AACjC,iDAA6G;AAApG,6GAAA,YAAY,OAAA;AAAuB,mHAAA,kBAAkB,OAAA;AAAE,oHAAA,mBAAmB,OAAA","sourcesContent":["// Export all error classes\nexport {\n  McpError,\n  PublicMcpError,\n  InternalMcpError,\n  ToolNotFoundError,\n  ResourceNotFoundError,\n  ResourceReadError,\n  InvalidResourceUriError,\n  InvalidInputError,\n  InvalidOutputError,\n  InvalidMethodError,\n  ToolExecutionError,\n  RateLimitError,\n  QuotaExceededError,\n  UnauthorizedError,\n  GenericServerError,\n  DependencyNotFoundError,\n  InvalidHookFlowError,\n  AuthConfigurationError,\n  PromptNotFoundError,\n  PromptExecutionError,\n  GlobalConfigNotFoundError,\n  isPublicError,\n  toMcpError,\n  formatMcpErrorResponse,\n  // Error codes\n  MCP_ERROR_CODES,\n  type McpErrorCode,\n} from './mcp.error';\n\n// Export authorization required error for progressive auth\nexport {\n  // Schemas\n  authorizationRequiredDataSchema,\n  authorizationRequiredParamsSchema,\n  authorizationRequiredMetaSchema,\n  // Types (inferred from schemas)\n  AuthorizationRequiredData,\n  AuthorizationRequiredParams,\n  AuthorizationRequiredMeta,\n  // Error class\n  AuthorizationRequiredError,\n} from './authorization-required.error';\n\n// Export error handler utilities\nexport { ErrorHandler, ErrorHandlerOptions, createErrorHandler, shouldStopExecution } from './error-handler';\n"]}

package/src/errors/mcp.error.d.ts

@@ -202,6 +202,13 @@ export declare class DependencyNotFoundError extends InternalMcpError {
 export declare class InvalidHookFlowError extends InternalMcpError {
     constructor(message: string);
 }
+/**
+ * Request context not available error - thrown when code attempts to access
+ * RequestContext outside of a request scope (i.e., without AsyncLocalStorage context).
+ */
+export declare class RequestContextNotAvailableError extends InternalMcpError {
+    constructor(message?: string);
+}
 /**
  * Auth configuration error - thrown when auth configuration is invalid
  * (e.g., transparent mode on parent with multiple child providers).
@@ -230,6 +237,15 @@ export declare class PromptExecutionError extends InternalMcpError {
     constructor(promptName: string, cause?: Error);
     getInternalMessage(): string;
 }
+/**
+ * Global configuration not found error - thrown when a plugin requires
+ * global configuration that is not defined in @FrontMcp decorator.
+ */
+export declare class GlobalConfigNotFoundError extends PublicMcpError {
+    readonly pluginName: string;
+    readonly configKey: string;
+    constructor(pluginName: string, configKey: string);
+}
 /**
  * Check if the error is a public error that can be safely shown to users
  */

package/src/errors/mcp.error.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PromptExecutionError = exports.PromptNotFoundError = exports.AuthConfigurationError = exports.InvalidHookFlowError = exports.DependencyNotFoundError = exports.GenericServerError = exports.UnauthorizedError = exports.QuotaExceededError = exports.RateLimitError = exports.ToolExecutionError = exports.InvalidMethodError = exports.InvalidOutputError = exports.InvalidInputError = exports.InvalidResourceUriError = exports.ResourceReadError = exports.ResourceNotFoundError = exports.ToolNotFoundError = exports.InternalMcpError = exports.PublicMcpError = exports.McpError = exports.MCP_ERROR_CODES = void 0;
+exports.GlobalConfigNotFoundError = exports.PromptExecutionError = exports.PromptNotFoundError = exports.AuthConfigurationError = exports.RequestContextNotAvailableError = exports.InvalidHookFlowError = exports.DependencyNotFoundError = exports.GenericServerError = exports.UnauthorizedError = exports.QuotaExceededError = exports.RateLimitError = exports.ToolExecutionError = exports.InvalidMethodError = exports.InvalidOutputError = exports.InvalidInputError = exports.InvalidResourceUriError = exports.ResourceReadError = exports.ResourceNotFoundError = exports.ToolNotFoundError = exports.InternalMcpError = exports.PublicMcpError = exports.McpError = exports.MCP_ERROR_CODES = void 0;
 exports.isPublicError = isPublicError;
 exports.toMcpError = toMcpError;
 exports.formatMcpErrorResponse = formatMcpErrorResponse;
@@ -305,6 +305,16 @@ class InvalidHookFlowError extends InternalMcpError {
     }
 }
 exports.InvalidHookFlowError = InvalidHookFlowError;
+/**
+ * Request context not available error - thrown when code attempts to access
+ * RequestContext outside of a request scope (i.e., without AsyncLocalStorage context).
+ */
+class RequestContextNotAvailableError extends InternalMcpError {
+    constructor(message = 'RequestContext not available. Ensure execution runs within a request scope created by RequestContextStorage.run().') {
+        super(message, 'REQUEST_CONTEXT_NOT_AVAILABLE');
+    }
+}
+exports.RequestContextNotAvailableError = RequestContextNotAvailableError;
 /**
  * Auth configuration error - thrown when auth configuration is invalid
  * (e.g., transparent mode on parent with multiple child providers).
@@ -358,6 +368,24 @@ class PromptExecutionError extends InternalMcpError {
 }
 exports.PromptExecutionError = PromptExecutionError;
 // ============================================================================
+// Configuration Errors
+// ============================================================================
+/**
+ * Global configuration not found error - thrown when a plugin requires
+ * global configuration that is not defined in @FrontMcp decorator.
+ */
+class GlobalConfigNotFoundError extends PublicMcpError {
+    pluginName;
+    configKey;
+    constructor(pluginName, configKey) {
+        super(`Plugin "${pluginName}" requires global "${configKey}" configuration. ` +
+            `Add "${configKey}" to your @FrontMcp decorator options.`, 'GLOBAL_CONFIG_NOT_FOUND', 500);
+        this.pluginName = pluginName;
+        this.configKey = configKey;
+    }
+}
+exports.GlobalConfigNotFoundError = GlobalConfigNotFoundError;
+// ============================================================================
 // Error Utilities
 // ============================================================================
 /**