mcp.downloader.integration
==========================

.. py:module:: mcp.downloader.integration

.. autoapi-nested-parse::

   Agent integration for MCP Downloader.

   This module provides integration between the MCP downloader system and Haive agents,
   enabling automatic tool, resource, and prompt discovery from downloaded MCP servers.

   .. rubric:: Examples

   Basic integration:

       .. code-block:: python
       from haive.mcp.downloader import MCPAgentIntegration

   from haive import core


           integration = MCPAgentIntegration()
           agent = await integration.create_agent_with_mcp_servers(
               engine=engine,
               server_names=["filesystem", "github"]
           )

       Auto-discovery integration:



           .. code-block:: python



               agent = await integration.create_agent_with_auto_discovery(
               engine=engine,
               limit=10,
               categories=["official", "core"]
           )

   Classes:
       MCPAgentIntegration: Main integration class
       MCPServerConnection: Connection management for MCP servers
       MCPCapabilityExtractor: Extract tools, resources, and prompts



Attributes
----------

.. autoapisummary::

   mcp.downloader.integration.MCP_ADAPTERS_AVAILABLE
   mcp.downloader.integration.logger


Classes
-------

.. autoapisummary::

   mcp.downloader.integration.MCPAgentIntegration
   mcp.downloader.integration.MCPCapabilityExtractor
   mcp.downloader.integration.MCPServerConnection


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

.. py:class:: MCPAgentIntegration(config_file: str | None = None, install_dir: str | None = None)

   Integration between MCP downloader and Haive agents.

   This class provides high-level methods to create agents with
   MCP servers automatically configured and connected.

   .. attribute:: downloader

      General MCP downloader instance

   .. attribute:: extractor

      Capability extractor

   .. attribute:: manager

      MCP manager for agent integration

   .. rubric:: Examples

   Creating integrated agent:

   .. code-block:: python
       integration = MCPAgentIntegration()
       agent = await integration.create_agent_with_mcp_servers(
           engine=engine,
           server_names=["filesystem", "github"]
       )


   .. py:method:: create_agent_with_auto_discovery(engine: haive.core.engine.aug_llm.AugLLMConfig, limit: int | None = None, categories: list[str] | None = None, tags: set[str] | None = None, agent_class: type = MCPAgent, **agent_kwargs) -> haive.mcp.agents.MCPAgent
      :async:


      Create an agent with auto-discovered MCP servers.

      :param engine: Haive engine configuration
      :param limit: Maximum servers to discover
      :param categories: Server categories to include
      :param tags: Server tags to filter by
      :param agent_class: Agent class to instantiate
      :param \*\*agent_kwargs: Additional agent arguments

      :returns: Configured agent with discovered servers

      .. rubric:: Examples

      Auto-discovery agent:

      .. code-block:: python
              agent = await integration.create_agent_with_auto_discovery(
                  engine=engine,
                  limit=10,
                  categories=["official", "core"],
                  tags={"file-operations", "database"}
              )



   .. py:method:: create_agent_with_mcp_servers(engine: haive.core.engine.aug_llm.AugLLMConfig, server_names: list[str], agent_class: type = MCPAgent, install_if_missing: bool = True, **agent_kwargs) -> haive.mcp.agents.MCPAgent
      :async:


      Create an agent with specific MCP servers.

      :param engine: Haive engine configuration
      :param server_names: List of server names to use
      :param agent_class: Agent class to instantiate
      :param install_if_missing: Install missing servers
      :param \*\*agent_kwargs: Additional agent arguments

      :returns: Configured agent with MCP servers

      .. rubric:: Examples

      Creating agent with servers:

      .. code-block:: python
              agent = await integration.create_agent_with_mcp_servers(
                  engine=engine,
                  server_names=["filesystem", "github", "postgres"],
                  name="my_mcp_agent"
              )



   .. py:method:: create_transferable_agent_team(engine: haive.core.engine.aug_llm.AugLLMConfig, num_agents: int, server_distribution: str = 'shared', **agent_kwargs) -> list[haive.mcp.agents.TransferableMCPAgent]
      :async:


      Create a team of transferable MCP agents.

      :param engine: Haive engine configuration
      :param num_agents: Number of agents to create
      :param server_distribution: How to distribute servers
                                  - "shared": All agents share all servers
                                  - "split": Divide servers among agents
                                  - "specialized": Each agent gets specific categories
      :param \*\*agent_kwargs: Additional agent arguments

      :returns: List of configured transferable agents

      .. rubric:: Examples

      Creating agent team:

      .. code-block:: python
              agents = await integration.create_transferable_agent_team(
                  engine=engine,
                  num_agents=3,
                  server_distribution="specialized"
              )



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

      Get a summary of all discovered capabilities.

      :returns: Dict with capability statistics

      .. rubric:: Examples

      Getting summary:

      .. code-block:: python
              summary = integration.get_capability_summary()
              print(f"Total tools: {summary['total_tools']}")



   .. py:attribute:: downloader


   .. py:attribute:: extractor


   .. py:attribute:: manager


