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

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

@@ -1,23 +1,23 @@
 Metadata-Version: 2.4
 Name: cited-cli
-Version: 0.3.15
+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.3.15
+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.3.15; 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.3.15; extra == 'mcp'
+Requires-Dist: cited-mcp>=0.5.1; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # Cited CLI

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cited-core"
-version = "0.3.15"
+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.3.15 → cited_cli-0.5.1}/packages/core/src/cited_core/api/endpoints.py

@@ -23,6 +23,7 @@ BUSINESS = "/businesses/{business_id}"
 BUSINESS_LOGO = "/businesses/{business_id}/logo"
 HEALTH_SCORES = "/businesses/{business_id}/health-scores"
 HEALTH_SCORES_BREAKDOWN = "/businesses/{business_id}/health-scores/breakdown"
+PROFILE_COMPETITORS = "/businesses/{business_id}/profile-competitors"
 
 # Business Crawl
 CRAWL_DATA = "/businesses/{business_id}/crawl-data"
@@ -77,9 +78,16 @@ HQ_PRIORITY_STATUS = "/businesses/{business_id}/hq/priority/{action_id}/status"
 HQ_PRIORITY_SUMMARY = "/businesses/{business_id}/hq/priority/summary"
 HQ_EXPORT_PDF = "/businesses/{business_id}/hq/export/pdf"
 HQ_RECOMPUTE = "/businesses/{business_id}/hq/recompute"
+HQ_OVERVIEW_REFRESH_AUDIT = "/businesses/{business_id}/overview/refresh-audit"
+HQ_OVERVIEW_REFRESH_RECS = "/businesses/{business_id}/overview/refresh-recommendations"
+HQ_OVERVIEW_REFRESH_ALL = "/businesses/{business_id}/overview/refresh-all"
+HQ_AGENT_BRIEF = "/businesses/{business_id}/agent-brief"
 PERSONAS = "/businesses/{business_id}/personas"
+PERSONA = "/businesses/{business_id}/personas/{persona_id}"
 PRODUCTS = "/businesses/{business_id}/products"
+PRODUCT = "/businesses/{business_id}/products/{product_id}"
 BUYER_INTENTS = "/businesses/{business_id}/buyer-intents"
+BUYER_INTENT = "/businesses/{business_id}/buyer-intents/{intent_id}"
 AGENTIC_READINESS = "/businesses/{business_id}/agentic-readiness"
 TRUST_SIGNALS = "/businesses/{business_id}/trust-signals"
 

{cited_cli-0.3.15 → 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.3.15 → 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.3.15 → cited_cli-0.5.1}/packages/mcp/pyproject.toml

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

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

@@ -43,6 +43,18 @@ _SCALE_TOOLS: set[str] = {
     "mark_action_done",
     "dismiss_action",
     "get_action_progress",
+    "set_profile_competitors",
+    "create_persona",
+    "update_persona",
+    "delete_persona",
+    "create_product",
+    "update_product",
+    "delete_product",
+    "create_buyer_intent",
+    "update_buyer_intent",
+    "delete_buyer_intent",
+    "recompute_health_scores",
+    "refresh_business_overview",
 }
 
 # Tools restricted to pro+ tier
