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

basic_memory/mcp/tools/canvas.py

@@ -7,11 +7,12 @@ import json
 from typing import Dict, List, Any, Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import 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_put
-from basic_memory.mcp.project_session import get_active_project
 
 
 @mcp.tool(
@@ -23,21 +24,28 @@ async def canvas(
     title: str,
     folder: str,
     project: Optional[str] = None,
+    context: Context | None = None,
 ) -> str:
     """Create an Obsidian canvas file with the provided nodes and edges.
 
     This tool creates a .canvas file compatible with Obsidian's Canvas feature,
     allowing visualization of relationships between concepts or documents.
 
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
     For the full JSON Canvas 1.0 specification, see the 'spec://canvas' resource.
 
     Args:
+        project: Project name to create canvas in. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         nodes: List of node objects following JSON Canvas 1.0 spec
         edges: List of edge objects following JSON Canvas 1.0 spec
         title: The title of the canvas (will be saved as title.canvas)
         folder: Folder path relative to project root where the canvas should be saved.
                 Use forward slashes (/) as separators. Examples: "diagrams", "projects/2025", "visual/maps"
-        project: Optional project name to create canvas in. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         A summary of the created canvas file
@@ -77,13 +85,16 @@ async def canvas(
     ```
 
     Examples:
-        # Create canvas in current project
-        canvas(nodes=[...], edges=[...], title="My Canvas", folder="diagrams")
+        # Create canvas in project
+        canvas("my-project", nodes=[...], edges=[...], title="My Canvas", folder="diagrams")
+
+        # Create canvas in work project
+        canvas("work-project", nodes=[...], edges=[...], title="Process Flow", folder="visual/maps")
 
-        # Create canvas in specific project
-        canvas(nodes=[...], edges=[...], title="My Canvas", folder="diagrams", project="work-project")
+    Raises:
+        ToolError: If project doesn't exist or folder path is invalid
     """
-    active_project = get_active_project(project)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
     # Ensure path has .canvas extension
@@ -97,7 +108,7 @@ async def canvas(
     canvas_json = json.dumps(canvas_data, indent=2)
 
     # Write the file using the resource API
-    logger.info(f"Creating canvas file: {file_path}")
+    logger.info(f"Creating canvas file: {file_path} in project {project}")
     response = await call_put(client, f"{project_url}/resource/{file_path}", json=canvas_json)
 
     # Parse response

basic_memory/mcp/tools/chatgpt_tools.py

@@ -0,0 +1,178 @@
+"""ChatGPT-compatible MCP tools for Basic Memory.
+
+These adapters expose Basic Memory's search/fetch functionality using the exact
+tool names and response structure OpenAI's MCP clients expect: each call returns
+a list containing a single `{"type": "text", "text": "{...json...}"}` item.
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+from loguru import logger
+from fastmcp import Context
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.search import search_notes
+from basic_memory.mcp.tools.read_note import read_note
+from basic_memory.schemas.search import SearchResponse
+
+
+def _format_search_results_for_chatgpt(results: SearchResponse) -> List[Dict[str, Any]]:
+    """Format search results according to ChatGPT's expected schema.
+
+    Returns a list of result objects with id, title, and url fields.
+    """
+    formatted_results = []
+
+    for result in results.results:
+        formatted_result = {
+            "id": result.permalink or f"doc-{len(formatted_results)}",
+            "title": result.title if result.title and result.title.strip() else "Untitled",
+            "url": result.permalink or "",
+        }
+        formatted_results.append(formatted_result)
+
+    return formatted_results
+
+
+def _format_document_for_chatgpt(
+    content: str, identifier: str, title: Optional[str] = None
+) -> Dict[str, Any]:
+    """Format document content according to ChatGPT's expected schema.
+
+    Returns a document object with id, title, text, url, and metadata fields.
+    """
+    # Extract title from markdown content if not provided
+    if not title and isinstance(content, str):
+        lines = content.split("\n")
+        if lines and lines[0].startswith("# "):
+            title = lines[0][2:].strip()
+        else:
+            title = identifier.split("/")[-1].replace("-", " ").title()
+
+    # Ensure title is never None
+    if not title:
+        title = "Untitled Document"
+
+    # Handle error cases
+    if isinstance(content, str) and content.startswith("# Note Not Found"):
+        return {
+            "id": identifier,
+            "title": title or "Document Not Found",
+            "text": content,
+            "url": identifier,
+            "metadata": {"error": "Document not found"},
+        }
+
+    return {
+        "id": identifier,
+        "title": title or "Untitled Document",
+        "text": content,
+        "url": identifier,
+        "metadata": {"format": "markdown"},
+    }
+
+
+@mcp.tool(description="Search for content across the knowledge base")
+async def search(
+    query: str,
+    context: Context | None = None,
+) -> List[Dict[str, Any]]:
+    """ChatGPT/OpenAI MCP search adapter returning a single text content item.
+
+    Args:
+        query: Search query (full-text syntax supported by `search_notes`)
+        context: Optional FastMCP context passed through for auth/session data
+
+    Returns:
+        List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
+        where the JSON body contains `results`, `total_count`, and echo of `query`.
+    """
+    logger.info(f"ChatGPT search request: query='{query}'")
+
+    try:
+        # Call underlying search_notes with sensible defaults for ChatGPT
+        results = await search_notes.fn(
+            query=query,
+            project=None,  # Let project resolution happen automatically
+            page=1,
+            page_size=10,  # Reasonable default for ChatGPT consumption
+            search_type="text",  # Default to full-text search
+            context=context,
+        )
+
+        # Handle string error responses from search_notes
+        if isinstance(results, str):
+            logger.warning(f"Search failed with error: {results[:100]}...")
+            search_results = {
+                "results": [],
+                "error": "Search failed",
+                "error_details": results[:500],  # Truncate long error messages
+            }
+        else:
+            # Format successful results for ChatGPT
+            formatted_results = _format_search_results_for_chatgpt(results)
+            search_results = {
+                "results": formatted_results,
+                "total_count": len(results.results),  # Use actual count from results
+                "query": query,
+            }
+            logger.info(f"Search completed: {len(formatted_results)} results returned")
+
+        # Return in MCP content array format as required by OpenAI
+        return [{"type": "text", "text": json.dumps(search_results, ensure_ascii=False)}]
+
+    except Exception as e:
+        logger.error(f"ChatGPT search failed for query '{query}': {e}")
+        error_results = {
+            "results": [],
+            "error": "Internal search error",
+            "error_message": str(e)[:200],
+        }
+        return [{"type": "text", "text": json.dumps(error_results, ensure_ascii=False)}]
+
+
+@mcp.tool(description="Fetch the full contents of a search result document")
+async def fetch(
+    id: str,
+    context: Context | None = None,
+) -> List[Dict[str, Any]]:
+    """ChatGPT/OpenAI MCP fetch adapter returning a single text content item.
+
+    Args:
+        id: Document identifier (permalink, title, or memory URL)
+        context: Optional FastMCP context passed through for auth/session data
+
+    Returns:
+        List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
+        where the JSON body includes `id`, `title`, `text`, `url`, and metadata.
+    """
+    logger.info(f"ChatGPT fetch request: id='{id}'")
+
+    try:
+        # Call underlying read_note function
+        content = await read_note.fn(
+            identifier=id,
+            project=None,  # Let project resolution happen automatically
+            page=1,
+            page_size=10,  # Default pagination
+            context=context,
+        )
+
+        # Format the document for ChatGPT
+        document = _format_document_for_chatgpt(content, id)
+
+        logger.info(f"Fetch completed: id='{id}', content_length={len(document.get('text', ''))}")
+
+        # Return in MCP content array format as required by OpenAI
+        return [{"type": "text", "text": json.dumps(document, ensure_ascii=False)}]
+
+    except Exception as e:
+        logger.error(f"ChatGPT fetch failed for id '{id}': {e}")
+        error_document = {
+            "id": id,
+            "title": "Fetch Error",
+            "text": f"Failed to fetch document: {str(e)[:200]}",
+            "url": id,
+            "metadata": {"error": "Fetch failed"},
+        }
+        return [{"type": "text", "text": json.dumps(error_document, ensure_ascii=False)}]

basic_memory/mcp/tools/delete_note.py

@@ -2,15 +2,16 @@ from textwrap import dedent
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.tools.utils import call_delete
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.async_client import client
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas import DeleteEntitiesResponse
 
 
-def _format_delete_error_response(error_message: str, identifier: str) -> str:
+def _format_delete_error_response(project: str, error_message: str, identifier: str) -> str:
     """Format helpful error responses for delete failures that guide users to successful deletions."""
 
     # Note not found errors
@@ -24,7 +25,7 @@ def _format_delete_error_response(error_message: str, identifier: str) -> str:
         return dedent(f"""
             # Delete Failed - Note Not Found
 
-            The note '{identifier}' could not be found for deletion.
+            The note '{identifier}' could not be found for deletion in {project}.
 
             ## This might mean:
             1. **Already deleted**: The note may have been deleted previously
@@ -32,21 +33,21 @@ def _format_delete_error_response(error_message: str, identifier: str) -> str:
             3. **Different project**: The note might be in a different project
 
             ## How to verify:
-            1. **Search for the note**: Use `search_notes("{search_term}")` to find it
+            1. **Search for the note**: Use `search_notes("{project}", "{search_term}")` to find it
             2. **Try different formats**:
                - If you used a permalink like "folder/note-title", try just the title: "{title_format}"
                - If you used a title, try the permalink format: "{permalink_format}"
 
             3. **Check if already deleted**: Use `list_directory("/")` to see what notes exist
-            4. **Check current project**: Use `get_current_project()` to verify you're in the right project
+            4. **List notes in project**: Use `list_directory("/")` to see what notes exist in the current project
 
             ## If the note actually exists:
             ```
             # First, find the correct identifier:
-            search_notes("{identifier}")
+            search_notes("{project}", "{identifier}")
 
             # Then delete using the correct identifier:
-            delete_note("correct-identifier-from-search")
+            delete_note("{project}", "correct-identifier-from-search")
             ```
 
             ## If you want to delete multiple similar notes:
@@ -69,12 +70,12 @@ You don't have permission to delete '{identifier}': {error_message}
 3. **Project access**: Ensure you're in the correct project with proper permissions
 
 ## Alternative actions:
-- Check current project: `get_current_project()`
-- Switch to correct project: `switch_project("project-name")`
-- Verify note exists first: `read_note("{identifier}")`
+- List available projects: `list_memory_projects()`
+- Specify the correct project: `delete_note("{identifier}", project="project-name")`
+- Verify note exists first: `read_note("{identifier}", project="project-name")`
 
 ## If you have read-only access:
-Send a message to support@basicmachines.co to request deletion, or ask someone with write access to delete the note."""
+Ask someone with write access to delete the note."""
 
     # Server/filesystem errors
     if (
@@ -92,8 +93,7 @@ A system error occurred while deleting '{identifier}': {error_message}
 3. **Check disk space**: Ensure the system has adequate storage
 
 ## Troubleshooting:
-- Verify note exists: `read_note("{identifier}")`
-- Check project status: `get_current_project()`
+- Verify note exists: `read_note("{project}","{identifier}")`
 - Try again in a few moments
 
 ## If problem persists:
@@ -112,7 +112,7 @@ A database error occurred while deleting '{identifier}': {error_message}
 
 ## Steps to resolve:
 1. **Try again**: Wait a moment and retry the deletion
-2. **Check note status**: `read_note("{identifier}")` to see current state
+2. **Check note status**: `read_note("{project}","{identifier}")` to see current state
 3. **Manual verification**: Use `list_directory()` to see if file still exists
 
 ## If the note appears gone but database shows it exists:
@@ -124,7 +124,7 @@ Send a message to support@basicmachines.co - a manual database cleanup may be ne
 Error deleting note '{identifier}': {error_message}
 
 ## General troubleshooting:
-1. **Verify the note exists**: `read_note("{identifier}")` or `search_notes("{identifier}")`
+1. **Verify the note exists**: `read_note("{project}", "{identifier}")` or `search_notes("{project}", "{identifier}")`
 2. **Check permissions**: Ensure you can edit/delete files in this project
 3. **Try again**: The error might be temporary
 4. **Check project**: Make sure you're in the correct project
@@ -132,46 +132,77 @@ Error deleting note '{identifier}': {error_message}
 ## Step-by-step approach:
 ```
 # 1. Confirm note exists and get correct identifier
-search_notes("{identifier}")
+search_notes("{project}", "{identifier}")
 
 # 2. Read the note to verify access
-read_note("correct-identifier-from-search")
+read_note("{project}", "correct-identifier-from-search")
 
 # 3. Try deletion with correct identifier
-delete_note("correct-identifier-from-search")
+delete_note("{project}", "correct-identifier-from-search")
 ```
 
 ## Alternative approaches:
-- Check what notes exist: `list_directory("/")`
-- Verify current project: `get_current_project()`
-- Switch projects if needed: `switch_project("correct-project")`
+- Check what notes exist: `list_directory("{project}", "/")`
 
 ## Need help?
-If the note should be deleted but the operation keeps failing, send a message to support@basicmachines.co."""
+If the note should be deleted but the operation keeps failing, send a message to support@basicmemory.com."""
 
 
 @mcp.tool(description="Delete a note by title or permalink")
-async def delete_note(identifier: str, project: Optional[str] = None) -> bool | str:
+async def delete_note(
+    identifier: str, project: Optional[str] = None, context: Context | None = None
+) -> bool | str:
     """Delete a note from the knowledge base.
 
+    Permanently removes a note from the specified project. The note is identified
+    by title or permalink. If the note doesn't exist, the operation returns False
+    without error. If deletion fails due to other issues, helpful error messages are provided.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
     Args:
-        identifier: Note title or permalink
-        project: Optional project name to delete from. If not provided, uses current active project.
+        project: Project name to delete from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        identifier: Note title or permalink to delete
+                   Can be a title like "Meeting Notes" or permalink like "notes/meeting-notes"
+        context: Optional FastMCP context for performance caching.
 
     Returns:
-        True if note was deleted, False otherwise
+        True if note was successfully deleted, False if note was not found.
+        On errors, returns a formatted string with helpful troubleshooting guidance.
 
     Examples:
         # Delete by title
-        delete_note("Meeting Notes: Project Planning")
+        delete_note("my-project", "Meeting Notes: Project Planning")
 
         # Delete by permalink
-        delete_note("notes/project-planning")
+        delete_note("work-docs", "notes/project-planning")
+
+        # Delete with exact path
+        delete_note("research", "experiments/ml-model-results")
+
+        # Common usage pattern
+        if delete_note("my-project", "old-draft"):
+            print("Note deleted successfully")
+        else:
+            print("Note not found or already deleted")
+
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If identifier attempts path traversal
+
+    Warning:
+        This operation is permanent and cannot be undone. The note file
+        will be removed from the filesystem and all references will be lost.
 
-        # Delete from specific project
-        delete_note("notes/project-planning", project="work-project")
+    Note:
+        If the note is not found, this function provides helpful error messages
+        with suggestions for finding the correct identifier, including search
+        commands and alternative formats to try.
     """
-    active_project = get_active_project(project)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
     try:
@@ -179,13 +210,15 @@ async def delete_note(identifier: str, project: Optional[str] = None) -> bool |
         result = DeleteEntitiesResponse.model_validate(response.json())
 
         if result.deleted:
-            logger.info(f"Successfully deleted note: {identifier}")
+            logger.info(
+                f"Successfully deleted note: {identifier} in project: {active_project.name}"
+            )
             return True
         else:
             logger.warning(f"Delete operation completed but note was not deleted: {identifier}")
             return False
 
     except Exception as e:  # pragma: no cover
-        logger.error(f"Delete failed for '{identifier}': {e}")
+        logger.error(f"Delete failed for '{identifier}': {e}, project: {active_project.name}")
         # Return formatted error message for better user experience
-        return _format_delete_error_response(str(e), identifier)
+        return _format_delete_error_response(active_project.name, str(e), identifier)