@defai.digital/ax-cli 4.3.5 → 4.3.8

package/dist/tools/priority-registry.js

@@ -0,0 +1,401 @@
+/**
+ * Priority Registry - Tool Selection Engine
+ *
+ * Manages priority-based tool selection to ensure the right tool is used for each task.
+ * Prevents AutomatosX MCP from overshadowing native capabilities or provider-specific MCPs.
+ *
+ * Key behaviors:
+ * - Grok web search → Uses native API (not AutomatosX MCP)
+ * - GLM web search → Uses Z.AI MCP (not AutomatosX MCP)
+ * - Figma tasks → Uses Figma MCP regardless of provider
+ * - Memory/agent delegation → Uses AutomatosX MCP (its primary purpose)
+ */
+import { getActiveProvider } from '../provider/config.js';
+import { ToolPriority, SUPERSEDE_THRESHOLD, NATIVE_CAPABILITY_PREFIX, isVariantOf, hasNativeCapability, getServerCapabilityMapping, getServerPriority, providerMatches, } from './priority.js';
+/**
+ * Prefix for MCP tool names.
+ * e.g., 'mcp__automatosx__run_agent' starts with 'mcp__'
+ */
+const MCP_TOOL_PREFIX = 'mcp__';
+/**
+ * Separator used in MCP tool names between prefix, server name, and tool name.
+ */
+const MCP_NAME_SEPARATOR = '__';
+/**
+ * Well-known MCP server names used in capability guidance.
+ * These are referenced when providing context-aware tool recommendations.
+ */
+const KNOWN_SERVERS = {
+    ZAI_WEB_SEARCH: 'zai-web-search',
+    AUTOMATOSX: 'automatosx',
+    FIGMA: 'figma',
+    GITHUB: 'github',
+};
+/**
+ * Extract server name from MCP tool name
+ * e.g., 'mcp__automatosx__run_agent' → 'automatosx'
+ *
+ * ASSUMPTION: Server names do NOT contain "__" (double underscore).
+ * This is enforced by MCPServerIdSchema in @defai.digital/ax-schemas.
+ * If server names could contain "__", this parsing would fail.
+ *
+ * Returns undefined for:
+ * - Non-MCP tools (don't start with MCP_TOOL_PREFIX)
+ * - Malformed MCP tools with empty server name (e.g., 'mcp__' or 'mcp____tool')
+ */
+export function extractServerNameFromTool(toolName) {
+    if (!toolName.startsWith(MCP_TOOL_PREFIX)) {
+        return undefined;
+    }
+    // Format: mcp__serverName__toolName - server name is at index 1
+    // Note: This assumes server names don't contain "__" (enforced by MCPServerIdSchema)
+    const parts = toolName.split(MCP_NAME_SEPARATOR);
+    // BUG FIX: Validate that tool name has correct format (at least 3 parts: 'mcp', serverName, toolName)
+    // Malformed names like 'mcp__' or 'mcp____tool' would return empty/undefined server names
+    if (parts.length < 3 || !parts[1]) {
+        // Only log in debug mode to avoid console spam
+        if (process.env.DEBUG || process.env.AX_DEBUG) {
+            console.warn(`Malformed MCP tool name: "${toolName}". Expected format: mcp__serverName__toolName`);
+        }
+        return undefined;
+    }
+    return parts[1];
+}
+/**
+ * Helper to check if any phrase is found in text
+ */
+function containsAny(text, phrases) {
+    return phrases.some(phrase => text.includes(phrase));
+}
+/**
+ * Check if a server name matches a target (case-insensitive, supports variants)
+ */
+function serverNameMatches(serverName, target) {
+    const normalizedServer = serverName.toLowerCase();
+    const normalizedTarget = target.toLowerCase();
+    return normalizedServer === normalizedTarget || isVariantOf(normalizedServer, normalizedTarget);
+}
+/**
+ * Capability detection rules - defines how to detect each capability
+ */
+const CAPABILITY_RULES = [
+    // Web search - exclude file search tools
+    {
+        capability: 'web-search',
+        nameIncludes: ['websearch', 'web_search'],
+        descIncludes: ['search the web', 'on the web', 'web search', 'internet search'],
+        excludeNamePattern: /\bfile\b|_file\b|\bfile_|\bgrep\b|_grep\b|\bgrep_|\bglob\b|_glob\b|\bglob_/,
+        excludeDescIncludes: ['search files', 'file search'],
+    },
+    // Web fetch - exclude file readers
+    {
+        capability: 'web-fetch',
+        nameIncludes: ['webfetch', 'web_fetch', 'url_fetch', 'web-reader', 'web_reader'],
+        descIncludes: ['fetch url', 'fetch content from url', 'fetch web', 'http request'],
+        excludeNamePattern: /\bpdf\b|_pdf\b|\bpdf_|\bcsv\b|_csv\b|\bcsv_|\bfile\b|_file\b|\bfile_/,
+        excludeDescIncludes: ['read file', 'parse file'],
+    },
+    // Vision - exclude image manipulation tools
+    {
+        capability: 'vision',
+        namePatterns: /\bvision\b|\bcomputer vision\b|\bmachine vision\b/,
+        descPatterns: /\bvision\b|\bcomputer vision\b|\bmachine vision\b/,
+        descIncludes: ['image analysis', 'image understanding', 'analyze image', 'visual understanding'],
+        excludeNamePattern: /\bresize_image\b|\bget_image_dimensions\b|\bcompress_image\b|\bconvert_image_format\b|\bimage_resize\b|\bimage_compress\b|\bimage_convert\b/,
+        excludeDescIncludes: ['resize image', 'image dimensions', 'compress image', 'convert image format'],
+    },
+    // Memory - exclude system memory tools
+    {
+        capability: 'memory',
+        namePatterns: /\bmemory_add\b|\bmemory_search\b|\bmemory_list\b|\bmemory_delete\b|\bsave_memory\b|\bget_memory\b|\bcontext_store\b/,
+        descIncludes: ['context store', 'conversation memory', 'persist memory', 'retrieve memory', 'memory entries'],
+        excludeDescIncludes: ['memory usage', 'memory leak', 'low memory', 'memory limit', 'in-memory'],
+    },
+    // Agent delegation
+    {
+        capability: 'agent-delegation',
+        namePatterns: /\brun_agent\b|\bspawn_agent\b|\bcreate_agent\b|\bagent_task\b/,
+        descIncludes: ['delegate to agent', 'spawn agent', 'run agent', 'execute agent', 'multi-agent'],
+    },
+    // Git operations
+    {
+        capability: 'git-operations',
+        namePatterns: /\bgit\b|\bgit_|github|gitlab|gitea/,
+        descPatterns: /\bgit\b|\bgit_|github|gitlab|gitea/,
+        descIncludes: ['git repository', 'version control'],
+    },
+    // Database
+    {
+        capability: 'database',
+        namePatterns: /\bpostgres\b|\bpostgres_|\bsqlite\b|\bsqlite_|\bmysql\b|\bmysql_|\bmongodb\b|\bmongodb_|\bsupabase\b|\bsupabase_|\bfirebase\b|\bfirebase_|\bdynamodb\b|\bdynamodb_|\bredis\b|\bredis_|\bcassandra\b|\bcassandra_|\bsql_query\b|\bdb_query\b|\bexecute_sql\b|\brun_sql\b|\bdb_execute\b|\bdb_insert\b|\bdb_select\b|\bdb_update\b|\bdb_delete\b/,
+        descIncludes: ['execute sql', 'database query', 'run sql', 'database operations', 'sql statement'],
+    },
+    // Deployment
+    {
+        capability: 'deployment',
+        namePatterns: /\bvercel\b|\bvercel_|\bnetlify\b|\bnetlify_|\bheroku\b|\bheroku_|\baws_deploy\b|\bcloud_run\b|\bflyio\b|\brailway\b|\bdeploy_app\b|\bdeploy_site\b|\bdeploy_function\b|\bcreate_deployment\b|\btrigger_deploy\b/,
+        descIncludes: ['deploy to production', 'deploy application', 'deployment platform', 'deploy website'],
+    },
+    // File operations
+    {
+        capability: 'file-operations',
+        namePatterns: /\bfile\b|\bread_file\b|\bwrite_file\b|\bedit_file\b|\bview_file\b|\bcreate_file\b|\bdelete_file\b|\bstr_replace\b|\btext_editor\b/,
+        descIncludes: ['read file', 'write file', 'edit file', 'file system', 'file operations'],
+    },
+    // Testing
+    {
+        capability: 'testing',
+        namePatterns: /\btest\b|_test\b|\btest_|\btesting\b|puppeteer|playwright|cypress|selenium|\bjest\b|_jest_|_jest$|^jest_|vitest|mocha/,
+        descIncludes: ['run test', 'execute test', 'browser automation', 'e2e test', 'unit test', 'integration test'],
+    },
+    // Monitoring
+    {
+        capability: 'monitoring',
+        namePatterns: /sentry|datadog|newrelic|pagerduty|grafana|prometheus|error_track|log_event|alert_/,
+        descIncludes: ['error tracking', 'error monitoring', 'application monitoring', 'observability', 'apm', 'alert management'],
+    },
+];
+/**
+ * Check if a capability rule matches the tool name and description.
+ * Checks exclusions first, then inclusions with short-circuit evaluation.
+ */
+function matchesCapabilityRule(rule, toolName, toolDescription) {
+    // Check exclusions first (short-circuit on any match)
+    if (rule.excludeNamePattern?.test(toolName) ||
+        (rule.excludeDescIncludes && containsAny(toolDescription, rule.excludeDescIncludes))) {
+        return false;
+    }
+    // Check inclusions (short-circuit on first match)
+    return !!(rule.namePatterns?.test(toolName) ||
+        rule.descPatterns?.test(toolDescription) ||
+        (rule.nameIncludes && containsAny(toolName, rule.nameIncludes)) ||
+        (rule.descIncludes && containsAny(toolDescription, rule.descIncludes)));
+}
+/**
+ * Infer capability from tool name and description.
+ * Uses heuristics to determine what a tool does.
+ *
+ * @param tool - The LLM tool to analyze
+ * @returns Array of inferred capabilities
+ */
+export function inferToolCapability(tool) {
+    const toolName = tool.function.name.toLowerCase();
+    const toolDescription = (tool.function.description || '').toLowerCase();
+    const capabilities = [];
+    // Apply standard rules
+    for (const rule of CAPABILITY_RULES) {
+        if (matchesCapabilityRule(rule, toolName, toolDescription)) {
+            capabilities.push(rule.capability);
+        }
+    }
+    // Design detection: Figma-specific vs general design tools
+    const hasFigma = toolName.includes('figma') || toolDescription.includes('figma');
+    if (hasFigma) {
+        capabilities.push('design-figma');
+    }
+    else if (/\bdesign_system\b|\bdesign_token\b|\bui_design\b|\bget_design\b|\bcreate_design\b/.test(toolName) ||
+        containsAny(toolDescription, ['design system', 'design tokens'])) {
+        capabilities.push('design-general');
+    }
+    return capabilities;
+}
+/**
+ * Registry for managing tool priorities and selection
+ */
+export class PriorityRegistry {
+    provider;
+    toolMetadata = new Map();
+    constructor(provider) {
+        this.provider = provider || getActiveProvider();
+    }
+    /**
+     * Analyze a tool and determine its metadata
+     */
+    analyzeToolMetadata(tool) {
+        const toolName = tool.function.name;
+        // Check cache first (most common path)
+        const cached = this.toolMetadata.get(toolName);
+        if (cached) {
+            return cached;
+        }
+        const serverName = extractServerNameFromTool(toolName);
+        const mapping = serverName ? getServerCapabilityMapping(serverName) : undefined;
+        // Determine priority: known MCP > unknown MCP > built-in
+        const priority = mapping
+            ? getServerPriority(serverName, this.provider.name)
+            : toolName.startsWith(MCP_TOOL_PREFIX)
+                ? ToolPriority.COMMUNITY_MCP
+                : ToolPriority.BUILTIN_TOOL;
+        // Merge registered capabilities with inferred ones
+        const baseCapabilities = mapping?.capabilities ?? [];
+        const inferredCapabilities = inferToolCapability(tool);
+        const capabilities = baseCapabilities.length > 0
+            ? [...baseCapabilities, ...inferredCapabilities.filter(c => !baseCapabilities.includes(c))]
+            : inferredCapabilities;
+        const metadata = { name: toolName, capabilities, priority, serverName };
+        this.toolMetadata.set(toolName, metadata);
+        return metadata;
+    }
+    /**
+     * Check if a tool should be hidden based on capability conflicts
+     * Returns reason if hidden, undefined if should be shown
+     *
+     * IMPORTANT: A tool is only hidden if ALL of its capabilities are superseded
+     * by higher-priority alternatives. If a tool provides unique capabilities
+     * (e.g., AutomatosX's memory/agent-delegation), it should NOT be hidden
+     * even if some of its capabilities (e.g., web-search) are better served elsewhere.
+     */
+    shouldHideTool(tool, allTools) {
+        const metadata = this.analyzeToolMetadata(tool);
+        const { capabilities, name: toolName, priority: toolPriority } = metadata;
+        // If tool has no capabilities detected, don't hide it
+        if (capabilities.length === 0) {
+            return undefined;
+        }
+        // Track superseded capabilities - only collect details if all are superseded
+        const supersededCapabilities = [];
+        for (const capability of capabilities) {
+            // Find the highest priority tool for this capability
+            // This includes native API capabilities (priority 100) as virtual tools
+            const highestPriorityTool = this.findHighestPriorityTool(allTools, capability);
+            // Check if this capability is NOT superseded (early exit optimization)
+            const isSuperseded = highestPriorityTool &&
+                highestPriorityTool.name !== toolName &&
+                (highestPriorityTool.priority - toolPriority) >= SUPERSEDE_THRESHOLD;
+            if (!isSuperseded) {
+                // Found a unique capability - tool should not be hidden
+                return undefined;
+            }
+            supersededCapabilities.push(`${capability} (by ${highestPriorityTool.name})`);
+        }
+        // All capabilities are superseded - hide this tool
+        return `All capabilities superseded: ${supersededCapabilities.join(', ')}`;
+    }
+    /**
+     * Find the highest priority tool for a given capability
+     * Also considers native API capabilities which have priority NATIVE_API (100)
+     */
+    findHighestPriorityTool(tools, capability) {
+        // Native capabilities have highest priority (100) - early return optimization
+        if (hasNativeCapability(this.provider.name, capability)) {
+            return {
+                name: `${NATIVE_CAPABILITY_PREFIX}${capability}`,
+                capabilities: [capability],
+                priority: ToolPriority.NATIVE_API,
+            };
+        }
+        // Find highest priority tool for this capability
+        let highest;
+        for (const tool of tools) {
+            const metadata = this.analyzeToolMetadata(tool);
+            if (metadata.capabilities.includes(capability) && (!highest || metadata.priority > highest.priority)) {
+                highest = metadata;
+            }
+        }
+        return highest;
+    }
+    /**
+     * Filter tools based on priority, removing lower-priority duplicates
+     * Returns filtered tools and a list of hidden tools (for debugging)
+     */
+    filterTools(tools) {
+        const filtered = [];
+        const hidden = [];
+        // Single pass: analyze and filter in one loop
+        for (const tool of tools) {
+            // analyzeToolMetadata caches results, so shouldHideTool benefits from this
+            const hideReason = this.shouldHideTool(tool, tools);
+            if (hideReason) {
+                hidden.push({ tool, reason: hideReason });
+            }
+            else {
+                filtered.push(tool);
+            }
+        }
+        return { filtered, hidden };
+    }
+    /**
+     * Get capability-based guidance for the system prompt
+     * Helps the LLM understand which tools to prefer
+     * Uses flexible provider matching to handle variants like 'grok-beta', 'glm-4'
+     *
+     * @param connectedServers - Optional list of currently connected MCP server names.
+     *                           If provided, guidance is only given for connected servers.
+     */
+    getCapabilityGuidance(connectedServers) {
+        const guidance = [];
+        const providerName = this.provider.name;
+        // Check if a server is connected (or if we don't have connection info)
+        const isConnected = (target) => !connectedServers || connectedServers.some(s => serverNameMatches(s, target));
+        // Add provider-specific guidance
+        if (providerMatches(providerName, 'grok') || providerMatches(providerName, 'gemini')) {
+            guidance.push('For web searches, use NATIVE search capabilities (simply ask questions that require current information).', 'Do NOT use MCP web search tools when native search is available.');
+        }
+        else if (providerMatches(providerName, 'glm') && isConnected(KNOWN_SERVERS.ZAI_WEB_SEARCH)) {
+            guidance.push(`For web searches, use Z.AI MCP tools (${KNOWN_SERVERS.ZAI_WEB_SEARCH}) for best results.`, 'Z.AI tools are optimized for GLM integration.');
+        }
+        // Add MCP guidance only for servers that are actually connected
+        if (isConnected(KNOWN_SERVERS.AUTOMATOSX)) {
+            guidance.push('For memory and context management, use AutomatosX MCP tools.');
+        }
+        if (isConnected(KNOWN_SERVERS.FIGMA)) {
+            guidance.push('For design tasks involving Figma, use Figma MCP tools.');
+        }
+        if (isConnected(KNOWN_SERVERS.GITHUB)) {
+            guidance.push('For GitHub operations, use GitHub MCP tools.');
+        }
+        return guidance;
+    }
+    /**
+     * Get tools sorted by priority for a given capability
+     */
+    getToolsForCapability(tools, capability) {
+        // Collect matching tools with their priorities in single pass
+        const matching = [];
+        for (const tool of tools) {
+            const metadata = this.analyzeToolMetadata(tool);
+            if (metadata.capabilities.includes(capability)) {
+                matching.push({ tool, priority: metadata.priority });
+            }
+        }
+        // Sort and extract tools
+        return matching
+            .sort((a, b) => b.priority - a.priority)
+            .map(({ tool }) => tool);
+    }
+    /**
+     * Clear the metadata cache (useful for testing or provider changes)
+     */
+    clearCache() {
+        this.toolMetadata.clear();
+    }
+    /**
+     * Set provider (useful when provider changes mid-session)
+     */
+    setProvider(provider) {
+        this.provider = provider;
+        this.clearCache();
+    }
+}
+// Singleton instance
+let registryInstance = null;
+/**
+ * Get the priority registry singleton
+ */
+export function getPriorityRegistry() {
+    return registryInstance ??= new PriorityRegistry();
+}
+/**
+ * Reset the priority registry (for testing or provider changes)
+ */
+export function resetPriorityRegistry() {
+    registryInstance?.clearCache();
+    registryInstance = null;
+}
+/**
+ * Update the registry when provider changes
+ */
+export function updatePriorityRegistryProvider(provider) {
+    getPriorityRegistry().setProvider(provider);
+}
+//# sourceMappingURL=priority-registry.js.map