@@ -54,6 +66,7 @@ _PRO_TOOLS: set[str] = {
     "get_semantic_health",
     "buyer_fit_query",
     "get_business_hq",
+    "get_agent_brief",
     "get_analytics_trends",
     "get_analytics_dashboard",
     "compare_audits",
@@ -156,6 +169,10 @@ _BASE_TOOLS: set[str] = {
     "get_business",
     "crawl_business",
     "get_health_scores",
+    "list_profile_competitors",
+    "list_personas",
+    "list_products",
+    "list_buyer_intents",
     "list_audit_templates",
     "get_audit_template",
     "start_audit",

{cited_cli-0.3.15 → 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.3.15 → cited_cli-0.5.1}/packages/mcp/src/cited_mcp/tool_changelog.yaml

@@ -21,6 +21,176 @@
 #      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
+    # CRUD flows (agents need IDs before they can call update/delete), plus a
+    # significant parameter-schema expansion on update_business / create_business
+    # to cover the full canonical BusinessUpdate/CreateRequest field set. Also
+    # fixes a latent bug: update_business previously sent HTTP PUT against a
+    # backend PATCH route. Bumps minor (not patch) because update_business /
+    # create_business signature changes shift parameter ordering and clients
+    # diffing the fingerprint should pick this up as non-additive.
+    fingerprint: "5bef45100c53"
+    tools_added:
+      - name: list_personas
+        description: |
+          List buyer personas declared on the business profile. Required
+          before update_persona / delete_persona since the agent has no
+          other way to discover persona_ids.
+      - name: list_products
+        description: |
+          List products / service offerings declared on the business
+          profile. Required before update_product / delete_product to
+          discover product_ids.
+      - name: list_buyer_intents
+        description: |
+          List buyer-intent entries declared on the business profile.
+          Use before recommending a new create_buyer_intent to avoid
+          overlapping entries.
+      - name: update_buyer_intent
+        description: |
+          Update a buyer-intent entry (question, intent_type, priority,
+          is_answered, answering_page_url — all optional). Closes the
+          persona/product CRUD symmetry. Requires the cited backend with
+          PATCH /businesses/{id}/buyer-intents/{intent_id} (added in
+          companion backend PR).
+      - name: delete_buyer_intent
+        description: |
+          Delete a buyer intent. Confirm with the user before calling —
+          there's no undo. Requires the cited backend with
+          DELETE /businesses/{id}/buyer-intents/{intent_id}.
+    tools_changed:
+      - name: update_business
+        change_summary: |
+          Parameter set expanded from 4 fields (name, website, description,
+          industry) to the full BusinessUpdateRequest schema: adds
+          one_line_description, primary_customer, problem_solved,
+          offering_type, primary_market, service_areas,
+          headquarters_country, goals, discovery_channels,
+          success_definition, plus primary-location fields (address, city,
+          region, country). All new params are optional and keyword-only.
+          Also fixes a method bug: now sends PATCH (was PUT) to match the
+          backend @router.patch route.
+      - name: create_business
+        change_summary: |
+          Parameter set expanded to the full BusinessCreateRequest schema:
+          description is now optional (server composes from structured
+          fields if omitted); adds one_line_description, primary_customer,
+          problem_solved, offering_type, primary_market, service_areas,
+          headquarters_country, goals, discovery_channels,
+          success_definition. Existing 4-field callers unaffected
+          (description was already accepted; making it optional is
+          backward-compatible).
+
+  - version: "0.4.0"
+    released: "2026-05-08"
+    # 12 new tools + docstring/parameter-schema edits on 4 existing tools —
+    # significant surface expansion, so the minor version bumps to 0.4.0
+    # to signal a non-additive-only release for clients that diff the
+    # fingerprint.
+    fingerprint: "8197f97dcd06"
+    tools_added:
+      - name: get_agent_brief
+        description: |
+          Single-call composite "what should I focus on right now?" —
+          top priority actions, quick wins, failing deterministic checks,
+          and recent citation-rate movement. Designed to replace
+          chained get_business_hq + get_quick_wins + check_status calls
+          in opening-turn agent flows.
+      - name: list_profile_competitors
+        description: |
+          List the user-declared competitors on a business profile.
+          These bypass third-party domain filtering and rank ahead of
+          citation-only picks in head-to-head comparisons.
+      - name: set_profile_competitors
+        description: |
+          Replace the full list of profile competitors (max 10).
+          Pass [{name, website}] entries; PUT replaces. Use when the
+          user reports an obviously-relevant rival missing from H2H.
+      - name: recompute_health_scores
+        description: |
+          Force a fresh recomputation of business health scores after
+          profile/HQ edits — no crawl, no audit, just re-derive from
+          existing data.
+      - name: refresh_business_overview
+        description: |
+          Refresh cached audit / recommendation overview projections
+          for a business. scope ∈ {audit, recommendations, all}.
+      - name: create_persona
+        description: Create a target buyer persona on a business.
+      - name: update_persona
+        description: Update a persona (partial — only changed fields).
+      - name: delete_persona
+        description: Delete a persona.
+      - name: create_product
+        description: Create a product/service offering on a business.
+      - name: update_product
+        description: Update a product (partial).
+      - name: delete_product
+        description: Delete a product.
+      - name: create_buyer_intent
+        description: |
+          Create a buyer-intent entry tying personas to products
+          through specific decision moments — drives audit question
+          generation and per-intent coverage scoring.
+    tools_changed:
+      - name: get_business_hq
+        change_summary: |
+          New include flags ``include_agentic_readiness`` and
+          ``include_trust_signals`` add the agentic-readiness summary
+          and trust-signal evidence to the dashboard payload. Existing
+          callers are unaffected — both default to false.
+      - name: get_competitive_comparison
+        change_summary: |
+          Docstring now describes the new ``analysis_status`` and
+          ``last_analysis_run_at`` freshness fields on the response
+          (added in cited backend commit 2c716be). Tool behavior is
+          unchanged — these were already passed through; the docstring
+          was previously silent about them.
+      - name: get_recommendation_check_status
+        change_summary: |
+          Updated for Validation Engine Tier 4: now runs 72
+          deterministic checks (was 62). New checks fill
+          monitoring_adaptation and original_research domains
+          (knowledge_graph_linkage, aggregate_rating_present,
+          author_bio_on_blog_posts, sitemap_lastmod_freshness,
+          outbound_authority_citations, hreflang_and_lang_consistency,
+          well_known_agent_discovery). Response shape unchanged.
+      - name: crawl_business
+        change_summary: |
+          Docstring now notes the post-crawl auto-fill side effect:
+          empty business-profile fields (description, founding year,
+          NAICS, sameAs links) are populated from JSON-LD / meta tags
+          found on the homepage. User-supplied values are never
+          overwritten. (cited backend CIT-148.)
+    tools_removed: []
+    behavior_changed:
+      - area: plan_gating
+        change_summary: |
+          Tier assignments for the new tools:
+          - base (all tiers): ``list_profile_competitors``
+          - scale: ``set_profile_competitors``,
+            ``create/update/delete_persona``,
+            ``create/update/delete_product``,
+            ``create_buyer_intent``,
+            ``recompute_health_scores``,
+            ``refresh_business_overview``
+          - pro: ``get_agent_brief`` (matches the ``get_business_hq``
+            tier — same composite-dashboard semantics).
+
   - version: "0.3.15"
     released: "2026-05-05"
     # Fingerprint unchanged from 0.3.14 image runtime — pure observability +

{cited_cli-0.3.15 → 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):