cited-mcp 0.3.2__tar.gz

cited_mcp-0.3.2/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.so
+.coverage
+htmlcov/
+.env
+~/.cited/

cited_mcp-0.3.2/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: cited-mcp
+Version: 0.3.2
+Summary: MCP server for the Cited GEO platform
+Author-email: Cited <support@youcited.com>
+License-Expression: LicenseRef-Proprietary
+Requires-Python: >=3.11
+Requires-Dist: cited-core>=0.3.2
+Requires-Dist: mcp>=1.26.0
+Provides-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'

cited_mcp-0.3.2/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cited-mcp"
+version = "0.3.2"
+description = "MCP server for the Cited GEO platform"
+license = "LicenseRef-Proprietary"
+requires-python = ">=3.11"
+authors = [{ name = "Cited", email = "support@youcited.com" }]
+dependencies = [
+    "cited-core>=0.3.2",
+    "mcp>=1.26.0",
+]
+
+[project.scripts]
+cited-mcp = "cited_mcp:run_server"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "respx>=0.21",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cited_mcp"]

cited_mcp-0.3.2/src/cited_mcp/__init__.py

@@ -0,0 +1,4 @@
+from __future__ import annotations
+
+from cited_core import __version__ as __version__  # noqa: F401
+from cited_mcp.server import run_server as run_server  # noqa: F401

cited_mcp-0.3.2/src/cited_mcp/__main__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from cited_mcp import run_server
+
+run_server()

cited_mcp-0.3.2/src/cited_mcp/context.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from cited_core.api.client import CitedClient
+
+
+@dataclass
+class CitedContext:
+    client: CitedClient
+    env: str
+    api_url: str

cited_mcp-0.3.2/src/cited_mcp/server.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from mcp.server.fastmcp import FastMCP
+
+from cited_core.api.client import CitedClient
+from cited_core.auth.store import TokenStore
+from cited_core.config.manager import ConfigManager
+from cited_mcp.context import CitedContext
+
+
+@asynccontextmanager
+async def cited_lifespan(server: FastMCP) -> AsyncIterator[CitedContext]:
+    """Set up CitedClient for the MCP server lifetime."""
+    config = ConfigManager()
+    env_override = os.environ.get("CITED_ENV")
+    env = config.get_environment(override=env_override)
+    api_url = config.get_api_url(env_override=env_override)
+
+    token = os.environ.get("CITED_TOKEN") or TokenStore().get_token(env)
+    agent_api_key = os.environ.get("CITED_AGENT_API_KEY") or config.get("agent_api_key")
+
+    client = CitedClient(
+        base_url=api_url,
+        token=token,
+        agent_api_key=agent_api_key,
+    )
+    try:
+        yield CitedContext(client=client, env=env, api_url=api_url)
+    finally:
+        client.close()
+
+
+mcp = FastMCP(
+    "cited",
+    instructions="Cited GEO platform — audit, optimize, and monitor AI search presence",
+    lifespan=cited_lifespan,
+)
+
+# Import tool modules to trigger @mcp.tool() registrations
+import cited_mcp.tools.auth  # noqa: I001, E402, F401
+import cited_mcp.tools.audit  # noqa: E402, F401
+import cited_mcp.tools.business  # noqa: E402, F401
+import cited_mcp.tools.job  # noqa: E402, F401
+import cited_mcp.tools.recommend  # noqa: E402, F401
+import cited_mcp.tools.solution  # noqa: E402, F401
+
+
+def run_server() -> None:
+    """Start the MCP server on stdio transport."""
+    mcp.run(transport="stdio")

cited_mcp-0.3.2/src/cited_mcp/tools/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

