basic-memory 0.16.1__py3-none-any.whl → 0.17.4__py3-none-any.whl

basic_memory/mcp/clients/project.py

@@ -0,0 +1,89 @@
+"""Typed client for project API operations.
+
+Encapsulates project-level endpoints.
+"""
+
+from typing import Any
+
+from httpx import AsyncClient
+
+from basic_memory.mcp.tools.utils import call_get, call_post, call_delete
+from basic_memory.schemas.project_info import ProjectList, ProjectStatusResponse
+
+
+class ProjectClient:
+    """Typed client for project management operations.
+
+    Centralizes:
+    - API path construction for project endpoints
+    - Response validation via Pydantic models
+    - Consistent error handling through call_* utilities
+
+    Note: This client does not require a project_id since it operates
+    across projects.
+
+    Usage:
+        async with get_client() as http_client:
+            client = ProjectClient(http_client)
+            projects = await client.list_projects()
+    """
+
+    def __init__(self, http_client: AsyncClient):
+        """Initialize the project client.
+
+        Args:
+            http_client: HTTPX AsyncClient for making requests
+        """
+        self.http_client = http_client
+
+    async def list_projects(self) -> ProjectList:
+        """List all available projects.
+
+        Returns:
+            ProjectList with all projects and default project name
+
+        Raises:
+            ToolError: If the request fails
+        """
+        response = await call_get(
+            self.http_client,
+            "/projects/projects",
+        )
+        return ProjectList.model_validate(response.json())
+
+    async def create_project(self, project_data: dict[str, Any]) -> ProjectStatusResponse:
+        """Create a new project.
+
+        Args:
+            project_data: Project creation data (name, path, set_default)
+
+        Returns:
+            ProjectStatusResponse with creation result
+
+        Raises:
+            ToolError: If the request fails
+        """
+        response = await call_post(
+            self.http_client,
+            "/projects/projects",
+            json=project_data,
+        )
+        return ProjectStatusResponse.model_validate(response.json())
+
+    async def delete_project(self, project_external_id: str) -> ProjectStatusResponse:
+        """Delete a project by its external ID.
+
+        Args:
+            project_external_id: Project external ID (UUID)
+
+        Returns:
+            ProjectStatusResponse with deletion result
+
+        Raises:
+            ToolError: If the request fails
+        """
+        response = await call_delete(
+            self.http_client,
+            f"/v2/projects/{project_external_id}",
+        )
+        return ProjectStatusResponse.model_validate(response.json())

basic_memory/mcp/clients/resource.py

@@ -0,0 +1,71 @@
+"""Typed client for resource API operations.
+
+Encapsulates all /v2/projects/{project_id}/resource/* endpoints.
+"""
+
+from typing import Optional
+
+from httpx import AsyncClient, Response
+
+from basic_memory.mcp.tools.utils import call_get
+
+
+class ResourceClient:
+    """Typed client for resource operations.
+
+    Centralizes:
+    - API path construction for /v2/projects/{project_id}/resource/*
+    - Consistent error handling through call_* utilities
+
+    Note: This client returns raw Response objects for resources since they
+    may be text, images, or other binary content that needs special handling.
+
+    Usage:
+        async with get_client() as http_client:
+            client = ResourceClient(http_client, project_id)
+            response = await client.read(entity_id)
+            text = response.text
+    """
+
+    def __init__(self, http_client: AsyncClient, project_id: str):
+        """Initialize the resource client.
+
+        Args:
+            http_client: HTTPX AsyncClient for making requests
+            project_id: Project external_id (UUID) for API calls
+        """
+        self.http_client = http_client
+        self.project_id = project_id
+        self._base_path = f"/v2/projects/{project_id}/resource"
+
+    async def read(
+        self,
+        entity_id: str,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+    ) -> Response:
+        """Read a resource by entity ID.
+
+        Args:
+            entity_id: Entity external_id (UUID)
+            page: Optional page number for paginated content
+            page_size: Optional page size for paginated content
+
+        Returns:
+            Raw HTTP Response (caller handles text/binary content)
+
+        Raises:
+            ToolError: If the resource is not found or request fails
+        """
+        params: dict = {}
+        if page is not None:
+            params["page"] = page
+        if page_size is not None:
+            params["page_size"] = page_size
+
+        return await call_get(
+            self.http_client,
+            f"{self._base_path}/{entity_id}",
+            params=params if params else None,
+        )

