cited-cli 0.3.4__tar.gz → 0.3.14__tar.gz

cited_cli-0.3.14/.github/workflows/changelog-guard.yml

@@ -0,0 +1,32 @@
+name: Changelog Guard
+
+# Path-filtered: this workflow only spins up a runner when the PR touches
+# pyproject.toml or the changelog itself. Doc-only or unrelated PRs don't
+# trigger it at all, so contributors don't see an extra check on changes
+# that have nothing to do with versioning.
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "pyproject.toml"
+      - "packages/*/pyproject.toml"
+      - "packages/mcp/src/cited_mcp/tool_changelog.yaml"
+
+jobs:
+  guard:
+    # Fails any PR that bumps a `version = "..."` line in any pyproject.toml
+    # without also editing packages/mcp/src/cited_mcp/tool_changelog.yaml.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+      - name: Check changelog vs version bump
+        run: |
+          base="origin/${{ github.base_ref }}"
+          if git diff "$base"...HEAD -- '**/pyproject.toml' | grep -qE '^[+-]version = '; then
+            if ! git diff --name-only "$base"...HEAD | grep -q '^packages/mcp/src/cited_mcp/tool_changelog\.yaml$'; then
+              echo "::error::PR bumps pyproject.toml version but does not modify packages/mcp/src/cited_mcp/tool_changelog.yaml. Add a top entry with the new version, fingerprint, and tools_added/changed/removed."
+              exit 1
+            fi
+          fi

{cited_cli-0.3.4 → cited_cli-0.3.14}/.github/workflows/ci.yml