.. py:class:: MCPCapabilityExtractor

   Extracts tools, resources, and prompts from MCP servers.

   This class provides methods to extract and organize capabilities
   from multiple MCP servers for use with agents.

   .. attribute:: connections

      Active server connections

   .. attribute:: all_tools

      Aggregated tools from all servers

   .. attribute:: all_resources

      Aggregated resources

   .. attribute:: all_prompts

      Aggregated prompts

   .. rubric:: Examples

   Extracting capabilities:

   .. code-block:: python
       extractor = MCPCapabilityExtractor()
       await extractor.add_server("filesystem", config)
       tools = extractor.get_all_tools()


   .. py:method:: add_server(name: str, config: dict[str, Any], transport: str = 'stdio') -> bool
      :async:


      Add and connect to an MCP server.

      :param name: Server name
      :param config: Server configuration
      :param transport: Transport type

      :returns: True if server added successfully
      :rtype: bool

      .. rubric:: Examples

      Adding a server:

      .. code-block:: python
              success = await extractor.add_server(
                  "filesystem",
                  {"command": "npx", "args": ["@modelcontextprotocol/server-filesystem"]}
              )



   .. py:method:: add_servers_from_config(servers: list[haive.mcp.downloader.config.ServerConfig], config_dir: pathlib.Path) -> dict[str, bool]
      :async:


      Add multiple servers from configuration.

      :param servers: List of server configurations
      :param config_dir: Directory containing server configs

      :returns: Dict mapping server names to success status

      .. rubric:: Examples

      Adding from config:

      .. code-block:: python
              results = await extractor.add_servers_from_config(
                  downloader.servers,
                  downloader.install_dir
              )



   .. py:method:: get_all_prompts() -> dict[str, list[dict]]

      Get all discovered prompts.

      :returns: Dict of server name to prompt list



   .. py:method:: get_all_resources() -> dict[str, list[dict]]

      Get all discovered resources.

      :returns: Dict of server name to resource list



   .. py:method:: get_all_tools() -> dict[str, langchain_core.tools.BaseTool]

      Get all discovered tools.

      :returns: Dict of tool name to tool object

      .. rubric:: Examples

      Getting tools:

      .. code-block:: python
              tools = extractor.get_all_tools()
              for name, tool in tools.items():
                  print(f"Tool: {name}")



   .. py:method:: get_tools_by_capability(capability: str) -> dict[str, langchain_core.tools.BaseTool]

      Get tools that have a specific capability.

      :param capability: Capability to filter by

      :returns: Dict of tools with that capability



   .. py:method:: get_tools_by_server(server_name: str) -> dict[str, langchain_core.tools.BaseTool]

      Get tools from a specific server.

      :param server_name: Name of the server

      :returns: Dict of tools from that server



   .. py:attribute:: all_prompts
      :type:  dict[str, list[dict]]


   .. py:attribute:: all_resources
      :type:  dict[str, list[dict]]


   .. py:attribute:: all_tools
      :type:  dict[str, langchain_core.tools.BaseTool]


   .. py:attribute:: connections
      :type:  dict[str, MCPServerConnection]


.. py:class:: MCPServerConnection(/, **data: Any)

   Bases: :py:obj:`pydantic.BaseModel`


   Manages connection to an MCP server.

   .. attribute:: name

      Server name identifier

   .. attribute:: config

      Server configuration

   .. attribute:: transport

      Transport type (stdio, sse, etc.)

   .. attribute:: connection

      Active connection object

   .. attribute:: tools

      Discovered tools from the server

   .. attribute:: resources

      Available resources

   .. attribute:: prompts

      Available prompts

   .. attribute:: connected

      Connection status

   .. rubric:: Examples

   Creating a connection:

   .. code-block:: python
       connection = MCPServerConnection(
           name="filesystem",
           config=server_config,
           transport="stdio"
       )
       await connection.connect()


   .. py:method:: connect() -> bool
      :async:


      Establish connection to the MCP server.

      :returns: True if connection successful
      :rtype: bool

      .. rubric:: Examples

      Connecting to server:

      .. code-block:: python
              if await connection.connect():
                  print(f"Connected to {connection.name}")



   .. py:method:: discover_capabilities() -> dict[str, Any]
      :async:


      Discover tools, resources, and prompts from the server.

      :returns: Dict containing discovered capabilities

      .. rubric:: Examples

      Discovering capabilities:

      .. code-block:: python
              caps = await connection.discover_capabilities()
              print(f"Found {len(caps['tools'])} tools")



   .. py:attribute:: config
      :type:  dict[str, Any]
      :value: None



   .. py:attribute:: connected
      :type:  bool
      :value: None



   .. py:attribute:: connection
      :type:  Any | None
      :value: None



   .. py:attribute:: model_config

      Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].


   .. py:attribute:: name
      :type:  str
      :value: None



   .. py:attribute:: prompts
      :type:  list[dict[str, Any]]
      :value: None



   .. py:attribute:: resources
      :type:  list[dict[str, Any]]
      :value: None



   .. py:attribute:: tools
      :type:  dict[str, langchain_core.tools.BaseTool]
      :value: None



   .. py:attribute:: transport
      :type:  str
      :value: None



.. py:data:: MCP_ADAPTERS_AVAILABLE
   :value: True


.. py:data:: logger