refactor: introduce typed internal API clients for MCP tools (#494)

Creates a new basic_memory/mcp/clients/ module with typed API clients:
- KnowledgeClient: Entity CRUD operations (/knowledge/*)
- SearchClient: Search operations (/search/*)
- MemoryClient: Context building (/memory/*)
- DirectoryClient: Directory listing (/directory/*)
- ResourceClient: Resource reading (/resource/*)
- ProjectClient: Project management (/projects/*)

Each client:
- Encapsulates API path construction (no hardcoded paths in tools)
- Validates responses via Pydantic models
- Uses existing call_* utilities for consistent error handling

Refactored search_notes tool to use SearchClient as demonstration.
Other tools can be migrated incrementally in follow-up work.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/mcp/clients/__init__.py

@@ -0,0 +1,28 @@
+"""Typed internal API clients for MCP tools.
+
+These clients encapsulate API paths, error handling, and response validation.
+MCP tools become thin adapters that call these clients and format results.
+
+Usage:
+    from basic_memory.mcp.clients import KnowledgeClient, SearchClient
+
+    async with get_client() as http_client:
+        knowledge = KnowledgeClient(http_client, project_id)
+        entity = await knowledge.create_entity(entity_data)
+"""
+
+from basic_memory.mcp.clients.knowledge import KnowledgeClient
+from basic_memory.mcp.clients.search import SearchClient
+from basic_memory.mcp.clients.memory import MemoryClient
+from basic_memory.mcp.clients.directory import DirectoryClient
+from basic_memory.mcp.clients.resource import ResourceClient
+from basic_memory.mcp.clients.project import ProjectClient
+
+__all__ = [
+    "KnowledgeClient",
+    "SearchClient",
+    "MemoryClient",
+    "DirectoryClient",
+    "ResourceClient",
+    "ProjectClient",
+]

src/basic_memory/mcp/clients/directory.py

@@ -0,0 +1,70 @@
+"""Typed client for directory API operations.
+
+Encapsulates all /v2/projects/{project_id}/directory/* endpoints.
+"""
+
+from typing import Optional, Any
+
+from httpx import AsyncClient
+
+from basic_memory.mcp.tools.utils import call_get
+
+
+class DirectoryClient:
+    """Typed client for directory listing operations.
+
+    Centralizes:
+    - API path construction for /v2/projects/{project_id}/directory/*
+    - Response validation
+    - Consistent error handling through call_* utilities
+
+    Usage:
+        async with get_client() as http_client:
+            client = DirectoryClient(http_client, project_id)
+            nodes = await client.list("/", depth=2)
+    """
+
+    def __init__(self, http_client: AsyncClient, project_id: str):
+        """Initialize the directory client.
+
+        Args:
+            http_client: HTTPX AsyncClient for making requests
+            project_id: Project external_id (UUID) for API calls
+        """
+        self.http_client = http_client
+        self.project_id = project_id
+        self._base_path = f"/v2/projects/{project_id}/directory"
+
+    async def list(
+        self,
+        dir_name: str = "/",
+        *,
+        depth: int = 1,
+        file_name_glob: Optional[str] = None,
+    ) -> list[dict[str, Any]]:
+        """List directory contents.
+
+        Args:
+            dir_name: Directory path to list (default: root)
+            depth: How deep to traverse (default: 1)
+            file_name_glob: Optional glob pattern to filter files
+
+        Returns:
+            List of directory nodes with their contents
+
+        Raises:
+            ToolError: If the request fails
+        """
+        params: dict = {
+            "dir_name": dir_name,
+            "depth": depth,
+        }
+        if file_name_glob:
+            params["file_name_glob"] = file_name_glob
+
+        response = await call_get(
+            self.http_client,
+            f"{self._base_path}/list",
+            params=params,
+        )
+        return response.json()

src/basic_memory/mcp/clients/knowledge.py

@@ -0,0 +1,176 @@
+"""Typed client for knowledge/entity API operations.
+
+Encapsulates all /v2/projects/{project_id}/knowledge/* endpoints.
+"""
+
+from typing import Any
+
+from httpx import AsyncClient
+
+from basic_memory.mcp.tools.utils import call_get, call_post, call_put, call_patch, call_delete
+from basic_memory.schemas.response import EntityResponse, DeleteEntitiesResponse
+
+
+class KnowledgeClient:
+    """Typed client for knowledge graph entity operations.
+
+    Centralizes:
+    - API path construction for /v2/projects/{project_id}/knowledge/*
+    - Response validation via Pydantic models
+    - Consistent error handling through call_* utilities
+
+    Usage:
+        async with get_client() as http_client:
+            client = KnowledgeClient(http_client, project_id)
+            entity = await client.create_entity(entity_data)
+    """
+
+    def __init__(self, http_client: AsyncClient, project_id: str):
+        """Initialize the knowledge client.
+
+        Args:
+            http_client: HTTPX AsyncClient for making requests
+            project_id: Project external_id (UUID) for API calls
+        """
+        self.http_client = http_client
+        self.project_id = project_id
+        self._base_path = f"/v2/projects/{project_id}/knowledge"
+
+    # --- Entity CRUD Operations ---
+
+    async def create_entity(self, entity_data: dict[str, Any]) -> EntityResponse:
+        """Create a new entity.
+
+        Args:
+            entity_data: Entity data including title, content, folder, etc.
+
+        Returns:
+            EntityResponse with created entity details
+
+        Raises:
+            ToolError: If the request fails
+        """
+        response = await call_post(
+            self.http_client,
+            f"{self._base_path}/entities",
+            json=entity_data,
+        )
+        return EntityResponse.model_validate(response.json())
+
+    async def update_entity(self, entity_id: str, entity_data: dict[str, Any]) -> EntityResponse:
+        """Update an existing entity (full replacement).
+
+        Args:
+            entity_id: Entity external_id (UUID)
+            entity_data: Complete entity data for replacement
+
+        Returns:
+            EntityResponse with updated entity details
+
+        Raises:
+            ToolError: If the request fails
+        """
+        response = await call_put(
+            self.http_client,
+            f"{self._base_path}/entities/{entity_id}",
+            json=entity_data,
+        )
+        return EntityResponse.model_validate(response.json())
+
+    async def get_entity(self, entity_id: str) -> EntityResponse:
+        """Get an entity by ID.
+
+        Args:
+            entity_id: Entity external_id (UUID)
+
+        Returns:
+            EntityResponse with entity details
+
+        Raises:
+            ToolError: If the entity is not found or request fails
+        """
+        response = await call_get(
+            self.http_client,
+            f"{self._base_path}/entities/{entity_id}",
+        )
+        return EntityResponse.model_validate(response.json())
+
+    async def patch_entity(self, entity_id: str, patch_data: dict[str, Any]) -> EntityResponse:
+        """Partially update an entity.
+
+        Args:
+            entity_id: Entity external_id (UUID)
+            patch_data: Partial entity data to update
+
+        Returns:
+            EntityResponse with updated entity details
+
+        Raises:
+            ToolError: If the request fails
+        """
+        response = await call_patch(
+            self.http_client,
+            f"{self._base_path}/entities/{entity_id}",
+            json=patch_data,
+        )
+        return EntityResponse.model_validate(response.json())
+
+    async def delete_entity(self, entity_id: str) -> DeleteEntitiesResponse:
+        """Delete an entity.
+
+        Args:
+            entity_id: Entity external_id (UUID)
+
+        Returns:
+            DeleteEntitiesResponse confirming deletion
+
+        Raises:
+            ToolError: If the entity is not found or request fails
+        """
+        response = await call_delete(
+            self.http_client,
+            f"{self._base_path}/entities/{entity_id}",
+        )
+        return DeleteEntitiesResponse.model_validate(response.json())
+
+    async def move_entity(self, entity_id: str, destination: str) -> EntityResponse:
+        """Move an entity to a new location.
+
+        Args:
+            entity_id: Entity external_id (UUID)
+            destination: New file path for the entity
+
+        Returns:
+            EntityResponse with updated entity details
+
+        Raises:
+            ToolError: If the request fails
+        """
+        response = await call_put(
+            self.http_client,
+            f"{self._base_path}/entities/{entity_id}/move",
+            json={"destination": destination},
+        )
+        return EntityResponse.model_validate(response.json())
+
+    # --- Resolution ---
+
+    async def resolve_entity(self, identifier: str) -> str:
+        """Resolve a string identifier to an entity external_id.
+
+        Args:
+            identifier: The identifier to resolve (permalink, title, or path)
+
+        Returns:
+            The resolved entity external_id (UUID)
+
+        Raises:
+            ToolError: If the identifier cannot be resolved
+        """
+        response = await call_post(
+            self.http_client,
+            f"{self._base_path}/resolve",
+            json={"identifier": identifier},
+        )
+        data = response.json()
+        return data["external_id"]

src/basic_memory/mcp/clients/memory.py

@@ -0,0 +1,120 @@
+"""Typed client for memory/context API operations.
+
+Encapsulates all /v2/projects/{project_id}/memory/* endpoints.
+"""
+
+from typing import Optional
+
+from httpx import AsyncClient
+
+from basic_memory.mcp.tools.utils import call_get
+from basic_memory.schemas.memory import GraphContext
+
+
+class MemoryClient:
+    """Typed client for memory context operations.
+
+    Centralizes:
+    - API path construction for /v2/projects/{project_id}/memory/*
+    - Response validation via Pydantic models
+    - Consistent error handling through call_* utilities
+
+    Usage:
+        async with get_client() as http_client:
+            client = MemoryClient(http_client, project_id)
+            context = await client.build_context("memory://specs/search")
+    """
+
+    def __init__(self, http_client: AsyncClient, project_id: str):
+        """Initialize the memory client.
+
+        Args:
+            http_client: HTTPX AsyncClient for making requests
+            project_id: Project external_id (UUID) for API calls
+        """
+        self.http_client = http_client
+        self.project_id = project_id
+        self._base_path = f"/v2/projects/{project_id}/memory"
+
+    async def build_context(
+        self,
+        path: str,
+        *,
+        depth: int = 1,
+        timeframe: Optional[str] = None,
+        page: int = 1,
+        page_size: int = 10,
+        max_related: int = 10,
+    ) -> GraphContext:
+        """Build context from a memory path.
+
+        Args:
+            path: The path to build context for (without memory:// prefix)
+            depth: How deep to traverse relations
+            timeframe: Time filter (e.g., "7d", "1 week")
+            page: Page number (1-indexed)
+            page_size: Results per page
+            max_related: Maximum related items per result
+
+        Returns:
+            GraphContext with hierarchical results
+
+        Raises:
+            ToolError: If the request fails
+        """
+        params: dict = {
+            "depth": depth,
+            "page": page,
+            "page_size": page_size,
+            "max_related": max_related,
+        }
+        if timeframe:
+            params["timeframe"] = timeframe
+
+        response = await call_get(
+            self.http_client,
+            f"{self._base_path}/{path}",
+            params=params,
+        )
+        return GraphContext.model_validate(response.json())
+
+    async def recent(
+        self,
+        *,
+        timeframe: str = "7d",
+        depth: int = 1,
+        types: Optional[list[str]] = None,
+        page: int = 1,
+        page_size: int = 10,
+    ) -> GraphContext:
+        """Get recent activity.
+
+        Args:
+            timeframe: Time filter (e.g., "7d", "1 week", "2 days ago")
+            depth: How deep to traverse relations
+            types: Filter by item types
+            page: Page number (1-indexed)
+            page_size: Results per page
+
+        Returns:
+            GraphContext with recent activity
+
+        Raises:
+            ToolError: If the request fails
+        """
+        params: dict = {
+            "timeframe": timeframe,
+            "depth": depth,
+            "page": page,
+            "page_size": page_size,
+        }
+        if types:
+            # Join types as comma-separated string if provided
+            params["type"] = ",".join(types) if isinstance(types, list) else types
+
+        response = await call_get(
+            self.http_client,
+            f"{self._base_path}/recent",
+            params=params,
+        )
+        return GraphContext.model_validate(response.json())