cloudwright-ai-cli 0.2.27__tar.gz → 0.3.1__tar.gz

{cloudwright_ai_cli-0.2.27 → cloudwright_ai_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudwright-ai-cli
-Version: 0.2.27
+Version: 0.3.1
 Summary: CLI for Cloudwright architecture intelligence
 Project-URL: Homepage, https://github.com/xmpuspus/cloudwright
 Project-URL: Repository, https://github.com/xmpuspus/cloudwright

cloudwright_ai_cli-0.3.1/cloudwright_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.1"

cloudwright_ai_cli-0.3.1/cloudwright_cli/commands/adr.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from cloudwright_cli.output import emit_dry_run, emit_error, validate_output_path
+from cloudwright_cli.utils import handle_error
+
+console = Console()
+
+_ADR_SYSTEM = """You generate Architecture Decision Records (ADRs) in MADR format.
+
+Given an architecture spec as JSON, produce a markdown ADR with this exact structure:
+
+# ADR: {name} — {key decision}
+
+## Status
+Proposed
+
+## Context
+{problem and why a decision is needed}
+
+## Decision
+{the chosen architecture and key choices}
+
+## Components
+| ID | Service | Provider | Purpose |
+|---|---|---|---|
+{component rows}
+
+## Consequences
+### Positive
+- {benefits}
+
+### Negative
+- {trade-offs and risks}
+
+## Alternatives Considered
+{alternatives if any, otherwise note none documented}
+
+## Cost Estimate
+{monthly cost if available, otherwise omit}
+
+Be concise. Focus on the WHY, not just what the architecture contains.
+Respond with ONLY the markdown — no explanation, no code fences."""
+
+
+def adr(
+    ctx: typer.Context,
+    spec_file: Annotated[Path, typer.Argument(help="Path to ArchSpec YAML file", exists=True)],
+    output: Annotated[str | None, typer.Option("--output", "-o", help="Write ADR to this file")] = None,
+    title: Annotated[str | None, typer.Option("--title", help="ADR title (default: auto-generated)")] = None,
+    decision: Annotated[str | None, typer.Option("--decision", help="Specific decision to document")] = None,
+) -> None:
+    """Generate an Architecture Decision Record from an ArchSpec."""
+    try:
+        from cloudwright import ArchSpec
+
+        if output:
+            try:
+                validate_output_path(output)
+            except ValueError as e:
+                emit_error(ctx, e)
+
+        spec = ArchSpec.from_file(spec_file)
+
+        if ctx.obj and ctx.obj.get("dry_run"):
+            from cloudwright.llm.anthropic import GENERATE_MODEL
+
+            spec_json = spec.model_dump_json(indent=2, exclude_none=True)
+            emit_dry_run(ctx, {
+                "model": GENERATE_MODEL,
+                "estimated_tokens": len(spec_json + _ADR_SYSTEM) // 4,
+                "max_tokens": 2000,
+                "system_prompt_preview": _ADR_SYSTEM,
+                "user_prompt_preview": f"Generate ADR for: {spec.name}",
+            })
+
+        text = _generate_adr(spec, title=title, decision=decision)
+
+        if output:
+            Path(output).write_text(text)
+            console.print(f"[green]ADR written to {output}[/green]")
+        else:
+            print(text)
+
+    except typer.Exit:
+        raise
+    except Exception as e:
+        handle_error(ctx, e)
+
+
+def _generate_adr(spec, *, title: str | None = None, decision: str | None = None) -> str:
+    try:
+        return _llm_adr(spec, title=title, decision=decision)
+    except Exception:
+        return _deterministic_adr(spec, title=title, decision=decision)
+
+
+def _llm_adr(spec, *, title: str | None, decision: str | None) -> str:
+    from cloudwright.architect import Architect
+
+    arch = Architect()
+    spec_summary = spec.model_dump_json(indent=2, exclude_none=True)
+
+    decision_hint = f"\nDocument this specific decision: {decision}" if decision else ""
+    title_hint = f"\nUse this ADR title: {title}" if title else ""
+    prompt = f"Generate an ADR for this architecture:{title_hint}{decision_hint}\n\n{spec_summary}"
+
+    text, _ = arch.llm.generate([{"role": "user", "content": prompt}], _ADR_SYSTEM, max_tokens=2000)
+    if not text.strip().startswith("#"):
+        raise ValueError("LLM did not return markdown ADR")
+    return text.strip()
+
+
+def _deterministic_adr(spec, *, title: str | None = None, decision: str | None = None) -> str:
+    adr_title = title or spec.name
+    key_decision = decision or _infer_key_decision(spec)
+
+    lines = [
+        f"# ADR: {adr_title} — {key_decision}",
+        "",
+        "## Status",
+        "Proposed",
+        "",
+        "## Context",
+        _build_context(spec),
+        "",
+        "## Decision",
+        _build_decision(spec),
+        "",
+        "## Components",
+        "| ID | Service | Provider | Purpose |",
+        "|---|---|---|---|",
+    ]
+
+    for c in spec.components:
+        purpose = c.description or c.label
+        lines.append(f"| {c.id} | {c.service} | {c.provider} | {purpose} |")
+
+    lines += ["", "## Consequences"]
+    lines += _build_consequences(spec)
+
+    rationale = spec.metadata.get("rationale") or []
+    if rationale:
+        lines += ["", "## Alternatives Considered"]
+        for r in rationale:
+            if isinstance(r, dict):
+                lines.append(f"- **{r.get('decision', '')}**: {r.get('reason', '')}")
+
+    if spec.cost_estimate:
+        lines += [
+            "",
+            "## Cost Estimate",
+            f"Estimated monthly cost: ${spec.cost_estimate.monthly_total:,.2f} USD",
+        ]
+
+    return "\n".join(lines)
+
+
+def _infer_key_decision(spec) -> str:
+    rationale = spec.metadata.get("rationale") or []
+    if rationale and isinstance(rationale[0], dict):
+        return rationale[0].get("decision", f"{spec.provider.upper()} architecture")
+    return f"{spec.provider.upper()} architecture"
+
+
+def _build_context(spec) -> str:
+    parts = [f"This architecture, {spec.name!r}, targets the {spec.provider.upper()} platform in region {spec.region}."]
+    if spec.constraints:
+        if spec.constraints.compliance:
+            parts.append(f"Compliance requirements: {', '.join(spec.constraints.compliance)}.")
+        if spec.constraints.budget_monthly:
+            parts.append(f"Monthly budget constraint: ${spec.constraints.budget_monthly:,.0f}.")
+    parts.append(f"It consists of {len(spec.components)} components across {len(spec.connections)} connections.")
+    return " ".join(parts)
+
+
+def _build_decision(spec) -> str:
+    rationale = spec.metadata.get("rationale") or []
+    if rationale:
+        items = []
+        for r in rationale:
+            if isinstance(r, dict):
+                items.append(f"- **{r.get('decision', '')}**: {r.get('reason', '')}")
+        if items:
+            return "\n".join(items)
+
+    services = ", ".join(c.service for c in spec.components[:5])
+    suffix = ", ..." if len(spec.components) > 5 else ""
+    return f"Selected architecture using: {services}{suffix}."
+
+
+def _build_consequences(spec) -> list[str]:
+    lines = ["### Positive"]
+    suggestions = spec.metadata.get("suggestions") or []
+
+    positives = [
+        f"Established {spec.provider.upper()} native services reduce operational overhead.",
+        f"{len(spec.components)} components provide clear separation of concerns.",
+    ]
+    lines += [f"- {p}" for p in positives]
+
+    lines += ["", "### Negative"]
+    negatives = ["Vendor lock-in to selected provider and service tier."]
+    if suggestions:
+        negatives.append("Additional configuration required: " + suggestions[0].lower() + ".")
+    lines += [f"- {n}" for n in negatives]
+
+    return lines

{cloudwright_ai_cli-0.2.27 → cloudwright_ai_cli-0.3.1}/cloudwright_cli/commands/analyze_cmd.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import json
 from typing import Annotated
 
 import typer
@@ -11,6 +10,7 @@ from rich.panel import Panel
 from rich.table import Table
 from rich.tree import Tree
 
+from cloudwright_cli.output import emit_error, emit_success, is_json_mode
 from cloudwright_cli.utils import handle_error
 
 console = Console()
@@ -31,15 +31,17 @@ def analyze(
         if component:
             valid_ids = {c.id for c in spec.components}
             if component not in valid_ids:
-                console.print(f"[red]Error:[/red] Component '{component}' not found in spec.")
-                console.print(f"[dim]Available components: {', '.join(sorted(valid_ids))}[/dim]")
-                raise typer.Exit(1)
+                emit_error(
+                    ctx,
+                    ValueError(f"Component '{component}' not found in spec"),
+                    action=f"Available: {', '.join(sorted(valid_ids))}",
+                )
 
         analyzer = Analyzer()
         result = analyzer.analyze(spec, component_id=component)
 
-        if ctx.obj and ctx.obj.get("json"):
-            print(json.dumps(result.to_dict(), indent=2))
+        if is_json_mode(ctx):
+            emit_success(ctx, {"analysis": result.to_dict()})
             return
 
         spof_text = ", ".join(result.spofs) if result.spofs else "None"

{cloudwright_ai_cli-0.2.27 → cloudwright_ai_cli-0.3.1}/cloudwright_cli/commands/catalog_cmd.py

@@ -8,6 +8,8 @@ from cloudwright import Catalog
 from rich.console import Console
 from rich.table import Table
 
+from cloudwright_cli.output import emit_success, err_console
+
 console = Console()
 
 catalog_app = typer.Typer(
@@ -68,9 +70,7 @@ def catalog_search(
     # Resolve ctx.obj through parent chain when invoked via sub-app
     obj = ctx.obj or (ctx.parent.obj if ctx.parent else None)
     if obj and obj.get("json"):
-        import json
-
-        print(json.dumps({"results": results}, default=str))
+        emit_success(ctx, {"results": results})
         return
 
     if not results:
@@ -108,7 +108,7 @@ def catalog_compare(
 ) -> None:
     """Compare two or more cloud instances side by side."""
     if len(instances) < 2:
-        console.print("[red]Error:[/red] Provide at least 2 instance names to compare.")
+        err_console.print("[red]Error:[/red] Provide at least 2 instance names to compare.")
         raise typer.Exit(1)
 
     with console.status("Fetching instance details..."):
@@ -118,10 +118,8 @@ def catalog_compare(
     # Resolve ctx.obj through parent chain when invoked via sub-app
     obj = ctx.obj or (ctx.parent.obj if ctx.parent else None)
     if obj and obj.get("json"):
-        import json
-
         inst_map = {r.get("name", r.get("id", "")): r for r in results}
-        print(json.dumps({"comparison": inst_map}, default=str))
+        emit_success(ctx, {"comparison": inst_map})
         return
 
     if not results:

{cloudwright_ai_cli-0.2.27 → cloudwright_ai_cli-0.3.1}/cloudwright_cli/commands/compare.py

@@ -8,17 +8,20 @@ from cloudwright import Architect, ArchSpec
 from rich.console import Console
 from rich.table import Table
 
+from cloudwright_cli.output import emit_success, err_console, is_json_mode
+
 console = Console()
 
 
 def compare(
+    ctx: typer.Context,
     spec_file: Annotated[Path, typer.Argument(help="Path to spec YAML file", exists=True)],
     providers: Annotated[str, typer.Option(help="Comma-separated target providers")],
 ) -> None:
     """Compare an architecture across multiple cloud providers."""
     target_providers = [p.strip() for p in providers.split(",") if p.strip()]
     if not target_providers:
-        console.print("[red]Error:[/red] --providers requires at least one provider")
+        err_console.print("[red]Error:[/red] --providers requires at least one provider")
         raise typer.Exit(1)
 
     spec = ArchSpec.from_file(spec_file)
@@ -32,6 +35,26 @@ def compare(
         if alt.spec:
             alt_map[alt.provider] = alt.spec
 
+    if is_json_mode(ctx):
+        origin_total = spec.cost_estimate.monthly_total if spec.cost_estimate else 0.0
+        data = {
+            "baseline": spec.provider,
+            "providers": {
+                spec.provider: {
+                    "monthly_total": origin_total,
+                    "components": [c.model_dump() for c in spec.components],
+                }
+            },
+        }
+        for alt in alts:
+            data["providers"][alt.provider] = {
+                "monthly_total": alt.monthly_total,
+                "key_differences": alt.key_differences,
+                "components": [c.model_dump() for c in alt.spec.components] if alt.spec else [],
+            }
+        emit_success(ctx, {"comparison": data})
+        return
+
     # Side-by-side service comparison
     table = Table(title=f"Provider Comparison — {spec.name}")
     table.add_column("Component", style="cyan")

{cloudwright_ai_cli-0.2.27 → cloudwright_ai_cli-0.3.1}/cloudwright_cli/commands/cost.py

@@ -9,6 +9,8 @@ from cloudwright.cost import CostEngine
 from rich.console import Console
 from rich.table import Table
 
+from cloudwright_cli.output import emit_success, is_json_mode
+
 console = Console()
 
 
@@ -28,10 +30,8 @@ def cost(
         engine = CostEngine()
         spec.cost_estimate = engine.estimate(spec)
 
-    if ctx.obj and ctx.obj.get("json"):
-        import json
-
-        print(json.dumps({"estimate": spec.cost_estimate.model_dump()}, default=str))
+    if is_json_mode(ctx):
+        emit_success(ctx, {"estimate": spec.cost_estimate.model_dump(exclude_none=True)})
         return
 
     if compare:

{cloudwright_ai_cli-0.2.27 → cloudwright_ai_cli-0.3.1}/cloudwright_cli/commands/design.py

@@ -13,6 +13,8 @@ from rich.panel import Panel
 from rich.syntax import Syntax
 from rich.table import Table
 
+from cloudwright_cli.output import emit_dry_run, emit_error, emit_success, is_json_mode
+
 console = Console()
 
 
@@ -35,24 +37,37 @@ def design(
         compliance=compliance or [],
     )
 
+    # Dry-run: show what the LLM call would look like
+    if ctx.obj and ctx.obj.get("dry_run"):
+        from cloudwright.architect import _build_constraint_prompt
+        from cloudwright.llm.anthropic import GENERATE_MODEL
+
+        system = Architect._select_system_prompt(description)
+        if constraints:
+            system += _build_constraint_prompt(constraints)
+        emit_dry_run(ctx, {
+            "model": GENERATE_MODEL,
+            "estimated_tokens": len(system + description) // 4,
+            "max_tokens": 10000,
+            "system_prompt_preview": system[:200],
+            "user_prompt_preview": description,
+            "constraints": constraints.model_dump(exclude_none=True),
+        })
+
     try:
         architect = Architect()
     except RuntimeError as e:
-        console.print(f"[red]Error:[/red] {e}")
-        raise typer.Exit(1) from None
+        emit_error(ctx, e, action="Set ANTHROPIC_API_KEY or OPENAI_API_KEY")
 
     with console.status("Designing architecture..."):
         spec = architect.design(description, constraints=constraints)
-        # Set provider/region from CLI args if not overridden by LLM
         if spec.provider == "aws" and provider != "aws":
             spec = spec.model_copy(update={"provider": provider})
         if spec.region == "us-east-1" and region != "us-east-1":
             spec = spec.model_copy(update={"region": region})
 
-    if ctx.obj and ctx.obj.get("json"):
-        import json
-
-        print(json.dumps(spec.model_dump(), default=str))
+    if is_json_mode(ctx):
+        emit_success(ctx, {"spec": spec.model_dump(exclude_none=True), "yaml": spec.to_yaml()})
         return
 
     yaml_str = spec.to_yaml()

{cloudwright_ai_cli-0.2.27 → cloudwright_ai_cli-0.3.1}/cloudwright_cli/commands/diff.py

@@ -9,6 +9,8 @@ from rich.console import Console
 from rich.rule import Rule
 from rich.table import Table
 
+from cloudwright_cli.output import emit_success, is_json_mode
+
 console = Console()
 
 
@@ -24,10 +26,8 @@ def diff(
     with console.status("Computing diff..."):
         result = Differ().diff(a, b)
 
-    if ctx.obj and ctx.obj.get("json"):
-        import json
-
-        print(json.dumps(result.model_dump(), default=str))
+    if is_json_mode(ctx):
+        emit_success(ctx, {"diff": result.model_dump(exclude_none=True)})
         return
 
     console.print(Rule(f"[bold]Diff: {spec_a.name} → {spec_b.name}[/bold]"))

{cloudwright_ai_cli-0.2.27 → cloudwright_ai_cli-0.3.1}/cloudwright_cli/commands/drift_cmd.py

@@ -11,6 +11,7 @@ from rich.panel import Panel
 from rich.rule import Rule
 from rich.table import Table
 
+from cloudwright_cli.output import emit_success, err_console, is_json_mode
 from cloudwright_cli.utils import handle_error
 
 console = Console()
@@ -23,25 +24,22 @@ def drift(
     fmt: Annotated[
         str, typer.Option("--format", "-f", help="Infrastructure format: auto, terraform, cloudformation")
     ] = "auto",
-    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
 ) -> None:
     """Compare design spec against deployed infrastructure to detect drift."""
     try:
         from cloudwright.drift import detect_drift
 
         if not Path(spec_file).exists():
-            console.print(f"[red]Error:[/red] Design spec not found: {spec_file}")
+            err_console.print(f"[red]Error:[/red] Design spec not found: {spec_file}")
             raise typer.Exit(1)
         if not Path(infra_file).exists():
-            console.print(f"[red]Error:[/red] Infrastructure file not found: {infra_file}")
+            err_console.print(f"[red]Error:[/red] Infrastructure file not found: {infra_file}")
             raise typer.Exit(1)
 
         with console.status("Detecting drift..."):
             report = detect_drift(spec_file, infra_file, infra_format=fmt)
 
-        if json_output:
-            import json
-
+        if is_json_mode(ctx):
             result = {
                 "drift_score": report.drift_score,
                 "drifted_components": report.drifted_components,
@@ -50,7 +48,7 @@ def drift(
                 "diff": report.diff.model_dump(),
                 "summary": report.summary,
             }
-            console.print_json(json.dumps(result, default=str))
+            emit_success(ctx, {"drift": result})
             return
 
         score_color = "green" if report.drift_score == 0 else "yellow" if report.drift_score < 0.3 else "red"

{cloudwright_ai_cli-0.2.27 → cloudwright_ai_cli-0.3.1}/cloudwright_cli/commands/export.py

@@ -9,6 +9,8 @@ from cloudwright.exporter import FORMATS
 from rich.console import Console
 from rich.syntax import Syntax
 
+from cloudwright_cli.output import emit_error, emit_success, is_json_mode, validate_output_path
+
 console = Console()
 
 _SYNTAX_MAP = {
@@ -40,8 +42,13 @@ def export(
     """Export an architecture spec to Terraform, CloudFormation, Mermaid, SVG, PNG, SBOM, or AIBOM."""
     fmt = format.lower().strip()
     if fmt not in FORMATS and fmt != "cfn":
-        console.print(f"[red]Error:[/red] Unknown format {fmt!r}. Supported: {', '.join(FORMATS)}")
-        raise typer.Exit(1)
+        emit_error(ctx, ValueError(f"Unknown format {fmt!r}"), action=f"Use one of: {', '.join(FORMATS)}")
+
+    if output:
+        try:
+            validate_output_path(output)
+        except ValueError as e:
+            emit_error(ctx, e)
 
     spec = ArchSpec.from_file(spec_file)
 
@@ -62,10 +69,11 @@ def export(
         from cloudwright.exporter.renderer import DiagramRenderer
 
         if not DiagramRenderer.is_available():
-            console.print(
-                "[red]Error:[/red] D2 binary not found. Install: curl -fsSL https://d2lang.com/install.sh | sh"
+            emit_error(
+                ctx,
+                RuntimeError("D2 binary not found"),
+                action="Install: curl -fsSL https://d2lang.com/install.sh | sh",
             )
-            raise typer.Exit(1)
 
         with console.status("Rendering PNG via D2..."):
             data = DiagramRenderer().render_png(spec)
@@ -90,10 +98,8 @@ def export(
     with console.status(f"Exporting as {fmt}..."):
         content = spec.export(fmt, output=output_str, output_dir=output_dir_str)
 
-    if ctx.obj and ctx.obj.get("json"):
-        import json
-
-        print(json.dumps({"format": fmt, "content": content}, default=str))
+    if is_json_mode(ctx):
+        emit_success(ctx, {"format": fmt, "content": content})
         return
 
     if output:

{cloudwright_ai_cli-0.2.27 → cloudwright_ai_cli-0.3.1}/cloudwright_cli/commands/import_cmd.py

@@ -10,6 +10,7 @@ from typing import Annotated
 import typer
 from rich.console import Console
 
+from cloudwright_cli.output import emit_success, is_json_mode, validate_output_path
 from cloudwright_cli.utils import handle_error
 
 console = Console()
@@ -45,15 +46,14 @@ def import_infra(
         if name:
             spec = spec.model_copy(update={"name": name})
 
-        json_mode = ctx.obj and ctx.obj.get("json")
-
-        if json_mode:
-            print(json.dumps(json.loads(spec.to_json()), indent=2))
+        if is_json_mode(ctx):
+            emit_success(ctx, {"spec": json.loads(spec.to_json())})
             return
 
         content = spec.to_yaml()
 
         if output:
+            validate_output_path(output)
             Path(output).write_text(content)
             n_comps = len(spec.components)
             n_conns = len(spec.connections)

{cloudwright_ai_cli-0.2.27 → cloudwright_ai_cli-0.3.1}/cloudwright_cli/commands/init_cmd.py

@@ -10,6 +10,7 @@ import yaml
 from rich.console import Console
 from rich.table import Table
 
+from cloudwright_cli.output import validate_output_path
 from cloudwright_cli.utils import handle_error
 
 console = Console()
@@ -116,6 +117,7 @@ def init(
             (proj_dir / "config.yaml").write_text(yaml.dump(config, default_flow_style=False, sort_keys=False))
         else:
             output_path = Path(output)
+            validate_output_path(output_path)
 
         output_path.write_text(yaml.dump(spec_data, default_flow_style=False, sort_keys=False, allow_unicode=True))
 

{cloudwright_ai_cli-0.2.27 → cloudwright_ai_cli-0.3.1}/cloudwright_cli/commands/lint_cmd.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
 from typing import Annotated
 
@@ -11,6 +10,7 @@ from rich.console import Console
 from rich.table import Table
 from rich.text import Text
 
+from cloudwright_cli.output import emit_stream, emit_success, is_json_mode, should_stream
 from cloudwright_cli.utils import handle_error
 
 console = Console()
@@ -19,7 +19,6 @@ console = Console()
 def lint(
     ctx: typer.Context,
     spec_file: Annotated[Path, typer.Argument(help="Architecture spec YAML file", exists=True)],
-    output: Annotated[str, typer.Option(help="Output format: text, json")] = "text",
     strict: Annotated[bool, typer.Option(help="Fail on warnings too")] = False,
 ) -> None:
     """Detect architecture anti-patterns in a spec file."""
@@ -30,7 +29,17 @@ def lint(
         spec = ArchSpec.from_file(spec_file)
         warnings = run_lint(spec)
 
-        if output == "json":
+        if is_json_mode(ctx):
+            if should_stream(ctx):
+                for w in warnings:
+                    emit_stream({
+                        "rule": w.rule,
+                        "severity": w.severity,
+                        "component": w.component,
+                        "message": w.message,
+                        "recommendation": w.recommendation,
+                    })
+                return
             result = [
                 {
                     "rule": w.rule,
@@ -41,7 +50,7 @@ def lint(
                 }
                 for w in warnings
             ]
-            print(json.dumps(result, indent=2))
+            emit_success(ctx, {"warnings": result})
         else:
             if not warnings:
                 console.print(f"[green][PASS][/green] No anti-patterns detected in {spec.name}")

cloudwright_ai_cli-0.3.1/cloudwright_cli/commands/mcp_cmd.py

@@ -0,0 +1,34 @@
+"""Serve cloudwright functions as an MCP server."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+
+def mcp_serve(
+    tools: Annotated[
+        str | None,
+        typer.Option("--tools", "-t", help="Comma-separated tool groups: design,cost,validate,analyze,export,session"),
+    ] = None,
+    transport: Annotated[str, typer.Option("--transport", help="Transport: stdio or sse")] = "stdio",
+) -> None:
+    """Start an MCP server exposing cloudwright tools."""
+    try:
+        from cloudwright_mcp.server import create_server
+    except ImportError:
+        from rich.console import Console
+
+        Console(stderr=True).print(
+            "[red]Error:[/red] cloudwright-ai-mcp not installed.\n"
+            "  Install: pip install cloudwright-ai-mcp"
+        )
+        raise typer.Exit(1) from None
+
+    tool_set: set[str] | None = None
+    if tools:
+        tool_set = {t.strip() for t in tools.split(",") if t.strip()}
+
+    server = create_server(tools=tool_set)
+    server.run(transport=transport)