@frontmcp/sdk 0.5.0 → 0.6.0

package/src/context/frontmcp-context-storage.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * FrontMcpContextStorage - AsyncLocalStorage wrapper for unified context
+ *
+ * Provides concurrent-safe context propagation using Node.js AsyncLocalStorage.
+ * Access through DI only - never use static imports to access the storage directly.
+ *
+ * @example
+ * ```typescript
+ * // In a flow or middleware
+ * const storage = this.get(FrontMcpContextStorage);
+ * await storage.runFromHeaders(request.headers, {
+ *   sessionId: sessionId,
+ *   scopeId: scope.id,
+ * }, async () => {
+ *   // All code here can access the context via DI
+ *   const ctx = this.get(FRONTMCP_CONTEXT);
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextStorage = exports.FrontMcpContextStorage = void 0;
+const tslib_1 = require("tslib");
+const node_async_hooks_1 = require("node:async_hooks");
+const decorators_1 = require("../common/decorators");
+const metadata_1 = require("../common/metadata");
+const frontmcp_context_1 = require("./frontmcp-context");
+const trace_context_1 = require("./trace-context");
+const mcp_error_1 = require("../errors/mcp.error");
+/**
+ * Module-level AsyncLocalStorage instance.
+ *
+ * This is the ONLY place where the storage is created.
+ * Access should be through DI, not through static imports.
+ */
+const frontmcpContextStorage = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * FrontMcpContextStorage provides unified context via AsyncLocalStorage.
+ *
+ * This is a GLOBAL-scoped provider because it manages the storage itself,
+ * not the per-context data. The actual FrontMcpContext is accessed via
+ * the FRONTMCP_CONTEXT token which is CONTEXT-scoped.
+ */
+let FrontMcpContextStorage = class FrontMcpContextStorage {
+    /**
+     * Run a callback with a new FrontMcpContext.
+     *
+     * @param args - Arguments to create the context
+     * @param fn - Async function to run with the context
+     * @returns Result of the callback
+     */
+    run(args, fn) {
+        const context = new frontmcp_context_1.FrontMcpContext(args);
+        return frontmcpContextStorage.run(context, fn);
+    }
+    /**
+     * Run with context extracted from HTTP headers.
+     *
+     * Automatically parses trace context from headers using W3C Trace Context
+     * specification with fallback to x-frontmcp-trace-id.
+     *
+     * @param headers - HTTP headers
+     * @param args - Additional context args (sessionId, scopeId)
+     * @param fn - Async function to run
+     * @returns Result of the callback
+     */
+    runFromHeaders(headers, args, fn) {
+        const traceContext = (0, trace_context_1.parseTraceContext)(headers);
+        const metadata = extractMetadata(headers);
+        const context = new frontmcp_context_1.FrontMcpContext({
+            ...args,
+            traceContext,
+            metadata,
+        });
+        return frontmcpContextStorage.run(context, fn);
+    }
+    /**
+     * Run with an existing FrontMcpContext.
+     *
+     * Useful when you need to propagate an existing context to a new async scope.
+     *
+     * @param context - Existing FrontMcpContext
+     * @param fn - Async function to run
+     * @returns Result of the callback
+     */
+    runWithContext(context, fn) {
+        return frontmcpContextStorage.run(context, fn);
+    }
+    /**
+     * Get the current FrontMcpContext.
+     *
+     * @returns Current context or undefined if not in a context scope
+     */
+    getStore() {
+        return frontmcpContextStorage.getStore();
+    }
+    /**
+     * Get the current FrontMcpContext, throwing if not available.
+     *
+     * @throws Error if not in a context scope
+     */
+    getStoreOrThrow() {
+        const ctx = this.getStore();
+        if (!ctx) {
+            throw new mcp_error_1.RequestContextNotAvailableError('FrontMcpContext not available. Ensure operation runs within context scope.');
+        }
+        return ctx;
+    }
+    /**
+     * Check if currently running within a context.
+     *
+     * @returns True if a FrontMcpContext is available
+     */
+    hasContext() {
+        return frontmcpContextStorage.getStore() !== undefined;
+    }
+    /**
+     * Update the authInfo in the current context.
+     *
+     * This mutates the existing context in place to preserve internal state
+     * (marks, store, sessionMetadata) while updating auth info.
+     *
+     * @param authInfo - Auth info fields to set/update (merged with existing)
+     * @param fn - Function to run after update
+     * @returns Result of the callback
+     */
+    updateAuthInfo(authInfo, fn) {
+        const current = this.getStoreOrThrow();
+        current.updateAuthInfo(authInfo);
+        return fn();
+    }
+};
+exports.FrontMcpContextStorage = FrontMcpContextStorage;
+exports.ContextStorage = FrontMcpContextStorage;
+exports.ContextStorage = exports.FrontMcpContextStorage = FrontMcpContextStorage = tslib_1.__decorate([
+    (0, decorators_1.Provider)({
+        name: 'FrontMcpContextStorage',
+        description: 'Manages unified context via AsyncLocalStorage',
+        scope: metadata_1.ProviderScope.GLOBAL,
+    })
+], FrontMcpContextStorage);
+/**
+ * Extract request metadata from headers.
+ */
+function extractMetadata(headers) {
+    const customHeaders = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase().startsWith('x-frontmcp-') && typeof value === 'string') {
+            customHeaders[key.toLowerCase()] = value;
+        }
+    }
+    return {
+        userAgent: typeof headers['user-agent'] === 'string' ? headers['user-agent'] : undefined,
+        contentType: typeof headers['content-type'] === 'string' ? headers['content-type'] : undefined,
+        accept: typeof headers['accept'] === 'string' ? headers['accept'] : undefined,
+        clientIp: extractClientIp(headers),
+        customHeaders,
+    };
+}
+/**
+ * Extract client IP from headers.
+ * Handles both string and array header values (some adapters pass arrays).
+ */
+function extractClientIp(headers) {
+    // x-forwarded-for can be comma-separated list; first is client IP
+    const xff = headers['x-forwarded-for'];
+    if (typeof xff === 'string') {
+        return xff.split(',')[0]?.trim();
+    }
+    // Some adapters pass arrays for multi-value headers
+    if (Array.isArray(xff) && typeof xff[0] === 'string') {
+        return xff[0].split(',')[0]?.trim();
+    }
+    const realIp = headers['x-real-ip'];
+    if (typeof realIp === 'string') {
+        return realIp;
+    }
+    if (Array.isArray(realIp) && typeof realIp[0] === 'string') {
+        return realIp[0];
+    }
+    return undefined;
+}
+//# sourceMappingURL=frontmcp-context-storage.js.map

package/src/context/frontmcp-context-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmcp-context-storage.js","sourceRoot":"","sources":["../../../src/context/frontmcp-context-storage.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * FrontMcpContextStorage - AsyncLocalStorage wrapper for unified context\n *\n * Provides concurrent-safe context propagation using Node.js AsyncLocalStorage.\n * Access through DI only - never use static imports to access the storage directly.\n *\n * @example\n * ```typescript\n * // In a flow or middleware\n * const storage = this.get(FrontMcpContextStorage);\n * await storage.runFromHeaders(request.headers, {\n *   sessionId: sessionId,\n *   scopeId: scope.id,\n * }, async () => {\n *   // All code here can access the context via DI\n *   const ctx = this.get(FRONTMCP_CONTEXT);\n * });\n * ```\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { Provider } from '../common/decorators';\nimport { ProviderScope } from '../common/metadata';\nimport { FrontMcpContext, FrontMcpContextArgs, RequestMetadata } from './frontmcp-context';\nimport { parseTraceContext } from './trace-context';\nimport { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';\nimport { RequestContextNotAvailableError } from '../errors/mcp.error';\n\n/**\n * Module-level AsyncLocalStorage instance.\n *\n * This is the ONLY place where the storage is created.\n * Access should be through DI, not through static imports.\n */\nconst frontmcpContextStorage = new AsyncLocalStorage<FrontMcpContext>();\n\n/**\n * FrontMcpContextStorage provides unified context via AsyncLocalStorage.\n *\n * This is a GLOBAL-scoped provider because it manages the storage itself,\n * not the per-context data. The actual FrontMcpContext is accessed via\n * the FRONTMCP_CONTEXT token which is CONTEXT-scoped.\n */\n@Provider({\n  name: 'FrontMcpContextStorage',\n  description: 'Manages unified context via AsyncLocalStorage',\n  scope: ProviderScope.GLOBAL,\n})\nexport class FrontMcpContextStorage {\n  /**\n   * Run a callback with a new FrontMcpContext.\n   *\n   * @param args - Arguments to create the context\n   * @param fn - Async function to run with the context\n   * @returns Result of the callback\n   */\n  run<T>(args: FrontMcpContextArgs, fn: () => T | Promise<T>): T | Promise<T> {\n    const context = new FrontMcpContext(args);\n    return frontmcpContextStorage.run(context, fn);\n  }\n\n  /**\n   * Run with context extracted from HTTP headers.\n   *\n   * Automatically parses trace context from headers using W3C Trace Context\n   * specification with fallback to x-frontmcp-trace-id.\n   *\n   * @param headers - HTTP headers\n   * @param args - Additional context args (sessionId, scopeId)\n   * @param fn - Async function to run\n   * @returns Result of the callback\n   */\n  runFromHeaders<T>(\n    headers: Record<string, unknown>,\n    args: Omit<FrontMcpContextArgs, 'traceContext' | 'metadata'>,\n    fn: () => T | Promise<T>,\n  ): T | Promise<T> {\n    const traceContext = parseTraceContext(headers);\n    const metadata = extractMetadata(headers);\n    const context = new FrontMcpContext({\n      ...args,\n      traceContext,\n      metadata,\n    });\n    return frontmcpContextStorage.run(context, fn);\n  }\n\n  /**\n   * Run with an existing FrontMcpContext.\n   *\n   * Useful when you need to propagate an existing context to a new async scope.\n   *\n   * @param context - Existing FrontMcpContext\n   * @param fn - Async function to run\n   * @returns Result of the callback\n   */\n  runWithContext<T>(context: FrontMcpContext, fn: () => T | Promise<T>): T | Promise<T> {\n    return frontmcpContextStorage.run(context, fn);\n  }\n\n  /**\n   * Get the current FrontMcpContext.\n   *\n   * @returns Current context or undefined if not in a context scope\n   */\n  getStore(): FrontMcpContext | undefined {\n    return frontmcpContextStorage.getStore();\n  }\n\n  /**\n   * Get the current FrontMcpContext, throwing if not available.\n   *\n   * @throws Error if not in a context scope\n   */\n  getStoreOrThrow(): FrontMcpContext {\n    const ctx = this.getStore();\n    if (!ctx) {\n      throw new RequestContextNotAvailableError(\n        'FrontMcpContext not available. Ensure operation runs within context scope.',\n      );\n    }\n    return ctx;\n  }\n\n  /**\n   * Check if currently running within a context.\n   *\n   * @returns True if a FrontMcpContext is available\n   */\n  hasContext(): boolean {\n    return frontmcpContextStorage.getStore() !== undefined;\n  }\n\n  /**\n   * Update the authInfo in the current context.\n   *\n   * This mutates the existing context in place to preserve internal state\n   * (marks, store, sessionMetadata) while updating auth info.\n   *\n   * @param authInfo - Auth info fields to set/update (merged with existing)\n   * @param fn - Function to run after update\n   * @returns Result of the callback\n   */\n  updateAuthInfo<T>(authInfo: Partial<AuthInfo>, fn: () => T | Promise<T>): T | Promise<T> {\n    const current = this.getStoreOrThrow();\n    current.updateAuthInfo(authInfo);\n    return fn();\n  }\n}\n\n/**\n * Extract request metadata from headers.\n */\nfunction extractMetadata(headers: Record<string, unknown>): RequestMetadata {\n  const customHeaders: Record<string, string> = {};\n\n  for (const [key, value] of Object.entries(headers)) {\n    if (key.toLowerCase().startsWith('x-frontmcp-') && typeof value === 'string') {\n      customHeaders[key.toLowerCase()] = value;\n    }\n  }\n\n  return {\n    userAgent: typeof headers['user-agent'] === 'string' ? headers['user-agent'] : undefined,\n    contentType: typeof headers['content-type'] === 'string' ? headers['content-type'] : undefined,\n    accept: typeof headers['accept'] === 'string' ? headers['accept'] : undefined,\n    clientIp: extractClientIp(headers),\n    customHeaders,\n  };\n}\n\n/**\n * Extract client IP from headers.\n * Handles both string and array header values (some adapters pass arrays).\n */\nfunction extractClientIp(headers: Record<string, unknown>): string | undefined {\n  // x-forwarded-for can be comma-separated list; first is client IP\n  const xff = headers['x-forwarded-for'];\n  if (typeof xff === 'string') {\n    return xff.split(',')[0]?.trim();\n  }\n  // Some adapters pass arrays for multi-value headers\n  if (Array.isArray(xff) && typeof xff[0] === 'string') {\n    return xff[0].split(',')[0]?.trim();\n  }\n\n  const realIp = headers['x-real-ip'];\n  if (typeof realIp === 'string') {\n    return realIp;\n  }\n  if (Array.isArray(realIp) && typeof realIp[0] === 'string') {\n    return realIp[0];\n  }\n\n  return undefined;\n}\n\n/**\n * Alias for backward compatibility.\n * @deprecated Use FrontMcpContextStorage instead\n */\nexport { FrontMcpContextStorage as ContextStorage };\n"]}

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