basic_memory/mcp/clients/search.py

@@ -0,0 +1,65 @@
+"""Typed client for search API operations.
+
+Encapsulates all /v2/projects/{project_id}/search/* endpoints.
+"""
+
+from typing import Any
+
+from httpx import AsyncClient
+
+from basic_memory.mcp.tools.utils import call_post
+from basic_memory.schemas.search import SearchResponse
+
+
+class SearchClient:
+    """Typed client for search operations.
+
+    Centralizes:
+    - API path construction for /v2/projects/{project_id}/search/*
+    - Response validation via Pydantic models
+    - Consistent error handling through call_* utilities
+
+    Usage:
+        async with get_client() as http_client:
+            client = SearchClient(http_client, project_id)
+            results = await client.search(search_query.model_dump())
+    """
+
+    def __init__(self, http_client: AsyncClient, project_id: str):
+        """Initialize the search client.
+
+        Args:
+            http_client: HTTPX AsyncClient for making requests
+            project_id: Project external_id (UUID) for API calls
+        """
+        self.http_client = http_client
+        self.project_id = project_id
+        self._base_path = f"/v2/projects/{project_id}/search"
+
+    async def search(
+        self,
+        query: dict[str, Any],
+        *,
+        page: int = 1,
+        page_size: int = 10,
+    ) -> SearchResponse:
+        """Search across all content in the knowledge base.
+
+        Args:
+            query: Search query dict (from SearchQuery.model_dump())
+            page: Page number (1-indexed)
+            page_size: Results per page
+
+        Returns:
+            SearchResponse with results and pagination
+
+        Raises:
+            ToolError: If the request fails
+        """
+        response = await call_post(
+            self.http_client,
+            f"{self._base_path}/",
+            json=query,
+            params={"page": page, "page_size": page_size},
+        )
+        return SearchResponse.model_validate(response.json())

basic_memory/mcp/container.py

