@frontmcp/sdk 0.1.0

package/src/interfaces/internal/primary-auth-provider.interface.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Auth = exports.FrontMcpAuth = void 0;
+const utils_1 = require("../../utils");
+/**
+ * Base class for primary auth provider.
+ * Used for easy access current auth context by dependency injection.
+ *
+ * In tool context, you can access current auth context by calling:
+ *  this.get(FrontMcpAuth) | this.get(Auth)
+ *
+ * Or in session scoped Providers in constructor arguments:
+ *  constructor(private readonly auth: FrontMcpAuth) {
+ *  // auth.fetch('MY endpoint ')
+ *  }
+ */
+class FrontMcpAuth {
+    ready;
+    options;
+    id;
+    constructor(options) {
+        this.options = options;
+        if (options.type === 'local') {
+            this.id = options.id;
+        }
+        else {
+            this.id = options.id ?? (0, utils_1.urlToSafeId)(options.baseUrl);
+        }
+    }
+}
+exports.FrontMcpAuth = FrontMcpAuth;
+exports.Auth = FrontMcpAuth;
+//# sourceMappingURL=primary-auth-provider.interface.js.map

package/src/interfaces/internal/primary-auth-provider.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primary-auth-provider.interface.js","sourceRoot":"","sources":["../../../../src/interfaces/internal/primary-auth-provider.interface.ts"],"names":[],"mappings":";;;AAEA,uCAA0C;AAG1C;;;;;;;;;;;GAWG;AACH,MAAsB,YAAY;IAChC,KAAK,CAAgB;IACZ,OAAO,CAAc;IACrB,EAAE,CAAS;IAEpB,YAAY,OAAoB;QAC9B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,IAAA,mBAAW,EAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACvD,CAAC;IAEH,CAAC;CAOF;AApBD,oCAoBC;AAGiB,4BAAI","sourcesContent":["import { ServerRequest } from '../server.interface';\nimport { AuthOptions } from '../../types';\nimport { urlToSafeId } from '../../utils';\n\n\n/**\n * Base class for primary auth provider.\n * Used for easy access current auth context by dependency injection.\n *\n * In tool context, you can access current auth context by calling:\n *  this.get(FrontMcpAuth) | this.get(Auth)\n *\n * Or in session scoped Providers in constructor arguments:\n *  constructor(private readonly auth: FrontMcpAuth) {\n *  // auth.fetch('MY endpoint ')\n *  }\n */\nexport abstract class FrontMcpAuth {\n  ready: Promise<void>;\n  readonly options: AuthOptions;\n  readonly id: string;\n\n  constructor(options: AuthOptions) {\n    this.options = options;\n    if (options.type === 'local') {\n      this.id = options.id;\n    } else {\n      this.id = options.id ?? urlToSafeId(options.baseUrl);\n    }\n\n  }\n\n  abstract fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;\n\n  abstract validate(request: ServerRequest): Promise<void>\n\n  abstract get issuer(): string\n}\n\nexport {\n  FrontMcpAuth as Auth,\n};"]}

package/src/interfaces/internal/registry.interface.d.ts

