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

mci/cli/formatters/json_formatter.py

@@ -0,0 +1,93 @@
+"""
+json_formatter.py - JSON formatter for file output
+
+This module provides formatting for outputting tools to JSON files
+with metadata including timestamp, source file, filters, and tool count.
+"""
+
+import json
+from typing import Any
+
+from mcipy.models import Tool
+
+from mci.utils.timestamp import generate_timestamp_filename, get_iso_timestamp
+
+
+class JSONFormatter:
+    """
+    Formats tool information as JSON files with metadata.
+
+    This class provides methods to format tool lists into JSON files
+    with timestamp, source file, filters applied, and total count.
+    """
+
+    @staticmethod
+    def format_to_file(
+        tools: list[Tool],
+        mci_file: str,
+        filters_applied: list[str] | None = None,
+        verbose: bool = False,
+    ) -> str:
+        """
+        Format tools to a JSON file and return the filename.
+
+        Creates a timestamped JSON file with tool data and metadata.
+        Filename format: tools_YYYYMMDD_HHMMSS.json
+
+        Args:
+            tools: List of Tool objects to format
+            mci_file: Path to the source MCI file
+            filters_applied: Optional list of filter specifications that were applied
+            verbose: Whether to include verbose tool metadata
+
+        Returns:
+            The filename of the created JSON file
+
+        Example:
+            >>> formatter = JSONFormatter()
+            >>> filename = formatter.format_to_file(tools, "mci.json", ["tags:api"])
+            >>> print(filename)
+            tools_20241029_143022.json
+        """
+        # Generate timestamped filename
+        filename = generate_timestamp_filename("json")
+
+        # Build output data structure
+        output_data: dict[str, Any] = {
+            "timestamp": get_iso_timestamp(),
+            "mci_file": mci_file,
+            "filters_applied": filters_applied or [],
+            "total": len(tools),
+            "tools": [],
+        }
+
+        # Format each tool
+        for tool in tools:
+            tool_data: dict[str, str | list[str] | dict[str, Any] | bool] = {
+                "name": tool.name,
+                "source": tool.toolset_source or "main",
+                "description": tool.description or "",
+            }
+
+            # Add verbose fields if requested
+            if verbose:
+                tool_data["tags"] = tool.tags
+                tool_data["execution_type"] = (
+                    tool.execution.type.value
+                    if hasattr(tool.execution.type, "value")
+                    else str(tool.execution.type)
+                )
+
+                if tool.inputSchema:
+                    tool_data["inputSchema"] = tool.inputSchema
+
+                if tool.disabled:
+                    tool_data["disabled"] = tool.disabled
+
+            output_data["tools"].append(tool_data)
+
+        # Write to file
+        with open(filename, "w") as f:
+            json.dump(output_data, f, indent=2)
+
+        return filename

mci/cli/formatters/table_formatter.py

