memcp-server 0.1.0__py3-none-any.whl

memcp/__init__.py

@@ -0,0 +1,3 @@
+"""memcp — backend-agnostic, multi-tenant MCP memory server."""
+
+__version__ = "0.1.0"

memcp/__main__.py

@@ -0,0 +1,38 @@
+"""python -m memcp entrypoint."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+import uvicorn
+from pydantic import ValidationError
+
+from memcp.config import Config
+from memcp.logging import setup_logging
+from memcp.server import create_app
+
+logger = logging.getLogger(__name__)
+
+
+def main() -> None:
+    try:
+        config = Config()  # type: ignore[call-arg]
+    except ValidationError as e:
+        print(f"Configuration error:\n{e}", file=sys.stderr)
+        raise SystemExit(1) from None
+    setup_logging(level=config.log_level, fmt=config.log_format)
+
+    if not config.memcp_auth_tokens:
+        logger.warning("MEMCP_AUTH_TOKENS is unset — the MCP endpoint is UNAUTHENTICATED.")
+
+    try:
+        app, _backend = create_app(config)
+    except ValueError as e:
+        logger.critical("Configuration error: %s", e)
+        raise SystemExit(1) from None
+    uvicorn.run(app, host=config.host, port=config.port, log_config=None)
+
+
+if __name__ == "__main__":
+    main()

memcp/auth.py

@@ -0,0 +1,156 @@
+"""Authentication — tenant resolution, context propagation, ASGI middleware.
+
+Tenant identity flows: Bearer token → Resolver → ContextVar → tool handlers.
+"""
+
+from __future__ import annotations
+
+import hmac
+import json
+import logging
+from contextvars import ContextVar
+from typing import Any, Protocol, runtime_checkable
+
+from memcp.types import canonical_error
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Tenant context (per-request via contextvars)
+# ---------------------------------------------------------------------------
+
+_tenant_var: ContextVar[str] = ContextVar("tenant_user_id")
+
+_DEFAULT_USER = "default_user"
+
+
+def get_tenant() -> str:
+    """Read the current request's user_id. Falls back to default in dev mode."""
+    return _tenant_var.get(_DEFAULT_USER)
+
+
+def set_tenant(user_id: str) -> Any:
+    """Set the current request's user_id. Returns a reset token."""
+    return _tenant_var.set(user_id)
+
+
+def reset_tenant(token: Any) -> None:
+    """Reset the contextvar to its previous value."""
+    _tenant_var.reset(token)
+
+
+# ---------------------------------------------------------------------------
+# Resolver protocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class Resolver(Protocol):
+    async def resolve(self, token: str) -> str | None:
+        """Map a bearer token to a user_id. Returns None for invalid tokens (never raises)."""
+        ...
+
+
+class StaticResolver:
+    """Resolves tokens from a static dict (parsed from env var)."""
+
+    def __init__(self, mapping: dict[str, str]):
+        self._mapping = mapping
+
+    async def resolve(self, token: str) -> str | None:
+        # Iterate all tokens without early return — constant-time to prevent timing oracle
+        matched: str | None = None
+        for known_token, user_id in self._mapping.items():
+            if hmac.compare_digest(token.encode(), known_token.encode()):
+                matched = user_id
+        return matched
+
+    @classmethod
+    def from_env(cls, raw: str) -> StaticResolver:
+        """Parse 'token1:user1,token2:user2' format."""
+        mapping: dict[str, str] = {}
+        for pair in raw.split(","):
+            pair = pair.strip()
+            if not pair:
+                continue
+            if ":" not in pair:
+                raise ValueError(
+                    f"Invalid token mapping: {pair!r}. Expected format: token:user_id"
+                )
+            token, user_id = pair.split(":", 1)
+            token, user_id = token.strip(), user_id.strip()
+            if not token or not user_id:
+                raise ValueError(f"Empty token or user_id in mapping: {pair!r}")
+            mapping[token] = user_id
+        if not mapping:
+            raise ValueError("MEMCP_AUTH_TOKENS is set but contains no valid mappings")
+        return cls(mapping)
+
+
+# ---------------------------------------------------------------------------
+# ASGI middleware
+# ---------------------------------------------------------------------------
+
+
+class BearerGate:
+    """ASGI middleware that resolves bearer tokens to tenant identity.
+
+    Raw ASGI (not BaseHTTPMiddleware) to avoid buffering MCP streaming.
+    Non-HTTP scopes (lifespan) pass through.
+    """
+
+    def __init__(self, app: Any, resolver: Resolver | None):
+        self.app = app
+        self.resolver = resolver
+
+    async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        if not self.resolver:
+            # Dev mode: no auth, default user
+            token = set_tenant(_DEFAULT_USER)
+            try:
+                await self.app(scope, receive, send)
+            finally:
+                reset_tenant(token)
+            return
+
+        headers = dict(scope.get("headers") or [])
+        provided = headers.get(b"authorization", b"").decode("utf-8", errors="replace")
+
+        if not provided.startswith("Bearer "):
+            logger.warning("Rejected request: missing Bearer prefix (path=%s)", scope.get("path"))
+            await self._send_401(send)
+            return
+
+        bearer_token = provided[7:]
+        user_id = await self.resolver.resolve(bearer_token)
+
+        if user_id is None:
+            logger.warning("Rejected request: invalid token (path=%s)", scope.get("path"))
+            await self._send_401(send)
+            return
+
+        token = set_tenant(user_id)
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            reset_tenant(token)
+
+    @staticmethod
+    async def _send_401(send: Any) -> None:
+        err = canonical_error("unauthorized", "Invalid or missing token")
+        body = json.dumps(err).encode()
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 401,
+                "headers": [
+                    (b"content-type", b"application/json"),
+                    (b"www-authenticate", b"Bearer"),
+                ],
+            }
+        )
+        await send({"type": "http.response.body", "body": body, "more_body": False})