@@ -0,0 +1,71 @@
+import { ScopeEntry, FlowEntry, AuthProviderEntry, AppEntry, ProviderEntry, PluginEntry, AdapterEntry, PromptEntry, ResourceEntry, ToolEntry, LoggerEntry } from '../../entries';
+import { Token } from '../base.interface';
+import { EntryOwnerRef } from '../../entries/base.entry';
+import { FrontMcpAuth } from './primary-auth-provider.interface';
+import { FlowName } from '../../metadata';
+export interface ScopeRegistryInterface {
+    getScopes(): ScopeEntry[];
+}
+export interface FlowRegistryInterface {
+    getFlows(): FlowEntry<FlowName>[];
+}
+export interface ProviderViews {
+    /** App-wide singletons, created at boot. Immutable from invoke’s POV. */
+    global: ReadonlyMap<Token, unknown>;
+    /** Session-scoped cache for this sessionId. Mutable. */
+    session: Map<Token, unknown>;
+    /** Request-scoped providers for this single invocation. Mutable. */
+    request: Map<Token, unknown>;
+}
+export interface ProviderRegistryInterface {
+    get<T>(token: Token<T>): T;
+    getProviders(): ProviderEntry[];
+    getRegistries<T extends RegistryKind>(type: T): RegistryType[T][];
+    buildViews(session: any): Promise<ProviderViews>;
+}
+export interface AuthRegistryInterface {
+    getPrimary(): FrontMcpAuth;
+    getAuthProviders(): AuthProviderEntry[];
+}
+export interface AppRegistryInterface {
+    getApps(): AppEntry[];
+}
+export interface PluginRegistryInterface {
+    getPlugins(): PluginEntry[];
+}
+export interface AdapterRegistryInterface {
+    getAdapters(): AdapterEntry[];
+}
+export interface ToolRegistryInterface {
+    owner: EntryOwnerRef;
+    getTools(includeHidden?: boolean): ToolEntry<any, any>[];
+    getInlineTools(): ToolEntry<any, any>[];
+}
+export interface ResourceRegistryInterface {
+    getResources(): ResourceEntry<any, any>[];
+    getInlineResources(): ResourceEntry<any, any>[];
+}
+export interface PromptRegistryInterface {
+    getPrompts(): PromptEntry[];
+    getInlinePrompts(): PromptEntry[];
+}
+export interface LoggerRegistryInterface {
+    getLoggers(): LoggerEntry[];
+}
+export type GlobalRegistryKind = 'LoggerRegistry' | 'ScopeRegistry';
+export type ScopedRegistryKind = 'AppRegistry' | 'AuthRegistry' | 'FlowRegistry';
+export type AppRegistryKind = 'ProviderRegistry' | 'PluginRegistry' | 'AdapterRegistry' | 'ToolRegistry' | 'PromptRegistry' | 'ResourceRegistry';
+export type RegistryKind = GlobalRegistryKind | ScopedRegistryKind | AppRegistryKind;
+export type RegistryType = {
+    LoggerRegistry: LoggerRegistryInterface;
+    ScopeRegistry: ScopeRegistryInterface;
+    FlowRegistry: FlowRegistryInterface;
+    AppRegistry: AppRegistryInterface;
+    AuthRegistry: AuthRegistryInterface;
+    ProviderRegistry: ProviderRegistryInterface;
+    PluginRegistry: PluginRegistryInterface;
+    AdapterRegistry: AdapterRegistryInterface;
+    ToolRegistry: ToolRegistryInterface;
+    ResourceRegistry: ResourceRegistryInterface;
+    PromptRegistry: PromptRegistryInterface;
+};

package/src/interfaces/internal/registry.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=registry.interface.js.map

