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

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

@@ -1,23 +1,23 @@
 Metadata-Version: 2.4
 Name: cited-cli
-Version: 0.3.14
+Version: 0.3.15
 Summary: CLI for the Cited GEO platform
 Author-email: Cited <support@youcited.com>
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 Requires-Python: >=3.11
-Requires-Dist: cited-core>=0.3.14
+Requires-Dist: cited-core>=0.3.15
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.15.0
 Provides-Extra: dev
-Requires-Dist: cited-mcp>=0.3.14; extra == 'dev'
+Requires-Dist: cited-mcp>=0.3.15; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
 Provides-Extra: mcp
-Requires-Dist: cited-mcp>=0.3.14; extra == 'mcp'
+Requires-Dist: cited-mcp>=0.3.15; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # Cited CLI

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

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

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

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

{cited_cli-0.3.14 → cited_cli-0.3.15}/packages/core/src/cited_core/api/client.py

@@ -40,6 +40,15 @@ class CitedClient:
     def close(self) -> None:
         self._client.close()
 
+    def set_request_id(self, request_id: str | None) -> None:
+        """Stamp X-Request-ID on subsequent outgoing requests so the cited
+        backend can echo it in its access logs and produce end-to-end traces.
+        Pass None to clear."""
+        if request_id:
+            self._client.headers["X-Request-ID"] = request_id
+        else:
+            self._client.headers.pop("X-Request-ID", None)
+
     def __enter__(self) -> CitedClient:
         return self
 

{cited_cli-0.3.14 → cited_cli-0.3.15}/packages/mcp/pyproject.toml

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

{cited_cli-0.3.14 → cited_cli-0.3.15}/packages/mcp/src/cited_mcp/tool_changelog.yaml

@@ -21,6 +21,57 @@
 #      this file.
 
 versions:
