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

mci/cli/run.py

@@ -0,0 +1,125 @@
+"""
+run.py - Run command for starting MCP servers from MCI schemas
+
+This module implements the `mcix run` command, which launches an MCP server
+over STDIO that dynamically serves tools from an MCI schema file. The server
+loads tools using MCIClient, converts them to MCP format, and delegates
+execution back to MCIClient.
+"""
+
+import asyncio
+import os
+
+import click
+from mcipy import MCIClientError
+from rich.console import Console
+
+from mci.core.dynamic_server import run_server
+from mci.core.file_finder import MCIFileFinder
+from mci.utils.error_handler import ErrorHandler
+
+
+@click.command()
+@click.option(
+    "--file",
+    "-f",
+    type=click.Path(exists=True),
+    default=None,
+    help="Path to MCI schema file (defaults to mci.json or mci.yaml in current directory)",
+)
+@click.option(
+    "--filter",
+    type=str,
+    default=None,
+    help="Filter tools (format: type:value1,value2 - e.g., tags:api,database)",
+)
+def run(file: str | None, filter: str | None):
+    """
+    Run an MCP server that serves tools from an MCI schema.
+
+    Launches an MCP server over STDIO that dynamically loads and serves tools
+    from the specified MCI schema file. The server uses MCIClient to load tools
+    (including toolsets and environment variable templating), converts them to
+    MCP format, and delegates execution back to MCIClient.
+
+    The server supports:
+    - Loading tools from JSON/YAML MCI schemas
+    - Tool filtering by name, tags, and toolsets
+    - Environment variable templating
+    - Graceful shutdown on Ctrl+C
+
+    Examples:
+
+        # Run server with default mci.json or mci.yaml
+        mcix run
+
+        # Run server with specific file
+        mcix run --file=./custom.mci.json
+
+        # Run server with filtered tools
+        mcix run --filter=tags:api,database
+
+        # Run server with only specific tools
+        mcix run --filter=only:tool1,tool2
+
+        # Run server excluding specific tools
+        mcix run --filter=except:tool3,tool4
+
+        # Run server with tools from specific toolsets
+        mcix run --filter=toolsets:weather,database
+    """
+    console = Console()
+
+    try:
+        # Step 1: Find MCI file
+        if file is None:
+            finder = MCIFileFinder()
+            file = finder.find_mci_file()
+            if file is None:
+                console.print(
+                    "[red]✗[/red] No MCI schema file found. "
+                    "Run 'mcix install' to create one or specify --file.",
+                    style="red",
+                )
+                raise click.Abort()
+
+        # Step 2: Validate filter spec if provided
+        if filter:
+            # Validate filter format early to provide better error messages
+            from mci.core.tool_manager import ToolManager
+
+            try:
+                ToolManager.parse_filter_spec(filter)
+            except ValueError as e:
+                console.print(f"[red]✗[/red] Invalid filter: {e}", style="red")
+                raise click.Abort() from e
+
+        # Step 3: Gather environment variables for templating
+        env_vars = dict(os.environ)
+
+        # Step 4: Display startup message
+        console.print("[green]⚡[/green] Starting MCP server...", style="bold green")
+        console.print(f"[cyan]📄 Schema:[/cyan] {file}")
+        if filter:
+            console.print(f"[cyan]🔍 Filter:[/cyan] {filter}")
+        console.print()
+        console.print("[dim]Press Ctrl+C to stop the server[/dim]")
+        console.print()
+
+        # Step 5: Run the server (this blocks until Ctrl+C)
+        asyncio.run(run_server(file, filter, env_vars))
+
+    except KeyboardInterrupt:
+        # Graceful shutdown on Ctrl+C
+        console.print()
+        console.print("[yellow]⏹[/yellow] Server stopped by user", style="yellow")
+    except click.Abort:
+        raise
+    except MCIClientError as e:
+        console.print()
+        console.print(ErrorHandler.format_mci_client_error(e))
+        raise click.Abort() from e
+    except Exception as e:
+        console.print()
+        console.print(ErrorHandler.format_generic_error(e))
+        raise click.Abort() from e

mci/cli/validate.py