package/src/interfaces/internal/registry.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.interface.js","sourceRoot":"","sources":["../../../../src/interfaces/internal/registry.interface.ts"],"names":[],"mappings":"","sourcesContent":["import {\n  ScopeEntry,\n  FlowEntry,\n  AuthProviderEntry,\n  AppEntry,\n  ProviderEntry,\n  PluginEntry,\n  AdapterEntry,\n  PromptEntry,\n  ResourceEntry,\n  ToolEntry, LoggerEntry,\n} from '../../entries';\nimport { Token } from '../base.interface';\nimport { EntryOwnerRef } from '../../entries/base.entry';\nimport { FrontMcpAuth } from './primary-auth-provider.interface';\nimport { FlowName } from '../../metadata';\n\nexport interface ScopeRegistryInterface {\n  getScopes(): ScopeEntry[];\n}\n\nexport interface FlowRegistryInterface {\n  getFlows(): FlowEntry<FlowName>[];\n}\n\n\nexport interface ProviderViews {\n  /** App-wide singletons, created at boot. Immutable from invoke’s POV. */\n  global: ReadonlyMap<Token, unknown>;\n  /** Session-scoped cache for this sessionId. Mutable. */\n  session: Map<Token, unknown>;\n  /** Request-scoped providers for this single invocation. Mutable. */\n  request: Map<Token, unknown>;\n}\n\n\nexport interface ProviderRegistryInterface {\n  get<T>(token: Token<T>): T;\n\n  getProviders(): ProviderEntry[];\n\n  getRegistries<T extends RegistryKind>(type: T): RegistryType[T][];\n\n  // TODO: fix session type\n  buildViews(session: any): Promise<ProviderViews>;\n}\n\nexport interface AuthRegistryInterface {\n  getPrimary(): FrontMcpAuth;\n\n  getAuthProviders(): AuthProviderEntry[];\n}\n\nexport interface AppRegistryInterface {\n  getApps(): AppEntry[];\n}\n\nexport interface PluginRegistryInterface {\n  getPlugins(): PluginEntry[];\n\n  //\n  // // nested adapters\n  // getAdapters(): AdapterEntry[];\n  //\n  // // plugin tools plus nested adapter's tools\n  // getTools(): ToolEntry<any, any>[];\n  //\n  // // plugin resources plus nested adapter's tools\n  // getResources(): ResourceEntry[];\n  //\n  // // plugin prompts plus nested adapter's tools\n  // getPrompts(): PromptEntry[];\n}\n\nexport interface AdapterRegistryInterface {\n  getAdapters(): AdapterEntry[];\n\n  //\n  // // nested tools\n  // getTools(): ToolEntry<any, any>[];\n  //\n  // getResources(): ResourceEntry[];\n  //\n  // getPrompts(): PromptEntry[];\n}\n\nexport interface ToolRegistryInterface {\n  owner: EntryOwnerRef;\n\n  // inline tools plus discovered by nested tool registries\n  getTools(includeHidden?:boolean): ToolEntry<any, any>[];\n\n  // inline tools only\n  getInlineTools(): ToolEntry<any, any>[];\n}\n\n\nexport interface ResourceRegistryInterface {\n  // inline resources plus discovered by nested tool registries\n  getResources(): ResourceEntry<any, any>[];\n\n  // inline resources only\n  getInlineResources(): ResourceEntry<any, any>[];\n}\n\n\nexport interface PromptRegistryInterface {\n  // inline prompts plus discovered by nested tool registries\n  getPrompts(): PromptEntry[];\n\n  // inline prompts only\n  getInlinePrompts(): PromptEntry[];\n}\n\n\nexport interface LoggerRegistryInterface {\n  getLoggers(): LoggerEntry[];\n\n}\n\n\nexport type GlobalRegistryKind =\n  | 'LoggerRegistry'\n  | 'ScopeRegistry'\n\nexport type ScopedRegistryKind =\n  | 'AppRegistry'\n  | 'AuthRegistry'\n  | 'FlowRegistry'\n\nexport type AppRegistryKind =\n  | 'ProviderRegistry'\n  | 'PluginRegistry'\n  | 'AdapterRegistry'\n  | 'ToolRegistry'\n  | 'PromptRegistry'\n  | 'ResourceRegistry'\n\n\nexport type RegistryKind = GlobalRegistryKind | ScopedRegistryKind | AppRegistryKind;\n\nexport type RegistryType = {\n  LoggerRegistry: LoggerRegistryInterface;\n  ScopeRegistry: ScopeRegistryInterface;\n  FlowRegistry: FlowRegistryInterface;\n  AppRegistry: AppRegistryInterface;\n  AuthRegistry: AuthRegistryInterface,\n  ProviderRegistry: ProviderRegistryInterface;\n  PluginRegistry: PluginRegistryInterface;\n  AdapterRegistry: AdapterRegistryInterface;\n  ToolRegistry: ToolRegistryInterface;\n  ResourceRegistry: ResourceRegistryInterface;\n  PromptRegistry: PromptRegistryInterface;\n}"]}

package/src/interfaces/logger.interface.d.ts

@@ -0,0 +1,42 @@
+import { Type } from './base.interface';
+import { LogLevel } from '../types';
+export interface LogRecord {
+    level: LogLevel;
+    levelName: string;
+    message: string;
+    args: unknown[];
+    timestamp: Date;
+    prefix: string;
+}
+export type LogFn = (msg?: any, ...args: any[]) => void;
+export declare abstract class LogTransportInterface {
+    abstract log(rec: LogRecord): void;
+}
+export type LogTransportType<T = any> = Type<T>;
+export declare abstract class FrontMcpLogger {
+    abstract child(prefix: string): FrontMcpLogger;
+    /**
+     * Verbose — extremely granular, high-volume logs useful when diagnosing tricky bugs
+     * (function entry/exit, detailed branches, low-level I/O). Disable in most environments.
+     */
+    abstract get verbose(): ((...args: any[]) => void);
+    /**
+     * Debug — development-focused diagnostics (state changes, computed values, API request params),
+     * still fairly verbose but less noisy than TRACE. Typically disabled in production.
+     */
+    abstract get debug(): ((...args: any[]) => void);
+    /**
+     * Info — key milestones in normal operation (server start, feature toggles, user actions,
+     * successful requests). Safe to keep enabled in production.
+     */
+    abstract get info(): ((...args: any[]) => void);
+    /**
+     * Warn — unexpected or suboptimal situations that the system handled and continued
+     * (fallbacks, retries, partial failures). Worth investigating but not service-breaking.
+     */
+    abstract get warn(): ((...args: any[]) => void);
+    /**
+     * Error — failures where an operation could not complete or data is invalid,
+     */
+    abstract get error(): ((...args: any[]) => void);
+}

package/src/interfaces/logger.interface.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrontMcpLogger = exports.LogTransportInterface = void 0;
+class LogTransportInterface {
+}
+exports.LogTransportInterface = LogTransportInterface;
+class FrontMcpLogger {
+}
+exports.FrontMcpLogger = FrontMcpLogger;
+//# sourceMappingURL=logger.interface.js.map

package/src/interfaces/logger.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.interface.js","sourceRoot":"","sources":["../../../src/interfaces/logger.interface.ts"],"names":[],"mappings":";;;AAeA,MAAsB,qBAAqB;CAE1C;AAFD,sDAEC;AAOD,MAAsB,cAAc;CAgCnC;AAhCD,wCAgCC","sourcesContent":["import { Type } from './base.interface';\nimport { LogLevel } from '../types';\n\n\nexport interface LogRecord {\n  level: LogLevel;\n  levelName: string;\n  message: string;\n  args: unknown[];\n  timestamp: Date;\n  prefix: string;\n}\n\nexport type LogFn = (msg?: any, ...args: any[]) => void;\n\nexport abstract class LogTransportInterface {\n  abstract log(rec: LogRecord): void\n}\n\n\nexport type LogTransportType<T = any> =\n  | Type<T>\n\n\nexport abstract class FrontMcpLogger {\n  abstract child(prefix: string): FrontMcpLogger;\n\n  /**\n   * Verbose — extremely granular, high-volume logs useful when diagnosing tricky bugs\n   * (function entry/exit, detailed branches, low-level I/O). Disable in most environments.\n   */\n  abstract get verbose(): ((...args: any[]) => void);\n\n  /**\n   * Debug — development-focused diagnostics (state changes, computed values, API request params),\n   * still fairly verbose but less noisy than TRACE. Typically disabled in production.\n   */\n  abstract get debug(): ((...args: any[]) => void);\n\n  /**\n   * Info — key milestones in normal operation (server start, feature toggles, user actions,\n   * successful requests). Safe to keep enabled in production.\n   */\n  abstract get info(): ((...args: any[]) => void);\n\n  /**\n   * Warn — unexpected or suboptimal situations that the system handled and continued\n   * (fallbacks, retries, partial failures). Worth investigating but not service-breaking.\n   */\n  abstract get warn(): ((...args: any[]) => void);\n\n  /**\n   * Error — failures where an operation could not complete or data is invalid,\n   */\n  abstract get error(): ((...args: any[]) => void);\n\n}\n"]}

package/src/interfaces/plugin.interface.d.ts

@@ -0,0 +1,8 @@
+import { Type, Token, ValueType, ClassType, FactoryType } from './base.interface';
+import { PluginMetadata } from '../metadata';
+export interface PluginInterface {
+}
+export type PluginClassType<Provide> = ClassType<Provide> & PluginMetadata;
+export type PluginValueType<Provide> = ValueType<Provide> & PluginMetadata;
+export type PluginFactoryType<Provide, Tokens extends readonly Token[]> = FactoryType<Provide, Tokens> & PluginMetadata;
+export type PluginType<Provide extends PluginInterface = PluginInterface> = Type<Provide> | PluginClassType<Provide> | PluginValueType<Provide> | PluginFactoryType<Provide, any[]>;

package/src/interfaces/plugin.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=plugin.interface.js.map

package/src/interfaces/plugin.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.interface.js","sourceRoot":"","sources":["../../../src/interfaces/plugin.interface.ts"],"names":[],"mappings":"","sourcesContent":["import { Type, Token, ValueType, ClassType, FactoryType } from './base.interface';\nimport { PluginMetadata } from '../metadata';\n\nexport interface PluginInterface {\n\n}\n\n\nexport type PluginClassType<Provide> = ClassType<Provide> & PluginMetadata;\nexport type PluginValueType<Provide> = ValueType<Provide> & PluginMetadata;\nexport type PluginFactoryType<Provide, Tokens extends readonly Token[]> = FactoryType<Provide, Tokens> & PluginMetadata;\n\n\nexport type PluginType<Provide extends PluginInterface = PluginInterface> =\n  | Type<Provide>\n  | PluginClassType<Provide>\n  | PluginValueType<Provide>\n  | PluginFactoryType<Provide, any[]>\n\n"]}

package/src/interfaces/prompt.interface.d.ts

@@ -0,0 +1,5 @@
+import { FuncType, Type } from './base.interface';
+interface PromptInterface {
+}
+type PromptType = Type<PromptInterface> | FuncType<PromptInterface>;
+export { PromptInterface, PromptInterface as FrontMcpPromptInterface, PromptType, PromptType as FrontMcpPromptType, };

package/src/interfaces/prompt.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=prompt.interface.js.map

package/src/interfaces/prompt.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.interface.js","sourceRoot":"","sources":["../../../src/interfaces/prompt.interface.ts"],"names":[],"mappings":"","sourcesContent":["import { FuncType, Type } from './base.interface';\n\n\ninterface PromptInterface {\n\n}\n\ntype PromptType =\n  | Type<PromptInterface>\n  | FuncType<PromptInterface>;\n\n\nexport {\n  PromptInterface,\n  PromptInterface as FrontMcpPromptInterface,\n  PromptType,\n  PromptType as FrontMcpPromptType,\n};\n\n"]}

package/src/interfaces/provider.interface.d.ts

@@ -0,0 +1,20 @@
+import { Type, Token, ValueType, ClassType, FactoryType, ClassToken } from './base.interface';
+import { ProviderMetadata } from '../metadata';
+export interface ProviderInterface {
+}
+export type ProviderClassType<Provide> = ClassType<Provide> & ProviderMetadata;
+export type ProviderValueType<Provide> = ValueType<Provide> & ProviderMetadata;
+export type ProviderFactoryType<Provide, Tokens extends readonly (ClassToken | Token)[]> = FactoryType<Provide, Tokens> & ProviderMetadata;
+export type ProviderType<Provide extends ProviderInterface = any, Tokens extends readonly (ClassToken | Token)[] = readonly (ClassToken | Token)[]> = Type<Provide> | ProviderClassType<Provide> | ProviderValueType<Provide> | ProviderFactoryType<Provide, Tokens>;
+/**
+ * Helper to define factory providers without tuple widening.
+ * Enforces that `useFactory` params follow the `inject()` tokens (order + arity).
+ *
+ * Usage:
+ *   const p = AsyncMcpProvider({
+ *     provide: RedisProviderRef,
+ *     inject: () => [ExpenseConfigRef, RedisType] as const,
+ *     useFactory: async (config, redis) => new RedisProvider(redis),
+ *   });
+ */
+export declare function AsyncProvider<Provide, const Tokens extends readonly (ClassToken | Token)[]>(cfg: ProviderFactoryType<Provide, Tokens>): ProviderFactoryType<Provide, Tokens>;

package/src/interfaces/provider.interface.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncProvider = AsyncProvider;
+/**
+ * Helper to define factory providers without tuple widening.
+ * Enforces that `useFactory` params follow the `inject()` tokens (order + arity).
+ *
+ * Usage:
+ *   const p = AsyncMcpProvider({
+ *     provide: RedisProviderRef,
+ *     inject: () => [ExpenseConfigRef, RedisType] as const,
+ *     useFactory: async (config, redis) => new RedisProvider(redis),
+ *   });
+ */
+function AsyncProvider(cfg) {
+    return cfg;
+}
+//# sourceMappingURL=provider.interface.js.map

package/src/interfaces/provider.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.interface.js","sourceRoot":"","sources":["../../../src/interfaces/provider.interface.ts"],"names":[],"mappings":";;AAgCA,sCAIC;AAfD;;;;;;;;;;GAUG;AACH,SAAgB,aAAa,CAC3B,GAAyC;IAEzC,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["import { Type, Token, ValueType, ClassType, FactoryType, ClassToken } from './base.interface';\nimport { ProviderMetadata } from '../metadata';\n\nexport interface ProviderInterface {\n}\n\nexport type ProviderClassType<Provide> = ClassType<Provide> & ProviderMetadata;\nexport type ProviderValueType<Provide> = ValueType<Provide> & ProviderMetadata;\nexport type ProviderFactoryType<Provide, Tokens extends readonly (ClassToken | Token)[]> = FactoryType<Provide, Tokens> & ProviderMetadata;\n\n\nexport type ProviderType<\n  Provide extends ProviderInterface = any,\n  Tokens extends readonly (ClassToken | Token)[] = readonly (ClassToken | Token)[]\n> =\n  | Type<Provide>\n  | ProviderClassType<Provide>\n  | ProviderValueType<Provide>\n  | ProviderFactoryType<Provide, Tokens>\n\n\n/**\n * Helper to define factory providers without tuple widening.\n * Enforces that `useFactory` params follow the `inject()` tokens (order + arity).\n *\n * Usage:\n *   const p = AsyncMcpProvider({\n *     provide: RedisProviderRef,\n *     inject: () => [ExpenseConfigRef, RedisType] as const,\n *     useFactory: async (config, redis) => new RedisProvider(redis),\n *   });\n */\nexport function AsyncProvider<Provide, const Tokens extends readonly (ClassToken | Token)[]>(\n  cfg: ProviderFactoryType<Provide, Tokens>,\n): ProviderFactoryType<Provide, Tokens> {\n  return cfg;\n}\n"]}

