@1mcp/agent 0.22.3 → 0.23.0

package/build/core/filtering/filteringService.js

@@ -0,0 +1,253 @@
+import { ClientStatus } from '../types/client.js';
+import { TagQueryParser } from '../../utils/tagQueryParser.js';
+import { TagQueryEvaluator } from '../../utils/tagQueryEvaluator.js';
+import { normalizeTag } from '../../utils/sanitization.js';
+import logger from '../../logger/logger.js';
+/**
+ * Unified filtering service that consolidates all filtering logic across the application.
+ * This service provides a single source of truth for filtering MCP server connections
+ * based on various criteria including tags, capabilities, and advanced expressions.
+ */
+export class FilteringService {
+    /**
+     * Get filtered connections based on inbound connection configuration
+     * This is the main entry point for filtering and should be used by most components
+     *
+     * @param connections Map of outbound connections to filter
+     * @param config Inbound connection configuration containing filter criteria
+     * @returns Filtered map of connections
+     */
+    static getFilteredConnections(connections, config) {
+        logger.debug('FilteringService: Filtering connections', {
+            totalConnections: connections.size,
+            filterMode: config.tagFilterMode,
+            tags: config.tags,
+            hasTagExpression: !!config.tagExpression,
+            hasTagQuery: !!config.tagQuery,
+        });
+        // Only include connected clients in filtering
+        const connectedClients = new Map();
+        for (const [name, connection] of connections) {
+            if (connection.status === ClientStatus.Connected) {
+                connectedClients.set(name, connection);
+            }
+        }
+        logger.debug('FilteringService: Connected clients', {
+            connectedCount: connectedClients.size,
+            connectedNames: Array.from(connectedClients.keys()),
+        });
+        if (!config.tagFilterMode || config.tagFilterMode === 'none') {
+            logger.debug('FilteringService: No filtering specified, returning all connected clients');
+            return connectedClients;
+        }
+        const filter = this.createFilter(config);
+        const filteredConnections = filter(connectedClients);
+        logger.debug('FilteringService: Filtering completed', {
+            filteredCount: filteredConnections.size,
+            filteredNames: Array.from(filteredConnections.keys()),
+        });
+        return filteredConnections;
+    }
+    /**
+     * Create a filter function based on inbound connection configuration
+     *
+     * @param config Inbound connection configuration
+     * @returns Filter function that can be applied to connections
+     */
+    static createFilter(config) {
+        if (config.tagFilterMode === 'preset' && config.tagQuery) {
+            return this.byTagQuery(config.tagQuery);
+        }
+        else if (config.tagFilterMode === 'advanced' && config.tagExpression) {
+            return this.byTagExpression(config.tagExpression);
+        }
+        else if (config.tagFilterMode === 'simple-or' || config.tags) {
+            return this.byTags(config.tags);
+        }
+        else {
+            // No filtering - return function that passes all clients through
+            return this.byTags(undefined);
+        }
+    }
+    /**
+     * Filter connections by tags using OR logic
+     * If no tags are provided, all connections are returned
+     *
+     * @param tags Array of tags to filter by
+     * @returns Filter function
+     */
+    static byTags(tags) {
+        return (connections) => {
+            logger.debug(`FilteringService.byTags: Filtering for tags: ${tags ? tags.join(', ') : 'none'}`);
+            if (!tags || tags.length === 0) {
+                logger.debug('FilteringService.byTags: No tags specified, returning all connections');
+                return connections;
+            }
+            // Normalize the filter tags for consistent comparison
+            const normalizedFilterTags = tags.map((tag) => normalizeTag(tag));
+            return Array.from(connections.entries()).reduce((filtered, [name, connection]) => {
+                const clientTags = connection.transport.tags || [];
+                // Normalize client tags for comparison
+                const normalizedClientTags = clientTags.map((tag) => normalizeTag(tag));
+                const hasMatchingTags = normalizedClientTags.some((clientTag) => normalizedFilterTags.includes(clientTag));
+                logger.debug(`FilteringService.byTags: Connection ${name}`, {
+                    clientTags,
+                    normalizedClientTags,
+                    requiredTags: tags,
+                    normalizedRequiredTags: normalizedFilterTags,
+                    hasMatchingTags,
+                });
+                if (hasMatchingTags) {
+                    filtered.set(name, connection);
+                }
+                return filtered;
+            }, new Map());
+        };
+    }
+    /**
+     * Filter connections by advanced tag expression
+     *
+     * @param expression Parsed tag expression to evaluate
+     * @returns Filter function
+     */
+    static byTagExpression(expression) {
+        return (connections) => {
+            logger.debug(`FilteringService.byTagExpression: Filtering with expression: ${TagQueryParser.expressionToString(expression)}`);
+            return Array.from(connections.entries()).reduce((filtered, [name, connection]) => {
+                const clientTags = connection.transport.tags || [];
+                const matches = TagQueryParser.evaluate(expression, clientTags);
+                logger.debug(`FilteringService.byTagExpression: Connection ${name}`, {
+                    clientTags,
+                    expression: TagQueryParser.expressionToString(expression),
+                    matches,
+                });
+                if (matches) {
+                    filtered.set(name, connection);
+                }
+                return filtered;
+            }, new Map());
+        };
+    }
+    /**
+     * Filter connections by MongoDB-style tag query
+     *
+     * @param query Tag query to evaluate
+     * @returns Filter function
+     */
+    static byTagQuery(query) {
+        return (connections) => {
+            logger.debug('FilteringService.byTagQuery: Filtering with tag query', { query });
+            const filtered = new Map();
+            for (const [name, connection] of connections.entries()) {
+                if (connection.status !== ClientStatus.Connected) {
+                    continue;
+                }
+                const clientTags = connection.transport.tags || [];
+                try {
+                    if (TagQueryEvaluator.evaluate(query, clientTags)) {
+                        filtered.set(name, connection);
+                        logger.debug(`FilteringService.byTagQuery: Connection ${name} matches query`, {
+                            clientTags,
+                            query,
+                        });
+                    }
+                }
+                catch (error) {
+                    logger.warn(`FilteringService.byTagQuery: Failed to evaluate query for connection ${name}`, {
+                        error: error instanceof Error ? error.message : 'Unknown error',
+                        clientTags,
+                        query,
+                    });
+                }
+            }
+            return filtered;
+        };
+    }
+    /**
+     * Filter connections by server capabilities
+     *
+     * @param requiredCapabilities Capabilities that must be present
+     * @returns Filter function
+     */
+    static byCapabilities(requiredCapabilities) {
+        return (connections) => {
+            const requiredCaps = Object.keys(requiredCapabilities);
+            logger.debug(`FilteringService.byCapabilities: Filtering for capabilities: ${requiredCaps.join(', ')}`);
+            return Array.from(connections.entries()).reduce((filtered, [name, connection]) => {
+                const clientCaps = connection.capabilities ? Object.keys(connection.capabilities) : [];
+                const hasCapabilities = requiredCaps.every((cap) => connection.capabilities && cap in connection.capabilities);
+                logger.debug(`FilteringService.byCapabilities: Connection ${name}`, {
+                    clientCapabilities: clientCaps,
+                    requiredCapabilities: requiredCaps,
+                    hasCapabilities,
+                    clientCapabilitiesObject: connection.capabilities,
+                });
+                if (hasCapabilities) {
+                    filtered.set(name, connection);
+                }
+                return filtered;
+            }, new Map());
+        };
+    }
+    /**
+     * Combine multiple filters using AND logic
+     * All filters must pass for a connection to be included
+     *
+     * @param filters Array of filter functions to combine
+     * @returns Combined filter function
+     */
+    static combineFilters(...filters) {
+        return (connections) => {
+            logger.debug(`FilteringService.combineFilters: Starting with ${connections.size} connections`, {
+                connectionNames: Array.from(connections.keys()),
+                filterCount: filters.length,
+            });
+            const result = filters.reduce((filteredConnections, filter, index) => {
+                const beforeCount = filteredConnections.size;
+                const afterFiltering = filter(filteredConnections);
+                const afterCount = afterFiltering.size;
+                logger.debug(`FilteringService.combineFilters: Filter ${index} reduced connections from ${beforeCount} to ${afterCount}`, {
+                    beforeNames: Array.from(filteredConnections.keys()),
+                    afterNames: Array.from(afterFiltering.keys()),
+                });
+                return afterFiltering;
+            }, connections);
+            logger.debug(`FilteringService.combineFilters: Final result has ${result.size} connections`, {
+                finalNames: Array.from(result.keys()),
+            });
+            return result;
+        };
+    }
+    /**
+     * Get a summary of filtering results for logging and debugging
+     *
+     * @param originalConnections Original connection map before filtering
+     * @param filteredConnections Filtered connection map after filtering
+     * @param config Filter configuration used
+     * @returns Summary object with filtering statistics
+     */
+    static getFilteringSummary(originalConnections, filteredConnections, config) {
+        const originalNames = Array.from(originalConnections.keys());
+        const filteredNames = Array.from(filteredConnections.keys());
+        const removedNames = originalNames.filter((name) => !filteredNames.includes(name));
+        let filterType = 'none';
+        if (config.tagFilterMode === 'preset') {
+            filterType = 'preset';
+        }
+        else if (config.tagFilterMode === 'advanced') {
+            filterType = 'advanced';
+        }
+        else if (config.tagFilterMode === 'simple-or' || config.tags) {
+            filterType = 'simple-or';
+        }
+        return {
+            original: originalConnections.size,
+            filtered: filteredConnections.size,
+            removed: removedNames.length,
+            filterType,
+            filteredNames: filteredNames.sort(),
+            removedNames: removedNames.sort(),
+        };
+    }
+}
+//# sourceMappingURL=filteringService.js.map