package/dist/tools/priority-registry.js.map

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

package/dist/tools/priority.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Tool Priority System
+ *
+ * Defines priority levels and capability types for intelligent tool selection.
+ * When multiple tools can handle the same task, the system prefers higher-priority tools.
+ *
+ * Priority Order:
+ * 1. Native API capabilities (e.g., Grok's built-in search)
+ * 2. Provider-specific MCP (e.g., Z.AI MCP for GLM)
+ * 3. Domain-specific MCP (e.g., Figma MCP for design)
+ * 4. Official MCP servers
+ * 5. Community MCP servers
+ * 6. General-purpose MCP (e.g., AutomatosX)
+ * 7. Built-in tools (fallback)
+ */
+/**
+ * Capability types that tools can provide
+ */
+export type ToolCapability = 'web-search' | 'web-fetch' | 'vision' | 'code-generation' | 'file-operations' | 'git-operations' | 'design-figma' | 'design-general' | 'database' | 'deployment' | 'memory' | 'agent-delegation' | 'testing' | 'monitoring';
+/**
+ * Priority levels for tool selection
+ * Higher values = higher priority = preferred tool
+ */
+export declare enum ToolPriority {
+    /** Built into provider API (highest priority) */
+    NATIVE_API = 100,
+    /** Provider-specific MCP (e.g., Z.AI for GLM) */
+    PROVIDER_MCP = 80,
+    /** Domain-specific MCP (e.g., Figma for design) */
+    DOMAIN_SPECIFIC = 60,
+    /** Official MCP servers (e.g., @modelcontextprotocol/*) */
+    OFFICIAL_MCP = 40,
+    /** Community MCP servers */
+    COMMUNITY_MCP = 20,
+    /** General-purpose MCP (e.g., AutomatosX) */
+    GENERAL_MCP = 10,
+    /** Built-in ax-cli tools (fallback) */
+    BUILTIN_TOOL = 5
+}
+/**
+ * Priority boost applied when a server has affinity for the current provider.
+ * This ensures provider-affinity servers beat same-level servers without affinity.
+ */
+export declare const PROVIDER_AFFINITY_BOOST = 10;
+/**
+ * Minimum priority difference required to consider a capability superseded.
+ * Prevents minor priority differences from hiding useful tools.
+ */
+export declare const SUPERSEDE_THRESHOLD = 15;
+/**
+ * Delimiters used to separate base names from variant suffixes.
+ * e.g., 'grok-beta' uses '-', 'automatosx_glm' uses '_'
+ */
+export declare const VARIANT_DELIMITERS: readonly ["-", "_"];
+/**
+ * Prefix used for virtual native capability tool names.
+ * e.g., 'native_web-search' represents Grok's native search capability
+ */
+export declare const NATIVE_CAPABILITY_PREFIX = "native_";
+/**
+ * Check if a name starts with a base name followed by a variant delimiter.
+ * Used to match variant names like 'grok-beta' to base name 'grok'.
+ *
+ * @param fullName - The full name to check (e.g., 'grok-beta')
+ * @param baseName - The base name to match against (e.g., 'grok')
+ * @returns True if fullName is a variant of baseName
+ */
+export declare function isVariantOf(fullName: string, baseName: string): boolean;
+/**
+ * Provider names for capability mapping
+ */
+export type ProviderName = 'grok' | 'glm' | 'claude' | 'openai' | 'gemini';
+/**
+ * Native capabilities built into provider APIs
+ * These don't require MCP - they're part of the API itself
+ */
+export declare const PROVIDER_NATIVE_CAPABILITIES: Record<ProviderName, ToolCapability[]>;
+/**
+ * MCP server capability mapping
+ * Defines which capabilities each MCP server provides and its priority
+ */
+export interface MCPCapabilityMapping {
+    /** MCP server name (e.g., 'figma', 'github', 'automatosx') */
+    serverName: string;
+    /** Capabilities this server provides */
+    capabilities: ToolCapability[];
+    /** Priority level for this server */
+    priority: ToolPriority;
+    /** Preferred providers for this server (if any) */
+    providerAffinity?: ProviderName[];
+    /** Whether this is an official MCP server */
+    isOfficial?: boolean;
+}
+/**
+ * Known MCP server capability registry
+ * Add new servers here as they become available
+ */
+export declare const MCP_CAPABILITY_REGISTRY: MCPCapabilityMapping[];
+/**
+ * Get capability mapping for a server by name.
+ * Supports exact matches and variant matches (e.g., 'automatosx-glm' matches 'automatosx').
+ * Case-insensitive matching for robustness.
+ *
+ * @param serverName - The server name to look up (may include variant suffix)
+ * @returns The capability mapping, or undefined if not found
+ */
+export declare function getServerCapabilityMapping(serverName: string): MCPCapabilityMapping | undefined;
+/**
+ * Check if a provider has native support for a capability.
+ * Supports provider variants (e.g., 'grok-beta' matches 'grok' native capabilities)
+ *
+ * @param providerName - The provider name (may include variant suffix)
+ * @param capability - The capability to check
+ * @returns True if the provider natively supports the capability
+ */
+export declare function hasNativeCapability(providerName: string, capability: ToolCapability): boolean;
+/**
+ * Check if a provider matches a base provider name.
+ * e.g., 'grok-beta' matches 'grok', 'glm-4' matches 'glm'
+ *
+ * @param providerName - The provider name to check (may include variant suffix)
+ * @param baseProvider - The base provider to match against
+ * @returns True if the provider matches the base provider
+ */
+export declare function providerMatches(providerName: string, baseProvider: ProviderName): boolean;
+/**
+ * Get the priority for a server, considering provider affinity.
+ *
+ * @param serverName - The MCP server name
+ * @param providerName - Optional provider name for affinity boosting
+ * @returns The priority value (higher = more preferred)
+ */
+export declare function getServerPriority(serverName: string, providerName?: string): number;
+/**
+ * Check if a server should be preferred for a given capability and provider.
+ *
+ * A server is preferred if:
+ * 1. The provider does NOT have native support for this capability, AND
+ * 2. Either:
+ *    a. It has provider affinity for the current provider, OR
+ *    b. It has the highest priority among all servers providing this capability
+ *
+ * Note: If the provider has native capability support, NO MCP server should be preferred.
+ *
+ * @param serverName - The MCP server name
+ * @param capability - The capability to check
+ * @param providerName - The current provider name
+ * @returns True if the server should be preferred for this capability
+ */
+export declare function shouldPreferServer(serverName: string, capability: ToolCapability, providerName: string): boolean;
+/**
+ * Get all servers that provide a given capability, sorted by priority.
+ *
+ * @param capability - The capability to search for
+ * @param providerName - Optional provider name for affinity-based priority boosting
+ * @returns Array of server mappings sorted by priority (highest first)
+ */
+export declare function getServersForCapability(capability: ToolCapability, providerName?: string): MCPCapabilityMapping[];