package/src/interfaces/resource.interface.d.ts

@@ -0,0 +1,21 @@
+import { ResourceMetadata } from '../metadata';
+import { FuncType, Token, Type } from './base.interface';
+export interface ResourceInterface<In = any, Out = any> {
+    execute(input: In, context: ResourceContext<In, Out>): Promise<Out>;
+}
+export type ResourceType<In = any, Out = any> = Type<ResourceInterface<In, Out>> | FuncType<ResourceInterface<In, Out>>;
+export interface ResourceContext<In, Out> {
+    readonly resourceId: string;
+    readonly resourceName: string;
+    readonly metadata: ResourceMetadata;
+    get<T>(token: Token<T>): T;
+    tryGet<T>(token: Token<T>): T | undefined;
+    get inputHistory(): In[];
+    get outputHistory(): Out[];
+    set input(value: In);
+    get input(): In;
+    set output(value: Out);
+    get output(): Out | undefined;
+    respond(value: Out): never;
+    fail(reason: string, error: any): never;
+}

package/src/interfaces/resource.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=resource.interface.js.map

package/src/interfaces/resource.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.interface.js","sourceRoot":"","sources":["../../../src/interfaces/resource.interface.ts"],"names":[],"mappings":"","sourcesContent":["import { ResourceMetadata } from '../metadata';\nimport { FuncType, Token, Type } from './base.interface';\n\n\nexport interface ResourceInterface<In = any, Out = any> {\n  execute(input: In, context: ResourceContext<In, Out>): Promise<Out>;\n}\n\nexport type ResourceType<In = any, Out = any> =\n  | Type<ResourceInterface<In, Out>>\n  | FuncType<ResourceInterface<In, Out>>\n\n\nexport interface ResourceContext<In, Out> {\n  readonly resourceId: string;\n  readonly resourceName: string;\n  readonly metadata: ResourceMetadata;\n\n\n  get<T>(token: Token<T>): T;\n\n  tryGet<T>(token: Token<T>): T | undefined;\n\n  get inputHistory(): In[];\n\n  get outputHistory(): Out[];\n\n  set input(value: In);\n\n  get input(): In;\n\n  set output(value: Out);\n\n  get output(): Out | undefined;\n\n  respond(value: Out): never;\n\n  fail(reason: string, error: any): never;\n}"]}