@@ -0,0 +1,113 @@
+"""
+validate.py - CLI command to validate MCI schemas
+
+This module provides the `mcix validate` command which checks MCI schema
+correctness using mci-py's built-in validation and provides user-friendly
+error and warning messages.
+"""
+
+import os
+import sys
+
+import click
+
+from mci.core.file_finder import MCIFileFinder
+from mci.core.validator import MCIValidator
+from mci.utils.error_formatter import ErrorFormatter
+
+
+@click.command()
+@click.option(
+    "--file",
+    "-f",
+    default=None,
+    help="Path to MCI schema file (default: auto-discover mci.json/mci.yaml)",
+)
+@click.option(
+    "--env",
+    "-e",
+    multiple=True,
+    help="Environment variables in KEY=VALUE format (can be specified multiple times)",
+)
+def validate(file: str | None, env: tuple[str, ...]) -> None:
+    """
+    Validate MCI schema file for correctness.
+
+    This command validates an MCI schema file using mci-py's built-in validation
+    engine. It checks for:
+    - Schema structure and syntax
+    - Required fields and data types
+    - Valid references and tool definitions
+
+    Additionally, it provides warnings for:
+    - Missing toolset files
+    - MCP commands not in PATH
+
+    Examples:
+        mcix validate                        # Validate default mci.json/mci.yaml
+        mcix validate --file custom.mci.json # Validate specific file
+        mcix validate -e API_KEY=123         # Provide environment variables
+    """
+    formatter = ErrorFormatter()
+
+    # Parse environment variables
+    env_vars = {}
+    for env_pair in env:
+        if "=" in env_pair:
+            key, value = env_pair.split("=", 1)
+            env_vars[key] = value
+        else:
+            formatter.console.print(
+                f"[yellow]Warning: Invalid environment variable format: {env_pair}. "
+                "Expected KEY=VALUE.[/yellow]"
+            )
+
+    # Merge environment variables: user-provided env vars override system environment variables
+    merged_env = {**os.environ, **env_vars}
+
+    # Find the schema file
+    if file is None:
+        file_finder = MCIFileFinder()
+        file = file_finder.find_mci_file()
+        if file is None:
+            formatter.console.print("[red]❌ No MCI schema file found in current directory[/red]\n")
+            formatter.console.print(
+                "[yellow]💡 Run 'mcix install' to create a default mci.json file[/yellow]"
+            )
+            sys.exit(1)
+
+    # Validate the schema
+    validator = MCIValidator(file_path=file, env_vars=merged_env)
+
+    try:
+        result = validator.validate_schema()
+
+        # Display errors
+        if result.errors:
+            formatter.format_validation_errors(result.errors)
+            formatter.console.print(
+                "\n[yellow]💡 Fix the errors above and run 'mcix validate' again[/yellow]\n"
+            )
+            sys.exit(1)
+
+        # Display warnings (if any)
+        if result.warnings:
+            formatter.format_validation_warnings(result.warnings)
+
+        # Display success message
+        formatter.format_validation_success(file)
+
+        # Exit with appropriate code
+        sys.exit(0)
+
+    except FileNotFoundError as e:
+        formatter.format_mci_error(f"File not found: {str(e)}")
+        sys.exit(1)
+    except Exception as e:
+        formatter.format_mci_error(f"Unexpected error: {str(e)}")
+        sys.exit(1)
+
+
+# Allow running as script
+if __name__ == "__main__":
+    validate()

mci/core/__init__.py

@@ -0,0 +1,8 @@
+"""
+Core business logic for the MCI CLI Tool.
+
+This package contains the core functionality for MCI schema management,
+tool loading, MCP server creation, and execution.
+"""
+
+__all__ = ()

mci/core/config.py