@@ -0,0 +1,138 @@
+"""
+table_formatter.py - Rich table formatter for CLI output
+
+This module provides formatting for displaying tools in Rich terminal tables
+with support for both basic and verbose output modes.
+"""
+
+from mcipy.models import Tool
+from rich.markup import escape
+from rich.table import Table
+
+
+class TableFormatter:
+    """
+    Formats tool information as Rich terminal tables.
+
+    This class provides methods to format tool lists into beautiful
+    terminal tables using the Rich library, with support for both
+    basic and verbose output modes.
+    """
+
+    @staticmethod
+    def format(tools: list[Tool], verbose: bool = False) -> Table | list[str]:
+        """
+        Format tools as a Rich table.
+
+        Args:
+            tools: List of Tool objects to format
+            verbose: Whether to show verbose output with additional metadata
+
+        Returns:
+            Rich Table object (basic mode) or list of Rich markup strings (verbose mode)
+
+        Example:
+            >>> formatter = TableFormatter()
+            >>> output = formatter.format(tools, verbose=False)
+            >>> print(output)
+        """
+        if verbose:
+            return TableFormatter.format_verbose(tools)
+        else:
+            return TableFormatter.format_basic(tools)
+
+    @staticmethod
+    def format_basic(tools: list[Tool]) -> Table:
+        """
+        Format tools in basic table mode.
+
+        Displays a table with columns: Name, Source, Description
+
+        Args:
+            tools: List of Tool objects to format
+
+        Returns:
+            Rich Table object ready for rendering
+        """
+        # Create table
+        table = Table(
+            title=f"🧩 Available Tools ({len(tools)})",
+            show_header=True,
+            header_style="bold cyan",
+        )
+
+        table.add_column("Name", style="green", no_wrap=True)
+        table.add_column("Source", style="blue")
+        table.add_column("Description", style="white")
+
+        # Add rows
+        for tool in tools:
+            name = tool.name
+            source = tool.toolset_source or "main"
+            description = tool.description or ""
+
+            table.add_row(name, source, description)
+
+        return table
+
+    @staticmethod
+    def format_verbose(tools: list[Tool]) -> list[str]:
+        """
+        Format tools in verbose mode with detailed information.
+
+        Shows detailed information for each tool including tags,
+        parameters, execution type, and other metadata.
+
+        Args:
+            tools: List of Tool objects to format
+
+        Returns:
+            List of formatted output lines with Rich markup
+        """
+        output_lines: list[str] = []
+
+        output_lines.append(f"🧩 Available Tools ({len(tools)}):\n")
+
+        for tool in tools:
+            # Tool header
+            source = tool.toolset_source or "main"
+            output_lines.append(f"[bold green]{tool.name}[/bold green] [blue]({source})[/blue]")
+
+            # Description
+            if tool.description:
+                output_lines.append(f"├── Description: {tool.description}")
+
+            # Tags
+            if tool.tags:
+                tags_str = ", ".join(tool.tags)
+                # Escape the brackets and content to prevent Rich markup interpretation
+                output_lines.append(f"├── Tags: {escape(f'[{tags_str}]')}")
+
+            # Execution type
+            execution_type = (
+                tool.execution.type.value
+                if hasattr(tool.execution.type, "value")
+                else str(tool.execution.type)
+            )
+            output_lines.append(f"├── Execution: {execution_type}")
+
+            # Parameters from inputSchema
+            if tool.inputSchema and "properties" in tool.inputSchema:
+                params = tool.inputSchema["properties"]
+                required = tool.inputSchema.get("required", [])
+
+                param_strs = []
+                for param_name, param_def in params.items():
+                    param_type = param_def.get("type", "any")
+                    is_required = param_name in required
+                    req_indicator = "" if is_required else " (optional)"
+                    param_strs.append(f"{param_name} ({param_type}){req_indicator}")
+
+                if param_strs:
+                    output_lines.append(f"└── Parameters: {', '.join(param_strs)}")
+            else:
+                output_lines.append("└── Parameters: none")
+
+            output_lines.append("")  # Empty line between tools
+
+        return output_lines

mci/cli/formatters/yaml_formatter.py

@@ -0,0 +1,93 @@
+"""
+yaml_formatter.py - YAML formatter for file output
+
+This module provides formatting for outputting tools to YAML files
+with metadata including timestamp, source file, filters, and tool count.
+"""
+
+from typing import Any
+
+import yaml
+from mcipy.models import Tool
+
+from mci.utils.timestamp import generate_timestamp_filename, get_iso_timestamp
+
+
+class YAMLFormatter:
+    """
+    Formats tool information as YAML files with metadata.
+
+    This class provides methods to format tool lists into YAML files
+    with timestamp, source file, filters applied, and total count.
+    """
+
+    @staticmethod
+    def format_to_file(
+        tools: list[Tool],
+        mci_file: str,
+        filters_applied: list[str] | None = None,
+        verbose: bool = False,
+    ) -> str:
+        """
+        Format tools to a YAML file and return the filename.
+
+        Creates a timestamped YAML file with tool data and metadata.
+        Filename format: tools_YYYYMMDD_HHMMSS.yaml
+
+        Args:
+            tools: List of Tool objects to format
+            mci_file: Path to the source MCI file
+            filters_applied: Optional list of filter specifications that were applied
+            verbose: Whether to include verbose tool metadata
+
+        Returns:
+            The filename of the created YAML file
+
+        Example:
+            >>> formatter = YAMLFormatter()
+            >>> filename = formatter.format_to_file(tools, "mci.json", ["tags:api"])
+            >>> print(filename)
+            tools_20241029_143022.yaml
+        """
+        # Generate timestamped filename
+        filename = generate_timestamp_filename("yaml")
+
+        # Build output data structure
+        output_data: dict[str, Any] = {
+            "timestamp": get_iso_timestamp(),
+            "mci_file": mci_file,
+            "filters_applied": filters_applied or [],
+            "total": len(tools),
+            "tools": [],
+        }
+
+        # Format each tool
+        for tool in tools:
+            tool_data: dict[str, str | list[str] | dict[str, Any] | bool] = {
+                "name": tool.name,
+                "source": tool.toolset_source or "main",
+                "description": tool.description or "",
+            }
+
+            # Add verbose fields if requested
+            if verbose:
+                tool_data["tags"] = tool.tags
+                tool_data["execution_type"] = (
+                    tool.execution.type.value
+                    if hasattr(tool.execution.type, "value")
+                    else str(tool.execution.type)
+                )
+
+                if tool.inputSchema:
+                    tool_data["inputSchema"] = tool.inputSchema
+
+                if tool.disabled:
+                    tool_data["disabled"] = tool.disabled
+
+            output_data["tools"].append(tool_data)
+
+        # Write to file
+        with open(filename, "w") as f:
+            yaml.dump(output_data, f, default_flow_style=False, sort_keys=False)
+
+        return filename

