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

iflow_mcp_modelcontextinterface_mcix-1.1.1.dev0.dist-info/RECORD

@@ -0,0 +1,42 @@
+mci/__init__.py,sha256=nuemO6CcSJn9t-0Ah57JVcbIkzSFEZPjYWTfHC3nbkI,204
+mci/mci.py,sha256=Xw3ibISXDPtLaz3RGMk1WqPODbByyijRXceXOXWUNIw,909
+mci/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mci/assets/example_toolset.mci.json,sha256=oNxS_QxfScOJWjBr3JmNeNGoScquDPzZ8zBVh-qr7qo,770
+mci/assets/example_toolset.mci.yaml,sha256=WS8pIf4t5VIEbp0aWLeGw0S31KwgGHBY7RuaYAluLbw,541
+mci/assets/gitignore,sha256=l6yi4sEzheFyEHHK6oHzm9nP2DIZjrwXfMVOIGsjxG0,5
+mci/assets/mci.json,sha256=GgFiQJ3EtL7NVtMVwoleFKU-H71WCEEYXY283s4WIYk,600
+mci/assets/mci.yaml,sha256=B95JmmzjUgYOSW2s6AFWMkQo9jc6dX7LGhZ33QRkSgk,420
+mci/cli/__init__.py,sha256=N6bvmpH2Wrn5HXELYEQ7H7QDmAknL0ih_WCUfcWDvCs,190
+mci/cli/add.py,sha256=6FeuGQTLZs23A8_ZReJryk7LAPey-L8z4ZVEKPQVbIQ,3217
+mci/cli/envs.py,sha256=WTgkszkdg5-B5JMZ7gDA4TgU-H7z7Ov6RpH2d2pyQyg,8860
+mci/cli/install.py,sha256=NDQnNvgzPJlSQnQ_RLnVy19dIonEYbJEvZoxYidw08o,4359
+mci/cli/list.py,sha256=o7hyb9iNZ9fKO7vKLY4HhpaVcC_n8xuwSO6WHVOw3O4,5018
+mci/cli/run.py,sha256=0a1Vj413_XzCgtX0Mky1-K6uIQgaYC2ZMv1BIsJjJQk,4101
+mci/cli/validate.py,sha256=qit0lpz0YkGAArPUCrQA1_vOtPQhlrll3IvCDXq1hcM,3409
+mci/cli/formatters/__init__.py,sha256=mijJRgrkNYkoLHztNUM3ezskwmhOZtHCGogFjxW7fq4,435
+mci/cli/formatters/env_formatter.py,sha256=zuL76kTzV7Kph58QvTlQNpAlxYhOmn-tfg70z9E5n9Y,2674
+mci/cli/formatters/json_formatter.py,sha256=Sopuw7eYP-0eakUlat_5o1F82AkbUAKgzA_qwOOvNjE,2919
+mci/cli/formatters/table_formatter.py,sha256=kV73T5phFlLe468X4PAfpTiFvzKMZq6iKri1ZIJ70Gc,4541
+mci/cli/formatters/yaml_formatter.py,sha256=0_G2jE2zIXnun7mlU9cQzUUsztqZMhUVkqt22tiCohw,2952
+mci/core/__init__.py,sha256=nuCREJL3nCOQi5IQKVyL1swl_xrz7QPdUOO6Ju_K2Vc,187
+mci/core/config.py,sha256=3oiJz9bjfympXZsDwisZZrKLY1hb_1rb7ERGil3YOYM,5869
+mci/core/dynamic_server.py,sha256=5nnTO8LadRJdjCA4zRJ0qZIHBXFTY7TSX3JLZByECXU,6977
+mci/core/file_finder.py,sha256=nB0TVV5kSqYzVp04KCE_q0n4xabudowFWNQkvQ7H0pg,3226
+mci/core/mci_client.py,sha256=k8lTBcEbw830TcQEEWI3PiD7-WgugOY6y6ZxZnZU8kE,6797
+mci/core/mcp_server.py,sha256=csIkKv9bMaecAR2hu-7p_Jht3QHZs6xPIqiSVTI5YR4,8453
+mci/core/schema_editor.py,sha256=uYrHgcdz3vLagjNjKxPuVt1Rt615NLYgMQCo86xhZM4,10065
+mci/core/tool_converter.py,sha256=xRluMABCB9whdy_Y0ncug9FpbumnpkxC7_9_n2KN2S4,4491
+mci/core/tool_manager.py,sha256=eAggVfC6sAxwYhAfkNbK-FnJBpySRvOEx5GGMLLyZF4,4438
+mci/core/validator.py,sha256=7b5mt2uP0ko2nUWGHStB4sKNicTRrwJEMPcx0CBEYmo,5746
+mci/utils/__init__.py,sha256=b_nmqu4_AAAq3D5p9njpkXj8y9oU_-MyLMFBYhQmAII,179
+mci/utils/dotenv.py,sha256=XBUhGcQtHQ8hJFoM9NlY0bxTMDUqqkI7zdzCYe73s4w,6181
+mci/utils/env_scanner.py,sha256=7W00ov1DuWaxD6j6M56pXb0SqQdYaA_EeCSAzyVt77Q,2599
+mci/utils/error_formatter.py,sha256=TOs6CT3SAcBWUycjn1er6Tzp6kJkAB_5u_vYfZ5VRJw,5093
+mci/utils/error_handler.py,sha256=ybv_JpHDTqW8Zmm4Vv2MyQGzJ20T1hMbe7D5UwM4nCw,5899
+mci/utils/timestamp.py,sha256=AxRpVv9cTQByduDOJYEYtRZl2XGdrAtCZtdvb2oQXP0,1341
+mci/utils/validation.py,sha256=qKI3tn8oZzDRVP0qrMhPnMJSYjEi2XTj_1b28Ly0WG8,1806
+iflow_mcp_modelcontextinterface_mcix-1.1.1.dev0.dist-info/METADATA,sha256=u1tAv0pcLi-YrUK4VMP0DZShVRtTqTvLscjOPIShJC8,25157
+iflow_mcp_modelcontextinterface_mcix-1.1.1.dev0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+iflow_mcp_modelcontextinterface_mcix-1.1.1.dev0.dist-info/entry_points.txt,sha256=5d6RSblyFS_5gbD524eS-tJEUzQQ8C2mUugZVnkTKbU,34
+iflow_mcp_modelcontextinterface_mcix-1.1.1.dev0.dist-info/licenses/LICENSE,sha256=tMFywLM9365292nkpvJgJTcleQn_ABNSELN5YMV2dzo,1069
+iflow_mcp_modelcontextinterface_mcix-1.1.1.dev0.dist-info/RECORD,,

