fix(mcp): isolate workspace index failures

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

Author: phernandez

src/basic_memory/mcp/project_context.py

@@ -57,6 +57,7 @@ class WorkspaceProjectIndex:
     workspaces: tuple[WorkspaceInfo, ...]
     entries: tuple[WorkspaceProjectEntry, ...]
     entries_by_permalink: dict[str, tuple[WorkspaceProjectEntry, ...]]
+    failed_workspaces: tuple[WorkspaceInfo, ...] = ()
 
 
 def set_workspace_provider(provider: Callable[[], Awaitable[list[WorkspaceInfo]]]) -> None:
@@ -300,6 +301,12 @@ def _workspace_project_index_from_state(raw: object) -> WorkspaceProjectIndex |
         return None
 
     workspaces = tuple(WorkspaceInfo.model_validate(item) for item in workspaces_raw)
+    failed_workspaces_raw = raw_mapping.get("failed_workspaces")
+    failed_workspaces = (
+        tuple(WorkspaceInfo.model_validate(item) for item in failed_workspaces_raw)
+        if isinstance(failed_workspaces_raw, list)
+        else ()
+    )
     entries_list: list[WorkspaceProjectEntry] = []
     for item in entries_raw:
         if not isinstance(item, dict):
@@ -316,13 +323,18 @@ def _workspace_project_index_from_state(raw: object) -> WorkspaceProjectIndex |
             )
         )
     entries = tuple(entries_list)