package/build/core/filtering/filteringService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filteringService.js","sourceRoot":"","sources":["../../../src/core/filtering/filteringService.ts"],"names":[],"mappings":"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"}

package/build/core/instructions/instructionAggregator.d.ts

@@ -0,0 +1,141 @@
+import { EventEmitter } from 'events';
+import { OutboundConnections, InboundConnectionConfig } from '../types/index.js';
+/**
+ * Events emitted by InstructionAggregator
+ */
+export interface InstructionAggregatorEvents {
+    'instructions-changed': () => void;
+}
+/**
+ * Aggregates instructions from multiple MCP servers into a single instruction string.
+ * Provides both simple concatenation and filtered instructions with educational templates.
+ * The aggregator acts as an educational prompt to help LLMs understand 1MCP better.
+ *
+ * @example
+ * ```typescript
+ * const aggregator = new InstructionAggregator();
+ * aggregator.on('instructions-changed', () => {
+ *   // Server instructions have changed
+ * });
+ *
+ * // When server comes online
+ * aggregator.setInstructions('server1', 'Server 1 instructions');
+ *
+ * // Get filtered instructions for a client
+ * const filtered = aggregator.getFilteredInstructions(config, connections);
+ * ```
+ */
+export declare class InstructionAggregator extends EventEmitter {
+    private serverInstructions;
+    private isInitialized;
+    private templateCache;
+    constructor();
+    /**
+     * Set or update instructions for a specific server
+     * @param serverName The name of the server
+     * @param instructions The instruction string from the server, or undefined to remove
+     */
+    setInstructions(serverName: string, instructions: string | undefined): void;
+    /**
+     * Remove instructions for a specific server
+     * @param serverName The name of the server to remove
+     */
+    removeServer(serverName: string): void;
+    /**
+     * Get filtered instructions for a specific client based on their configuration
+     * This is the main method that should be used by server connections
+     *
+     * @param config Client's inbound connection configuration
+     * @param connections All available outbound connections
+     * @returns Formatted instruction string with educational template or custom template
+     */
+    getFilteredInstructions(config: InboundConnectionConfig, connections: OutboundConnections): string;
+    /**
+     * Get the number of servers that have provided instructions
+     * @returns The count of servers with instructions
+     */
+    getServerCount(): number;
+    /**
+     * Get a list of server names that have provided instructions
+     * @returns Array of server names
+     */
+    getServerNames(): string[];
+    /**
+     * Check if a specific server has instructions
+     * @param serverName The server name to check
+     * @returns True if the server has instructions
+     */
+    hasInstructions(serverName: string): boolean;
+    /**
+     * Get instructions for a specific server
+     * @param serverName The server name
+     * @returns The instructions for the server, or undefined if not found
+     */
+    getServerInstructions(serverName: string): string | undefined;
+    /**
+     * Clear all instructions (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Get filter context description for the template
+     */
+    private getFilterContext;
+    /**
+     * Get a summary of current instruction state for logging
+     */
+    getSummary(): string;
+    /**
+     * Render a custom Handlebars template with template variables
+     * @param template Custom template string
+     * @param filteredConnections Filtered server connections
+     * @param config Client configuration
+     * @returns Rendered template string
+     */
+    private renderCustomTemplate;
+    /**
+     * Get or compile a Handlebars template with caching
+     * @param template Template string
+     * @returns Compiled template function
+     */
+    private getCompiledTemplate;
+    /**
+     * Generate template variables for rendering
+     * @param filteredConnections Filtered server connections
+     * @param config Client configuration
+     * @returns Template variables object
+     */
+    private generateTemplateVariables;
+    /**
+     * Clear template cache (useful for testing)
+     */
+    clearTemplateCache(): void;
+    /**
+     * Get template cache statistics for monitoring
+     */
+    getTemplateCacheStats(): {
+        size: number;
+        maxSize: number;
+        calculatedSize: number;
+    };
+    /**
+     * Invalidate template cache with reason logging
+     * @param reason Reason for cache invalidation
+     */
+    private invalidateTemplateCache;
+    /**
+     * Force template cache invalidation (for external triggers)
+     * @param reason Reason for forced invalidation
+     */
+    forceTemplateCacheInvalidation(reason?: string): void;
+    /**
+     * Cryptographically secure hash function for template cache keys
+     * Uses SHA-256 to prevent collision attacks
+     */
+    private hashString;
+    /**
+     * Cleanup method to remove all event listeners and clear caches
+     * Should be called when the aggregator is no longer needed
+     */
+    cleanup(): void;
+}
+//# sourceMappingURL=instructionAggregator.d.ts.map