@@ -14,10 +14,10 @@ jobs:
         python-version: ["3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: ${{ matrix.python-version }}
 

{cited_cli-0.3.4 → cited_cli-0.3.14}/.github/workflows/release.yml

@@ -13,10 +13,10 @@ jobs:
     runs-on: ubuntu-latest
     environment: Prod
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.12"
 
@@ -28,28 +28,34 @@ jobs:
         run: |
           cd packages/core
           python -m build
-          twine upload dist/* -u __token__ -p ${{ secrets.PYPI_TOKEN }}
+          twine upload dist/*
         env:
           TWINE_NON_INTERACTIVE: "1"
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
 
       - name: Build and publish cited-mcp
         run: |
           cd packages/mcp
           python -m build
-          twine upload dist/* -u __token__ -p ${{ secrets.PYPI_TOKEN }}
+          twine upload dist/*
         env:
           TWINE_NON_INTERACTIVE: "1"
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
 
       - name: Build cited-cli
         run: python -m build
 
       - name: Publish cited-cli to PyPI
-        run: twine upload dist/* -u __token__ -p ${{ secrets.PYPI_TOKEN }}
+        run: twine upload dist/*
         env:
           TWINE_NON_INTERACTIVE: "1"
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
         with:
           files: dist/*
           generate_release_notes: true

{cited_cli-0.3.4 → cited_cli-0.3.14}/.gitignore

@@ -17,3 +17,4 @@ env/
 htmlcov/
 .env
 ~/.cited/
+.DS_Store

{cited_cli-0.3.4 → cited_cli-0.3.14}/CLAUDE.md

@@ -7,7 +7,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 Monorepo for the [Cited](https://youcited.com) GEO platform tooling. Contains three Python packages:
 
 - **`cited-core`** (`packages/core/`) — Shared library: API client, auth, config, endpoints, errors. No CLI or MCP dependencies.
-- **`cited-mcp`** (`packages/mcp/`) — Standalone MCP server with 28 tools. Depends on `cited-core` + `mcp` SDK. Installable via `pip install cited-mcp` or `uvx cited-mcp`.
+- **`cited-mcp`** (`packages/mcp/`) — Standalone MCP server with 47 tools. Depends on `cited-core` + `mcp` SDK. Installable via `pip install cited-mcp` or `uvx cited-mcp`.
 - **`cited-cli`** (root `src/cited_cli/`) — Typer + Rich CLI. Depends on `cited-core` + `typer` + `rich`. Optional dep on `cited-mcp` for `cited mcp serve`.
 
 Also contains `cited-plugins/` — a Claude Code plugin (skills, commands, agents) that references the MCP server via `uvx cited-mcp`.
@@ -37,8 +37,8 @@ cited --help
 cited-mcp                    # Standalone binary (from cited-mcp package)
 cited mcp serve              # Via CLI (requires cited-cli[mcp])
 
-# Release (publishes cited-core → cited-mcp → cited-cli to PyPI)
-./scripts/release.sh 0.3.2
+# Release and deploy scripts are in the private infra repo:
+# ~/repos/cited-mcp-infra (github.com/YouCited/cited-mcp-infra)
 ```
 
 ## Architecture
@@ -54,11 +54,14 @@ cited mcp serve              # Via CLI (requires cited-cli[mcp])
 - `config/constants.py` — `ENVIRONMENTS`, `CONFIG_DIR`, `VALID_INDUSTRIES`, etc.
 - `errors.py` — `CitedAPIError`, `ExitCode`, `exit_code_for_status()`
 
-**`cited-mcp`** (`packages/mcp/src/cited_mcp/`) — MCP server + 28 tools:
+**`cited-mcp`** (`packages/mcp/src/cited_mcp/`) — MCP server + 47 tools:
 - `server.py` — `FastMCP` instance, lifespan, `run_server()`
 - `tools/` — auth, business, audit, recommend, solution, job tool modules
+- `plan_gating.py` — Per-plan tool access control (growth/scale/pro tiers)
+- `auth_provider.py` — OAuth provider with stateless JWT tokens and user JWT expiry detection
 - Supports `CITED_TOKEN` and `CITED_AGENT_API_KEY` env vars
 - Includes browser OAuth `login` tool for Claude Desktop users
+- Remote server (`remote.py`) runs stateless HTTP with Fargate Spot auto-scaling
 
 **`cited-cli`** (`src/cited_cli/`) — Typer CLI:
 - Imports core modules from `cited_core.*` (not `cited_cli.api.*`)
@@ -113,6 +116,17 @@ This gives `cited audit template list|get|create|update|delete` while `cited aud
 
 **Audit template workflow:** The typical flow is create → review → refine → run audit. Auto-generated questions are rarely perfect, so `audit template update` is a common operation. The `--question` flags on `update` **replace all** existing questions (matching the web editor's save behavior). Omit `--question` to keep existing questions unchanged while updating name/description. Backend endpoint: `PUT /named-audits/{id}` with `NamedAuditUpdate` schema.
 
+## CLI / MCP Feature Parity
+
+**Every new feature must be added to BOTH the CLI and MCP server.** A test (`tests/test_feature_parity.py`) enforces this — it compares all CLI commands against MCP tools and fails if a command exists in one but not the other.
+
+When adding a new feature:
+1. Add the CLI command in `src/cited_cli/commands/`
+2. Add the MCP tool in `packages/mcp/src/cited_mcp/tools/`
+3. Add the tool to `plan_gating.py` (in the appropriate tier set)
+4. Update the `_CLI_TO_MCP` mapping in `tests/test_feature_parity.py`
+5. If the feature is intentionally one-interface-only, add it to `CLI_ONLY` or `MCP_ONLY` with a comment explaining why
+
 ## Key Conventions
 
 - **Exit codes:** 0=success, 1=error, 2=auth, 3=not found, 4=validation, 5=rate limited (defined in `utils/errors.py`)
@@ -125,9 +139,14 @@ This gives `cited audit template list|get|create|update|delete` while `cited aud
 - **User config** lives at `~/.cited/config.toml`; version is in `src/cited_cli/__init__.py`
 - **Version** single source of truth is `packages/core/src/cited_core/__init__.py`. The CLI and MCP packages import it via `from cited_core import __version__`. The `version =` field in all three `pyproject.toml` files must also be bumped (the release script handles this).
 
-## Releasing
+## Releasing & Deployment
+
+Release, deploy, and infrastructure scripts live in the **private** repo `~/repos/cited-mcp-infra` ([YouCited/cited-mcp-infra](https://github.com/YouCited/cited-mcp-infra)):
 
-`scripts/release.sh <version>` handles the full release pipeline. It bumps the version in both `pyproject.toml` and `__init__.py`, commits, tags `v<version>`, pushes (triggering the GitHub Actions release workflow), waits for the release, then regenerates the Homebrew formula in `~/repos/homebrew-cited` with the new tarball URL, SHA256, and all Python dependency resource blocks (resolved from PyPI). Finally it commits and pushes the tap update.
+- `scripts/release.sh <version>` — Bumps version, publishes to PyPI, updates Homebrew tap
+- `scripts/deploy-mcp.sh <env>` — Deploys MCP server to AWS ECS Fargate
+- `scripts/cleanup_dev.py` — Removes test data from dev environment
+- `docker/Dockerfile` — Docker image for the remote MCP server
 
 **Prerequisites:** clean git state on `main`, `gh` CLI authenticated, `.venv` with cited-cli installed, `~/repos/homebrew-cited` cloned.
 

cited_cli-0.3.14/FUTURE.md

@@ -0,0 +1,106 @@
+# Future Enhancements
+
+## Shell Completions: `cited completions`
+
+Generate shell completion scripts for bash, zsh, and fish. Typer has built-in support for this but it needs to be exposed as a command.
+
+```bash
+# Generate and install completions
+cited completions zsh > ~/.zfunc/_cited
+cited completions bash > /etc/bash_completion.d/cited
+cited completions fish > ~/.config/fish/completions/cited.fish
+```
+
+Typer provides this via `typer.main.get_command(app).get_help()` and Click's shell completion utilities.
+
+---
+
+## Batch Operations
+
+### `cited audit batch`
+
+Run multiple audit templates in sequence or parallel, collecting results into a single report.
+
+```bash
+# Run all templates for a business
+cited audit batch --business $BID --all
+
+# Run specific templates
+cited audit batch --business $BID --template $T1 --template $T2
+
+# Export combined results
+cited audit batch --business $BID --all --export results.json
+```
+
+### `cited business import`
+
+Bulk-create businesses from a CSV or JSON file for agencies managing multiple clients.
+
+```bash
+cited business import clients.csv
+cited business import --format json clients.json
+```
+
+---
+
+## Diff and History
+
+### `cited audit diff`
+
+Compare two audit runs side-by-side to show citation changes over time.
+
+```bash
+cited audit diff $JOB_ID_1 $JOB_ID_2
+```
+
+Output would show per-question citation deltas (gained/lost citations, score changes) in a Rich table.
+
+### `cited analytics export`
+
+Export historical analytics data to CSV/JSON for external analysis or dashboarding.
+
+```bash
+cited analytics export --business $BID --from 2026-01-01 --to 2026-03-20 --format csv > trends.csv
+```
+
+---
+
+## Interactive Mode: `cited interactive`
+
+A REPL-style session that keeps auth and business context loaded, reducing repetitive flags:
+
+```bash
+$ cited interactive --business $BID --env dev
+cited> audit template list
+cited> audit start $TEMPLATE_ID
+cited> job watch $JOB_ID
+cited> recommend start $JOB_ID
+```
+
+Would use `prompt_toolkit` for readline-style history, tab completion, and inline help.
+
+---
+
+## Webhooks: `cited webhook`
+
+Register webhook URLs to get notified when jobs complete, instead of polling with `job watch`.
+
+```bash
+cited webhook create --event job.completed --url https://example.com/hook
+cited webhook list
+cited webhook delete $WEBHOOK_ID
+```
+
+Requires backend support for webhook delivery.
+
+---
+
+## MCP Server Card (SEP-2127)
+
+Publish a server card at `/.well-known/mcp/server-card.json` to support automatic MCP server discovery. This would advertise the server's capabilities, authentication requirements, and tool catalog to MCP clients.
+
+---
+
+## MCP Code Mode
+
+Inspired by [Cloudflare's Code Mode pattern](https://blog.cloudflare.com/enterprise-mcp/), reduce token consumption by exposing just two tools (`search` and `execute`) instead of all 30 tool definitions. The model discovers available tools via search and executes them by name. Could reduce initial token overhead by ~90% for clients that support it.

cited_cli-0.3.4/README.md → cited_cli-0.3.14/PKG-INFO

@@ -1,3 +1,25 @@
+Metadata-Version: 2.4
+Name: cited-cli
+Version: 0.3.14
+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.3.14
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: cited-mcp>=0.3.14; 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.3.14; extra == 'mcp'
+Description-Content-Type: text/markdown
+
 # Cited CLI
 
 Command-line interface for the [Cited](https://youcited.com) GEO (Generative Engine Optimization) platform. Audit how often your business is cited by AI assistants, generate recommendations, and produce AI-ready content solutions — all from the terminal or a Python script.
@@ -73,11 +95,24 @@ cited register --email you@example.com --name "Your Name" --password "Secret123!
 
 ## MCP Server
 
-This repo also includes `cited-mcp`, a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes 28 tools for AI assistants like Claude. It lets Claude manage businesses, run GEO audits, generate recommendations, and create solutions on your behalf.
+This repo also includes `cited-mcp`, a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes 56 tools for AI assistants like Claude. It lets Claude manage businesses, run GEO audits, generate recommendations, work a prioritized action plan, verify fixes via the Validation Engine, and create solutions on your behalf.
+
+### Claude Desktop (Custom Connector — recommended)
+
+No local install required. Claude connects to Cited's hosted MCP server directly:
+
+1. Open Claude Desktop → **Settings** → **Customize > Connectors**
+2. Click **"+"** → **"Add custom connector"**
+3. Enter URL: `https://mcp.youcited.com/mcp`
+4. Click **Add**
+
+Your browser will open for authentication on first use. See [Anthropic's connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for details.
 
-### Claude Desktop (remote — recommended)
+> **Requires:** Claude Pro, Max, Team, or Enterprise plan.
 
-No local install required. Add this to your Claude Desktop config (`Settings → Developer → Edit Config`):
+### Claude Desktop (Developer Config — alternative)
+
+If Custom Connectors aren't available, use the developer config with `mcp-remote`:
 
 ```json
 {
@@ -90,7 +125,7 @@ No local install required. Add this to your Claude Desktop config (`Settings →
 }
 ```
 
-Restart Claude Desktop. A browser window will open for authentication on first use.
+Add to `Settings → Developer → Edit Config`, then restart Claude Desktop.
 
 > **Prerequisite:** [Node.js](https://nodejs.org) (LTS) must be installed for `npx`.
 
@@ -131,6 +166,10 @@ Verify Node.js is installed (`node --version`), or install with `brew install no
 
 Open Settings (`Cmd+,`) → search "MCP" → verify the server shows a green status. Use tools in Composer (Agent mode).
 
+### Updating to new Cited features
+
+Cited adds new tools regularly. To access new tools after a release, **disconnect and reconnect the Cited connector** in your Claude Desktop or Claude.ai connector settings — restarting Claude alone is not enough, because the connector's tool list is cached at registration time. Once reconnected, ask the agent to call `whats_new` to see what changed since you last connected.
+
 ### Example
 
 Once connected, ask Claude something like:
@@ -143,13 +182,17 @@ Claude will chain the tools automatically — `list_businesses` → `start_audit
 
 | Category | Tools |
 |----------|-------|
-| **Auth** | `check_auth_status`, `login` |
-| **Businesses** | `list_businesses`, `get_business`, `create_business`, `update_business`, `delete_business`, `crawl_business`, `get_health_scores` |
+| **Auth** | `check_auth_status`, `login`, `logout` |
+| **Businesses** | `list_businesses`, `get_business`, `create_business`, `update_business`, `delete_business`, `crawl_business`, `get_health_scores`, `get_usage_stats` |
 | **Audit Templates** | `list_audit_templates`, `get_audit_template`, `create_audit_template`, `update_audit_template`, `delete_audit_template` |
-| **Audits** | `start_audit`, `get_audit_status`, `get_audit_result`, `list_audits` |
+| **Audits** | `start_audit`, `get_audit_status`, `get_audit_result`, `list_audits`, `export_audit` |
 | **Recommendations** | `start_recommendation`, `get_recommendation_status`, `get_recommendation_result`, `get_recommendation_insights`, `list_recommendations` |
 | **Solutions** | `start_solution`, `get_solution_status`, `get_solution_result`, `list_solutions` |
-| **Jobs** | `get_job_status` |
+| **Jobs** | `get_job_status`, `cancel_job` |
+| **HQ** | `get_business_hq` |
+| **Analytics** | `get_analytics_trends`, `get_analytics_summary`, `compare_audits` |
+| **Agent API** | `get_business_facts`, `get_business_claims`, `get_competitive_comparison`, `get_semantic_health`, `buyer_fit_query` |
+| **Action Plan** | `get_action_plan`, `get_quick_wins`, `mark_action_done`, `dismiss_action`, `get_action_progress` |
 
 See [`packages/mcp/README.md`](packages/mcp/README.md) for full details, environment variables, and development instructions.
 
@@ -557,22 +600,17 @@ ruff check src/
 mypy src/cited_cli/ --ignore-missing-imports
 ```
 
-## Releasing
+### MCP test harness
 
-A single script handles the full release pipeline — version bump, GitHub release, and Homebrew tap update:
+`scripts/mcp_test_harness.py` runs an end-to-end test suite against the deployed MCP server (dev or prod). Exercises the four-PR-plan test cases — `tools_fingerprint` on `ping`, `whats_new` lookups, `upgrade_plan` no-op response, `tool_unavailable` error shape — plus auth/host-header/rate-limit/cross-env/`robots.txt` regression checks.
 
 ```bash
-./scripts/release.sh 0.2.0
+./scripts/mcp_test_harness.py --env dev    # mcpdev.youcited.com
+./scripts/mcp_test_harness.py --env prod   # mcp.youcited.com
 ```
 
-This will:
-1. Bump the version in `pyproject.toml` and `src/cited_cli/__init__.py`
-2. Commit, tag `v0.2.0`, and push to origin (triggers GitHub Actions release)
-3. Wait for the GitHub release to be created
-4. Download the tarball, compute SHA256, and resolve all Python dependency hashes from PyPI
-5. Regenerate `Formula/cited.rb` in `~/repos/homebrew-cited` with the updated formula
-6. Commit and push the tap update
+First run per env opens a browser for OAuth; tokens are cached at `/tmp/cited-mcp-{env}-token.json` and reused for 7 days. The rate-limiter test fills the user's per-token window for ~60s, so run it last in any debug session.
 
-After the script completes, users can update with `brew update && brew upgrade cited`.
+## Releasing
 
-**Prerequisites:** `gh` CLI authenticated, `.venv` with cited-cli installed, `~/repos/homebrew-cited` cloned.
+Release and deployment scripts are in a [private infrastructure repo](https://github.com/YouCited/cited-mcp-infra). See that repo's README for release and deploy instructions.

cited_cli-0.3.4/PKG-INFO → cited_cli-0.3.14/README.md

@@ -1,24 +1,3 @@
-Metadata-Version: 2.4
-Name: cited-cli
-Version: 0.3.4
-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.3.4
-Requires-Dist: rich>=13.0.0
-Requires-Dist: typer>=0.15.0
-Provides-Extra: dev
-Requires-Dist: cited-mcp>=0.3.4; 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'
-Provides-Extra: mcp
-Requires-Dist: cited-mcp>=0.3.4; extra == 'mcp'
-Description-Content-Type: text/markdown
-
 # Cited CLI
 
 Command-line interface for the [Cited](https://youcited.com) GEO (Generative Engine Optimization) platform. Audit how often your business is cited by AI assistants, generate recommendations, and produce AI-ready content solutions — all from the terminal or a Python script.
@@ -94,11 +73,24 @@ cited register --email you@example.com --name "Your Name" --password "Secret123!
 
 ## MCP Server
 
-This repo also includes `cited-mcp`, a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes 28 tools for AI assistants like Claude. It lets Claude manage businesses, run GEO audits, generate recommendations, and create solutions on your behalf.
+This repo also includes `cited-mcp`, a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes 56 tools for AI assistants like Claude. It lets Claude manage businesses, run GEO audits, generate recommendations, work a prioritized action plan, verify fixes via the Validation Engine, and create solutions on your behalf.
+
+### Claude Desktop (Custom Connector — recommended)
+
+No local install required. Claude connects to Cited's hosted MCP server directly:
+
+1. Open Claude Desktop → **Settings** → **Customize > Connectors**
+2. Click **"+"** → **"Add custom connector"**
+3. Enter URL: `https://mcp.youcited.com/mcp`
+4. Click **Add**
+
+Your browser will open for authentication on first use. See [Anthropic's connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for details.
 
-### Claude Desktop (remote — recommended)
+> **Requires:** Claude Pro, Max, Team, or Enterprise plan.
 
-No local install required. Add this to your Claude Desktop config (`Settings → Developer → Edit Config`):
+### Claude Desktop (Developer Config — alternative)
+
+If Custom Connectors aren't available, use the developer config with `mcp-remote`:
 
 ```json
 {
@@ -111,7 +103,7 @@ No local install required. Add this to your Claude Desktop config (`Settings →
 }
 ```
 
-Restart Claude Desktop. A browser window will open for authentication on first use.
+Add to `Settings → Developer → Edit Config`, then restart Claude Desktop.
 
 > **Prerequisite:** [Node.js](https://nodejs.org) (LTS) must be installed for `npx`.
 
@@ -152,6 +144,10 @@ Verify Node.js is installed (`node --version`), or install with `brew install no
 
 Open Settings (`Cmd+,`) → search "MCP" → verify the server shows a green status. Use tools in Composer (Agent mode).
 
+### Updating to new Cited features
+
+Cited adds new tools regularly. To access new tools after a release, **disconnect and reconnect the Cited connector** in your Claude Desktop or Claude.ai connector settings — restarting Claude alone is not enough, because the connector's tool list is cached at registration time. Once reconnected, ask the agent to call `whats_new` to see what changed since you last connected.
+
 ### Example
 
 Once connected, ask Claude something like:
@@ -164,13 +160,17 @@ Claude will chain the tools automatically — `list_businesses` → `start_audit
 
 | Category | Tools |
 |----------|-------|
-| **Auth** | `check_auth_status`, `login` |
-| **Businesses** | `list_businesses`, `get_business`, `create_business`, `update_business`, `delete_business`, `crawl_business`, `get_health_scores` |
+| **Auth** | `check_auth_status`, `login`, `logout` |
+| **Businesses** | `list_businesses`, `get_business`, `create_business`, `update_business`, `delete_business`, `crawl_business`, `get_health_scores`, `get_usage_stats` |
 | **Audit Templates** | `list_audit_templates`, `get_audit_template`, `create_audit_template`, `update_audit_template`, `delete_audit_template` |
-| **Audits** | `start_audit`, `get_audit_status`, `get_audit_result`, `list_audits` |
+| **Audits** | `start_audit`, `get_audit_status`, `get_audit_result`, `list_audits`, `export_audit` |
 | **Recommendations** | `start_recommendation`, `get_recommendation_status`, `get_recommendation_result`, `get_recommendation_insights`, `list_recommendations` |
 | **Solutions** | `start_solution`, `get_solution_status`, `get_solution_result`, `list_solutions` |
-| **Jobs** | `get_job_status` |
+| **Jobs** | `get_job_status`, `cancel_job` |
+| **HQ** | `get_business_hq` |
+| **Analytics** | `get_analytics_trends`, `get_analytics_summary`, `compare_audits` |
+| **Agent API** | `get_business_facts`, `get_business_claims`, `get_competitive_comparison`, `get_semantic_health`, `buyer_fit_query` |
+| **Action Plan** | `get_action_plan`, `get_quick_wins`, `mark_action_done`, `dismiss_action`, `get_action_progress` |
 
 See [`packages/mcp/README.md`](packages/mcp/README.md) for full details, environment variables, and development instructions.
 
@@ -578,22 +578,17 @@ ruff check src/
 mypy src/cited_cli/ --ignore-missing-imports
 ```
 
-## Releasing
+### MCP test harness
 
-A single script handles the full release pipeline — version bump, GitHub release, and Homebrew tap update:
+`scripts/mcp_test_harness.py` runs an end-to-end test suite against the deployed MCP server (dev or prod). Exercises the four-PR-plan test cases — `tools_fingerprint` on `ping`, `whats_new` lookups, `upgrade_plan` no-op response, `tool_unavailable` error shape — plus auth/host-header/rate-limit/cross-env/`robots.txt` regression checks.
 
 ```bash
-./scripts/release.sh 0.2.0
+./scripts/mcp_test_harness.py --env dev    # mcpdev.youcited.com
+./scripts/mcp_test_harness.py --env prod   # mcp.youcited.com
 ```
 
-This will:
-1. Bump the version in `pyproject.toml` and `src/cited_cli/__init__.py`
-2. Commit, tag `v0.2.0`, and push to origin (triggers GitHub Actions release)
-3. Wait for the GitHub release to be created
-4. Download the tarball, compute SHA256, and resolve all Python dependency hashes from PyPI
-5. Regenerate `Formula/cited.rb` in `~/repos/homebrew-cited` with the updated formula
-6. Commit and push the tap update
+First run per env opens a browser for OAuth; tokens are cached at `/tmp/cited-mcp-{env}-token.json` and reused for 7 days. The rate-limiter test fills the user's per-token window for ~60s, so run it last in any debug session.
 
-After the script completes, users can update with `brew update && brew upgrade cited`.
+## Releasing
 
-**Prerequisites:** `gh` CLI authenticated, `.venv` with cited-cli installed, `~/repos/homebrew-cited` cloned.
+Release and deployment scripts are in a [private infrastructure repo](https://github.com/YouCited/cited-mcp-infra). See that repo's README for release and deploy instructions.

{cited_cli-0.3.4 → cited_cli-0.3.14}/TEST_RUNBOOK.md

@@ -460,20 +460,14 @@ cited auth status   # Should fail with exit code 2
 
 ### Automated cleanup script
 
-If you forget to clean up (or a run fails partway through), use the cleanup script to find and remove test assets:
+If you forget to clean up (or a run fails partway through), use the cleanup script from the [private infra repo](https://github.com/YouCited/cited-mcp-infra):
 
 ```bash
 # Dry run — see what would be deleted
-python3 scripts/cleanup_dev.py --dry-run
-
-# Interactive — prompts you to pick which businesses to delete
-python3 scripts/cleanup_dev.py
+python3 ~/repos/cited-mcp-infra/scripts/cleanup_dev.py --dry-run
 
 # Auto — deletes all businesses matching test name patterns (no prompts)
-python3 scripts/cleanup_dev.py --auto
-
-# Target a different environment
-python3 scripts/cleanup_dev.py --env prod --dry-run
+python3 ~/repos/cited-mcp-infra/scripts/cleanup_dev.py --auto
 ```
 
 The script detects test businesses by name patterns ("E2E Test", "CLI Test", etc.), deletes associated audit templates first, then the business itself.

{cited_cli-0.3.4 → cited_cli-0.3.14}/cited-plugins/CLAUDE_DESKTOP_SETUP.md

@@ -6,9 +6,27 @@ This guide walks you through connecting Claude Desktop to the Cited GEO platform
 
 - **Claude Desktop** app installed
 - **A Cited account** at [youcited.com](https://youcited.com)
-- **Node.js** installed (download from [nodejs.org](https://nodejs.org))
 
-## Step 1: Configure Claude Desktop
+## Option A: Custom Connector (recommended)
+
+The simplest setup — no local software required. Claude connects to Cited's hosted MCP server directly.
+
+1. Open Claude Desktop
+2. Go to **Settings** (gear icon or Claude menu)
+3. Navigate to **Customize > Connectors**
+4. Click **"+"** then **"Add custom connector"**
+5. Enter the server URL: `https://mcp.youcited.com/mcp`
+6. Click **Add**
+
+Your browser will open to authenticate with your Cited account. After logging in, you'll be redirected back automatically.
+
+> **Note:** Custom Connectors require Claude Pro, Max, Team, or Enterprise. See [Anthropic's guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for details.
+
+## Option B: Developer Config (mcp-remote)
+
+If Custom Connectors aren't available on your plan, or you prefer the developer config approach:
+
+**Prerequisite:** [Node.js](https://nodejs.org) (LTS) must be installed.
 
 1. Open Claude Desktop
 2. Click the **Claude** menu (top-left on Mac, top bar on Windows)
@@ -23,19 +41,15 @@ This opens `claude_desktop_config.json`. Add the `mcpServers` section:
   "mcpServers": {
     "cited": {
       "command": "npx",
-      "args": ["mcp-remote", "https://mcp.youcited.com"]
+      "args": ["mcp-remote", "https://mcp.youcited.com/mcp"]
     }
   }
 }
 ```
 
-Save the file and close the text editor.
-
-## Step 2: Restart Claude Desktop
+Save the file, then quit and reopen Claude Desktop (Cmd+Q on Mac, or close fully on Windows).
 
-Quit Claude Desktop completely (Cmd+Q on Mac, or close fully on Windows), then reopen it.
-
-## Step 3: Try It Out
+## Try It Out
 
 Start a new conversation in Claude Desktop and try any of these:
 
@@ -43,16 +57,20 @@ Start a new conversation in Claude Desktop and try any of these:
 - **"Run a GEO audit on [business name]"** — audits your AI search presence
 - **"Check my Cited account status"** — verifies you're connected
 
-On first use, your browser will open to log in to your Cited account. After logging in, you'll be redirected back automatically. This only happens once.
+On first use, your browser will open to log in to your Cited account. After logging in, you'll be redirected back automatically. This only happens once per session.
 
 ## Troubleshooting
 
-**Browser login popup doesn't appear:**
+**"Not authenticated" or 401 errors:**
+- Disconnect and reconnect the Cited connector — this triggers a fresh login
+- Or restart Claude Desktop fully (not just close the window)
+
+**Browser login popup doesn't appear (Option B):**
 - Make sure Node.js is installed: open a terminal and type `node --version`
 - Make sure you saved the config file correctly
-- Restart Claude Desktop fully (not just close the window)
+- Restart Claude Desktop fully
 
-**"npx not found" error:**
+**"npx not found" error (Option B):**
 - Install Node.js from [nodejs.org](https://nodejs.org) (LTS version recommended)
 - Restart Claude Desktop after installing Node.js
 
@@ -65,5 +83,6 @@ Once connected, Claude can:
 - **Generate recommendations** — get actionable insights to improve your AI search visibility
 - **Create solutions** — detailed implementation steps for each recommendation
 - **Check health scores** — see your overall GEO health at a glance
+- **Monitor usage** — check plan limits and account statistics
 
 Just ask Claude in plain English — no commands to memorize.