basic-memory 0.14.3__py3-none-any.whl → 0.15.0__py3-none-any.whl

basic_memory/mcp/tools/project_management.py

@@ -4,240 +4,75 @@ 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.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.
+    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.
+
+    Use this tool:
+    - At conversation start when project is unknown
+    - When user asks about available projects
+    - Before any operation requiring a project
+
+    After calling:
+    - Ask user which project to use
+    - Remember their choice for the session
 
     Returns:
-        Formatted list of projects with status indicators
+        Formatted list of projects with session management guidance
 
     Example:
         list_memory_projects()
     """
-    if ctx:  # pragma: no cover
-        await ctx.info("Listing all available projects")
+    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")
 
     # 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"
+    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"
 
-    for project in project_list.projects:
-        indicators = []
-        if project.name == current:
-            indicators.append("current")
-        if project.is_default:
-            indicators.append("default")
-
-        if indicators:
-            result += f"• {project.name} ({', '.join(indicators)})\n"
-        else:
+        for project in project_list.projects:
             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.
-
-    Args:
-        project_name: Name of the project to switch to
-
-    Returns:
-        Confirmation message with project summary
-
-    Example:
-        switch_project("work-notes")
-        switch_project("personal-journal")
-    """
-    if ctx:  # pragma: no cover
-        await ctx.info(f"Switching to project: {project_name}")
-
-    project_permalink = generate_permalink(project_name)
-    current_project = session.get_current_project()
-    try:
-        # Validate project exists by getting project list
-        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"
+        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, 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
-    response = await call_put(client, f"/projects/{project_name}/default")
-    status_response = ProjectStatusResponse.model_validate(response.json())
-
-    result = f"✓ {status_response.message}\n\n"
-    result += "Restart Basic Memory for this change to take effect:\n"
-    result += "basic-memory mcp\n"
-
-    if status_response.old_project:
-        result += f"\nPrevious default: {status_response.old_project.name}\n"
-
-    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.
 
@@ -256,8 +91,13 @@ 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}")
+    # 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(
@@ -278,17 +118,14 @@ async def create_memory_project(
         if set_default:
             result += "• Set as default project\n"
 
-    result += "\nProject is now available for use.\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
@@ -308,31 +145,42 @@ 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}")
+    # 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()
-
-    # 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."
-        )
+    if context:  # pragma: no cover
+        await context.info(f"Deleting project: {project_name}")
 
     # Get project info before deletion to validate it exists
     response = await call_get(client, "/projects/projects")
     project_list = ProjectList.model_validate(response.json())
 
-    # Check if project exists
-    project_exists = any(p.name == project_name for p in project_list.projects)
-    if not project_exists:
+    # 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
-    response = await call_delete(client, f"/projects/{project_name}")
+    # 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())
 
     result = f"✓ {status_response.message}\n\n"
@@ -346,4 +194,4 @@ async def delete_project(project_name: str, ctx: Context | None = None) -> str:
     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.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,20 +181,27 @@ 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)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
     url = memory_url_path(path)