cited-cli 0.3.2__py3-none-any.whl

cited_cli/mcp/tools/audit.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_cli.api import endpoints
+from cited_cli.mcp.context import CitedContext
+from cited_cli.mcp.server import mcp
+from cited_cli.mcp.tools._helpers import _api_error_response, _auth_check, _get_ctx
+from cited_cli.utils.errors import CitedAPIError
+
+
+@mcp.tool()
+async def list_audit_templates(ctx: Context[Any, CitedContext, Any]) -> Any:
+    """List all audit templates (named audits) for the user."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.NAMED_AUDITS)
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def get_audit_template(ctx: Context[Any, CitedContext, Any], named_audit_id: str) -> Any:
+    """Get a specific audit template by ID."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(
+            endpoints.NAMED_AUDIT.format(named_audit_id=named_audit_id)
+        )
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def create_audit_template(
+    ctx: Context[Any, CitedContext, Any],
+    name: str,
+    business_id: str,
+    description: str | None = None,
+    questions: list[str] | None = None,
+) -> Any:
+    """Create a new audit template.
+
+    Args:
+        ctx: MCP context
+        name: Template name
+        business_id: Business ID to associate with
+        description: Optional template description
+        questions: Optional list of audit questions
+    """
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    payload: dict[str, Any] = {"name": name, "business_id": business_id}
+    if description is not None:
+        payload["description"] = description
+    if questions is not None:
+        payload["questions"] = questions
+    try:
+        return cited_ctx.client.post(endpoints.NAMED_AUDITS, json=payload)
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def start_audit(
+    ctx: Context[Any, CitedContext, Any],
+    named_audit_id: str,
+    business_id: str | None = None,
+) -> Any:
+    """Start an audit using a template. Returns a job_id to poll for status.
+
+    Args:
+        ctx: MCP context
+        named_audit_id: The audit template ID to run
+        business_id: Optional business ID override
+    """
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    payload: dict[str, Any] = {"named_audit_id": named_audit_id}
+    if business_id is not None:
+        payload["business_id"] = business_id
+    try:
+        return cited_ctx.client.post(endpoints.AUDIT_START, json=payload)
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def get_audit_status(ctx: Context[Any, CitedContext, Any], job_id: str) -> Any:
+    """Check the status of a running audit job."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.AUDIT_STATUS.format(job_id=job_id))
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def get_audit_result(ctx: Context[Any, CitedContext, Any], job_id: str) -> Any:
+    """Get the results of a completed audit job."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.AUDIT_RESULT.format(job_id=job_id))
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def list_audits(ctx: Context[Any, CitedContext, Any]) -> Any:
+    """List audit history."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.AUDIT_HISTORY)
+    except CitedAPIError as e:
+        return _api_error_response(e)

cited_cli/mcp/tools/auth.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_cli.api import endpoints
+from cited_cli.mcp.context import CitedContext
+from cited_cli.mcp.server import mcp
+from cited_cli.mcp.tools._helpers import _api_error_response, _auth_check, _get_ctx
+from cited_cli.utils.errors import CitedAPIError
+
+
+@mcp.tool()
+async def check_auth_status(ctx: Context[Any, CitedContext, Any]) -> Any:
+    """Check if the user is authenticated and return their account info."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.ME)
+    except CitedAPIError as e:
+        return _api_error_response(e)

