glaip-sdk 0.0.10__py3-none-any.whl → 0.0.12__py3-none-any.whl

glaip_sdk/cli/commands/mcps.py

@@ -5,6 +5,7 @@ Authors:
 """
 
 import json
+import sys
 from pathlib import Path
 from typing import Any
 
@@ -21,12 +22,14 @@ from glaip_sdk.cli.display import (
     handle_json_output,
     handle_rich_output,
 )
-from glaip_sdk.cli.io import (
-    export_resource_to_file_with_validation as export_resource_to_file,
-)
 from glaip_sdk.cli.io import (
     fetch_raw_resource_details,
 )
+from glaip_sdk.cli.mcp_validators import (
+    validate_mcp_auth_structure,
+    validate_mcp_config_structure,
+)
+from glaip_sdk.cli.parsers.json_input import parse_json_input
 from glaip_sdk.cli.resolution import resolve_resource_reference
 from glaip_sdk.cli.utils import (
     coerce_to_row,
@@ -40,20 +43,41 @@ from glaip_sdk.cli.utils import (
 )
 from glaip_sdk.rich_components import AIPPanel
 from glaip_sdk.utils import format_datetime
+from glaip_sdk.utils.serialization import (
+    build_mcp_export_payload,
+    write_resource_export,
+)
 
 console = Console()
 
 
 @click.group(name="mcps", no_args_is_help=True)
 def mcps_group() -> None:
-    """MCP management operations."""
+    """MCP management operations.
+
+    Provides commands for creating, listing, updating, deleting, and managing
+    Model Context Protocol (MCP) configurations.
+    """
     pass
 
 
 def _resolve_mcp(
     ctx: Any, client: Any, ref: str, select: int | None = None
 ) -> Any | None:
-    """Resolve MCP reference (ID or name) with ambiguity handling."""
+    """Resolve MCP reference (ID or name) with ambiguity handling.
+
+    Args:
+        ctx: Click context object
+        client: API client instance
+        ref: MCP reference (ID or name)
+        select: Index to select when multiple matches found
+
+    Returns:
+        MCP object if found, None otherwise
+
+    Raises:
+        ClickException: If MCP not found or selection invalid
+    """
     return resolve_resource_reference(
         ctx,
         client,
@@ -70,7 +94,14 @@ def _resolve_mcp(
 @output_flags()
 @click.pass_context
 def list_mcps(ctx: Any) -> None:
-    """List all MCPs."""
+    """List all MCPs in a formatted table.
+
+    Args:
+        ctx: Click context containing output format preferences
+
+    Raises:
+        ClickException: If API request fails
+    """
     try:
         client = get_client(ctx)
         with spinner_context(
@@ -111,36 +142,83 @@ def list_mcps(ctx: Any) -> None:
 @click.option("--name", required=True, help="MCP name")
 @click.option("--transport", required=True, help="MCP transport protocol")
 @click.option("--description", help="MCP description")
-@click.option("--config", help="JSON configuration string")
+@click.option(
+    "--config",
+    help="JSON configuration string or @file reference (e.g., @config.json)",
+)
+@click.option(
+    "--auth",
+    "--authentication",
+    "auth",
+    help="JSON authentication object or @file reference (e.g., @auth.json)",
+)
 @output_flags()
 @click.pass_context
 def create(
-    ctx: Any, name: str, transport: str, description: str | None, config: str | None
+    ctx: Any,
+    name: str,
+    transport: str,
+    description: str | None,
+    config: str | None,
+    auth: str | None,
 ) -> None:
-    """Create a new MCP."""
+    """Create a new MCP with specified configuration.
+
+    Args:
+        ctx: Click context containing output format preferences
+        name: MCP name (required)
+        transport: MCP transport protocol (required)
+        description: Optional MCP description
+        config: JSON configuration string or @file reference
+        auth: JSON authentication object or @file reference
+
+    Raises:
+        ClickException: If JSON parsing fails or API request fails
+    """
     try:
         client = get_client(ctx)
 
-        # Parse config if provided
-        mcp_config = {}
-        if config:
-            try:
-                mcp_config = json.loads(config)
-            except json.JSONDecodeError:
-                raise click.ClickException("Invalid JSON in --config")
+        # Parse config if provided (supports inline JSON or @file)
+        raw_config = parse_json_input(config)
+        if raw_config is None:
+            mcp_config: dict[str, Any] = {}
+        else:
+            mcp_config = validate_mcp_config_structure(
+                raw_config,
+                transport=transport,
+                source="--config",
+            )
+
+        # Parse authentication if provided (supports inline JSON or @file)
+        mcp_auth = parse_json_input(auth)
+        validated_auth = (
+            validate_mcp_auth_structure(mcp_auth, source="--auth")
+            if mcp_auth is not None
+            else None
+        )
+
+        # Build kwargs for create_mcp
+        create_kwargs = {
+            "name": name,
+            "type": "server",  # MCPs are always server type
+            "transport": transport,
+            "config": mcp_config,
+        }
+
+        # Only add description if provided
+        if description is not None:
+            create_kwargs["description"] = description
+
+        # Only add authentication if provided
+        if validated_auth:
+            create_kwargs["authentication"] = validated_auth
 
         with spinner_context(
             ctx,
             "[bold blue]Creating MCP…[/bold blue]",
             console_override=console,
         ):
-            mcp = client.mcps.create_mcp(
-                name=name,
-                type="server",  # MCPs are always server type
-                transport=transport,
-                description=description,
-                config=mcp_config,
-            )
+            mcp = client.mcps.create_mcp(**create_kwargs)
 
         # Handle JSON output
         handle_json_output(ctx, mcp.model_dump())
@@ -163,22 +241,191 @@ def create(
         raise click.ClickException(str(e))
 
 
+def _handle_mcp_export(
+    ctx: Any,
+    client: Any,
+    mcp: Any,
+    export_path: Path,
+    no_auth_prompt: bool,
+    auth_placeholder: str,
+) -> None:
+    """Handle MCP export to file with format detection and auth handling.
+
+    Args:
+        ctx: Click context for spinner management
+        client: API client for fetching MCP details
+        mcp: MCP object to export
+        export_path: Target file path (format detected from extension)
+        no_auth_prompt: Skip interactive secret prompts if True
+        auth_placeholder: Placeholder text for missing secrets
+
+    Note:
+        Supports JSON (.json) and YAML (.yaml/.yml) export formats.
+        In interactive mode, prompts for secret values.
+        In non-interactive mode, uses placeholder values.
+    """
+    # Auto-detect format from file extension
+    detected_format = detect_export_format(export_path)
+
+    # Always export comprehensive data - re-fetch with full details
+    try:
+        with spinner_context(
+            ctx,
+            "[bold blue]Fetching complete MCP details…[/bold blue]",
+            console_override=console,
+        ):
+            mcp = client.mcps.get_mcp_by_id(mcp.id)
+    except Exception as e:
+        console.print(
+            Text(f"[yellow]⚠️  Could not fetch full MCP details: {e}[/yellow]")
+        )
+        console.print(Text("[yellow]⚠️  Proceeding with available data[/yellow]"))
+
+    # Determine if we should prompt for secrets
+    prompt_for_secrets = not no_auth_prompt and sys.stdin.isatty()
+
+    # Warn user if non-interactive mode forces placeholder usage
+    if not no_auth_prompt and not sys.stdin.isatty():
+        console.print(
+            Text(
+                "[yellow]⚠️  Non-interactive mode detected. "
+                "Using placeholder values for secrets.[/yellow]"
+            )
+        )
+
+    # Build and write export payload
+    if prompt_for_secrets:
+        # Interactive mode: no spinner during prompts
+        export_payload = build_mcp_export_payload(
+            mcp,
+            prompt_for_secrets=prompt_for_secrets,
+            placeholder=auth_placeholder,
+            console=console,
+        )
+        with spinner_context(
+            ctx,
+            "[bold blue]Writing export file…[/bold blue]",
+            console_override=console,
+        ):
+            write_resource_export(export_path, export_payload, detected_format)
+    else:
+        # Non-interactive mode: spinner for entire export process
+        with spinner_context(
+            ctx,
+            "[bold blue]Exporting MCP configuration…[/bold blue]",
+            console_override=console,
+        ):
+            export_payload = build_mcp_export_payload(
+                mcp,
+                prompt_for_secrets=prompt_for_secrets,
+                placeholder=auth_placeholder,
+                console=console,
+            )
+            write_resource_export(export_path, export_payload, detected_format)
+
+    console.print(
+        Text(
+            f"[green]✅ Complete MCP configuration exported to: "
+            f"{export_path} (format: {detected_format})[/green]"
+        )
+    )
+
+
+def _display_mcp_details(ctx: Any, client: Any, mcp: Any) -> None:
+    """Display MCP details using raw API data or fallback to Pydantic model.
+
+    Args:
+        ctx: Click context containing output format preferences
+        client: API client for fetching raw MCP data
+        mcp: MCP object to display details for
+
+    Note:
+        Attempts to fetch raw API data first to preserve all fields.
+        Falls back to Pydantic model data if raw data unavailable.
+        Formats datetime fields for better readability.
+    """
+    # Try to fetch raw API data first to preserve ALL fields
+    with spinner_context(
+        ctx,
+        "[bold blue]Fetching detailed MCP data…[/bold blue]",
+        console_override=console,
+    ):
+        raw_mcp_data = fetch_raw_resource_details(client, mcp, "mcps")
+
+    if raw_mcp_data:
+        # Use raw API data - this preserves ALL fields
+        formatted_data = raw_mcp_data.copy()
+        if "created_at" in formatted_data:
+            formatted_data["created_at"] = format_datetime(formatted_data["created_at"])
+        if "updated_at" in formatted_data:
+            formatted_data["updated_at"] = format_datetime(formatted_data["updated_at"])
+
+        output_result(
+            ctx,
+            formatted_data,
+            title="MCP Details",
+            panel_title=f"🔌 {raw_mcp_data.get('name', 'Unknown')}",
+        )
+    else:
+        # Fall back to Pydantic model data
+        console.print("[yellow]Falling back to Pydantic model data[/yellow]")
+        result_data = {
+            "id": str(getattr(mcp, "id", "N/A")),
+            "name": getattr(mcp, "name", "N/A"),
+            "type": getattr(mcp, "type", "N/A"),
+            "config": getattr(mcp, "config", "N/A"),
+            "status": getattr(mcp, "status", "N/A"),
+            "connection_status": getattr(mcp, "connection_status", "N/A"),
+        }
+        output_result(
+            ctx, result_data, title="MCP Details", panel_title=f"🔌 {mcp.name}"
+        )
+
+
 @mcps_group.command()
 @click.argument("mcp_ref")
 @click.option(
     "--export",
     type=click.Path(dir_okay=False, writable=True),
-    help="Export complete MCP configuration to file (format auto-detected from .json/.yaml extension)",
+    help="Export complete MCP configuration to file "
+    "(format auto-detected from .json/.yaml extension)",
+)
+@click.option(
+    "--no-auth-prompt",
+    is_flag=True,
+    help="Skip interactive secret prompts and use placeholder values.",
+)
+@click.option(
+    "--auth-placeholder",
+    default="<INSERT VALUE>",
+    show_default=True,
+    help="Placeholder text used when secrets are unavailable.",
 )
 @output_flags()
 @click.pass_context
-def get(ctx: Any, mcp_ref: str, export: str | None) -> None:
-    """Get MCP details.
+def get(
+    ctx: Any,
+    mcp_ref: str,
+    export: str | None,
+    no_auth_prompt: bool,
+    auth_placeholder: str,
+) -> None:
+    """Get MCP details and optionally export configuration to file.
+
+    Args:
+        ctx: Click context containing output format preferences
+        mcp_ref: MCP reference (ID or name)
+        export: Optional file path to export MCP configuration
+        no_auth_prompt: Skip interactive secret prompts if True
+        auth_placeholder: Placeholder text for missing secrets
+
+    Raises:
+        ClickException: If MCP not found or export fails
 
     Examples:
         aip mcps get my-mcp
-        aip mcps get my-mcp --export mcp.json    # Exports complete configuration as JSON
-        aip mcps get my-mcp --export mcp.yaml    # Exports complete configuration as YAML
+        aip mcps get my-mcp --export mcp.json    # Export as JSON
+        aip mcps get my-mcp --export mcp.yaml    # Export as YAML
     """
     try:
         client = get_client(ctx)
