mcpstate 0.1.0__py3-none-any.whl

mcpstate/__init__.py

@@ -0,0 +1,42 @@
+"""mcpstate — durable, user-keyed state for stateless MCP servers.
+
+State that follows the user, not the session.
+"""
+from .errors import (
+    BackendError,
+    HandleExpired,
+    HandleNotFound,
+    McpStateError,
+    PatchError,
+    StaleWrite,
+    StateTooLarge,
+    Unauthenticated,
+    InternalError,
+)
+from .ops import Append, DelKey, Merge, PatchOp, SetKey, apply_ops, op_from_dict
+from .store import HandleInfo, HandleStore, Snapshot
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "HandleStore",
+    "Snapshot",
+    "HandleInfo",
+    "McpStateError",
+    "HandleNotFound",
+    "HandleExpired",
+    "StaleWrite",
+    "PatchError",
+    "StateTooLarge",
+    "Unauthenticated",
+    "InternalError",
+    "BackendError",
+    "Append",
+    "SetKey",
+    "DelKey",
+    "Merge",
+    "PatchOp",
+    "apply_ops",
+    "op_from_dict",
+    "__version__",
+]

mcpstate/backends/__init__.py

@@ -0,0 +1,3 @@
+from .base import Backend, Record
+
+__all__ = ["Backend", "Record"]

mcpstate/backends/base.py

@@ -0,0 +1,42 @@
+"""Storage protocol. Six methods; implement them and any store works.
+
+Backends persist opaque records keyed by ``(user, handle)``. All conflict
+semantics live in the single primitive ``cas_put`` — an atomic write that
+succeeds only when the stored version still matches ``expected_version``.
+Expiry is not a backend concern; the store applies TTL logic on top.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass
+class Record:
+    kind: str
+    state: dict
+    version: int
+    created_at: float
+    updated_at: float
+    expires_at: float | None
+    last_writer: str | None
+
+
+class Backend(Protocol):
+    def get(self, user: str, handle: str) -> Record | None:
+        """Return the record, or None if absent."""
+
+    def put_new(self, user: str, handle: str, record: Record) -> bool:
+        """Create the record. False (and no write) if the handle already exists."""
+
+    def cas_put(self, user: str, handle: str, expected_version: int, record: Record) -> bool:
+        """Atomically replace the record iff its version equals expected_version."""
+
+    def delete(self, user: str, handle: str) -> bool:
+        """Remove the record. False if it was absent."""
+
+    def list(self, user: str) -> list[tuple[str, Record]]:
+        """All of the user's (handle, record) pairs, most recently updated first."""
+
+    def close(self) -> None:
+        """Release resources."""

mcpstate/backends/redis.py