cited_cli/mcp/tools/business.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_cli.api import endpoints
+from cited_cli.mcp.context import CitedContext
+from cited_cli.mcp.server import mcp
+from cited_cli.mcp.tools._helpers import _api_error_response, _auth_check, _get_ctx
+from cited_cli.utils.errors import CitedAPIError
+
+
+@mcp.tool()
+async def list_businesses(ctx: Context[Any, CitedContext, Any]) -> Any:
+    """List all businesses for the authenticated user."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.BUSINESSES)
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def get_business(ctx: Context[Any, CitedContext, Any], business_id: str) -> Any:
+    """Get details for a specific business by ID."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.BUSINESS.format(business_id=business_id))
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def create_business(
+    ctx: Context[Any, CitedContext, Any],
+    name: str,
+    website: str,
+    description: str,
+    industry: str = "technology",
+) -> Any:
+    """Create a new business.
+
+    Args:
+        ctx: MCP context
+        name: Business name
+        website: Business website (must be a publicly DNS-resolvable domain)
+        description: Business description (minimum ~50 characters)
+        industry: One of: automotive, beauty, consulting, education, entertainment,
+            finance, fitness, government, healthcare, home_services, hospitality,
+            legal, manufacturing, non_profit, real_estate, restaurant, retail,
+            technology, other
+    """
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.post(
+            endpoints.BUSINESSES,
+            json={
+                "name": name,
+                "website": website,
+                "description": description,
+                "industry": industry,
+            },
+        )
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def crawl_business(ctx: Context[Any, CitedContext, Any], business_id: str) -> Any:
+    """Start a crawl job for a business. Returns a job_id you can poll with get_job_status."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.post(endpoints.CRAWL_START.format(business_id=business_id))
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def get_health_scores(ctx: Context[Any, CitedContext, Any], business_id: str) -> Any:
+    """Get GEO health scores for a business."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.HEALTH_SCORES.format(business_id=business_id))
+    except CitedAPIError as e:
+        return _api_error_response(e)

cited_cli/mcp/tools/job.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_cli.api import endpoints
+from cited_cli.mcp.context import CitedContext
+from cited_cli.mcp.server import mcp
+from cited_cli.mcp.tools._helpers import _api_error_response, _auth_check, _get_ctx
+from cited_cli.utils.errors import CitedAPIError
+
+_STATUS_ENDPOINTS = {
+    "audit": endpoints.AUDIT_STATUS,
+    "recommendation": endpoints.RECOMMEND_STATUS,
+    "solution": endpoints.SOLUTION_STATUS,
+}
+
+
+@mcp.tool()
+async def get_job_status(
+    ctx: Context[Any, CitedContext, Any],
+    job_id: str,
+    job_type: str | None = None,
+) -> Any:
+    """Get the status of any job by ID.
+
+    Args:
+        ctx: MCP context
+        job_id: The job ID to check
+        job_type: Optional job type hint: audit, recommendation, or solution.
+            If not provided, will probe each type until one responds.
+    """
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+
+    if job_type and job_type in _STATUS_ENDPOINTS:
+        try:
+            result = cited_ctx.client.get(
+                _STATUS_ENDPOINTS[job_type].format(job_id=job_id)
+            )
+            result["job_type"] = job_type
+            return result
+        except CitedAPIError as e:
+            return _api_error_response(e)
+
+    # Probe each type
+    for jtype, endpoint_tpl in _STATUS_ENDPOINTS.items():
+        try:
+            result = cited_ctx.client.get(endpoint_tpl.format(job_id=job_id))
+            result["job_type"] = jtype
+            return result
+        except CitedAPIError:
+            continue
+
+    return {"error": True, "message": f"No job found with ID: {job_id}"}

cited_cli/mcp/tools/recommend.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_cli.api import endpoints
+from cited_cli.mcp.context import CitedContext
+from cited_cli.mcp.server import mcp
+from cited_cli.mcp.tools._helpers import _api_error_response, _auth_check, _get_ctx
+from cited_cli.utils.errors import CitedAPIError
+
+
+@mcp.tool()
+async def start_recommendation(ctx: Context[Any, CitedContext, Any], audit_job_id: str) -> Any:
+    """Start a recommendation job based on a completed audit.
+
+    Args:
+        ctx: MCP context
+        audit_job_id: The completed audit job ID to generate recommendations for
+    """
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.post(
+            endpoints.RECOMMEND_START,
+            json={"audit_job_id": audit_job_id},
+        )
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def get_recommendation_status(ctx: Context[Any, CitedContext, Any], job_id: str) -> Any:
+    """Check the status of a recommendation job."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.RECOMMEND_STATUS.format(job_id=job_id))
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def get_recommendation_result(ctx: Context[Any, CitedContext, Any], job_id: str) -> Any:
+    """Get the full results of a completed recommendation job."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.RECOMMEND_RESULT.format(job_id=job_id))
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def get_recommendation_insights(ctx: Context[Any, CitedContext, Any], job_id: str) -> Any:
+    """Get actionable insights from a recommendation, with source_type and source_id for solutions.
+
+    Returns question_insights, head_to_head_comparisons, strengthening_tips, and
+    priority_actions, each annotated with the source_type and source_id needed to
+    start a solution via start_solution.
+    """
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        result = cited_ctx.client.get(endpoints.RECOMMEND_RESULT.format(job_id=job_id))
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+    insights: dict[str, Any] = {}
+
+    for item in result.get("question_insights", []):
+        item["source_type"] = "question_insight"
+        item["source_id"] = item.get("question_id", "")
+    insights["question_insights"] = result.get("question_insights", [])
+
+    for item in result.get("head_to_head_comparisons", []):
+        item["source_type"] = "head_to_head"
+        item["source_id"] = item.get("competitor_domain", "")
+    insights["head_to_head_comparisons"] = result.get("head_to_head_comparisons", [])
+
+    for item in result.get("strengthening_tips", []):
+        item["source_type"] = "strengthening_tip"
+        item["source_id"] = item.get("category", "")
+    insights["strengthening_tips"] = result.get("strengthening_tips", [])
+
+    for item in result.get("priority_actions", []):
+        item["source_type"] = "priority_action"
+        item["source_id"] = item.get("id", item.get("category", ""))
+    insights["priority_actions"] = result.get("priority_actions", [])
+
+    return insights

