@frontmcp/plugin-feature-flags 0.0.1

package/feature-flag.context-extension.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Context Extension Types for FeatureFlagPlugin
+ *
+ * Declares TypeScript types for `this.featureFlags` property
+ * on ExecutionContextBase (ToolContext, AgentContext, etc.).
+ *
+ * The SDK handles the runtime installation via `contextExtensions` in plugin metadata.
+ * This file only provides TypeScript type augmentation.
+ */
+import type { FeatureFlagAccessor } from './providers/feature-flag-accessor.provider';
+declare module '@frontmcp/sdk' {
+    interface ExecutionContextBase {
+        /**
+         * Access the feature flag accessor for evaluating flags.
+         * Only available when FeatureFlagPlugin is installed.
+         *
+         * @throws Error if FeatureFlagPlugin is not installed
+         */
+        readonly featureFlags: FeatureFlagAccessor;
+    }
+    interface PromptContext {
+        /**
+         * Access the feature flag accessor for evaluating flags.
+         * Only available when FeatureFlagPlugin is installed.
+         */
+        readonly featureFlags: FeatureFlagAccessor;
+    }
+}
+/**
+ * Get the FeatureFlagAccessor from an execution context.
+ * Alternative to `this.featureFlags` for explicit function-style access.
+ *
+ * @throws Error if FeatureFlagPlugin is not installed
+ */
+export declare function getFeatureFlags<T extends {
+    get: (token: unknown) => unknown;
+}>(ctx: T): FeatureFlagAccessor;
+/**
+ * Try to get the FeatureFlagAccessor, returning undefined if not available.
+ * Use this for graceful degradation when the plugin might not be installed.
+ */
+export declare function tryGetFeatureFlags<T extends {
+    tryGet?: (token: unknown) => unknown;
+}>(ctx: T): FeatureFlagAccessor | undefined;
+//# sourceMappingURL=feature-flag.context-extension.d.ts.map

package/feature-flag.context-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag.context-extension.d.ts","sourceRoot":"","sources":["../src/feature-flag.context-extension.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4CAA4C,CAAC;AAOtF,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,oBAAoB;QAC5B;;;;;WAKG;QACH,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;KAC5C;IAGD,UAAU,aAAa;QACrB;;;WAGG;QACH,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;KAC5C;CACF;AAMD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;CAAE,EAAE,GAAG,EAAE,CAAC,GAAG,mBAAmB,CAE3G;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;CAAE,EACnF,GAAG,EAAE,CAAC,GACL,mBAAmB,GAAG,SAAS,CAKjC"}

package/feature-flag.plugin.d.ts

@@ -0,0 +1,67 @@
+import { DynamicPlugin, FlowCtxOf, ProviderType } from '@frontmcp/sdk';
+import type { FeatureFlagPluginOptions, FeatureFlagPluginOptionsInput } from './feature-flag.types';
+/**
+ * FeatureFlagPlugin - Dynamic capability gating for FrontMCP.
+ *
+ * Filters tools, resources, prompts, and skills based on feature flag evaluation.
+ * Supports static flags, Split.io, LaunchDarkly, Unleash, and custom adapters.
+ *
+ * @example
+ * ```typescript
+ * @FrontMcp({
+ *   plugins: [
+ *     FeatureFlagPlugin.init({
+ *       adapter: 'static',
+ *       flags: { 'beta-tools': true, 'experimental-agent': false },
+ *     }),
+ *   ],
+ * })
+ * class MyServer {}
+ * ```
+ */
+export default class FeatureFlagPlugin extends DynamicPlugin<FeatureFlagPluginOptions, FeatureFlagPluginOptionsInput> {
+    options: FeatureFlagPluginOptions;
+    constructor(options: FeatureFlagPluginOptionsInput);
+    /**
+     * Dynamic providers based on plugin options.
+     */
+    static dynamicProviders: (options: FeatureFlagPluginOptionsInput) => ProviderType[];
+    /**
+     * Filter tools from list_tools based on feature flags.
+     * Runs after findTools but before resolveConflicts for fewer conflicts.
+     */
+    filterListTools(flowCtx: FlowCtxOf<'tools:list-tools'>): Promise<void>;
+    /**
+     * Filter resources from list_resources based on feature flags.
+     */
+    filterListResources(flowCtx: FlowCtxOf<'resources:list-resources'>): Promise<void>;
+    /**
+     * Filter prompts from list_prompts based on feature flags.
+     */
+    filterListPrompts(flowCtx: any): Promise<void>;
+    /**
+     * Filter skills from skills:search based on feature flags.
+     * Hooks after search stage, before finalize converts to output.
+     */
+    filterSearchSkills(flowCtx: any): Promise<void>;
+    /**
+     * Execution gate: block direct tool/call when the tool's feature flag is off.
+     * This prevents bypassing the list filter via direct tool invocation.
+     */
+    gateToolExecution(flowCtx: FlowCtxOf<'tools:call-tool'>): Promise<void>;
+    /**
+     * Collect unique flag keys from items that have a featureFlag metadata.
+     */
+    private collectFlagRefs;
+    /**
+     * Batch evaluate all collected flag refs via the adapter.
+     */
+    private batchEvaluateRefs;
+    /**
+     * Determine if a feature flag ref is enabled given adapter results.
+     * For object-style refs, `defaultValue` acts as a fallback when the adapter
+     * returns false (i.e., the flag is unknown to the adapter).
+     */
+    private isRefEnabled;
+}
+//# sourceMappingURL=feature-flag.plugin.d.ts.map