mci/cli/install.py

@@ -0,0 +1,147 @@
+"""
+install.py - CLI command for initializing MCI project structure
+
+This module provides the 'install' command which creates a new MCI project
+by copying template files and setting up the directory structure.
+"""
+
+from importlib.resources import files
+from pathlib import Path
+
+import click
+
+
+def copy_asset(resource_name: str, dest_path: Path, overwrite: bool = False) -> bool:
+    """
+    Copy an asset file from the package to a destination path.
+
+    Args:
+        resource_name: Name of the asset file in src/mci/assets/
+        dest_path: Destination path to copy the file to
+        overwrite: Whether to overwrite existing files (default: False)
+
+    Returns:
+        True if file was copied, False if it already existed and overwrite=False
+    """
+    if dest_path.exists() and not overwrite:
+        return False
+
+    # Get the asset file content using importlib.resources
+    asset_files = files("mci.assets")
+    asset_file = asset_files.joinpath(resource_name)
+
+    # Read the asset content and write to destination
+    content = asset_file.read_text()
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+    dest_path.write_text(content)
+
+    return True
+
+
+def create_mci_file(format: str = "json") -> None:
+    """
+    Create the main MCI configuration file (mci.json or mci.yaml).
+
+    Args:
+        format: File format, either "json" or "yaml"
+    """
+    if format == "yaml":
+        filename = "mci.yaml"
+        asset_name = "mci.yaml"
+    else:
+        filename = "mci.json"
+        asset_name = "mci.json"
+
+    dest_path = Path.cwd() / filename
+
+    if copy_asset(asset_name, dest_path):
+        click.echo(f"✓ Created {filename}")
+    else:
+        click.echo(f"⚠ {filename} already exists, skipping")
+
+
+def create_mci_directory() -> None:
+    """
+    Create the ./mci/ directory and update .gitignore.
+    """
+    mci_dir = Path.cwd() / "mci"
+    mci_dir.mkdir(exist_ok=True)
+    click.echo("✓ Created ./mci/ directory")
+
+    # Create or update .gitignore
+    gitignore_path = mci_dir / ".gitignore"
+
+    if gitignore_path.exists():
+        # Check if 'mcp/' already exists in .gitignore
+        content = gitignore_path.read_text()
+        if "mcp/" not in content:
+            # Append mcp/ entry
+            with gitignore_path.open("a") as f:
+                if not content.endswith("\n"):
+                    f.write("\n")
+                f.write("mcp/\n")
+            click.echo("✓ Updated ./mci/.gitignore with mcp/ entry")
+        else:
+            click.echo("⚠ ./mci/.gitignore already contains mcp/ entry, skipping")
+    else:
+        # Create new .gitignore from template
+        copy_asset("gitignore", gitignore_path, overwrite=True)
+        click.echo("✓ Created ./mci/.gitignore")
+
+
+def create_example_toolset(format: str = "json") -> None:
+    """
+    Create the example toolset file in ./mci/ directory.
+
+    Args:
+        format: File format, either "json" or "yaml"
+    """
+    if format == "yaml":
+        filename = "example_toolset.mci.yaml"
+        asset_name = "example_toolset.mci.yaml"
+    else:
+        filename = "example_toolset.mci.json"
+        asset_name = "example_toolset.mci.json"
+
+    dest_path = Path.cwd() / "mci" / filename
+
+    if copy_asset(asset_name, dest_path):
+        click.echo(f"✓ Created ./mci/{filename}")
+    else:
+        click.echo(f"⚠ ./mci/{filename} already exists, skipping")
+
+
+@click.command()
+@click.option(
+    "--yaml",
+    is_flag=True,
+    help="Create YAML configuration file instead of JSON",
+)
+def install(yaml: bool):
+    """
+    Initialize an MCI project structure.
+
+    Creates mci.json (or mci.yaml with --yaml flag), ./mci/ directory,
+    example toolset file, and .gitignore configuration.
+    """
+    click.echo("Initializing MCI project...")
+    click.echo()
+
+    format = "yaml" if yaml else "json"
+
+    # Create main configuration file
+    create_mci_file(format=format)
+
+    # Create ./mci directory and .gitignore
+    create_mci_directory()
+
+    # Create example toolset
+    create_example_toolset(format=format)
+
+    click.echo()
+    click.echo("✓ MCI project initialized successfully!")
+    click.echo()
+    click.echo("Next steps:")
+    click.echo("  1. Review the generated configuration files")
+    click.echo("  2. Run 'mcix list' to see available tools")
+    click.echo("  3. Run 'mcix validate' to check your configuration")

