cortexdb-mcp 0.3.0__tar.gz → 0.3.1__tar.gz

{cortexdb_mcp-0.3.0 → cortexdb_mcp-0.3.1}/.gitignore

@@ -69,3 +69,11 @@ dist/
 # Scratch/debug text files at root
 /*.txt
 /*.log
+
+# Local debug / marketing / private content (not for repo)
+harness/.reports/
+harness_data_*/
+blog/
+sales/
+videos/
+local-instance/

{cortexdb_mcp-0.3.0 → cortexdb_mcp-0.3.1}/Dockerfile

@@ -7,6 +7,6 @@ COPY cortexdb_mcp/ cortexdb_mcp/
 
 RUN pip install --no-cache-dir .
 
-ENV CORTEXDB_URL=https://api.cortexdb.ai
+ENV CORTEXDB_URL=https://api-v1.cortexdb.ai
 
 CMD ["cortexdb-mcp"]

{cortexdb_mcp-0.3.0 → cortexdb_mcp-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdb-mcp
-Version: 0.3.0
+Version: 0.3.1
 Summary: MCP Server for CortexDB — expose memory operations to AI agents
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -56,6 +56,28 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
 }
 ```
 
+> **Windows note (audit POL-3):** if Claude Desktop / Cursor / Windsurf
+> can't find `cortexdb-mcp` on PATH, give it the full path to the
+> installed executable:
+>
+> ```json
+> {
+>   "mcpServers": {
+>     "cortexdb": {
+>       "command": "C:\\Python313\\Scripts\\cortexdb-mcp.exe"
+>     }
+>   }
+> }
+> ```
+>
+> Locate it with `where cortexdb-mcp` in `cmd.exe` or
+> `(Get-Command cortexdb-mcp).Source` in PowerShell.
+>
+> Some Windows terminals don't have UTF-8 enabled by default, which can
+> garble emoji in `--help` output (they show as `?`). The server itself
+> isn't affected — only the CLI banner. Run
+> `chcp 65001` once per terminal session to fix.
+
 ### Claude Code (CLI)
 
 Edit `~/.claude/mcp.json`:
@@ -200,7 +222,7 @@ Pre-built prompt templates:
 
 | Environment Variable | Default | Description |
 |---|---|---|
-| `CORTEXDB_URL` | `https://api.cortexdb.ai` | CortexDB server URL |
+| `CORTEXDB_URL` | `https://api-v1.cortexdb.ai` | CortexDB server URL |
 | `CORTEXDB_API_KEY` | (none) | API key for authentication |
 | `CORTEXDB_TIMEOUT` | `30.0` | HTTP request timeout (seconds) |
 

{cortexdb_mcp-0.3.0 → cortexdb_mcp-0.3.1}/README.md

@@ -43,6 +43,28 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
 }
 ```
 
+> **Windows note (audit POL-3):** if Claude Desktop / Cursor / Windsurf
+> can't find `cortexdb-mcp` on PATH, give it the full path to the
+> installed executable:
+>
+> ```json
+> {
+>   "mcpServers": {
+>     "cortexdb": {
+>       "command": "C:\\Python313\\Scripts\\cortexdb-mcp.exe"
+>     }
+>   }
+> }
+> ```
+>
+> Locate it with `where cortexdb-mcp` in `cmd.exe` or
+> `(Get-Command cortexdb-mcp).Source` in PowerShell.
+>
+> Some Windows terminals don't have UTF-8 enabled by default, which can
+> garble emoji in `--help` output (they show as `?`). The server itself
+> isn't affected — only the CLI banner. Run
+> `chcp 65001` once per terminal session to fix.
+
 ### Claude Code (CLI)
 
 Edit `~/.claude/mcp.json`:
@@ -187,7 +209,7 @@ Pre-built prompt templates:
 
 | Environment Variable | Default | Description |
 |---|---|---|
-| `CORTEXDB_URL` | `https://api.cortexdb.ai` | CortexDB server URL |
+| `CORTEXDB_URL` | `https://api-v1.cortexdb.ai` | CortexDB server URL |
 | `CORTEXDB_API_KEY` | (none) | API key for authentication |
 | `CORTEXDB_TIMEOUT` | `30.0` | HTTP request timeout (seconds) |
 

