universal-mcp 0.1.23rc2__py3-none-any.whl → 0.1.24rc3__py3-none-any.whl

universal_mcp/config.py

@@ -7,63 +7,148 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
 class StoreConfig(BaseModel):
-    """Configuration for credential storage."""
+    """Specifies the configuration for a credential or token store.
 
-    name: str = Field(default="universal_mcp", description="Name of the store")
+    Defines where and how sensitive information like API keys or OAuth tokens
+    should be stored and retrieved.
+    """
+
+    name: str = Field(
+        default="universal_mcp",
+        description="Name of the store service or context (e.g., 'my_app_tokens', 'global_api_keys').",
+    )
     type: Literal["memory", "environment", "keyring", "agentr"] = Field(
-        default="memory", description="Type of credential storage to use"
+        default="memory",
+        description="The type of storage backend to use. 'memory' is transient, 'environment' uses environment variables, 'keyring' uses the system's secure credential manager, 'agentr' delegates to AgentR platform storage.",
+    )
+    path: Path | None = Field(
+        default=None,
+        description="Filesystem path for store types that require it (e.g., a future 'file' store type)",
     )
-    path: Path | None = Field(default=None, description="Path to store credentials (if applicable)")
 
 
 class IntegrationConfig(BaseModel):
-    """Configuration for API integrations."""
+    """Defines the authentication and credential management for an application.
 
-    name: str = Field(..., description="Name of the integration")
+    Specifies how a particular application (`AppConfig`) should authenticate
+    with its target service, including the authentication type (e.g., API key,
+    OAuth) and where to find the necessary credentials.
+    """
+
+    name: str = Field(
+        ..., description="A unique name for this integration instance (e.g., 'my_github_oauth', 'tavily_api_key')."
+    )
     type: Literal["api_key", "oauth", "agentr", "oauth2", "basic_auth"] = Field(
-        default="api_key", description="Type of authentication to use"
+        default="api_key",
+        description="The authentication mechanism to be used. 'oauth2' is often synonymous with 'oauth'. 'agentr' implies AgentR platform managed authentication.",
+    )
+    credentials: dict[str, Any] | None = Field(
+        default=None,
+        description="Directly provided credentials, if not using a store. Structure depends on the integration type (e.g., {'api_key': 'value'} or {'client_id': 'id', 'client_secret': 'secret'}). Use with caution for sensitive data; prefer using a 'store'.",
+    )
+    store: StoreConfig | None = Field(
+        default=None,
+        description="Configuration for the credential store to be used for this integration, overriding any default server-level store.",
     )
-    credentials: dict[str, Any] | None = Field(default=None, description="Integration-specific credentials")
-    store: StoreConfig | None = Field(default=None, description="Store configuration for credentials")
 
 
 class AppConfig(BaseModel):
-    """Configuration for individual applications."""
+    """Configuration for a single application to be loaded by the MCP server.
+
+    Defines an application's name (slug), its integration settings for
+    authentication, and optionally, a list of specific actions (tools)
+    it provides.
+    """
+
+    name: str = Field(
+        ...,
+        description="The unique name or slug of the application (e.g., 'github', 'google-calendar'). This is often used to dynamically load the application module.",
+    )
+    integration: IntegrationConfig | None = Field(
+        default=None,
+        description="Authentication and credential configuration for this application. If None, the application is assumed not to require authentication or uses a global/default mechanism.",
+    )
+    actions: list[str] | None = Field(
+        default=None,
+        description="A list of specific actions or tools provided by this application that should be exposed. If None or empty, all tools from the application might be exposed by default, depending on the application's implementation.",
+    )
 
