basic-memory 0.14.4__py3-none-any.whl → 0.15.1__py3-none-any.whl

basic_memory/mcp/tools/project_management.py

@@ -4,242 +4,76 @@ These tools allow users to switch between projects, list available projects,
 and manage project context during conversations.
 """
 
-from textwrap import dedent
-from typing import Optional
-
+import os
 from fastmcp import Context
-from loguru import logger
 
-from basic_memory.mcp.async_client import client
-from basic_memory.mcp.project_session import session, add_project_metadata
+from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.utils import call_get, call_put, call_post, call_delete
-from basic_memory.schemas import ProjectInfoResponse
-from basic_memory.schemas.project_info import ProjectList, ProjectStatusResponse, ProjectInfoRequest
+from basic_memory.mcp.tools.utils import call_get, call_post, call_delete
+from basic_memory.schemas.project_info import (
+    ProjectList,
+    ProjectStatusResponse,
+    ProjectInfoRequest,
+)
 from basic_memory.utils import generate_permalink
 
 
 @mcp.tool("list_memory_projects")
-async def list_memory_projects(
-    ctx: Context | None = None, _compatibility: Optional[str] = None
-) -> str:
+async def list_memory_projects(context: Context | None = None) -> str:
     """List all available projects with their status.
 
-    Shows all Basic Memory projects that are available, indicating which one
-    is currently active and which is the default.
-
-    Returns:
-        Formatted list of projects with status indicators
-
-    Example:
-        list_memory_projects()
-    """
-    if ctx:  # pragma: no cover
-        await ctx.info("Listing all available projects")
-
-    # Get projects from API
-    response = await call_get(client, "/projects/projects")
-    project_list = ProjectList.model_validate(response.json())
-
-    current = session.get_current_project()
-
-    result = "Available projects:\n"
-
-    for project in project_list.projects:
-        indicators = []
-        if project.name == current:
-            indicators.append("current")
-        if project.is_default:
-            indicators.append("default")
+    Shows all Basic Memory projects that are available for MCP operations.
+    Use this tool to discover projects when you need to know which project to use.
 
-        if indicators:
-            result += f"• {project.name} ({', '.join(indicators)})\n"
-        else:
-            result += f"• {project.name}\n"
-
-    return add_project_metadata(result, current)
-
-
-@mcp.tool()
-async def switch_project(project_name: str, ctx: Context | None = None) -> str:
-    """Switch to a different project context.
-
-    Changes the active project context for all subsequent tool calls.
-    Shows a project summary after switching successfully.
+    Use this tool:
+    - At conversation start when project is unknown
+    - When user asks about available projects
+    - Before any operation requiring a project
 
-    Args:
-        project_name: Name of the project to switch to
+    After calling:
+    - Ask user which project to use
+    - Remember their choice for the session
 
     Returns:
-        Confirmation message with project summary
+        Formatted list of projects with session management guidance
 
     Example:
