cortexdb-mcp 0.7.1__tar.gz → 0.7.2__tar.gz

{cortexdb_mcp-0.7.1 → cortexdb_mcp-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortexdb-mcp
-Version: 0.7.1
+Version: 0.7.2
 Summary: MCP Server for CortexDB — expose memory operations to AI agents
 License-Expression: MIT
 Requires-Python: >=3.10

cortexdb_mcp-0.7.2/cortexdb_mcp/check_call.py

@@ -0,0 +1,239 @@
+"""Validate a CortexDB call BEFORE the agent writes it.
+
+KAN-167. Documentation search only helps an agent that knows it is unsure.
+The failure that actually produces broken integrations is the confident
+guess: the model writes `client.remember(...)` or `POST /v1/memories`, gets
+a plausible-looking error, and invents a workaround. Nothing in that loop
+tells it the real call exists under a different name.
+
+So the check runs the other way round. The agent pastes what it is ABOUT to
+write and is told whether it is valid, with the correction when it is not.
+
+Pure functions over a static contract, deliberately: no network, no
+credentials, no server. A validator an agent has to authenticate to is one
+it will skip, and this has to be cheaper than guessing to get used at all.
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+DOCS = "https://cortexdb.ai/docs"
+MANIFEST = "https://cortexdb.ai/agent/manifest.json"
+
+#: The v1 surface an integrator touches, and the required body fields.
+#: Intentionally the COMMON surface, not all 117 routes: a validator that
+#: lists everything cannot say "you meant this one".
+ROUTES: dict[tuple[str, str], dict[str, Any]] = {
+    ("POST", "/v1/experience"): {
+        "purpose": "write one memory",
+        "required": ["scope", "content"],
+        "notes": "Use ?wait=indexed when the next step recalls it.",
+    },
+    ("POST", "/v1/experience/bulk"): {
+        "purpose": "write many memories",
+        "required": ["items"],
+        "notes": "Each item carries its own scope; there is no top-level scope.",
+    },
+    ("POST", "/v1/recall"): {
+        "purpose": "retrieve a context pack",
+        "required": ["scope", "query"],
+        "notes": "view is one of raw | granular | holistic | structured | descend.",
+    },
+    ("POST", "/v1/answer"): {"purpose": "recall + LLM answer", "required": ["scope", "query"]},
+    ("POST", "/v1/compose"): {"purpose": "markdown document from memory", "required": ["scope", "query"]},
+    ("POST", "/v1/forget"): {
+        "purpose": "delete with audit",
+        "required": ["scope"],
+        "notes": "A selector with confirm_all=true is refused: confirm_all "
+                 "authorizes a SCOPE-WIDE erase, a selector narrows it. Pick one.",
+    },
+    ("POST", "/v1/forget/preview"): {"purpose": "dry-run a forget", "required": ["scope"]},
+    ("GET", "/v1/events"): {"purpose": "list raw events", "required": []},
+    ("POST", "/v1/auth/signup"): {"purpose": "anonymous free-tier identity", "required": []},
+    ("GET", "/v1/auth/whoami"): {"purpose": "caller + capabilities", "required": []},
+    ("GET", "/v1/admin/health"): {"purpose": "liveness", "required": []},
+    ("GET", "/v1/admin/ready"): {"purpose": "readiness + capability canaries", "required": []},
+}
+
+#: Paths agents reach for that do not exist, and what they meant.
+PATH_ALIASES = {
+    "/v1/memories": "/v1/experience",
+    "/v1/memory": "/v1/experience",
+    "/v1/remember": "/v1/experience",
+    "/v1/store": "/v1/experience",
+    "/v1/add": "/v1/experience",
+    "/v1/search": "/v1/recall",
+    "/v1/query": "/v1/recall",
+    "/v1/retrieve": "/v1/recall",
+    "/v1/ask": "/v1/answer",
+    "/v1/delete": "/v1/forget",
+    "/v1/health": "/v1/admin/health",
+    "/memories": "/v1/experience",
+    "/recall": "/v1/recall",
+}
+
+#: SDK methods, mirroring the guidance the SDKs themselves now raise.
+SDK_METHODS = {
+    "experience", "experience_bulk", "recall", "answer", "compose", "forget",
+    "forget_preview", "events", "episodes", "facts", "beliefs", "whoami",
+    "signup", "upload_blob", "erase", "erasure_preview",
+}
+SDK_ALIASES = {
+    "remember": "experience", "store": "experience", "add": "experience",
+    "add_memory": "experience", "write": "experience", "save": "experience",
+    "retrieve": "recall", "search": "recall", "query": "recall",
+    "get_memories": "recall", "ask": "answer", "chat": "answer",
+    "delete": "forget", "remove": "forget", "delete_memory": "forget",
+    "bulk": "experience_bulk", "upload": "upload_blob", "me": "whoami",
+}
+
+
+@dataclass
+class Verdict:
+    valid: bool
+    call: str
+    problems: list[str] = field(default_factory=list)
+    correction: str | None = None
+    notes: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema": "cortexdb.check_call/v1",
+            "valid": self.valid,
+            "call": self.call,
+            "problems": self.problems,
+            "correction": self.correction,
+            "notes": self.notes,
+            "docs": DOCS,
+            "manifest": MANIFEST,
+        }
+
+
+def _check_scope(scope: str) -> list[str]:
+    """Scope grammar: colon-delimited key:value segments joined by '/'.
+
+    The single most common integration bug, and silent in both directions -
+    a bad scope writes where nobody reads and recalls nothing.
+    """
+    problems = []
+    if not scope:
+        return ["scope is empty"]
+    for i, segment in enumerate(scope.split("/"), 1):
+        if not segment:
+            problems.append(f"scope segment {i} is empty (double slash?)")
+        elif ":" not in segment:
+            problems.append(
+                f"scope segment {i} ({segment!r}) has no ':' delimiter - "
+                f"segments are key:value, e.g. 'user:{segment}'. "
+                f"The server rejects this with 422 INVALID_BODY."
+            )
+    return problems
+
+
+def check_http(method: str, path: str, body: dict[str, Any] | None = None) -> Verdict:
+    """Validate an HTTP call against the v1 surface."""
+    method = (method or "").strip().upper()
+    path = (path or "").strip()
+    if "?" in path:
+        path = path.split("?", 1)[0]
+    path = "/" + path.strip("/") if path else ""
+    call = f"{method} {path}"
+    body = body or {}
+
+    if (method, path) not in ROUTES:
+        alias = PATH_ALIASES.get(path)
+        if alias:
+            spec = ROUTES.get(("POST", alias)) or ROUTES.get(("GET", alias)) or {}
+            correct_method = "POST" if ("POST", alias) in ROUTES else "GET"
+            return Verdict(
+                valid=False,
+                call=call,
+                problems=[f"{path} does not exist."],
+                correction=f"{correct_method} {alias}  ({spec.get('purpose', '')})",
+                notes=[n for n in [spec.get("notes")] if n],
+            )
+        known = sorted({p for _, p in ROUTES})
+        close = difflib.get_close_matches(path, known, n=3, cutoff=0.5)
+        problems = [f"{path} is not a documented v1 route."]
+        correction = None
+        if close:
+            correction = "  ".join(close)
+        # A known path with the wrong verb is a distinct, commoner mistake.
+        for m, p in ROUTES:
+            if p == path and m != method:
+                problems = [f"{path} exists but not for {method}."]
+                correction = f"{m} {path}"
+                close = []
+                break
+        return Verdict(valid=False, call=call, problems=problems, correction=correction,
+                       notes=[] if close or correction else [f"See {MANIFEST} for the full surface."])
+
+    spec = ROUTES[(method, path)]
+    problems: list[str] = []
+    for required in spec.get("required", []):
+        if required not in body:
+            problems.append(f"missing required field: {required!r}")
+    if "scope" in body and isinstance(body["scope"], str):
+        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)]
+        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."
+            )
+    notes = [n for n in [spec.get("notes")] if n]
+    return Verdict(valid=not problems, call=call, problems=problems, notes=notes)
+
+
+def check_sdk(snippet: str) -> Verdict:
+    """Validate an SDK call written as `client.method(...)`."""
+    snippet = (snippet or "").strip()
+    match = re.search(r"\.\s*([A-Za-z_][A-Za-z0-9_]*)\s*\(", snippet)
+    if not match:
+        return Verdict(
+            valid=False, call=snippet,
+            problems=["could not find a method call of the form client.method(...)"],
+            correction=None,
+        )
+    name = match.group(1)
+    if name in SDK_METHODS:
+        return Verdict(valid=True, call=f".{name}()")
+    alias = SDK_ALIASES.get(name)
+    if alias:
+        return Verdict(
+            valid=False, call=f".{name}()",
+            problems=[f".{name}() does not exist."],
+            correction=f".{alias}()  - CortexDB calls that operation {alias!r}.",
+        )
+    close = difflib.get_close_matches(name, sorted(SDK_METHODS), n=3, cutoff=0.6)
+    return Verdict(
+        valid=False, call=f".{name}()",
+        problems=[f".{name}() does not exist."],
+        correction="  ".join(f".{c}()" for c in close) if close else None,
+        notes=[] if close else [f"Available: {', '.join(sorted(SDK_METHODS))}"],
+    )
+
+
+def check(call: str, body: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Entry point: accepts either an HTTP call or an SDK snippet."""
+    text = (call or "").strip()
+    if not text:
+        return Verdict(valid=False, call="", problems=["nothing to check"]).to_dict()
+
+    http = re.match(r"^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(\S+)", text, re.I)
+    if http:
+        return check_http(http.group(1), http.group(2), body).to_dict()
+    if text.startswith("/"):
+        # A bare path is almost always meant as a request; guess POST rather
+        # than refusing, and the verb correction covers a wrong guess.
+        return check_http("POST", text, body).to_dict()
+    return check_sdk(text).to_dict()