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

basic_memory/mcp/tools/project_management.py

@@ -0,0 +1,204 @@
+"""Project management tools for Basic Memory MCP server.
+
+These tools allow users to switch between projects, list available projects,
+and manage project context during conversations.
+"""
+
+import os
+from fastmcp import Context
+
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.server import mcp
+from basic_memory.schemas.project_info import ProjectInfoRequest
+from basic_memory.telemetry import track_mcp_tool
+from basic_memory.utils import generate_permalink
+
+
+@mcp.tool("list_memory_projects")
+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 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 session management guidance
+
+    Example:
+        list_memory_projects()
+    """
+    track_mcp_tool("list_memory_projects")
+    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")
+
+        # Import here to avoid circular import
+        from basic_memory.mcp.clients import ProjectClient
+
+        # Use typed ProjectClient for API calls
+        project_client = ProjectClient(client)
+        project_list = await project_client.list_projects()
+
+        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:
+                result += f"• {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 result
+
+
+@mcp.tool("create_memory_project")
+async def create_memory_project(
+    project_name: str, project_path: str, set_default: bool = False, context: Context | None = None
+) -> str:
+    """Create a new Basic Memory project.
+
+    Creates a new project with the specified name and path. The project directory
+    will be created if it doesn't exist. Optionally sets the new project as default.
+
+    Args:
+        project_name: Name for the new project (must be unique)
+        project_path: File system path where the project will be stored
+        set_default: Whether to set this project as the default (optional, defaults to False)
+
+    Returns:
+        Confirmation message with project details
+
+    Example:
+        create_memory_project("my-research", "~/Documents/research")
+        create_memory_project("work-notes", "/home/user/work", set_default=True)
+    """
+    track_mcp_tool("create_memory_project")
+    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
+        )
+
+        # Import here to avoid circular import
+        from basic_memory.mcp.clients import ProjectClient
+
+        # Use typed ProjectClient for API calls
+        project_client = ProjectClient(client)
+        status_response = await project_client.create_project(project_request.model_dump())
+
+        result = f"✓ {status_response.message}\n\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"
+
+            if set_default:
+                result += "• Set as default project\n"
+
+        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 result
+
+
+@mcp.tool()
+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
+    the actual files on disk - only removes the project from Basic Memory's
+    configuration and database records.
+
+    Args:
+        project_name: Name of the project to delete
+
+    Returns:
+        Confirmation message about project deletion
+
+    Example:
+        delete_project("old-project")
+
+    Warning:
+        This action cannot be undone. The project will need to be re-added
+        to access its content through Basic Memory again.
+    """
+    track_mcp_tool("delete_project")
+    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}\"`"
+
+        if context:  # pragma: no cover
+            await context.info(f"Deleting project: {project_name}")
+
+        # Import here to avoid circular import
+        from basic_memory.mcp.clients import ProjectClient
+
+        # Use typed ProjectClient for API calls
+        project_client = ProjectClient(client)
+
+        # Get project info before deletion to validate it exists
+        project_list = await project_client.list_projects()
+
+        # Find the project by permalink (derived from name).
+        # Note: The API response uses `ProjectItem` which derives `permalink` from `name`,
+        # so a separate case-insensitive name match would be redundant here.
+        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
+
+        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)}"
+            )
+
+        # Delete project using project external_id
+        status_response = await project_client.delete_project(target_project.external_id)
+
+        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"
+
+        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 result

basic_memory/mcp/tools/read_content.py

