mtrx-cli 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrx-cli",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "MATRX CLI for routing Codex and Claude through Matrx",
   "homepage": "https://mtrx.so",
   "repository": {
@@ -24,6 +24,8 @@
     "bin/mtrx.js",
     "src/matrx/__init__.py",
     "src/matrx/cli/__init__.py",
+    "src/matrx/cli/cursor_config.py",
+    "src/matrx/cli/cursor_proxy.py",
     "src/matrx/cli/launcher.py",
     "src/matrx/cli/main.py",
     "src/matrx/cli/state.py"

package/src/matrx/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.8"
+__version__ = "0.1.10"

package/src/matrx/cli/cursor_config.py

@@ -0,0 +1,331 @@
+"""
+Read / write Cursor IDE settings stored in the SQLite ``state.vscdb`` database.
+
+Cursor stores its model-related settings (custom API keys, base URL overrides)
+in ``~/Library/Application Support/Cursor/User/globalStorage/state.vscdb``
+(macOS) inside an ``ItemTable`` key-value store.
+
+This module provides helpers to:
+  - locate the database on each platform
+  - discover which keys Cursor uses for the OpenAI API key / base URL override
+  - read, write, backup, and restore those settings
+  - print manual setup instructions as a fallback
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import platform
+import sqlite3
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Known key patterns that Cursor uses (or has used) for BYOK settings.
+# These are discovered empirically; Cursor may change them across versions.
+_CANDIDATE_SETTINGS_KEYS = [
+    "storage.ServiceStorage",
+    "cursorai/cachedSettings",
+    "cursorai/modelSettings",
+]
+
+_OPENAI_KEY_FIELD = "openaiApiKey"
+_OPENAI_BASE_URL_FIELD = "openaiBaseUrl"
+_OVERRIDE_OPENAI_BASE_URL_FIELD = "enableOpenaiBaseUrlOverride"
+_ANTHROPIC_KEY_FIELD = "anthropicApiKey"
+
+
+def cursor_state_db_path() -> Path:
+    """Return the platform-specific path to Cursor's ``state.vscdb``."""
+    system = platform.system()
+    if system == "Darwin":
+        return (
+            Path.home()
+            / "Library"
+            / "Application Support"
+            / "Cursor"
+            / "User"
+            / "globalStorage"
+            / "state.vscdb"
+        )
+    if system == "Linux":
+        return (
+            Path.home()
+            / ".config"
+            / "Cursor"
+            / "User"
+            / "globalStorage"
+            / "state.vscdb"
+        )
+    # Windows
+    appdata = os.environ.get("APPDATA", "")
+    if appdata:
+        return Path(appdata) / "Cursor" / "User" / "globalStorage" / "state.vscdb"
+    return Path.home() / "AppData" / "Roaming" / "Cursor" / "User" / "globalStorage" / "state.vscdb"
+
+
+def cursor_is_running() -> bool:
+    """Best-effort check for whether a Cursor process is active."""
+    system = platform.system()
+    if system == "Darwin":
+        import subprocess
+        try:
+            result = subprocess.run(
+                ["pgrep", "-f", "Cursor"],
+                capture_output=True,
+                timeout=3,
+            )
+            return result.returncode == 0
+        except Exception:
+            return False
+    if system == "Linux":
+        import subprocess
+        try:
+            result = subprocess.run(
+                ["pgrep", "-f", "[Cc]ursor"],
+                capture_output=True,
+                timeout=3,
+            )
+            return result.returncode == 0
+        except Exception:
+            return False
+    return False
+
+
+def _open_db(db_path: Path) -> sqlite3.Connection | None:
+    if not db_path.exists():
+        return None
+    try:
+        conn = sqlite3.connect(str(db_path), timeout=5)
+        return conn
+    except sqlite3.Error as exc:
+        logger.debug("cursor_config: cannot open %s: %s", db_path, exc)
+        return None
+
+
+def _find_settings_key(conn: sqlite3.Connection) -> str | None:
+    """Discover which ItemTable key holds the model/BYOK settings blob."""
+    cursor = conn.cursor()
+    for candidate in _CANDIDATE_SETTINGS_KEYS:
+        cursor.execute(
+            "SELECT value FROM ItemTable WHERE key = ?", (candidate,)
+        )
+        row = cursor.fetchone()
+        if row is None:
+            continue
+        try:
+            data = json.loads(row[0]) if isinstance(row[0], str) else row[0]
+        except (json.JSONDecodeError, TypeError):
+            continue
+        if isinstance(data, dict) and (
+            _OPENAI_KEY_FIELD in data
+            or _OPENAI_BASE_URL_FIELD in data
+            or _OVERRIDE_OPENAI_BASE_URL_FIELD in data
+        ):
+            return candidate
+    return None
+
+
+def _scan_for_settings_key(conn: sqlite3.Connection) -> str | None:
+    """Fallback: scan all keys looking for any JSON blob with openai fields."""
+    cursor = conn.cursor()
+    cursor.execute("SELECT key, value FROM ItemTable")
+    for key, value in cursor.fetchall():
+        if not isinstance(value, str):
+            continue
+        try:
+            data = json.loads(value)
+        except (json.JSONDecodeError, TypeError):
+            continue
+        if isinstance(data, dict) and (
+            _OPENAI_KEY_FIELD in data
+            or _OPENAI_BASE_URL_FIELD in data
+            or _OVERRIDE_OPENAI_BASE_URL_FIELD in data
+            or _ANTHROPIC_KEY_FIELD in data
+        ):
+            return key
+    return None
+
+
+def read_cursor_settings(db_path: Path | None = None) -> dict | None:
+    """
+    Read Cursor's current BYOK/model settings.
+
+    Returns the parsed JSON blob, or None if the DB cannot be read or the
+    settings key is not found.
+    """
+    db_path = db_path or cursor_state_db_path()
+    conn = _open_db(db_path)
+    if conn is None:
+        return None
+    try:
+        settings_key = _find_settings_key(conn) or _scan_for_settings_key(conn)
+        if not settings_key:
+            return None
+        cursor = conn.cursor()
+        cursor.execute(
+            "SELECT value FROM ItemTable WHERE key = ?", (settings_key,)
+        )
+        row = cursor.fetchone()
+        if row is None:
+            return None
+        data = json.loads(row[0]) if isinstance(row[0], str) else {}
+        data["_mtrx_settings_key"] = settings_key
+        return data
+    except (sqlite3.Error, json.JSONDecodeError) as exc:
+        logger.debug("cursor_config: read error: %s", exc)
+        return None
+    finally:
+        conn.close()
+
+
+def write_cursor_settings(
+    db_path: Path,
+    settings_key: str,
+    data: dict,
+) -> bool:
+    """Write the settings blob back to Cursor's state.vscdb."""
+    clean = {k: v for k, v in data.items() if not k.startswith("_mtrx_")}
+    conn = _open_db(db_path)
+    if conn is None:
+        return False
+    try:
+        cursor = conn.cursor()
+        cursor.execute(
+            "INSERT OR REPLACE INTO ItemTable (key, value) VALUES (?, ?)",
+            (settings_key, json.dumps(clean)),
+        )
+        conn.commit()
+        return True
+    except sqlite3.Error as exc:
+        logger.debug("cursor_config: write error: %s", exc)
+        return False
+    finally:
+        conn.close()
+
+
+def configure_cursor_for_proxy(
+    proxy_url: str,
+    proxy_api_key: str = "mtrx-cursor-proxy",
+    *,
+    db_path: Path | None = None,
+) -> dict | None:
+    """
+    Configure Cursor to route through the local MTRX proxy.
+
+    Sets the OpenAI API key and Override Base URL in state.vscdb.
+    Returns the previous settings dict (for later restoration), or None on failure.
+    """
+    db_path = db_path or cursor_state_db_path()
+    current = read_cursor_settings(db_path)
+
+    if current is None:
+        # Settings key not found — may need user to set a dummy key via UI first.
+        # Try to insert a fresh settings blob under the first candidate key.
+        conn = _open_db(db_path)
+        if conn is None:
+            return None
+        try:
+            settings_key = _CANDIDATE_SETTINGS_KEYS[0]
+            fresh: dict = {
+                _OPENAI_KEY_FIELD: proxy_api_key,
+                _OPENAI_BASE_URL_FIELD: proxy_url,
+                _OVERRIDE_OPENAI_BASE_URL_FIELD: True,
+            }
+            cursor = conn.cursor()
+            cursor.execute(
+                "INSERT OR REPLACE INTO ItemTable (key, value) VALUES (?, ?)",
+                (settings_key, json.dumps(fresh)),
+            )
+            conn.commit()
+            return {"_mtrx_settings_key": settings_key, "_mtrx_was_absent": True}
+        except sqlite3.Error as exc:
+            logger.debug("cursor_config: fresh insert error: %s", exc)
+            return None
+        finally:
+            conn.close()
+
+    settings_key = current.pop("_mtrx_settings_key", _CANDIDATE_SETTINGS_KEYS[0])
+    previous = {
+        _OPENAI_KEY_FIELD: current.get(_OPENAI_KEY_FIELD),
+        _OPENAI_BASE_URL_FIELD: current.get(_OPENAI_BASE_URL_FIELD),
+        _OVERRIDE_OPENAI_BASE_URL_FIELD: current.get(_OVERRIDE_OPENAI_BASE_URL_FIELD),
+        _ANTHROPIC_KEY_FIELD: current.get(_ANTHROPIC_KEY_FIELD),
+        "_mtrx_settings_key": settings_key,
+    }
+
+    current[_OPENAI_KEY_FIELD] = proxy_api_key
+    current[_OPENAI_BASE_URL_FIELD] = proxy_url
+    current[_OVERRIDE_OPENAI_BASE_URL_FIELD] = True
+
+    if write_cursor_settings(db_path, settings_key, current):
+        return previous
+    return None
+
+
+def restore_cursor_settings(
+    previous: dict,
+    *,
+    db_path: Path | None = None,
+) -> bool:
+    """Restore Cursor settings to their pre-proxy state."""
+    db_path = db_path or cursor_state_db_path()
+    settings_key = previous.get("_mtrx_settings_key", "")
+
+    if previous.get("_mtrx_was_absent"):
+        conn = _open_db(db_path)
+        if conn is None:
+            return False
+        try:
+            cursor = conn.cursor()
+            cursor.execute(
+                "DELETE FROM ItemTable WHERE key = ?", (settings_key,)
+            )
+            conn.commit()
+            return True
+        except sqlite3.Error:
+            return False
+        finally:
+            conn.close()
+
+    if not settings_key:
+        return False
+
+    current = read_cursor_settings(db_path)
+    if current is None:
+        return False
+
+    current.pop("_mtrx_settings_key", None)
+
+    for field in (
+        _OPENAI_KEY_FIELD,
+        _OPENAI_BASE_URL_FIELD,
+        _OVERRIDE_OPENAI_BASE_URL_FIELD,
+        _ANTHROPIC_KEY_FIELD,
+    ):
+        old_value = previous.get(field)
+        if old_value is None:
+            current.pop(field, None)
+        else:
+            current[field] = old_value
+
+    return write_cursor_settings(db_path, settings_key, current)
+
+
+def print_manual_setup_instructions(proxy_url: str) -> None:
+    """Print step-by-step instructions for the user to configure Cursor manually."""
+    print()
+    print("  Could not auto-configure Cursor settings.")
+    print("  Please configure manually in Cursor:")
+    print()
+    print("  1. Open Cursor Settings (Cmd+, or Ctrl+,)")
+    print("  2. Go to Models")
+    print("  3. In the OpenAI API Keys section:")
+    print(f"     - API Key:           mtrx-cursor-proxy")
+    print(f"     - Override Base URL:  {proxy_url}")
+    print("     - Toggle ON 'Override OpenAI Base URL'")
+    print()
+    print("  All models (Claude, GPT, Gemini, etc.) will route through MTRX.")
+    print()

package/src/matrx/cli/cursor_proxy.py

@@ -0,0 +1,351 @@
+"""
+Local HTTP proxy server for routing Cursor IDE requests through MTRX.
+
+Sits between Cursor and the MTRX API, injecting X-Matrx-* headers on every
+request so that Cursor gets the same full-featured proxy pipeline as
+``mtrx claude`` and ``mtrx codex`` (injection, compression, memory, groups,
+observability).
+
+Cursor's "Override OpenAI Base URL" sends ALL model requests (OpenAI,
+Anthropic, Google, etc.) in OpenAI Chat Completions format to the configured
+URL.  The MTRX router auto-detects the provider from the model name.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+import platform
+import os
+import shutil
+import signal
+import socket
+import threading
+import uuid
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+_PROXY_API_KEY = "mtrx-cursor-proxy"
+_FORWARDED_METHODS = {"POST", "GET", "PUT", "PATCH", "DELETE", "OPTIONS"}
+
+
+def _capture_env_snapshot() -> dict:
+    out: dict = {
+        "os": platform.system(),
+        "shell": os.environ.get("SHELL", os.environ.get("COMSPEC", "")),
+        "cwd": os.getcwd(),
+    }
+    out["venv"] = os.environ.get("VIRTUAL_ENV", "") or None
+    node = shutil.which("node")
+    if node:
+        import subprocess as _sp
+        try:
+            r = _sp.run([node, "-v"], capture_output=True, text=True, timeout=2)
+            out["node"] = r.stdout.strip() if r.returncode == 0 else None
+        except Exception:
+            out["node"] = None
+    else:
+        out["node"] = None
+    return out
+
+
+class CursorProxyServer:
+    """Async HTTP proxy that injects MTRX headers and forwards to the MTRX API."""
+
+    def __init__(
+        self,
+        *,
+        matrx_key: str,
+        matrx_base_url: str,
+        session_id: str | None = None,
+        group_id: str = "",
+        project_id: str = "",
+        host: str = "127.0.0.1",
+        port: int = 0,
+    ):
+        self.matrx_key = matrx_key
+        self.matrx_base_url = matrx_base_url.rstrip("/")
+        self.session_id = session_id or str(uuid.uuid4())
+        self.group_id = group_id
+        self.project_id = project_id
+        self.host = host
+        self.port = port
+
+        env_snap = _capture_env_snapshot()
+        self._env_b64 = (
+            base64.b64encode(json.dumps(env_snap).encode()).decode()
+            if env_snap
+            else ""
+        )
+        self._server: asyncio.Server | None = None
+        self._http_client: httpx.AsyncClient | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+    @property
+    def url(self) -> str:
+        return f"http://{self.host}:{self.port}/v1"
+
+    def _build_matrx_headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {
+            "X-Matrx-Key": self.matrx_key,
+            "X-Matrx-Agent-Id": "cursor",
+            "X-Matrx-Provider": "cursor",
+            "X-Matrx-Session-Id": self.session_id,
+        }
+        if self.group_id:
+            headers["X-Matrx-Group"] = self.group_id
+        if self.project_id:
+            headers["X-Matrx-Project-Id"] = self.project_id
+        if self._env_b64:
+            headers["X-Matrx-Env"] = self._env_b64
+        return headers
+
+    async def _handle_request(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+    ) -> None:
+        try:
+            await self._process_http(reader, writer)
+        except Exception:
+            logger.debug("cursor_proxy: connection error", exc_info=True)
+        finally:
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    async def _process_http(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+    ) -> None:
+        request_line = await reader.readline()
+        if not request_line:
+            return
+        parts = request_line.decode("utf-8", errors="replace").strip().split(" ", 2)
+        if len(parts) < 3:
+            return
+        method, raw_path, _ = parts
+
+        headers_raw: dict[str, str] = {}
+        while True:
+            line = await reader.readline()
+            decoded = line.decode("utf-8", errors="replace").strip()
+            if not decoded:
+                break
+            if ":" in decoded:
+                key, _, value = decoded.partition(":")
+                headers_raw[key.strip().lower()] = value.strip()
+
+        content_length = int(headers_raw.get("content-length", "0"))
+        body = b""
+        if content_length > 0:
+            body = await reader.readexactly(content_length)
+
+        if method not in _FORWARDED_METHODS:
+            self._send_response(writer, 405, {"error": "Method not allowed"})
+            return
+
+        upstream_path = raw_path
+        if upstream_path.startswith("/v1/"):
+            upstream_path = "/" + upstream_path[4:]
+        elif upstream_path == "/v1":
+            upstream_path = "/"
+
+        upstream_url = f"{self.matrx_base_url}/v1{upstream_path}"
+
+        upstream_headers: dict[str, str] = {}
+        for key, value in headers_raw.items():
+            if key in {"host", "connection", "transfer-encoding"}:
+                continue
+            if key == "authorization":
+                continue
+            upstream_headers[key] = value
+
+        upstream_headers.update(self._build_matrx_headers())
+        upstream_headers["Authorization"] = f"Bearer {self.matrx_key}"
+
+        is_stream = False
+        if body and method == "POST":
+            try:
+                parsed = json.loads(body)
+                is_stream = parsed.get("stream", False)
+            except (json.JSONDecodeError, AttributeError):
+                pass
+
+        assert self._http_client is not None
+
+        if is_stream:
+            await self._proxy_streaming(
+                writer, method, upstream_url, upstream_headers, body
+            )
+        else:
+            await self._proxy_buffered(
+                writer, method, upstream_url, upstream_headers, body
+            )
+
+    async def _proxy_buffered(
+        self,
+        writer: asyncio.StreamWriter,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        body: bytes,
+    ) -> None:
+        assert self._http_client is not None
+        try:
+            resp = await self._http_client.request(
+                method, url, headers=headers, content=body, timeout=120
+            )
+            resp_headers = {
+                "Content-Type": resp.headers.get("content-type", "application/json"),
+                "Content-Length": str(len(resp.content)),
+            }
+            for h in ("x-matrx-request-id", "x-matrx-latency-ms", "x-matrx-tokens-saved"):
+                if h in resp.headers:
+                    resp_headers[h] = resp.headers[h]
+            self._send_raw_response(writer, resp.status_code, resp_headers, resp.content)
+        except httpx.HTTPError as exc:
+            logger.warning("cursor_proxy: upstream error: %s", exc)
+            self._send_response(writer, 502, {"error": f"Upstream error: {exc}"})
+
+    async def _proxy_streaming(
+        self,
+        writer: asyncio.StreamWriter,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        body: bytes,
+    ) -> None:
+        assert self._http_client is not None
+        try:
+            async with self._http_client.stream(
+                method, url, headers=headers, content=body, timeout=300
+            ) as resp:
+                resp_headers = {
+                    "Content-Type": resp.headers.get(
+                        "content-type", "text/event-stream"
+                    ),
+                    "Cache-Control": "no-cache",
+                    "Transfer-Encoding": "chunked",
+                }
+                for h in ("x-matrx-request-id", "x-matrx-latency-ms", "x-matrx-tokens-saved"):
+                    if h in resp.headers:
+                        resp_headers[h] = resp.headers[h]
+
+                header_block = f"HTTP/1.1 {resp.status_code} OK\r\n"
+                for k, v in resp_headers.items():
+                    header_block += f"{k}: {v}\r\n"
+                header_block += "\r\n"
+                writer.write(header_block.encode("utf-8"))
+                await writer.drain()
+
+                async for chunk in resp.aiter_bytes():
+                    chunk_header = f"{len(chunk):x}\r\n".encode("utf-8")
+                    writer.write(chunk_header + chunk + b"\r\n")
+                    await writer.drain()
+
+                writer.write(b"0\r\n\r\n")
+                await writer.drain()
+        except httpx.HTTPError as exc:
+            logger.warning("cursor_proxy: streaming error: %s", exc)
+            self._send_response(writer, 502, {"error": f"Upstream error: {exc}"})
+
+    @staticmethod
+    def _send_response(
+        writer: asyncio.StreamWriter,
+        status: int,
+        body: dict[str, Any],
+    ) -> None:
+        content = json.dumps(body).encode("utf-8")
+        CursorProxyServer._send_raw_response(
+            writer,
+            status,
+            {"Content-Type": "application/json", "Content-Length": str(len(content))},
+            content,
+        )
+
+    @staticmethod
+    def _send_raw_response(
+        writer: asyncio.StreamWriter,
+        status: int,
+        headers: dict[str, str],
+        content: bytes,
+    ) -> None:
+        reason = "OK" if 200 <= status < 300 else "Error"
+        header_block = f"HTTP/1.1 {status} {reason}\r\n"
+        for k, v in headers.items():
+            header_block += f"{k}: {v}\r\n"
+        header_block += "\r\n"
+        writer.write(header_block.encode("utf-8") + content)
+
+    def _pick_port(self) -> int:
+        if self.port:
+            return self.port
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("127.0.0.1", 0))
+            return s.getsockname()[1]
+
+    async def _run(self) -> None:
+        self.port = self._pick_port()
+        self._http_client = httpx.AsyncClient(http2=False, follow_redirects=True)
+        self._server = await asyncio.start_server(
+            self._handle_request, self.host, self.port
+        )
+        logger.info("cursor_proxy: listening on %s:%s", self.host, self.port)
+        async with self._server:
+            await self._server.serve_forever()
+
+    async def _shutdown(self) -> None:
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()
+        if self._http_client:
+            await self._http_client.aclose()
+
+    def start_background(self) -> None:
+        """Start the proxy in a background daemon thread. Returns once listening."""
+        ready = threading.Event()
+
+        def _run_loop() -> None:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            self._loop = loop
+
+            async def _start_and_signal() -> None:
+                self.port = self._pick_port()
+                self._http_client = httpx.AsyncClient(
+                    http2=False, follow_redirects=True
+                )
+                self._server = await asyncio.start_server(
+                    self._handle_request, self.host, self.port
+                )
+                ready.set()
+                async with self._server:
+                    await self._server.serve_forever()
+
+            try:
+                loop.run_until_complete(_start_and_signal())
+            except asyncio.CancelledError:
+                pass
+            finally:
+                loop.run_until_complete(self._shutdown())
+                loop.close()
+
+        thread = threading.Thread(target=_run_loop, daemon=True)
+        thread.start()
+        ready.wait(timeout=10)
+        if not ready.is_set():
+            raise RuntimeError("Cursor proxy failed to start within 10 seconds")
+
+    def stop(self) -> None:
+        """Stop the background proxy."""
+        if self._server and self._loop and self._loop.is_running():
+            self._loop.call_soon_threadsafe(self._server.close)