@@ -0,0 +1,269 @@
+/**
+ * FrontMcpContext - Unified context for FrontMCP
+ *
+ * Single point of truth for all request-related data, combining session and request state.
+ * Flows through the entire async execution chain via AsyncLocalStorage.
+ *
+ * Access via DI using the FRONTMCP_CONTEXT token:
+ * ```typescript
+ * const ctx = this.get(FRONTMCP_CONTEXT);
+ * console.log(ctx.requestId, ctx.sessionId, ctx.authInfo);
+ * ```
+ */
+import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import { FrontMcpLogger } from '../common/interfaces/logger.interface';
+import { TraceContext } from './trace-context';
+import type { SessionIdPayload } from '../common/types';
+/**
+ * Request metadata extracted from HTTP headers.
+ */
+export interface RequestMetadata {
+    /** User-Agent header */
+    userAgent?: string;
+    /** Content-Type header */
+    contentType?: string;
+    /** Accept header */
+    accept?: string;
+    /** Client IP address (from x-forwarded-for or socket) */
+    clientIp?: string;
+    /** Custom headers matching x-frontmcp-* pattern */
+    customHeaders: Record<string, string>;
+}
+/**
+ * Configuration for the context.
+ */
+export interface FrontMcpContextConfig {
+    /** Auto-inject auth headers in fetch requests (default: true) */
+    autoInjectAuthHeaders?: boolean;
+    /** Auto-inject tracing headers in fetch requests (default: true) */
+    autoInjectTracingHeaders?: boolean;
+    /** Default fetch request timeout in milliseconds (default: 30000) */
+    requestTimeout?: number;
+}
+/**
+ * Arguments for creating a FrontMcpContext.
+ */
+export interface FrontMcpContextArgs {
+    /** Optional request ID (generated if not provided) */
+    requestId?: string;
+    /** Optional trace context (generated if not provided) */
+    traceContext?: TraceContext;
+    /** Session identifier (required) */
+    sessionId: string;
+    /** Authentication information (can be partial, progressively populated) */
+    authInfo?: Partial<AuthInfo>;
+    /** Scope identifier (required) */
+    scopeId: string;
+    /** Optional timestamp (defaults to Date.now()) */
+    timestamp?: number;
+    /** Optional request metadata */
+    metadata?: RequestMetadata;
+    /** Optional configuration */
+    config?: FrontMcpContextConfig;
+}
+/**
+ * Interface for transport access (elicit support).
+ * Provides clean API for accessing transport capabilities.
+ */
+export interface TransportAccessor {
+    /**
+     * Check if transport supports elicit requests.
+     */
+    readonly supportsElicit: boolean;
+    /**
+     * Send an elicit request to the client for interactive input.
+     *
+     * @param message - Message to display to the user
+     * @param requestedSchema - Zod schema for validating the response
+     * @returns Typed elicit result with action and validated content
+     */
+    elicit<T>(message: string, requestedSchema: T): Promise<{
+        action: string;
+        content: unknown;
+    }>;
+}
+type FlowBaseRef = {
+    readonly name: string;
+};
+type ScopeRef = {
+    readonly id: string;
+    readonly logger: FrontMcpLogger;
+};
+type TransportRef = {
+    sendElicitRequest: TransportAccessor['elicit'];
+    readonly type: string;
+};
+/**
+ * FrontMcpContext - Unified context for FrontMCP
+ *
+ * Provides a single point of truth for all request-related data:
+ * - Identity: requestId, sessionId, scopeId
+ * - Tracing: W3C trace context
+ * - Auth: authentication information (progressively populated)
+ * - References: transport, flow, scope (pointers, not copies)
+ * - Store: key/value storage for context-scoped data
+ * - Fetch: context-aware fetch with auto-injection
+ */
+export declare class FrontMcpContext {
+    /** Unique request identifier (UUID v4) */
+    readonly requestId: string;
+    /** Session identifier (validated) */
+    readonly sessionId: string;
+    /** Scope identifier */
+    readonly scopeId: string;
+    /** W3C Trace Context or generated trace ID */
+    readonly traceContext: TraceContext;
+    /** Request start timestamp */
+    readonly timestamp: number;
+    /** Context configuration */
+    readonly config: FrontMcpContextConfig;
+    /** Request metadata (headers, user-agent, etc.) */
+    readonly metadata: RequestMetadata;
+    private _authInfo;
+    private _sessionMetadata?;
+    private _transport?;
+    private _flow?;
+    private _scope?;
+    private readonly marks;
+    private readonly store;
+    constructor(args: FrontMcpContextArgs);
+    /**
+     * Get authentication information.
+     * Returns Partial<AuthInfo> because auth info is progressively populated.
+     */
+    get authInfo(): Partial<AuthInfo>;
+    /**
+     * Update auth info after authorization is verified.
+     * Can be called multiple times to progressively add fields.
+     *
+     * @param authInfo - The auth info fields to set/update
+     * @internal
+     */
+    updateAuthInfo(authInfo: Partial<AuthInfo>): void;
+    /**
+     * Get session metadata (protocol, platform type, node info).
+     * Only available after session verification.
+     */
+    get sessionMetadata(): SessionIdPayload | undefined;
+    /**
+     * Update session metadata after session verification.
+     *
+     * @param metadata - Session metadata from verified session
+     * @internal
+     */
+    updateSessionMetadata(metadata: SessionIdPayload): void;
+    /**
+     * Get transport accessor for elicit support.
+     * Returns undefined if no transport is registered.
+     */
+    get transport(): TransportAccessor | undefined;
+    /**
+     * Set transport reference (internal use).
+     * @internal
+     */
+    setTransport(transport: TransportRef): void;
+    /**
+     * Get current flow reference.
+     */
+    get flow(): FlowBaseRef | undefined;
+    /**
+     * Set flow reference (internal use).
+     * @internal
+     */
+    setFlow(flow: FlowBaseRef): void;
+    /**
+     * Get scope reference.
+     */
+    get scope(): ScopeRef | undefined;
+    /**
+     * Set scope reference (internal use).
+     * @internal
+     */
+    setScope(scope: ScopeRef): void;
+    /**
+     * Store context-scoped data.
+     *
+     * @param key - Storage key
+     * @param value - Value to store
+     */
+    set<T>(key: string | symbol, value: T): void;
+    /**
+     * Retrieve context-scoped data.
+     *
+     * @param key - Storage key
+     * @returns Stored value or undefined
+     */
+    get<T>(key: string | symbol): T | undefined;
+    /**
+     * Check if a key exists in the context store.
+     *
+     * @param key - Storage key
+     * @returns True if key exists
+     */
+    has(key: string | symbol): boolean;
+    /**
+     * Delete a key from the context store.
+     *
+     * @param key - Storage key
+     * @returns True if key was deleted
+     */
+    delete(key: string | symbol): boolean;
+    /**
+     * Mark a timing point for performance tracking.
+     *
+     * @param name - Name of the timing mark
+     */
+    mark(name: string): void;
+    /**
+     * Get elapsed time in milliseconds between two marks.
+     *
+     * @param from - Start mark name (defaults to 'init')
+     * @param to - End mark name (defaults to current time)
+     * @returns Elapsed time in milliseconds
+     */
+    elapsed(from?: string, to?: string): number;
+    /**
+     * Get all timing marks.
+     *
+     * @returns Read-only map of mark names to timestamps
+     */
+    getMarks(): ReadonlyMap<string, number>;
+    /**
+     * Get a child logger with context attached.
+     *
+     * Creates a child logger with a prefix containing the request ID and trace ID
+     * for easy request tracing in logs.
+     *
+     * @param parentLogger - The parent logger to create a child from
+     * @returns A logger with requestId and traceId in the prefix
+     */
+    getLogger(parentLogger: FrontMcpLogger): FrontMcpLogger;
+    /**
+     * Get a summary of the context for logging.
+     *
+     * Note: sessionId is hashed to prevent accidental exposure of user-identifying
+     * session identifiers in logs while still allowing correlation.
+     *
+     * @returns Object with key context fields
+     */
+    toLogContext(): Record<string, unknown>;
+    /**
+     * Perform a fetch request with automatic header injection.
+     *
+     * Injects:
+     * - Authorization header (if authInfo.token is available and autoInjectAuthHeaders is true)
+     * - W3C traceparent header (if autoInjectTracingHeaders is true)
+     * - x-request-id header
+     * - Custom headers from request metadata
+     *
+     * @param input - Request URL or Request object
+     * @param init - Request options
+     * @returns Fetch response
+     */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+/**
+ * Alias for FrontMcpContext.
+ * Use when you want a shorter name.
+ */
+export { FrontMcpContext as Context };