package/src/interfaces/scope.interface.d.ts

@@ -0,0 +1,5 @@
+import { Type } from './base.interface';
+export interface ScopeInterface {
+}
+export type ScopeType = Type<ScopeInterface>;
+export { ScopeInterface as FrontMcpScopeInterface, ScopeType as FrontMcpScopeType, };

package/src/interfaces/scope.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=scope.interface.js.map

package/src/interfaces/scope.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.interface.js","sourceRoot":"","sources":["../../../src/interfaces/scope.interface.ts"],"names":[],"mappings":"","sourcesContent":["import { Type } from './base.interface';\n\nexport interface ScopeInterface {\n\n}\n\nexport type ScopeType = Type<ScopeInterface>\n\n\nexport {\n  ScopeInterface as FrontMcpScopeInterface,\n  ScopeType as FrontMcpScopeType,\n}"]}

package/src/interfaces/server.interface.d.ts

@@ -0,0 +1,46 @@
+import { IncomingMessage, ServerResponse as HttpServerResponse } from 'http';
+import { Authorization } from '../types';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+export declare class ServerRequest extends IncomingMessage {
+    method: HttpMethod;
+    path: string;
+    url: string;
+    headers: Record<string, string>;
+    query: Record<string, string | string[]>;
+    body?: any;
+    authSession?: Authorization;
+}
+export declare abstract class ServerResponse extends HttpServerResponse {
+    abstract status(code: number): ServerResponse;
+    abstract json(payload: any): void;
+    abstract send(payload: any): void;
+    abstract redirect(url: string): void;
+    abstract redirect(status: number, url: string): void;
+}
+export type NextFn = () => Promise<void> | void;
+export type ServerRequestHandler = (req: ServerRequest, res: ServerResponse, next: NextFn) => Promise<void> | void;
+export declare abstract class FrontMcpServer {
+    /**
+     * Register a middleware handler for a specific entry path.
+     * @param entryPath - e.g. '' or '/mcp'
+     * @param handler - (req, res, next) => {// middleware // next()}
+     */
+    abstract registerMiddleware(entryPath: string, handler: ServerRequestHandler): Promise<void> | void;
+    /**
+     * Register a route handler for a specific path.
+     * @param method - e.g. 'GET' or 'POST'
+     * @param path - e.g. '/mcp/invoke'
+     * @param handler - (req, res) => {// route handler // res.end() }
+     */
+    abstract registerRoute(method: HttpMethod, path: string, handler: ServerRequestHandler): Promise<void> | void;
+    /**
+     * Enhance a request handler with request/response processing and error handling.
+     * This handle will be stored as the first middleware in the chain to align adapter handler
+     * with the gateway's request/response processing.
+     */
+    abstract enhancedHandler(handler: ServerRequestHandler): (req: any, res: any, next: () => any) => Promise<void> | void;
+    /**
+     *  Start the server on the specified port
+     */
+    abstract start(port?: number): Promise<void> | void;
+}

