cited-cli 0.5.1__tar.gz → 0.5.2__tar.gz

{cited_cli-0.5.1 → cited_cli-0.5.2}/PKG-INFO

@@ -1,23 +1,23 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: cited-cli
-Version: 0.5.1
+Version: 0.5.2
 Summary: CLI for the Cited GEO platform
 Author-email: Cited <support@youcited.com>
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 Requires-Python: >=3.11
-Requires-Dist: cited-core>=0.5.1
+Requires-Dist: cited-core>=0.5.2
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.15.0
 Provides-Extra: dev
-Requires-Dist: cited-mcp>=0.5.1; extra == 'dev'
+Requires-Dist: cited-mcp>=0.5.2; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
 Provides-Extra: mcp
-Requires-Dist: cited-mcp>=0.5.1; extra == 'mcp'
+Requires-Dist: cited-mcp>=0.5.2; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # Cited CLI

{cited_cli-0.5.1 → cited_cli-0.5.2}/packages/core/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cited-core"
-version = "0.5.1"
+version = "0.5.2"
 description = "Core library for the Cited GEO platform"
 license = "LicenseRef-Proprietary"
 requires-python = ">=3.11"

cited_cli-0.5.2/packages/core/src/cited_core/__init__.py

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

{cited_cli-0.5.1 → cited_cli-0.5.2}/packages/core/src/cited_core/api/client.py

@@ -72,8 +72,16 @@ class CitedClient:
             message = response.text or message
         raise CitedAPIError(response.status_code, str(message), error_code)
 