cited_cli/mcp/tools/solution.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_cli.api import endpoints
+from cited_cli.mcp.context import CitedContext
+from cited_cli.mcp.server import mcp
+from cited_cli.mcp.tools._helpers import _api_error_response, _auth_check, _get_ctx
+from cited_cli.utils.errors import CitedAPIError
+
+
+@mcp.tool()
+async def start_solution(
+    ctx: Context[Any, CitedContext, Any],
+    recommendation_job_id: str,
+    source_type: str,
+    source_id: str,
+) -> Any:
+    """Start generating a solution for a specific recommendation insight.
+
+    Args:
+        ctx: MCP context
+        recommendation_job_id: The recommendation job ID
+        source_type: One of: question_insight, head_to_head, strengthening_tip, priority_action
+        source_id: The source identifier (question_id, competitor_domain, category, etc.)
+    """
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.post(
+            endpoints.SOLUTION_REQUEST,
+            json={
+                "recommendation_job_id": recommendation_job_id,
+                "source_type": source_type,
+                "source_id": source_id,
+            },
+        )
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def get_solution_status(ctx: Context[Any, CitedContext, Any], job_id: str) -> Any:
+    """Check the status of a solution generation job."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.SOLUTION_STATUS.format(job_id=job_id))
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def get_solution_result(ctx: Context[Any, CitedContext, Any], job_id: str) -> Any:
+    """Get the results of a completed solution generation job."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.SOLUTION_RESULT.format(job_id=job_id))
+    except CitedAPIError as e:
+        return _api_error_response(e)

cited_cli/output/formatter.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from rich.console import Console
+
+
+@dataclass
+class OutputContext:
+    json_mode: bool = False
+    quiet: bool = False
+    no_color: bool = False
+    _console: Console | None = field(default=None, repr=False)
+
+    @property
+    def console(self) -> Console:
+        if self._console is None:
+            self._console = Console(
+                no_color=self.no_color,
+                quiet=self.quiet and not self.json_mode,
+            )
+        return self._console
+
+
+def print_result(
+    data: Any,
+    ctx: OutputContext,
+    human_formatter: Callable[[Any, Console], None] | None = None,
+) -> None:
+    if ctx.json_mode:
+        sys.stdout.write(json.dumps(data, indent=2, default=str) + "\n")
+    elif human_formatter:
+        human_formatter(data, ctx.console)
+    else:
+        ctx.console.print_json(json.dumps(data, default=str))
+
+
+def print_success(message: str, ctx: OutputContext) -> None:
+    if ctx.json_mode:
+        sys.stdout.write(json.dumps({"status": "ok", "message": message}) + "\n")
+    elif not ctx.quiet:
+        ctx.console.print(f"[green]✓[/green] {message}")
+
+
+def print_error(message: str, ctx: OutputContext, status_code: int | None = None) -> None:
+    if ctx.json_mode:
+        err: dict[str, Any] = {"error": True, "message": message}
+        if status_code:
+            err["status_code"] = status_code
+        sys.stderr.write(json.dumps(err) + "\n")
+    else:
+        Console(stderr=True).print(f"[red]Error:[/red] {message}")
+
+
+def print_warning(message: str, ctx: OutputContext) -> None:
+    if not ctx.json_mode and not ctx.quiet:
+        ctx.console.print(f"[yellow]Warning:[/yellow] {message}")

