iflow-mcp_modelcontextinterface-mcix 1.1.1.dev0__py3-none-any.whl

mci/mci.py

@@ -0,0 +1,39 @@
+"""
+mci.py - Main entry point for the MCI CLI Tool
+
+This module provides the main CLI interface for managing MCI (Model Context Interface)
+schemas and dynamically running MCP servers using defined MCI toolsets.
+"""
+
+import click
+
+from mci.cli.add import add
+from mci.cli.envs import envs_command
+from mci.cli.install import install
+from mci.cli.list import list_command
+from mci.cli.run import run
+from mci.cli.validate import validate
+
+
+@click.group()
+@click.version_option()
+def main():
+    """
+    MCI CLI - Manage Model Context Interface schemas and run MCP servers.
+
+    Use 'mci COMMAND --help' for more information on a specific command.
+    """
+    pass
+
+
+# Register commands
+main.add_command(add)
+main.add_command(envs_command, name="envs")
+main.add_command(install)
+main.add_command(list_command, name="list")
+main.add_command(run)
+main.add_command(validate)
+
+
+if __name__ == "__main__":
+    main()

mci/utils/__init__.py

@@ -0,0 +1,8 @@
+"""
+Utility functions for the MCI CLI Tool.
+
+This package contains utility functions for error handling, validation,
+formatting, and other helper functionality.
+"""
+
+__all__ = ()

mci/utils/dotenv.py