iflow_mcp_modelcontextinterface_mcix-1.1.1.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

iflow_mcp_modelcontextinterface_mcix-1.1.1.dev0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcix = mci:main

iflow_mcp_modelcontextinterface_mcix-1.1.1.dev0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 maestroerror
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mci/__init__.py

@@ -0,0 +1,10 @@
+"""
+MCI CLI Package
+
+This package provides a command-line interface for managing Model Context Interface (MCI)
+schemas and dynamically running MCP servers.
+"""
+
+from .mci import main
+
+__all__ = ("main",)

mci/assets/example_toolset.mci.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": "1.0",
+  "metadata": {
+    "name": "Example Toolset",
+    "description": "Example MCI toolset with CLI tool"
+  },
+  "tools": [
+    {
+      "name": "list_files",
+      "description": "List files in a directory",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "directory": {
+            "type": "string",
+            "description": "Directory to list files from"
+          }
+        },
+        "required": [
+          "directory"
+        ]
+      },
+      "execution": {
+        "type": "cli",
+        "command": "ls",
+        "args": [
+          "-la",
+          "{{props.directory}}"
+        ]
+      },
+      "enableAnyPaths": false,
+      "directoryAllowList": [
+        "{{env.PROJECT_ROOT}}"
+      ]
+    }
+  ]
+}