cited_cli/output/progress.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import time
+
+from rich.console import Console
+from rich.live import Live
+from rich.spinner import Spinner
+from rich.text import Text
+
+from cited_cli.utils.errors import CitedAPIError
+from cited_core.api.client import CitedClient
+
+
+def watch_job(
+    client: CitedClient,
+    status_path: str,
+    console: Console | None = None,
+    poll_interval: float = 2.0,
+) -> dict[str, object]:
+    """Poll a job status endpoint until completion. Returns the final status response."""
+    c = console or Console()
+
+    with Live(Spinner("dots", text="Starting..."), console=c, refresh_per_second=4) as live:
+        while True:
+            try:
+                data = client.get(status_path)
+            except CitedAPIError:
+                raise
+
+            status = data.get("status", "unknown")
+            progress = data.get("progress")
+            message = data.get("message", "")
+
+            if progress is not None:
+                pct = (
+                    int(progress * 100)
+                    if isinstance(progress, float) and progress <= 1
+                    else int(progress)
+                )
+                bar_w = 20
+                filled = int((pct / 100) * bar_w)
+                bar = f"{'█' * filled}{'░' * (bar_w - filled)}"
+                text = Text.from_markup(
+                    f"[cyan]{bar}[/cyan] {pct}% — {status} {message}"
+                )
+            else:
+                text = Text.from_markup(f"[cyan]⟳[/cyan] {status} {message}")
+
+            live.update(Spinner("dots", text=text))
+
+            if status in ("completed", "complete", "done", "failed", "error", "cancelled"):
+                break
+
+            time.sleep(poll_interval)
+
+    return data  # type: ignore[no-any-return]

cited_cli/output/tables.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+
+def render_table(
+    title: str,
+    columns: list[str],
+    rows: list[list[Any]],
+    console: Console | None = None,
+) -> None:
+    c = console or Console()
+    table = Table(title=title, show_header=True, header_style="bold cyan")
+    for col in columns:
+        table.add_column(col)
+    for row in rows:
+        table.add_row(*[str(v) for v in row])
+    c.print(table)
+
+
+def render_kv(
+    title: str,
+    items: dict[str, Any],
+    console: Console | None = None,
+) -> None:
+    c = console or Console()
+    lines = []
+    for key, value in items.items():
+        lines.append(f"[bold]{key}:[/bold] {value}")
+    panel = Panel("\n".join(lines), title=title, border_style="cyan")
+    c.print(panel)
+
+
+def render_bar(
+    label: str,
+    value: int | float,
+    max_value: int | float = 100,
+    console: Console | None = None,
+) -> None:
+    c = console or Console()
+    bar_width = 20
+    filled = int((value / max_value) * bar_width) if max_value > 0 else 0
+    empty = bar_width - filled
+    bar = f"[green]{'█' * filled}[/green][dim]{'░' * empty}[/dim]"
+    c.print(f"  {label:<25} {bar}  {value:.0f}%")

cited_cli/utils/errors.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import sys
+
+from rich.console import Console
+
+from cited_core.errors import CitedAPIError as CitedAPIError  # noqa: F401
+from cited_core.errors import ExitCode as ExitCode  # noqa: F401
+from cited_core.errors import exit_code_for_status as exit_code_for_status  # noqa: F401
+
+err_console = Console(stderr=True)
+
+
+def handle_api_error(error: CitedAPIError, json_mode: bool = False) -> None:
+    code = exit_code_for_status(error.status_code)
+    if json_mode:
+        import json
+
+        err_console.print(
+            json.dumps(
+                {
+                    "error": True,
+                    "status_code": error.status_code,
+                    "message": error.message,
+                    "error_code": error.error_code,
+                }
+            )
+        )
+    else:
+        err_console.print(f"[red]Error[/red] ({error.status_code}): {error.message}")
+    sys.exit(code)