@@ -0,0 +1,110 @@
+"""MCP composition root for Basic Memory.
+
+This container owns reading ConfigManager and environment variables for the
+MCP server entrypoint. Downstream modules receive config/dependencies explicitly
+rather than reading globals.
+
+Design principles:
+- Only this module reads ConfigManager directly
+- Runtime mode (cloud/local/test) is resolved here
+- File sync decisions are centralized here
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from basic_memory.config import BasicMemoryConfig, ConfigManager
+from basic_memory.runtime import RuntimeMode, resolve_runtime_mode
+
+if TYPE_CHECKING:  # pragma: no cover
+    from basic_memory.sync import SyncCoordinator
+
+
+@dataclass
+class McpContainer:
+    """Composition root for the MCP server entrypoint.
+
+    Holds resolved configuration and runtime context.
+    Created once at server startup, then used to wire dependencies.
+    """
+
+    config: BasicMemoryConfig
+    mode: RuntimeMode
+
+    @classmethod
+    def create(cls) -> "McpContainer":
+        """Create container by reading ConfigManager.
+
+        This is the single point where MCP reads global config.
+        """
+        config = ConfigManager().config
+        mode = resolve_runtime_mode(
+            cloud_mode_enabled=config.cloud_mode_enabled,
+            is_test_env=config.is_test_env,
+        )
+        return cls(config=config, mode=mode)
+
+    # --- Runtime Mode Properties ---
+
+    @property
+    def should_sync_files(self) -> bool:
+        """Whether local file sync should be started.
+
+        Sync is enabled when:
+        - sync_changes is True in config
+        - Not in test mode (tests manage their own sync)
+        - Not in cloud mode (cloud handles sync differently)
+        """
+        return (
+            self.config.sync_changes and not self.mode.is_test and not self.mode.is_cloud
+        )
+
+    @property
+    def sync_skip_reason(self) -> str | None:
+        """Reason why sync is skipped, or None if sync should run.
+
+        Useful for logging why sync was disabled.
+        """
+        if self.mode.is_test:
+            return "Test environment detected"
+        if self.mode.is_cloud:
+            return "Cloud mode enabled"
+        if not self.config.sync_changes:
+            return "Sync changes disabled"
+        return None
+
+    def create_sync_coordinator(self) -> "SyncCoordinator":
+        """Create a SyncCoordinator with this container's settings.
+
+        Returns:
+            SyncCoordinator configured for this runtime environment
+        """
+        # Deferred import to avoid circular dependency
+        from basic_memory.sync import SyncCoordinator
+
+        return SyncCoordinator(
+            config=self.config,
+            should_sync=self.should_sync_files,
+            skip_reason=self.sync_skip_reason,
+        )
+
+
+# Module-level container instance (set by lifespan)
+_container: McpContainer | None = None
+
+
+def get_container() -> McpContainer:
+    """Get the current MCP container.
+
+    Raises:
+        RuntimeError: If container hasn't been initialized
+    """
+    if _container is None:
+        raise RuntimeError("MCP container not initialized. Call set_container() first.")
+    return _container
+
+
+def set_container(container: McpContainer) -> None:
+    """Set the MCP container (called by lifespan)."""
+    global _container
+    _container = container

basic_memory/mcp/project_context.py

@@ -2,9 +2,12 @@
 
 Provides project lookup utilities for MCP tools.
 Handles project validation and context management in one place.
+
+Note: This module uses ProjectResolver for unified project resolution.
+The resolve_project_parameter function is a thin wrapper for backwards
+compatibility with existing MCP tools.
 """
 