package/feature-flag.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag.plugin.d.ts","sourceRoot":"","sources":["../src/feature-flag.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,SAAS,EAOT,YAAY,EAEb,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,wBAAwB,EAAE,6BAA6B,EAAkB,MAAM,sBAAsB,CAAC;AAYpH;;;;;;;;;;;;;;;;;;GAkBG;AAaH,MAAM,CAAC,OAAO,OAAO,iBAAkB,SAAQ,aAAa,CAAC,wBAAwB,EAAE,6BAA6B,CAAC;IACnH,OAAO,EAAE,wBAAwB,CAAC;gBAEtB,OAAO,EAAE,6BAA6B;IAKlD;;OAEG;IACH,OAAgB,gBAAgB,GAAI,SAAS,6BAA6B,KAAG,YAAY,EAAE,CA0FzF;IAMF;;;OAGG;IAEG,eAAe,CAAC,OAAO,EAAE,SAAS,CAAC,kBAAkB,CAAC;IAmB5D;;OAEG;IAEG,mBAAmB,CAAC,OAAO,EAAE,SAAS,CAAC,0BAA0B,CAAC;IAmBxE;;OAEG;IAEG,iBAAiB,CAAC,OAAO,EAAE,GAAG;IAmBpC;;;OAGG;IAEG,kBAAkB,CAAC,OAAO,EAAE,GAAG;IAmBrC;;;OAGG;IAEG,iBAAiB,CAAC,OAAO,EAAE,SAAS,CAAC,iBAAiB,CAAC;IA2B7D;;OAEG;IACH,OAAO,CAAC,eAAe;IAcvB;;OAEG;YACW,iBAAiB;IAQ/B;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAOrB"}

package/feature-flag.symbols.d.ts

@@ -0,0 +1,17 @@
+import { Reference } from '@frontmcp/sdk';
+import type { FeatureFlagAdapter } from './adapters/feature-flag-adapter.interface';
+import type { FeatureFlagAccessor } from './providers/feature-flag-accessor.provider';
+import type { FeatureFlagPluginOptions } from './feature-flag.types';
+/**
+ * DI token for the feature flag adapter.
+ */
+export declare const FeatureFlagAdapterToken: Reference<FeatureFlagAdapter>;
+/**
+ * DI token for the plugin configuration.
+ */
+export declare const FeatureFlagConfigToken: Reference<FeatureFlagPluginOptions>;
+/**
+ * DI token for the context-scoped FeatureFlagAccessor.
+ */
+export declare const FeatureFlagAccessorToken: Reference<FeatureFlagAccessor>;
+//# sourceMappingURL=feature-flag.symbols.d.ts.map

package/feature-flag.symbols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag.symbols.d.ts","sourceRoot":"","sources":["../src/feature-flag.symbols.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4CAA4C,CAAC;AACtF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,CAAC,kBAAkB,CAEhC,CAAC;AAEnC;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,CAAC,wBAAwB,CAE/B,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,CAAC,mBAAmB,CAEjC,CAAC"}

package/feature-flag.types.d.ts