-    return _build_workspace_project_index(workspaces, entries)
+    return _build_workspace_project_index(
+        workspaces,
+        entries,
+        failed_workspaces=failed_workspaces,
+    )
 
 
 def _workspace_project_index_to_state(index: WorkspaceProjectIndex) -> dict:
     """Serialize a workspace project index for MCP context state."""
     return {
         "workspaces": [workspace.model_dump() for workspace in index.workspaces],
+        "failed_workspaces": [workspace.model_dump() for workspace in index.failed_workspaces],
         "entries": [
             {
                 "workspace": entry.workspace.model_dump(),
@@ -336,6 +348,8 @@ def _workspace_project_index_to_state(index: WorkspaceProjectIndex) -> dict:
 def _build_workspace_project_index(
     workspaces: tuple[WorkspaceInfo, ...],
     entries: tuple[WorkspaceProjectEntry, ...],
+    *,
+    failed_workspaces: tuple[WorkspaceInfo, ...] = (),
 ) -> WorkspaceProjectIndex:
     """Build the permalink lookup table for workspace-project entries."""
     grouped: dict[str, list[WorkspaceProjectEntry]] = {}
@@ -349,6 +363,7 @@ def _build_workspace_project_index(
             permalink: tuple(items)
             for permalink, items in sorted(grouped.items(), key=lambda item: item[0])
         },
+        failed_workspaces=failed_workspaces,
     )
 
 
@@ -469,11 +484,50 @@ async def _ensure_workspace_project_index(
             "Ensure you have an active subscription and tenant access."
         )
 
-    fetched_entries = await asyncio.gather(
-        *[_fetch_workspace_project_entries(workspace, context=context) for workspace in workspaces]
+    fetched_results = await asyncio.gather(
+        *[_fetch_workspace_project_entries(workspace, context=context) for workspace in workspaces],
+        return_exceptions=True,
+    )
+    entries_list: list[WorkspaceProjectEntry] = []
+    failed_workspaces: list[WorkspaceInfo] = []
+    successful_fetches = 0
+    for workspace, result in zip(workspaces, fetched_results, strict=True):
+        if isinstance(result, BaseException):
+            if not isinstance(result, Exception):
+                raise result
+            # Trigger: one workspace project listing failed during a multi-workspace index.
+            # Why: a transient or unauthorized tenant should not break qualified routing for
+            #   healthy workspaces, but unqualified routing still needs to know the index is partial.
+            # Outcome: keep successful workspace entries and record the failed workspace.
+            failed_workspaces.append(workspace)
+            logger.warning(
+                f"Cloud project discovery failed for workspace {workspace.slug} "
+                f"({workspace.tenant_id}): {result}"
+            )
+            if context:  # pragma: no cover
+                await context.info(
+                    f"Cloud project discovery failed for workspace {workspace.slug}; "
+                    "continuing with other workspaces"
+                )
+            continue
+
+        workspace_entries = cast(tuple[WorkspaceProjectEntry, ...], result)
+        successful_fetches += 1
+        entries_list.extend(workspace_entries)
+
+    if failed_workspaces and successful_fetches == 0:
+        failed_labels = ", ".join(workspace.slug for workspace in failed_workspaces)
+        raise ValueError(
+            "Unable to discover projects in any accessible workspace. "
+            f"Failed workspaces: {failed_labels}"
+        )
+
+    entries = tuple(entries_list)
+    index = _build_workspace_project_index(
+        workspaces,
+        entries,
+        failed_workspaces=tuple(failed_workspaces),
     )
-    entries = tuple(entry for workspace_entries in fetched_entries for entry in workspace_entries)
-    index = _build_workspace_project_index(workspaces, entries)
 
     if context:
         await context.set_state(
@@ -520,6 +574,14 @@ async def resolve_workspace_project_identifier(
             if entry.workspace.tenant_id == workspace.tenant_id
         ]
         if not matches:
+            if any(
+                failed_workspace.tenant_id == workspace.tenant_id
+                for failed_workspace in index.failed_workspaces
+            ):
+                raise ValueError(
+                    f"Projects for workspace '{workspace.name}' ({workspace.slug}) "
+                    "could not be loaded. Retry after workspace discovery recovers."
+                )
             available = ", ".join(
                 entry.qualified_name
                 for entry in index.entries
@@ -533,10 +595,17 @@ async def resolve_workspace_project_identifier(
 
     matches = index.entries_by_permalink.get(project_permalink, ())
     if not matches:
+        failed_note = ""
+        if index.failed_workspaces:
+            failed = ", ".join(workspace.slug for workspace in index.failed_workspaces)
+            failed_note = (
+                f" Project discovery failed for workspace(s): {failed}; "
+                "retry or use a qualified project from an indexed workspace."
+            )
         available = ", ".join(entry.qualified_name for entry in index.entries)
         raise ValueError(
-            f"Project '{project}' was not found in any accessible cloud workspace. "
-            f"Available projects: {available}"
+            f"Project '{project}' was not found in indexed cloud workspaces. "
+            f"Available projects: {available}.{failed_note}"
         )
 
     cached_workspace = await _get_cached_active_workspace(context)
@@ -557,6 +626,15 @@ async def resolve_workspace_project_identifier(
             f"Project '{project}' exists in multiple workspaces. Use: {choices}\n{details}"
         )
 
+    if index.failed_workspaces:
+        qualified_name = matches[0].qualified_name
+        failed = ", ".join(workspace.slug for workspace in index.failed_workspaces)
+        raise ValueError(
+            f"Project '{project}' was found as {qualified_name}, but project discovery "
+            f"failed for workspace(s): {failed}. Use '{qualified_name}' to route "
+            "explicitly, or retry after discovery recovers."
+        )
+
     return matches[0]
 
 

src/basic_memory/mcp/tools/project_management.py

@@ -250,7 +250,7 @@ def _format_project_list_text(merged: list[dict]) -> str:
         source = project["source"]
         qualified_name = project.get("qualified_name")
         qualified_suffix = f" [{qualified_name}]" if qualified_name else ""
-        result += f"• {label} ({source}){qualified_suffix}\n"
+        result += f"- {label} ({source}){qualified_suffix}\n"
 
     result += "\n" + "─" * 40 + "\n"
     result += "Next: Ask which project to use for this session.\n"

tests/mcp/test_project_context.py

@@ -24,6 +24,9 @@ async def get_state(self, key: str):
     async def set_state(self, key: str, value: object, **kwargs) -> None:
         self._state[key] = value
 
+    async def info(self, message: str) -> None:
+        self._state["info_message"] = message
+
 
 def _ctx(context: _ContextState) -> Any:
     return cast(Any, context)
@@ -425,6 +428,101 @@ async def fake_fetch_workspace_project_entries(workspace, context=None):
     assert calls == ["personal", "acme", "personal", "acme"]
 
 
+@pytest.mark.asyncio
+async def test_workspace_project_index_keeps_successes_when_workspace_fetch_fails(
+    monkeypatch,
+):
+    import basic_memory.mcp.project_context as project_context
+    from basic_memory.mcp.project_context import (
+        WorkspaceProjectEntry,
+        _ensure_workspace_project_index,
+        resolve_workspace_project_identifier,
+    )
+
+    context = _ContextState()
+    personal = _workspace(
+        tenant_id="personal-tenant",
+        workspace_type="personal",
+        slug="personal",
+        name="Personal",
+        role="owner",
+        is_default=True,
+    )
+    acme = _workspace(
+        tenant_id="acme-tenant",
+        workspace_type="organization",
+        slug="acme",
+        name="Acme",
+        role="editor",
+    )
+    project = _project("Meeting Notes", id=7, external_id="personal-meeting-notes")
+
+    async def fake_get_available_workspaces(context=None):
+        return [personal, acme]
+
+    async def fake_fetch_workspace_project_entries(workspace, context=None):
+        if workspace.slug == "acme":
+            raise RuntimeError("acme unavailable")
+        return (WorkspaceProjectEntry(workspace=workspace, project=project),)
+
+    monkeypatch.setattr(project_context, "get_available_workspaces", fake_get_available_workspaces)
+    monkeypatch.setattr(
+        project_context,
+        "_fetch_workspace_project_entries",
+        fake_fetch_workspace_project_entries,
+    )
+
+    index = await _ensure_workspace_project_index(context=_ctx(context))
+
+    assert [entry.qualified_name for entry in index.entries] == ["personal/meeting-notes"]
+    assert [workspace.slug for workspace in index.failed_workspaces] == ["acme"]
+
+    resolved = await resolve_workspace_project_identifier(
+        "personal/meeting-notes",
+        context=_ctx(context),
+    )
+    assert resolved.project.external_id == "personal-meeting-notes"
+
+    with pytest.raises(ValueError, match="Use 'personal/meeting-notes'"):
+        await resolve_workspace_project_identifier(
+            "meeting-notes",
+            context=_ctx(context),
+        )
+
+
+@pytest.mark.asyncio
+async def test_workspace_project_index_raises_when_all_workspace_fetches_fail(
+    monkeypatch,
+):
+    import basic_memory.mcp.project_context as project_context
+    from basic_memory.mcp.project_context import _ensure_workspace_project_index
+
+    personal = _workspace(
+        tenant_id="personal-tenant",
+        workspace_type="personal",
+        slug="personal",
+        name="Personal",
+        role="owner",
+        is_default=True,
+    )
+
+    async def fake_get_available_workspaces(context=None):
+        return [personal]
+
+    async def fake_fetch_workspace_project_entries(workspace, context=None):
+        raise RuntimeError("tenant unavailable")
+
+    monkeypatch.setattr(project_context, "get_available_workspaces", fake_get_available_workspaces)
+    monkeypatch.setattr(
+        project_context,
+        "_fetch_workspace_project_entries",
+        fake_fetch_workspace_project_entries,
+    )
+
+    with pytest.raises(ValueError, match="Unable to discover projects"):
+        await _ensure_workspace_project_index()
+
+
 @pytest.mark.asyncio
 async def test_fetch_workspace_project_entries_copies_default_project(monkeypatch):
     import basic_memory.mcp.async_client as async_client

tests/mcp/test_tool_project_management.py

@@ -47,7 +47,7 @@ def _make_list(projects: list[ProjectItem], default: str | None = None) -> Proje
 async def test_list_memory_projects_unconstrained(app, test_project):
     result = await list_memory_projects()
     assert "Available projects:" in result
-    assert f"• {test_project.name}" in result
+    assert f"- {test_project.name}" in result
 
 
 @pytest.mark.asyncio
@@ -77,9 +77,9 @@ async def test_list_memory_projects_shows_display_name(app, client, test_project
         result = await list_memory_projects()
 
     # Regular project shows name with source label
-    assert "• main (local)" in result
+    assert "- main (local)" in result
     # Private project shows display_name with slug in parentheses, then source
-    assert "• My Notes (private-fb83af23) (local)" in result
+    assert "- My Notes (private-fb83af23) (local)" in result
 
 
 @pytest.mark.asyncio
@@ -95,7 +95,7 @@ async def test_list_memory_projects_no_display_name_shows_name_only(app, client,
     ):
         result = await list_memory_projects()
 
-    assert "• my-project (local)" in result
+    assert "- my-project (local)" in result
 
 
 @pytest.mark.asyncio
@@ -176,11 +176,11 @@ async def test_list_memory_projects_local_and_cloud_merge(app, test_project):
         result = await list_memory_projects()
 
     # Both local+cloud project shows merged source
-    assert "• main (local+cloud)" in result
+    assert "- main (local+cloud)" in result
     # Local-only project
-    assert "• specs (local)" in result
+    assert "- specs (local)" in result
     # Cloud-only project
-    assert "• basic-memory-llc (cloud)" in result
+    assert "- basic-memory-llc (cloud)" in result
 
 
 @pytest.mark.asyncio
@@ -193,7 +193,7 @@ async def test_list_memory_projects_no_cloud_credentials(app, test_project):
         result = await list_memory_projects()
 
     assert "Available projects:" in result
-    assert f"• {test_project.name} (local)" in result
+    assert f"- {test_project.name} (local)" in result
     # No cloud source labels
     assert "cloud)" not in result
 
@@ -215,7 +215,7 @@ async def test_list_memory_projects_cloud_failure_graceful(app, test_project):
         result = await list_memory_projects()
 
     assert "Available projects:" in result
-    assert f"• {test_project.name} (local)" in result
+    assert f"- {test_project.name} (local)" in result
 
 
 @pytest.mark.asyncio
@@ -244,7 +244,7 @@ async def test_list_memory_projects_factory_mode(app, test_project):
     ):
         result = await list_memory_projects()
 
-    assert "• cloud-proj (cloud)" in result
+    assert "- cloud-proj (cloud)" in result
 
 
 @pytest.mark.asyncio
@@ -313,7 +313,7 @@ async def test_list_memory_projects_factory_mode_workspace_lookup_failure(app, t
         result = await list_memory_projects()
 
     # Still reported as cloud even without workspace metadata
-    assert "• cloud-proj (cloud)" in result
+    assert "- cloud-proj (cloud)" in result
 
 
 @pytest.mark.asyncio
@@ -579,7 +579,7 @@ async def test_list_memory_projects_aggregates_without_config_workspace(app, tes
         result = await list_memory_projects()
 
     mock_index.assert_awaited_once()
-    assert "• cloud-proj (cloud) [default/cloud-proj]" in result
+    assert "- cloud-proj (cloud) [default/cloud-proj]" in result
 
 
 @pytest.mark.asyncio