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

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

@@ -1,3 +1,24 @@
+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.
@@ -71,6 +92,90 @@ 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.
+
+### Claude Desktop (remote — recommended)
+
+No local install required. Add this to your Claude Desktop config (`Settings → Developer → Edit Config`):
+
+```json
+{
+  "mcpServers": {
+    "cited": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.youcited.com/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. A browser window will open for authentication on first use.
+
+> **Prerequisite:** [Node.js](https://nodejs.org) (LTS) must be installed for `npx`.
+
+### Claude Desktop (local stdio)
+
+```json
+{
+  "mcpServers": {
+    "cited": {
+      "command": "uvx",
+      "args": ["cited-mcp"],
+      "env": {
+        "CITED_TOKEN": "your-jwt-token"
+      }
+    }
+  }
+}
+```
+
+Get your token with `cited login` then `cited auth token`.
+
+### Cursor
+
+Add a `.cursor/mcp.json` file to your project root (or `~/.cursor/mcp.json` for global access):
+
+```json
+{
+  "mcpServers": {
+    "cited": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.youcited.com/mcp"]
+    }
+  }
+}
+```
+
+Verify Node.js is installed (`node --version`), or install with `brew install node`.
+
+Open Settings (`Cmd+,`) → search "MCP" → verify the server shows a green status. Use tools in Composer (Agent mode).
+
+### Example
+
+Once connected, ask Claude something like:
+
+> "List my businesses, then run a GEO audit on Acme Corp using the default template. When it's done, generate recommendations and show me the top insights."
+
+Claude will chain the tools automatically — `list_businesses` → `start_audit` → `get_audit_status` → `start_recommendation` → `get_recommendation_insights`.
+
+### Available Tools
+
+| Category | Tools |
+|----------|-------|
+| **Auth** | `check_auth_status`, `login` |
+| **Businesses** | `list_businesses`, `get_business`, `create_business`, `update_business`, `delete_business`, `crawl_business`, `get_health_scores` |
+| **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` |
+| **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` |
+
+See [`packages/mcp/README.md`](packages/mcp/README.md) for full details, environment variables, and development instructions.
+
+---
+
 ## Global Flags
 
 These flags apply to every command and must be placed immediately after `cited`:

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

@@ -1,24 +1,3 @@
-Metadata-Version: 2.4
-Name: cited-cli
-Version: 0.3.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.3.2
-Requires-Dist: rich>=13.0.0
-Requires-Dist: typer>=0.15.0
-Provides-Extra: dev
-Requires-Dist: cited-mcp>=0.3.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'
-Provides-Extra: mcp
-Requires-Dist: cited-mcp>=0.3.2; 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.
@@ -92,6 +71,90 @@ 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.
+
+### Claude Desktop (remote — recommended)
+
+No local install required. Add this to your Claude Desktop config (`Settings → Developer → Edit Config`):
+
+```json
+{
+  "mcpServers": {
+    "cited": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.youcited.com/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. A browser window will open for authentication on first use.
+
+> **Prerequisite:** [Node.js](https://nodejs.org) (LTS) must be installed for `npx`.
+
+### Claude Desktop (local stdio)
+
+```json
+{
+  "mcpServers": {
+    "cited": {
+      "command": "uvx",
+      "args": ["cited-mcp"],
+      "env": {
+        "CITED_TOKEN": "your-jwt-token"
+      }
+    }
+  }
+}
+```
+
+Get your token with `cited login` then `cited auth token`.
+
+### Cursor
+
+Add a `.cursor/mcp.json` file to your project root (or `~/.cursor/mcp.json` for global access):
+
+```json
+{
+  "mcpServers": {
+    "cited": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.youcited.com/mcp"]
+    }
+  }
+}
+```
+
+Verify Node.js is installed (`node --version`), or install with `brew install node`.
+
+Open Settings (`Cmd+,`) → search "MCP" → verify the server shows a green status. Use tools in Composer (Agent mode).
+
+### Example
+
+Once connected, ask Claude something like:
+
+> "List my businesses, then run a GEO audit on Acme Corp using the default template. When it's done, generate recommendations and show me the top insights."
+
+Claude will chain the tools automatically — `list_businesses` → `start_audit` → `get_audit_status` → `start_recommendation` → `get_recommendation_insights`.
+
+### Available Tools
+
+| Category | Tools |
+|----------|-------|
+| **Auth** | `check_auth_status`, `login` |
+| **Businesses** | `list_businesses`, `get_business`, `create_business`, `update_business`, `delete_business`, `crawl_business`, `get_health_scores` |
+| **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` |
+| **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` |
+
+See [`packages/mcp/README.md`](packages/mcp/README.md) for full details, environment variables, and development instructions.
+
+---
+
 ## Global Flags
 
 These flags apply to every command and must be placed immediately after `cited`:

{cited_cli-0.3.2 → cited_cli-0.3.4}/cited-plugins/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "cited",
-      "source": ".",
+      "source": "./",
       "description": "Audit, optimize, and monitor AI search presence for any business",
       "version": "0.3.2",
       "author": {

cited_cli-0.3.4/cited-plugins/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "cited": {
+      "type": "http",
+      "url": "https://mcpdev.youcited.com"
+    }
+  }
+}

cited_cli-0.3.4/cited-plugins/CLAUDE_DESKTOP_SETUP.md

@@ -0,0 +1,69 @@
+# Setting Up Cited for Claude Desktop
+
+This guide walks you through connecting Claude Desktop to the Cited GEO platform. Once set up, you can ask Claude to audit your business's AI search presence, generate recommendations, and create solutions — all through conversation.
+
+## What You Need
+
+- **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
+
+1. Open Claude Desktop
+2. Click the **Claude** menu (top-left on Mac, top bar on Windows)
+3. Click **Settings**
+4. Click **Developer** in the left sidebar
+5. Click **Edit Config**
+
+This opens `claude_desktop_config.json`. Add the `mcpServers` section:
+
+```json
+{
+  "mcpServers": {
+    "cited": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.youcited.com"]
+    }
+  }
+}
+```
+
+Save the file and close the text editor.
+
+## Step 2: Restart Claude Desktop
+
+Quit Claude Desktop completely (Cmd+Q on Mac, or close fully on Windows), then reopen it.
+
+## Step 3: Try It Out
+
+Start a new conversation in Claude Desktop and try any of these:
+
+- **"List my businesses"** — shows all your businesses on Cited
+- **"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.
+
+## Troubleshooting
+
+**Browser login popup doesn't appear:**
+- 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)
+
+**"npx not found" error:**
+- Install Node.js from [nodejs.org](https://nodejs.org) (LTS version recommended)
+- Restart Claude Desktop after installing Node.js
+
+## What Can Claude Do With Cited?
+
+Once connected, Claude can:
+
+- **List and manage your businesses** — view, create, update, or delete businesses
+- **Run GEO audits** — check how your business appears in AI search results (ChatGPT, Perplexity, Gemini, etc.)
+- **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
+
+Just ask Claude in plain English — no commands to memorize.

{cited_cli-0.3.2 → cited_cli-0.3.4}/packages/core/pyproject.toml

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

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

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

{cited_cli-0.3.2 → cited_cli-0.3.4}/packages/core/src/cited_core/api/endpoints.py

@@ -6,6 +6,7 @@ CLI_LOGIN = "/auth/cli-login"
 CLI_REGISTER = "/auth/cli-register"
 CLI_VERIFY_EMAIL = "/auth/cli-verify-email"
 CLI_OAUTH_START = "/auth/cli-oauth-start"
+AUTHORIZE_APP = "/auth/authorize-app"
 LOGOUT = "/auth/logout"
 ME = "/auth/me"
 

{cited_cli-0.3.2 → cited_cli-0.3.4}/packages/core/src/cited_core/config/constants.py

@@ -14,6 +14,12 @@ FRONTEND_URLS: dict[str, str] = {
     "local": "http://localhost:3000",
 }
 
+MCP_URLS: dict[str, str] = {
+    "prod": "https://mcp.youcited.com",
+    "dev": "https://mcpdev.youcited.com",
+    "local": "http://localhost:8080",
+}
+
 DEFAULT_ENV = "prod"
 CONFIG_DIR = Path.home() / ".cited"
 CONFIG_FILE = CONFIG_DIR / "config.toml"

cited_cli-0.3.4/packages/mcp/Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install core first (dependency), then mcp
+COPY packages/core/ /app/packages/core/
+COPY packages/mcp/ /app/packages/mcp/
+
+RUN pip install --no-cache-dir /app/packages/core /app/packages/mcp
+
+ENV PORT=8080
+EXPOSE 8080
+
+CMD ["cited-mcp-remote"]

cited_cli-0.3.4/packages/mcp/README.md

@@ -0,0 +1,204 @@
+# cited-mcp
+
+MCP server for the [Cited](https://youcited.com) Generative Engine Optimization (GEO) platform. Exposes 28 tools that let AI assistants like Claude manage businesses, run GEO audits, generate recommendations, and create solutions — all through the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+## Install
+
+```bash
+pip install cited-mcp
+```
+
+Or run directly without installing:
+
+```bash
+uvx cited-mcp
+```
+
+## Usage
+
+### Claude Desktop (remote server — recommended)
+
+No local install required. Add this to your Claude Desktop config (`Settings → Developer → Edit Config`):
+
+```json
+{
+  "mcpServers": {
+    "cited": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.youcited.com/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. A browser window will open for authentication on first use.
+
+> **Prerequisite:** [Node.js](https://nodejs.org) must be installed for `npx`.
+
+### Claude Desktop (local stdio server)
+
+If you prefer running the server locally:
+
+```json
+{
+  "mcpServers": {
+    "cited": {
+      "command": "uvx",
+      "args": ["cited-mcp"],
+      "env": {
+        "CITED_TOKEN": "your-jwt-token"
+      }
+    }
+  }
+}
+```
+
+Get your token by running `cited login` and then `cited auth token` with the [cited-cli](https://pypi.org/project/cited-cli/).
+
+### Claude Code
+
+Add the remote server as a tool source in your Claude Code settings or use the `cited-plugins/` configuration from the monorepo.
+
+### Cursor
+
+Add a `.cursor/mcp.json` file to your project root (or configure globally in `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "cited": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.youcited.com/mcp"]
+    }
+  }
+}
+```
+
+Verify Node.js is installed first:
+
+```bash
+node --version   # should print v18+ or v20+
+```
+
+If not installed, run `brew install node` or download from [nodejs.org](https://nodejs.org).
+
+Then in Cursor: open Settings (`Cmd+,`) → search "MCP" → verify the server appears and shows a green status indicator. Use Cited tools in Composer (Agent mode) or Chat by asking Claude to interact with your GEO data.
+
+### Standalone
+
+```bash
+# Local stdio mode (requires CITED_TOKEN env var)
+CITED_TOKEN=your-jwt-token cited-mcp
+
+# Remote HTTP mode (used for hosted deployment)
+cited-mcp-remote
+```
+
+## Tools
+
+### Auth
+| Tool | Description |
+|------|-------------|
+| `check_auth_status` | Check current authentication status |
+| `login` | Authenticate via browser OAuth flow |
+| `logout` | Clear stored authentication token |
+
+### Businesses
+| Tool | Description |
+|------|-------------|
+| `list_businesses` | List all businesses on your account |
+| `get_business` | Get details for a specific business |
+| `create_business` | Create a new business |
+| `update_business` | Update business details |
+| `delete_business` | Delete a business |
+| `crawl_business` | Start a website crawl for a business |
+| `get_health_scores` | Get GEO health scores for a business |
+
+### Audit Templates
+| Tool | Description |
+|------|-------------|
+| `list_audit_templates` | List all audit templates |
+| `get_audit_template` | Get a specific template with questions |
+| `create_audit_template` | Create a new audit template |
+| `update_audit_template` | Update template name, description, or questions |
+| `delete_audit_template` | Delete an audit template |
+
+### Audits
+| Tool | Description |
+|------|-------------|
+| `start_audit` | Run a GEO audit using a template |
+| `get_audit_status` | Check audit job status |
+| `get_audit_result` | Get completed audit results |
+| `list_audits` | List all audits |
+
+### Recommendations
+| Tool | Description |
+|------|-------------|
+| `start_recommendation` | Generate recommendations from a completed audit |
+| `get_recommendation_status` | Check recommendation job status |
+| `get_recommendation_result` | Get full recommendation results |
+| `get_recommendation_insights` | Get actionable insights with risk levels and coverage scores |
+| `list_recommendations` | List all recommendation jobs |
+
+### Solutions
+| Tool | Description |
+|------|-------------|
+| `start_solution` | Generate a solution for a specific insight or tip |
+| `get_solution_status` | Check solution job status |
+| `get_solution_result` | Get completed solution with implementation steps |
+| `list_solutions` | List all solutions |
+
+### Jobs
+| Tool | Description |
+|------|-------------|
+| `get_job_status` | Check status of any job by type and ID |
+
+## Example Workflow
+
+Once connected, ask Claude to run a full GEO audit:
+
+> "List my businesses, then run a GEO audit on Acme Corp using the default template. When it's done, generate recommendations and show me the top insights."
+
+Claude will chain the tools automatically:
+
+1. `list_businesses` → find the business ID
+2. `list_audit_templates` → find or create a template
+3. `start_audit` → kick off the audit
+4. `get_audit_status` → poll until complete
+5. `start_recommendation` → generate recommendations
+6. `get_recommendation_insights` → display actionable results
+7. `start_solution` → generate implementation steps for top issues
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CITED_TOKEN` | JWT auth token (stdio mode) |
+| `CITED_AGENT_API_KEY` | Agent API key (alternative to JWT) |
+| `CITED_API_URL` | API base URL (default: `https://api.youcited.com`) |
+| `CITED_ENV` | Environment: `prod`, `dev`, or `local` |
+| `MCP_URL` | Public URL of this MCP server (remote mode) |
+| `JWT_SECRET` | Secret for signing OAuth tokens (remote mode) |
+
+## Development
+
+```bash
+# Install in editable mode with dev dependencies
+pip install -e packages/core
+pip install -e "packages/mcp[dev]"
+
+# Run tests
+pytest tests/test_mcp_server.py tests/test_mcp_tools.py -v
+
+# Lint and type check
+ruff check packages/mcp/
+mypy packages/mcp/src --ignore-missing-imports
+```
+
+## Privacy Policy
+
+See our [Privacy Policy](https://youcited.com/privacy) for details on data collection, usage, storage, and third-party sharing.
+
+## License
+
+Proprietary — see [youcited.com](https://youcited.com) for terms.

cited_cli-0.3.4/packages/mcp/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: cited
+description: Audit, optimize, and monitor your business's visibility in AI-powered search engines
+---
+
+# Cited — AI Search Visibility Platform
+
+Cited helps businesses measure and improve how they appear in AI-powered search results from ChatGPT, Claude, Perplexity, and Gemini. Use these tools to run GEO (Generative Engine Optimization) audits, get actionable recommendations, and generate ready-to-deploy solutions.
+
+## Core Workflow
+
+The typical flow is: **Business Setup → Audit → Recommendations → Solutions**
+
+### 1. Business Setup
+- `check_auth_status` — Verify authentication and check plan limits
+- `list_businesses` — See existing businesses
+- `create_business` — Add a new business (requires name, website, description)
+- `crawl_business` — Crawl the business website to gather data for analysis
+
+### 2. Run an Audit
+- `create_audit_template` — Define what questions to audit (e.g., "What is [business]?", "Best [industry] tools")
+- `start_audit` — Launch the audit using a template
+- `get_audit_status` — Poll until the audit completes (typically 2-4 minutes)
+- `get_audit_result` — Retrieve visibility scores, citation rates, and competitor data
+
+### 3. Generate Recommendations
+- `start_recommendation` — Analyze audit results and generate improvement recommendations
+- `get_recommendation_insights` — Get structured insights with question-level analysis, competitor head-to-head comparisons, and strengthening tips. Each insight includes `source_type` and `source_id` needed for the next step.
+
+### 4. Create Solutions
+- `start_solution` — Generate implementation artifacts (schema markup, content templates, outreach playbooks) for a specific insight
+- `get_solution_result` — Retrieve the solution with downloadable artifacts
+
+## Example Prompts
+
+**Run a full GEO audit:**
+> "List my businesses, then run a GEO audit on [business name]. When it's done, show me my visibility scores and which competitors are being cited instead of me."
+
+**Competitive analysis:**
+> "Run an audit on my business for these questions: 'Best CRM software for small business', 'Top sales automation tools', 'What is [my product]?'. Then generate recommendations and show me the head-to-head comparisons with my top competitors."
+
+**Generate solutions:**
+> "Look at my latest audit recommendations and generate solutions for the top 3 highest-risk insights. I want to see the schema markup and content changes I need to make."
+
+**Monitor over time:**
+> "Show me the health scores for my business and compare them to my last audit. What has improved and what still needs work?"
+
+## Tips
+
+- Always call `check_auth_status` first to verify authentication and plan limits
+- Audits take 2-4 minutes — poll `get_audit_status` every 15 seconds
+- Use `get_recommendation_insights` (not `get_recommendation_result`) for structured, actionable data
+- Solutions have a concurrency limit of 3 — wait for one batch to complete before starting more
+- Each insight's `source_type` and `source_id` map directly to `start_solution` parameters

{cited_cli-0.3.2 → cited_cli-0.3.4}/packages/mcp/pyproject.toml

@@ -4,18 +4,21 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cited-mcp"
-version = "0.3.2"
+version = "0.3.4"
 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.3.2",
+    "cited-core>=0.3.4",
     "mcp>=1.26.0",
+    "PyJWT>=2.8.0",
 ]
 
 [project.scripts]
 cited-mcp = "cited_mcp:run_server"
+cited-mcp-remote = "cited_mcp.remote:run_remote_server"
 
 [project.optional-dependencies]
 dev = [