@@ -0,0 +1,144 @@
+"""
+config.py - Configuration loading and validation for MCI files
+
+This module provides functionality to load and validate MCI configuration files
+using the MCIClient from mci-py. It handles schema validation, error handling,
+and provides user-friendly error messages. It also automatically loads environment
+variables from .env files in the project root and ./mci directory.
+"""
+
+from pathlib import Path
+
+from mcipy import MCIClient, MCIClientError
+
+from mci.utils.dotenv import get_env_with_dotenv
+
+
+class MCIConfig:
+    """
+    Manages MCI configuration file loading and validation.
+
+    This class provides methods to load MCI configuration files using the
+    MCIClient from mci-py, which performs built-in schema validation.
+    It also provides utilities for validating schemas and extracting
+    user-friendly error messages.
+
+    The class automatically loads environment variables from .env files in:
+    - The project root directory (same location as the MCI schema file)
+    - The ./mci directory
+
+    Variables are merged with project root taking precedence over ./mci/.env.
+    """
+
+    @staticmethod
+    def load(
+        file_path: str, env_vars: dict[str, str] | None = None, auto_load_dotenv: bool = True
+    ) -> MCIClient:
+        """
+        Load and parse an MCI configuration file using MCIClient.
+
+        This method uses MCIClient from mci-py to load and validate the schema.
+        The MCIClient performs comprehensive schema validation during initialization.
+
+        If auto_load_dotenv is True (default), automatically loads environment variables
+        from .env and .env.mci files. Priority order:
+        - 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
+          4. env_vars argument (highest priority)
+
+        Args:
+            file_path: Path to the MCI schema file (.json, .yaml, or .yml)
+            env_vars: Optional environment variables for template substitution (highest priority)
+            auto_load_dotenv: Whether to automatically load .env files (default: True)
+
+        Returns:
+            An initialized MCIClient instance
+
+        Raises:
+            MCIClientError: If the schema file cannot be loaded or parsed, or if
+                          validation fails
+
+        Example:
+            >>> config = MCIConfig()
+            >>> try:
+            ...     # Auto-loads .env files from project root and ./mci
+            ...     client = config.load("mci.json")
+            ...     tools = client.tools()
+            ... except MCIClientError as e:
+            ...     print(f"Schema invalid: {e}")
+        """
+        try:
+            # Determine project root from schema file location
+            project_root = Path(file_path).parent.resolve()
+
+            # Load environment variables with proper precedence
+            if auto_load_dotenv:
+                merged_env = get_env_with_dotenv(project_root, env_vars)
+            else:
+                # If auto-loading is disabled, just use provided env_vars
+                merged_env = env_vars or {}
+
+            client = MCIClient(schema_file_path=file_path, env_vars=merged_env)
+            return client
+        except MCIClientError:
+            # Re-raise with the original error message from mci-py
+            raise
+
+    @staticmethod
+    def validate_schema(
+        file_path: str, env_vars: dict[str, str] | None = None, auto_load_dotenv: bool = True
+    ) -> tuple[bool, str]:
+        """
+        Validate an MCI schema file using MCIClient.
+
+        This method validates the schema using MCIClient in validation-only mode,
+        which skips template resolution for MCP servers and other runtime concerns.
+        MCIClient performs comprehensive validation including schema structure,
+        required fields, and data types.
+
+        If auto_load_dotenv is True (default), automatically loads environment variables
+        from .env files in the project root and ./mci directory.
+
+        Args:
+            file_path: Path to the MCI schema file to validate
+            env_vars: Optional environment variables for template substitution
+            auto_load_dotenv: Whether to automatically load .env files (default: True)
+
+        Returns:
+            A tuple of (is_valid, error_message) where:
+            - is_valid is True if the schema is valid, False otherwise
+            - error_message is empty string if valid, or contains error details if invalid
+
+        Example:
+            >>> config = MCIConfig()
+            >>> is_valid, error = config.validate_schema("mci.json")
+            >>> if not is_valid:
+            ...     print(f"Validation failed: {error}")
+        """
+        try:
+            # Determine project root from schema file location
+            project_root = Path(file_path).parent.resolve()
+
+            # Load environment variables with proper precedence
+            if auto_load_dotenv:
+                merged_env = get_env_with_dotenv(project_root, env_vars)
+            else:
+                # If auto-loading is disabled, just use provided env_vars
+                merged_env = env_vars or {}
+
+            # Use validating=True to skip template resolution for MCP servers
+            # This allows validation without requiring all env_vars at validation time
+            MCIClient(schema_file_path=file_path, env_vars=merged_env, validating=True)
+            return (True, "")
+        except MCIClientError as e:
+            return (False, str(e))
+        except FileNotFoundError:
+            return (False, f"File not found: {file_path}")
+        except Exception as e:
+            return (False, f"Unexpected error: {str(e)}")

mci/core/dynamic_server.py