@@ -0,0 +1,120 @@
+"""Redis backend — shared reach.
+
+Point multiple server instances (or the same server on several machines) at
+one Redis and state follows the user across all of them: this is the backend
+that turns hand-off into cross-device sync. CAS uses an optimistic
+WATCH/MULTI transaction so it works on any Redis-compatible server.
+
+The module never imports the ``redis`` package — behavior comes entirely from
+the injected client, so the core library stays dependency-free and tests can
+use fakeredis.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import quote
+
+from .base import Record
+
+_PREFIX = "mcpstate"
+
+
+def _q(part: str) -> str:
+    # Percent-encode so a user or handle containing ':' (an OAuth sub like
+    # "org:alice") cannot collide with the key layout.
+    return quote(part, safe="")
+
+
+# Records and indexes live under disjoint prefixes ("h" vs "i") so no username
+# — even the literal "index" — can ever land in the index keyspace.
+def _key(user: str, handle: str) -> str:
+    return f"{_PREFIX}:h:{_q(user)}:{_q(handle)}"
+
+
+def _index(user: str) -> str:
+    return f"{_PREFIX}:i:{_q(user)}"
+
+
+def _dump(record: Record) -> str:
+    return json.dumps(
+        {
+            "kind": record.kind,
+            "state": record.state,
+            "version": record.version,
+            "created_at": record.created_at,
+            "updated_at": record.updated_at,
+            "expires_at": record.expires_at,
+            "last_writer": record.last_writer,
+        }
+    )
+
+
+def _load(raw: bytes | str) -> Record:
+    d = json.loads(raw)
+    return Record(
+        kind=d["kind"],
+        state=d["state"],
+        version=d["version"],
+        created_at=d["created_at"],
+        updated_at=d["updated_at"],
+        expires_at=d["expires_at"],
+        last_writer=d["last_writer"],
+    )
+
+
+class RedisBackend:
+    def __init__(self, client: Any) -> None:
+        self._r = client
+
+    def get(self, user: str, handle: str) -> Record | None:
+        raw = self._r.get(_key(user, handle))
+        return _load(raw) if raw is not None else None
+
+    def put_new(self, user: str, handle: str, record: Record) -> bool:
+        created = bool(self._r.set(_key(user, handle), _dump(record), nx=True))
+        if created:
+            self._r.sadd(_index(user), handle)
+        return created
+
+    def cas_put(self, user: str, handle: str, expected_version: int, record: Record) -> bool:
+        key = _key(user, handle)
+        with self._r.pipeline() as pipe:
+            try:
+                pipe.watch(key)
+                raw = pipe.get(key)
+                if raw is None or _load(raw).version != expected_version:
+                    pipe.unwatch()
+                    return False
+                pipe.multi()
+                pipe.set(key, _dump(record))
+                pipe.execute()
+                return True
+            except Exception as exc:
+                # WatchError means a concurrent write landed first: the CAS loses.
+                # Caught by name so this module imports without the redis package.
+                if type(exc).__name__ == "WatchError":
+                    return False
+                raise
+
+    def delete(self, user: str, handle: str) -> bool:
+        removed = self._r.delete(_key(user, handle)) == 1
+        self._r.srem(_index(user), handle)
+        return removed
+
+    def list(self, user: str) -> list[tuple[str, Record]]:
+        handles = [
+            h.decode() if isinstance(h, bytes) else h for h in self._r.smembers(_index(user))
+        ]
+        out = []
+        for handle in handles:
+            raw = self._r.get(_key(user, handle))
+            if raw is not None:
+                out.append((handle, _load(raw)))
+        out.sort(key=lambda pair: pair[1].updated_at, reverse=True)
+        return out
+
+    def close(self) -> None:
+        close = getattr(self._r, "close", None)
+        if close:
+            close()

mcpstate/backends/sqlite.py

@@ -0,0 +1,130 @@
+"""SQLite backend — the zero-config default.
+
+Covers cross-conversation and cross-client continuity on one machine. The
+compare-and-swap is a single ``UPDATE ... WHERE version = ?`` statement, which
+SQLite executes atomically; a lock serializes connection access across threads.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from pathlib import Path
+
+from .base import Record
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS handles (
+  user TEXT NOT NULL,
+  handle TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  state TEXT NOT NULL,
+  version INTEGER NOT NULL,
+  created_at REAL NOT NULL,
+  updated_at REAL NOT NULL,
+  expires_at REAL,
+  last_writer TEXT,
+  PRIMARY KEY (user, handle)
+)
+"""
+
+
+class SQLiteBackend:
+    def __init__(self, path: str) -> None:
+        if path != ":memory:":
+            p = Path(path).expanduser()
+            p.parent.mkdir(parents=True, exist_ok=True)
+            path = str(p)
+        self._lock = threading.Lock()
+        # timeout doubles as the busy handler: a second process writing the same
+        # DB (the cross-client axis) waits up to 10s instead of erroring.
+        self._conn = sqlite3.connect(path, check_same_thread=False, timeout=10.0)
+        with self._lock:
+            self._conn.execute("PRAGMA journal_mode=WAL")
+            self._conn.execute(_SCHEMA)
+            self._conn.commit()
+
+    def _row_to_record(self, row: tuple) -> Record:
+        kind, state, version, created_at, updated_at, expires_at, last_writer = row
+        return Record(
+            kind=kind,
+            state=json.loads(state),
+            version=version,
+            created_at=created_at,
+            updated_at=updated_at,
+            expires_at=expires_at,
+            last_writer=last_writer,
+        )
+
+    def get(self, user: str, handle: str) -> Record | None:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT kind, state, version, created_at, updated_at, expires_at, last_writer "
+                "FROM handles WHERE user = ? AND handle = ?",
+                (user, handle),
+            ).fetchone()
+        return self._row_to_record(row) if row else None
+
+    def put_new(self, user: str, handle: str, record: Record) -> bool:
+        with self._lock:
+            cur = self._conn.execute(
+                "INSERT OR IGNORE INTO handles "
+                "(user, handle, kind, state, version, created_at, updated_at, expires_at, last_writer) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    user,
+                    handle,
+                    record.kind,
+                    json.dumps(record.state),
+                    record.version,
+                    record.created_at,
+                    record.updated_at,
+                    record.expires_at,
+                    record.last_writer,
+                ),
+            )
+            self._conn.commit()
+        return cur.rowcount == 1
+
+    def cas_put(self, user: str, handle: str, expected_version: int, record: Record) -> bool:
+        with self._lock:
+            cur = self._conn.execute(
+                "UPDATE handles SET kind = ?, state = ?, version = ?, created_at = ?, "
+                "updated_at = ?, expires_at = ?, last_writer = ? "
+                "WHERE user = ? AND handle = ? AND version = ?",
+                (
+                    record.kind,
+                    json.dumps(record.state),
+                    record.version,
+                    record.created_at,
+                    record.updated_at,
+                    record.expires_at,
+                    record.last_writer,
+                    user,
+                    handle,
+                    expected_version,
+                ),
+            )
+            self._conn.commit()
+        return cur.rowcount == 1
+
+    def delete(self, user: str, handle: str) -> bool:
+        with self._lock:
+            cur = self._conn.execute(
+                "DELETE FROM handles WHERE user = ? AND handle = ?", (user, handle)
+            )
+            self._conn.commit()
+        return cur.rowcount == 1
+
+    def list(self, user: str) -> list[tuple[str, Record]]:
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT handle, kind, state, version, created_at, updated_at, expires_at, last_writer "
+                "FROM handles WHERE user = ? ORDER BY updated_at DESC",
+                (user,),
+            ).fetchall()
+        return [(row[0], self._row_to_record(row[1:])) for row in rows]
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()

mcpstate/errors.py

@@ -0,0 +1,71 @@
+"""Structured, agent-legible errors.
+
+Every error renders to a JSON payload a model can read and act on: a stable
+``code``, a message written as an instruction, and the details needed to
+recover (for example, the current state inside a stale-write rejection).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class McpStateError(Exception):
+    """Base class for all runtime state errors."""
+
+    code = "mcpstate_error"
+
+    def __init__(self, message: str, **details: Any) -> None:
+        super().__init__(message)
+        self.details = details
+
+    def to_payload(self) -> dict[str, Any]:
+        """Render as a structured payload suitable for a tool result."""
+        return {"code": self.code, "message": str(self), **self.details}
+
+
+class HandleNotFound(McpStateError):
+    """The handle does not exist for this user (never minted, or revoked)."""
+
+    code = "handle_not_found"
+
+
+class HandleExpired(McpStateError):
+    """The handle existed but its TTL has elapsed."""
+
+    code = "handle_expired"
+
+
+class StaleWrite(McpStateError):
+    """A versioned save lost a race; details carry the current snapshot."""
+
+    code = "stale_write"
+
+
+class PatchError(McpStateError):
+    """A patch op could not be applied to the state's shape."""
+
+    code = "patch_error"
+
+
+class StateTooLarge(McpStateError):
+    """The state exceeds the store's configured size limit."""
+
+    code = "state_too_large"
+
+
+class Unauthenticated(McpStateError):
+    """No caller identity could be resolved on a transport that requires one."""
+
+    code = "unauthenticated"
+
+
+class InternalError(McpStateError):
+    """An unexpected failure; message is scrubbed of sensitive detail."""
+
+    code = "internal_error"
+
+
+class BackendError(McpStateError):
+    """The storage backend failed or is misconfigured."""
+
+    code = "backend_error"