package/build/core/instructions/instructionAggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructionAggregator.d.ts","sourceRoot":"","sources":["../../../src/core/instructions/instructionAggregator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAKtC,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAQjF;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,sBAAsB,EAAE,MAAM,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,aAAa,CAAgD;;IAuBrE;;;;OAIG;IACI,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAuBlF;;;OAGG;IACI,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAU7C;;;;;;;OAOG;IACI,uBAAuB,CAAC,MAAM,EAAE,uBAAuB,EAAE,WAAW,EAAE,mBAAmB,GAAG,MAAM;IAoBzG;;;OAGG;IACI,cAAc,IAAI,MAAM;IAI/B;;;OAGG;IACI,cAAc,IAAI,MAAM,EAAE;IAIjC;;;;OAIG;IACI,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAInD;;;;OAIG;IACI,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIpE;;OAEG;IACI,KAAK,IAAI,IAAI;IAUpB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;OAEG;IACI,UAAU,IAAI,MAAM;IAM3B;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAsE5B;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAoC3B;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;IA2DjC;;OAEG;IACI,kBAAkB,IAAI,IAAI;IAKjC;;OAEG;IACI,qBAAqB,IAAI;QAC9B,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,MAAM,CAAC;KACxB;IAQD;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAQ/B;;;OAGG;IACI,8BAA8B,CAAC,MAAM,GAAE,MAA2B,GAAG,IAAI;IAIhF;;;OAGG;IACH,OAAO,CAAC,UAAU;IAKlB;;;OAGG;IACI,OAAO,IAAI,IAAI;CAiBvB"}