cited_mcp-0.3.2/src/cited_mcp/tools/_helpers.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_core.errors import CitedAPIError
+from cited_mcp.context import CitedContext
+
+
+def _get_ctx(ctx: Context[Any, CitedContext, Any]) -> CitedContext:
+    """Extract CitedContext from MCP lifespan context."""
+    lc: CitedContext = ctx.request_context.lifespan_context
+    return lc
+
+
+def _auth_check(cited_ctx: CitedContext) -> dict[str, Any] | None:
+    """Return error dict if not authenticated, else None."""
+    if cited_ctx.client.token is None:
+        return {
+            "error": True,
+            "message": "Not authenticated. Use the 'login' tool or set CITED_TOKEN env var.",
+        }
+    return None
+
+
+def _api_error_response(e: CitedAPIError) -> dict[str, Any]:
+    """Convert CitedAPIError to a structured error dict."""
+    return {
+        "error": True,
+        "status_code": e.status_code,
+        "message": e.message,
+    }

cited_mcp-0.3.2/src/cited_mcp/tools/audit.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_core.api import endpoints
+from cited_core.errors import CitedAPIError
+from cited_mcp.context import CitedContext
+from cited_mcp.server import mcp
+from cited_mcp.tools._helpers import _api_error_response, _auth_check, _get_ctx
+
+
+@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 update_audit_template(
+    ctx: Context[Any, CitedContext, Any],
+    named_audit_id: str,
+    name: str | None = None,
+    description: str | None = None,
+    questions: list[str] | None = None,
+) -> Any:
+    """Update an audit template. Questions replace ALL existing questions if provided.
+
+    Args:
+        ctx: MCP context
+        named_audit_id: Template ID to update
+        name: New template name
+        description: New description
+        questions: New list of questions (replaces all existing questions). Omit to keep existing.
+    """
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    payload: dict[str, Any] = {}
+    if name is not None:
+        payload["name"] = name
+    if description is not None:
+        payload["description"] = description
+    if questions is not None:
+        payload["questions"] = questions
+    try:
+        return cited_ctx.client.put(
+            endpoints.NAMED_AUDIT.format(named_audit_id=named_audit_id), json=payload
+        )
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def delete_audit_template(
+    ctx: Context[Any, CitedContext, Any], named_audit_id: str
+) -> Any:
+    """Delete an audit template.
+
+    Args:
+        ctx: MCP context
+        named_audit_id: Template ID to delete
+    """
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        cited_ctx.client.delete(
+            endpoints.NAMED_AUDIT.format(named_audit_id=named_audit_id)
+        )
+        return {"success": True, "message": f"Template {named_audit_id} deleted"}
+    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_mcp-0.3.2/src/cited_mcp/tools/auth.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import webbrowser
+from typing import Any
+
+import anyio
+from mcp.server.fastmcp import Context
+
+from cited_core.api import endpoints
+from cited_core.auth.oauth_server import OAuthCallbackServer
+from cited_core.auth.store import TokenStore
+from cited_core.config.constants import FRONTEND_URLS
+from cited_core.errors import CitedAPIError
+from cited_mcp.context import CitedContext
+from cited_mcp.server import mcp
+from cited_mcp.tools._helpers import _api_error_response, _auth_check, _get_ctx
+
+
+@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)
+
+
+@mcp.tool()
+async def login(ctx: Context[Any, CitedContext, Any], env: str | None = None) -> Any:
+    """Log in to Cited by opening a browser window for OAuth authentication.
+
+    Args:
+        ctx: MCP context
+        env: Optional environment override (dev, prod, local)
+    """
+    cited_ctx = _get_ctx(ctx)
+    target_env = env or cited_ctx.env
+
+    callback_server = OAuthCallbackServer(timeout=120.0)
+    callback_server.start()
+
+    frontend = FRONTEND_URLS.get(target_env, FRONTEND_URLS["prod"])
+    login_url = f"{frontend}/login?callback={callback_server.redirect_uri}"
+
+    webbrowser.open(login_url)
+
+    token = await anyio.to_thread.run_sync(callback_server.wait_for_token)
+    callback_server.shutdown()
+
+    if not token:
+        return {"error": True, "message": "Login timed out. Please try again."}
+
+    TokenStore().save_token(target_env, token)
+    cited_ctx.client.token = token
+
+    return {"success": True, "message": f"Logged in successfully (env: {target_env})"}