mcpstate/fastmcp.py

@@ -0,0 +1,70 @@
+"""FastMCP integration helpers. Optional — the core library never imports FastMCP."""
+from __future__ import annotations
+
+import os
+
+from .errors import Unauthenticated
+from .store import HandleStore
+
+
+def store_from_env() -> HandleStore:
+    """Build a HandleStore from MCPSTATE_BACKEND (default: local SQLite)."""
+    return HandleStore.from_url(os.environ.get("MCPSTATE_BACKEND"))
+
+
+def current_writer() -> str:
+    """A label for who is writing, shown as last_writer in freshness metadata.
+
+    MCPSTATE_WRITER env (e.g. "laptop/claude-code") -> hostname fallback, so
+    cross-device hand-offs are attributable out of the box.
+    """
+    writer = os.environ.get("MCPSTATE_WRITER")
+    if writer:
+        return writer
+    import socket
+
+    return socket.gethostname()
+
+
+def _oauth_subject() -> str | None:
+    """The authenticated caller's identity, issuer-scoped, or None."""
+    try:
+        from fastmcp.server.dependencies import get_access_token
+
+        token = get_access_token()
+        if token is None:
+            return None
+        claims = getattr(token, "claims", None) or {}
+        sub = claims.get("sub")
+        if sub:
+            issuer = claims.get("iss")
+            # Scope by issuer: an OAuth `sub` is only unique within its issuer,
+            # so two IdPs can mint the same sub for different humans.
+            return f"{issuer}#{sub}" if issuer else str(sub)
+        client_id = getattr(token, "client_id", None)
+        if client_id:
+            return f"client:{client_id}"
+    except Exception:
+        return None
+    return None
+
+
+def current_user(require_auth: bool = False) -> str:
+    """Resolve the state-scoping user for the current request.
+
+    Order: OAuth subject (issuer-scoped, when the server runs with FastMCP
+    auth) -> MCPSTATE_USER env -> "local" (single-user stdio servers).
+
+    When ``require_auth`` is set (the server does this on the HTTP transport),
+    an unresolvable identity raises :class:`Unauthenticated` instead of falling
+    back to the shared "local" bucket — a security boundary must fail closed.
+    """
+    subject = _oauth_subject()
+    if subject:
+        return subject
+    if require_auth:
+        raise Unauthenticated(
+            "No authenticated caller could be resolved. This server requires auth "
+            "on the HTTP transport so that state stays isolated per user."
+        )
+    return os.environ.get("MCPSTATE_USER", "local")