@@ -0,0 +1,281 @@
+"""File reading tool for Basic Memory MCP server.
+
+This module provides tools for reading raw file content directly,
+supporting various file types including text, images, and other binary files.
+Files are read directly without any knowledge graph processing.
+"""
+
+import base64
+import io
+
+from typing import Optional
+
+from loguru import logger
+from PIL import Image as PILImage
+from fastmcp import Context
+from mcp.server.fastmcp.exceptions import ToolError
+
+from basic_memory.mcp.project_context import get_active_project
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.tools.utils import call_get, resolve_entity_id
+from basic_memory.schemas.memory import memory_url_path
+from basic_memory.telemetry import track_mcp_tool
+from basic_memory.utils import validate_project_path
+
+
+def calculate_target_params(content_length):
+    """Calculate initial quality and size based on input file size"""
+    target_size = 350000  # Reduced target for more safety margin
+    ratio = content_length / target_size
+
+    logger.debug(
+        "Calculating target parameters",
+        content_length=content_length,
+        ratio=ratio,
+        target_size=target_size,
+    )
+
+    if ratio > 4:
+        # Very large images - start very aggressive
+        return 50, 600  # Lower initial quality and size
+    elif ratio > 2:
+        return 60, 800
+    else:
+        return 70, 1000
+
+
+def resize_image(img, max_size):
+    """Resize image maintaining aspect ratio"""
+    original_dimensions = {"width": img.width, "height": img.height}
+
+    if img.width > max_size or img.height > max_size:
+        ratio = min(max_size / img.width, max_size / img.height)
+        new_size = (int(img.width * ratio), int(img.height * ratio))
+        logger.debug("Resizing image", original=original_dimensions, target=new_size, ratio=ratio)
+        return img.resize(new_size, PILImage.Resampling.LANCZOS)
+
+    logger.debug("No resize needed", dimensions=original_dimensions)
+    return img
+
+
+def optimize_image(img, content_length, max_output_bytes=350000):
+    """Iteratively optimize image with aggressive size reduction"""
+    stats = {
+        "dimensions": {"width": img.width, "height": img.height},
+        "mode": img.mode,
+        "estimated_memory": (img.width * img.height * len(img.getbands())),
+    }
+
+    initial_quality, initial_size = calculate_target_params(content_length)
+
+    logger.debug(
+        "Starting optimization",
+        image_stats=stats,
+        content_length=content_length,
+        initial_quality=initial_quality,
+        initial_size=initial_size,
+        max_output_bytes=max_output_bytes,
+    )
+
+    quality = initial_quality
+    size = initial_size
+
+    # Convert to RGB if needed
+    if img.mode in ("RGBA", "LA") or (img.mode == "P" and "transparency" in img.info):
+        img = img.convert("RGB")
+        logger.debug("Converted to RGB mode")
+
+    iteration = 0
+    min_size = 300  # Absolute minimum size
+    min_quality = 20  # Absolute minimum quality
+
+    while True:
+        iteration += 1
+        buf = io.BytesIO()
+        resized = resize_image(img, size)
+
+        resized.save(
+            buf,
+            format="JPEG",
+            quality=quality,
+            optimize=True,
+            progressive=True,
+            subsampling="4:2:0",
+        )
+
+        output_size = buf.getbuffer().nbytes
+        reduction_ratio = output_size / content_length
+
+        logger.debug(
+            "Optimization attempt",
+            iteration=iteration,
+            quality=quality,
+            size=size,
+            output_bytes=output_size,
+            target_bytes=max_output_bytes,
+            reduction_ratio=f"{reduction_ratio:.2f}",
+        )
+
+        if output_size < max_output_bytes:
+            logger.info(
+                "Image optimization complete",
+                final_size=output_size,
+                quality=quality,
+                dimensions={"width": resized.width, "height": resized.height},
+                reduction_ratio=f"{reduction_ratio:.2f}",
+            )
+            return buf.getvalue()
+
+        # Very aggressive reduction for large files
+        if content_length > 2000000:  # 2MB+   # pragma: no cover
+            quality = max(min_quality, quality - 20)
+            size = max(min_size, int(size * 0.6))
+        elif content_length > 1000000:  # 1MB+ # pragma: no cover
+            quality = max(min_quality, quality - 15)
+            size = max(min_size, int(size * 0.7))
+        else:
+            quality = max(min_quality, quality - 10)  # pragma: no cover
+            size = max(min_size, int(size * 0.8))  # pragma: no cover
+
+        logger.debug("Reducing parameters", new_quality=quality, new_size=size)  # pragma: no cover
+
+        # If we've hit minimum values and still too big
+        if quality <= min_quality and size <= min_size:  # pragma: no cover
+            logger.warning(
+                "Reached minimum parameters",
+                final_size=output_size,
+                over_limit_by=output_size - max_output_bytes,
+            )
+            return buf.getvalue()
+
+
+@mcp.tool(description="Read a file's raw content by path or permalink")
+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. 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
+
+    Args:
+        path: The path or permalink to the file. Can be:
+            - A regular file path (docs/example.md)
+            - A memory URL (memory://docs/example)
+            - A permalink (docs/example)
+        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:
+        - For text: {"type": "text", "text": "content", "content_type": "text/markdown", "encoding": "utf-8"}
+        - For images: {"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": "base64_data"}}
+        - For other files: {"type": "document", "source": {"type": "base64", "media_type": "content_type", "data": "base64_data"}}
+        - For errors: {"type": "error", "error": "error message"}
+
+    Examples:
+        # Read a markdown file
+        result = await read_content("docs/project-specs.md")
+
+        # Read an image
+        image_data = await read_content("assets/diagram.png")
+
+        # Read using memory URL
+        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")
+
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If path attempts path traversal
+    """
+    track_mcp_tool("read_content")
+    logger.info("Reading file", path=path, project=project)
+
+    async with get_client() as client:
+        active_project = await get_active_project(client, project, context)
+
+        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",
+            }
+
+        # Resolve path to entity ID
+        try:
+            entity_id = await resolve_entity_id(client, active_project.external_id, url)
+        except ToolError:
+            # Convert resolution errors to "Resource not found" for consistency
+            raise ToolError(f"Resource not found: {url}")
+
+        # Call the v2 resource endpoint
+        response = await call_get(client, f"/v2/projects/{active_project.external_id}/resource/{entity_id}")
+        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"),
+                },
+            }