package/src/interfaces/server.interface.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrontMcpServer = exports.ServerResponse = exports.ServerRequest = void 0;
+const http_1 = require("http");
+class ServerRequest extends http_1.IncomingMessage {
+    path;
+    query;
+    body;
+    authSession;
+}
+exports.ServerRequest = ServerRequest;
+class ServerResponse extends http_1.ServerResponse {
+}
+exports.ServerResponse = ServerResponse;
+class FrontMcpServer {
+}
+exports.FrontMcpServer = FrontMcpServer;
+//# sourceMappingURL=server.interface.js.map

package/src/interfaces/server.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.interface.js","sourceRoot":"","sources":["../../../src/interfaces/server.interface.ts"],"names":[],"mappings":";;;AAAA,+BAA6E;AAK7E,MAAa,aAAc,SAAQ,sBAAe;IAEhD,IAAI,CAAS;IAGb,KAAK,CAAoC;IACzC,IAAI,CAAO;IACX,WAAW,CAAiB;CAC7B;AARD,sCAQC;AAED,MAAsB,cAAe,SAAQ,qBAAkB;CAU9D;AAVD,wCAUC;AAMD,MAAsB,cAAc;CA+BnC;AA/BD,wCA+BC","sourcesContent":["import { IncomingMessage, ServerResponse as HttpServerResponse } from 'http';\nimport { Authorization } from '../types'; // TODO: move to internal\n\nexport type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';\n\nexport class ServerRequest extends IncomingMessage {\n  declare method: HttpMethod;\n  path: string;\n  declare url: string;\n  declare headers: Record<string, string>;\n  query: Record<string, string | string[]>;\n  body?: any;\n  authSession?: Authorization;\n}\n\nexport abstract class ServerResponse extends HttpServerResponse {\n  abstract status(code: number): ServerResponse;\n\n  abstract json(payload: any): void;\n\n  abstract send(payload: any): void;\n\n  abstract redirect(url: string): void;\n\n  abstract redirect(status: number, url: string): void;\n}\n\nexport type NextFn = () => Promise<void> | void;\n\nexport type ServerRequestHandler = (req: ServerRequest, res: ServerResponse, next: NextFn) => Promise<void> | void;\n\nexport abstract class FrontMcpServer {\n\n  /**\n   * Register a middleware handler for a specific entry path.\n   * @param entryPath - e.g. '' or '/mcp'\n   * @param handler - (req, res, next) => {// middleware // next()}\n   */\n  abstract registerMiddleware(entryPath: string, handler: ServerRequestHandler): Promise<void> | void;\n\n  /**\n   * Register a route handler for a specific path.\n   * @param method - e.g. 'GET' or 'POST'\n   * @param path - e.g. '/mcp/invoke'\n   * @param handler - (req, res) => {// route handler // res.end() }\n   */\n  abstract registerRoute(method: HttpMethod, path: string, handler: ServerRequestHandler): Promise<void> | void;\n\n  /**\n   * Enhance a request handler with request/response processing and error handling.\n   * This handle will be stored as the first middleware in the chain to align adapter handler\n   * with the gateway's request/response processing.\n   */\n  abstract enhancedHandler(\n    handler: ServerRequestHandler,\n  ): (req: any, res: any, next: () => any) => Promise<void> | void;\n\n\n  /**\n   *  Start the server on the specified port\n   */\n  abstract start(port?: number): Promise<void> | void;\n}"]}