mci/assets/example_toolset.mci.yaml

@@ -0,0 +1,23 @@
+schemaVersion: '1.0'
+metadata:
+  name: Example Toolset
+  description: Example MCI toolset with CLI tool
+tools:
+  - name: list_files
+    description: List files in a directory
+    inputSchema:
+      type: object
+      properties:
+        directory:
+          type: string
+          description: Directory to list files from
+      required: [directory]
+    execution:
+      type: cli
+      command: ls
+      args:
+        - '-la'
+        - '{{props.directory}}'
+    enableAnyPaths: false
+    directoryAllowList:
+      - '{{env.PROJECT_ROOT}}'

mci/assets/gitignore

@@ -0,0 +1 @@
+mcp/

mci/assets/mci.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "1.0",
+  "metadata": {
+    "name": "Example Project",
+    "description": "Example MCI configuration"
+  },
+  "tools": [
+    {
+      "name": "echo_test",
+      "description": "Simple echo test tool",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "Message to echo"
+          }
+        },
+        "required": ["message"]
+      },
+      "execution": {
+        "type": "text",
+        "text": "Echo: {{props.message}}"
+      }
+    }
+  ],
+  "toolsets": [],
+  "mcp_servers": {}
+}

mci/assets/mci.yaml

@@ -0,0 +1,19 @@
+schemaVersion: '1.0'
+metadata:
+  name: Example Project
+  description: Example MCI configuration
+tools:
+  - name: echo_test
+    description: Simple echo test tool
+    inputSchema:
+      type: object
+      properties:
+        message:
+          type: string
+          description: Message to echo
+      required: [message]
+    execution:
+      type: text
+      text: 'Echo: {{props.message}}'
+toolsets: []
+mcp_servers: {}

mci/cli/__init__.py

@@ -0,0 +1,8 @@
+"""
+CLI command modules for the MCI CLI Tool.
+
+This package contains all command implementations for the MCI CLI,
+including install, list, validate, add, and run commands.
+"""
+
+__all__ = ()

mci/cli/add.py

@@ -0,0 +1,108 @@
+"""
+add.py - CLI command to add toolset references to MCI schemas
+
+This module provides the `mcix add` command which adds toolset references
+to MCI schema files with optional filtering, while preserving the original
+file format (JSON or YAML).
+"""
+
+import sys
+
+import click
+from rich.console import Console
+
+from mci.core.file_finder import MCIFileFinder
+from mci.core.schema_editor import SchemaEditor, parse_add_filter
+
+
+@click.command()
+@click.argument("toolset_name", type=str)
+@click.option(
+    "--filter",
+    "-f",
+    default=None,
+    help='Filter specification (e.g., "only:Tool1,Tool2" or "tags:api,database")',
+)
+@click.option(
+    "--path",
+    "-p",
+    default=None,
+    help="Path to MCI schema file (default: auto-discover mci.json/mci.yaml)",
+)
+def add(toolset_name: str, filter: str | None, path: str | None) -> None:
+    """
+    Add a toolset reference to an MCI schema file.
+
+    This command adds a toolset to the schema's toolsets array. If the toolset
+    already exists, it will be updated with the new filter (if provided).
+    The original file format (JSON or YAML) is preserved.
+
+    TOOLSET_NAME is the name of the toolset to add.
+
+    Examples:
+
+        \b
+        # Add a toolset without filter
+        mcix add weather-tools
+
+        \b
+        # Add a toolset with "only" filter
+        mcix add analytics --filter=only:Tool1,Tool2
+
+        \b
+        # Add a toolset with "tags" filter
+        mcix add api-tools --filter=tags:api,database
+
+        \b
+        # Add to a custom file
+        mcix add weather-tools --path=custom.mci.json
+    """
+    console = Console()
+
+    # Find the schema file
+    if path is None:
+        file_finder = MCIFileFinder()
+        schema_file = file_finder.find_mci_file()
+        if schema_file is None:
+            console.print("[red]❌ No MCI schema file found in current directory[/red]\n")
+            console.print("[yellow]💡 Run 'mcix install' to create a default mci.json file[/yellow]")
+            sys.exit(1)
+    else:
+        schema_file = path
+
+    # Parse filter specification if provided
+    filter_type = None
+    filter_value = None
+    if filter:
+        try:
+            filter_type, filter_value = parse_add_filter(filter)
+        except ValueError as e:
+            console.print(f"[red]❌ Invalid filter specification: {e}[/red]\n")
+            sys.exit(1)
+
+    # Load, modify, and save the schema
+    editor = SchemaEditor()
+    try:
+        editor.load_schema(schema_file)
+        editor.add_toolset(toolset_name, filter_type, filter_value)
+        editor.save_schema()
+
+        # Display success message
+        console.print(f"[green]✅ Added toolset '{toolset_name}' to {schema_file}[/green]")
+        if filter_type and filter_value:
+            console.print(f"[dim]   Filter: {filter_type}:{filter_value}[/dim]")
+
+    except FileNotFoundError as e:
+        console.print(f"[red]❌ File not found: {e}[/red]\n")
+        sys.exit(1)
+    except ValueError as e:
+        console.print(f"[red]❌ Error: {e}[/red]\n")
+        sys.exit(1)
+    except Exception as e:
+        console.print(f"[red]❌ Unexpected error: {e}[/red]\n")
+        sys.exit(1)
+
+
+# Allow running as script
+if __name__ == "__main__":
+    add()