memcp/backend/__init__.py

@@ -0,0 +1,5 @@
+"""Memory backend adapters."""
+
+from memcp.backend.base import MemoryBackend
+
+__all__ = ["MemoryBackend"]

memcp/backend/base.py

@@ -0,0 +1,115 @@
+"""MemoryBackend ABC — @experimental, will change in v0.2 when second backend is added."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from memcp.types import (
+    AddResult,
+    EntitiesResult,
+    HealthStatus,
+    HistoryEntry,
+    ListResult,
+    Memory,
+)
+
+
+class MemoryBackend(ABC):
+    """Abstract base class for memory storage backends.
+
+    @experimental — validated against mem0 and in-memory adapters.
+    Will be refined when Cognee adapter is added in v0.2.
+    """
+
+    # --- required (universal tools) ---
+
+    @abstractmethod
+    async def add(
+        self,
+        user_id: str,
+        content: str,
+        *,
+        scope: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+        infer: bool = True,
+    ) -> AddResult | list[AddResult]: ...
+
+    @abstractmethod
+    async def search(
+        self,
+        user_id: str,
+        query: str,
+        *,
+        scope: dict[str, Any] | None = None,
+        limit: int = 10,
+        threshold: float = 0.0,
+    ) -> list[Memory]: ...
+
+    @abstractmethod
+    async def delete(self, user_id: str, memory_id: str) -> bool:
+        """Raises MemoryAPIError(404) if not found or not owned by user_id."""
+        ...
+
+    @abstractmethod
+    async def delete_all(self, user_id: str, scope: dict[str, Any]) -> int | None:
+        """Returns count of deleted memories, or None if backend doesn't report counts."""
+        ...
+
+    @abstractmethod
+    async def health(self) -> HealthStatus: ...
+
+    @abstractmethod
+    def capabilities(self) -> set[str]: ...
+
+    @abstractmethod
+    def scope_keys(self) -> list[str]: ...
+
+    # --- optional (declared in capabilities()) ---
+
+    async def get(self, user_id: str, memory_id: str) -> Memory | None:
+        """Returns None if not found or not owned by user_id."""
+        raise NotImplementedError
+
+    async def update(
+        self,
+        user_id: str,
+        memory_id: str,
+        content: str,
+        *,
+        metadata: dict[str, Any] | None = None,
+    ) -> Memory:
+        """Raises MemoryAPIError(404) if not found or not owned by user_id."""
+        raise NotImplementedError
+
+    async def list_memories(
+        self,
+        user_id: str,
+        *,
+        scope: dict[str, Any] | None = None,
+        limit: int = 100,
+        cursor: str | None = None,
+    ) -> ListResult:
+        raise NotImplementedError
+
+    async def history(self, user_id: str, memory_id: str) -> list[HistoryEntry]:
+        """Raises MemoryAPIError(404) if not found or not owned by user_id.
+
+        Note: action strings are backend-specific (e.g. "created"/"updated" vs
+        "add"/"update"). Normalize in v0.2 when the Protocol stabilizes.
+        """
+        raise NotImplementedError
+
+    async def entities(
+        self,
+        user_id: str,
+        *,
+        scope: dict[str, Any] | None = None,
+        limit: int = 100,
+    ) -> EntitiesResult:
+        raise NotImplementedError
+
+    # --- lifecycle ---
+
+    async def close(self) -> None:  # noqa: B027
+        """Clean up resources. Called on shutdown."""

