feat(mcp): expose note external_id in list_directory and recent_activity output

Web-app deep links are built from a note's external_id, and the hosted
cloud MCP appends a link template to these tools' results that agents
fill with that id on request. Neither tool rendered the id in its text
output, so the template referenced a value the model could not see
(basicmachines-co/basic-memory-cloud#1437 review).

list_directory file rows gain a trailing "| id: <uuid>" column;
recent_activity entity rows gain "[id: <uuid>]". Both values were
already present in the underlying API payloads (DirectoryNode,
EntitySummary) - this only surfaces them in the rendered text.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Joe P <joe@basicmemory.com>

Author: 2 people

src/basic_memory/mcp/tools/list_directory.py

@@ -162,6 +162,12 @@ async def list_directory(
                 file_line += f" | {title}"
             if date_str:
                 file_line += f" | {date_str}"
+            # Web-app deep links are built from the note's external_id; hosted
+            # MCP appends a link template that references it, so the id must be
+            # visible in the listing the agent actually reads.
+            external_id = node.get("external_id")
+            if external_id:
+                file_line += f" | id: {external_id}"
 
             output_lines.append(file_line)
 

src/basic_memory/mcp/tools/recent_activity.py

@@ -516,7 +516,9 @@ def _format_project_output(
                 folder_path = str(PurePosixPath(entity.file_path).parent)
                 if folder_path and folder_path != ".":
                     folder = f" ({folder_path})"
-            lines.append(f"  • {title}{folder}")
+            # external_id makes rows linkable: hosted MCP appends a web-app
+            # link template that the agent fills with this id on request.
+            lines.append(f"  • {title}{folder} [id: {entity.external_id}]")
 
     # Show observations (categorized insights)
     if observations:

tests/mcp/test_tool_list_directory.py

@@ -221,3 +221,21 @@ async def test_list_directory_shows_file_metadata(client, test_graph, test_proje
     lines = result.split("\n")
     file_lines = [line for line in lines if "📄" in line]
     assert len(file_lines) == 5  # All 5 files from test_graph
+
+
+@pytest.mark.asyncio
+async def test_list_directory_file_rows_include_external_id(client, test_graph, test_project):
+    """File rows carry the note external_id.
+
+    Web-app deep links are built from this id; the hosted MCP link template
+    tells agents to substitute it, so it must be visible in the text output.
+    """
+    import re
+
+    result = await list_directory(project=test_project.name, dir_name="/test")
+
+    uuid_pattern = r"\| id: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
+    file_lines = [line for line in result.splitlines() if line.startswith("📄")]
+    assert file_lines, f"no file rows in: {result!r}"
+    for line in file_lines:
+        assert re.search(uuid_pattern, line), f"file row missing external_id: {line!r}"

tests/mcp/test_tool_recent_activity.py

@@ -611,3 +611,23 @@ def test_format_project_output_no_more_pages():
     )
     assert "1 items found." in out
     assert "Use page=" not in out
+
+
+@pytest.mark.asyncio
+async def test_recent_activity_entity_rows_include_external_id(client, test_graph, test_project):
+    """Entity rows carry the note external_id for web-app link building.
+
+    The hosted MCP link template tells agents to substitute this id, so it
+    must be visible in the text output they read.
+    """
+    import re
+
+    result = await recent_activity(project=test_project.name, timeframe="30d")
+
+    assert "Recent Notes & Documents" in result
+    uuid_pattern = r"\[id: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\]"
+    entity_lines = [line for line in result.splitlines() if line.strip().startswith("•")]
+    assert entity_lines, f"no entity rows in: {result!r}"
+    assert any(re.search(uuid_pattern, line) for line in entity_lines), (
+        f"entity rows missing external_id: {entity_lines!r}"
+    )