{cortexdb_mcp-0.3.0 → cortexdb_mcp-0.3.1}/cortexdb_mcp/__init__.py

@@ -1,3 +1,3 @@
 """CortexDB MCP Server -- expose CortexDB memory operations to AI agents via MCP."""
 
-__version__ = "0.2.1"
+__version__ = "0.3.1"

{cortexdb_mcp-0.3.0 → cortexdb_mcp-0.3.1}/cortexdb_mcp/api.py

@@ -6,7 +6,7 @@ display proactive insights.  Results are cached with a configurable TTL (default
 
 Configuration is read from environment variables:
 
-- ``CORTEXDB_URL``      -- CortexDB base URL (default ``https://api.cortexdb.ai``)
+- ``CORTEXDB_URL``      -- CortexDB base URL (default ``https://api-v1.cortexdb.ai``)
 - ``CORTEXDB_API_KEY``  -- Optional bearer token
 - ``CORTEXDB_TENANT_ID``-- Optional tenant scope
 - ``INSIGHTS_CACHE_TTL``-- Cache lifetime in seconds (default ``300``)
@@ -34,7 +34,7 @@ logger = logging.getLogger("cortexdb_mcp.api")
 # Configuration
 # ---------------------------------------------------------------------------
 
-CORTEXDB_URL = os.environ.get("CORTEXDB_URL", "https://api.cortexdb.ai")
+CORTEXDB_URL = os.environ.get("CORTEXDB_URL", "https://api-v1.cortexdb.ai")
 CORTEXDB_API_KEY = os.environ.get("CORTEXDB_API_KEY")
 CORTEXDB_TENANT_ID = os.environ.get("CORTEXDB_TENANT_ID")
 INSIGHTS_CACHE_TTL = int(os.environ.get("INSIGHTS_CACHE_TTL", "300"))

{cortexdb_mcp-0.3.0 → cortexdb_mcp-0.3.1}/cortexdb_mcp/config.py

@@ -1,145 +1,145 @@
-"""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, caching the resulting
-   PASETO token (+ actor + scope) under ``~/.config/cortexdb-mcp/state.json``.
-   Re-launches reuse the cached token until it expires.
-
-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. **Legacy v0 key** — set ``CORTEXDB_API_KEY=cx_live_...`` and point
-   ``CORTEXDB_URL`` at the legacy v0 surface (``https://api.cortexdb.ai``).
-   Several MCP tools won't work in this mode because v0 lacks the
-   layer-read endpoints.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-from dataclasses import dataclass, field
-from pathlib import Path
-
-
-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.
-        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
-    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_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"),
-            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)
-            if cached:
-                cfg.api_key = cfg.api_key or cached.get("token")
-                cfg.actor = cfg.actor or cached.get("actor")
-                cfg.scope = cfg.scope or cached.get("scope")
-        return cfg
-
-    def save_state(self, token: str, actor: str, scope: str) -> 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},
-                    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 _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
+"""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, caching the resulting
+   PASETO token (+ actor + scope) under ``~/.config/cortexdb-mcp/state.json``.
+   Re-launches reuse the cached token until it expires.
+
+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. **Legacy v0 key** — set ``CORTEXDB_API_KEY=cx_live_...`` and point
+   ``CORTEXDB_URL`` at the legacy v0 surface (``https://api-v1.cortexdb.ai``).
+   Several MCP tools won't work in this mode because v0 lacks the
+   layer-read endpoints.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+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.
+        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
+    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_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"),
+            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)
+            if cached:
+                cfg.api_key = cfg.api_key or cached.get("token")
+                cfg.actor = cfg.actor or cached.get("actor")
+                cfg.scope = cfg.scope or cached.get("scope")
+        return cfg
+
+    def save_state(self, token: str, actor: str, scope: str) -> 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},
+                    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 _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.3.0 → cortexdb_mcp-0.3.1}/cortexdb_mcp/insights.py

@@ -131,7 +131,7 @@ class InsightsEngine:
 
     def __init__(
         self,
-        cortex_url: str = "https://api.cortexdb.ai",
+        cortex_url: str = "https://api-v1.cortexdb.ai",
         api_key: str | None = None,
         tenant_id: str | None = None,
     ) -> None: