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

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

@@ -1,23 +1,23 @@
 Metadata-Version: 2.4
 Name: cited-cli
-Version: 0.5.0
+Version: 0.5.1
 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.0
+Requires-Dist: cited-core>=0.5.1
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.15.0
 Provides-Extra: dev
-Requires-Dist: cited-mcp>=0.5.0; extra == 'dev'
+Requires-Dist: cited-mcp>=0.5.1; 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.0; extra == 'mcp'
+Requires-Dist: cited-mcp>=0.5.1; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # Cited CLI

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

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

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

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

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

@@ -1,6 +1,6 @@
 # cited-mcp
 
-MCP server for the [Cited](https://youcited.com) Generative Engine Optimization (GEO) platform. Exposes 56 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 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/).
 
 ## Install
 
@@ -231,9 +231,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 — **22 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) — **38 tools** |
-| **Pro** | Everything in Scale + usage stats, HQ dashboard, analytics, agent API — **56 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 — **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** |
 
 When a user calls a tool above their plan, the server returns a structured error with an upgrade link:
 

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

@@ -50,9 +50,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 (19 tools)
-- **Scale**: Full write access — create/update/delete, solutions, export, cancel (32 tools)
-- **Pro**: Everything + HQ dashboard, analytics, agent API (42 tools)
+- **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)
 
 Always call `check_auth_status` first — it shows the user's plan and remaining limits.
 

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

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cited-mcp"
-version = "0.5.0"
+version = "0.5.1"
 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.0",
+    "cited-core>=0.5.1",
     "mcp>=1.27.0",
     "PyJWT>=2.8.0",
     "PyYAML>=6.0",

{cited_cli-0.5.0 → cited_cli-0.5.1}/packages/mcp/src/cited_mcp/remote.py

@@ -204,6 +204,56 @@ class _OAuthEventLogMiddleware:
             logger.info("[oauth-event] %s", kv)
 
 
+class _RequestContextMiddleware:
+    """ASGI middleware that captures the request's source IP and User-Agent
+    into contextvars consumed by the tool-call decorator.
+
+    Why: ``tool_call`` log lines previously carried no source-identifying
+    metadata beyond the (possibly absent) decoded user JWT. When a probe
+    came in with a non-standard token — logged as user=``unknown`` — there
+    was no way to trace the source. Threading an HTTP request object
+    through every tool function is invasive; contextvars stay scoped to
+    the request's async task without touching tool signatures.
+
+    For stdio transport this middleware is not in the chain, so the
+    contextvars stay None and the log fields render as null.
+
+    We prefer the leftmost value of ``X-Forwarded-For`` when present
+    because the ALB inserts the original client IP there and the immediate
+    ``scope["client"]`` is the ALB's internal address. Trusting X-F-F is
+    only safe behind a known proxy — which is the deploy topology here.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        from cited_mcp.tools._helpers import _request_ip, _request_ua
+
+        headers = {k: v for k, v in scope.get("headers", [])}
+        xff = headers.get(b"x-forwarded-for", b"").decode("latin-1", errors="replace")
+        if xff:
+            ip: str | None = xff.split(",")[0].strip() or None
+        else:
+            client = scope.get("client") or ("?", 0)
+            ip = client[0] if client and client[0] != "?" else None
+
+        ua_bytes = headers.get(b"user-agent", b"")
+        ua = ua_bytes.decode("latin-1", errors="replace")[:120] if ua_bytes else None
+
+        token_ip = _request_ip.set(ip)
+        token_ua = _request_ua.set(ua)
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            _request_ip.reset(token_ip)
+            _request_ua.reset(token_ua)
+
+
 @asynccontextmanager
 async def cited_remote_lifespan(server: FastMCP) -> AsyncIterator[CitedContext]:
     """Lifespan for the remote MCP server.
@@ -403,9 +453,13 @@ def run_remote_server() -> None:
     starlette_app = server.streamable_http_app()
     # Order: oauth-event log on the OUTSIDE of the registration patcher so
     # patcher-rejected /register calls (400 invalid_redirect_uri) still
-    # produce an event line.
+    # produce an event line. RequestContextMiddleware sits innermost so
+    # its contextvars (ip, user_agent) are set in the same task that
+    # dispatches the tool call.
     patched_app = _OAuthEventLogMiddleware(
-        _PatchRegistrationMiddleware(starlette_app)
+        _PatchRegistrationMiddleware(
+            _RequestContextMiddleware(starlette_app)
+        )
     )
 
     config = uvicorn.Config(

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

@@ -21,6 +21,18 @@
 #      this file.
 
 versions:
+  - version: "0.5.1"
+    released: "2026-05-18"
+    # Telemetry-only release: tool surface is unchanged (fingerprint matches
+    # 0.5.0). Adds forensic fields to every tool_call log line — ip,
+    # user_agent, and a new auth_kind discriminator (anonymous / agent_key /
+    # oauth_email / oauth_no_email / oauth_malformed / stdio_email /
+    # stdio_no_email / stdio_malformed). Also fixes client_id extraction
+    # which was reading from user_jwt claims (always null in prod) instead
+    # of the OAuth access token. Motivated by a 2026-05-02 dev probe that
+    # logged user=unknown with no traceable source.
+    fingerprint: "5bef45100c53"
+
   - version: "0.5.0"
     released: "2026-05-11"
     # Three new read-only list_* tools to enable persona/product/buyer-intent

{cited_cli-0.5.0 → cited_cli-0.5.1}/packages/mcp/src/cited_mcp/tools/_helpers.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import contextlib
+import contextvars
 import functools
 import hashlib
 import json
@@ -22,6 +23,20 @@ from cited_mcp.context import CitedContext
 
 logger = logging.getLogger("cited_mcp.usage")
 
+# ---------------------------------------------------------------------------
+# Per-request forensic context (set by remote.py _RequestContextMiddleware).
+#
+# These let tool_call log lines carry the request's source IP and User-Agent
+# without threading an HTTP request object through every tool function. For
+# stdio transport (no HTTP) they remain None and are emitted as null in logs.
+# ---------------------------------------------------------------------------
+_request_ip: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "cited_mcp_request_ip", default=None
+)
+_request_ua: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "cited_mcp_request_ua", default=None
+)
+
 # ---------------------------------------------------------------------------
 # Response size guardrails
 # ---------------------------------------------------------------------------
@@ -244,18 +259,84 @@ def _extract_user(token: str | None) -> str:
         return "unknown"
 
 
-def _extract_client_id(token: str | None) -> str | None:
-    """Decode OAuth client_id from a JWT (for connector-mix analytics)."""
-    if not token:
+def _extract_client_id_from_oauth() -> str | None:
+    """Return the OAuth client_id from the current access token, truncated.
+
+    The MCP server's client_id is itself a signed JWT (RFC 7591 dynamic
+    registration encoded into the id), so we truncate to a 12-char prefix
+    sufficient to group connector traffic without bloating log lines.
+
+    Returns None for stdio transport (no OAuth context), or whenever the
+    access-token contextvar is unset.
+
+    Note: this used to decode the user_jwt looking for client_id/aud/azp
+    claims, but backend session JWTs do not carry OAuth-client identity —
+    so the field was always empty in production logs. This implementation
+    reads from the OAuth access token instead.
+    """
+    try:
+        from mcp.server.auth.middleware.auth_context import get_access_token
+    except ImportError:
         return None
     try:
-        payload = pyjwt.decode(token, options={"verify_signature": False})
-        cid = payload.get("client_id") or payload.get("aud") or payload.get("azp")
-        if isinstance(cid, list):
-            cid = cid[0] if cid else None
-        return str(cid) if cid else None
+        access_token = get_access_token()
     except Exception:
         return None
+    if not access_token:
+        return None
+    cid = getattr(access_token, "client_id", None)
+    if not cid:
+        return None
+    return str(cid)[:12]
+
+
+def _extract_auth_kind(
+    ctx: Context[Any, CitedContext, Any], token: str | None
+) -> str:
+    """Categorize the auth path for forensic logging.
+
+    Returns one of:
+      - ``anonymous`` — no token, no agent key
+      - ``agent_key`` — CitedClient has agent_api_key set (stdio mode)
+      - ``oauth_email`` — OAuth flow, user_jwt has email claim
+      - ``oauth_no_email`` — OAuth flow, user_jwt decoded but no email
+      - ``oauth_malformed`` — OAuth flow, user_jwt couldn't be decoded
+      - ``stdio_email`` — stdio mode, token is a JWT with email claim
+      - ``stdio_no_email`` — stdio mode, token decoded but no email
+      - ``stdio_malformed`` — stdio mode, token isn't a parseable JWT
+
+    Lets us tell apart the practical cases — including the case where
+    ``_extract_user`` returns ``"unknown"`` because the token was not a
+    JWT at all versus because the JWT had no email/sub claim. Without
+    this, the ``<unknown>`` bucket in usage reports is unactionable.
+    """
+    try:
+        lc = ctx.request_context.lifespan_context
+        if getattr(lc.client, "agent_api_key", None):
+            return "agent_key"
+    except Exception:
+        pass
+
+    method = "stdio"
+    try:
+        from mcp.server.auth.middleware.auth_context import get_access_token
+
+        if get_access_token() is not None:
+            method = "oauth"
+    except Exception:
+        pass
+
+    if not token:
+        return "anonymous" if method == "stdio" else "oauth_no_token"
+
+    try:
+        payload = pyjwt.decode(token, options={"verify_signature": False})
+    except Exception:
+        return f"{method}_malformed"
+
+    if payload.get("email"):
+        return f"{method}_email"
+    return f"{method}_no_email"
 
 
 # ---------------------------------------------------------------------------