mcpstate/ops.py

@@ -0,0 +1,168 @@
+"""Commutative patch operations.
+
+Patches are applied without version checks: adding an item, setting a key, or
+merging a mapping commutes with the same operations from another session, so
+two devices patching concurrently both land. Only full-state saves need the
+version protocol.
+"""
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass
+from typing import Any, Sequence, Union
+
+from .errors import PatchError
+
+
+@dataclass(frozen=True)
+class Append:
+    """Append ``value`` to the list at ``path``."""
+
+    path: str
+    value: Any
+
+
+@dataclass(frozen=True)
+class SetKey:
+    """Set ``key`` to ``value`` in the object at ``path``."""
+
+    path: str
+    key: str
+    value: Any
+
+
+@dataclass(frozen=True)
+class DelKey:
+    """Remove ``key`` from the object at ``path`` (no-op if absent)."""
+
+    path: str
+    key: str
+
+
+@dataclass(frozen=True)
+class Merge:
+    """Shallow-merge ``mapping`` into the state root."""
+
+    mapping: dict
+
+
+PatchOp = Union[Append, SetKey, DelKey, Merge]
+
+
+def _resolve(state: dict, path: str, op_name: str) -> Any:
+    node: Any = state
+    if path == "":
+        return node
+    for part in path.split("."):
+        if not isinstance(node, dict) or part not in node:
+            raise PatchError(
+                f"Path '{path}' does not exist in the state; cannot apply {op_name}. "
+                "Load the current state to see its shape.",
+                op=op_name,
+                path=path,
+                reason="path_not_found",
+            )
+        node = node[part]
+    return node
+
+
+def _apply_one(state: dict, op: PatchOp) -> None:
+    if isinstance(op, Append):
+        target = _resolve(state, op.path, "append")
+        if not isinstance(target, list):
+            raise PatchError(
+                f"Path '{op.path}' holds a {type(target).__name__}, but append needs a list.",
+                op="append",
+                path=op.path,
+                reason="expected_list",
+            )
+        target.append(op.value)
+    elif isinstance(op, SetKey):
+        target = _resolve(state, op.path, "set_key")
+        if not isinstance(target, dict):
+            raise PatchError(
+                f"Path '{op.path}' holds a {type(target).__name__}, but set_key needs an object.",
+                op="set_key",
+                path=op.path,
+                reason="expected_object",
+            )
+        target[op.key] = op.value
+    elif isinstance(op, DelKey):
+        target = _resolve(state, op.path, "del_key")
+        if not isinstance(target, dict):
+            raise PatchError(
+                f"Path '{op.path}' holds a {type(target).__name__}, but del_key needs an object.",
+                op="del_key",
+                path=op.path,
+                reason="expected_object",
+            )
+        target.pop(op.key, None)
+    elif isinstance(op, Merge):
+        if not isinstance(op.mapping, dict):
+            raise PatchError(
+                f"merge needs an object mapping, got {type(op.mapping).__name__}.",
+                op="merge",
+                reason="expected_object",
+            )
+        state.update(op.mapping)
+    else:  # pragma: no cover - defensive
+        raise PatchError(f"Unknown op {op!r}", op=str(op), reason="unknown_op")
+
+
+def get_path(state: dict, path: str) -> Any:
+    """Select the subtree at a dotted ``path`` (``""`` returns the whole state)."""
+    return _resolve(state, path, "load")
+
+
+def apply_ops(state: dict, ops: Sequence[PatchOp]) -> dict:
+    """Return a new state with every op applied. The input is never mutated."""
+    out = copy.deepcopy(state)
+    for op in ops:
+        _apply_one(out, op)
+    return out
+
+
+def _require(value: object, typ: tuple, field: str, op_name: str) -> None:
+    if not isinstance(value, typ) or isinstance(value, bool) and bool not in typ:
+        names = " or ".join(t.__name__ for t in typ)
+        raise PatchError(
+            f"Op '{op_name}' field '{field}' must be {names}, got {type(value).__name__}.",
+            op=op_name,
+            reason="bad_field_type",
+        )
+
+
+def op_from_dict(d: dict) -> PatchOp:
+    """Parse the wire form used by the flagship server's state_patch tool."""
+    if not isinstance(d, dict):
+        raise PatchError(
+            f"Each patch op must be an object, got {type(d).__name__}.",
+            reason="not_an_object",
+        )
+    kind = d.get("op")
+    try:
+        if kind == "append":
+            _require(d["path"], (str,), "path", "append")
+            return Append(d["path"], d["value"])
+        if kind == "set_key":
+            _require(d["path"], (str,), "path", "set_key")
+            _require(d["key"], (str,), "key", "set_key")
+            return SetKey(d["path"], d["key"], d["value"])
+        if kind == "del_key":
+            _require(d["path"], (str,), "path", "del_key")
+            _require(d["key"], (str,), "key", "del_key")
+            return DelKey(d["path"], d["key"])
+        if kind == "merge":
+            _require(d["mapping"], (dict,), "mapping", "merge")
+            return Merge(d["mapping"])
+    except KeyError as missing:
+        raise PatchError(
+            f"Op '{kind}' is missing required field {missing}.",
+            op=str(kind),
+            reason="missing_field",
+        ) from None
+    raise PatchError(
+        f"Unknown op '{kind}'. Supported: append, set_key, del_key, merge.",
+        op=str(kind),
+        reason="unknown_op",
+    )