mci/cli/envs.py

@@ -0,0 +1,257 @@
+"""
+envs.py - Environment variables command for displaying required env vars
+
+This module implements the `envs` command for the MCI CLI, which scans
+the MCI configuration and displays all environment variables referenced
+in templates across tools, toolsets, and MCP servers.
+"""
+
+import json
+from pathlib import Path
+
+import click
+import yaml
+from mcipy import MCIClientError
+from rich.console import Console
+from rich.table import Table
+
+from mci.cli.formatters.env_formatter import EnvFormatter
+from mci.core.file_finder import MCIFileFinder
+from mci.utils.env_scanner import EnvScanner
+from mci.utils.error_handler import ErrorHandler
+
+
+def extract_env_vars_from_schema(schema_path: str) -> dict[str, list[str]]:
+    """
+    Extract all environment variables from a schema file and its referenced files.
+
+    This function loads the main schema file and scans it along with all
+    referenced toolsets and MCP servers to find environment variable references.
+
+    Args:
+        schema_path: Path to the main MCI schema file
+
+    Returns:
+        Dictionary mapping variable names to list of locations where used
+        (e.g., {"API_KEY": ["main", "weather-toolset"]})
+
+    Raises:
+        FileNotFoundError: If schema file or referenced files are not found
+        ValueError: If schema file is invalid
+    """
+    env_vars: dict[str, set[str]] = {}
+    schema_dir = Path(schema_path).parent.resolve()
+
+    # Load main schema
+    with open(schema_path) as f:
+        if schema_path.endswith((".yaml", ".yml")):
+            main_schema = yaml.safe_load(f)
+        else:
+            main_schema = json.load(f)
+
+    # Scan main schema (excluding mcp_servers which we'll scan separately)
+    main_schema_without_mcp = {k: v for k, v in main_schema.items() if k != "mcp_servers"}
+    main_env_vars = EnvScanner.scan_dict(main_schema_without_mcp)
+    for var in main_env_vars:
+        if var not in env_vars:
+            env_vars[var] = set()
+        env_vars[var].add("main")
+
+    # Get library directory for toolsets
+    library_dir = main_schema.get("libraryDir", "mci")
+    lib_path = schema_dir / library_dir
+
+    # Scan registered toolsets
+    toolsets = main_schema.get("toolsets", [])
+    for toolset_ref in toolsets:
+        toolset_name = toolset_ref if isinstance(toolset_ref, str) else toolset_ref.get("name")
+        if not toolset_name:
+            continue
+
+        # Try to find toolset file
+        toolset_file = _find_toolset_file(lib_path, toolset_name)
+        if toolset_file:
+            try:
+                with open(toolset_file) as f:
+                    if toolset_file.suffix in {".yaml", ".yml"}:
+                        toolset_schema = yaml.safe_load(f)
+                    else:
+                        toolset_schema = json.load(f)
+
+                # Scan toolset
+                toolset_env_vars = EnvScanner.scan_dict(toolset_schema)
+                for var in toolset_env_vars:
+                    if var not in env_vars:
+                        env_vars[var] = set()
+                    env_vars[var].add(toolset_name)
+            except Exception as e:
+                # Warn but continue if toolset file is invalid
+                console = Console()
+                console.print(
+                    f"[yellow]⚠[/yellow] Warning: Could not load toolset '{toolset_name}': {e}",
+                    style="yellow",
+                )
+
+    # Scan MCP servers
+    mcp_servers = main_schema.get("mcp_servers", {})
+    if isinstance(mcp_servers, dict):
+        for server_name, server_config in mcp_servers.items():
+            if isinstance(server_config, dict):
+                server_env_vars = EnvScanner.scan_dict(server_config)
+                for var in server_env_vars:
+                    if var not in env_vars:
+                        env_vars[var] = set()
+                    env_vars[var].add(f"mcp:{server_name}")
+
+    # Convert sets to sorted lists
+    result = {var: sorted(locations) for var, locations in env_vars.items()}
+    return result
+
+
+def _find_toolset_file(lib_path: Path, toolset_name: str) -> Path | None:
+    """
+    Find a toolset file in the library directory.
+
+    Args:
+        lib_path: Path to the library directory
+        toolset_name: Name of the toolset
+
+    Returns:
+        Path to the toolset file if found, None otherwise
+    """
+    if not lib_path.exists():
+        return None
+
+    # Try various file patterns
+    patterns = [
+        f"{toolset_name}.mci.json",
+        f"{toolset_name}.mci.yaml",
+        f"{toolset_name}.mci.yml",
+        f"{toolset_name}.json",
+        f"{toolset_name}.yaml",
+        f"{toolset_name}.yml",
+    ]
+
+    for pattern in patterns:
+        file_path = lib_path / pattern
+        if file_path.exists() and file_path.is_file():
+            return file_path
+
+    # Check if it's a directory with a schema file
+    dir_path = lib_path / toolset_name
+    if dir_path.exists() and dir_path.is_dir():
+        for pattern in patterns:
+            file_path = dir_path / pattern
+            if file_path.exists() and file_path.is_file():
+                return file_path
+
+    return None
+
+
+@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(
+    "--format",
+    type=click.Choice(["table", "env"], case_sensitive=False),
+    default="table",
+    help="Output format (default: table)",
+)
+def envs_command(file: str | None, format: str):
+    """
+    List all environment variables used in the MCI configuration.
+
+    Scans the main schema file, referenced toolsets, and MCP servers to find
+    all environment variable references in templates ({{env.VARIABLE}}).
+
+    Outputs a list of all required environment variables with their locations,
+    helping you understand what credentials and configuration are needed.
+
+    Examples:
+
+        # Show environment variables in table format
+        mci envs
+
+        # Generate .env.example.mci file
+        mci envs --format=env
+
+        # Scan specific schema file
+        mci envs --file=custom.mci.json
+    """
+    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()
+
+        # Extract environment variables
+        try:
+            env_vars = extract_env_vars_from_schema(file)
+        except FileNotFoundError as e:
+            console.print(f"[red]✗[/red] File not found: {e}", style="red")
+            raise click.Abort() from e
+        except (json.JSONDecodeError, yaml.YAMLError) as e:
+            console.print(f"[red]✗[/red] Invalid schema file: {e}", style="red")
+            raise click.Abort() from e
+        except Exception as e:
+            console.print(ErrorHandler.format_generic_error(e))
+            raise click.Abort() from e
+
+        # Check if any variables were found
+        if not env_vars:
+            if format == "table":
+                console.print("[yellow]ℹ[/yellow] No environment variables found in schema.")
+            else:
+                console.print(
+                    "[yellow]ℹ[/yellow] No environment variables found. Skipping file generation."
+                )
+            return
+
+        # Format and display output
+        if format == "table":
+            # Display table to console
+            table = Table(
+                title=f"🔐 Environment Variables ({len(env_vars)})",
+                show_header=True,
+                header_style="bold cyan",
+            )
+
+            table.add_column("Variable", style="green", no_wrap=True)
+            table.add_column("Used In", style="blue")
+
+            # Sort by variable name
+            for var_name in sorted(env_vars.keys()):
+                locations = env_vars[var_name]
+                locations_str = ", ".join(locations)
+                table.add_row(var_name, locations_str)
+
+            console.print(table)
+
+        elif format == "env":
+            # Write to .env.example.mci file
+            filename = EnvFormatter.format_to_file(env_vars)
+            console.print(f"[green]✓[/green] Environment variables exported to: {filename}")
+            console.print("[dim]Copy this file to .env.mci and fill in your values[/dim]")
+
+    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