-        switch_project("work-notes")
-        switch_project("personal-journal")
+        list_memory_projects()
     """
-    if ctx:  # pragma: no cover
-        await ctx.info(f"Switching to project: {project_name}")
+    async with get_client() as client:
+        if context:  # pragma: no cover
+            await context.info("Listing all available projects")
+
+        # Check if server is constrained to a specific project
+        constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
 
-    project_permalink = generate_permalink(project_name)
-    current_project = session.get_current_project()
-    try:
-        # Validate project exists by getting project list
+        # Get projects from API
         response = await call_get(client, "/projects/projects")
         project_list = ProjectList.model_validate(response.json())
 
-        # Find the project by name (case-insensitive) or permalink
-        target_project = None
-        for p in project_list.projects:
-            # Match by permalink (handles case-insensitive input)
-            if p.permalink == project_permalink:
-                target_project = p
-                break
-            # Also match by name comparison (case-insensitive)
-            if p.name.lower() == project_name.lower():
-                target_project = p
-                break
-
-        if not target_project:
-            available_projects = [p.name for p in project_list.projects]
-            return f"Error: Project '{project_name}' not found. Available projects: {', '.join(available_projects)}"
-
-        # Switch to the project using the canonical name from database
-        canonical_name = target_project.name
-        session.set_current_project(canonical_name)
-        current_project = session.get_current_project()
-
-        # Get project info to show summary
-        try:
-            current_project_permalink = generate_permalink(canonical_name)
-            response = await call_get(
-                client,
-                f"/{current_project_permalink}/project/info",
-                params={"project_name": canonical_name},
-            )
-            project_info = ProjectInfoResponse.model_validate(response.json())
-
-            result = f"✓ Switched to {canonical_name} project\n\n"
-            result += "Project Summary:\n"
-            result += f"• {project_info.statistics.total_entities} entities\n"
-            result += f"• {project_info.statistics.total_observations} observations\n"
-            result += f"• {project_info.statistics.total_relations} relations\n"
-
-        except Exception as e:
-            # If we can't get project info, still confirm the switch
-            logger.warning(f"Could not get project info for {canonical_name}: {e}")
-            result = f"✓ Switched to {canonical_name} project\n\n"
-            result += "Project summary unavailable.\n"
-
-        return add_project_metadata(result, canonical_name)
-
-    except Exception as e:
-        logger.error(f"Error switching to project {project_name}: {e}")
-        # Revert to previous project on error
-        session.set_current_project(current_project)
-
-        # Return user-friendly error message instead of raising exception
-        return dedent(f"""
-            # Project Switch Failed
-
-            Could not switch to project '{project_name}': {str(e)}
-
-            ## Current project: {current_project}
-            Your session remains on the previous project.
-
-            ## Troubleshooting:
-            1. **Check available projects**: Use `list_memory_projects()` to see valid project names
-            2. **Verify spelling**: Ensure the project name is spelled correctly
-            3. **Check permissions**: Verify you have access to the requested project
-            4. **Try again**: The error might be temporary
-
-            ## Available options:
-            - See all projects: `list_memory_projects()`
-            - Stay on current project: `get_current_project()`
-            - Try different project: `switch_project("correct-project-name")`
-
-            If the project should exist but isn't listed, send a message to support@basicmachines.co.
-            """).strip()
-
-
-@mcp.tool()
-async def get_current_project(
-    ctx: Context | None = None, _compatibility: Optional[str] = None
-) -> str:
-    """Show the currently active project and basic stats.
-
-    Displays which project is currently active and provides basic information
-    about it.
-
-    Returns:
-        Current project name and basic statistics
-
-    Example:
-        get_current_project()
-    """
-    if ctx:  # pragma: no cover
-        await ctx.info("Getting current project information")
-
-    current_project = session.get_current_project()
-    result = f"Current project: {current_project}\n\n"
-
-    # get project stats (use permalink in URL path)
-    current_project_permalink = generate_permalink(current_project)
-    response = await call_get(
-        client,
-        f"/{current_project_permalink}/project/info",
-        params={"project_name": current_project},
-    )
-    project_info = ProjectInfoResponse.model_validate(response.json())
-
-    result += f"• {project_info.statistics.total_entities} entities\n"
-    result += f"• {project_info.statistics.total_observations} observations\n"
-    result += f"• {project_info.statistics.total_relations} relations\n"
-
-    default_project = session.get_default_project()
-    if current_project != default_project:
-        result += f"• Default project: {default_project}\n"
-
-    return add_project_metadata(result, current_project)
-
-
-@mcp.tool()
-async def set_default_project(project_name: str, ctx: Context | None = None) -> str:
-    """Set default project in config. Requires restart to take effect.
-
-    Updates the configuration to use a different default project. This change
-    only takes effect after restarting the Basic Memory server.
-
-    Args:
-        project_name: Name of the project to set as default
-
-    Returns:
-        Confirmation message about config update
-
-    Example:
-        set_default_project("work-notes")
-    """
-    if ctx:  # pragma: no cover
-        await ctx.info(f"Setting default project to: {project_name}")
-
-    # Call API to set default project using URL encoding for special characters
-    from urllib.parse import quote
-    encoded_name = quote(project_name, safe='')
-    response = await call_put(client, f"/projects/{encoded_name}/default")
-    status_response = ProjectStatusResponse.model_validate(response.json())
+        if constrained_project:
+            result = f"Project: {constrained_project}\n\n"
+            result += "Note: This MCP server is constrained to a single project.\n"
+            result += "All operations will automatically use this project."
+        else:
+            # Show all projects with session guidance
+            result = "Available projects:\n"
 
-    result = f"✓ {status_response.message}\n\n"
-    result += "Restart Basic Memory for this change to take effect:\n"
-    result += "basic-memory mcp\n"
+            for project in project_list.projects:
+                result += f"• {project.name}\n"
 
-    if status_response.old_project:
-        result += f"\nPrevious default: {status_response.old_project.name}\n"
+            result += "\n" + "─" * 40 + "\n"
+            result += "Next: Ask which project to use for this session.\n"
+            result += "Example: 'Which project should I use for this task?'\n\n"
+            result += "Session reminder: Track the selected project for all subsequent operations in this conversation.\n"
+            result += "The user can say 'switch to [project]' to change projects."
 
-    return add_project_metadata(result, session.get_current_project())
+        return result
 
 
 @mcp.tool("create_memory_project")
 async def create_memory_project(
-    project_name: str, project_path: str, set_default: bool = False, ctx: Context | None = None
+    project_name: str, project_path: str, set_default: bool = False, context: Context | None = None
 ) -> str:
     """Create a new Basic Memory project.
 