cited_mcp-0.3.2/src/cited_mcp/tools/business.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_core.api import endpoints
+from cited_core.errors import CitedAPIError
+from cited_mcp.context import CitedContext
+from cited_mcp.server import mcp
+from cited_mcp.tools._helpers import _api_error_response, _auth_check, _get_ctx
+
+
+@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 update_business(
+    ctx: Context[Any, CitedContext, Any],
+    business_id: str,
+    name: str | None = None,
+    website: str | None = None,
+    description: str | None = None,
+    industry: str | None = None,
+) -> Any:
+    """Update an existing business. Only provided fields are changed.
+
+    Args:
+        ctx: MCP context
+        business_id: Business ID to update
+        name: New business name
+        website: New website URL
+        description: New description
+        industry: New industry value
+    """
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    payload: dict[str, Any] = {}
+    if name is not None:
+        payload["name"] = name
+    if website is not None:
+        payload["website"] = website
+    if description is not None:
+        payload["description"] = description
+    if industry is not None:
+        payload["industry"] = industry
+    try:
+        return cited_ctx.client.put(
+            endpoints.BUSINESS.format(business_id=business_id), json=payload
+        )
+    except CitedAPIError as e:
+        return _api_error_response(e)
+
+
+@mcp.tool()
+async def delete_business(ctx: Context[Any, CitedContext, Any], business_id: str) -> Any:
+    """Delete a business and all its associated data.
+
+    Args:
+        ctx: MCP context
+        business_id: Business ID to delete
+    """
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        cited_ctx.client.delete(endpoints.BUSINESS.format(business_id=business_id))
+        return {"success": True, "message": f"Business {business_id} deleted"}
+    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_mcp-0.3.2/src/cited_mcp/tools/job.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_core.api import endpoints
+from cited_core.errors import CitedAPIError
+from cited_mcp.context import CitedContext
+from cited_mcp.server import mcp
+from cited_mcp.tools._helpers import _api_error_response, _auth_check, _get_ctx
+
+_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_mcp-0.3.2/src/cited_mcp/tools/recommend.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_core.api import endpoints
+from cited_core.errors import CitedAPIError
+from cited_mcp.context import CitedContext
+from cited_mcp.server import mcp
+from cited_mcp.tools._helpers import _api_error_response, _auth_check, _get_ctx
+
+
+@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
+
+
+@mcp.tool()
+async def list_recommendations(
+    ctx: Context[Any, CitedContext, Any], audit_job_id: str
+) -> Any:
+    """List recommendation history for a specific audit.
+
+    Args:
+        ctx: MCP context
+        audit_job_id: The audit job ID to list recommendations for
+    """
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(
+            endpoints.RECOMMEND_HISTORY.format(audit_job_id=audit_job_id)
+        )
+    except CitedAPIError as e:
+        return _api_error_response(e)

cited_mcp-0.3.2/src/cited_mcp/tools/solution.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_core.api import endpoints
+from cited_core.errors import CitedAPIError
+from cited_mcp.context import CitedContext
+from cited_mcp.server import mcp
+from cited_mcp.tools._helpers import _api_error_response, _auth_check, _get_ctx
+
+
+@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)
+
+
+@mcp.tool()
+async def list_solutions(ctx: Context[Any, CitedContext, Any]) -> Any:
+    """List solution history."""
+    cited_ctx = _get_ctx(ctx)
+    if err := _auth_check(cited_ctx):
+        return err
+    try:
+        return cited_ctx.client.get(endpoints.SOLUTION_HISTORY)
+    except CitedAPIError as e:
+        return _api_error_response(e)