@@ -0,0 +1,187 @@
+"""
+dynamic_server.py - Dynamic MCP server creation from MCI schemas
+
+This module provides the DynamicMCPServer class for creating and running
+MCP servers that dynamically load tools from MCI schema files. The server
+uses MCIClient to load tools (including toolsets and environment variables),
+converts them to MCP format, and delegates execution back to MCIClient.
+
+The server supports:
+- Loading tools from JSON/YAML MCI schemas
+- Tool filtering by name, tags, and toolsets
+- STDIO transport for MCP protocol
+- Graceful shutdown and error handling
+- Environment variable templating
+
+Note: This module accesses dynamically added attributes on MCP Server instances
+(prefixed with _mci_). Type checkers will report these as unknown attributes,
+which is expected.
+"""
+# pyright: reportAttributeAccessIssue=false
+
+from mcp.server.lowlevel import Server
+
+from mci.core.mci_client import MCIClientWrapper
+from mci.core.mcp_server import MCPServerBuilder, ServerInstance
+from mci.core.tool_manager import ToolManager
+
+
+class DynamicMCPServer:
+    """
+    Creates and manages dynamic MCP servers from MCI schemas.
+
+    This class provides the main interface for creating MCP servers that serve
+    tools from MCI schema files. It handles loading, filtering, conversion,
+    and runtime management of the server.
+    """
+
+    def __init__(
+        self,
+        schema_path: str,
+        filter_spec: str | None = None,
+        env_vars: dict[str, str] | None = None,
+    ):
+        """
+        Initialize the dynamic server configuration.
+
+        Args:
+            schema_path: Path to the MCI schema file (.json, .yaml, or .yml)
+            filter_spec: Optional filter specification (e.g., "tags:api,database")
+            env_vars: Optional environment variables for template substitution
+        """
+        self.schema_path: str = schema_path
+        self.filter_spec: str | None = filter_spec
+        self.env_vars: dict[str, str] = env_vars or {}
+        self.server: Server | None = None
+        self.instance: ServerInstance | None = None
+        self.mci_client_wrapper: MCIClientWrapper | None = None
+
+    async def create_from_mci_schema(
+        self, server_name: str = "mci-dynamic-server", server_version: str = "1.0.0"
+    ) -> ServerInstance:
+        """
+        Create an MCP server instance from the MCI schema.
+
+        This method:
+        1. Loads tools using MCIClient (with toolsets and env var templating)
+        2. Applies filters if specified
+        3. Converts tools to MCP format using Stage 8 converter
+        4. Registers tools with MCP server
+        5. Sets up handlers for tool listing and execution
+        6. Returns ServerInstance ready for STDIO transport
+
+        Args:
+            server_name: Name for the MCP server
+            server_version: Version string for the server
+
+        Returns:
+            ServerInstance configured with MCI tools
+
+        Raises:
+            Exception: If schema loading, tool conversion, or server creation fails
+
+        Example:
+            >>> server = DynamicMCPServer("mci.json")
+            >>> instance = await server.create_from_mci_schema()
+            >>> await instance.start(stdio=True)
+        """
+        # Step 1: Load tools using MCIClient
+        self.mci_client_wrapper = MCIClientWrapper(self.schema_path, self.env_vars)
+
+        # Step 2: Apply filters if specified
+        if self.filter_spec:
+            tools = ToolManager.apply_filter_spec(self.mci_client_wrapper, self.filter_spec)
+        else:
+            tools = self.mci_client_wrapper.get_tools()
+
+        # Step 3: Create MCP server using Stage 8 infrastructure
+        builder = MCPServerBuilder(self.mci_client_wrapper.client)
+        self.server = await builder.create_server(server_name, server_version)
+
+        # Step 4: Register all tools (converter handles MCI to MCP conversion)
+        await builder.register_all_tools(self.server, tools)
+
+        # Step 5: Create ServerInstance (sets up handlers for listing and execution)
+        self.instance = ServerInstance(self.server, self.mci_client_wrapper.client, self.env_vars)
+
+        return self.instance
+
+    async def start_stdio(self) -> None:
+        """
+        Start the MCP server on STDIO transport.
+
+        This method starts the server and blocks until shutdown is requested.
+        The server will stop when:
+        - Ctrl+C (KeyboardInterrupt) is pressed
+        - The client disconnects
+        - An unrecoverable error occurs
+
+        The server will:
+        - Respond to MCP protocol requests for tool listing
+        - Execute tools by delegating to MCIClient.execute()
+        - Support structured output validation (outputSchema)
+        - Handle errors gracefully
+
+        Raises:
+            RuntimeError: If server instance is not created
+            Exception: If server startup or runtime fails
+
+        Example:
+            >>> server = DynamicMCPServer("mci.json")
+            >>> await server.create_from_mci_schema()
+            >>> await server.start_stdio()  # Blocks until Ctrl+C
+        """
+        if self.instance is None:
+            raise RuntimeError("Server instance not created. Call create_from_mci_schema() first.")
+
+        try:
+            # Start the server on STDIO (this blocks until server stops)
+            # KeyboardInterrupt will be raised automatically when Ctrl+C is pressed
+            await self.instance.start(stdio=True)
+        except KeyboardInterrupt:
+            # Graceful shutdown on Ctrl+C
+            pass
+        finally:
+            # Cleanup
+            if self.instance:
+                self.instance.stop()
+
+    def get_tool_count(self) -> int:
+        """
+        Get the number of tools registered with the server.
+
+        Returns:
+            Number of registered tools, or 0 if server not created
+
+        Example:
+            >>> server = DynamicMCPServer("mci.json")
+            >>> await server.create_from_mci_schema()
+            >>> count = server.get_tool_count()
+            >>> print(f"Server has {count} tools")
+        """
+        if self.server and hasattr(self.server, "_mci_tools"):
+            return len(self.server._mci_tools)  # type: ignore[attr-defined]
+        return 0
+
+
+async def run_server(
+    schema_path: str, filter_spec: str | None = None, env_vars: dict[str, str] | None = None
+) -> None:
+    """
+    Create and run a dynamic MCP server from an MCI schema.
+
+    This is a convenience function that creates a server, loads tools,
+    and starts it on STDIO in a single call.
+
+    Args:
+        schema_path: Path to the MCI schema file
+        filter_spec: Optional filter specification (e.g., "tags:api,database")
+        env_vars: Optional environment variables for template substitution
+
+    Example:
+        >>> await run_server("mci.json")
+        >>> await run_server("mci.json", filter_spec="tags:api")
+    """
+    server = DynamicMCPServer(schema_path, filter_spec, env_vars)
+    await server.create_from_mci_schema()
+    await server.start_stdio()