mci/cli/list.py

@@ -0,0 +1,153 @@
+"""
+list.py - List command for displaying available tools
+
+This module implements the `list` command for the MCI CLI, which displays
+all available tools in the current MCI configuration with support for
+filtering, multiple output formats, and verbose mode.
+"""
+
+import click
+from mcipy import MCIClientError
+from rich.console import Console
+
+from mci.cli.formatters import JSONFormatter, TableFormatter, YAMLFormatter
+from mci.core.file_finder import MCIFileFinder
+from mci.core.mci_client import MCIClientWrapper
+from mci.core.tool_manager import ToolManager
+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)",
+)
+@click.option(
+    "--format",
+    type=click.Choice(["table", "json", "yaml"], case_sensitive=False),
+    default="table",
+    help="Output format (default: table)",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Show detailed tool information including tags, parameters, etc.",
+)
+def list_command(file: str | None, filter: str | None, format: str, verbose: bool):
+    """
+    List available tools from the MCI configuration.
+
+    Displays all tools defined in the MCI schema file, with support for
+    filtering, multiple output formats (table, JSON, YAML), and verbose mode.
+
+    The list command uses the same tool loading and filtering logic as the
+    run command, ensuring consistency between what is listed and what will
+    actually be available when running the MCP server.
+
+    Examples:
+
+        # List all tools in table format
+        mcix list
+
+        # List tools from specific file
+        mcix list --file=./custom.mci.json
+
+        # List tools with filter
+        mcix list --filter=tags:api,database
+
+        # List tools with verbose output
+        mcix list --verbose
+
+        # Export tools to JSON file
+        mcix list --format=json
+
+        # Export tools to YAML file with verbose info
+        mcix list --format=yaml --verbose
+    """
+    console = Console()
+
+    try:
+        # 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()
+
+        # Load schema using MCIClientWrapper
+        try:
+            client = MCIClientWrapper(file)
+        except MCIClientError as e:
+            console.print(ErrorHandler.format_mci_client_error(e))
+            raise click.Abort() from e
+        except Exception as e:
+            console.print(ErrorHandler.format_generic_error(e))
+            raise click.Abort() from e
+
+        # Get tools (with or without filter)
+        if filter:
+            try:
+                tools = ToolManager.apply_filter_spec(client, filter)
+            except ValueError as e:
+                console.print(f"[red]✗[/red] Invalid filter: {e}", style="red")
+                raise click.Abort() from e
+        else:
+            tools = client.get_tools()
+
+        # Format and display output
+        if format == "table":
+            # Display table to console
+            output = TableFormatter.format(tools, verbose=verbose)
+            if isinstance(output, list):
+                # Verbose mode returns list of Rich markup strings
+                for line in output:
+                    console.print(line)
+            else:
+                # Basic mode returns a Table object
+                console.print(output)
+
+        elif format == "json":
+            # Write to JSON file
+            filters_applied = [filter] if filter else []
+            filename = JSONFormatter.format_to_file(
+                tools=tools,
+                mci_file=file,
+                filters_applied=filters_applied,
+                verbose=verbose,
+            )
+            console.print(f"[green]✓[/green] Tools exported to: {filename}")
+
+        elif format == "yaml":
+            # Write to YAML file
+            filters_applied = [filter] if filter else []
+            filename = YAMLFormatter.format_to_file(
+                tools=tools,
+                mci_file=file,
+                filters_applied=filters_applied,
+                verbose=verbose,
+            )
+            console.print(f"[green]✓[/green] Tools exported to: {filename}")
+
+    except click.Abort:
+        raise
+    except MCIClientError as e:
+        console.print(ErrorHandler.format_mci_client_error(e))
+        raise click.Abort() from e
+    except Exception as e:
+        console.print(ErrorHandler.format_generic_error(e))
+        raise click.Abort() from e