ProviderRegistry

Overview

scope.providers is typed ProviderRegistryInterface, which declares get(), getScope(), getProviders(), getRegistries() and buildViews(). The other methods on this page belong to the exported ProviderRegistry class, which the scope’s registry is at runtime: narrow with instanceof ProviderRegistry to call them.

import { ProviderRegistry } from '@frontmcp/sdk';

// Access via scope
const providers = scope.providers;

// Get a singleton provider
const logger = providers.get(LoggerToken);

// Get a CONTEXT-scoped provider from the views built for a session
if (providers instanceof ProviderRegistry) {
  const views = await providers.buildViews('session-123');
  const service = providers.getScoped(ServiceToken, views);
}

Methods

get()

Get a GLOBAL-scoped (singleton) provider.

get<T>(token: Token<T>): T

Example:

const logger = registry.get(LoggerToken);
const config = registry.get(ConfigToken);

getScoped()

Get a provider from given views (for session/request scoped providers).

getScoped<T>(token: Token<T>, views: ProviderViews): T

Example:

const views = await registry.buildViews(sessionKey, contextProviders);
const session = registry.getScoped(SessionToken, views);

resolve()

Lightweight synchronous resolver for app-scoped DI. A registered token must be a GLOBAL provider that is already instantiated; a class that is not registered is constructed, and its synchronous init() called.

resolve<T>(cls: any): T

Example:

const service = registry.resolve(MyService);

resolveBootstrapDep()

Resolve a GLOBAL-scoped provider during the bootstrap phase, from this registry or a parent registry. It returns an instance that already exists and never instantiates one: it throws PluginDependencyError when the provider is not GLOBAL-scoped, is not instantiated yet, or is not found, so instantiate the provider before a bootstrap caller resolves it.

resolveBootstrapDep(t: Token): Promise<any>

getProviders()

Get all provider entries.

getProviders(): ProviderEntry[]

buildViews()

Build provider views for different scopes. Async — instantiates context-scoped providers per request.

buildViews(
  sessionKey: string,
  contextProviders?: Map<Token, unknown>,
  contextSource?: ProviderRegistryInterface
): Promise<ProviderViews>

Parameter	Description
`sessionKey`	Context/session identifier used to cache CONTEXT-scoped instances.
`contextProviders`	Instances already built for this request (for example the scope’s views and `FRONTMCP_CONTEXT`). They are reused instead of being built again.
`contextSource`	The ancestor registry that built `contextProviders`. When given, every token this registry’s hierarchy defines below that ancestor is resolved from its own nearest definition, and the pre-built instance is ignored.

The tools:call-tool, resources:read-resource and prompts:get-prompt flows build an entry’s views with the scope’s views as contextProviders and the scope registry as contextSource. As a result, a tool resolves the providers of the plugins its own app installed, even when another app on the same server installs the same plugin with different options. Example:

const views = await registry.buildViews('session-123', new Map([
  [RequestToken, currentRequest],
]));

// Entry views on top of the scope's views: the app's own definitions win.
// scopeProviders is the scope's ProviderRegistry, appProviders an app's.
const scopeViews = await scopeProviders.buildViews(sessionKey, requestProviders);
const appViews = await appProviders.buildViews(sessionKey, scopeViews.context, scopeProviders);

addRegistry()

Add a registry by type.

addRegistry<T extends RegistryKind>(type: T, value: RegistryType[T]): void

getRegistries()

Get registries by type.

getRegistries<T extends RegistryKind>(type: T): RegistryType[T][]

getHooksRegistry()

Get the hooks registry.

getHooksRegistry(): HookRegistry

getScopeRegistry()

Get the scope registry.

getScopeRegistry(): ScopeRegistryInterface

mergeFromRegistry()

Merge providers from another registry. With visibleBelow, the merged providers resolve for this registry’s own lookups and for visibleBelow’s subtree; other registries below this one resolve them as if they were not merged.

mergeFromRegistry(
  providedBy: ProviderRegistry,
  exported: { token: Token; def: ProviderRecord; instance: ProviderEntry | undefined }[],
  visibleBelow?: ProviderRegistry
): void

getProviderInfo()

Get a provider’s definition and its instance (undefined for a CONTEXT-scoped provider, built per request), in the shape mergeFromRegistry() takes. Throws ProviderNotRegisteredError when this registry does not define the token.

getProviderInfo(token: Token): { token: Token; def: ProviderRecord; instance: ProviderEntry | undefined }

injectProvider()

Inject a provider value directly.

injectProvider(injected: Omit<ProviderInjectedRecord, 'kind'>): void

Example:

registry.injectProvider({
  provide: ConfigToken,
  value: { debug: true },
  metadata: { name: 'config' },
});

addDynamicProviders()

Add providers dynamically at runtime. Async — instantiates global-scoped providers immediately.

addDynamicProviders(dynamicProviders: ProviderType[]): Promise<unknown[]>

Session Management

cleanupSession()

Clean up a specific session’s provider cache.

