Resolve projects by external_id, remove workspace from MCP tools

Workspaces are an implementation detail that should not be exposed to MCP
tool callers. This change:

- 🔑 Adds external_id (UUID) lookup to project resolution so callers can
  reference projects unambiguously without knowing which workspace owns them
- 🗑️ Removes the `workspace` parameter from all 15 MCP tool signatures
- 🔄 Falls back to the default workspace when a project name exists in
  multiple workspaces (instead of erroring)
- 📋 Includes external_id in list_memory_projects output so LLMs can
  discover and use project UUIDs

Closes basicmachines-co/basic-memory-cloud#673

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: phernandez

src/basic_memory/mcp/project_context.py

@@ -10,8 +10,9 @@
 
 import asyncio
 from contextlib import asynccontextmanager
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import AsyncIterator, Awaitable, Callable, Optional, List, Tuple, cast
+from uuid import UUID
 
 from httpx import AsyncClient
 from httpx._types import (
@@ -52,11 +53,12 @@ def qualified_name(self) -> str:
 
 @dataclass(frozen=True)
 class WorkspaceProjectIndex:
-    """Session-local cloud project lookup index keyed by project permalink."""
+    """Session-local cloud project lookup index keyed by project permalink and external_id."""
 
     workspaces: tuple[WorkspaceInfo, ...]
     entries: tuple[WorkspaceProjectEntry, ...]
     entries_by_permalink: dict[str, tuple[WorkspaceProjectEntry, ...]]
+    entries_by_external_id: dict[str, WorkspaceProjectEntry] = field(default_factory=dict)
     failed_workspaces: tuple[WorkspaceInfo, ...] = ()
 
 
@@ -351,10 +353,12 @@ def _build_workspace_project_index(
     *,
     failed_workspaces: tuple[WorkspaceInfo, ...] = (),
 ) -> WorkspaceProjectIndex:
-    """Build the permalink lookup table for workspace-project entries."""
+    """Build the permalink and external_id lookup tables for workspace-project entries."""
     grouped: dict[str, list[WorkspaceProjectEntry]] = {}
+    by_external_id: dict[str, WorkspaceProjectEntry] = {}
     for entry in entries:
         grouped.setdefault(entry.project.permalink, []).append(entry)
+        by_external_id[entry.project.external_id] = entry
 
     return WorkspaceProjectIndex(
         workspaces=workspaces,
@@ -363,6 +367,7 @@ def _build_workspace_project_index(
             permalink: tuple(items)
             for permalink, items in sorted(grouped.items(), key=lambda item: item[0])
         },
+        entries_by_external_id=by_external_id,
         failed_workspaces=failed_workspaces,
     )
 
@@ -549,8 +554,18 @@ async def resolve_workspace_project_identifier(
     project: str,
     context: Optional[Context] = None,
 ) -> WorkspaceProjectEntry:
-    """Resolve an unqualified or ``<workspace>/<project>`` cloud project identifier."""
+    """Resolve a project by external_id (UUID), qualified name, or unqualified name."""
     index = await _ensure_workspace_project_index(context=context)
+
+    # Fast path: direct lookup by external_id when the identifier is a UUID
+    try:
+        UUID(project)
+        entry = index.entries_by_external_id.get(project)
+        if entry:
+            return entry
+    except ValueError:
+        pass
+
     workspace_slug, project_identifier = _split_qualified_project_identifier(project)
     project_permalink = generate_permalink(project_identifier)
 
@@ -617,6 +632,13 @@ async def resolve_workspace_project_identifier(
             return cached_matches[0]
 
     if len(matches) > 1:
+        # Prefer the project in the default workspace when name is ambiguous
+        default_match = next(
+            (entry for entry in matches if entry.workspace.is_default), None
+        )
+        if default_match:
+            return default_match
+
         choices = _format_qualified_choices(matches)
         details = "\n".join(
             f"- {entry.workspace.name} ({entry.workspace.slug}): {entry.qualified_name}"
@@ -956,7 +978,6 @@ def detect_project_from_url_prefix(identifier: str, config: BasicMemoryConfig) -
 @asynccontextmanager
 async def get_project_client(
     project: Optional[str] = None,
-    workspace: Optional[str] = None,
     context: Optional[Context] = None,
 ) -> AsyncIterator[Tuple[AsyncClient, ProjectItem]]:
     """Resolve project, create correctly-routed client, and validate project.
@@ -972,15 +993,8 @@ async def get_project_client(
     3. Cloud project mode → resolve project through workspace/project index
     4. Otherwise → local ASGI client
 
-    Workspace resolution priority (when cloud routing):
-    1. Explicit ``workspace`` parameter
-    2. Per-project ``workspace_id`` from config
-    3. Qualified project identifier (``<workspace-slug>/<project>``)
-    4. Workspace/project index lookup with collision detection
-
     Args:
-        project: Optional explicit project parameter
-        workspace: Optional cloud workspace selector (tenant_id or unique name)
+        project: Optional explicit project parameter (name, permalink, or external_id UUID)
         context: Optional FastMCP context for caching
 
     Yields:
@@ -1050,37 +1064,14 @@ async def get_project_client(
     project_entry = config.projects.get(resolved_project)
     project_mode = config.get_project_mode(resolved_project)
 
-    # Trigger: workspace provided for a local project (without explicit --cloud)
-    # Why: workspace selection is a cloud routing concern only
-    # Outcome: fail fast with a deterministic guidance message
-    if (
-        not factory_mode
-        and project_mode != ProjectMode.CLOUD
-        and workspace is not None
-        and not _explicit_routing()
-    ):
-        raise ValueError(
-            f"Workspace '{workspace}' cannot be used with local project '{resolved_project}'. "
-            "Workspace selection is only supported for cloud-mode projects."
-        )
-
     if factory_mode or project_mode == ProjectMode.CLOUD or explicit_cloud_routing:
         route_mode = "factory" if factory_mode else "cloud_proxy"
         active_ws: WorkspaceInfo | None = None
         workspace_id: str
         project_for_api = _unqualified_project_identifier(resolved_project)
 
-        # Trigger: a script or config entry pins the tenant explicitly
-        # Why: explicit tenant configuration remains the escape hatch during migration
-        # Outcome: route to that workspace, but validate the project name inside it
-        if workspace is not None:
-            active_ws = await resolve_workspace_parameter(workspace=workspace, context=context)
-            workspace_id = active_ws.tenant_id
-        elif project_entry and project_entry.workspace_id:
-            # Trigger: the local project config already stores the cloud tenant id.
-            # Why: routing can send that id directly; requiring workspace discovery here
-            #   would turn a control-plane listing outage into a project routing failure.
-            # Outcome: preserve project-scoped routing even when discovery is unavailable.
+        if project_entry and project_entry.workspace_id:
+            # Per-project config stores the cloud tenant id directly
             workspace_id = project_entry.workspace_id
         else:
             resolved_entry = cloud_default_entry

src/basic_memory/mcp/tools/build_context.py

@@ -139,7 +139,6 @@ async def build_context(
         Field(validation_alias=AliasChoices("url", "uri", "memory_url")),
     ],
     project: Optional[str] = None,
-    workspace: Optional[str] = None,
     depth: str | int | None = 1,
     timeframe: Annotated[
         Optional[TimeFrame],
@@ -228,7 +227,6 @@ async def build_context(
         entrypoint="mcp",
         tool_name="build_context",
         requested_project=project,
-        workspace_id=workspace,
         depth=depth or 1,
         timeframe=timeframe,
         page=page,
@@ -237,7 +235,7 @@ async def build_context(
         output_format=output_format,
         is_memory_url=str(url).startswith("memory://"),
     ):
-        async with get_project_client(project, workspace, context) as (client, active_project):
+        async with get_project_client(project, context=context) as (client, active_project):
             logger.info(
                 f"MCP tool call tool=build_context project={active_project.name} "
                 f"url={url} depth={depth} timeframe={timeframe} output_format={output_format}"

src/basic_memory/mcp/tools/canvas.py

@@ -29,7 +29,6 @@ async def canvas(
         Field(validation_alias=AliasChoices("directory", "folder", "dir", "path")),
     ],
     project: Optional[str] = None,
-    workspace: Optional[str] = None,
     context: Context | None = None,
 ) -> str:
     """Create an Obsidian canvas file with the provided nodes and edges.
@@ -100,7 +99,7 @@ async def canvas(
     Raises:
         ToolError: If project doesn't exist or directory path is invalid
     """
-    async with get_project_client(project, workspace, context) as (client, active_project):
+    async with get_project_client(project, context=context) as (client, active_project):
         # Ensure path has .canvas extension
         file_title = title if title.endswith(".canvas") else f"{title}.canvas"
         file_path = f"{directory}/{file_title}"

src/basic_memory/mcp/tools/delete_note.py

@@ -159,7 +159,6 @@ async def delete_note(
         Field(default=False, validation_alias=AliasChoices("is_directory", "is_dir")),
     ] = False,
     project: Optional[str] = None,
-    workspace: Optional[str] = None,
     output_format: Literal["text", "json"] = "text",
     context: Context | None = None,
 ) -> bool | str | dict:
@@ -237,7 +236,7 @@ async def delete_note(
         if detected:
             project = detected
 
-    async with get_project_client(project, workspace, context) as (client, active_project):
+    async with get_project_client(project, context=context) as (client, active_project):
         logger.debug(
             f"Deleting {'directory' if is_directory else 'note'}: {identifier} in project: {active_project.name}"
         )

src/basic_memory/mcp/tools/edit_note.py

@@ -182,7 +182,6 @@ async def edit_note(
         ),
     ],
     project: Optional[str] = None,
-    workspace: Optional[str] = None,
     # Section/heading naming varies across tools; accept the descriptive forms.
     section: Annotated[
         Optional[str],
@@ -303,14 +302,13 @@ async def edit_note(
         entrypoint="mcp",
         tool_name="edit_note",
         requested_project=project,
-        workspace_id=workspace,
         edit_operation=operation,
         output_format=output_format,
         has_section=bool(section),
         has_find_text=bool(find_text),
         expected_replacements=effective_replacements,
     ):
-        async with get_project_client(project, workspace, context) as (client, active_project):
+        async with get_project_client(project, context=context) as (client, active_project):
             logger.info(
                 f"MCP tool call tool=edit_note project={active_project.name} "
                 f"identifier={identifier} operation={operation} output_format={output_format}"

src/basic_memory/mcp/tools/list_directory.py

@@ -32,7 +32,6 @@ async def list_directory(
         ),
     ] = None,
     project: Optional[str] = None,
-    workspace: Optional[str] = None,
     context: Context | None = None,
 ) -> str:
     """List directory contents from the knowledge base with optional filtering.
@@ -77,7 +76,7 @@ async def list_directory(
     Raises:
         ToolError: If project doesn't exist or directory path is invalid
     """
-    async with get_project_client(project, workspace, context) as (client, active_project):
+    async with get_project_client(project, context=context) as (client, active_project):
         logger.debug(
             f"Listing directory '{dir_name}' in project {project} with depth={depth}, glob='{file_name_glob}'"
         )

src/basic_memory/mcp/tools/move_note.py

@@ -371,7 +371,6 @@ async def move_note(
         Field(default=False, validation_alias=AliasChoices("is_directory", "is_dir")),
     ] = False,
     project: Optional[str] = None,
-    workspace: Optional[str] = None,
     output_format: Literal["text", "json"] = "text",
     context: Context | None = None,
 ) -> str | dict:
@@ -495,7 +494,7 @@ async def move_note(
                 "error": "DESTINATION_FOLDER_NOT_FOR_DIRECTORIES",
             }
         return f"# Move Failed - Invalid Parameters\n\n{error_msg}"
-    async with get_project_client(project, workspace, context) as (client, active_project):
+    async with get_project_client(project, context=context) as (client, active_project):
         destination_target = destination_folder or destination_path
         logger.info(
             f"MCP tool call tool=move_note project={active_project.name} "