haive.mcp.downloader.core¶

Core MCP Downloader implementation.

This module provides the main GeneralMCPDownloader class that orchestrates the downloading, installation, and configuration of MCP servers from various sources.

Example

Basic usage:

downloader = GeneralMCPDownloader() result = await downloader.download_servers([“filesystem”, “github”])

Auto-discovery:

result = await downloader.auto_discover_and_download(limit=10)

Custom configuration:

downloader = GeneralMCPDownloader(
config_file="my_config.yaml",
install_dir="/custom/path"

)

Classes:: GeneralMCPDownloader: Main downloader orchestrator DownloadResult: Result of download operations ServerStatus: Status tracking for servers

Version: 1.0.0 Author: Haive MCP Team

Classes¶

`DownloadResult`	Result of a download operation.
`GeneralMCPDownloader`	General MCP Server Downloader with configurable patterns and installers.
`ServerStatus`	Status information for an MCP server.

Module Contents¶

class haive.mcp.downloader.core.DownloadResult(/, **data)[source]¶

Bases: pydantic.BaseModel

Result of a download operation.

Parameters:: data (Any)

total¶: Total servers attempted

successful¶: Number of successful installations

failed¶: Number of failed installations

success_rate¶: Percentage success rate

successful_servers¶: List of successful server details

failed_servers¶: List of failed server details

config_file¶: Path to generated configuration

duration¶: Operation duration in seconds

Example

Checking results:

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class haive.mcp.downloader.core.GeneralMCPDownloader(config_file=None, install_dir=None)[source]¶

General MCP Server Downloader with configurable patterns and installers.

This is the main orchestrator class that manages the downloading, installation, and configuration of MCP servers from various sources using a plugin-based architecture.

config¶: Downloader configuration

installers¶: List of available installers

discovery¶: Server discovery instance

status_tracker¶: Server status tracking

Example

Creating and using downloader:

Note

The downloader automatically creates necessary directories and default configuration if not provided.

Initialize the General MCP Downloader.

Parameters:

config_file (str | None) – Path to YAML configuration file. If not provided, creates a default configuration.
install_dir (str | None) – Directory for server installations. Defaults to ~/.mcp/servers if not specified.

Example

Initialization:

add_custom_server(server)[source]¶

Add a custom server configuration.

Parameters:: server (haive.mcp.downloader.config.ServerConfig) – ServerConfig to add
Return type:: None

Example

Adding custom server:

add_custom_template(template)[source]¶

Add a custom template.

Parameters:: template (haive.mcp.downloader.config.ServerTemplate) – ServerTemplate to add
Return type:: None

Example

Adding custom template:

async auto_discover_and_download(limit=None, auto_install=True)[source]¶

Auto-discover servers from registries and optionally download them.

This method discovers MCP servers from configured sources and can automatically install them.

Parameters:

limit (int | None) – Maximum number of servers to discover per source
auto_install (bool) – Whether to automatically install discovered servers

Returns:

DownloadResult with discovery and installation details

Return type:

DownloadResult

Example

Auto-discover and install:

async check_server_health(server_names=None)[source]¶

Check health status of installed servers.

Parameters:: server_names (list[str] | None) – Specific servers to check. If None, checks all installed.
Returns:: Dict with health check results
Return type:: dict[str, Any]

Example

Checking health:

async download_servers(server_names=None, categories=None, tags=None, max_concurrent=None)[source]¶

Download and install MCP servers.

This is the main method for downloading servers. It supports filtering by name, category, or tags, and handles concurrent downloads with retry logic.

Parameters:

server_names (list[str] | None) – Specific server names to download. If None, downloads all enabled servers.
categories (list[str] | None) – Filter servers by category (e.g., “official”, “community”)
tags (set[str] | None) – Filter servers by tags (e.g., {“database”, “file-operations”})
max_concurrent (int | None) – Maximum concurrent downloads. Uses config default if None.

Returns:

DownloadResult with details of the operation

Return type:

DownloadResult

Example

Download specific servers:

Raises:

ValueError – If no servers match the criteria

Parameters:

server_names (list[str] | None)
categories (list[str] | None)
tags (set[str] | None)
max_concurrent (int | None)

Return type:

DownloadResult

get_all_status()[source]¶

Get status for all servers.

Returns:: Dict mapping server names to ServerStatus objects
Return type:: dict[str, ServerStatus]

get_server_status(server_name)[source]¶

Get status for a specific server.

Parameters:: server_name (str) – Name of the server
Returns:: ServerStatus if found, None otherwise
Return type:: ServerStatus | None

Example

Checking status:

save_configuration(config_file)[source]¶

Save current configuration to file.

Parameters:: config_file (pathlib.Path) – Path to save configuration
Return type:: None

Example

Saving config:

property servers: list[haive.mcp.downloader.config.ServerConfig]¶

Get list of server configurations.

Returns:: List of ServerConfig objects
Return type:: list[haive.mcp.downloader.config.ServerConfig]

Example

Listing servers:

property templates: dict[str, haive.mcp.downloader.config.ServerTemplate]¶

Get templates as a dictionary.

Returns:: Dict mapping template names to ServerTemplate objects
Return type:: dict[str, haive.mcp.downloader.config.ServerTemplate]

Example

Accessing templates:

class haive.mcp.downloader.core.ServerStatus(/, **data)[source]¶

Bases: pydantic.BaseModel

Status information for an MCP server.

Parameters:: data (Any)

name¶: Server name

status¶: Current status (installed, failed, pending)

last_check¶: Timestamp of last status check

last_success¶: Timestamp of last successful operation

install_result¶: Result of installation attempt

health_status¶: Health check status

error¶: Error message if failed

Example

Creating status:

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.