-    name: str = Field(..., description="Name of the application")
-    integration: IntegrationConfig | None = Field(default=None, description="Integration configuration")
-    actions: list[str] | None = Field(default=None, description="List of available actions")
+    source_type: Literal["package", "local_folder", "remote_zip", "remote_file", "local_file"] = Field(
+        default="package",
+        description="The source of the application. 'package' (default) installs from a repository, 'local_folder' loads from a local path, 'remote_zip' downloads and extracts a project zip, 'remote_file' downloads a single Python file from a URL, 'local_file' loads a single Python file from the local filesystem.",
+    )
+    source_path: str | None = Field(
+        default=None,
+        description="The path or URL for 'local_folder', 'remote_zip', 'remote_file', or 'local_file' source types.",
+    )
+
+    @model_validator(mode="after")
+    def check_path_for_non_package_sources(self) -> Self:
+        if self.source_type in ["local_folder", "remote_zip", "remote_file", "local_file"] and not self.source_path:
+            raise ValueError(f"'source_path' is required for source_type '{self.source_type}'")
+        return self
 
 
 class ServerConfig(BaseSettings):
-    """Main server configuration."""
+    """Core configuration settings for the Universal MCP server.
+
+    Manages server behavior, including its name, description, connection
+    to AgentR (if applicable), transport protocol, network settings (port/host),
+    applications to load, default credential store, and logging verbosity.
+    Settings can be loaded from environment variables or a .env file.
+    """
 