@@ -188,83 +435,12 @@ def get(ctx: Any, mcp_ref: str, export: str | None) -> None:
 
         # Handle export option
         if export:
-            export_path = Path(export)
-            # Auto-detect format from file extension
-            detected_format = detect_export_format(export_path)
-
-            # Always export comprehensive data - re-fetch MCP with full details if needed
-            try:
-                with spinner_context(
-                    ctx,
-                    "[bold blue]Fetching complete MCP details…[/bold blue]",
-                    console_override=console,
-                ):
-                    mcp = client.mcps.get_mcp_by_id(mcp.id)
-            except Exception as e:
-                console.print(
-                    Text(f"[yellow]⚠️  Could not fetch full MCP details: {e}[/yellow]")
-                )
-                console.print(
-                    Text("[yellow]⚠️  Proceeding with available data[/yellow]")
-                )
-
-            with spinner_context(
-                ctx,
-                "[bold blue]Exporting MCP configuration…[/bold blue]",
-                console_override=console,
-            ):
-                export_resource_to_file(mcp, export_path, detected_format)
-            console.print(
-                Text(
-                    f"[green]✅ Complete MCP configuration exported to: {export_path} (format: {detected_format})[/green]"
-                )
-            )
-
-        # Try to fetch raw API data first to preserve ALL fields
-        with spinner_context(
-            ctx,
-            "[bold blue]Fetching detailed MCP data…[/bold blue]",
-            console_override=console,
-        ):
-            raw_mcp_data = fetch_raw_resource_details(client, mcp, "mcps")
-
-        if raw_mcp_data:
-            # Use raw API data - this preserves ALL fields
-            # Format dates for better display (minimal postprocessing)
-            formatted_data = raw_mcp_data.copy()
-            if "created_at" in formatted_data:
-                formatted_data["created_at"] = format_datetime(
-                    formatted_data["created_at"]
-                )
-            if "updated_at" in formatted_data:
-                formatted_data["updated_at"] = format_datetime(
-                    formatted_data["updated_at"]
-                )
-
-            # Display using output_result with raw data
-            output_result(
-                ctx,
-                formatted_data,
-                title="MCP Details",
-                panel_title=f"🔌 {raw_mcp_data.get('name', 'Unknown')}",
+            _handle_mcp_export(
+                ctx, client, mcp, Path(export), no_auth_prompt, auth_placeholder
             )
-        else:
-            # Fall back to original method if raw fetch fails
-            console.print("[yellow]Falling back to Pydantic model data[/yellow]")
-
-            # Create result data with actual available fields
-            result_data = {
-                "id": str(getattr(mcp, "id", "N/A")),
-                "name": getattr(mcp, "name", "N/A"),
-                "type": getattr(mcp, "type", "N/A"),
-                "config": getattr(mcp, "config", "N/A"),
-                "status": getattr(mcp, "status", "N/A"),
-                "connection_status": getattr(mcp, "connection_status", "N/A"),
-            }
 
-            output_result(
-                ctx, result_data, title="MCP Details", panel_title=f"🔌 {mcp.name}"
-            )
+        # Display MCP details
+        _display_mcp_details(ctx, client, mcp)
 
     except Exception as e:
         raise click.ClickException(str(e))
@@ -275,7 +451,15 @@ def get(ctx: Any, mcp_ref: str, export: str | None) -> None:
 @output_flags()
 @click.pass_context
 def list_tools(ctx: Any, mcp_ref: str) -> None:
-    """List tools from MCP."""
+    """List tools available from a specific MCP.
+
+    Args:
+        ctx: Click context containing output format preferences
+        mcp_ref: MCP reference (ID or name)
+
+    Raises:
+        ClickException: If MCP not found or tools fetch fails
+    """
     try:
         client = get_client(ctx)
 
@@ -325,7 +509,19 @@ def list_tools(ctx: Any, mcp_ref: str) -> None:
 @output_flags()
 @click.pass_context
 def connect(ctx: Any, config_file: str) -> None:
-    """Connect to MCP using config file."""
+    """Test MCP connection using a configuration file.
+
+    Args:
+        ctx: Click context containing output format preferences
+        config_file: Path to MCP configuration JSON file
+
+    Raises:
+        ClickException: If config file invalid or connection test fails
+
+    Note:
+        Loads MCP configuration from JSON file and tests connectivity.
+        Displays success or failure with connection details.
+    """
     try:
         client = get_client(ctx)
 
@@ -337,7 +533,8 @@ def connect(ctx: Any, config_file: str) -> None:
         if view != "json":
             console.print(
                 Text(
-                    f"[yellow]Connecting to MCP with config from {config_file}...[/yellow]"
+                    f"[yellow]Connecting to MCP with config from "
+                    f"{config_file}...[/yellow]"
                 )
             )
 
@@ -369,7 +566,16 @@ def connect(ctx: Any, config_file: str) -> None:
 @click.argument("mcp_ref")
 @click.option("--name", help="New MCP name")
 @click.option("--description", help="New description")
-@click.option("--config", help="JSON configuration string")
+@click.option(
+    "--config",
+    help="JSON configuration string or @file reference (e.g., @config.json)",
+)
+@click.option(
+    "--auth",
+    "--authentication",
+    "auth",
+    help="JSON authentication object or @file reference (e.g., @auth.json)",
+)
 @output_flags()
 @click.pass_context
 def update(
@@ -378,8 +584,25 @@ def update(
     name: str | None,
     description: str | None,
     config: str | None,
+    auth: str | None,
 ) -> None:
-    """Update an existing MCP."""
+    """Update an existing MCP with new configuration values.
+
+    Args:
+        ctx: Click context containing output format preferences
+        mcp_ref: MCP reference (ID or name)
+        name: New MCP name (optional)
+        description: New description (optional)
+        config: New JSON configuration string or @file reference (optional)
+        auth: New JSON authentication object or @file reference (optional)
+
+    Raises:
+        ClickException: If MCP not found, JSON invalid, or no fields specified
+
+    Note:
+        At least one field must be specified for update.
+        Uses PUT for complete updates or PATCH for partial updates.
+    """
     try:
         client = get_client(ctx)
 
@@ -393,10 +616,17 @@ def update(
         if description is not None:
             update_data["description"] = description
         if config is not None:
-            try:
-                update_data["config"] = json.loads(config)
-            except json.JSONDecodeError:
-                raise click.ClickException("Invalid JSON in --config")
+            parsed_config = parse_json_input(config)
+            update_data["config"] = validate_mcp_config_structure(
+                parsed_config,
+                transport=getattr(mcp, "transport", None),
+                source="--config",
+            )
+        if auth is not None:
+            parsed_auth = parse_json_input(auth)
+            update_data["authentication"] = validate_mcp_auth_structure(
+                parsed_auth, source="--auth"
+            )
 
         if not update_data:
             raise click.ClickException("No update fields specified")
@@ -425,7 +655,20 @@ def update(
 @output_flags()
 @click.pass_context
 def delete(ctx: Any, mcp_ref: str, yes: bool) -> None:
-    """Delete an MCP."""
+    """Delete an MCP after confirmation.
+
+    Args:
+        ctx: Click context containing output format preferences
+        mcp_ref: MCP reference (ID or name)
+        yes: Skip confirmation prompt if True
+
+    Raises:
+        ClickException: If MCP not found or deletion fails
+
+    Note:
+        Requires confirmation unless --yes flag is provided.
+        Deletion is permanent and cannot be undone.
+    """
     try:
         client = get_client(ctx)
 

glaip_sdk/cli/main.py

@@ -24,6 +24,7 @@ from glaip_sdk.cli.commands.configure import (
 from glaip_sdk.cli.commands.mcps import mcps_group
 from glaip_sdk.cli.commands.models import models_group
 from glaip_sdk.cli.commands.tools import tools_group
+from glaip_sdk.cli.update_notifier import maybe_notify_update
 from glaip_sdk.cli.utils import spinner_context, update_spinner
 from glaip_sdk.config.constants import (
     DEFAULT_AGENT_RUN_TIMEOUT,
@@ -82,6 +83,13 @@ def main(
 
     ctx.obj["tty"] = not no_tty
 
+    if not ctx.resilient_parsing and ctx.obj["tty"]:
+        console = Console()
+        maybe_notify_update(
+            _SDK_VERSION,
+            console=console,
+        )
+
     if ctx.invoked_subcommand is None and not ctx.resilient_parsing:
         if _should_launch_slash(ctx) and SlashSession is not None:
             session = SlashSession(ctx)