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

mci/core/schema_editor.py

@@ -0,0 +1,284 @@
+"""
+schema_editor.py - Schema file editing logic
+
+This module provides functionality to programmatically edit MCI schema files,
+including adding toolset references with optional filters while preserving
+the original file format (JSON or YAML).
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from mci.core.file_finder import MCIFileFinder
+
+
+class SchemaEditor:
+    """
+    Edits MCI schema files while preserving format and structure.
+
+    This class provides methods to load, modify, and save MCI schema files,
+    ensuring that the original file format (JSON or YAML) is preserved.
+    It supports adding toolset references with optional filters.
+    """
+
+    def __init__(self):
+        """Initialize the SchemaEditor with empty state."""
+        # Stores the loaded schema dictionary
+        self.schema_data: dict[str, Any] | None = None
+        # Stores the detected file format ('json' or 'yaml')
+        self.file_format: str | None = None
+        # Stores the path of the loaded schema file
+        self.file_path: str | None = None
+
+    def load_schema(self, file_path: str) -> dict[str, Any]:
+        """
+        Load an MCI schema file into memory.
+
+        Args:
+            file_path: Path to the MCI schema file (.json, .yaml, or .yml)
+
+        Returns:
+            The loaded schema data as a dictionary
+
+        Raises:
+            FileNotFoundError: If the file doesn't exist
+            ValueError: If the file format is unsupported
+            Exception: If the file cannot be parsed
+
+        Example:
+            >>> editor = SchemaEditor()
+            >>> schema = editor.load_schema("mci.json")
+            >>> print(schema.get("schemaVersion"))
+        """
+        path = Path(file_path)
+
+        if not path.exists():
+            raise FileNotFoundError(f"Schema file not found: {file_path}")
+
+        # Detect file format
+        file_finder = MCIFileFinder()
+        self.file_format = file_finder.get_file_format(str(path))
+
+        if self.file_format is None:
+            raise ValueError(f"Unsupported file format: {path.suffix}")
+
+        # Load the file
+        with open(path) as f:
+            if self.file_format == "json":
+                self.schema_data = json.load(f)
+            elif self.file_format == "yaml":
+                loaded_data = yaml.safe_load(f)
+                if loaded_data is None:
+                    raise ValueError(f"YAML file is empty or invalid: {file_path}")
+                self.schema_data = loaded_data
+            else:
+                raise ValueError(f"Unsupported file format: {self.file_format}")
+
+        self.file_path = str(path)
+
+        # Type narrowing: at this point schema_data is guaranteed to be a dict
+        assert self.schema_data is not None
+        return self.schema_data
+
+    def add_toolset(
+        self, toolset_name: str, filter_type: str | None = None, filter_value: str | None = None
+    ) -> None:
+        """
+        Add a toolset reference to the schema.
+
+        This method adds a toolset to the schema's toolsets array. If the toolset
+        already exists, it will be updated with the new filter (if provided).
+
+        Args:
+            toolset_name: Name of the toolset to add
+            filter_type: Optional filter type (only, except, tags, withoutTags)
+            filter_value: Optional comma-separated filter values
+
+        Raises:
+            ValueError: If schema hasn't been loaded yet
+            ValueError: If filter_type is provided without filter_value or vice versa
+
+        Example:
+            >>> editor = SchemaEditor()
+            >>> editor.load_schema("mci.json")
+            >>> editor.add_toolset("weather-tools")
+            >>> editor.add_toolset("analytics", "only", "Tool1,Tool2")
+            >>> editor.save_schema("mci.json")
+        """
+        if self.schema_data is None:
+            raise ValueError("No schema loaded. Call load_schema() first.")
+
+        # Validate filter arguments
+        if (filter_type is None) != (filter_value is None):
+            raise ValueError("filter_type and filter_value must both be provided or both be None")
+
+        # Ensure toolsets array exists
+        if "toolsets" not in self.schema_data:
+            self.schema_data["toolsets"] = []
+
+        toolsets = self.schema_data["toolsets"]
+
+        # Check if toolset already exists
+        existing_index = None
+        for i, toolset in enumerate(toolsets):
+            # Toolsets can be strings or objects
+            if isinstance(toolset, str) and toolset == toolset_name:
+                existing_index = i
+                break
+            elif isinstance(toolset, dict) and toolset.get("name") == toolset_name:
+                existing_index = i
+                break
+
+        # Prepare the toolset entry
+        if filter_type and filter_value:
+            toolset_entry = {
+                "name": toolset_name,
+                "filter": filter_type,
+                "filterValue": filter_value,
+            }
+        else:
+            toolset_entry = toolset_name
+
+        # Add or update the toolset
+        if existing_index is not None:
+            toolsets[existing_index] = toolset_entry
+        else:
+            toolsets.append(toolset_entry)
+
+    def save_schema(self, file_path: str | None = None) -> None:
+        """
+        Save the schema back to a file, preserving the original format.
+
+        Args:
+            file_path: Optional path to save to. If None, uses the path from load_schema()
+
+        Raises:
+            ValueError: If no schema is loaded
+            ValueError: If file_path is None and no file was previously loaded
+            ValueError: If file format cannot be determined
+
+        Example:
+            >>> editor = SchemaEditor()
+            >>> editor.load_schema("mci.json")
+            >>> editor.add_toolset("weather-tools")
+            >>> editor.save_schema()  # Saves to mci.json
+        """
+        if self.schema_data is None:
+            raise ValueError("No schema loaded. Call load_schema() first.")
+
+        # Determine the save path
+        save_path = file_path if file_path is not None else self.file_path
+
+        if save_path is None:
+            raise ValueError("No file path specified and no file was previously loaded")
+
+        # Determine format if saving to a new path
+        if file_path is not None:
+            file_finder = MCIFileFinder()
+            save_format = file_finder.get_file_format(file_path)
+            if save_format is None:
+                raise ValueError(f"Cannot determine format for file: {file_path}")
+        else:
+            save_format = self.file_format
+
+        if save_format is None:
+            raise ValueError("Cannot determine file format for saving")
+
+        # Write the file
+        path = Path(save_path)
+        with open(path, "w") as f:
+            if save_format == "json":
+                json.dump(self.schema_data, f, indent=2)
+                # Add newline at end of file for consistency
+                f.write("\n")
+            elif save_format == "yaml":
+                yaml.safe_dump(
+                    self.schema_data,
+                    f,
+                    default_flow_style=False,
+                    sort_keys=False,
+                    allow_unicode=True,
+                )
+            else:
+                raise ValueError(f"Unsupported save format: {save_format}")
+
+    def preserve_format(self) -> str:
+        """
+        Get the format of the loaded schema file.
+
+        Returns:
+            The file format ("json" or "yaml")
+
+        Raises:
+            ValueError: If no schema has been loaded
+
+        Example:
+            >>> editor = SchemaEditor()
+            >>> editor.load_schema("mci.json")
+            >>> print(editor.preserve_format())  # Output: "json"
+        """
+        if self.file_format is None:
+            raise ValueError("No schema loaded. Call load_schema() first.")
+        return self.file_format
+
+
+def parse_add_filter(filter_spec: str) -> tuple[str, str]:
+    """
+    Parse a filter specification string for the add command.
+
+    Filter specifications follow the format:
+    - "only:tool1,tool2,tool3" - Include only specified tools
+    - "except:tool1,tool2" - Exclude specified tools
+    - "tags:tag1,tag2" - Include tools with any of these tags
+    - "withoutTags:tag1,tag2" - Exclude tools with any of these tags
+
+    Args:
+        filter_spec: Filter specification string (e.g., "tags:api,database")
+
+    Returns:
+        Tuple of (filter_type, filter_value) where:
+        - filter_type is one of: "only", "except", "tags", "withoutTags"
+        - filter_value is the comma-separated list of values
+
+    Raises:
+        ValueError: If filter specification is invalid or malformed
+
+    Example:
+        >>> filter_type, filter_value = parse_add_filter("tags:api,database")
+        >>> print(filter_type, filter_value)
+        ('tags', 'api,database')
+    """
+    if not filter_spec or ":" not in filter_spec:
+        raise ValueError(
+            f"Invalid filter specification: '{filter_spec}'. "
+            "Expected format: 'type:value1,value2,...' "
+            "where type is one of: only, except, tags, withoutTags"
+        )
+
+    parts = filter_spec.split(":", 1)
+    if len(parts) != 2:
+        raise ValueError(f"Invalid filter specification: '{filter_spec}'")
+
+    filter_type = parts[0].strip()
+    filter_value = parts[1].strip()
+
+    # Validate filter type
+    valid_types = ["only", "except", "tags", "withoutTags"]
+    if filter_type not in valid_types:
+        raise ValueError(
+            f"Invalid filter type: '{filter_type}'. Valid types are: {', '.join(valid_types)}"
+        )
+
+    # Validate that we have values
+    if not filter_value:
+        raise ValueError(f"No values provided for filter type '{filter_type}'")
+
+    # Validate that values are not empty after splitting
+    values = [v.strip() for v in filter_value.split(",") if v.strip()]
+    if not values:
+        raise ValueError(f"No valid values found in filter specification: '{filter_spec}'")
+
+    return (filter_type, filter_value)

mci/core/tool_converter.py

@@ -0,0 +1,119 @@
+"""
+tool_converter.py - Convert MCI tools to MCP tool format
+
+This module provides functionality to convert MCI tool definitions (from mci-py)
+to MCP tool format compatible with the MCP protocol. It handles schema conversion,
+metadata preservation, and ensures proper formatting for MCP servers.
+"""
+
+from typing import Any
+
+import mcp.types as types
+from mcipy.models import Tool
+
+
+class MCIToolConverter:
+    """
+    Converter for translating MCI tool definitions to MCP tool format.
+
+    This class handles the conversion of tool metadata, descriptions, and JSON schemas
+    from the MCI format (used by mci-py) to the MCP format required by MCP servers.
+    """
+
+    @staticmethod
+    def convert_to_mcp_tool(mci_tool: Tool) -> types.Tool:
+        """
+        Convert an MCI Tool to MCP Tool format.
+
+        Takes a Tool object from mci-py and converts it to the types.Tool format
+        expected by the MCP protocol. This includes converting the input schema,
+        preserving all metadata, and transferring annotations.
+
+        Args:
+            mci_tool: Tool object from mci-py (Pydantic model)
+
+        Returns:
+            types.Tool object compatible with MCP protocol
+
+        Example:
+            >>> converter = MCIToolConverter()
+            >>> mcp_tool = converter.convert_to_mcp_tool(mci_tool)
+            >>> print(mcp_tool.name, mcp_tool.description)
+        """
+        # Convert inputSchema to MCP format (JSON Schema)
+        input_schema = MCIToolConverter.convert_input_schema(mci_tool.inputSchema or {})
+
+        # Convert annotations to MCP format
+        annotations = MCIToolConverter.convert_annotations(mci_tool.annotations)
+
+        # Create MCP Tool with converted schema and annotations
+        return types.Tool(
+            name=mci_tool.name,
+            description=mci_tool.description or "",
+            inputSchema=input_schema,
+            annotations=annotations,
+        )
+
+    @staticmethod
+    def convert_input_schema(mci_schema: dict[str, Any]) -> dict[str, Any]:
+        """
+        Convert MCI inputSchema to MCP-compatible JSON Schema format.
+
+        MCI and MCP both use JSON Schema for input validation, but this method
+        ensures the schema is in the exact format expected by MCP servers.
+        Currently, both formats are compatible, so this is mostly a pass-through
+        with validation.
+
+        Args:
+            mci_schema: Input schema dictionary from MCI tool definition
+
+        Returns:
+            JSON Schema dictionary compatible with MCP protocol
+
+        Example:
+            >>> schema = {"type": "object", "properties": {"name": {"type": "string"}}}
+            >>> mcp_schema = MCIToolConverter.convert_input_schema(schema)
+        """
+        # Both MCI and MCP use JSON Schema, so we can pass through
+        # If the schema is empty, provide a minimal valid schema
+        if not mci_schema:
+            return {"type": "object", "properties": {}}
+
+        # Ensure the schema has at minimum a type field
+        if "type" not in mci_schema:
+            return {"type": "object", "properties": mci_schema}
+
+        return mci_schema
+
+    @staticmethod
+    def convert_annotations(mci_annotations: Any) -> types.ToolAnnotations | None:
+        """
+        Convert MCI Annotations to MCP ToolAnnotations format.
+
+        Transfers annotation fields from MCI tool annotations to the MCP format,
+        including title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.
+
+        Args:
+            mci_annotations: Annotations object from MCI tool definition (or None)
+
+        Returns:
+            ToolAnnotations object compatible with MCP protocol, or None if no annotations
+
+        Example:
+            >>> from mcipy.models import Annotations
+            >>> mci_ann = Annotations(title="My Tool", readOnlyHint=True)
+            >>> mcp_ann = MCIToolConverter.convert_annotations(mci_ann)
+            >>> print(mcp_ann.title, mcp_ann.readOnlyHint)
+        """
+        if mci_annotations is None:
+            return None
+
+        # Convert MCI Annotations to MCP ToolAnnotations
+        # Both models have the same field structure, so we can extract and transfer
+        return types.ToolAnnotations(
+            title=mci_annotations.title,
+            readOnlyHint=mci_annotations.readOnlyHint,
+            destructiveHint=mci_annotations.destructiveHint,
+            idempotentHint=mci_annotations.idempotentHint,
+            openWorldHint=mci_annotations.openWorldHint,
+        )

mci/core/tool_manager.py

@@ -0,0 +1,118 @@
+"""
+tool_manager.py - Tool filtering and management logic
+
+This module provides utilities for parsing filter specifications from the CLI
+and applying them to tools using the MCIClient filtering methods.
+"""
+
+from mcipy.models import Tool
+
+from mci.core.mci_client import MCIClientWrapper
+
+
+class ToolManager:
+    """
+    Manages tool filtering based on CLI filter specifications.
+
+    This class parses filter specifications from command-line arguments
+    and applies them using MCIClient's built-in filtering methods.
+    """
+
+    @staticmethod
+    def parse_filter_spec(filter_spec: str) -> tuple[str, list[str]]:
+        """
+        Parse a filter specification string into filter type and values.
+
+        Filter specifications follow the format:
+        - "only:tool1,tool2,tool3" - Include only specified tools
+        - "except:tool1,tool2" - Exclude specified tools
+        - "tags:tag1,tag2" - Include tools with any of these tags
+        - "without-tags:tag1,tag2" - Exclude tools with any of these tags
+        - "toolsets:toolset1,toolset2" - Include tools from specified toolsets
+
+        Args:
+            filter_spec: Filter specification string (e.g., "tags:api,database")
+
+        Returns:
+            Tuple of (filter_type, values) where:
+            - filter_type is one of: "only", "except", "tags", "without-tags", "toolsets"
+            - values is a list of filter values
+
+        Raises:
+            ValueError: If filter specification is invalid or malformed
+
+        Example:
+            >>> filter_type, values = ToolManager.parse_filter_spec("tags:api,database")
+            >>> print(filter_type, values)
+            ('tags', ['api', 'database'])
+        """
+        if not filter_spec or ":" not in filter_spec:
+            raise ValueError(
+                f"Invalid filter specification: '{filter_spec}'. "
+                "Expected format: 'type:value1,value2,...' "
+                "where type is one of: only, except, tags, without-tags, toolsets"
+            )
+
+        parts = filter_spec.split(":", 1)
+        if len(parts) != 2:
+            raise ValueError(f"Invalid filter specification: '{filter_spec}'")
+
+        filter_type = parts[0].strip()
+        values_str = parts[1].strip()
+
+        # Validate filter type
+        valid_types = ["only", "except", "tags", "without-tags", "toolsets"]
+        if filter_type not in valid_types:
+            raise ValueError(
+                f"Invalid filter type: '{filter_type}'. Valid types are: {', '.join(valid_types)}"
+            )
+
+        # Parse comma-separated values
+        if not values_str:
+            raise ValueError(f"No values provided for filter type '{filter_type}'")
+
+        values = [v.strip() for v in values_str.split(",") if v.strip()]
+        if not values:
+            raise ValueError(f"No valid values found in filter specification: '{filter_spec}'")
+
+        return (filter_type, values)
+
+    @staticmethod
+    def apply_filter_spec(client: MCIClientWrapper, filter_spec: str) -> list[Tool]:
+        """
+        Apply a filter specification to get filtered tools.
+
+        This method parses the filter specification and applies the appropriate
+        MCIClient filtering method.
+
+        Args:
+            client: MCIClientWrapper instance to apply filters on
+            filter_spec: Filter specification string (e.g., "tags:api,database")
+
+        Returns:
+            Filtered list of Tool objects
+
+        Raises:
+            ValueError: If filter specification is invalid
+
+        Example:
+            >>> wrapper = MCIClientWrapper("mci.json")
+            >>> tools = ToolManager.apply_filter_spec(wrapper, "tags:api,database")
+            >>> print([t.name for t in tools])
+        """
+        filter_type, values = ToolManager.parse_filter_spec(filter_spec)
+
+        # Apply the appropriate filter based on type
+        if filter_type == "only":
+            return client.filter_only(values)
+        elif filter_type == "except":
+            return client.filter_except(values)
+        elif filter_type == "tags":
+            return client.filter_tags(values)
+        elif filter_type == "without-tags":
+            return client.filter_without_tags(values)
+        elif filter_type == "toolsets":
+            return client.filter_toolsets(values)
+        else:
+            # This shouldn't happen if parse_filter_spec validates correctly
+            raise ValueError(f"Unsupported filter type: '{filter_type}'")

mci/core/validator.py

@@ -0,0 +1,162 @@
+"""
+validator.py - Schema validation logic using mci-py
+
+This module provides validation functionality for MCI schemas,
+leveraging mci-py's built-in MCIClient validation and adding
+additional checks for toolset files and MCP command availability.
+"""
+
+import json
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from mci.core.config import MCIConfig
+from mci.utils.error_formatter import ValidationError, ValidationWarning
+
+
+@dataclass
+class ValidationResult:
+    """
+    Result of validating an MCI schema.
+
+    Attributes:
+        errors: List of validation errors from MCIClient
+        warnings: List of validation warnings from additional checks
+        is_valid: True if no errors were found (warnings are OK)
+    """
+
+    errors: list[ValidationError]
+    warnings: list[ValidationWarning]
+    is_valid: bool
+
+
+class MCIValidator:
+    """
+    Validates MCI schemas using MCIClient and performs additional checks.
+
+    This class uses mci-py's built-in validation via MCIClient and adds
+    extra validation for toolset file existence and MCP command availability.
+    """
+
+    def __init__(self, file_path: str, env_vars: dict[str, str] | None = None):
+        """
+        Initialize the validator.
+
+        Args:
+            file_path: Path to the MCI schema file to validate
+            env_vars: Optional environment variables for template substitution
+        """
+        self.file_path: str = file_path
+        self.env_vars: dict[str, str] = env_vars or {}
+        self.schema_data: dict[str, Any] | None = None
+
+    def validate_schema(self) -> ValidationResult:
+        """
+        Validate the MCI schema file using MCIClient.
+
+        This method uses MCIConfig.validate_schema which wraps MCIClient
+        validation. It then performs additional checks for toolset files
+        and MCP commands.
+
+        Returns:
+            ValidationResult with errors, warnings, and validity status
+
+        Example:
+            >>> validator = MCIValidator("mci.json")
+            >>> result = validator.validate_schema()
+            >>> if not result.is_valid:
+            ...     print("Schema has errors!")
+        """
+        errors: list[ValidationError] = []
+        warnings: list[ValidationWarning] = []
+
+        # First, validate using MCIClient (primary validation)
+        config = MCIConfig()
+        is_valid, error_message = config.validate_schema(self.file_path, self.env_vars)
+
+        if not is_valid:
+            # Parse the error message from MCIClient
+            errors.append(ValidationError(message=error_message))
+            # If schema is invalid, we can't perform additional checks
+            return ValidationResult(errors=errors, warnings=warnings, is_valid=False)
+
+        # Load schema data for additional checks
+        try:
+            self._load_schema_data()
+        except Exception as e:
+            errors.append(ValidationError(message=f"Failed to load schema data: {str(e)}"))
+            return ValidationResult(errors=errors, warnings=warnings, is_valid=False)
+
+        # Perform additional checks for MCP commands (as warnings)
+        mcp_warnings = self.check_mcp_commands()
+        warnings.extend(mcp_warnings)
+
+        return ValidationResult(errors=errors, warnings=warnings, is_valid=True)
+
+    def _load_schema_data(self) -> None:
+        """
+        Load the raw schema data from the file.
+
+        This is used for additional validation checks beyond what MCIClient provides.
+
+        Raises:
+            Exception: If the file cannot be loaded or parsed
+        """
+        file_path = Path(self.file_path)
+
+        if not file_path.exists():
+            raise FileNotFoundError(f"Schema file not found: {self.file_path}")
+
+        with open(file_path) as f:
+            if file_path.suffix == ".json":
+                self.schema_data = json.load(f)
+            elif file_path.suffix in [".yaml", ".yml"]:
+                self.schema_data = yaml.safe_load(f)
+            else:
+                raise ValueError(f"Unsupported file format: {file_path.suffix}")
+
+    def check_mcp_commands(self) -> list[ValidationWarning]:
+        """
+        Check that MCP server commands are available in PATH.
+
+        Returns:
+            List of ValidationWarning for missing MCP commands
+
+        Example:
+            >>> validator = MCIValidator("mci.json")
+            >>> validator._load_schema_data()
+            >>> warnings = validator.check_mcp_commands()
+        """
+        warnings: list[ValidationWarning] = []
+
+        if not self.schema_data:
+            return warnings
+
+        mcp_servers = self.schema_data.get("mcp_servers", {})
+        if not mcp_servers:
+            return warnings
+
+        # Type narrowing: guard against invalid schema data where mcp_servers
+        # might not be a dict (in case it passed MCIClient validation but has unexpected type)
+        if not isinstance(mcp_servers, dict):
+            return warnings
+
+        for server_name, server_config in mcp_servers.items():
+            if isinstance(server_config, dict):
+                command = server_config.get("command")
+                if command:
+                    # Check if command is available in PATH
+                    # Ensure command is a string (not PathLike) to avoid deprecation warning
+                    if not shutil.which(str(command)):
+                        warnings.append(
+                            ValidationWarning(
+                                message=f"MCP server command not found in PATH: {command} (server: {server_name})",
+                                suggestion="Install the command or ensure it's in your PATH",
+                            )
+                        )
+
+        return warnings