-    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
-        response = self._client.get(path, params=params)
+    def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        kwargs: dict[str, Any] = {"params": params}
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        response = self._client.get(path, **kwargs)
         return self._handle_response(response)
 
     def post(

{cited_cli-0.5.1 → cited_cli-0.5.2}/packages/core/src/cited_core/api/endpoints.py

@@ -43,6 +43,10 @@ AUDIT_EXPORT_PDF = "/audit/{job_id}/export/pdf"
 AUDIT_EXPORT_URL = "/audit/{job_id}/export/url"
 AUDIT_HISTORY = "/audit/history"
 AUDIT_CANCEL = "/audit/{job_id}/cancel"
+
+# Free audit (no login; same audit the youcited.com homepage prompt runs)
+FREE_AUDIT = "/free-audit"
+FREE_AUDIT_REPORT = "/free-audit/report/{token}"
 AUDIT_DELETE = "/audit/{job_id}"
 AUDIT_PROVIDERS = "/audit/{job_id}/providers"
 AUDIT_QUESTION_DETAIL = "/audit/{job_id}/question/{question_id}"

cited_cli-0.5.2/packages/core/src/cited_core/free_audit.py

@@ -0,0 +1,39 @@
+"""Free audit: the no-login GEO audit behind the youcited.com homepage prompt.
+
+``GET /free-audit?url=...`` starts an audit (or returns the one already run for
+that domain in the last 24 hours) and hands back a ``report_url``. Fetching the
+report returns status while the audit runs and the full report once it is done.
+Neither call needs a token, so these work before the user has an account.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cited_core.api import endpoints
+from cited_core.api.client import LONG_TIMEOUT, CitedClient
+
+
+def report_token(report_url: str) -> str:
+    """Extract the report token from a ``report_url`` returned by the API."""
+    return report_url.rstrip("/").rsplit("/", 1)[-1]
+
+
+def check_free_audit(client: CitedClient, url: str) -> dict[str, Any]:
+    """Start (or resume) the free audit for ``url`` and return its current report.
+
+    Safe to call repeatedly: the API reuses the same audit for a domain, so
+    calling again later returns progress or, once complete, the full report.
+    """
+    # Starting a new audit generates its questions in-request, which can be slow.
+    started = client.get(endpoints.FREE_AUDIT, params={"url": url}, timeout=LONG_TIMEOUT)
+    token = report_token(started["report_url"])
+    report: dict[str, Any] = client.get(endpoints.FREE_AUDIT_REPORT.format(token=token))
+    report.setdefault("report_url", started["report_url"])
+    report.setdefault("share_url", started.get("share_url"))
+    report.setdefault("domain", started.get("domain"))
+    return report
+
+
+def is_finished(report: dict[str, Any]) -> bool:
+    return report.get("status") not in ("pending", "processing")

{cited_cli-0.5.1 → cited_cli-0.5.2}/packages/mcp/README.md

@@ -1,6 +1,6 @@
 # cited-mcp
 
-MCP server for the [Cited](https://youcited.com) Generative Engine Optimization (GEO) platform. Exposes 73 tools that let AI assistants like Claude manage businesses, run GEO audits, generate recommendations, work a prioritized action plan, verify fixes via the Validation Engine, and create solutions — all through the [Model Context Protocol](https://modelcontextprotocol.io/).
+MCP server for the [Cited](https://youcited.com) Generative Engine Optimization (GEO) platform. Exposes 74 tools that let AI assistants like Claude manage businesses, run GEO audits, generate recommendations, work a prioritized action plan, verify fixes via the Validation Engine, and create solutions — all through the [Model Context Protocol](https://modelcontextprotocol.io/).
 
 ## Install
 
@@ -146,6 +146,7 @@ Cited adds new tools regularly. To access new tools after a release, **disconnec
 ### Audits
 | Tool | Description |
 |------|-------------|
+| `free_audit` | Free GEO audit of any website, no login needed. Call again with the same URL for progress and the full report |
 | `start_audit` | Run a GEO audit using a template |
 | `get_audit_status` | Check audit job status |
 | `get_audit_result` | Get completed audit results |
@@ -231,9 +232,9 @@ Tools are gated by subscription tier. All tiers can read data; write operations
 
 | Tier | Tools Available |
 |------|----------------|
-| **Growth** (entry) | Auth, list/get businesses, crawl, health scores, audits (start/status/result/list), all recommendation tools, action-plan reads (get_action_plan, get_quick_wins), Validation Engine reads, job status — **31 tools** |
-| **Scale** | Everything in Growth + create/update/delete businesses, create/update/delete audit templates, all solution tools, batch solutions, export audit, cancel job, action-plan writes (mark_action_done, dismiss_action, get_action_progress) — **62 tools** |
-| **Pro** | Everything in Scale + usage stats, HQ dashboard, analytics, agent API — **73 tools** |
+| **Growth** (entry) | Auth, list/get businesses, crawl, health scores, audits (start/status/result/list), all recommendation tools, action-plan reads (get_action_plan, get_quick_wins), Validation Engine reads, job status, free audit — **32 tools** |
+| **Scale** | Everything in Growth + create/update/delete businesses, create/update/delete audit templates, all solution tools, batch solutions, export audit, cancel job, action-plan writes (mark_action_done, dismiss_action, get_action_progress) — **63 tools** |
+| **Pro** | Everything in Scale + usage stats, HQ dashboard, analytics, agent API — **74 tools** |
 
 When a user calls a tool above their plan, the server returns a structured error with an upgrade link:
 

{cited_cli-0.5.1 → cited_cli-0.5.2}/packages/mcp/SKILL.md

@@ -19,6 +19,7 @@ The typical flow is: **Business Setup → Audit → Recommendations → Solution
 
 ### 2. Run an Audit
 - `create_audit_template` — Define what questions to audit (e.g., "What is [business]?", "Best [industry] tools")
+- `free_audit` — Free GEO audit of any website, no login or plan needed. Use it when the user has no Cited account yet. Call again with the same `url` every ~30 seconds until `status` is `completed` (2-4 minutes).
 - `start_audit` — Launch the audit using a template (2-4 minutes). Poll `get_audit_status` every 30-60 seconds.
 - `get_audit_result` — Returns a summary by default (aggregate KPIs, competitor leaderboard, question IDs). Use `full=True` for detailed per-question citations — warning: full results can be very large.
 
@@ -50,9 +51,9 @@ The typical flow is: **Business Setup → Audit → Recommendations → Solution
 
 Tools are gated by subscription tier. If a tool is above the user's plan, it returns an upgrade message with a billing link.
 
-- **Growth** (entry tier): Read-only — list/get businesses, run audits, view recommendations (31 tools)
-- **Scale**: Full write access — create/update/delete, solutions, export, cancel (62 tools)
-- **Pro**: Everything + HQ dashboard, analytics, agent API (73 tools)
+- **Growth** (entry tier): Read-only — list/get businesses, run audits, view recommendations (32 tools)
+- **Scale**: Full write access — create/update/delete, solutions, export, cancel (63 tools)
+- **Pro**: Everything + HQ dashboard, analytics, agent API (74 tools)
 
 Always call `check_auth_status` first — it shows the user's plan and remaining limits.
 

{cited_cli-0.5.1 → cited_cli-0.5.2}/packages/mcp/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cited-mcp"
-version = "0.5.1"
+version = "0.5.2"
 description = "MCP server for the Cited GEO platform"
 readme = "README.md"
 license = "LicenseRef-Proprietary"
 requires-python = ">=3.11"
 authors = [{ name = "Cited", email = "support@youcited.com" }]
 dependencies = [
-    "cited-core>=0.5.1",
-    "mcp>=1.27.0",
+    "cited-core>=0.5.2",
+    "mcp>=1.27.0,<2",
     "PyJWT>=2.8.0",
     "PyYAML>=6.0",
 ]

{cited_cli-0.5.1 → cited_cli-0.5.2}/packages/mcp/src/cited_mcp/plan_gating.py

@@ -165,6 +165,7 @@ _BASE_TOOLS: set[str] = {
     "get_pricing",
     "upgrade_plan",
     "whats_new",
+    "free_audit",
     "list_businesses",
     "get_business",
     "crawl_business",

{cited_cli-0.5.1 → cited_cli-0.5.2}/packages/mcp/src/cited_mcp/tool_changelog.yaml

@@ -21,6 +21,22 @@
 #      this file.
 
 versions:
+  - version: "0.5.2"
+    released: "2026-10-14"
+    # Adds free_audit: the no-login GEO audit behind the youcited.com homepage
+    # prompt, so agents can audit a site before the user has an account.
+    fingerprint: "8e42f3842abe"
+    tools_added:
+      - name: free_audit
+        description: |
+          Free GEO visibility audit of any website, no login or plan needed.
+          The first call starts it; call again with the same url for progress
+          and the full report (questions, whether the site was cited, which
+          domains AI cited instead). Requires the cited backend with
+          GET /free-audit (YouCited/cited#132).
+    tools_changed: []
+    tools_removed: []
+
   - version: "0.5.1"
     released: "2026-05-18"
     # Telemetry-only release: tool surface is unchanged (fingerprint matches

{cited_cli-0.5.1 → cited_cli-0.5.2}/packages/mcp/src/cited_mcp/tools/audit.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
+import os
 from typing import Any
 
 from mcp.server.fastmcp import Context
 from mcp.types import ToolAnnotations
 
 from cited_core.api import endpoints
+from cited_core.api.client import CitedClient
 from cited_core.errors import CitedAPIError
+from cited_core.free_audit import check_free_audit, is_finished
 from cited_mcp.context import CitedContext
 from cited_mcp.server import mcp
 from cited_mcp.tools._helpers import (
@@ -366,3 +369,37 @@ async def list_audits(
         return cited_ctx.client.get(endpoints.AUDIT_HISTORY, params=params)
     except CitedAPIError as e:
         return _api_error_response(e)
+
+
+@mcp.tool(
+    title="Free Audit",
+    annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False, idempotentHint=True, openWorldHint=True),  # noqa: E501
+)
+@log_tool_call
+async def free_audit(ctx: Context[Any, CitedContext, Any], url: str) -> Any:
+    """Run a free GEO visibility audit for any website. No login or plan needed.
+
+    Checks how often AI assistants cite the site for a handful of buyer
+    questions and which sites they cite instead. The first call starts the
+    audit (2-4 minutes); call again with the same url to get progress, and the
+    full report once status is "completed". Re-running a domain within 24 hours
+    returns the same audit.
+
+    Args:
+        ctx: MCP context
+        url: Website to audit, e.g. "example.com"
+    """
+    cited_ctx = _get_ctx(ctx)
+    # Anonymous client: no user cookie. The hosted server's agent key (when set)
+    # exempts it from the backend's per-IP limit, which all its users share.
+    agent_key = os.environ.get("CITED_AGENT_API_KEY") or cited_ctx.client.agent_api_key
+    client = CitedClient(base_url=cited_ctx.api_url, agent_api_key=agent_key)
+    try:
+        report = check_free_audit(client, url)
+    except CitedAPIError as e:
+        return _api_error_response(e)
+    finally:
+        client.close()
+    if not is_finished(report):
+        report["hint"] = "Audit still running. Call free_audit again with the same url in ~30s."
+    return _truncate_response(report)

{cited_cli-0.5.1 → cited_cli-0.5.2}/packages/mcp/tests/test_plan_gating.py

@@ -204,7 +204,7 @@ class TestToolsForTier:
         # All tools should be available to pro. Bump this count whenever a tool
         # is added/removed to/from any tier set.
         tools = tools_for_tier("pro")
-        assert len(tools) == 73
+        assert len(tools) == 74
 
     def test_all_registered_tools_are_in_tier_sets(self):
         """Every registered MCP tool must appear in exactly one tier set."""

{cited_cli-0.5.1 → cited_cli-0.5.2}/packages/mcp/tests/test_surface_invariants.py

@@ -63,6 +63,7 @@ EXPECTED_TOOLS_V0_5_0: set[str] = {
     "get_pricing",
     "upgrade_plan",
     "whats_new",
+    "free_audit",
     "get_usage_stats",
     # Businesses
     "list_businesses",

{cited_cli-0.5.1 → cited_cli-0.5.2}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cited-cli"
-version = "0.5.1"
+version = "0.5.2"
 description = "CLI for the Cited GEO platform"
 readme = "README.md"
 license = "LicenseRef-Proprietary"
 requires-python = ">=3.11"
 authors = [{ name = "Cited", email = "support@youcited.com" }]
 dependencies = [
-    "cited-core>=0.5.1",
+    "cited-core>=0.5.2",
     "typer>=0.15.0",
     "rich>=13.0.0",
 ]
@@ -20,13 +20,13 @@ dependencies = [
 cited = "cited_cli.app:main"
 
 [project.optional-dependencies]
-mcp = ["cited-mcp>=0.5.1"]
+mcp = ["cited-mcp>=0.5.2"]
 dev = [
     "pytest>=8.0",
     "respx>=0.21",
     "ruff>=0.4",
     "mypy>=1.10",
-    "cited-mcp>=0.5.1",
+    "cited-mcp>=0.5.2",
     "types-PyYAML>=6.0",
 ]
 

{cited_cli-0.5.1 → cited_cli-0.5.2}/src/cited_cli/commands/audit.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
-from typing import Annotated
+import time
+from contextlib import nullcontext
+from typing import Annotated, Any
 
 import typer
 from rich.console import Console
@@ -13,6 +15,7 @@ from cited_core.api import endpoints
 from cited_core.api.client import LONG_TIMEOUT, CitedClient
 from cited_core.auth.store import TokenStore
 from cited_core.config.manager import ConfigManager
+from cited_core.free_audit import check_free_audit, is_finished
 
 audit_app = typer.Typer(name="audit", help="Run and manage audits.")
 
@@ -34,6 +37,95 @@ def _get_client(ctx: typer.Context) -> tuple[OutputContext, CitedClient, str]:
     return out, CitedClient(base_url=api_url, token=token), env
 
 
+FREE_AUDIT_POLL_SECONDS = 15
+FREE_AUDIT_MAX_WAIT_SECONDS = 15 * 60
+
+
+def _render_free_audit(data: dict[str, Any], console: Console) -> None:
+    if data.get("status") != "completed":
+        render_kv(
+            "Free Audit",
+            {
+                "Domain": data.get("domain", ""),
+                "Status": data.get("status", ""),
+                "Progress": f"{data.get('progress', 0)}%",
+                "Report": data.get("report_url", ""),
+            },
+            console,
+        )
+        if data.get("error"):
+            console.print(f"[red]{data['error']}[/red]")
+        return
+
+    summary = data.get("summary", {})
+    render_kv(
+        f"Free Audit: {data.get('domain', '')}",
+        {
+            "Your site cited in": (
+                f"{summary.get('questions_where_brand_cited', 0)} of "
+                f"{summary.get('questions_checked', 0)} questions"
+            ),
+            "High-risk questions": summary.get("high_risk_questions", 0),
+            "Share of voice": f"{summary.get('share_of_voice') or 0:.0f}%",
+            "AI providers": ", ".join(data.get("providers_used") or []),
+            "Full report": data.get("share_url", ""),
+        },
+        console,
+    )
+    render_table(
+        "Questions",
+        ["Question", "Risk", "You cited", "AI cited instead"],
+        [
+            [
+                q.get("question", ""),
+                q.get("risk_level") or "",
+                "yes" if q.get("brand_cited") else "no",
+                ", ".join(q.get("cited_domains") or []),
+            ]
+            for q in data.get("questions", [])
+        ],
+        console,
+    )
+    console.print("\nFor more questions and fixes, create an account: [bold]cited register[/bold]")
+
+
+@audit_app.command("free")
+def audit_free(
+    ctx: typer.Context,
+    url: Annotated[str | None, typer.Argument(help="Website to audit, e.g. example.com")] = None,
+    wait: Annotated[
+        bool,
+        typer.Option("--wait/--no-wait", help="Wait for the audit to finish (2-4 minutes)"),
+    ] = True,
+) -> None:
+    """Run a free GEO visibility audit for any website. No login needed."""
+    obj = ctx.obj or {}
+    out: OutputContext = obj.get("output", OutputContext())
+    cfg: ConfigManager = obj.get("config", ConfigManager())
+    api_url = cfg.get_api_url(obj.get("profile", "default"), obj.get("env_override"))
+    url = prompt_if_missing(url, "URL", "Website to audit", out)
+
+    client = CitedClient(base_url=api_url)
+    try:
+        deadline = time.monotonic() + FREE_AUDIT_MAX_WAIT_SECONDS
+        # No spinner in JSON mode: stdout must carry only the JSON document.
+        status = nullcontext() if out.json_mode else out.console.status("Running free audit...")
+        with status as spinner:
+            data = check_free_audit(client, url)
+            while wait and not is_finished(data) and time.monotonic() < deadline:
+                if spinner is not None:
+                    spinner.update(f"Running free audit... {data.get('progress', 0)}%")
+                time.sleep(FREE_AUDIT_POLL_SECONDS)
+                data = check_free_audit(client, url)
+        print_result(data, out, human_formatter=_render_free_audit)
+        if not out.json_mode and not is_finished(data):
+            out.console.print(f"\nCheck again later: [bold]cited audit free {url}[/bold]")
+    except CitedAPIError as e:
+        handle_api_error(e, out.json_mode)
+    finally:
+        client.close()
+
+
 @audit_app.command("start")
 def audit_start(
     ctx: typer.Context,

{cited_cli-0.5.1 → cited_cli-0.5.2}/tests/test_feature_parity.py

@@ -108,6 +108,7 @@ _CLI_TO_MCP: dict[str, str | list[str]] = {
     "audit result": "get_audit_result",
     "audit list": "list_audits",
     "audit export": "export_audit",
+    "audit free": "free_audit",
     # Recommendations
     "recommend start": "start_recommendation",
     "recommend status": "get_recommendation_status",

cited_cli-0.5.2/tests/test_free_audit.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+import respx
+
+from tests.test_mcp_tools import _make_cited_ctx, _make_mcp_ctx, _mcp_available, _run  # noqa: F401
+
+DEV_API = "https://dev.youcited.com"
+TOKEN = "instant_a1b2c3d4_0123456789abcdef"
+
+STARTED = {
+    "domain": "acme-plumbing.com",
+    "job_id": "a1b2c3d4e5",
+    "status": "pending",
+    "report_url": f"{DEV_API}/free-audit/report/{TOKEN}",
+    "share_url": f"https://youcited.com/share/{TOKEN}",
+    "poll_after_seconds": 30,
+}
+PROCESSING = {"status": "processing", "progress": 40, "poll_after_seconds": 30}
+COMPLETED = {
+    "status": "completed",
+    "domain": "acme-plumbing.com",
+    "providers_used": ["perplexity"],
+    "summary": {
+        "questions_checked": 2,
+        "questions_where_brand_cited": 1,
+        "high_risk_questions": 1,
+        "share_of_voice": 35.0,
+    },
+    "questions": [
+        {
+            "question": "Best plumber in Austin?",
+            "risk_level": "high",
+            "brand_cited": False,
+            "cited_domains": ["yelp.com", "angi.com"],
+        }
+    ],
+    "share_url": f"https://youcited.com/share/{TOKEN}",
+}
+
+
+def _isolate_config(tmp_path, monkeypatch) -> None:
+    """Point config and credentials at an empty temp dir: no login exists."""
+    config_dir = tmp_path / ".cited"
+    monkeypatch.setattr("cited_core.config.constants.CONFIG_DIR", config_dir)
+    monkeypatch.setattr("cited_core.config.constants.CONFIG_FILE", config_dir / "config.toml")
+    monkeypatch.setattr(
+        "cited_core.config.constants.CREDENTIALS_FILE", config_dir / "credentials.json"
+    )
+    monkeypatch.setattr("cited_core.auth.store.CONFIG_DIR", config_dir)
+    monkeypatch.setattr(
+        "cited_core.auth.store.CREDENTIALS_FILE", config_dir / "credentials.json"
+    )
+    monkeypatch.setattr("cited_core.auth.store.TokenStore._has_keyring", lambda self: False)
+    monkeypatch.setattr("cited_cli.commands.audit.time.sleep", lambda s: None)
+
+
+@respx.mock
+def test_cli_audit_free_waits_for_report_without_login(runner, cli_app, tmp_path, monkeypatch):
+    _isolate_config(tmp_path, monkeypatch)
+    start = respx.get(f"{DEV_API}/free-audit").mock(
+        return_value=httpx.Response(202, json=STARTED)
+    )
+    respx.get(f"{DEV_API}/free-audit/report/{TOKEN}").mock(
+        side_effect=[
+            httpx.Response(200, json=PROCESSING),
+            httpx.Response(200, json=COMPLETED),
+        ]
+    )
+
+    result = runner.invoke(
+        cli_app, ["--env", "dev", "--json", "audit", "free", "acme-plumbing.com"]
+    )
+
+    assert result.exit_code == 0, result.output
+    data = json.loads(result.output)
+    assert data["status"] == "completed"
+    assert data["summary"]["questions_where_brand_cited"] == 1
+    assert start.calls.last.request.url.params["url"] == "acme-plumbing.com"
+    assert "cookie" not in start.calls.last.request.headers
+
+
+@respx.mock
+def test_cli_audit_free_no_wait_returns_progress(runner, cli_app, tmp_path, monkeypatch):
+    _isolate_config(tmp_path, monkeypatch)
+    respx.get(f"{DEV_API}/free-audit").mock(return_value=httpx.Response(202, json=STARTED))
+    report = respx.get(f"{DEV_API}/free-audit/report/{TOKEN}").mock(
+        return_value=httpx.Response(200, json=PROCESSING)
+    )
+
+    result = runner.invoke(
+        cli_app,
+        ["--env", "dev", "--json", "audit", "free", "acme-plumbing.com", "--no-wait"],
+    )
+
+    assert result.exit_code == 0, result.output
+    data = json.loads(result.output)
+    assert data["status"] == "processing"
+    assert data["report_url"] == STARTED["report_url"]
+    assert report.call_count == 1
+
+
+@respx.mock
+def test_cli_audit_free_rate_limited(runner, cli_app, tmp_path, monkeypatch):
+    _isolate_config(tmp_path, monkeypatch)
+    respx.get(f"{DEV_API}/free-audit").mock(
+        return_value=httpx.Response(429, json={"detail": "at today's limit"})
+    )
+
+    result = runner.invoke(cli_app, ["--env", "dev", "audit", "free", "acme-plumbing.com"])
+
+    assert result.exit_code == 5
+
+
+@pytest.mark.usefixtures("_mcp_available")
+@respx.mock
+def test_mcp_free_audit_works_without_token():
+    from cited_mcp.tools.audit import free_audit
+
+    respx.get(f"{DEV_API}/free-audit").mock(return_value=httpx.Response(202, json=STARTED))
+    respx.get(f"{DEV_API}/free-audit/report/{TOKEN}").mock(
+        return_value=httpx.Response(200, json=PROCESSING)
+    )
+
+    ctx = _make_mcp_ctx(_make_cited_ctx(token=None))
+    result = _run(free_audit(ctx, url="acme-plumbing.com"))
+
+    assert result["status"] == "processing"
+    assert "call free_audit again" in result["hint"].lower()
+
+
+@pytest.mark.usefixtures("_mcp_available")
+@respx.mock
+def test_mcp_free_audit_returns_completed_report():
+    from cited_mcp.tools.audit import free_audit
+
+    respx.get(f"{DEV_API}/free-audit").mock(
+        return_value=httpx.Response(202, json={**STARTED, "status": "completed"})
+    )
+    respx.get(f"{DEV_API}/free-audit/report/{TOKEN}").mock(
+        return_value=httpx.Response(200, json=COMPLETED)
+    )
+
+    ctx = _make_mcp_ctx(_make_cited_ctx(token=None))
+    result = _run(free_audit(ctx, url="acme-plumbing.com"))
+
+    assert result["status"] == "completed"
+    assert result["questions"][0]["cited_domains"] == ["yelp.com", "angi.com"]
+    assert "hint" not in result
+
+
+@pytest.mark.usefixtures("_mcp_available")
+@respx.mock
+def test_mcp_free_audit_sends_server_agent_key_not_user_cookie(monkeypatch):
+    from cited_mcp.tools.audit import free_audit
+
+    monkeypatch.setenv("CITED_AGENT_API_KEY", "server-key")
+    start = respx.get(f"{DEV_API}/free-audit").mock(
+        return_value=httpx.Response(202, json=STARTED)
+    )
+    respx.get(f"{DEV_API}/free-audit/report/{TOKEN}").mock(
+        return_value=httpx.Response(200, json=PROCESSING)
+    )
+
+    ctx = _make_mcp_ctx(_make_cited_ctx(token="user-jwt"))
+    _run(free_audit(ctx, url="acme-plumbing.com"))
+
+    sent = start.calls.last.request.headers
+    assert sent["x-agent-api-key"] == "server-key"
+    assert "cookie" not in sent

{cited_cli-0.5.1 → cited_cli-0.5.2}/tests/test_mcp_server.py

@@ -87,6 +87,7 @@ EXPECTED_TOOLS = [
     "upgrade_plan",
     # Changelog
     "whats_new",
+    "free_audit",
     # Agent API
     "get_business_facts",
     "get_business_claims",

cited_cli-0.5.1/packages/core/src/cited_core/__init__.py

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