mcpheroctl 0.1.0__tar.gz

mcpheroctl-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.3
+Name: mcpheroctl
+Version: 0.1.0
+Summary: CLI tool for interacting with the MCPHero platform
+Author: Andrew
+Author-email: Andrew <contact@arteriali.st>
+Requires-Dist: typer>=0.15.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: tenacity>=9.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Python: >=3.12

mcpheroctl-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "mcpheroctl"
+version = "0.1.0"
+description = "CLI tool for interacting with the MCPHero platform"
+authors = [
+    { name = "Andrew", email = "contact@arteriali.st" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "typer>=0.15.0",
+    "httpx>=0.28.0",
+    "pydantic>=2.0.0",
+    "tenacity>=9.0.0",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+mcpheroctl = "mcpheroctl.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.10.3,<0.11.0"]
+build-backend = "uv_build"

mcpheroctl-0.1.0/src/mcpheroctl/__init__.py

@@ -0,0 +1,3 @@
+"""mcpheroctl - CLI tool for interacting with the MCPHero platform."""
+
+__version__ = "0.1.0"

mcpheroctl-0.1.0/src/mcpheroctl/cli.py

@@ -0,0 +1,66 @@
+"""mcpheroctl – CLI tool for interacting with the MCPHero platform.
+
+Designed for both human operators and AI agent workflows.
+Follows the agent-first CLI guidelines: structured JSON output,
+meaningful exit codes, noun-verb grammar, and actionable errors.
+
+Exit codes:
+    0  success
+    1  general failure
+    2  usage error (bad arguments)
+    3  resource not found
+    4  permission denied / not authenticated
+    5  conflict (resource already exists)
+    6  not implemented
+"""
+
+from __future__ import annotations
+
+import typer
+
+from mcpheroctl import __version__
+from mcpheroctl.commands.auth import auth_app
+from mcpheroctl.commands.server import server_app
+from mcpheroctl.commands.wizard import wizard_app
+
+app = typer.Typer(
+    name="mcpheroctl",
+    help="CLI tool for interacting with the MCPHero platform.",
+    no_args_is_help=True,
+    rich_markup_mode=None,
+    add_completion=True,
+    pretty_exceptions_enable=False,
+)
+
+# Register sub-apps (noun-verb pattern)
+app.add_typer(auth_app, name="auth")
+app.add_typer(server_app, name="server")
+app.add_typer(wizard_app, name="wizard")
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"mcpheroctl {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _: bool = typer.Option(  # pyright: ignore[reportCallInDefaultInitializer]
+        False,
+        "--version",
+        "-v",
+        help="Show version and exit.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """MCPHero CLI – manage MCP servers and run the creation wizard.
+
+    Authenticate first with `mcpheroctl auth login --token <TOKEN>`, then
+    use `mcpheroctl server` and `mcpheroctl wizard` to interact with the
+    platform.
+
+    Use --json on any command for structured JSON output (stdout).
+    Human-readable messages go to stderr.
+    """

mcpheroctl-0.1.0/src/mcpheroctl/commands/auth.py

@@ -0,0 +1,108 @@
+"""Auth commands for mcpheroctl."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from mcpheroctl.core.config import Config, load_config, save_config
+from mcpheroctl.core.output import die, info, print_result, success
+
+auth_app = typer.Typer(
+    name="auth",
+    help="Manage API authentication.",
+    no_args_is_help=True,
+    rich_markup_mode=None,
+)
+
+
+@auth_app.command("login")
+def login(
+    token: Annotated[
+        str, typer.Option("--token", "-t", help="Organization API token.", prompt=False)
+    ],
+    base_url: Annotated[
+        str | None, typer.Option("--base-url", help="Override the API base URL.")
+    ] = None,
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Authenticate with the MCPHero API using an organization API token.
+
+    Saves the token to ~/.config/mcpheroctl/config.json for future use.
+
+    Examples:
+        mcpheroctl auth login --token myorg_sk_abc123
+        mcpheroctl auth login --token myorg_sk_abc123 --base-url https://custom.api.com/api
+    """
+    config: Config = load_config()
+    config.api_token = token
+    if base_url is not None:
+        config.base_url = base_url
+    save_config(config)
+    if output_json:
+        print_result(
+            {"status": "authenticated", "base_url": config.base_url}, use_json=True
+        )
+        return
+
+    success(f"Token saved. API: {config.base_url}")
+
+
+@auth_app.command("status")
+def status(
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Check current authentication status.
+
+    Examples:
+        mcpheroctl auth status
+        mcpheroctl auth status --json
+    """
+    config: Config = load_config()
+    is_authenticated: bool = config.api_token is not None
+    if output_json:
+        print_result(
+            {
+                "authenticated": is_authenticated,
+                "base_url": config.base_url,
+                "token_preview": f"...{config.api_token[-8:]}"
+                if config.api_token
+                else None,
+            },
+            use_json=True,
+        )
+        return
+
+    if is_authenticated:
+        success(f"Authenticated (token: ...{config.api_token[-8:]})")  # pyright: ignore[reportOptionalSubscript]
+        info(f"API: {config.base_url}")
+        return
+
+    die("Not authenticated. Run `mcpheroctl auth login --token <TOKEN>`.", code=4)
+
+
+@auth_app.command("logout")
+def logout(
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Remove stored credentials.
+
+    Examples:
+        mcpheroctl auth logout
+        mcpheroctl auth logout --json
+    """
+    config: Config = load_config()
+    config.api_token = None
+    save_config(config)
+    if output_json:
+        print_result({"status": "logged_out"}, use_json=True)
+        return
+
+    success("Credentials removed.")

mcpheroctl-0.1.0/src/mcpheroctl/commands/server.py

@@ -0,0 +1,182 @@
+"""Server management commands for mcpheroctl."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from mcpheroctl.core.client import APIError, MCPHeroClient
+from mcpheroctl.core.output import (
+    EXIT_GENERAL_FAILURE,
+    EXIT_NOT_FOUND,
+    die,
+    print_result,
+    success,
+)
+
+server_app = typer.Typer(
+    name="server",
+    help="Manage MCP servers.",
+    no_args_is_help=True,
+    rich_markup_mode=None,
+)
+
+
+def _client() -> MCPHeroClient:
+    return MCPHeroClient()
+
+
+def _handle_api_error(exc: APIError, *, use_json: bool) -> None:
+    """Translate APIError into a structured exit."""
+    code = EXIT_GENERAL_FAILURE
+    error_type = "api_error"
+    if exc.status_code == 404:
+        code = EXIT_NOT_FOUND
+        error_type = "not_found"
+    elif exc.status_code in (401, 403):
+        code = 4
+        error_type = "permission_denied"
+    elif exc.status_code == 409:
+        code = 5
+        error_type = "conflict"
+    die(
+        exc.detail,
+        code=code,
+        error_type=error_type,
+        details={"status_code": exc.status_code},
+        use_json=use_json,
+    )
+
+
+@server_app.command("list")
+def list_servers(
+    customer_id: Annotated[
+        str | None,
+        typer.Argument(help="Customer UUID (optional when using org API key)."),
+    ] = None,
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """List all MCP servers for a customer.
+
+    When authenticated with an org API key, customer_id is optional and
+    defaults to your organization. With admin API key, customer_id is required.
+
+    Examples:
+        mcpheroctl server list
+        mcpheroctl server list 550e8400-e29b-41d4-a716-446655440000
+        mcpheroctl server list --json
+    """
+    try:
+        result = _client().list_servers(customer_id)
+        print_result(result, use_json=output_json)
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+@server_app.command("get")
+def get_server(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Get full details of an MCP server.
+
+    Examples:
+        mcpheroctl server get 550e8400-e29b-41d4-a716-446655440000
+        mcpheroctl server get 550e8400-e29b-41d4-a716-446655440000 --json
+    """
+    try:
+        result = _client().get_server(server_id)
+        print_result(result, use_json=output_json)
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+@server_app.command("delete")
+def delete_server(
+    server_id: Annotated[str, typer.Argument(help="Server UUID to delete.")],
+    yes: Annotated[
+        bool, typer.Option("--yes", "-y", help="Skip confirmation prompt.")
+    ] = False,
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Delete an MCP server and all its resources.
+
+    This is a destructive operation. Use --yes to skip the confirmation prompt
+    (required for non-interactive / agent usage).
+
+    Examples:
+        mcpheroctl server delete 550e8400-e29b-41d4-a716-446655440000 --yes
+        mcpheroctl server delete 550e8400-e29b-41d4-a716-446655440000 --yes --json
+    """
+    if not yes:
+        confirm = typer.confirm(f"Delete server {server_id}? This cannot be undone")
+        if not confirm:
+            raise typer.Abort()
+    try:
+        result = _client().delete_server(server_id)
+        if output_json:
+            print_result(result, use_json=True)
+        else:
+            success(f"Server {server_id} deleted.")
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+@server_app.command("update")
+def update_server(
+    server_id: Annotated[str, typer.Argument(help="Server UUID to update.")],
+    name: Annotated[str | None, typer.Option("--name", help="New server name.")] = None,
+    description: Annotated[
+        str | None, typer.Option("--description", help="New server description.")
+    ] = None,
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Update an MCP server's name or description.
+
+    Examples:
+        mcpheroctl server update 550e8400-... --name "My Server"
+        mcpheroctl server update 550e8400-... --description "Does X, Y, Z" --json
+    """
+    if name is None and description is None:
+        die(
+            "At least one of --name or --description is required.",
+            code=2,
+            use_json=output_json,
+        )
+    try:
+        result = _client().update_server(server_id, name=name, description=description)
+        if output_json:
+            print_result(result, use_json=True)
+        else:
+            success(f"Server {server_id} updated.")
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+@server_app.command("api-key")
+def get_api_key(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Get the API key for a server.
+
+    Examples:
+        mcpheroctl server api-key 550e8400-e29b-41d4-a716-446655440000
+        mcpheroctl server api-key 550e8400-e29b-41d4-a716-446655440000 --json
+    """
+    try:
+        result = _client().get_server_api_key(server_id)
+        print_result(result, use_json=output_json)
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)

mcpheroctl-0.1.0/src/mcpheroctl/commands/wizard.py

@@ -0,0 +1,521 @@
+"""Wizard commands for mcpheroctl.
+
+Covers the full MCP server creation wizard pipeline:
+  1. start         – create server and kick off tool suggestion
+  2. list-tools    – view suggested/current tools
+  3. refine-tools  – refine tools via LLM with feedback
+  4. submit-tools  – select tools to keep
+  5. suggest-env-vars – trigger env var suggestion
+  6. list-env-vars – view suggested env vars
+  7. refine-env-vars – refine env vars via LLM
+  8. submit-env-vars – provide env var values
+  9. set-auth      – generate bearer token
+ 10. generate-code – generate tool implementation code
+ 11. regenerate-tool-code – regenerate code for a single tool
+ 12. deploy        – deploy to shared runtime
+ 13. state         – poll current wizard state
+ 14. conversation  – (stub) interactive conversation (not yet on backend)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from mcpheroctl.core.client import APIError, MCPHeroClient
+from mcpheroctl.core.output import (
+    EXIT_GENERAL_FAILURE,
+    EXIT_NOT_FOUND,
+    EXIT_NOT_IMPLEMENTED,
+    die,
+    info,
+    print_result,
+    success,
+)
+
+wizard_app = typer.Typer(
+    name="wizard",
+    help="MCP server creation wizard pipeline.",
+    no_args_is_help=True,
+    rich_markup_mode=None,
+)
+
+
+def _client() -> MCPHeroClient:
+    return MCPHeroClient()
+
+
+def _handle_api_error(exc: APIError, *, use_json: bool) -> None:
+    """Translate APIError into a structured exit."""
+    code = EXIT_GENERAL_FAILURE
+    error_type = "api_error"
+    if exc.status_code == 404:
+        code = EXIT_NOT_FOUND
+        error_type = "not_found"
+    elif exc.status_code in (401, 403):
+        code = 4
+        error_type = "permission_denied"
+    elif exc.status_code == 409:
+        code = 5
+        error_type = "conflict"
+    die(
+        exc.detail,
+        code=code,
+        error_type=error_type,
+        details={"status_code": exc.status_code},
+        use_json=use_json,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Step 1: Start wizard
+# ---------------------------------------------------------------------------
+
+
+@wizard_app.command("start")
+def start(
+    spec: Annotated[
+        Path,
+        typer.Argument(
+            help="Path to a markdown file containing the system/server description.",
+            exists=True,
+            readable=True,
+        ),
+    ],
+    customer_id: Annotated[
+        str | None,
+        typer.Option(
+            "--customer-id",
+            "-c",
+            help="Customer UUID (optional when using org API key).",
+        ),
+    ] = None,
+    technical_details: Annotated[
+        list[Path] | None,
+        typer.Option(
+            "--technical-details",
+            "-d",
+            help="Path(s) to markdown files with technical details (API specs, schemas, etc.). Can be repeated.",
+            exists=True,
+            readable=True,
+        ),
+    ] = None,
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Start the MCP server creation wizard.
+
+    Reads the server description from a markdown spec file and optionally
+    accepts technical detail files. Triggers background tool suggestion.
+
+    When authenticated with an org API key, --customer-id is optional.
+
+    Examples:
+        mcpheroctl wizard start spec.md
+        mcpheroctl wizard start spec.md --customer-id 550e8400-e29b-41d4-a716-446655440000
+        mcpheroctl wizard start spec.md -d api_schema.md -d endpoints.md
+    """
+    description = spec.read_text()
+    tech_details: list[str] | None = None
+    if technical_details:
+        tech_details = [p.read_text() for p in technical_details]
+
+    try:
+        result = _client().wizard_start(description, customer_id, tech_details)
+        if output_json:
+            print_result(result, use_json=True)
+        else:
+            server_id = result.get("server_id", "unknown")
+            success(f"Wizard started. Server ID: {server_id}")
+            info(
+                "Tool suggestion is running in the background. Poll with `wizard state`."
+            )
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+# ---------------------------------------------------------------------------
+# Step 1 tools management
+# ---------------------------------------------------------------------------
+
+
+@wizard_app.command("list-tools")
+def list_tools(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """List current tools for a server in the wizard.
+
+    Examples:
+        mcpheroctl wizard list-tools SERVER_ID
+        mcpheroctl wizard list-tools SERVER_ID --json
+    """
+    try:
+        result = _client().wizard_get_tools(server_id)
+        print_result(result, use_json=output_json)
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+@wizard_app.command("refine-tools")
+def refine_tools(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    feedback: Annotated[
+        str, typer.Option("--feedback", "-f", help="Feedback text for LLM refinement.")
+    ],
+    tool_id: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--tool-id",
+            help="Tool UUID(s) to refine. Can be repeated. Omit to refine all.",
+        ),
+    ] = None,
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Refine suggested tools based on feedback.
+
+    Triggers an LLM refinement in the background. Pass --tool-id multiple
+    times to target specific tools, or omit to refine all.
+
+    Examples:
+        mcpheroctl wizard refine-tools SERVER_ID --feedback "Add a search tool"
+        mcpheroctl wizard refine-tools SERVER_ID -f "Split into two" --tool-id UUID1 --tool-id UUID2
+        mcpheroctl wizard refine-tools SERVER_ID -f "Simplify parameters" --json
+    """
+    try:
+        result = _client().wizard_refine_tools(server_id, feedback, tool_id)
+        if output_json:
+            print_result(result, use_json=True)
+        else:
+            success("Tool refinement started. Poll with `wizard state`.")
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+@wizard_app.command("submit-tools")
+def submit_tools(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    tool_id: Annotated[
+        list[str],
+        typer.Option("--tool-id", help="Tool UUID(s) to keep. Can be repeated."),
+    ],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Submit selected tools to proceed to env vars step.
+
+    Pass --tool-id for each tool to keep. Unselected tools are deleted.
+
+    Examples:
+        mcpheroctl wizard submit-tools SERVER_ID --tool-id UUID1 --tool-id UUID2
+        mcpheroctl wizard submit-tools SERVER_ID --tool-id UUID1 --json
+    """
+    try:
+        result = _client().wizard_submit_tools(server_id, tool_id)
+        if output_json:
+            print_result(result, use_json=True)
+        else:
+            success(f"Submitted {len(tool_id)} tool(s). Env var suggestion started.")
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+# ---------------------------------------------------------------------------
+# Step 2: Environment variables
+# ---------------------------------------------------------------------------
+
+
+@wizard_app.command("suggest-env-vars")
+def suggest_env_vars(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Trigger environment variable suggestion via LLM.
+
+    Examples:
+        mcpheroctl wizard suggest-env-vars SERVER_ID
+        mcpheroctl wizard suggest-env-vars SERVER_ID --json
+    """
+    try:
+        result = _client().wizard_suggest_env_vars(server_id)
+        if output_json:
+            print_result(result, use_json=True)
+        else:
+            success("Env var suggestion started. Poll with `wizard state`.")
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+@wizard_app.command("list-env-vars")
+def list_env_vars(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """List current environment variables for a server.
+
+    Examples:
+        mcpheroctl wizard list-env-vars SERVER_ID
+        mcpheroctl wizard list-env-vars SERVER_ID --json
+    """
+    try:
+        result = _client().wizard_get_env_vars(server_id)
+        print_result(result, use_json=output_json)
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+@wizard_app.command("refine-env-vars")
+def refine_env_vars(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    feedback: Annotated[
+        str, typer.Option("--feedback", "-f", help="Feedback text for LLM refinement.")
+    ],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Refine suggested environment variables based on feedback.
+
+    Triggers an LLM refinement in the background.
+
+    Examples:
+        mcpheroctl wizard refine-env-vars SERVER_ID -f "Combine DB vars into DATABASE_URL"
+        mcpheroctl wizard refine-env-vars SERVER_ID --feedback "Add API key var" --json
+    """
+    try:
+        result = _client().wizard_refine_env_vars(server_id, feedback)
+        if output_json:
+            print_result(result, use_json=True)
+        else:
+            success("Env var refinement started. Poll with `wizard state`.")
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+@wizard_app.command("submit-env-vars")
+def submit_env_vars(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    var: Annotated[
+        list[str],
+        typer.Option("--var", help="Env var value as VAR_UUID=VALUE. Can be repeated."),
+    ],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Submit environment variable values.
+
+    Pass --var for each variable in the format UUID=VALUE.
+
+    Examples:
+        mcpheroctl wizard submit-env-vars SERVER_ID --var "UUID1=sk-abc123" --var "UUID2=https://api.example.com"
+        mcpheroctl wizard submit-env-vars SERVER_ID --var "UUID1=value1" --json
+    """
+    values: dict[str, str] = {}
+    for v in var:
+        if "=" not in v:
+            die(
+                f"Invalid --var format: '{v}'. Expected VAR_UUID=VALUE.",
+                code=2,
+                use_json=output_json,
+            )
+        key, val = v.split("=", 1)
+        values[key.strip()] = val.strip()
+
+    try:
+        result = _client().wizard_submit_env_vars(server_id, values)
+        if output_json:
+            print_result(result, use_json=True)
+        else:
+            success(f"Submitted {len(values)} env var value(s).")
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+# ---------------------------------------------------------------------------
+# Step 3: Auth
+# ---------------------------------------------------------------------------
+
+
+@wizard_app.command("set-auth")
+def set_auth(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Set up bearer token authentication for the server.
+
+    Generates and returns a Bearer token.
+
+    Examples:
+        mcpheroctl wizard set-auth SERVER_ID
+        mcpheroctl wizard set-auth SERVER_ID --json
+    """
+    try:
+        result = _client().wizard_set_auth(server_id)
+        if output_json:
+            print_result(result, use_json=True)
+        else:
+            token = result.get("bearer_token", "")
+            success(f"Auth set. Bearer token: {token}")
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+# ---------------------------------------------------------------------------
+# Step 4: Code generation
+# ---------------------------------------------------------------------------
+
+
+@wizard_app.command("generate-code")
+def generate_code(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Trigger code generation for all tools.
+
+    Runs in the background. Poll with `wizard state` to check progress.
+
+    Examples:
+        mcpheroctl wizard generate-code SERVER_ID
+        mcpheroctl wizard generate-code SERVER_ID --json
+    """
+    try:
+        result = _client().wizard_generate_code(server_id)
+        if output_json:
+            print_result(result, use_json=True)
+        else:
+            success("Code generation started. Poll with `wizard state`.")
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+@wizard_app.command("regenerate-tool-code")
+def regenerate_tool_code(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    tool_id: Annotated[str, typer.Argument(help="Tool UUID to regenerate code for.")],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Regenerate code for a single tool (synchronous).
+
+    Waits for LLM to produce new code and returns it.
+
+    Examples:
+        mcpheroctl wizard regenerate-tool-code SERVER_ID TOOL_ID
+        mcpheroctl wizard regenerate-tool-code SERVER_ID TOOL_ID --json
+    """
+    try:
+        result = _client().wizard_regenerate_tool_code(server_id, tool_id)
+        if output_json:
+            print_result(result, use_json=True)
+        else:
+            success(f"Code regenerated for tool {tool_id}.")
+            code = result.get("code", "")
+            if code:
+                info(f"Generated code:\n{code}")
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+# ---------------------------------------------------------------------------
+# Step 5: Deploy
+# ---------------------------------------------------------------------------
+
+
+@wizard_app.command("deploy")
+def deploy(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Deploy the MCP server to the shared runtime.
+
+    Examples:
+        mcpheroctl wizard deploy SERVER_ID
+        mcpheroctl wizard deploy SERVER_ID --json
+    """
+    try:
+        result = _client().wizard_deploy(server_id)
+        if output_json:
+            print_result(result, use_json=True)
+        else:
+            url = result.get("server_url", "")
+            success(f"Deployed! Endpoint: {url}")
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+# ---------------------------------------------------------------------------
+# State polling
+# ---------------------------------------------------------------------------
+
+
+@wizard_app.command("state")
+def state(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Get the current wizard state for a server.
+
+    Useful for polling during background operations (tool suggestion,
+    code generation, etc.).
+
+    Examples:
+        mcpheroctl wizard state SERVER_ID
+        mcpheroctl wizard state SERVER_ID --json
+    """
+    try:
+        result = _client().wizard_get_state(server_id)
+        print_result(result, use_json=output_json)
+    except APIError as exc:
+        _handle_api_error(exc, use_json=output_json)
+
+
+# ---------------------------------------------------------------------------
+# Conversation (stub – frontend-only for now)
+# ---------------------------------------------------------------------------
+
+
+@wizard_app.command("conversation")
+def conversation(
+    server_id: Annotated[str, typer.Argument(help="Server UUID.")],
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Output result as JSON.")
+    ] = False,
+) -> None:
+    """Start an interactive conversation with the wizard.
+
+    NOTE: This feature currently only exists on the frontend and has not yet
+    been migrated to the backend API. This command will be implemented once
+    the backend endpoint is available.
+
+    Examples:
+        mcpheroctl wizard conversation SERVER_ID
+    """
+    die(
+        "The conversation feature is not yet implemented on the backend.",
+        code=EXIT_NOT_IMPLEMENTED,
+        error_type="not_implemented",
+        details={"feature": "wizard_conversation", "server_id": server_id},
+        use_json=output_json,
+    )

mcpheroctl-0.1.0/src/mcpheroctl/core/client.py

@@ -0,0 +1,199 @@
+"""HTTP client for the MCPHero API.
+
+Uses httpx with tenacity retry logic for transient failures.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from httpx._client import Client
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from mcpheroctl.core.config import get_base_url, require_token
+
+# Retry on transient network / 5xx errors
+_RETRYABLE_STATUS_CODES = frozenset(range(500, 600))
+
+# Default timeout for API calls (seconds)
+_TIMEOUT = httpx.Timeout(30.0, connect=10.0)
+
+
+class APIError(Exception):
+    """Raised when the API returns an error response."""
+
+    def __init__(self, status_code: int, detail: str, body: Any = None) -> None:
+        self.status_code: int = status_code
+        self.detail: str = detail
+        self.body: Any = body
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+def _build_client(token: str, base_url: str) -> httpx.Client:
+    return httpx.Client(
+        base_url=base_url,
+        headers={
+            "Authorization": f"Bearer {token}",
+        },
+        timeout=_TIMEOUT,
+        follow_redirects=True,
+    )
+
+
+def _handle_response(response: httpx.Response) -> Any:
+    """Parse the response, raising APIError on non-2xx codes."""
+    if response.is_success:
+        if response.headers.get("content-type", "").startswith("application/json"):
+            return response.json()
+        return response.text
+    # Try to extract detail from JSON body
+    detail: str = response.text
+    try:
+        body = response.json()
+        if isinstance(body, dict):
+            detail = body.get("detail", detail)
+    except Exception:
+        body = None
+    raise APIError(response.status_code, detail, body)
+
+
+class MCPHeroClient:
+    """Synchronous HTTP client for the MCPHero backend API."""
+
+    def __init__(
+        self, *, token: str | None = None, base_url: str | None = None
+    ) -> None:
+        self._token: str = token or require_token()
+        self._base_url: str = base_url or get_base_url()
+        self._client: Client = _build_client(self._token, self._base_url)
+
+    # ------------------------------------------------------------------
+    # Low-level request helpers with retry
+    # ------------------------------------------------------------------
+
+    @retry(
+        retry=retry_if_exception_type((httpx.TransportError, APIError)),
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=0.5, min=0.5, max=5),
+        reraise=True,
+    )
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        response = self._client.request(method, path, **kwargs)
+        return _handle_response(response)
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self._request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self._request("POST", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> Any:
+        return self._request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self._request("DELETE", path, **kwargs)
+
+    # ------------------------------------------------------------------
+    # Server endpoints
+    # ------------------------------------------------------------------
+
+    def list_servers(self, customer_id: str | None = None) -> Any:
+        """List MCP servers. When using org API key, customer_id is optional."""
+        if customer_id is not None:
+            return self.get(f"/servers/list/{customer_id}")
+        return self.get("/servers/list")
+
+    def get_server(self, server_id: str) -> Any:
+        return self.get(f"/servers/{server_id}/details")
+
+    def delete_server(self, server_id: str) -> Any:
+        return self.delete(f"/servers/{server_id}")
+
+    def update_server(
+        self, server_id: str, *, name: str | None = None, description: str | None = None
+    ) -> Any:
+        body: dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        return self.patch(f"/servers/{server_id}", json=body)
+
+    def get_server_api_key(self, server_id: str) -> Any:
+        return self.get(f"/servers/{server_id}/api-key")
+
+    # ------------------------------------------------------------------
+    # Wizard endpoints
+    # ------------------------------------------------------------------
+
+    def wizard_start(
+        self,
+        description: str,
+        customer_id: str | None = None,
+        technical_details: list[str] | None = None,
+    ) -> Any:
+        body: dict[str, Any] = {"description": description}
+        if customer_id is not None:
+            body["customer_id"] = customer_id
+        if technical_details:
+            body["technical_details"] = technical_details
+        return self.post("/wizard/start", json=body)
+
+    def wizard_get_tools(self, server_id: str) -> Any:
+        return self.get(f"/wizard/{server_id}/tools")
+
+    def wizard_refine_tools(
+        self,
+        server_id: str,
+        feedback: str,
+        tool_ids: list[str] | None = None,
+    ) -> Any:
+        body: dict[str, Any] = {"feedback": feedback}
+        if tool_ids:
+            body["tool_ids"] = tool_ids
+        return self.post(f"/wizard/{server_id}/tools/refine", json=body)
+
+    def wizard_submit_tools(self, server_id: str, selected_tool_ids: list[str]) -> Any:
+        return self.post(
+            f"/wizard/{server_id}/tools/submit",
+            json={"selected_tool_ids": selected_tool_ids},
+        )
+
+    def wizard_suggest_env_vars(self, server_id: str) -> Any:
+        return self.post(f"/wizard/{server_id}/env-vars/suggest")
+
+    def wizard_get_env_vars(self, server_id: str) -> Any:
+        return self.get(f"/wizard/{server_id}/env-vars")
+
+    def wizard_refine_env_vars(self, server_id: str, feedback: str) -> Any:
+        return self.post(
+            f"/wizard/{server_id}/env-vars/refine",
+            json={"feedback": feedback},
+        )
+
+    def wizard_submit_env_vars(self, server_id: str, values: dict[str, str]) -> Any:
+        return self.post(
+            f"/wizard/{server_id}/env-vars/submit",
+            json={"values": values},
+        )
+
+    def wizard_set_auth(self, server_id: str) -> Any:
+        return self.post(f"/wizard/{server_id}/auth")
+
+    def wizard_generate_code(self, server_id: str) -> Any:
+        return self.post(f"/wizard/{server_id}/generate-code")
+
+    def wizard_regenerate_tool_code(self, server_id: str, tool_id: str) -> Any:
+        return self.post(f"/wizard/{server_id}/tools/{tool_id}/regenerate-code")
+
+    def wizard_deploy(self, server_id: str) -> Any:
+        return self.post(f"/wizard/{server_id}/deploy")
+
+    def wizard_get_state(self, server_id: str) -> Any:
+        return self.get(f"/wizard/{server_id}/state")

mcpheroctl-0.1.0/src/mcpheroctl/core/config.py

@@ -0,0 +1,59 @@
+"""Configuration management for mcpheroctl.
+
+Handles reading/writing the API token and base URL to
+~/.config/mcpheroctl/config.json.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+from pydantic import BaseModel
+
+CONFIG_DIR = Path.home() / ".config" / "mcpheroctl"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+# Default base URL for the MCPHero API
+DEFAULT_BASE_URL = "https://api.mcphero.app/api"
+
+
+class Config(BaseModel):
+    """Persisted CLI configuration."""
+
+    api_token: str | None = None
+    base_url: str = DEFAULT_BASE_URL
+
+
+def load_config() -> Config:
+    """Load configuration from disk. Returns defaults if file does not exist."""
+    if not CONFIG_FILE.exists():
+        return Config()
+    try:
+        data = json.loads(CONFIG_FILE.read_text())
+        return Config.model_validate(data)
+    except (json.JSONDecodeError, ValueError) as exc:
+        print(f"Warning: corrupt config at {CONFIG_FILE}: {exc}", file=sys.stderr)
+        return Config()
+
+
+def save_config(config: Config) -> None:
+    """Persist configuration to disk."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    _ = CONFIG_FILE.write_text(config.model_dump_json(indent=2) + "\n")
+
+
+def require_token() -> str:
+    """Return the stored API token or exit with an error message."""
+    config = load_config()
+    if not config.api_token:
+        print(
+            "Error: not authenticated. Run `mcpheroctl auth login --token <TOKEN>` first.",
+            file=sys.stderr,
+        )
+        raise SystemExit(4)  # exit code 4 = permission denied / not authenticated
+    return config.api_token
+
+
+def get_base_url() -> str:
+    """Return the configured API base URL."""
+    return load_config().base_url

mcpheroctl-0.1.0/src/mcpheroctl/core/output.py

@@ -0,0 +1,103 @@
+"""Structured output helpers for agent-first CLI design.
+
+Rules:
+- JSON to stdout, everything else to stderr.
+- Meaningful exit codes (not just 0/1).
+- Actionable error messages with error codes.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, NoReturn
+
+from rich.console import Console
+
+# Rich console for human-readable stderr messages
+err_console = Console(stderr=True)
+
+# ---------------------------------------------------------------------------
+# Exit codes (documented in --help)
+# ---------------------------------------------------------------------------
+EXIT_SUCCESS = 0
+EXIT_GENERAL_FAILURE = 1
+EXIT_USAGE_ERROR = 2
+EXIT_NOT_FOUND = 3
+EXIT_PERMISSION_DENIED = 4
+EXIT_CONFLICT = 5
+EXIT_NOT_IMPLEMENTED = 6
+
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+
+
+def print_json(data: Any) -> None:
+    """Print structured JSON to stdout."""
+    if hasattr(data, "model_dump"):
+        data = data.model_dump(mode="json")
+    json.dump(data, sys.stdout, indent=2, default=str)
+    _ = sys.stdout.write("\n")  # noqa: F821
+
+
+def print_result(data: Any, *, use_json: bool) -> None:
+    """Print *data* as JSON (stdout) or as a human table (stderr).
+
+    When *use_json* is False we still pretty-print via Rich to stderr so that
+    stdout stays clean for piping.
+    """
+    if use_json:
+        print_json(data)
+    else:
+        if hasattr(data, "model_dump"):
+            data = data.model_dump(mode="json")
+        err_console.print_json(data=data)
+
+
+def info(message: str) -> None:
+    """Print an informational message to stderr."""
+    err_console.print(f"[bold blue]ℹ[/] {message}")
+
+
+def success(message: str) -> None:
+    """Print a success message to stderr."""
+    err_console.print(f"[bold green]✔[/] {message}")
+
+
+def warn(message: str) -> None:
+    """Print a warning message to stderr."""
+    err_console.print(f"[bold yellow]⚠[/] {message}")
+
+
+def error_msg(message: str) -> None:
+    """Print an error message to stderr (does not exit)."""
+    err_console.print(f"[bold red]✖[/] {message}")
+
+
+def die(
+    message: str,
+    *,
+    code: int = EXIT_GENERAL_FAILURE,
+    error_type: str | None = None,
+    details: dict[str, Any] | None = None,
+    use_json: bool = False,
+) -> NoReturn:
+    """Print an error and exit with the given code.
+
+    When *use_json* is True, a structured error object is emitted to stdout
+    (matching agent-first guidelines rule 7).
+    """
+    if use_json:
+        payload: dict[str, Any] = {
+            "error": error_type or "error",
+            "message": message,
+        }
+        if details:
+            payload.update(details)
+        print_json(payload)
+    else:
+        error_msg(message)
+
+    raise SystemExit(code)