-import os
 from typing import Optional, List
 from httpx import AsyncClient
 from httpx._types import (
@@ -14,16 +17,26 @@ from loguru import logger
 from fastmcp import Context
 
 from basic_memory.config import ConfigManager
-from basic_memory.mcp.tools.utils import call_get
+from basic_memory.project_resolver import ProjectResolver
 from basic_memory.schemas.project_info import ProjectItem, ProjectList
 from basic_memory.utils import generate_permalink
 
 
-async def resolve_project_parameter(project: Optional[str] = None) -> Optional[str]:
+async def resolve_project_parameter(
+    project: Optional[str] = None,
+    allow_discovery: bool = False,
+    cloud_mode: Optional[bool] = None,
+    default_project_mode: Optional[bool] = None,
+    default_project: Optional[str] = None,
+) -> Optional[str]:
     """Resolve project parameter using three-tier hierarchy.
 
-    if config.cloud_mode:
-        project is required
+    This is a thin wrapper around ProjectResolver for backwards compatibility.
+    New code should consider using ProjectResolver directly for more detailed
+    resolution information.
+
+    if cloud_mode:
+        project is required (unless allow_discovery=True for tools that support discovery mode)
     else:
         Resolution order:
         1. Single Project Mode  (--project cli arg, or BASIC_MEMORY_MCP_PROJECT env var) - highest priority
@@ -32,41 +45,39 @@ async def resolve_project_parameter(project: Optional[str] = None) -> Optional[s
 
     Args:
         project: Optional explicit project parameter
+        allow_discovery: If True, allows returning None in cloud mode for discovery mode
+            (used by tools like recent_activity that can operate across all projects)
+        cloud_mode: Optional explicit cloud mode. If not provided, reads from ConfigManager.
+        default_project_mode: Optional explicit default project mode. If not provided, reads from ConfigManager.
+        default_project: Optional explicit default project. If not provided, reads from ConfigManager.
 
     Returns:
         Resolved project name or None if no resolution possible
     """
-
-    config = ConfigManager().config
-    # if cloud_mode, project is required
-    if config.cloud_mode:
-        if project:
-            logger.debug(f"project: {project}, cloud_mode: {config.cloud_mode}")
-            return project
-        else:
-            raise ValueError("No project specified. Project is required for cloud mode.")
-
-    # Priority 1: CLI constraint overrides everything (--project arg sets env var)
-    constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
-    if constrained_project:
-        logger.debug(f"Using CLI constrained project: {constrained_project}")
-        return constrained_project
-
-    # Priority 2: Explicit project parameter
-    if project:
-        logger.debug(f"Using explicit project parameter: {project}")
-        return project
-
-    # Priority 3: Default project mode
-    if config.default_project_mode:
-        logger.debug(f"Using default project from config: {config.default_project}")
-        return config.default_project
-
-    # No resolution possible
-    return None
+    # Load config for any values not explicitly provided
+    if cloud_mode is None or default_project_mode is None or default_project is None:
+        config = ConfigManager().config
+        if cloud_mode is None:
+            cloud_mode = config.cloud_mode
+        if default_project_mode is None:
+            default_project_mode = config.default_project_mode
+        if default_project is None:
+            default_project = config.default_project
+
+    # Create resolver with configuration and resolve
+    resolver = ProjectResolver.from_env(
+        cloud_mode=cloud_mode,
+        default_project_mode=default_project_mode,
+        default_project=default_project,
+    )
+    result = resolver.resolve(project=project, allow_discovery=allow_discovery)
+    return result.project
 
 
 async def get_project_names(client: AsyncClient, headers: HeaderTypes | None = None) -> List[str]:
+    # Deferred import to avoid circular dependency with tools
+    from basic_memory.mcp.tools.utils import call_get
+
     response = await call_get(client, "/projects/projects", headers=headers)
     project_list = ProjectList.model_validate(response.json())
     return [project.name for project in project_list.projects]
@@ -92,6 +103,9 @@ async def get_active_project(
         ValueError: If no project can be resolved
         HTTPError: If project doesn't exist or is inaccessible
     """
+    # Deferred import to avoid circular dependency with tools
+    from basic_memory.mcp.tools.utils import call_get
+
     resolved_project = await resolve_project_parameter(project)
     if not resolved_project:
         project_names = await get_project_names(client, headers)

basic_memory/mcp/prompts/ai_assistant_guide.py

@@ -32,7 +32,7 @@ def ai_assistant_guide() -> str:
 
     # Add mode-specific header
     mode_info = ""
-    if config.default_project_mode:
+    if config.default_project_mode:  # pragma: no cover
         mode_info = f"""
 # 🎯 Default Project Mode Active
 
@@ -46,7 +46,7 @@ def ai_assistant_guide() -> str:
 ────────────────────────────────────────
 
 """
-    else:
+    else:  # pragma: no cover
         mode_info = """
 # 🔧 Multi-Project Mode Active
 

basic_memory/mcp/prompts/recent_activity.py

@@ -64,7 +64,7 @@ async def recent_activity_prompt(
                     primary_results.append(item.primary_result)
                     # Add up to 1 related result per primary item
                     if item.related_results:
-                        related_results.extend(item.related_results[:1])
+                        related_results.extend(item.related_results[:1])  # pragma: no cover
 
         # Limit total results for readability
         primary_results = primary_results[:8]
@@ -78,7 +78,7 @@ async def recent_activity_prompt(
                 primary_results.append(item.primary_result)
                 # Add up to 2 related results per primary item
                 if item.related_results:
-                    related_results.extend(item.related_results[:2])
+                    related_results.extend(item.related_results[:2])  # pragma: no cover
 
     # Set topic based on mode
     if project:

basic_memory/mcp/prompts/utils.py

@@ -123,9 +123,9 @@ def format_prompt_context(context: PromptContext) -> str:
 
                 # Add content snippet
                 if hasattr(primary, "content") and primary.content:  # pyright: ignore
-                    content = primary.content or ""  # pyright: ignore
-                    if content:
-                        section += f"\n**Excerpt**:\n{content}\n"
+                    content = primary.content or ""  # pyright: ignore  # pragma: no cover
+                    if content:  # pragma: no cover
+                        section += f"\n**Excerpt**:\n{content}\n"  # pragma: no cover
 
                 section += dedent(f"""
 

basic_memory/mcp/server.py

@@ -2,8 +2,66 @@
 Basic Memory FastMCP server.
 """
 
+from contextlib import asynccontextmanager
+
 from fastmcp import FastMCP
+from loguru import logger
+
+from basic_memory import db
+from basic_memory.mcp.container import McpContainer, set_container
+from basic_memory.services.initialization import initialize_app
+from basic_memory.telemetry import show_notice_if_needed, track_app_started
+
+
+@asynccontextmanager
+async def lifespan(app: FastMCP):
+    """Lifecycle manager for the MCP server.
+
+    Handles:
+    - Database initialization and migrations
+    - Telemetry notice and tracking
+    - File sync via SyncCoordinator (if enabled and not in cloud mode)
+    - Proper cleanup on shutdown
+    """
+    # --- Composition Root ---
+    # Create container and read config (single point of config access)
+    container = McpContainer.create()
+    set_container(container)
+
+    logger.info(f"Starting Basic Memory MCP server (mode={container.mode.name})")
+
+    # Show telemetry notice (first run only) and track startup
+    show_notice_if_needed()
+    track_app_started("mcp")
+
+    # Track if we created the engine (vs test fixtures providing it)
+    # This prevents disposing an engine provided by test fixtures when
+    # multiple Client connections are made in the same test
+    engine_was_none = db._engine is None
+
+    # Initialize app (runs migrations, reconciles projects)
+    await initialize_app(container.config)
+
+    # Create and start sync coordinator (lifecycle centralized in coordinator)
+    sync_coordinator = container.create_sync_coordinator()
+    await sync_coordinator.start()
+
+    try:
+        yield
+    finally:
+        # Shutdown - coordinator handles clean task cancellation
+        logger.info("Shutting down Basic Memory MCP server")
+        await sync_coordinator.stop()
+
+        # Only shutdown DB if we created it (not if test fixture provided it)
+        if engine_was_none:
+            await db.shutdown_db()
+            logger.info("Database connections closed")
+        else:  # pragma: no cover
+            logger.debug("Skipping DB shutdown - engine provided externally")
+
 
 mcp = FastMCP(
     name="Basic Memory",
+    lifespan=lifespan,
 )

basic_memory/mcp/tools/build_context.py

@@ -8,7 +8,7 @@ from fastmcp import Context
 from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.utils import call_get
+from basic_memory.telemetry import track_mcp_tool
 from basic_memory.schemas.base import TimeFrame
 from basic_memory.schemas.memory import (
     GraphContext,
@@ -87,6 +87,7 @@ async def build_context(
     Raises:
         ToolError: If project doesn't exist or depth parameter is invalid
     """
+    track_mcp_tool("build_context")
     logger.info(f"Building context from {url} in project {project}")
 
     # Convert string depth to integer if needed
@@ -104,17 +105,16 @@ async def build_context(
         # Get the active project using the new stateless approach
         active_project = await get_active_project(client, project, context)
 
-        project_url = active_project.project_url
-
-        response = await call_get(
-            client,
-            f"{project_url}/memory/{memory_url_path(url)}",
-            params={
-                "depth": depth,
-                "timeframe": timeframe,
-                "page": page,
-                "page_size": page_size,
-                "max_related": max_related,
-            },
+        # Import here to avoid circular import
+        from basic_memory.mcp.clients import MemoryClient
+
+        # Use typed MemoryClient for API calls
+        memory_client = MemoryClient(client, active_project.external_id)
+        return await memory_client.build_context(
+            memory_url_path(url),
+            depth=depth or 1,
+            timeframe=timeframe,
+            page=page,
+            page_size=page_size,
+            max_related=max_related,
         )
-        return GraphContext.model_validate(response.json())