@@ -258,39 +92,42 @@ async def create_memory_project(
         create_memory_project("my-research", "~/Documents/research")
         create_memory_project("work-notes", "/home/user/work", set_default=True)
     """
-    if ctx:  # pragma: no cover
-        await ctx.info(f"Creating project: {project_name} at {project_path}")
-
-    # Create the project request
-    project_request = ProjectInfoRequest(
-        name=project_name, path=project_path, set_default=set_default
-    )
-
-    # Call API to create project
-    response = await call_post(client, "/projects/projects", json=project_request.model_dump())
-    status_response = ProjectStatusResponse.model_validate(response.json())
+    async with get_client() as client:
+        # Check if server is constrained to a specific project
+        constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
+        if constrained_project:
+            return f'# Error\n\nProject creation disabled - MCP server is constrained to project \'{constrained_project}\'.\nUse the CLI to create projects: `basic-memory project add "{project_name}" "{project_path}"`'
+
+        if context:  # pragma: no cover
+            await context.info(f"Creating project: {project_name} at {project_path}")
+
+        # Create the project request
+        project_request = ProjectInfoRequest(
+            name=project_name, path=project_path, set_default=set_default
+        )
 
-    result = f"✓ {status_response.message}\n\n"
+        # Call API to create project
+        response = await call_post(client, "/projects/projects", json=project_request.model_dump())
+        status_response = ProjectStatusResponse.model_validate(response.json())
 
-    if status_response.new_project:
-        result += "Project Details:\n"
-        result += f"• Name: {status_response.new_project.name}\n"
-        result += f"• Path: {status_response.new_project.path}\n"
+        result = f"✓ {status_response.message}\n\n"
 
-        if set_default:
-            result += "• Set as default project\n"
+        if status_response.new_project:
+            result += "Project Details:\n"
+            result += f"• Name: {status_response.new_project.name}\n"
+            result += f"• Path: {status_response.new_project.path}\n"
 
-    result += "\nProject is now available for use.\n"
+            if set_default:
+                result += "• Set as default project\n"
 
-    # If project was set as default, update session
-    if set_default:
-        session.set_current_project(project_name)
+        result += "\nProject is now available for use in tool calls.\n"
+        result += f"Use '{project_name}' as the project parameter in MCP tool calls.\n"
 
-    return add_project_metadata(result, session.get_current_project())
+        return result
 
 
 @mcp.tool()
-async def delete_project(project_name: str, ctx: Context | None = None) -> str:
+async def delete_project(project_name: str, context: Context | None = None) -> str:
     """Delete a Basic Memory project.
 
     Removes a project from the configuration and database. This does NOT delete
@@ -310,55 +147,54 @@ async def delete_project(project_name: str, ctx: Context | None = None) -> str:
         This action cannot be undone. The project will need to be re-added
         to access its content through Basic Memory again.
     """
-    if ctx:  # pragma: no cover
-        await ctx.info(f"Deleting project: {project_name}")
+    async with get_client() as client:
+        # Check if server is constrained to a specific project
+        constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
+        if constrained_project:
+            return f"# Error\n\nProject deletion disabled - MCP server is constrained to project '{constrained_project}'.\nUse the CLI to delete projects: `basic-memory project remove \"{project_name}\"`"
 
-    current_project = session.get_current_project()
+        if context:  # pragma: no cover
+            await context.info(f"Deleting project: {project_name}")
 
-    # Check if trying to delete current project
-    if project_name == current_project:
-        raise ValueError(
-            f"Cannot delete the currently active project '{project_name}'. Switch to a different project first."
-        )
+        # Get project info before deletion to validate it exists
+        response = await call_get(client, "/projects/projects")
+        project_list = ProjectList.model_validate(response.json())
 
-    # Get project info before deletion to validate it exists
-    response = await call_get(client, "/projects/projects")
-    project_list = ProjectList.model_validate(response.json())
-
-    # Find the project by name (case-insensitive) or permalink - same logic as switch_project
-    project_permalink = generate_permalink(project_name)
-    target_project = None
-    for p in project_list.projects:
-        # Match by permalink (handles case-insensitive input)
-        if p.permalink == project_permalink:
-            target_project = p
-            break
-        # Also match by name comparison (case-insensitive)
-        if p.name.lower() == project_name.lower():
-            target_project = p
-            break
-    
-    if not target_project:
-        available_projects = [p.name for p in project_list.projects]
-        raise ValueError(
-            f"Project '{project_name}' not found. Available projects: {', '.join(available_projects)}"
-        )
+        # Find the project by name (case-insensitive) or permalink - same logic as switch_project
+        project_permalink = generate_permalink(project_name)
+        target_project = None
+        for p in project_list.projects:
+            # Match by permalink (handles case-insensitive input)
+            if p.permalink == project_permalink:
+                target_project = p
+                break
+            # Also match by name comparison (case-insensitive)
+            if p.name.lower() == project_name.lower():
+                target_project = p
+                break
+
+        if not target_project:
+            available_projects = [p.name for p in project_list.projects]
+            raise ValueError(
+                f"Project '{project_name}' not found. Available projects: {', '.join(available_projects)}"
+            )
+
+        # Call API to delete project using URL encoding for special characters
+        from urllib.parse import quote
 
-    # Call API to delete project using URL encoding for special characters
-    from urllib.parse import quote
-    encoded_name = quote(target_project.name, safe='')
-    response = await call_delete(client, f"/projects/{encoded_name}")
-    status_response = ProjectStatusResponse.model_validate(response.json())
+        encoded_name = quote(target_project.name, safe="")
+        response = await call_delete(client, f"/projects/{encoded_name}")
+        status_response = ProjectStatusResponse.model_validate(response.json())
 
-    result = f"✓ {status_response.message}\n\n"
+        result = f"✓ {status_response.message}\n\n"
 
-    if status_response.old_project:
-        result += "Removed project details:\n"
-        result += f"• Name: {status_response.old_project.name}\n"
-        if hasattr(status_response.old_project, "path"):
-            result += f"• Path: {status_response.old_project.path}\n"
+        if status_response.old_project:
+            result += "Removed project details:\n"
+            result += f"• Name: {status_response.old_project.name}\n"
+            if hasattr(status_response.old_project, "path"):
+                result += f"• Path: {status_response.old_project.path}\n"
 
-    result += "Files remain on disk but project is no longer tracked by Basic Memory.\n"
-    result += "Re-add the project to access its content again.\n"
+        result += "Files remain on disk but project is no longer tracked by Basic Memory.\n"
+        result += "Re-add the project to access its content again.\n"
 
-    return add_project_metadata(result, session.get_current_project())
+        return result

basic_memory/mcp/tools/read_content.py

@@ -5,17 +5,19 @@ supporting various file types including text, images, and other binary files.
 Files are read directly without any knowledge graph processing.
 """
 
-from typing import Optional
 import base64
 import io
 
+from typing import Optional
+
 from loguru import logger
 from PIL import Image as PILImage
+from fastmcp import Context
 
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.async_client import client
+from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.tools.utils import call_get
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.memory import memory_url_path
 from basic_memory.utils import validate_project_path
 
@@ -147,11 +149,16 @@ def optimize_image(img, content_length, max_output_bytes=350000):
 
 
 @mcp.tool(description="Read a file's raw content by path or permalink")
-async def read_content(path: str, project: Optional[str] = None) -> dict:
+async def read_content(
+    path: str, project: Optional[str] = None, context: Context | None = None
+) -> dict:
     """Read a file's raw content by path or permalink.
 
     This tool provides direct access to file content in the knowledge base,
-    handling different file types appropriately:
+    handling different file types appropriately. Uses stateless architecture -
+    project parameter optional with server resolution.
+
+    Supported file types:
     - Text files (markdown, code, etc.) are returned as plain text
     - Images are automatically resized/optimized for display
     - Other binary files are returned as base64 if below size limits
@@ -161,7 +168,9 @@ async def read_content(path: str, project: Optional[str] = None) -> dict:
             - A regular file path (docs/example.md)
             - A memory URL (memory://docs/example)
             - A permalink (docs/example)
-        project: Optional project name to read from. If not provided, uses current active project.
+        project: Project name to read from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         A dictionary with the file content and metadata:
@@ -172,83 +181,91 @@ async def read_content(path: str, project: Optional[str] = None) -> dict:
 
     Examples:
         # Read a markdown file
-        result = await read_file("docs/project-specs.md")
+        result = await read_content("docs/project-specs.md")
 
         # Read an image
-        image_data = await read_file("assets/diagram.png")
+        image_data = await read_content("assets/diagram.png")
 
         # Read using memory URL
-        content = await read_file("memory://docs/architecture")
+        content = await read_content("memory://docs/architecture")
+
+        # Read configuration file
+        config = await read_content("config/settings.json")
+
+        # Explicit project specification
+        result = await read_content("docs/project-specs.md", project="my-project")
 
-        # Read from specific project
-        content = await read_content("docs/example.md", project="work-project")
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If path attempts path traversal
     """
-    logger.info("Reading file", path=path)
+    logger.info("Reading file", path=path, project=project)
 
-    active_project = get_active_project(project)
-    project_url = active_project.project_url
+    async with get_client() as client:
+        active_project = await get_active_project(client, project, context)
+        project_url = active_project.project_url
 
-    url = memory_url_path(path)
+        url = memory_url_path(path)
 
-    # Validate path to prevent path traversal attacks
-    project_path = active_project.home
-    if not validate_project_path(url, project_path):
-        logger.warning(
-            "Attempted path traversal attack blocked",
-            path=path,
-            url=url,
-            project=active_project.name,
-        )
-        return {
-            "type": "error",
-            "error": f"Path '{path}' is not allowed - paths must stay within project boundaries",
-        }
-
-    response = await call_get(client, f"{project_url}/resource/{url}")
-    content_type = response.headers.get("content-type", "application/octet-stream")
-    content_length = int(response.headers.get("content-length", 0))
-
-    logger.debug("Resource metadata", content_type=content_type, size=content_length, path=path)
-
-    # Handle text or json
-    if content_type.startswith("text/") or content_type == "application/json":
-        logger.debug("Processing text resource")
-        return {
-            "type": "text",
-            "text": response.text,
-            "content_type": content_type,
-            "encoding": "utf-8",
-        }
-
-    # Handle images
-    elif content_type.startswith("image/"):
-        logger.debug("Processing image")
-        img = PILImage.open(io.BytesIO(response.content))
-        img_bytes = optimize_image(img, content_length)
-
-        return {
-            "type": "image",
-            "source": {
-                "type": "base64",
-                "media_type": "image/jpeg",
-                "data": base64.b64encode(img_bytes).decode("utf-8"),
-            },
-        }
-
-    # Handle other file types
-    else:
-        logger.debug(f"Processing binary resource content_type {content_type}")
-        if content_length > 350000:  # pragma: no cover
-            logger.warning("Document too large for response", size=content_length)
+        # Validate path to prevent path traversal attacks
+        project_path = active_project.home
+        if not validate_project_path(url, project_path):
+            logger.warning(
+                "Attempted path traversal attack blocked",
+                path=path,
+                url=url,
+                project=active_project.name,
+            )
             return {
                 "type": "error",
-                "error": f"Document size {content_length} bytes exceeds maximum allowed size",
+                "error": f"Path '{path}' is not allowed - paths must stay within project boundaries",
+            }
+
+        response = await call_get(client, f"{project_url}/resource/{url}")
+        content_type = response.headers.get("content-type", "application/octet-stream")
+        content_length = int(response.headers.get("content-length", 0))
+
+        logger.debug("Resource metadata", content_type=content_type, size=content_length, path=path)
+
+        # Handle text or json
+        if content_type.startswith("text/") or content_type == "application/json":
+            logger.debug("Processing text resource")
+            return {
+                "type": "text",
+                "text": response.text,
+                "content_type": content_type,
+                "encoding": "utf-8",
+            }
+
+        # Handle images
+        elif content_type.startswith("image/"):
+            logger.debug("Processing image")
+            img = PILImage.open(io.BytesIO(response.content))
+            img_bytes = optimize_image(img, content_length)
+
+            return {
+                "type": "image",
+                "source": {
+                    "type": "base64",
+                    "media_type": "image/jpeg",
+                    "data": base64.b64encode(img_bytes).decode("utf-8"),
+                },
+            }
+
+        # Handle other file types
+        else:
+            logger.debug(f"Processing binary resource content_type {content_type}")
+            if content_length > 350000:  # pragma: no cover
+                logger.warning("Document too large for response", size=content_length)
+                return {
+                    "type": "error",
+                    "error": f"Document size {content_length} bytes exceeds maximum allowed size",
+                }
+            return {
+                "type": "document",
+                "source": {
+                    "type": "base64",
+                    "media_type": content_type,
+                    "data": base64.b64encode(response.content).decode("utf-8"),
+                },
             }
-        return {
-            "type": "document",
-            "source": {
-                "type": "base64",
-                "media_type": content_type,
-                "data": base64.b64encode(response.content).decode("utf-8"),
-            },
-        }