package/src/interfaces/session-hook.interface.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Lifecycle stages for session invocation.
+ *
+ * Ordering notes:
+ * - "will*" stages run before the action; "did*" stages run after.
+ * - Higher `priority()` runs earlier for "will*" (outermost), and later for "did*".
+ * - Finalization stages (`willFinalize`, `willAudit`, `didAudit`, `onMetrics`) should be placed
+ *   in your plan’s `finalize` array to run on both success and error paths.
+ *
+ * Control flow:
+ * - Hooks may call `ctx.respond(value)` to short-circuit with a return value.
+ * - Hooks may call `ctx.abort(reason, code?, httpStatus?)` to stop with an error.
+ *
+ * Common context fields:
+ * - `ctx.sessionId` SecureMcp session id (== secureJwt) once created/validated.
+ * - `ctx.input`/`output` Arbitrary payloads for the current flow.
+ * - `ctx.data` Shared bag for cross-hook state.
+ * - `ctx.providers` Optional provider views if needed for UI/selection.
+ */
+export declare enum SessionHookStage {
+    /** Prepare a new session (or re-register an incoming secureJwt).
+     * Responsibilities:
+     * - Validate incoming token (if any); compute defaults; attach user hints.
+     * - Initialize per-session resources and attach to `ctx.data`.
+     * Failure modes:
+     * - `ctx.abort('invalid jwt', 'INVALID_SESSION', 401)`.
+     */
+    willCreateSession = "willCreateSession",
+    /** Session created and registered.
+     * Responsibilities:
+     * - Announce readiness (mount handlers/streams), emit side-effects if needed.
+     * - Optionally shape `ctx.output` with a `SessionContextView`.
+     */
+    didCreateSession = "didCreateSession",
+    /** Bind DI providers needed for this session/request.
+     * Responsibilities:
+     * - Resolve and bind providers so later hooks can `ctx.get(...)`.
+     * - May set `ctx.bindProvider/bindProviders` helpers.
+     */
+    willBindProviders = "willBindProviders",
+    /** Signal the beginning of an auth sequence in the scope of this session.
+     * Responsibilities:
+     * - Initialize auth-related state (PKCE/state, CSRF, telemetry).
+     * - Decide transport (SSE/StreamableHTTP) for status/URL events if applicable.
+     */
+    willBeginAuth = "willBeginAuth",
+    /** Streamable authorization progress within the session.
+     * Responsibilities:
+     * - Emit URL/status events (e.g., “authorize_url”, “awaiting_callback”).
+     * - Optionally `ctx.respond({event: ...})` for push-style transports.
+     */
+    willAuthorize = "willAuthorize",// stream-able events (URL/status)
+    /** Prepare and gate the token exchange with the provider.
+     * Responsibilities:
+     * - Verify callback params; ensure prerequisites (sessionId present).
+     * - Compute exchange request; rate-limit/anti-replay checks.
+     * Failure modes:
+     * - `ctx.abort('invalid state/pkce', 'OAUTH_CALLBACK_ERROR', 400)`.
+     */
+    willExchangeToken = "willExchangeToken",
+    /** SecureMcp JWT has been minted/confirmed for this session.
+     * Responsibilities:
+     * - React to issuance (e.g., persist session claims, notify listeners).
+     * Notes:
+     * - Fired once the session’s secureJwt is known; avoid logging secrets.
+     */
+    didIssueSecureJwt = "didIssueSecureJwt",
+    /** Encrypt and store provider tokens for this session.
+     * Responsibilities:
+     * - Write encrypted blobs to the session record (per provider).
+     * - Derive minimal metadata (scopes/expiry) for later claims-only exposure.
+     */
+    willStoreTokens = "willStoreTokens",
+    /** Authorize and prepare a session read.
+     * Responsibilities:
+     * - Validate access to the session; attach read-scoped providers if required.
+     * - Optionally shape a partial view before execute.
+     */
+    willGetSession = "willGetSession",
+    /** Post-process the session view.
+     * Responsibilities:
+     * - Redact/transform/derive fields for the final response.
+     * - Set `ctx.output` to a `SessionContextView`.
+     */
+    didGetSession = "didGetSession",
+    /** Announce shutdown and allow flush/cleanup.
+     * Responsibilities:
+     * - Close streams, unsubscribe listeners, schedule disposers.
+     */
+    willDisposeSession = "willDisposeSession",
+    /** Confirm teardown and emit metrics.
+     * Responsibilities:
+     * - Final confirmation of resource release; summarize outcome.
+     */
+    didDisposeSession = "didDisposeSession",
+    /** Optional “late finally” hook if you need a single place before audit/metrics.
+     * Responsibilities:
+     * - Last-chance cleanup across success/error paths (idempotent, non-throwing).
+     * Notes:
+     * - Include this stage in your plan’s `finalize` array to activate.
+     */
+    willFinalize = "willFinalize",
+    /** Centralized error handler.
+     * Responsibilities:
+     * - Redact sensitive data; map internal errors to public codes.
+     * - Optionally `ctx.respond({ error })` or `ctx.abort(...)`.
+     * Notes:
+     * - Should not throw; runs before audit/metrics finalize.
+     */
+    onError = "onError",
+    /** Pre-audit collection on both success and error paths.
+     * Responsibilities:
+     * - Build audit envelope (actor, sessionId, providers touched).
+     * - Normalize and strip secrets (no raw tokens).
+     */
+    willAudit = "willAudit",
+    /** Persist/emit the audit record.
+     * Responsibilities:
+     * - Write to audit sink(s) with outcome and timings.
+     * - Correlate via `ctx.requestId`/`ctx.sessionId`.
+     */
+    didAudit = "didAudit",
+    /** Telemetry/metrics emission for both success and errors.
+     * Responsibilities:
+     * - Counters & timings (create/get/dispose/auth/exchange/store).
+     * - Error code/tag cardinality kept small for SLOs/alerts.
+     * Constraints:
+     * - Non-throwing; must not alter control flow.
+     */
+    onMetrics = "onMetrics"
+}