@@ -384,7 +465,8 @@ def log_tool_call(
         token = _resolve_token(ctx)
         rl_key = _rate_limit_key(token)
         user = _extract_user(token)
-        client_id = _extract_client_id(token)
+        auth_kind = _extract_auth_kind(ctx, token)
+        client_id = _extract_client_id_from_oauth()
         request_id = uuid.uuid4().hex[:12]
         start = time.monotonic()
         build = _get_build_identity()
@@ -399,7 +481,10 @@ def log_tool_call(
                 "request_id": request_id,
                 "tool": tool_name,
                 "user": user,
+                "auth_kind": auth_kind,
                 "client_id": client_id,
+                "ip": _request_ip.get(),
+                "user_agent": _request_ua.get(),
                 "server_version": build["server_version"],
                 "tools_fingerprint": build["tools_fingerprint"],
                 "deployment_id": build["deployment_id"],
@@ -407,7 +492,15 @@ def log_tool_call(
             if resources:
                 payload["resources"] = resources
             payload.update(extra)
-            logger.info(json.dumps(payload, default=str))
+            # CodeQL flags this as clear-text logging of sensitive data because
+            # `user` is sourced from a JWT email claim. This is by design —
+            # operator usage reports (scripts/mcp_usage_report.py) attribute
+            # tool calls to users by email, which is necessary for forensics
+            # and abuse investigation. Logs flow to a private CloudWatch group
+            # with restricted IAM access. Email is not transmitted anywhere
+            # else from this line. If we later move to hashed identifiers,
+            # the suppression can be removed.
+            logger.info(json.dumps(payload, default=str))  # noqa: E501 lgtm[py/clear-text-logging-sensitive-data]
 
         # Rate limit check
         if rl_err := _check_rate_limit(rl_key):

{cited_cli-0.5.0 → cited_cli-0.5.1}/packages/mcp/tests/test_auth_provider.py

@@ -1,4 +1,5 @@
 """Tests for the CitedOAuthProvider — specifically JWT expiry handling."""
+
 from __future__ import annotations
 
 import asyncio
@@ -59,14 +60,16 @@ class TestLoadAccessToken:
     def test_rejects_expired_user_jwt(self):
         provider = _make_provider()
         now = int(time.time())
-        token = provider._encode_token({
-            "typ": "access",
-            "sub": "client-123",
-            "scopes": ["cited"],
-            "user_jwt": _make_jwt(-60),  # expired backend JWT
-            "exp": now + 3600,
-            "iat": now,
-        })
+        token = provider._encode_token(
+            {
+                "typ": "access",
+                "sub": "client-123",
+                "scopes": ["cited"],
+                "user_jwt": _make_jwt(-60),  # expired backend JWT
+                "exp": now + 3600,
+                "iat": now,
+            }
+        )
 
         result = run(provider.load_access_token(token))
         assert result is None
@@ -75,14 +78,16 @@ class TestLoadAccessToken:
         provider = _make_provider()
         valid_jwt = _make_jwt(3600)
         now = int(time.time())
-        token = provider._encode_token({
-            "typ": "access",
-            "sub": "client-123",
-            "scopes": ["cited"],
-            "user_jwt": valid_jwt,
-            "exp": now + 3600,
-            "iat": now,
-        })
+        token = provider._encode_token(
+            {
+                "typ": "access",
+                "sub": "client-123",
+                "scopes": ["cited"],
+                "user_jwt": valid_jwt,
+                "exp": now + 3600,
+                "iat": now,
+            }
+        )
 
         result = run(provider.load_access_token(token))
         assert result is not None
@@ -94,14 +99,16 @@ class TestLoadRefreshToken:
         provider = _make_provider()
         client = _make_client()
         now = int(time.time())
-        token = provider._encode_token({
-            "typ": "refresh",
-            "sub": client.client_id,
-            "scopes": ["cited"],
-            "user_jwt": _make_jwt(-60),  # expired backend JWT
-            "exp": now + 86400,
-            "iat": now,
-        })
+        token = provider._encode_token(
+            {
+                "typ": "refresh",
+                "sub": client.client_id,
+                "scopes": ["cited"],
+                "user_jwt": _make_jwt(-60),  # expired backend JWT
+                "exp": now + 86400,
+                "iat": now,
+            }
+        )
 
         result = run(provider.load_refresh_token(client, token))
         assert result is None
@@ -111,14 +118,16 @@ class TestLoadRefreshToken:
         client = _make_client()
         valid_jwt = _make_jwt(3600)
         now = int(time.time())
-        token = provider._encode_token({
-            "typ": "refresh",
-            "sub": client.client_id,
-            "scopes": ["cited"],
-            "user_jwt": valid_jwt,
-            "exp": now + 86400,
-            "iat": now,
-        })
+        token = provider._encode_token(
+            {
+                "typ": "refresh",
+                "sub": client.client_id,
+                "scopes": ["cited"],
+                "user_jwt": valid_jwt,
+                "exp": now + 86400,
+                "iat": now,
+            }
+        )
 
         result = run(provider.load_refresh_token(client, token))
         assert result is not None

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

@@ -73,6 +73,79 @@ class TestIsToolAllowed:
     def test_get_usage_stats_enterprise_allowed(self):
         assert is_tool_allowed("get_usage_stats", "enterprise") is True
 
+    # ---- v0.4.0 / v0.5.0 write tools — Scale-gated.
+    # Tier misclassifications here translate to either revenue loss (giving
+    # Scale features away free) or angry-customer paging (gating something
+    # that should be free). Per-tool assertions catch both directions; the
+    # bulk count test only catches gross deletions.
+
+    # Profile competitors
+    def test_list_profile_competitors_base_allowed(self):
+        assert is_tool_allowed("list_profile_competitors", "free") is True
+
+    def test_set_profile_competitors_growth_blocked(self):
+        assert is_tool_allowed("set_profile_competitors", "growth") is False
+
+    def test_set_profile_competitors_scale_allowed(self):
+        assert is_tool_allowed("set_profile_competitors", "scale") is True
+
+    # Persona CRUD
+    def test_create_persona_growth_blocked(self):
+        assert is_tool_allowed("create_persona", "growth") is False
+
+    def test_create_persona_scale_allowed(self):
+        assert is_tool_allowed("create_persona", "scale") is True
+
+    def test_update_persona_growth_blocked(self):
+        assert is_tool_allowed("update_persona", "growth") is False
+
+    def test_update_persona_scale_allowed(self):
+        assert is_tool_allowed("update_persona", "scale") is True
+
+    def test_delete_persona_growth_blocked(self):
+        assert is_tool_allowed("delete_persona", "growth") is False
+
+    def test_delete_persona_scale_allowed(self):
+        assert is_tool_allowed("delete_persona", "scale") is True
+
+    # Product CRUD
+    def test_create_product_growth_blocked(self):
+        assert is_tool_allowed("create_product", "growth") is False
+
+    def test_create_product_scale_allowed(self):
+        assert is_tool_allowed("create_product", "scale") is True
+
+    def test_update_product_growth_blocked(self):
+        assert is_tool_allowed("update_product", "growth") is False
+
+    def test_update_product_scale_allowed(self):
+        assert is_tool_allowed("update_product", "scale") is True
+
+    def test_delete_product_growth_blocked(self):
+        assert is_tool_allowed("delete_product", "growth") is False
+
+    def test_delete_product_scale_allowed(self):
+        assert is_tool_allowed("delete_product", "scale") is True
+
+    # Buyer-intent CRUD (v0.5.0 added update + delete)
+    def test_create_buyer_intent_growth_blocked(self):
+        assert is_tool_allowed("create_buyer_intent", "growth") is False
+
+    def test_create_buyer_intent_scale_allowed(self):
+        assert is_tool_allowed("create_buyer_intent", "scale") is True
+
+    def test_update_buyer_intent_growth_blocked(self):
+        assert is_tool_allowed("update_buyer_intent", "growth") is False
+
+    def test_update_buyer_intent_scale_allowed(self):
+        assert is_tool_allowed("update_buyer_intent", "scale") is True
+
+    def test_delete_buyer_intent_growth_blocked(self):
+        assert is_tool_allowed("delete_buyer_intent", "growth") is False
+
+    def test_delete_buyer_intent_scale_allowed(self):
+        assert is_tool_allowed("delete_buyer_intent", "scale") is True
+
 
 class TestRequiredTier:
     def test_ungated_tool(self):