@@ -0,0 +1,170 @@
+"""
+dotenv.py - Environment variable file parsing utilities
+
+This module provides functionality to parse .env files using the python-dotenv library
+and merge environment variables from multiple sources. It supports:
+- Standard .env format via python-dotenv
+- Comments starting with #
+- Blank lines
+- Export keyword (which is ignored)
+- Quoted values
+
+The module is used to automatically load .env files from the project root
+and ./mci directory when initializing MCI configurations. It supports both
+.env and .env.mci files, with .env.mci taking precedence for MCI-specific
+configuration.
+"""
+
+import os
+from pathlib import Path
+
+from dotenv import dotenv_values
+
+
+def parse_dotenv_file(file_path: str | Path) -> dict[str, str]:
+    """
+    Parse a .env file and return a dictionary of environment variables.
+
+    This function uses python-dotenv to parse .env files, which supports:
+    - KEY=VALUE format
+    - Lines starting with # are comments (ignored)
+    - Blank lines are ignored
+    - Export keyword is ignored (e.g., "export KEY=VALUE" is treated as "KEY=VALUE")
+    - Values can be quoted with single or double quotes
+    - Variable expansion and interpolation (if needed)
+
+    Args:
+        file_path: Path to the .env file to parse
+
+    Returns:
+        Dictionary of environment variable key-value pairs (excluding None values)
+
+    Example:
+        >>> env_vars = parse_dotenv_file(".env")
+        >>> print(env_vars.get("API_KEY"))
+        'my-secret-key'
+    """
+    file_path = Path(file_path)
+
+    if not file_path.exists():
+        return {}
+
+    try:
+        # Use dotenv_values to parse the file
+        # This returns a dict with all variables, including None for empty values
+        env_dict = dotenv_values(file_path)
+        # Filter out None values and convert to strings
+        return {k: str(v) for k, v in env_dict.items() if v is not None}
+    except (OSError, UnicodeDecodeError):
+        # If we can't read the file, return empty dict (silent failure)
+        # This maintains the "no error if .env is missing" requirement
+        return {}
+
+
+def find_and_merge_dotenv_files(project_root: str | Path | None = None) -> dict[str, str]:
+    """
+    Find and merge .env files from project root and ./mci directory.
+
+    This function looks for .env files with the following priority order:
+    1. Check for .env.mci files first (MCI-specific configs have priority)
+       a. {project_root}/mci/.env.mci (MCI library MCI-specific)
+       b. {project_root}/.env.mci (project MCI-specific - highest priority)
+    2. If no .env.mci files exist, check for .env files
+       a. {project_root}/mci/.env (MCI library defaults)
+       b. {project_root}/.env (project-level configs)
+
+    Variables from files loaded later override those from earlier files.
+
+    Args:
+        project_root: Path to the project root directory. If None, uses current directory.
+
+    Returns:
+        Dictionary of merged environment variables
+
+    Example:
+        >>> env_vars = find_and_merge_dotenv_files()
+        >>> # Variables from root .env.mci override all others
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+    else:
+        project_root = Path(project_root)
+
+    merged_env: dict[str, str] = {}
+
+    # Check for .env.mci files first (MCI-specific configs)
+    mci_env_mci_path = project_root / "mci" / ".env.mci"
+    root_env_mci_path = project_root / ".env.mci"
+
+    has_env_mci = mci_env_mci_path.exists() or root_env_mci_path.exists()
+
+    if has_env_mci:
+        # Priority order for .env.mci files (lowest to highest):
+        # 1. ./mci/.env.mci (library MCI-specific)
+        if mci_env_mci_path.exists():
+            mci_env_mci_vars = parse_dotenv_file(mci_env_mci_path)
+            merged_env.update(mci_env_mci_vars)
+
+        # 2. .env.mci (project root MCI-specific - highest priority)
+        if root_env_mci_path.exists():
+            root_env_mci_vars = parse_dotenv_file(root_env_mci_path)
+            merged_env.update(root_env_mci_vars)
+    else:
+        # No .env.mci files found, check for .env files
+        # Priority order for .env files (lowest to highest):
+        # 1. ./mci/.env (library defaults)
+        mci_env_path = project_root / "mci" / ".env"
+        if mci_env_path.exists():
+            mci_env_vars = parse_dotenv_file(mci_env_path)
+            merged_env.update(mci_env_vars)
+
+        # 2. .env (project root - higher priority)
+        root_env_path = project_root / ".env"
+        if root_env_path.exists():
+            root_env_vars = parse_dotenv_file(root_env_path)
+            merged_env.update(root_env_vars)
+
+    return merged_env
+
+
+def get_env_with_dotenv(
+    project_root: str | Path | None = None, additional_env: dict[str, str] | None = None
+) -> dict[str, str]:
+    """
+    Get complete environment variables including system, .env files, and additional vars.
+
+    The precedence order (lowest to highest):
+    - If .env.mci files exist:
+      1. ./mci/.env.mci (library MCI-specific)
+      2. {project_root}/.env.mci (project MCI-specific)
+    - If no .env.mci files exist:
+      1. ./mci/.env (library defaults)
+      2. {project_root}/.env (project-level)
+    - Then:
+      3. System environment variables (os.environ)
+      4. Additional environment variables passed as argument (highest)
+
+    Args:
+        project_root: Path to the project root directory. If None, uses current directory.
+        additional_env: Additional environment variables to merge (highest priority)
+
+    Returns:
+        Dictionary of merged environment variables with proper precedence
+
+    Example:
+        >>> # Get all env vars with .env files loaded
+        >>> env_vars = get_env_with_dotenv()
+        >>> # Add custom vars that override everything
+        >>> env_vars = get_env_with_dotenv(additional_env={"API_KEY": "override"})
+    """
+    # Start with .env files (lowest priority)
+    merged_env = find_and_merge_dotenv_files(project_root)
+
+    # Merge with system environment variables (higher priority)
+    merged_env.update(os.environ)
+
+    # Merge with additional environment variables (highest priority)
+    if additional_env:
+        merged_env.update(additional_env)
+
+    return merged_env

mci/utils/env_scanner.py

@@ -0,0 +1,84 @@
+"""
+env_scanner.py - Environment variable scanning utilities
+
+This module provides utilities to scan MCI schemas and extract all
+referenced environment variables from template placeholders.
+"""
+
+import re
+from typing import Any
+
+
+class EnvScanner:
+    """
+    Scans MCI schemas to find all environment variable references.
+
+    Environment variables can appear in templates as {{env.VARIABLE_NAME}}.
+    This scanner recursively searches through dictionaries, lists, and strings
+    to find all such references.
+    """
+
+    # Regex pattern to match {{env.VARIABLE_NAME}}
+    ENV_PATTERN: re.Pattern[str] = re.compile(r"\{\{env\.([A-Za-z_][A-Za-z0-9_]*)\}\}")
+
+    @staticmethod
+    def scan_value(value: Any) -> set[str]:
+        """
+        Scan a single value for environment variable references.
+
+        Args:
+            value: Value to scan (can be str, dict, list, or other types)
+
+        Returns:
+            Set of environment variable names found
+
+        Example:
+            >>> EnvScanner.scan_value("{{env.API_KEY}}")
+            {'API_KEY'}
+            >>> EnvScanner.scan_value("Hello {{env.USER}}, your key is {{env.API_KEY}}")
+            {'USER', 'API_KEY'}
+        """
+        env_vars: set[str] = set()
+
+        if isinstance(value, str):
+            # Extract all env variable names from the string
+            matches = EnvScanner.ENV_PATTERN.findall(value)
+            env_vars.update(matches)
+
+        elif isinstance(value, dict):
+            # Recursively scan all values in the dictionary
+            for v in value.values():
+                env_vars.update(EnvScanner.scan_value(v))
+
+        elif isinstance(value, list):
+            # Recursively scan all items in the list
+            for item in value:
+                env_vars.update(EnvScanner.scan_value(item))
+
+        return env_vars
+
+    @staticmethod
+    def scan_dict(data: dict[str, Any]) -> set[str]:
+        """
+        Scan a dictionary for environment variable references.
+
+        This is a convenience wrapper around scan_value() for dictionaries.
+
+        Args:
+            data: Dictionary to scan
+
+        Returns:
+            Set of environment variable names found
+
+        Example:
+            >>> schema = {
+            ...     "execution": {
+            ...         "type": "http",
+            ...         "url": "{{env.BASE_URL}}/api",
+            ...         "headers": {"Authorization": "Bearer {{env.API_KEY}}"}
+            ...     }
+            ... }
+            >>> EnvScanner.scan_dict(schema)
+            {'BASE_URL', 'API_KEY'}
+        """
+        return EnvScanner.scan_value(data)

mci/utils/error_formatter.py

@@ -0,0 +1,165 @@
+"""
+error_formatter.py - Format validation errors and warnings for CLI display
+
+This module provides utilities for formatting validation errors and warnings
+in a user-friendly way with color-coded output using Rich library.
+"""
+
+from dataclasses import dataclass
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+
+@dataclass
+class ValidationError:
+    """Represents a validation error with message and optional location."""
+
+    message: str
+    location: str | None = None
+
+
+@dataclass
+class ValidationWarning:
+    """Represents a validation warning with message and optional suggestion."""
+
+    message: str
+    suggestion: str | None = None
+
+
+class ErrorFormatter:
+    """
+    Formats validation errors and warnings for CLI display.
+
+    This class provides methods to format validation results using the Rich library
+    for beautiful, color-coded terminal output.
+    """
+
+    def __init__(self, console: Console | None = None):
+        """
+        Initialize the ErrorFormatter.
+
+        Args:
+            console: Rich Console instance. Defaults to a new Console if not provided.
+        """
+        self.console: Console = console if console is not None else Console()
+
+    def format_validation_errors(self, errors: list[ValidationError]) -> None:
+        """
+        Display validation errors with color-coded output.
+
+        Args:
+            errors: List of ValidationError objects to display
+
+        Example:
+            >>> formatter = ErrorFormatter()
+            >>> errors = [ValidationError(message="Missing required field: name")]
+            >>> formatter.format_validation_errors(errors)
+        """
+        if not errors:
+            return
+
+        self.console.print()
+        error_text = Text()
+        error_text.append("❌ Validation Errors\n\n", style="bold red")
+
+        for i, error in enumerate(errors, 1):
+            error_text.append(f"{i}. ", style="red")
+            if error.location:
+                error_text.append(f"[{error.location}] ", style="yellow")
+            error_text.append(f"{error.message}\n", style="red")
+
+        panel = Panel(
+            error_text,
+            title="[bold red]Schema Validation Failed",
+            border_style="red",
+            expand=False,
+        )
+        self.console.print(panel)
+
+    def format_validation_warnings(self, warnings: list[ValidationWarning]) -> None:
+        """
+        Display validation warnings with color-coded output.
+
+        Args:
+            warnings: List of ValidationWarning objects to display
+
+        Example:
+            >>> formatter = ErrorFormatter()
+            >>> warnings = [ValidationWarning(
+            ...     message="Toolset file not found: weather.mci.json",
+            ...     suggestion="Create the file or update your schema"
+            ... )]
+            >>> formatter.format_validation_warnings(warnings)
+        """
+        if not warnings:
+            return
+
+        self.console.print()
+        warning_text = Text()
+        warning_text.append("⚠️  Validation Warnings\n\n", style="bold yellow")
+
+        for i, warning in enumerate(warnings, 1):
+            warning_text.append(f"{i}. ", style="yellow")
+            warning_text.append(f"{warning.message}\n", style="yellow")
+            if warning.suggestion:
+                warning_text.append(f"   💡 {warning.suggestion}\n", style="cyan dim")
+
+        panel = Panel(
+            warning_text,
+            title="[bold yellow]Warnings",
+            border_style="yellow",
+            expand=False,
+        )
+        self.console.print(panel)
+
+    def format_validation_success(self, file_path: str) -> None:
+        """
+        Display validation success message.
+
+        Args:
+            file_path: Path to the validated file
+
+        Example:
+            >>> formatter = ErrorFormatter()
+            >>> formatter.format_validation_success("mci.json")
+        """
+        self.console.print()
+        success_text = Text()
+        success_text.append("✅ Schema is valid!\n\n", style="bold green")
+        success_text.append(f"File: {file_path}", style="green")
+
+        panel = Panel(
+            success_text,
+            title="[bold green]Validation Successful",
+            border_style="green",
+            expand=False,
+        )
+        self.console.print(panel)
+        self.console.print()
+
+    def format_mci_error(self, error_message: str) -> None:
+        """
+        Display an MCIClient error message.
+
+        Args:
+            error_message: Error message from MCIClient
+
+        Example:
+            >>> formatter = ErrorFormatter()
+            >>> formatter.format_mci_error("Failed to load schema: Invalid JSON")
+        """
+        self.console.print()
+        error_text = Text()
+        error_text.append("❌ MCI Error\n\n", style="bold red")
+        error_text.append(error_message, style="red")
+
+        panel = Panel(
+            error_text,
+            title="[bold red]Error",
+            border_style="red",
+            expand=False,
+        )
+        self.console.print(panel)
+        self.console.print()

mci/utils/error_handler.py

@@ -0,0 +1,174 @@
+"""
+error_handler.py - Error handling utilities for CLI
+
+This module provides utilities for formatting errors from mci-py
+in a CLI-friendly way, with helpful messages and suggestions.
+"""
+
+from mcipy import MCIClientError
+
+
+class ErrorHandler:
+    """
+    Handles and formats errors for CLI display.
+
+    This class provides methods to format exceptions from mci-py
+    into user-friendly error messages suitable for terminal output.
+    """
+
+    @staticmethod
+    def format_mci_client_error(error: MCIClientError) -> str:
+        """
+        Format MCIClientError for CLI display.
+
+        Converts technical error messages from MCIClient into
+        user-friendly messages with helpful suggestions.
+
+        Args:
+            error: MCIClientError exception from mci-py
+
+        Returns:
+            Formatted error message string
+
+        Example:
+            >>> from mcipy import MCIClientError
+            >>> try:
+            ...     # Some MCIClient operation
+            ...     pass
+            ... except MCIClientError as e:
+            ...     msg = ErrorHandler.format_mci_client_error(e)
+            ...     print(msg)
+        """
+        error_str = str(error)
+
+        # Check for common error patterns and provide helpful messages
+        if "No such file or directory" in error_str:
+            return (
+                f"❌ Schema file not found\n\n"
+                f"Error: {error_str}\n\n"
+                f"💡 Suggestions:\n"
+                f"  • Check that the file path is correct\n"
+                f"  • Run 'mcix install' to create a default mci.json file\n"
+                f"  • Use --file option to specify a different schema file"
+            )
+
+        if "Unsupported file extension" in error_str:
+            return (
+                f"❌ Unsupported file format\n\n"
+                f"Error: {error_str}\n\n"
+                f"💡 Supported formats:\n"
+                f"  • .json (JSON format)\n"
+                f"  • .yaml or .yml (YAML format)"
+            )
+
+        if "Failed to load schema" in error_str:
+            # Try to extract the specific parse error
+            return (
+                f"❌ Failed to load schema\n\n"
+                f"Error: {error_str}\n\n"
+                f"💡 Suggestions:\n"
+                f"  • Check that the file contains valid JSON or YAML\n"
+                f"  • Run 'mcix validate' to see detailed validation errors\n"
+                f"  • Check for syntax errors like missing commas or brackets"
+            )
+
+        if "Tool not found" in error_str:
+            return (
+                f"❌ Tool not found\n\n"
+                f"Error: {error_str}\n\n"
+                f"💡 Suggestions:\n"
+                f"  • Run 'mcix list' to see all available tools\n"
+                f"  • Check the tool name for typos\n"
+                f"  • Ensure the tool is defined in your schema"
+            )
+
+        if "Template variable not found" in error_str:
+            return (
+                f"❌ Missing template variable\n\n"
+                f"Error: {error_str}\n\n"
+                f"💡 Suggestions:\n"
+                f"  • Set required environment variables before running the tool\n"
+                f"  • Check your schema for {{{{env.VARIABLE}}}} placeholders\n"
+                f"  • Use --env option to provide environment variables"
+            )
+
+        if "validation" in error_str.lower() or "invalid" in error_str.lower():
+            return (
+                f"❌ Schema validation error\n\n"
+                f"Error: {error_str}\n\n"
+                f"💡 Suggestions:\n"
+                f"  • Run 'mcix validate' for detailed validation errors\n"
+                f"  • Check that all required fields are present\n"
+                f"  • Verify that field types match the schema specification"
+            )
+
+        # Default formatting for other errors
+        return f"❌ Error\n\n{error_str}"
+
+    @staticmethod
+    def format_generic_error(error: Exception) -> str:
+        """
+        Format a generic exception for CLI display.
+
+        Args:
+            error: Any Python exception
+
+        Returns:
+            Formatted error message string
+
+        Example:
+            >>> try:
+            ...     # Some operation
+            ...     pass
+            ... except Exception as e:
+            ...     msg = ErrorHandler.format_generic_error(e)
+            ...     print(msg)
+        """
+        error_str = str(error)
+        error_type = type(error).__name__
+
+        return f"❌ {error_type}\n\n{error_str}"
+
+    @staticmethod
+    def format_file_not_found_error(file_path: str) -> str:
+        """
+        Format a file not found error with helpful suggestions.
+
+        Args:
+            file_path: Path to the file that was not found
+
+        Returns:
+            Formatted error message string
+
+        Example:
+            >>> msg = ErrorHandler.format_file_not_found_error("mci.json")
+            >>> print(msg)
+        """
+        return (
+            f"❌ File not found: {file_path}\n\n"
+            f"💡 Suggestions:\n"
+            f"  • Run 'mcix install' to create a default mci.json file\n"
+            f"  • Check that you're in the correct directory\n"
+            f"  • Use --file option to specify a different schema file"
+        )
+
+    @staticmethod
+    def format_validation_error(message: str) -> str:
+        """
+        Format a validation error message.
+
+        Args:
+            message: Validation error message
+
+        Returns:
+            Formatted error message string
+
+        Example:
+            >>> msg = ErrorHandler.format_validation_error("Missing required field: name")
+            >>> print(msg)
+        """
+        return (
+            f"❌ Validation Error\n\n"
+            f"{message}\n\n"
+            f"💡 Run 'mcix validate' for detailed validation information"
+        )

mci/utils/timestamp.py

@@ -0,0 +1,50 @@
+"""
+timestamp.py - Timestamp utilities for file output
+
+This module provides utilities for generating timestamped filenames
+and ISO 8601 timestamps for use in CLI output files.
+"""
+
+from datetime import UTC, datetime
+
+
+def generate_timestamp_filename(format: str, prefix: str = "tools") -> str:
+    """
+    Generate a timestamped filename for output files.
+
+    Creates a filename in the format: {prefix}_YYYYMMDD_HHMMSS.{format}
+    Uses UTC time for consistency.
+
+    Args:
+        format: File extension (e.g., "json", "yaml")
+        prefix: Filename prefix (default: "tools")
+
+    Returns:
+        Timestamped filename string (e.g., "tools_20241029_143022.json")
+
+    Example:
+        >>> filename = generate_timestamp_filename("json")
+        >>> print(filename)
+        tools_20241029_143022.json
+    """
+    now = datetime.now(UTC)
+    timestamp = now.strftime("%Y%m%d_%H%M%S")
+    return f"{prefix}_{timestamp}.{format}"
+
+
+def get_iso_timestamp() -> str:
+    """
+    Get current timestamp in ISO 8601 format.
+
+    Returns UTC timestamp in ISO 8601 format for use in metadata.
+
+    Returns:
+        ISO 8601 formatted timestamp string
+
+    Example:
+        >>> timestamp = get_iso_timestamp()
+        >>> print(timestamp)
+        2024-10-29T14:30:22Z
+    """
+    now = datetime.now(UTC)
+    return now.strftime("%Y-%m-%dT%H:%M:%SZ")