cleanupSession(sessionKey: string): void

cleanupExpiredSessions()

Clean up expired sessions from cache. Returns the number of sessions removed.

cleanupExpiredSessions(): number

startSessionCleanup()

Start background session cleanup timer.

startSessionCleanup(): void

stopSessionCleanup()

Stop background session cleanup timer.

stopSessionCleanup(): void

getSessionCacheStats()

Get session cache statistics.

getSessionCacheStats(): { enabled: boolean; size: number; maxSize: number; ttlMs: number }

isSessionCacheEnabled()

Check if session caching is enabled.

isSessionCacheEnabled(): boolean

dispose()

Dispose registry and clean up all resources.

dispose(): void

Server/Scope Access

getActiveScope()

Get the active scope.

getActiveScope(): ScopeEntry

getActiveServer()

Get the active server.

getActiveServer(): FrontMcpServer

Provider Scopes

A provider uses one of two ProviderScope values:

Scope	Description	Lifecycle
`GLOBAL`	Shared across all requests (default)	Server lifetime
`CONTEXT`	Per-execution context	Context lifetime

ProviderScope.SESSION and ProviderScope.REQUEST are deprecated: the registry treats both as CONTEXT.

Provider Views

Provider views represent the hierarchy of available providers:

interface ProviderViews {
  global: ReadonlyMap<Token, unknown>;  // Server-wide singletons, created at boot
  context: Map<Token, unknown>;         // CONTEXT-scoped instances: rebuilt per request, or reused across a verified session's requests while the session cache is on
}

Indexes

Index	Key	Description
`providedBy`	`Token`	Which registry provided each token
`order`	`number`	Topological order for instantiation
`registries`	`RegistryType`	Map of registries by kind

Session Caching

The registry implements LRU eviction and TTL-based session caching:

// Session cache stats
const stats = registry.getSessionCacheStats();
console.log(`Caching enabled: ${stats.enabled}`);
console.log(`Cached sessions: ${stats.size} of ${stats.maxSize}`);
console.log(`Session TTL: ${stats.ttlMs} ms`);

Provider Definition

A provider is a ProviderType: a class decorated with @Provider, or an object with a provide token, a name and one of useClass, useValue or useFactory. A factory provider adds inject, a function returning the tokens of its dependencies, when it has any. Every form takes an optional scope (ProviderScope.GLOBAL by default), description and id. The providers of @FrontMcp, @App, @Plugin and @Agent accept a @Provider class, a useValue holding an instance of one, or a factory provider with a name, and refuse the other forms. A plugin’s dynamicProviders() can return any of them. Example:

import { Provider, ProviderScope } from '@frontmcp/sdk';

@Provider({ name: 'cache', scope: ProviderScope.GLOBAL })
class CacheProvider { }

const redisCacheProvider = {
  name: 'redis-cache',
  provide: CacheToken,
  inject: () => [CacheSettings] as const,
  useFactory: (settings: CacheSettings) => new RedisCache(settings),
  scope: ProviderScope.GLOBAL,
};

Decorators

API

Errors

Overview

Methods

get()

getScoped()

resolve()

resolveBootstrapDep()

getProviders()

buildViews()

addRegistry()

getRegistries()

getHooksRegistry()

getScopeRegistry()

mergeFromRegistry()

getProviderInfo()

injectProvider()

addDynamicProviders()

Session Management

cleanupSession()

cleanupExpiredSessions()

startSessionCleanup()

stopSessionCleanup()

getSessionCacheStats()

isSessionCacheEnabled()

dispose()

Server/Scope Access

getActiveScope()

getActiveServer()

Provider Scopes

Provider Views

Indexes

Session Caching

Provider Definition

​Overview

​Methods

​get()

​getScoped()

​resolve()

​resolveBootstrapDep()

​getProviders()

​buildViews()

​addRegistry()

​getRegistries()

​getHooksRegistry()

​getScopeRegistry()

​mergeFromRegistry()

​getProviderInfo()

​injectProvider()

​addDynamicProviders()

​Session Management

​cleanupSession()

​cleanupExpiredSessions()

​startSessionCleanup()

​stopSessionCleanup()

​getSessionCacheStats()

​isSessionCacheEnabled()

​dispose()

​Server/Scope Access

​getActiveScope()

​getActiveServer()

​Provider Scopes

​Provider Views

​Indexes

​Session Caching

​Provider Definition

​Related

Overview

Methods

get()

getScoped()

resolve()

resolveBootstrapDep()

getProviders()

buildViews()

addRegistry()

getRegistries()

getHooksRegistry()

getScopeRegistry()

mergeFromRegistry()

getProviderInfo()

injectProvider()

addDynamicProviders()

Session Management

cleanupSession()

cleanupExpiredSessions()

startSessionCleanup()

stopSessionCleanup()

getSessionCacheStats()

isSessionCacheEnabled()

dispose()

Server/Scope Access

getActiveScope()

getActiveServer()

Provider Scopes

Provider Views

Indexes

Session Caching

Provider Definition

Related