mci/cli/formatters/__init__.py

@@ -0,0 +1,12 @@
+"""
+formatters package - Output formatters for CLI commands
+
+This package provides formatters for displaying tool information
+in various formats including Rich tables, JSON, and YAML.
+"""
+
+from mci.cli.formatters.json_formatter import JSONFormatter
+from mci.cli.formatters.table_formatter import TableFormatter
+from mci.cli.formatters.yaml_formatter import YAMLFormatter
+
+__all__ = ["TableFormatter", "JSONFormatter", "YAMLFormatter"]

mci/cli/formatters/env_formatter.py

@@ -0,0 +1,83 @@
+"""
+env_formatter.py - Environment variable file formatter
+
+This module provides formatting for environment variable output in .env file format.
+"""
+
+from pathlib import Path
+
+
+class EnvFormatter:
+    """
+    Formats environment variable information as .env files.
+
+    This formatter generates .env.example.mci files containing all detected
+    environment variables with empty values, suitable for use as templates.
+    """
+
+    @staticmethod
+    def format_to_string(env_vars: dict[str, list[str]]) -> str:
+        """
+        Format environment variables as a string in .env format.
+
+        Args:
+            env_vars: Dictionary mapping variable names to list of locations where used
+
+        Returns:
+            Formatted string in .env format
+
+        Example:
+            >>> env_vars = {"API_KEY": ["main"], "DB_URL": ["database-toolset"]}
+            >>> print(EnvFormatter.format_to_string(env_vars))
+            # .env.example.mci
+            ...
+        """
+        # Sort variables alphabetically
+        sorted_vars = sorted(env_vars.keys())
+
+        # Generate content
+        lines: list[str] = []
+        lines.append("# .env.example.mci")
+        lines.append("# Environment variables used in MCI configuration")
+        lines.append("#")
+        lines.append("# Copy this file to .env.mci and fill in your values")
+        lines.append("")
+
+        for var_name in sorted_vars:
+            locations = env_vars[var_name]
+            # Add comment showing where the variable is used
+            location_str = ", ".join(sorted(locations))
+            lines.append(f"# Used in: {location_str}")
+            lines.append(f"{var_name}=")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def format_to_file(env_vars: dict[str, list[str]], output_path: str | None = None) -> str:
+        """
+        Format environment variables and write to .env.example.mci file.
+
+        Args:
+            env_vars: Dictionary mapping variable names to list of locations where used
+            output_path: Optional custom output path (default: .env.example.mci)
+
+        Returns:
+            Path to the generated file
+
+        Example:
+            >>> env_vars = {
+            ...     "API_KEY": ["main", "weather-toolset"],
+            ...     "DB_URL": ["database-toolset"]
+            ... }
+            >>> path = EnvFormatter.format_to_file(env_vars)
+            >>> print(path)
+            .env.example.mci
+        """
+        if output_path is None:
+            output_path = ".env.example.mci"
+
+        content = EnvFormatter.format_to_string(env_vars)
+        Path(output_path).write_text(content)
+
+        return output_path