Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(mcp): guide directory read failures to list (#4056)

zgyf6ba06bbf87c
diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.py
index 9dc39a80f..f9ccd1fd0 100644
--- a/openviking/server/mcp_endpoint.py
+++ b/openviking/server/mcp_endpoint.py
@@ -398,14 +398,8 @@ async def read(uris: str | list[str]) -> str:
async def _read_one(uri: str) -> str:
async with semaphore:
- try:
- resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)
- body = await service.fs.read_visible(resolved_uri, ctx=ctx)
- if isinstance(body, str) and body.strip():
- return body
- except Exception:
- pass
- return f"(nothing found at {uri})"
+ resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)
+ return await service.fs.read_for_tool(resolved_uri, ctx=ctx, display_uri=uri)
if len(uri_list) == 1:
return await _read_one(uri_list[0])
diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.py
index 52c62e5cd..14ec64060 100644
--- a/openviking/service/fs_service.py
+++ b/openviking/service/fs_service.py
@@ -29,7 +29,7 @@ from openviking.telemetry import get_current_telemetry
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
from openviking.telemetry.resource_summary import build_queue_status_payload
from openviking.utils.embedding_utils import vectorize_directory_meta
-from openviking_cli.exceptions import DeadlineExceededError, NotInitializedError
+from openviking_cli.exceptions import DeadlineExceededError, NotFoundError, NotInitializedError
from openviking_cli.utils import VikingURI, get_logger
logger = get_logger(__name__)
@@ -587,6 +587,29 @@ class FSService:
content = await self.read(uri, ctx=ctx)
return visible_content(content, uri=uri, offset=offset, limit=limit)
+ async def read_for_tool(
+ self,
+ uri: str,
+ ctx: RequestContext,
+ *,
+ display_uri: str | None = None,
+ ) -> str:
+ """Read content for agent tools, returning recoverable text for common read misses."""
+ display_uri = display_uri or uri
+ try:
+ stat = await self.stat(uri, ctx=ctx)
+ except NotFoundError:
+ return f"(not found at {display_uri})"
+ if stat.get("isDir", stat.get("is_dir", False)):
+ return (
+ f"Directory URI is not readable as a file: {display_uri}. "
+ "Use the list tool on this URI to inspect children, then use read on a file URI."
+ )
+ content = await self.read_visible(uri, ctx=ctx)
+ if isinstance(content, str) and content.strip():
+ return content
+ return f"(empty file at {display_uri})"
+
async def abstract(self, uri: str, ctx: RequestContext) -> str:
"""Read L0 abstract (.abstract.md)."""
viking_fs = self._ensure_initialized()
diff --git a/tests/server/test_mcp_endpoint.py b/tests/server/test_mcp_endpoint.py
index 94fe7eefd..32460b344 100644
--- a/tests/server/test_mcp_endpoint.py
+++ b/tests/server/test_mcp_endpoint.py
@@ -444,7 +444,19 @@ async def test_mcp_middleware_rejects_invalid_actor_peer_header():
async def test_read_nonexistent_uri(service):
result = await read("viking://user/memories/does_not_exist.md")
- assert "nothing found" in result.lower()
+ assert "not found" in result.lower()
+
+
+async def test_read_directory_uri_returns_recoverable_hint(service):
+ uri = "viking://resources/test_read_dir_hint"
+ await service.viking_fs.mkdir(uri, ctx=DEFAULT_CTX, exist_ok=True)
+
+ result = await read(uri)
+
+ assert "Directory URI is not readable as a file" in result
+ assert "Use the list tool" in result
+ assert "then use read on a file URI" in result
+ assert "nothing found" not in result.lower()
async def test_read_batch(service):
@@ -455,21 +467,23 @@ async def test_read_batch(service):
]
)
assert "===" in result
- assert "nothing found" in result.lower()
+ assert "not found" in result.lower()
-async def test_read_uses_public_content_projection(monkeypatch):
- read_visible = AsyncMock(return_value="visible memory")
+async def test_read_delegates_to_tool_read(monkeypatch):
+ read_for_tool = AsyncMock(return_value="visible memory")
monkeypatch.setattr(
mcp_endpoint,
"get_service",
- lambda: SimpleNamespace(fs=SimpleNamespace(read_visible=read_visible)),
+ lambda: SimpleNamespace(fs=SimpleNamespace(read_for_tool=read_for_tool)),
)
uri = "viking://user/project/private.md"
assert await read(uri) == "visible memory"
- read_visible.assert_awaited_once_with(
- "viking://user/test_user/project/private.md", ctx=DEFAULT_CTX
+ read_for_tool.assert_awaited_once_with(
+ "viking://user/test_user/project/private.md",
+ ctx=DEFAULT_CTX,
+ display_uri=uri,
)
diff --git a/tests/service/test_fs_service.py b/tests/service/test_fs_service.py
index 941b31d5e..ed89de4f9 100644
--- a/tests/service/test_fs_service.py
+++ b/tests/service/test_fs_service.py
@@ -9,6 +9,7 @@ import pytest
from openviking.server.identity import RequestContext, Role
from openviking.service.fs_service import FSService
+from openviking_cli.exceptions import NotFoundError
from openviking_cli.session.user_id import UserIdentifier
@@ -183,6 +184,46 @@ async def test_read_visible_preserves_non_memory_content(request_context):
)
+async def test_read_for_tool_returns_not_found_message(request_context):
+ uri = "viking://resources/missing.md"
+ viking_fs = SimpleNamespace(stat=AsyncMock(side_effect=NotFoundError(uri)))
+ service = FSService(viking_fs=viking_fs)
+
+ result = await service.read_for_tool(uri, ctx=request_context, display_uri="viking://alias.md")
+
+ assert result == "(not found at viking://alias.md)"
+
+
+async def test_read_for_tool_returns_directory_hint(request_context):
+ viking_fs = SimpleNamespace(
+ stat=AsyncMock(return_value={"isDir": True}),
+ read_file=AsyncMock(),
+ )
+ service = FSService(viking_fs=viking_fs)
+
+ result = await service.read_for_tool("viking://resources/docs", ctx=request_context)
+
+ assert "Directory URI is not readable as a file" in result
+ assert "Use the list tool" in result
+ viking_fs.read_file.assert_not_awaited()
+
+
+async def test_read_for_tool_returns_empty_file_message(request_context):
+ uri = "viking://resources/empty.md"
+ viking_fs = SimpleNamespace(
+ stat=AsyncMock(return_value={"isDir": False}),
+ read_file=AsyncMock(return_value=""),
+ )
+ service = FSService(viking_fs=viking_fs)
+
+ result = await service.read_for_tool(uri, ctx=request_context)
+
+ assert result == f"(empty file at {uri})"
+
+
@pytest.mark.asyncio
async def test_grep_projects_memory_content_but_keeps_resource_fast_path(request_context):
viking_fs = SimpleNamespace(grep=AsyncMock(return_value={"matches": []}))