-    model_config = SettingsConfigDict(
+    model_config: SettingsConfigDict = SettingsConfigDict(
         env_file=".env",
         env_file_encoding="utf-8",
         case_sensitive=True,
         extra="allow",
     )
-
     name: str = Field(default="Universal MCP", description="Name of the MCP server")
-    description: str = Field(default="Universal MCP", description="Description of the MCP server")
-    base_url: str = Field(
-        default="https://api.agentr.dev", description="Base URL for AgentR API", alias="AGENTR_BASE_URL"
+    description: str = Field(
+        default="Universal MCP", description="A brief description of this MCP server's purpose or deployment."
+    )
+    type: Literal["local", "agentr", "other"] = Field(
+        default="agentr",
+        description="Source of apps to load. Local apps are defined in 'apps' list; AgentR apps are dynamically loaded from the AgentR platform.",
     )
-    api_key: SecretStr | None = Field(default=None, description="API key for authentication", alias="AGENTR_API_KEY")
-    type: Literal["local", "agentr"] = Field(default="agentr", description="Type of server deployment")
     transport: Literal["stdio", "sse", "streamable-http"] = Field(
-        default="stdio", description="Transport protocol to use"
+        default="stdio",
+        description="The communication protocol the server will use to interact with clients (e.g., an AI agent).",
+    )
+    port: int = Field(
+        default=8005,
+        description="Network port for 'sse' or 'streamable-http' transports. Must be between 1 and 65535.",
+        ge=1,
+        le=65535,
+    )
+    log_level: str = Field(
+        default="INFO", description="Logging level for the server (e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL)."
+    )
+    # AgentR specific settings
+    base_url: str = Field(
+        default="https://api.agentr.dev",
+        description="The base URL for the AgentR API, used when type is 'agentr' or for AgentR-mediated integrations.",
+        alias="AGENTR_BASE_URL",
+    )
+    api_key: SecretStr | None = Field(
+        default=None,
+        description="The API key for authenticating with the AgentR platform. Stored as a SecretStr for security.",
+        alias="AGENTR_API_KEY",
+    )
+    # Local specific settings
+    apps: list[AppConfig] | None = Field(
+        default=None,
+        description="A list of application configurations to load when server 'type' is 'local'. Ignored if 'type' is 'agentr'.",
+    )
+    store: StoreConfig | None = Field(
+        default=None,
+        description="Default credential store configuration for applications that do not define their own specific store.",
     )
-    port: int = Field(default=8005, description="Port to run the server on (if applicable)", ge=1024, le=65535)
-    host: str = Field(default="localhost", description="Host to bind the server to (if applicable)")
-    apps: list[AppConfig] | None = Field(default=None, description="List of configured applications")
-    store: StoreConfig | None = Field(default=None, description="Default store configuration")
-    debug: bool = Field(default=False, description="Enable debug mode")
-    log_level: str = Field(default="INFO", description="Logging level")
 
     @field_validator("log_level", mode="before")
     def validate_log_level(cls, v: str) -> str:
+        """Validates and normalizes the log_level field."""
         valid_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
         if v.upper() not in valid_levels:
             raise ValueError(f"Invalid log level. Must be one of: {', '.join(valid_levels)}")
@@ -71,32 +156,59 @@ class ServerConfig(BaseSettings):
 
     @field_validator("port", mode="before")
     def validate_port(cls, v: int) -> int:
+        """Validates the port number is within the valid range."""
         if not 1 <= v <= 65535:
             raise ValueError("Port must be between 1 and 65535")
         return v
 
     @classmethod
-    def load_json_config(cls, path: str = "local_config.json") -> Self:
+    def load_json_config(cls, path: str = "server_config.json") -> Self:
+        """Loads server configuration from a JSON file.
+
+        Args:
+            path (str, optional): The path to the JSON configuration file.
+                Defaults to "local_config.json".
+
+        Returns:
+            ServerConfig: An instance of ServerConfig populated with data
+                          from the JSON file.
+        """
         with open(path) as f:
             data = json.load(f)
         return cls.model_validate(data)
 
 
 class ClientTransportConfig(BaseModel):
-    transport: str | None = None
-    command: str | None = None
-    args: list[str] = []
-    env: dict[str, str] = {}
-    url: str | None = None
-    headers: dict[str, str] = {}
+    """Configuration for how an MCP client connects to an MCP server.
+
+    Specifies the transport protocol and its associated parameters, such as
+    the command for stdio, URL for HTTP-based transports (SSE, streamable_http),
+    and any necessary headers or environment variables.
+    """
+
+    transport: str | None = Field(
+        default=None,
+        description="The transport protocol (e.g., 'stdio', 'sse', 'streamable_http'). Auto-detected in model_validate if not set.",
+    )
+    command: str | None = Field(
+        default=None, description="The command to execute for 'stdio' transport (e.g., 'python -m mcp_server.run')."
+    )
+    args: list[str] = Field(default=[], description="List of arguments for the 'stdio' command.")
+    env: dict[str, str] = Field(default={}, description="Environment variables to set for the 'stdio' command.")
+    url: str | None = Field(default=None, description="The URL for 'sse' or 'streamable_http' transport.")
+    headers: dict[str, str] = Field(
+        default={}, description="HTTP headers to include for 'sse' or 'streamable_http' transport."
+    )
 
     @model_validator(mode="after")
-    def model_validate(self) -> Self:
-        """
-        Set the transport type based on the presence of command or url.
-        - If command is present, transport is 'stdio'.
-        - Else if url ends with 'mcp', transport is 'streamable_http'.
-        - Else, transport is 'sse'.
+    def determine_transport_if_not_set(self) -> Self:
+        """Determines and sets the transport type if not explicitly provided.
+
+        - If `command` is present, transport is set to 'stdio'.
+        - If `url` is present, transport is 'streamable_http' if URL ends with '/mcp',
+          otherwise 'sse' if URL ends with '/sse'.
+        - Raises ValueError if transport cannot be determined or if neither
+          `command` nor `url` is provided.
         """
         if self.command:
             self.transport = "stdio"
@@ -114,18 +226,46 @@ class ClientTransportConfig(BaseModel):
         return self
 
 
-class LLMConfig(BaseModel):
-    api_key: str
-    base_url: str
-    model: str
+class ClientConfig(BaseSettings):
+    """Configuration for a client application that interacts with MCP servers and an LLM.
 
+    Defines connections to one or more MCP servers (via `mcpServers`) and
+    optionally, settings for an LLM to be used by the client (e.g., by an agent).
+    """
 
-class ClientConfig(BaseSettings):
-    mcpServers: dict[str, ClientTransportConfig]
-    llm: LLMConfig | None = None
+    mcpServers: dict[str, ClientTransportConfig] = Field(
+        ...,
+        description="Dictionary of MCP server connections. Keys are descriptive names for the server, values are `ClientTransportConfig` objects defining how to connect to each server.",
+    )
+    apps: list[AppConfig] = Field(
+        default=[],
+        description="List of application configurations to load",
+    )
+    store: StoreConfig | None = Field(
+        default=None,
+        description="Default credential store configuration for applications that do not define their own specific store.",
+    )
+    model: str = Field(
+        default="openrouter/auto",
+        description="The model to use for the LLM.",
+    )
 
     @classmethod
-    def load_json_config(cls, path: str = "servers.json") -> Self:
+    def load_json_config(cls, path: Path) -> Self:
+        """Loads client configuration from a JSON file.
+
+        Args:
+            path (str, optional): The path to the JSON configuration file.
+                Defaults to "client_config.json".
+
+        Returns:
+            ClientConfig: An instance of ClientConfig populated with data
+                          from the JSON file.
+        """
         with open(path) as f:
             data = json.load(f)
         return cls.model_validate(data)
+
+    def save_json_config(self, path: str) -> None:
+        with open(path, "w") as f:
+            json.dump(self.model_dump(), f, indent=4)

universal_mcp/exceptions.py

@@ -1,25 +1,73 @@
 class NotAuthorizedError(Exception):
-    """Raised when a user is not authorized to access a resource or perform an action."""
+    """Raised when an action is attempted without necessary permissions.
+
+    This typically occurs if a user or process tries to access a protected
+    resource or perform an operation for which they lack the required
+    authorization credentials or roles.
+    """
 
     def __init__(self, message: str):
+        """Initializes the NotAuthorizedError.
+
+        Args:
+            message (str): A descriptive message explaining the authorization failure.
+        """
         self.message = message
+        super().__init__(message)  # Ensure message is passed to base Exception
 
 
 class ToolError(Exception):
-    """Raised when a tool is not found or fails to execute."""
+    """Indicates an issue related to tool discovery, validation, or execution.
+
+    This could be due to a tool not being found, failing during its
+    operation, or having invalid configuration or arguments.
+    """
+
+    pass
+
+
+class ToolNotFoundError(Exception):
+    """Raised when a tool is not found"""
 
 
 class InvalidSignature(Exception):
-    """Raised when a signature is invalid."""
+    """Raised when a cryptographic signature verification fails.
+
+    This can occur during webhook validation or any other process that
+    relies on verifying the authenticity and integrity of a message
+    using a digital signature.
+    """
+
+    pass
 
 
 class StoreError(Exception):
-    """Base exception class for store-related errors."""
+    """Base exception for errors related to data or credential stores.
+
+    This serves as a generic error for issues arising from operations
+    on any storage backend (e.g., KeyringStore, EnvironmentStore).
+    Specific store errors should ideally subclass this.
+    """
+
+    pass
 
 
 class KeyNotFoundError(StoreError):
-    """Exception raised when a key is not found in the store."""
+    """Raised when a specified key cannot be found in a data or credential store.
+
+    This is a common error when attempting to retrieve a piece of data
+    (e.g., an API key, token, or client information) that does not exist
+    under the given identifier.
+    """
+
+    pass
 
 
 class ConfigurationError(Exception):
-    """Exception raised when a configuration error occurs."""
+    """Indicates an error was detected in application or server configuration.
+
+    This can be due to missing required settings, invalid values for
+    configuration parameters, or inconsistencies in the provided setup.
+    """
+
+    pass

universal_mcp/integrations/__init__.py

@@ -1,29 +1,11 @@
-from universal_mcp.config import IntegrationConfig
 from universal_mcp.integrations.integration import (
-    AgentRIntegration,
     ApiKeyIntegration,
     Integration,
     OAuthIntegration,
 )
-from universal_mcp.stores.store import BaseStore
-
-
-def integration_from_config(config: IntegrationConfig, store: BaseStore | None = None, **kwargs) -> Integration:
-    if config.type == "api_key":
-        return ApiKeyIntegration(config.name, store=store, **kwargs)
-    elif config.type == "agentr":
-        api_key = kwargs.get("api_key")
-        if not api_key:
-            raise ValueError("api_key is required for AgentR integration")
-        return AgentRIntegration(config.name, api_key=api_key)
-    else:
-        raise ValueError(f"Unsupported integration type: {config.type}")
-
 
 __all__ = [
-    "AgentRIntegration",
     "ApiKeyIntegration",
     "Integration",
     "OAuthIntegration",
-    "integration_from_config",
 ]