mcp.tools.ai_assistant
======================

.. py:module:: mcp.tools.ai_assistant

.. autoapi-nested-parse::

   AI-friendly MCP server selection and configuration assistant.

   This module provides tools specifically designed for AI agents to automatically
   select, configure, and use MCP servers based on task analysis and intelligent
   recommendations. It minimizes the need for manual configuration while maximizing
   the effectiveness of server selection.

   The assistant provides:
       - Automatic server selection based on task analysis
       - Smart configuration generation with minimal setup
       - Performance-aware server combinations
       - Fallback strategies for failed servers
       - Context-aware capability matching

   Classes:
       MCPAssistant: Main AI-friendly server selection assistant
       SmartConfig: Intelligent configuration generator
       TaskMatcher: Advanced task-to-server matching system

   .. rubric:: Example

   AI agent usage:

   .. code-block:: python

       from haive.mcp.tools import MCPAssistant

       # Create assistant
       assistant = MCPAssistant()

       # Automatically select servers for a task
       task = "I need to analyze Python code in a GitHub repo for security issues"
       config = await assistant.auto_configure_for_task(task)

       # Create agent with optimal configuration
       agent = MCPAgent(
           engine=engine,
           mcp_config=config,
           name="security_analysis_agent"
       )

       # Assistant provides reasoning
       reasoning = assistant.get_selection_reasoning()
       print(f"Selected servers because: {reasoning}")

   .. note::

      Designed to work seamlessly with AI agents that need to dynamically
      adapt their capabilities based on task requirements.



Attributes
----------

.. autoapisummary::

   mcp.tools.ai_assistant.logger


Classes
-------

.. autoapisummary::

   mcp.tools.ai_assistant.MCPAssistant
   mcp.tools.ai_assistant.ServerRecommendation
   mcp.tools.ai_assistant.SmartConfiguration
   mcp.tools.ai_assistant.TaskMatcher


Module Contents
---------------

.. py:class:: MCPAssistant(cache_enabled: bool = True)

   AI-friendly MCP server selection and configuration assistant.


   .. py:method:: auto_configure_for_task(task_description: str, prefer_simple_setup: bool = True, max_servers: int = 3, include_fallbacks: bool = True) -> SmartConfiguration
      :async:


      Automatically configure MCP servers for a task.

      :param task_description: Natural language description of the task
      :param prefer_simple_setup: Prefer servers with easier setup
      :param max_servers: Maximum number of servers to include
      :param include_fallbacks: Whether to include fallback servers

      :returns: SmartConfiguration with optimized setup



   .. py:method:: explain_recommendation(server_name: str) -> dict[str, Any]

      Get detailed explanation for a server recommendation.

      :param server_name: Name of the server to explain

      :returns: Dictionary with detailed explanation



   .. py:method:: get_selection_reasoning() -> str

      Get the reasoning for the last selection.



   .. py:method:: validate_configuration(config: haive.mcp.config.MCPConfig) -> dict[str, Any]
      :async:


      Validate a configuration and provide feedback.

      :param config: MCP configuration to validate

      :returns: Validation results with issues and suggestions



   .. py:attribute:: analyzer


   .. py:attribute:: cache_enabled
      :value: True



   .. py:attribute:: cached_configs


   .. py:attribute:: last_reasoning
      :value: ''



   .. py:attribute:: matcher


   .. py:attribute:: selector


.. py:class:: ServerRecommendation

   A server recommendation with detailed reasoning.


   .. py:attribute:: capabilities
      :type:  list[str]


   .. py:attribute:: confidence
      :type:  float


   .. py:attribute:: estimated_setup_time
      :type:  int


   .. py:attribute:: fallback_servers
      :type:  list[str]


   .. py:attribute:: reasoning
      :type:  str


   .. py:attribute:: required_env_vars
      :type:  list[str]


   .. py:attribute:: server_name
      :type:  str


.. py:class:: SmartConfiguration

   A complete MCP configuration with metadata.


   .. py:attribute:: config
      :type:  haive.mcp.config.MCPConfig


   .. py:attribute:: estimated_capabilities
      :type:  list[str]


   .. py:attribute:: fallback_servers
      :type:  list[str]


   .. py:attribute:: primary_servers
      :type:  list[str]


   .. py:attribute:: reasoning
      :type:  str


   .. py:attribute:: setup_complexity
      :type:  str


   .. py:attribute:: warnings
      :type:  list[str]


.. py:class:: TaskMatcher

   Advanced task-to-server matching with learning capabilities.


   .. py:method:: get_server_recommendation_score(server_name: str, task_pattern: str | None, task_description: str) -> float

      Calculate recommendation score for a server.

      :param server_name: Name of the server
      :param task_pattern: Matched task pattern
      :param task_description: Original task description

      :returns: Score from 0.0 to 1.0



   .. py:method:: match_task_to_pattern(task_description: str) -> str | None

      Match a task description to a known pattern.

      :param task_description: Natural language task description

      :returns: Pattern name if matched, None otherwise



   .. py:attribute:: server_profiles


   .. py:attribute:: success_history


   .. py:attribute:: task_patterns


.. py:data:: logger