memcp/backend/in_memory.py

@@ -0,0 +1,261 @@
+"""In-memory backend adapter — for conformance tests, dev mode, and demos.
+
+Stores memories in plain dicts. No persistence, no extraction, no vector search.
+Search uses substring matching on content as a trivial approximation.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from memcp.types import (
+    AddResult,
+    EntitiesResult,
+    HealthStatus,
+    HistoryEntry,
+    ListResult,
+    Memory,
+    MemoryAPIError,
+    paginate,
+    reject_nested_filters,
+)
+
+from .base import MemoryBackend
+
+
+class InMemoryBackend(MemoryBackend):
+    """Trivial in-memory implementation of the MemoryBackend protocol."""
+
+    def __init__(self) -> None:
+        # {memory_id: {user_id, content, scope, metadata, created_at, updated_at}}
+        self._store: dict[str, dict[str, Any]] = {}
+        # {memory_id: [HistoryEntry, ...]}
+        self._history: dict[str, list[dict[str, Any]]] = {}
+
+    # --- required ---
+
+    async def add(
+        self,
+        user_id: str,
+        content: str,
+        *,
+        scope: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+        infer: bool = True,
+    ) -> list[AddResult]:
+        if scope:
+            reject_nested_filters(scope)
+        memory_id = str(uuid.uuid4())
+        now = datetime.now(UTC).isoformat()
+        self._store[memory_id] = {
+            "user_id": user_id,
+            "content": content,
+            "scope": scope or {},
+            "metadata": metadata or {},
+            "created_at": now,
+            "updated_at": None,
+        }
+        self._history[memory_id] = [
+            {
+                "action": "created",
+                "timestamp": now,
+                "content_before": None,
+                "content_after": content,
+            }
+        ]
+        return [AddResult(id=memory_id, status="ready", created_at=now)]
+
+    async def search(
+        self,
+        user_id: str,
+        query: str,
+        *,
+        scope: dict[str, Any] | None = None,
+        limit: int = 10,
+        threshold: float = 0.0,
+    ) -> list[Memory]:
+        if scope:
+            reject_nested_filters(scope)
+        results = []
+        query_lower = query.lower()
+        for mid, entry in self._store.items():
+            if entry["user_id"] != user_id:
+                continue
+            if scope:
+                entry_scope = entry.get("scope", {})
+                if not all(entry_scope.get(k) == v for k, v in scope.items()):
+                    continue
+            content_lower = entry["content"].lower()
+            # Trivial relevance: count query word matches
+            words = query_lower.split()
+            matches = sum(1 for w in words if w in content_lower)
+            if matches == 0 and query_lower not in content_lower:
+                continue
+            score = matches / max(len(words), 1)
+            results.append((score, mid, entry))
+        results.sort(key=lambda x: x[0], reverse=True)
+        return [
+            Memory(
+                id=mid,
+                content=entry["content"],
+                score=score,
+                scope=entry.get("scope", {}),
+                metadata=entry.get("metadata", {}),
+                created_at=entry["created_at"],
+                updated_at=entry.get("updated_at"),
+            )
+            for score, mid, entry in results[:limit]
+        ]
+
+    async def delete(self, user_id: str, memory_id: str) -> bool:
+        entry = self._store.get(memory_id)
+        if entry is None:
+            raise MemoryAPIError(404, "Not found")
+        if entry["user_id"] != user_id:
+            raise MemoryAPIError(404, "Not found")
+        del self._store[memory_id]
+        self._history.pop(memory_id, None)
+        return True
+
+    async def delete_all(self, user_id: str, scope: dict[str, Any]) -> int:
+        reject_nested_filters(scope)
+        to_delete = []
+        for mid, entry in self._store.items():
+            if entry["user_id"] != user_id:
+                continue
+            entry_scope = entry.get("scope", {})
+            if all(entry_scope.get(k) == v for k, v in scope.items()):
+                to_delete.append(mid)
+        for mid in to_delete:
+            del self._store[mid]
+            self._history.pop(mid, None)
+        return len(to_delete)
+
+    async def health(self) -> HealthStatus:
+        return HealthStatus(status="healthy", backend="in_memory", latency_ms=0.0)
+
+    def capabilities(self) -> set[str]:
+        return {
+            "get_memory",
+            "update_memory",
+            "list_memories",
+            "memory_history",
+            "memory_entities",
+        }
+
+    def scope_keys(self) -> list[str]:
+        return ["agent_id", "run_id"]
+
+    # --- optional ---
+
+    async def get(self, user_id: str, memory_id: str) -> Memory | None:
+        entry = self._store.get(memory_id)
+        if entry is None or entry["user_id"] != user_id:
+            return None
+        return Memory(
+            id=memory_id,
+            content=entry["content"],
+            scope=entry.get("scope", {}),
+            metadata=entry.get("metadata", {}),
+            created_at=entry["created_at"],
+            updated_at=entry.get("updated_at"),
+        )
+
+    async def update(
+        self,
+        user_id: str,
+        memory_id: str,
+        content: str,
+        *,
+        metadata: dict[str, Any] | None = None,
+    ) -> Memory:
+        entry = self._store.get(memory_id)
+        if entry is None or entry["user_id"] != user_id:
+            raise MemoryAPIError(404, "Not found")
+        now = datetime.now(UTC).isoformat()
+        old_content = entry["content"]
+        entry["content"] = content
+        entry["updated_at"] = now
+        if metadata is not None:
+            entry["metadata"] = metadata
+        if memory_id in self._history:
+            self._history[memory_id].append(
+                {
+                    "action": "updated",
+                    "timestamp": now,
+                    "content_before": old_content,
+                    "content_after": content,
+                }
+            )
+        return Memory(
+            id=memory_id,
+            content=content,
+            scope=entry.get("scope", {}),
+            metadata=entry.get("metadata", {}),
+            created_at=entry["created_at"],
+            updated_at=now,
+        )
+
+    async def list_memories(
+        self,
+        user_id: str,
+        *,
+        scope: dict[str, Any] | None = None,
+        limit: int = 100,
+        cursor: str | None = None,
+    ) -> ListResult:
+        memories = []
+        for mid, entry in self._store.items():
+            if entry["user_id"] != user_id:
+                continue
+            if scope:
+                entry_scope = entry.get("scope", {})
+                if not all(entry_scope.get(k) == v for k, v in scope.items()):
+                    continue
+            memories.append(
+                Memory(
+                    id=mid,
+                    content=entry["content"],
+                    scope=entry.get("scope", {}),
+                    metadata=entry.get("metadata", {}),
+                    created_at=entry["created_at"],
+                    updated_at=entry.get("updated_at"),
+                )
+            )
+        return paginate(memories, cursor, limit)
+
+    async def history(self, user_id: str, memory_id: str) -> list[HistoryEntry]:
+        entry = self._store.get(memory_id)
+        if entry is None or entry["user_id"] != user_id:
+            raise MemoryAPIError(404, "Not found")
+        raw = self._history.get(memory_id, [])
+        return [
+            HistoryEntry(
+                action=h["action"],
+                timestamp=h["timestamp"],
+                content_before=h.get("content_before"),
+                content_after=h.get("content_after"),
+            )
+            for h in raw
+        ]
+
+    async def entities(
+        self,
+        user_id: str,
+        *,
+        scope: dict[str, Any] | None = None,
+        limit: int = 100,
+    ) -> EntitiesResult:
+        count = sum(1 for e in self._store.values() if e["user_id"] == user_id)
+        if count == 0:
+            return EntitiesResult(entities=[], relationships=[])
+        return EntitiesResult(
+            entities=[{"id": user_id, "type": "user", "total_memories": count}],
+            relationships=[],
+        )
+
+    async def close(self) -> None:
+        self._store.clear()
+        self._history.clear()