mci/core/file_finder.py

@@ -0,0 +1,105 @@
+"""
+file_finder.py - File discovery logic for MCI configuration files
+
+This module provides functionality to locate MCI configuration files (mci.json or mci.yaml)
+in a given directory. It prioritizes JSON files when both formats exist and provides
+utilities for file format detection and validation.
+"""
+
+from pathlib import Path
+
+from mci.utils.validation import file_exists
+
+
+class MCIFileFinder:
+    """
+    Handles discovery of MCI configuration files in directories.
+
+    This class provides methods to find MCI configuration files (mci.json or mci.yaml),
+    with JSON files taking priority when both formats exist. It also includes utilities
+    for file validation and format detection.
+    """
+
+    @staticmethod
+    def find_mci_file(directory: str = ".") -> str | None:
+        """
+        Find an MCI configuration file in the specified directory.
+
+        Searches for mci.json first, then mci.yaml/mci.yml if JSON is not found.
+        This prioritizes JSON format when both formats exist in the same directory.
+
+        Args:
+            directory: The directory path to search in (default: current directory)
+
+        Returns:
+            The absolute path to the found MCI file, or None if no file is found
+
+        Example:
+            >>> finder = MCIFileFinder()
+            >>> path = finder.find_mci_file("./my_project")
+            >>> if path:
+            ...     print(f"Found: {path}")
+        """
+        dir_path = Path(directory).resolve()
+
+        # Check for mci.json first (priority)
+        json_path = dir_path / "mci.json"
+        if json_path.exists() and json_path.is_file():
+            return str(json_path)
+
+        # Check for mci.yaml
+        yaml_path = dir_path / "mci.yaml"
+        if yaml_path.exists() and yaml_path.is_file():
+            return str(yaml_path)
+
+        # Check for mci.yml as well
+        yml_path = dir_path / "mci.yml"
+        if yml_path.exists() and yml_path.is_file():
+            return str(yml_path)
+
+        return None
+
+    @staticmethod
+    def validate_file_exists(path: str) -> bool:
+        """
+        Check if a file exists at the given path.
+
+        Delegates to the validation utility module to avoid code duplication.
+
+        Args:
+            path: The file path to validate
+
+        Returns:
+            True if the file exists and is a file, False otherwise
+
+        Example:
+            >>> finder = MCIFileFinder()
+            >>> exists = finder.validate_file_exists("./mci.json")
+        """
+        return file_exists(path)
+
+    @staticmethod
+    def get_file_format(path: str) -> str | None:
+        """
+        Determine the file format based on the file extension.
+
+        Args:
+            path: The file path to check
+
+        Returns:
+            "json" for .json files, "yaml" for .yaml/.yml files, None for unknown formats
+
+        Example:
+            >>> finder = MCIFileFinder()
+            >>> fmt = finder.get_file_format("./mci.json")
+            >>> print(fmt)  # Output: "json"
+        """
+        file_path = Path(path)
+        ext = file_path.suffix.lower()
+
+        if ext == ".json":
+            return "json"
+        elif ext in [".yaml", ".yml"]:
+            return "yaml"
+        else:
+            return None