fix(mcp): make multi-project search opt-in (#807)

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/mcp/project_context.py

@@ -439,19 +439,16 @@ def _canonical_memory_path_for_workspace(
     workspace_type: str,
     project_permalink: str,
     remainder: str,
-    include_project: bool,
 ) -> str:
     """Return the stored canonical path for a workspace-qualified memory URL."""
     normalized_remainder = remainder.strip("/")
-    if workspace_type == "organization":
-        prefix = f"{generate_permalink(workspace_slug)}/{project_permalink}"
-    elif workspace_type == "personal":
-        prefix = project_permalink if include_project else ""
-    else:
+    if workspace_type not in {"organization", "personal"}:
         raise ValueError(f"Unsupported workspace_type for memory URL routing: {workspace_type}")
 
-    if not prefix:
-        return normalized_remainder
+    # Trigger: a caller supplied a workspace-qualified memory URL.
+    # Why: the first two path segments are the global route, even for Personal.
+    # Outcome: lookups preserve the complete workspace/project canonical permalink.
+    prefix = f"{generate_permalink(workspace_slug)}/{project_permalink}"
     if not normalized_remainder:
         return prefix
     return f"{prefix}/{normalized_remainder}"
@@ -483,7 +480,6 @@ def _canonical_memory_path_for_active_route(
             workspace_type=workspace_context.workspace_type,
             project_permalink=active_project.permalink,
             remainder=workspace_remainder,
-            include_project=include_project,
         )
 
     if cached_workspace is not None:
@@ -492,7 +488,6 @@ def _canonical_memory_path_for_active_route(
             workspace_type=cached_workspace.workspace_type,
             project_permalink=active_project.permalink,
             remainder=workspace_remainder,
-            include_project=include_project,
         )
 
     if not include_project:
@@ -582,7 +577,6 @@ async def resolve_workspace_qualified_memory_url(
         workspace_type=entry.workspace.workspace_type,
         project_permalink=entry.project.permalink,
         remainder=remainder,
-        include_project=ConfigManager().config.permalinks_include_project,
     )
     return WorkspaceMemoryUrlResolution(entry=entry, canonical_path=canonical_path)
 
@@ -1130,7 +1124,6 @@ async def resolve_project_and_path(
                     workspace_type=cached_workspace.workspace_type,
                     project_permalink=cached_project.permalink,
                     remainder=remainder,
-                    include_project=bool(include_project),
                 )
                 return cached_project, resolved_path, True
 
@@ -1153,7 +1146,6 @@ async def resolve_project_and_path(
                     workspace_type=workspace_context.workspace_type,
                     project_permalink=project_permalink,
                     remainder=remainder,
-                    include_project=bool(include_project),
                 )
                 return active_project, resolved_path, True
 

src/basic_memory/mcp/tools/chatgpt_tools.py

@@ -6,7 +6,7 @@
 """
 
 import json
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, cast
 
 from fastmcp import Context
 from loguru import logger
@@ -17,18 +17,30 @@
 from basic_memory.schemas.search import SearchResponse, SearchResult
 
 
+def _identifier_for_read_note(identifier: str) -> str:
+    """Convert ChatGPT result ids into routable Basic Memory identifiers."""
+    stripped = identifier.strip()
+    if stripped.startswith("memory://") or "/" not in stripped:
+        return identifier
+    return f"memory://{stripped}"
+
+
 def _format_search_results_for_chatgpt(
-    results: SearchResponse | list[SearchResult] | list[dict[str, Any]] | dict[str, Any],
+    results: SearchResponse | list[SearchResult | dict[str, Any]] | dict[str, Any],
 ) -> 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.
     """
     if isinstance(results, SearchResponse):
-        raw_results: list[SearchResult] | list[dict[str, Any]] = results.results
+        raw_results: list[SearchResult | dict[str, Any]] = list(results.results)
     elif isinstance(results, dict):
         nested_results = results.get("results")
-        raw_results = nested_results if isinstance(nested_results, list) else []
+        raw_results = (
+            cast(list[SearchResult | dict[str, Any]], nested_results)
+            if isinstance(nested_results, list)
+            else []
+        )
     else:
         raw_results = results
 
@@ -113,8 +125,7 @@ async def search(
     logger.info(f"ChatGPT search request: query='{query}'")
 
     try:
-        # Let search_notes resolve the default project via get_project_client(),
-        # which works in both local mode (ConfigManager) and cloud mode (database).
+        # Keep this adapter tiny: the real search behavior lives in search_notes.
         results = await search_notes(
             query=query,
             page=1,
@@ -123,24 +134,24 @@ async def 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
-            raw_results = results.get("results", []) if isinstance(results, dict) else []
-            formatted_results = _format_search_results_for_chatgpt(raw_results)
-            search_results = {
-                "results": formatted_results,
-                "total_count": len(raw_results),  # Use actual count from results
-                "query": query,
-            }
-            logger.info(f"Search completed: {len(formatted_results)} results returned")
+            return [{"type": "text", "text": json.dumps(search_results, ensure_ascii=False)}]
+
+        raw_results = results.get("results", []) if isinstance(results, dict) else []
+
+        formatted_results = _format_search_results_for_chatgpt(raw_results)
+        search_results = {
+            "results": formatted_results,
+            "total_count": len(raw_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)}]
@@ -180,7 +191,7 @@ async def fetch(
         # which works in both local mode (ConfigManager) and cloud mode (database).
         content = str(
             await read_note(
-                identifier=id,
+                identifier=_identifier_for_read_note(id),
                 context=context,
             )
         )

src/basic_memory/mcp/tools/read_note.py

@@ -18,7 +18,8 @@
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.search import search_notes
 from basic_memory.schemas.memory import memory_url_path
-from basic_memory.utils import validate_project_path
+from basic_memory.utils import generate_permalink, validate_project_path
+from basic_memory.workspace_context import current_workspace_permalink_context
 
 
 def _is_exact_title_match(identifier: str, title: str) -> bool:
@@ -277,24 +278,51 @@ def _result_file_path(item: dict[str, object]) -> Optional[str]:
                 value = item.get("file_path")
                 return str(value) if value else None
 
-            try:
-                # Try to resolve identifier to entity ID
-                entity_id = await knowledge_client.resolve_entity(entity_path, strict=True)
+            def _legacy_workspace_unqualified_path(path: str) -> str | None:
+                workspace_context = current_workspace_permalink_context()
+                if workspace_context is None:
+                    return None
+
+                workspace_prefix = generate_permalink(workspace_context.workspace_slug)
+                project_prefix = active_project.permalink
+                qualified_prefix = f"{workspace_prefix}/{project_prefix}"
+                normalized_path = path.strip("/")
+                if normalized_path == qualified_prefix:
+                    return project_prefix
+                if normalized_path.startswith(f"{qualified_prefix}/"):
+                    return f"{project_prefix}/{normalized_path.removeprefix(f'{qualified_prefix}/')}"
+                return None
+
+            direct_lookup_paths = [entity_path]
+            legacy_path = _legacy_workspace_unqualified_path(entity_path)
+            if legacy_path and legacy_path not in direct_lookup_paths:
+                # Trigger: existing cloud rows may still use project-prefixed permalinks.
+                # Why: new workspace-qualified IDs should read old notes without a re-sync.
+                # Outcome: try the legacy path after the canonical workspace path misses.
+                direct_lookup_paths.append(legacy_path)
+
+            for direct_lookup_path in direct_lookup_paths:
+                try:
+                    # Try to resolve identifier to entity ID
+                    entity_id = await knowledge_client.resolve_entity(
+                        direct_lookup_path, strict=True
+                    )
 
-                # Fetch content using entity ID
-                response = await resource_client.read(entity_id)
+                    # Fetch content using entity ID
+                    response = await resource_client.read(entity_id)
 
-                # If successful, return the content
-                if response.status_code == 200:
-                    logger.info(
-                        "Returning read_note result from resource: {path}", path=entity_path
-                    )
-                    if output_format == "json":
-                        return await _read_json_payload(entity_id)
-                    return response.text
-            except Exception as e:  # pragma: no cover
-                logger.info(f"Direct lookup failed for '{entity_path}': {e}")
-                # Continue to fallback methods
+                    # If successful, return the content
+                    if response.status_code == 200:
+                        logger.info(
+                            "Returning read_note result from resource: {path}",
+                            path=direct_lookup_path,
+                        )
+                        if output_format == "json":
+                            return await _read_json_payload(entity_id)
+                        return response.text
+                except Exception as e:  # pragma: no cover
+                    logger.info(f"Direct lookup failed for '{direct_lookup_path}': {e}")
+                    # Continue to alternate direct lookup paths, then fallback methods
 
             # Fallback 1: Try title search via API
             logger.info(f"Search title for: {identifier}")