cortexdb-mcp 0.7.4__tar.gz → 0.7.5__tar.gz

{cortexdb_mcp-0.7.4 → cortexdb_mcp-0.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortexdb-mcp
-Version: 0.7.4
+Version: 0.7.5
 Summary: MCP Server for CortexDB — expose memory operations to AI agents
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -41,7 +41,7 @@ cortexdb-mcp --tool-profile code
 This materially reduces tool-schema context while retaining natural-language
 retrieval, typed traversal, prefix symbol discovery, and directory inventory.
 
-That's it. On first launch the server hits `POST /v1/auth/signup`, mints a free-tier PASETO token + scope for itself, and caches them under `~/.config/cortexdb-mcp/state.json` (Linux/macOS) or `%APPDATA%\cortexdb-mcp\state.json` (Windows). Re-launches reuse the cached identity until the token expires (7 days).
+That's it. On first launch the server hits `POST /v1/auth/signup`, mints a free-tier PASETO token + scope for itself, and caches them under `~/.config/cortexdb-mcp/state.json` (Linux/macOS) or `%APPDATA%\cortexdb-mcp\state.json` (Windows). Re-launches reuse the cached identity until the token expires (7 days); the cached `expires_at` is checked at load, and a token the server rejects with 401 is discarded and re-minted automatically, so no hand-deletion of `state.json` is needed. Signup runs against any configured `CORTEXDB_URL`, self-hosted included; a deployment with no minter answers 503 and the server carries on unauthenticated.
 
 To target a custom deployment or pre-existing identity, set any of:
 

{cortexdb_mcp-0.7.4 → cortexdb_mcp-0.7.5}/README.md

@@ -24,7 +24,7 @@ cortexdb-mcp --tool-profile code
 This materially reduces tool-schema context while retaining natural-language
 retrieval, typed traversal, prefix symbol discovery, and directory inventory.
 
-That's it. On first launch the server hits `POST /v1/auth/signup`, mints a free-tier PASETO token + scope for itself, and caches them under `~/.config/cortexdb-mcp/state.json` (Linux/macOS) or `%APPDATA%\cortexdb-mcp\state.json` (Windows). Re-launches reuse the cached identity until the token expires (7 days).
+That's it. On first launch the server hits `POST /v1/auth/signup`, mints a free-tier PASETO token + scope for itself, and caches them under `~/.config/cortexdb-mcp/state.json` (Linux/macOS) or `%APPDATA%\cortexdb-mcp\state.json` (Windows). Re-launches reuse the cached identity until the token expires (7 days); the cached `expires_at` is checked at load, and a token the server rejects with 401 is discarded and re-minted automatically, so no hand-deletion of `state.json` is needed. Signup runs against any configured `CORTEXDB_URL`, self-hosted included; a deployment with no minter answers 503 and the server carries on unauthenticated.
 
 To target a custom deployment or pre-existing identity, set any of:
 

{cortexdb_mcp-0.7.4 → cortexdb_mcp-0.7.5}/cortexdb_mcp/check_call.py

@@ -76,6 +76,10 @@ PATH_ALIASES = {
     "/recall": "/v1/recall",
 }
 
+#: The fields of `ForgetRequest.selector` on the wire. They are NESTED under
+#: `selector`; the route rejects them at the top level with 422 INVALID_BODY.
+_SELECTOR_KEYS = ("memory_ids", "about_subject", "about_entity", "predicate")
+
 #: SDK methods, mirroring the guidance the SDKs themselves now raise.
 SDK_METHODS = {
     "experience", "experience_bulk", "recall", "answer", "compose", "forget",
@@ -142,6 +146,7 @@ def check_http(method: str, path: str, body: dict[str, Any] | None = None) -> Ve
         path = path.split("?", 1)[0]
     path = "/" + path.strip("/") if path else ""
     call = f"{method} {path}"
+    has_body = bool(body)
     body = body or {}
 
     if (method, path) not in ROUTES:
@@ -181,14 +186,36 @@ def check_http(method: str, path: str, body: dict[str, Any] | None = None) -> Ve
         problems.extend(_check_scope(body["scope"]))
     # The one cross-field rule the server enforces and agents keep hitting.
     if path.startswith("/v1/forget"):
-        selectors = [k for k in ("memory_ids", "about_subject", "about_entity", "predicate")
-                     if body.get(k)]
+        # Selectors live UNDER `selector` on the wire (ForgetRequest.selector),
+        # never at the top level. Reading only the top level meant this rule
+        # never fired for a real body -- which is how the MCP server's own
+        # memory_delete shipped a body the validator called valid and the
+        # server refused with 400 on every call (M1).
+        selector = body.get("selector")
+        selector = selector if isinstance(selector, dict) else {}
+        selectors = [k for k in _SELECTOR_KEYS if selector.get(k)]
+        misplaced = [k for k in _SELECTOR_KEYS if body.get(k)]
+        if misplaced:
+            problems.append(
+                f"{', '.join(misplaced)} must live under `selector`, not at the "
+                f"top level. The route rejects unknown top-level fields with "
+                f"422 INVALID_BODY (expected: scope, layers, selector, cascade, "
+                f"confirm_all, audit_note/reason, from_preview_id)."
+            )
         if selectors and body.get("confirm_all"):
             problems.append(
                 f"selector ({', '.join(selectors)}) combined with confirm_all=true is "
                 f"refused (AMBIGUOUS_SELECTOR_CONFIRM_ALL). confirm_all authorizes a "
-                f"SCOPE-WIDE erase; a selector narrows it. Use confirm_all=false with "
-                f"the selector, or drop the selector for a scope-wide forget."
+                f"SCOPE-WIDE erase; a selector narrows it. Drop confirm_all to delete "
+                f"exactly the selected memories, or drop the selector for a "
+                f"scope-wide forget."
+            )
+        if has_body and not selectors and not misplaced and not body.get("confirm_all"):
+            problems.append(
+                "no selector and no confirm_all: the route refuses an empty "
+                "selector without confirmation (422 "
+                "EMPTY_SELECTOR_WITHOUT_CONFIRMATION). Name what to delete "
+                "under `selector`, or set confirm_all=true for the whole scope."
             )
     notes = [n for n in [spec.get("notes")] if n]
     return Verdict(valid=not problems, call=call, problems=problems, notes=notes)

cortexdb_mcp-0.7.5/cortexdb_mcp/config.py

@@ -0,0 +1,278 @@
+"""Configuration management for the CortexDB MCP server.
+
+Reads settings from environment variables with sensible defaults.
+
+The MCP server targets the v1 API surface by default
+(``https://api-v1.cortexdb.ai``). Three auth paths are supported:
+
+1. **Anonymous one-click** — leave ``CORTEXDB_API_KEY`` unset and the server
+   will call ``POST /v1/auth/signup`` on first launch (against ANY configured
+   URL, self-hosted included), caching the resulting PASETO token, actor,
+   scope and ``expires_at`` under ``~/.config/cortexdb-mcp/state.json``.
+   Re-launches reuse the cached token until it expires: a lapsed cache is
+   treated as absent, and a token the server rejects with 401 is discarded and
+   re-minted once, so a stale ``state.json`` never has to be deleted by hand.
+
+2. **Bring your own PASETO** — set ``CORTEXDB_API_KEY`` to a PASETO ``v4.public.*``
+   token. The server still needs ``CORTEXDB_ACTOR`` and ``CORTEXDB_SCOPE`` so
+   it can send the matching ``X-Cortex-Actor`` header.
+
+3. **Static operator key** — set ``CORTEXDB_API_KEY`` to a deployment's
+   ``CORTEX_API_KEY``. Such a key does not expire, and is never discarded or
+   re-minted on a 401; the error surfaces to the caller instead. (The older
+   ``cx_live_`` / Turso customer-key path is retired server-side.)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+#: Refresh a cached anonymous token this long before its stated expiry, so a
+#: call started just under the wire doesn't 401 mid-flight.
+EXPIRY_SKEW_SECONDS = 300
+
+#: A token whose remaining life exceeds this is treated as non-expiring.
+#: Auth-disabled / static-API-key deployments synthesize ``exp = i64::MAX / 2``
+#: (~1.46e11 years), which rendered as a literal 4611686016638011224-second
+#: countdown. Anything past a century is a sentinel, not a deadline.
+NON_EXPIRING_THRESHOLD_SECONDS = 100 * 365 * 24 * 3600
+
+
+def parse_expiry(value: str | None) -> datetime | None:
+    """Parse an RFC3339 expiry into an aware UTC datetime, or None.
+
+    Returns None for absent, empty, or unparseable input — the server sends an
+    EMPTY ``x-cortex-token-expires-at`` for non-expiring credentials, because
+    its sentinel ``exp`` overflows ``DateTime::from_timestamp``.
+    """
+    if not value:
+        return None
+    text = value.strip()
+    if not text:
+        return None
+    if text.endswith(("Z", "z")):
+        text = text[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def expiry_is_sentinel(seconds: float) -> bool:
+    """Is this ``expires_in`` a non-expiry sentinel rather than a deadline?"""
+    return seconds >= NON_EXPIRING_THRESHOLD_SECONDS
+
+
+def _state_path() -> Path:
+    """Where the cached anonymous-signup token lives.
+
+    Uses XDG_CONFIG_HOME on Linux/macOS, %APPDATA% on Windows, with a
+    sensible fallback for both.
+    """
+    if os.name == "nt":
+        base = Path(os.environ.get("APPDATA", str(Path.home() / "AppData" / "Roaming")))
+    else:
+        base = Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config")))
+    return base / "cortexdb-mcp" / "state.json"
+
+
+@dataclass
+class CortexMCPConfig:
+    """Configuration for connecting to a CortexDB instance.
+
+    Attributes:
+        url: Base URL of the CortexDB HTTP API.
+        api_key: PASETO bearer token (or legacy cx_live_ key in v0 mode).
+        actor: ActorId sent as the X-Cortex-Actor header. Required for v1.
+        scope: Default scope path for write/recall calls. Required for v1.
+        tenant_id: Legacy tenant id for v0 calls. Defaults to None.
+        expires_at: RFC3339 expiry of ``api_key`` when the mint reported one.
+        anonymous: Whether ``api_key`` was minted by anonymous signup.
+        timeout: HTTP request timeout in seconds.
+    """
+
+    url: str = "https://api-v1.cortexdb.ai"
+    api_key: str | None = None
+    actor: str | None = None
+    scope: str | None = None
+    tenant_id: str | None = None
+    # RFC3339 expiry of ``api_key``, when known (anonymous signup reports one).
+    # None means "unknown / does not expire", never "already expired".
+    expires_at: str | None = None
+    # True when ``api_key`` came from an anonymous signup (this process or a
+    # cached one), so the server may discard and re-mint it on rejection. An
+    # operator-supplied CORTEXDB_API_KEY is never discarded — we surface the
+    # 401 instead of silently swapping identities underneath them.
+    anonymous: bool = False
+    # Default public-recall reach. "holistic" = the scope + authorized ancestors
+    # + authorized descendants, never siblings (the server default); "descend"
+    # = the scope + authorized descendants; "granular" = exact scope.
+    view: str = "holistic"
+    timeout: float = 30.0
+
+    # Set by save_state() / from_env() when an anonymous signup happens; used
+    # by the server to indicate whether persistence is enabled. Kept off the
+    # dataclass init signature so tests can construct configs directly.
+    state_file: Path = field(default_factory=_state_path)
+
+    @classmethod
+    def from_env(cls) -> "CortexMCPConfig":
+        """Build configuration from environment variables.
+
+        Environment variables
+        ---------------------
+        CORTEXDB_URL          -- API base URL (default ``https://api-v1.cortexdb.ai``).
+        CORTEXDB_API_KEY      -- PASETO token (preferred) or legacy v0 key.
+        CORTEXDB_ACTOR        -- ActorId for X-Cortex-Actor (e.g. ``user:alice``).
+        CORTEXDB_SCOPE        -- Default scope path for tool calls.
+        CORTEXDB_VIEW         -- Default public-recall reach: ``holistic``
+                                 (scope + authorized ancestors + authorized
+                                 descendants, never siblings), ``descend``
+                                 (scope + authorized descendants), or ``granular``.
+        CORTEXDB_TENANT_ID    -- Legacy tenant id (v0 callers only).
+        CORTEXDB_TIMEOUT      -- Request timeout in seconds (default ``30.0``).
+
+        When CORTEXDB_API_KEY is unset, the server will look for a cached
+        state file written by a previous anonymous signup; failing that,
+        the next outgoing request triggers a fresh ``/v1/auth/signup``.
+        """
+        url = os.environ.get("CORTEXDB_URL", cls.url)
+        cfg = cls(
+            url=url,
+            api_key=os.environ.get("CORTEXDB_API_KEY"),
+            actor=os.environ.get("CORTEXDB_ACTOR"),
+            scope=os.environ.get("CORTEXDB_SCOPE"),
+            tenant_id=os.environ.get("CORTEXDB_TENANT_ID"),
+            view=os.environ.get("CORTEXDB_VIEW", cls.view),
+            timeout=float(os.environ.get("CORTEXDB_TIMEOUT", str(cls.timeout))),
+        )
+
+        # If env didn't provide credentials, hydrate from the on-disk cache
+        # (anonymous signups from prior MCP-server launches). The cache only
+        # applies when CORTEXDB_API_KEY is unset, so an explicit env key
+        # always wins. We call `_state_path()` here (vs. reading
+        # cfg.state_file) so tests can monkeypatch the module-level
+        # function and influence resolution.
+        cfg.state_file = _state_path()
+        if cfg.api_key is None:
+            cached = _load_state(cfg.state_file)
+            # M4: an expired cached token used to be reused until every call
+            # 401'd, with "delete state.json" as the only recovery. Treat a
+            # lapsed (or nearly lapsed) cache as absent so the next request
+            # mints a fresh identity instead.
+            if cached and cached_token_is_usable(cached):
+                cfg.api_key = cached.get("token")
+                cfg.actor = cfg.actor or cached.get("actor")
+                cfg.scope = cfg.scope or cached.get("scope")
+                cfg.expires_at = cached.get("expires_at")
+                cfg.anonymous = True
+        return cfg
+
+    def token_is_expiring(self, *, now: datetime | None = None) -> bool:
+        """Is ``api_key`` past (or within the skew window of) its expiry?
+
+        False when no expiry is known — an unknown expiry is not a lapsed one.
+        """
+        return not expiry_is_future(self.expires_at, now=now)
+
+    def adopt_signup(
+        self, token: str, actor: str, scope: str, expires_at: str | None
+    ) -> None:
+        """Install a freshly minted anonymous identity and cache it."""
+        self.api_key = token
+        self.actor = actor
+        self.scope = scope
+        self.expires_at = expires_at
+        self.anonymous = True
+        self.save_state(token, actor, scope, expires_at)
+
+    def forget_credentials(self) -> None:
+        """Drop an anonymous identity the server rejected, in memory and on
+        disk, so the next request signs up again rather than replaying a dead
+        token. A no-op for operator-supplied keys: we never discard those."""
+        if not self.anonymous:
+            return
+        self.api_key = None
+        self.expires_at = None
+        self.anonymous = False
+        try:
+            self.state_file.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+    def save_state(
+        self, token: str, actor: str, scope: str, expires_at: str | None = None
+    ) -> None:
+        """Persist an anonymous-signup outcome so subsequent launches reuse
+        the same identity. Writes are best-effort — failures (perm denied,
+        full disk, etc.) are silently swallowed because the server is still
+        functional with an in-memory token."""
+        try:
+            self.state_file.parent.mkdir(parents=True, exist_ok=True)
+            self.state_file.write_text(
+                json.dumps(
+                    {
+                        "token": token,
+                        "actor": actor,
+                        "scope": scope,
+                        # M4: without this the cache had no way to know the
+                        # token had lapsed.
+                        **({"expires_at": expires_at} if expires_at else {}),
+                    },
+                    indent=2,
+                ),
+                encoding="utf-8",
+            )
+            # Best-effort tighten permissions on the secret-bearing file.
+            try:
+                os.chmod(self.state_file, 0o600)
+            except OSError:
+                pass
+        except OSError:
+            pass
+
+
+def expiry_is_future(expires_at: str | None, *, now: datetime | None = None) -> bool:
+    """Does ``expires_at`` leave more than the skew window of useful life?
+
+    An absent / unparseable expiry counts as usable: it means "unknown", and a
+    non-expiring credential reports exactly that. Only a parseable expiry that
+    has (nearly) arrived is a refusal.
+    """
+    deadline = parse_expiry(expires_at)
+    if deadline is None:
+        return True
+    moment = now or datetime.now(timezone.utc)
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=timezone.utc)
+    return (deadline - moment).total_seconds() > EXPIRY_SKEW_SECONDS
+
+
+def cached_token_is_usable(
+    cached: dict[str, str], *, now: datetime | None = None
+) -> bool:
+    """Is a cached signup state still worth replaying?"""
+    if not cached.get("token"):
+        return False
+    return expiry_is_future(cached.get("expires_at"), now=now)
+
+
+def _load_state(path: Path) -> dict[str, str] | None:
+    """Read a cached signup state. Returns None on any error — the caller
+    falls back to env-only config."""
+    try:
+        if not path.exists():
+            return None
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if isinstance(data, dict) and "token" in data:
+            return {k: str(v) for k, v in data.items() if isinstance(v, str)}
+    except (OSError, json.JSONDecodeError):
+        pass
+    return None

{cortexdb_mcp-0.7.4 → cortexdb_mcp-0.7.5}/cortexdb_mcp/render.py

@@ -4,10 +4,14 @@ Single source of truth for projecting the v1 wire shapes into readable text,
 shared by the MCP tools (``server.py``) and the insights engine
 (``insights.py``).
 
-Ground truth (verified against a live ``/v1/recall``): the StratifiedPack
-returns recalled *events* inside ``context_block`` (NOT ``layers.events`` —
-that layer is empty on the synthesized-recall path), while ``layers`` carries
-the derived ``facts`` / ``beliefs`` / ``episodes``. A v1 Fact serializes its
+Ground truth (re-verified against a live ``/v1/recall`` on v0.9.10): the
+StratifiedPack renders recalled *events* into ``context_block`` AND returns
+them structurally in ``layers.events`` (with ``context.labels`` and
+``context.observed_at``) — an older note here claimed that layer was always
+empty on the synthesized-recall path, which is no longer true and cost
+``advanced_search`` its label filters. ``layers`` also carries the derived
+``facts`` / ``beliefs`` / ``episodes``. ``memories_from_context`` remains the
+fallback for packs that carry a context block and no events layer. A v1 Fact serializes its
 triple FLAT — ``subject`` / ``predicate`` / ``object`` are top-level keys, with
 no ``triple`` wrapper — and ``subject`` / ``object`` are tagged ``TypedValue``
 objects: ``{"type":"entity","id":...,"name":...}`` or