@dollhousemcp/mcp-server/dist/utils/FieldFilter.d.ts

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

/**
 * FieldFilter - GraphQL-style field selection for MCP-AQL responses
 *
 * Provides field filtering and name transformation for element responses:
 * - Filters object fields based on a fields array
 * - Transforms field names for LLM consistency (name → element_name)
 * - Supports nested paths (e.g., metadata.author, metadata.tags)
 * - Handles arrays of objects (filter each item)
 * - Provides preset field sets (minimal, standard, full)
 * - Applies Unicode normalization to field names for security (DMCP-SEC-004)
 *
 * PERFORMANCE NOTE:
 * Field selection is applied AFTER handlers return complete data.
 * This design choice:
 * - Keeps handlers simple (no field-awareness needed)
 * - Ensures consistent handler behavior regardless of field selection
 * - Makes preset changes easy without modifying handlers
 * - Has minimal overhead (~0.5ms per 100 elements)
 *
 * Token savings benefit the LLM context window, not internal processing.
 * Empirical measurements show 80-90% token reduction with minimal preset.
 *
 * @see Issue #202 - Implement GraphQL field selection for response token optimization
 * @see tests/unit/utils/FieldFilter.tokenSavings.test.ts - Empirical token savings
 */
export interface FieldFilterOptions {
    /** Specific fields to include in response */
    fields?: string[];
    /** Preset field sets: 'minimal', 'standard', 'full' */
    preset?: 'minimal' | 'standard' | 'full';
    /** Transform field names for consistency (default: true) */
    transformNames?: boolean;
}
export interface FieldFilterResult {
    /** The filtered and transformed data */
    data: unknown;
    /** Fields that were requested but not found in data */
    missingFields?: string[];
    /** Whether name transformation was applied */
    transformed: boolean;
}
/**
 * Field name transformations for LLM consistency.
 * These ensure response field names match input parameter names.
 *
 * Key = internal field name, Value = external field name
 */
export declare const FIELD_TRANSFORMS: Record<string, string>;
/**
 * Reverse mapping for field selection.
 * Allows LLM to request either 'name' or 'element_name'.
 *
 * Key = external field name, Value = array of candidate internal paths (tried in order)
 * First match wins — supports both flat objects (name) and IElement objects (metadata.name).
 */
export declare const FIELD_ALIASES: Record<string, string[]>;
/**
 * Preset field sets for common use cases.
 * null = return all fields (default behavior)
 */
export declare const FIELD_PRESETS: Record<string, string[] | null>;
/**
 * Normalize an array of field names.
 * Returns both normalized fields and any invalid field warnings.
 *
 * @param fields - Array of field names to normalize
 * @returns Object with normalized fields and optional warnings
 */
export declare function normalizeFieldNames(fields: string[]): {
    normalized: string[];
    warnings?: string[];
};
/**
 * Filter and transform response data based on field selection.
 *
 * @param data - The data to filter (object or array of objects)
 * @param options - Filtering options
 * @returns Filtered and transformed data with metadata
 *
 * @example
 * // With specific fields
 * filterFields({ name: 'test', description: 'desc', content: '...' }, {
 *   fields: ['element_name', 'description']
 * });
 * // Returns: { data: { element_name: 'test', description: 'desc' }, transformed: true }
 *
 * @example
 * // With preset
 * filterFields(data, { preset: 'minimal' });
 * // Returns: { data: { element_name, description }, transformed: true }
 *
 * @example
 * // No fields = transform only
 * filterFields({ name: 'test' }, {});
 * // Returns: { data: { element_name: 'test' }, transformed: true }
 */
export declare function filterFields(data: unknown, options?: FieldFilterOptions): FieldFilterResult;
/**
 * Check if a preset name is valid.
 * Applies Unicode normalization for security (DMCP-SEC-004).
 */
export declare function isValidPreset(preset: string): preset is 'minimal' | 'standard' | 'full';
/**
 * Get fields for a preset name.
 * Applies Unicode normalization for security (DMCP-SEC-004).
 */
export declare function getPresetFields(preset: 'minimal' | 'standard' | 'full'): string[] | null;
//# sourceMappingURL=FieldFilter.d.ts.map