+  - version: "0.3.15"
+    released: "2026-05-05"
+    # Fingerprint unchanged from 0.3.14 image runtime — pure observability +
+    # logging-enrichment release; no tool surface change. (The 0.3.14 entry
+    # below pins defa3022aedb, which was the host-venv compute at release
+    # prep — differing from the deployed image's 1c4fed943fff. Future
+    # entries should pin runtime fingerprints; this collision is benign
+    # because there's nothing in the surface for clients to act on.)
+    fingerprint: "1c4fed943fff"
+    tools_added: []
+    tools_changed: []
+    tools_removed: []
+    behavior_changed:
+      - area: structured_logging
+        change_summary: |
+          Every ``tool_call`` log line now carries:
+          - ``server_version`` and ``tools_fingerprint`` (so log entries
+            self-identify which build emitted them)
+          - ``deployment_id`` from ``CITED_DEPLOYMENT_ID`` env var
+            (format ``<env>-<short-sha>-<unix-ts>``, set by the deploy
+            script — uniquely identifies a single deploy attempt)
+          - ``client_id`` extracted from the OAuth JWT (lets us tell
+            Claude Desktop traffic from Claude.ai traffic)
+          - ``resources`` map with ID-shaped kwargs (``business_id``,
+            ``audit_id``, ``job_id``, ``source_id``, etc.) — enough to
+            correlate user activity with backend records, never raw
+            content like buyer profiles or audit descriptions.
+          On failures the line now also carries ``error_type`` and
+          ``status_code`` pulled from the typed-error response, so the
+          dashboard can categorise failures without grepping messages.
+      - area: end_to_end_tracing
+        change_summary: |
+          The MCP now stamps ``X-Request-ID`` on every outgoing call to
+          the cited backend (matching the ``request_id`` already in the
+          tool_call log line). The backend can echo this to its own
+          access logs to produce end-to-end traces — when a customer
+          reports "buyer_fit_query 500 with request_id abc123" the
+          owner can find both MCP-side and backend-side log entries
+          for the same request.
+      - area: deploy_pipeline
+        change_summary: |
+          Companion ``deploy-mcp.sh`` improvements (cited-mcp-infra
+          repo, commit 5542667): split log groups (prod writes to
+          ``/ecs/cited-mcp-prod`` instead of mixing into the dev
+          group), real stability check that fails the deploy when ECS
+          silently rolls back to a prior task definition (the failure
+          mode that hid today's IAM-blocked prod deploy), and
+          deployment_id stamping. CloudWatch dashboard ``cited-mcp``
+          + saved Insights queries (``cited-mcp/usage/per-user`` etc.)
+          + failure-burst alarms also added.
+
   - version: "0.3.14"
     released: "2026-05-05"
     fingerprint: "defa3022aedb"

{cited_cli-0.3.14 → cited_cli-0.3.15}/packages/mcp/src/cited_mcp/tools/_helpers.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import contextlib
 import functools
 import hashlib
 import json
@@ -52,9 +53,7 @@ def _truncate_response(data: Any, max_bytes: int = _MAX_RESPONSE_BYTES) -> Any:
 
     if isinstance(data, dict):
         # Find list-valued fields and iteratively shrink the longest
-        list_fields = {
-            k: v for k, v in data.items() if isinstance(v, list) and len(v) > 0
-        }
+        list_fields = {k: v for k, v in data.items() if isinstance(v, list) and len(v) > 0}
         truncated_fields: list[str] = []
         attempts = 0
         while (
@@ -165,9 +164,7 @@ def _auth_check(cited_ctx: CitedContext) -> dict[str, Any] | None:
     return None
 
 
-def _resolve_business_id(
-    cited_ctx: CitedContext, business_id: str | None
-) -> str | None:
+def _resolve_business_id(cited_ctx: CitedContext, business_id: str | None) -> str | None:
     """Return *business_id* if provided, else the session default."""
     return business_id or cited_ctx.default_business_id
 
@@ -241,14 +238,107 @@ def _extract_user(token: str | None) -> str:
     if not token:
         return "anonymous"
     try:
-        payload = pyjwt.decode(
-            token, options={"verify_signature": False}
-        )
+        payload = pyjwt.decode(token, options={"verify_signature": False})
         return str(payload.get("email") or payload.get("sub") or "unknown")
     except Exception:
         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:
+        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
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Build identity — stamped into every tool_call line for log correlation.
+# Computed once at module import: cheap, deterministic, survives the request.
+# ---------------------------------------------------------------------------
+
+_BUILD_IDENTITY: dict[str, str] = {}
+
+
+def _get_build_identity() -> dict[str, str]:
+    """Return cached server_version, tools_fingerprint, deployment_id.
+
+    Lazy + memoised because compute_tools_fingerprint walks the live server's
+    tool registry — fine to do once but expensive per request.
+    """
+    if _BUILD_IDENTITY:
+        return _BUILD_IDENTITY
+    try:
+        from cited_mcp import __version__ as ver
+        from cited_mcp.server import compute_tools_fingerprint
+        from cited_mcp.server import mcp as live_mcp
+
+        _BUILD_IDENTITY["server_version"] = ver
+        _BUILD_IDENTITY["tools_fingerprint"] = compute_tools_fingerprint(live_mcp)
+    except Exception:
+        # Don't crash logging if the import fails — emit blanks instead.
+        _BUILD_IDENTITY["server_version"] = "unknown"
+        _BUILD_IDENTITY["tools_fingerprint"] = "unknown"
+    _BUILD_IDENTITY["deployment_id"] = os.environ.get("CITED_DEPLOYMENT_ID", "local")
+    return _BUILD_IDENTITY
+
+
+# ---------------------------------------------------------------------------
+# Resource ID extraction for tool_call logs.
+#
+# We log obvious-shaped IDs (business_id, audit_id, job_id, source_id, etc.)
+# so customer-support and abuse-investigation flows can correlate user
+# activity with platform records. We deliberately do NOT log free-text
+# content (audit descriptions, buyer profiles, etc.) — those can contain
+# sensitive material.
+# ---------------------------------------------------------------------------
+
+# Tool kwargs that name a resource we want to log. Match against suffixes:
+# *_id and *_type are the conventions across the surface.
+_RESOURCE_KEYS = {
+    "business_id",
+    "audit_id",
+    "baseline_id",
+    "job_id",
+    "recommendation_job_id",
+    "audit_job_id",
+    "named_audit_id",
+    "template_id",
+    "solution_id",
+    "recommendation_id",
+    "source_id",
+    "source_type",
+    "action_id",
+    "check_id",
+    "question_id",
+}
+
+# Maximum length of a logged ID value — avoids the case where a tool author
+# accidentally maps a long string into one of these key names.
+_MAX_RESOURCE_VALUE_LEN = 80
+
+
+def _extract_resource_ids(kwargs: dict[str, Any]) -> dict[str, str]:
+    """Pull ID-shaped kwargs into a flat dict, redacting anything else."""
+    out: dict[str, str] = {}
+    for key, val in kwargs.items():
+        if key not in _RESOURCE_KEYS:
+            continue
+        if val is None:
+            continue
+        s = str(val)
+        if len(s) > _MAX_RESOURCE_VALUE_LEN:
+            continue
+        out[key] = s
+    return out
+
+
 # ---------------------------------------------------------------------------
 # Per-user tier cache (avoids /auth/me call on every tool invocation)
 # ---------------------------------------------------------------------------
@@ -294,31 +384,52 @@ def log_tool_call(
         token = _resolve_token(ctx)
         rl_key = _rate_limit_key(token)
         user = _extract_user(token)
+        client_id = _extract_client_id(token)
         request_id = uuid.uuid4().hex[:12]
         start = time.monotonic()
+        build = _get_build_identity()
+        resources = _extract_resource_ids(kwargs)
+        # Header-propagation context — set inside the try block below so that
+        # _get_ctx failures still flow through structured error handling.
+        cited_ctx_for_header: CitedContext | None = None
+
+        def _log(event: str, **extra: Any) -> None:
+            payload: dict[str, Any] = {
+                "event": event,
+                "request_id": request_id,
+                "tool": tool_name,
+                "user": user,
+                "client_id": client_id,
+                "server_version": build["server_version"],
+                "tools_fingerprint": build["tools_fingerprint"],
+                "deployment_id": build["deployment_id"],
+            }
+            if resources:
+                payload["resources"] = resources
+            payload.update(extra)
+            logger.info(json.dumps(payload, default=str))
 
         # Rate limit check
         if rl_err := _check_rate_limit(rl_key):
-            logger.info(
-                json.dumps(
-                    {
-                        "event": "rate_limited",
-                        "request_id": request_id,
-                        "tool": tool_name,
-                        "user": user,
-                    }
-                )
-            )
+            _log("rate_limited")
             rl_err["_request_id"] = request_id
             return rl_err
 
         try:
+            # Propagate request_id to the cited backend for end-to-end traces.
+            cited_ctx_for_header = _get_ctx(ctx)
+            cited_ctx_for_header.client.set_request_id(request_id)
+
             # Plan gating check (skip for auth tools — must always be accessible)
             from cited_mcp.plan_gating import is_tool_allowed, upgrade_message
 
             _AUTH_TOOLS = {
-                "ping", "check_auth_status", "login", "logout",
-                "get_pricing", "upgrade_plan",
+                "ping",
+                "check_auth_status",
+                "login",
+                "logout",
+                "get_pricing",
+                "upgrade_plan",
             }
             if tool_name not in _AUTH_TOOLS and token:
                 cited_ctx = _get_ctx(ctx)
@@ -327,39 +438,31 @@ def log_tool_call(
                     if not is_tool_allowed(tool_name, user_tier):
                         gate_err = upgrade_message(tool_name, user_tier)
                         gate_err["_request_id"] = request_id
-                        logger.info(
-                            json.dumps(
-                                {
-                                    "event": "plan_gated",
-                                    "request_id": request_id,
-                                    "tool": tool_name,
-                                    "user": user,
-                                    "current_tier": user_tier,
-                                    "required_tier": gate_err[
-                                        "required_tier"
-                                    ],
-                                }
-                            )
+                        _log(
+                            "plan_gated",
+                            current_tier=user_tier,
+                            required_tier=gate_err["required_tier"],
                         )
                         return gate_err
 
             result = await func(ctx, *args, **kwargs)
             duration_ms = int((time.monotonic() - start) * 1000)
-            is_error = isinstance(result, dict) and result.get(
-                "error"
-            ) is True
-            logger.info(
-                json.dumps(
-                    {
-                        "event": "tool_call",
-                        "request_id": request_id,
-                        "tool": tool_name,
-                        "user": user,
-                        "duration_ms": duration_ms,
-                        "success": not is_error,
-                    }
-                )
-            )
+            is_error = isinstance(result, dict) and result.get("error") is True
+            extra: dict[str, Any] = {
+                "duration_ms": duration_ms,
+                "success": not is_error,
+            }
+            if is_error and isinstance(result, dict):
+                # Pull through the typed error fields the tools already emit
+                # so failures are categorisable in the dashboard without
+                # re-grepping raw error messages.
+                if et := result.get("error_type"):
+                    extra["error_type"] = et
+                if sc := result.get("status_code"):
+                    extra["status_code"] = sc
+                if pr := result.get("payment_required"):
+                    extra["payment_required"] = pr
+            _log("tool_call", **extra)
             # Inject request_id into response
             if isinstance(result, dict):
                 result["_request_id"] = request_id
@@ -372,19 +475,7 @@ def log_tool_call(
 
         except httpx.TimeoutException:
             duration_ms = int((time.monotonic() - start) * 1000)
-            logger.info(
-                json.dumps(
-                    {
-                        "event": "tool_call",
-                        "request_id": request_id,
-                        "tool": tool_name,
-                        "user": user,
-                        "duration_ms": duration_ms,
-                        "success": False,
-                        "error_type": "timeout",
-                    }
-                )
-            )
+            _log("tool_call", duration_ms=duration_ms, success=False, error_type="timeout")
             return {
                 "error": True,
                 "error_type": "upstream_timeout",
@@ -398,19 +489,7 @@ def log_tool_call(
 
         except httpx.ConnectError:
             duration_ms = int((time.monotonic() - start) * 1000)
-            logger.info(
-                json.dumps(
-                    {
-                        "event": "tool_call",
-                        "request_id": request_id,
-                        "tool": tool_name,
-                        "user": user,
-                        "duration_ms": duration_ms,
-                        "success": False,
-                        "error_type": "connection_error",
-                    }
-                )
-            )
+            _log("tool_call", duration_ms=duration_ms, success=False, error_type="connection_error")
             return {
                 "error": True,
                 "error_type": "connection_error",
@@ -424,29 +503,27 @@ def log_tool_call(
 
         except Exception as exc:
             duration_ms = int((time.monotonic() - start) * 1000)
-            logger.info(
-                json.dumps(
-                    {
-                        "event": "tool_call",
-                        "request_id": request_id,
-                        "tool": tool_name,
-                        "user": user,
-                        "duration_ms": duration_ms,
-                        "success": False,
-                        "error_type": type(exc).__name__,
-                    }
-                )
+            _log(
+                "tool_call",
+                duration_ms=duration_ms,
+                success=False,
+                error_type=type(exc).__name__,
             )
             return {
                 "error": True,
                 "error_type": type(exc).__name__,
                 "message": (
-                    "An unexpected error occurred. "
-                    "This is usually transient — please retry."
+                    "An unexpected error occurred. This is usually transient — please retry."
                 ),
                 "retriable": True,
                 "_request_id": request_id,
             }
+        finally:
+            # Clear the request_id header so the next caller's tool_call
+            # doesn't accidentally inherit this one's correlation id.
+            if cited_ctx_for_header is not None:
+                with contextlib.suppress(Exception):
+                    cited_ctx_for_header.client.set_request_id(None)
 
     return wrapper
 
@@ -461,8 +538,7 @@ def _api_error_response(e: CitedAPIError) -> dict[str, Any]:
 
     for code, substring, hint in _ERROR_HINTS:
         if e.status_code == code and (
-            substring is None
-            or (e.message and substring.lower() in e.message.lower())
+            substring is None or (e.message and substring.lower() in e.message.lower())
         ):
             response["hint"] = hint
             break

{cited_cli-0.3.14 → cited_cli-0.3.15}/packages/mcp/tests/test_tools.py

@@ -1556,6 +1556,78 @@ class TestDecoratorErrorHandling:
         assert "_request_id" in result
 
 
+class TestEnrichedLogging:
+    """Verify tool_call lines carry server_version, fingerprint, deployment_id,
+    resource IDs, and propagate X-Request-ID to the cited backend."""
+
+    def test_tool_call_log_includes_build_identity_and_resources(self, ctx, caplog):
+        """Successful tool_call log must carry server_version, tools_fingerprint,
+        deployment_id, AND extracted resource IDs from kwargs."""
+        import json
+        import logging
+
+        from cited_mcp.tools._helpers import _BUILD_IDENTITY
+
+        client = ctx.request_context.lifespan_context.client
+        client.get.return_value = {"id": "biz-abc"}
+
+        with caplog.at_level(logging.INFO, logger="cited_mcp.usage"):
+            run(get_business(ctx, business_id="biz-abc"))
+
+        tool_call_lines = [
+            json.loads(r.message)
+            for r in caplog.records
+            if r.name == "cited_mcp.usage" and '"event": "tool_call"' in r.message
+        ]
+        assert tool_call_lines, "no tool_call log line emitted"
+        rec = tool_call_lines[-1]
+        # build identity is stamped
+        assert rec["server_version"] == _BUILD_IDENTITY["server_version"]
+        assert rec["tools_fingerprint"] == _BUILD_IDENTITY["tools_fingerprint"]
+        assert "deployment_id" in rec
+        # the business_id kwarg made it into resources
+        assert rec.get("resources", {}).get("business_id") == "biz-abc"
+
+    def test_tool_call_propagates_request_id_to_client(self, ctx):
+        """The decorator must call set_request_id on the CitedClient so the
+        backend gets X-Request-ID for end-to-end correlation."""
+        client = ctx.request_context.lifespan_context.client
+        client.get.return_value = {"id": "biz-abc"}
+
+        run(get_business(ctx, business_id="biz-abc"))
+
+        # set_request_id should have been called twice: once with the
+        # request_id, once with None to clear in finally.
+        assert client.set_request_id.call_count >= 2
+        # First call carries a non-None 12-char hex request_id
+        first = client.set_request_id.call_args_list[0].args[0]
+        assert isinstance(first, str) and len(first) == 12
+        # Last call clears it
+        assert client.set_request_id.call_args_list[-1].args[0] is None
+
+    def test_tool_call_log_carries_typed_error_on_failure(self, ctx, caplog):
+        """When a tool returns {error: True, error_type: ..., status_code: ...}
+        the tool_call log line should include those fields."""
+        import json
+        import logging
+
+        client = ctx.request_context.lifespan_context.client
+        client.get.side_effect = CitedAPIError(404, "Business not found", "not_found")
+
+        with caplog.at_level(logging.INFO, logger="cited_mcp.usage"):
+            run(get_business(ctx, business_id="missing"))
+
+        tool_call_lines = [
+            json.loads(r.message)
+            for r in caplog.records
+            if r.name == "cited_mcp.usage" and '"event": "tool_call"' in r.message
+        ]
+        assert tool_call_lines
+        rec = tool_call_lines[-1]
+        assert rec["success"] is False
+        assert rec.get("status_code") == 404
+
+
 class TestTransportErrors:
     def test_timeout_returns_error(self, ctx):
         """httpx.TimeoutException should return a structured error, not crash."""

{cited_cli-0.3.14 → cited_cli-0.3.15}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cited-cli"
-version = "0.3.14"
+version = "0.3.15"
 description = "CLI 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.14",
+    "cited-core>=0.3.15",
     "typer>=0.15.0",
     "rich>=13.0.0",
 ]
@@ -20,13 +20,13 @@ dependencies = [
 cited = "cited_cli.app:main"
 
 [project.optional-dependencies]
-mcp = ["cited-mcp>=0.3.14"]
+mcp = ["cited-mcp>=0.3.15"]
 dev = [
     "pytest>=8.0",
     "respx>=0.21",
     "ruff>=0.4",
     "mypy>=1.10",
-    "cited-mcp>=0.3.14",
+    "cited-mcp>=0.3.15",
     "types-PyYAML>=6.0",
 ]
 

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

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