@@ -0,0 +1,88 @@
+import type { FrontMcpContext } from '@frontmcp/sdk';
+/** Context passed to feature flag adapters for per-user/session evaluation. */
+export interface FeatureFlagContext {
+    userId?: string;
+    sessionId?: string;
+    attributes?: Record<string, unknown>;
+}
+/** Variant result from multi-variate feature flags. */
+export interface FeatureFlagVariant {
+    name: string;
+    value: unknown;
+    enabled: boolean;
+}
+/**
+ * Metadata field type for annotating tools/resources/prompts/skills.
+ * Can be a simple flag key string or an object with default value.
+ */
+export type FeatureFlagRef = string | {
+    key: string;
+    defaultValue?: boolean;
+};
+/** Cache strategy for feature flag evaluations. */
+export type FeatureFlagCacheStrategy = 'session' | 'request' | 'none';
+/** Resolver function for extracting user ID from context. */
+export type UserIdResolver = (ctx: FrontMcpContext) => string | undefined;
+/** Resolver function for extracting attributes from context. */
+export type AttributesResolver = (ctx: FrontMcpContext) => Record<string, unknown>;
+/** Shared base options for all adapter configurations. */
+interface FeatureFlagBaseOptions {
+    defaultValue?: boolean;
+    cacheStrategy?: FeatureFlagCacheStrategy;
+    cacheTtlMs?: number;
+    userIdResolver?: UserIdResolver;
+    attributesResolver?: AttributesResolver;
+}
+/** Static/in-memory flags (no external dependency). */
+export interface StaticFeatureFlagPluginOptions extends FeatureFlagBaseOptions {
+    adapter: 'static';
+    flags: Record<string, boolean | FeatureFlagVariant>;
+}
+/** Split.io adapter options. */
+export interface SplitioFeatureFlagPluginOptions extends FeatureFlagBaseOptions {
+    adapter: 'splitio';
+    config: {
+        apiKey: string;
+    };
+}
+/** LaunchDarkly adapter options. */
+export interface LaunchDarklyFeatureFlagPluginOptions extends FeatureFlagBaseOptions {
+    adapter: 'launchdarkly';
+    config: {
+        sdkKey: string;
+    };
+}
+/** Unleash adapter options. */
+export interface UnleashFeatureFlagPluginOptions extends FeatureFlagBaseOptions {
+    adapter: 'unleash';
+    config: {
+        url: string;
+        appName: string;
+        apiKey?: string;
+    };
+}
+/** Custom adapter (user provides their own implementation). */
+export interface CustomFeatureFlagPluginOptions extends FeatureFlagBaseOptions {
+    adapter: 'custom';
+    adapterInstance: import('./adapters/feature-flag-adapter.interface').FeatureFlagAdapter;
+}
+/** Union of all plugin option types. */
+export type FeatureFlagPluginOptions = StaticFeatureFlagPluginOptions | SplitioFeatureFlagPluginOptions | LaunchDarklyFeatureFlagPluginOptions | UnleashFeatureFlagPluginOptions | CustomFeatureFlagPluginOptions;
+/** Input type (same as options for this plugin). */
+export type FeatureFlagPluginOptionsInput = FeatureFlagPluginOptions;
+declare global {
+    interface ExtendFrontMcpToolMetadata {
+        featureFlag?: FeatureFlagRef;
+    }
+    interface ExtendFrontMcpResourceMetadata {
+        featureFlag?: FeatureFlagRef;
+    }
+    interface ExtendFrontMcpPromptMetadata {
+        featureFlag?: FeatureFlagRef;
+    }
+    interface ExtendFrontMcpSkillMetadata {
+        featureFlag?: FeatureFlagRef;
+    }
+}
+export {};
+//# sourceMappingURL=feature-flag.types.d.ts.map

package/feature-flag.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag.types.d.ts","sourceRoot":"","sources":["../src/feature-flag.types.ts"],"names":[],"mappings":"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"}

package/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * FeatureFlagPlugin - Dynamic capability gating for FrontMCP
+ *
+ * Filters tools, resources, prompts, and skills based on feature flag evaluation.
+ * Supports static flags, Split.io, LaunchDarkly, Unleash, and custom adapters.
+ *
+ * @example
+ * ```typescript
+ * import { FeatureFlagPlugin } from '@frontmcp/plugin-feature-flags';
+ *
+ * @FrontMcp({
+ *   plugins: [
+ *     FeatureFlagPlugin.init({
+ *       adapter: 'static',
+ *       flags: { 'beta-tools': true, 'experimental-agent': false },
+ *     }),
+ *   ],
+ * })
+ * class MyServer {}
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { default, default as FeatureFlagPlugin } from './feature-flag.plugin';
+export { FeatureFlagAdapterToken, FeatureFlagConfigToken, FeatureFlagAccessorToken } from './feature-flag.symbols';
+export type { FeatureFlagContext, FeatureFlagVariant, FeatureFlagRef, FeatureFlagCacheStrategy, UserIdResolver, AttributesResolver, FeatureFlagPluginOptions, FeatureFlagPluginOptionsInput, StaticFeatureFlagPluginOptions, SplitioFeatureFlagPluginOptions, LaunchDarklyFeatureFlagPluginOptions, UnleashFeatureFlagPluginOptions, CustomFeatureFlagPluginOptions, } from './feature-flag.types';
+export type { FeatureFlagAdapter } from './adapters';
+export { StaticFeatureFlagAdapter } from './adapters/static.adapter';
+export { SplitioFeatureFlagAdapter } from './adapters/splitio.adapter';
+export { LaunchDarklyFeatureFlagAdapter } from './adapters/launchdarkly.adapter';
+export { UnleashFeatureFlagAdapter } from './adapters/unleash.adapter';
+export { FeatureFlagAccessor } from './providers/feature-flag-accessor.provider';
+export { getFeatureFlags, tryGetFeatureFlags } from './feature-flag.context-extension';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG9E,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAGnH,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,wBAAwB,EACxB,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,6BAA6B,EAC7B,8BAA8B,EAC9B,+BAA+B,EAC/B,oCAAoC,EACpC,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,8BAA8B,EAAE,MAAM,iCAAiC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAGvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4CAA4C,CAAC;AAKjF,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC"}