basic-memory 0.7.0__py3-none-any.whl → 0.17.4__py3-none-any.whl

basic_memory/mcp/tools/utils.py

@@ -1,4 +1,11 @@
+"""Utility functions for making HTTP requests in Basic Memory MCP tools.
+
+These functions provide a consistent interface for making HTTP requests
+to the Basic Memory API, with improved error handling and logging.
+"""
+
 import typing
+from typing import Optional
 
 from httpx import Response, URL, AsyncClient, HTTPStatusError
 from httpx._client import UseClientDefault, USE_CLIENT_DEFAULT
@@ -17,6 +24,56 @@ from loguru import logger
 from mcp.server.fastmcp.exceptions import ToolError
 
 
+def get_error_message(
+    status_code: int, url: URL | str, method: str, msg: Optional[str] = None
+) -> str:
+    """Get a friendly error message based on the HTTP status code.
+
+    Args:
+        status_code: The HTTP status code
+        url: The URL that was requested
+        method: The HTTP method used
+
+    Returns:
+        A user-friendly error message
+    """
+    # Extract path from URL for cleaner error messages
+    if isinstance(url, str):
+        path = url.split("/")[-1]
+    else:
+        path = str(url).split("/")[-1] if url else "resource"
+
+    # Client errors (400-499)
+    if status_code == 400:
+        return f"Invalid request: The request to '{path}' was malformed or invalid"
+    elif status_code == 401:  # pragma: no cover
+        return f"Authentication required: You need to authenticate to access '{path}'"
+    elif status_code == 403:  # pragma: no cover
+        return f"Access denied: You don't have permission to access '{path}'"
+    elif status_code == 404:
+        return f"Resource not found: '{path}' doesn't exist or has been moved"
+    elif status_code == 409:  # pragma: no cover
+        return f"Conflict: The request for '{path}' conflicts with the current state"
+    elif status_code == 429:  # pragma: no cover
+        return "Too many requests: Please slow down and try again later"
+    elif 400 <= status_code < 500:  # pragma: no cover
+        return f"Client error ({status_code}): The request for '{path}' could not be completed"
+
+    # Server errors (500-599)
+    elif status_code == 500:
+        return f"Internal server error: Something went wrong processing '{path}'"
+    elif status_code == 503:  # pragma: no cover
+        return (
+            f"Service unavailable: The server is currently unable to handle requests for '{path}'"
+        )
+    elif 500 <= status_code < 600:  # pragma: no cover
+        return f"Server error ({status_code}): The server encountered an error handling '{path}'"
+
+    # Fallback for any other status code
+    else:  # pragma: no cover
+        return f"HTTP error {status_code}: {method} request to '{path}' failed"
+
+
 async def call_get(
     client: AsyncClient,
     url: URL | str,
@@ -29,7 +86,28 @@ async def call_get(
     timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
     extensions: RequestExtensions | None = None,
 ) -> Response:
+    """Make a GET request and handle errors appropriately.
+
+    Args:
+        client: The HTTPX AsyncClient to use
+        url: The URL to request
+        params: Query parameters
+        headers: HTTP headers
+        cookies: HTTP cookies
+        auth: Authentication
+        follow_redirects: Whether to follow redirects
+        timeout: Request timeout
+        extensions: HTTPX extensions
+
+    Returns:
+        The HTTP response
+
+    Raises:
+        ToolError: If the request fails with an appropriate error message
+    """
     logger.debug(f"Calling GET '{url}' params: '{params}'")
+    error_message = None
+
     try:
         response = await client.get(
             url,
@@ -41,11 +119,36 @@ async def call_get(
             timeout=timeout,
             extensions=extensions,
         )
-        response.raise_for_status()
-        return response
+
+        if response.is_success:
+            return response
+
+        # Handle different status codes differently
+        status_code = response.status_code
+        # get the message if available
+        response_data = response.json()
+        if isinstance(response_data, dict) and "detail" in response_data:
+            error_message = response_data["detail"]
+        else:
+            error_message = get_error_message(status_code, url, "PUT")
+
+        # Log at appropriate level based on status code
+        if 400 <= status_code < 500:
+            # Client errors: log as info except for 429 (Too Many Requests)
+            if status_code == 429:  # pragma: no cover
+                logger.warning(f"Rate limit exceeded: GET {url}: {error_message}")
+            else:
+                logger.info(f"Client error: GET {url}: {error_message}")
+        else:  # pragma: no cover
+            # Server errors: log as error
+            logger.error(f"Server error: GET {url}: {error_message}")
+
+        # Raise a tool error with the friendly message
+        response.raise_for_status()  # Will always raise since we're in the error case
+        return response  # This line will never execute, but it satisfies the type checker  # pragma: no cover
+
     except HTTPStatusError as e:
-        logger.error(f"Error calling GET {url}: {e}")
-        raise ToolError(f"Error calling tool: {e}.") from e
+        raise ToolError(error_message) from e
 
 
 async def call_put(
@@ -64,6 +167,32 @@ async def call_put(
     timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
     extensions: RequestExtensions | None = None,
 ) -> Response:
+    """Make a PUT request and handle errors appropriately.
+
+    Args:
+        client: The HTTPX AsyncClient to use
+        url: The URL to request
+        content: Request content
+        data: Form data
+        files: Files to upload
+        json: JSON data
+        params: Query parameters
+        headers: HTTP headers
+        cookies: HTTP cookies
+        auth: Authentication
+        follow_redirects: Whether to follow redirects
+        timeout: Request timeout
+        extensions: HTTPX extensions
+
+    Returns:
+        The HTTP response
+
+    Raises:
+        ToolError: If the request fails with an appropriate error message
+    """
+    logger.debug(f"Calling PUT '{url}'")
+    error_message = None
+
     try:
         response = await client.put(
             url,
@@ -79,11 +208,141 @@ async def call_put(
             timeout=timeout,
             extensions=extensions,
         )
-        response.raise_for_status()
-        return response
+
+        if response.is_success:
+            return response
+
+        # Handle different status codes differently
+        status_code = response.status_code
+
+        # get the message if available
+        response_data = response.json()
+        if isinstance(response_data, dict) and "detail" in response_data:
+            error_message = response_data["detail"]  # pragma: no cover
+        else:
+            error_message = get_error_message(status_code, url, "PUT")
+
+        # Log at appropriate level based on status code
+        if 400 <= status_code < 500:
+            # Client errors: log as info except for 429 (Too Many Requests)
+            if status_code == 429:  # pragma: no cover
+                logger.warning(f"Rate limit exceeded: PUT {url}: {error_message}")
+            else:
+                logger.info(f"Client error: PUT {url}: {error_message}")
+        else:  # pragma: no cover
+            # Server errors: log as error
+            logger.error(f"Server error: PUT {url}: {error_message}")
+
+        # Raise a tool error with the friendly message
+        response.raise_for_status()  # Will always raise since we're in the error case
+        return response  # This line will never execute, but it satisfies the type checker  # pragma: no cover
+
     except HTTPStatusError as e:
-        logger.error(f"Error calling PUT {url}: {e}")
-        raise ToolError(f"Error calling tool: {e}") from e
+        raise ToolError(error_message) from e
+
+
+async def call_patch(
+    client: AsyncClient,
+    url: URL | str,
+    *,
+    content: RequestContent | None = None,
+    data: RequestData | None = None,
+    files: RequestFiles | None = None,
+    json: typing.Any | None = None,
+    params: QueryParamTypes | None = None,
+    headers: HeaderTypes | None = None,
+    cookies: CookieTypes | None = None,
+    auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,
+    follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,
+    timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
+    extensions: RequestExtensions | None = None,
+) -> Response:
+    """Make a PATCH request and handle errors appropriately.
+
+    Args:
+        client: The HTTPX AsyncClient to use
+        url: The URL to request
+        content: Request content
+        data: Form data
+        files: Files to upload
+        json: JSON data
+        params: Query parameters
+        headers: HTTP headers
+        cookies: HTTP cookies
+        auth: Authentication
+        follow_redirects: Whether to follow redirects
+        timeout: Request timeout
+        extensions: HTTPX extensions
+
+    Returns:
+        The HTTP response
+
+    Raises:
+        ToolError: If the request fails with an appropriate error message
+    """
+    logger.debug(f"Calling PATCH '{url}'")
+
+    try:
+        response = await client.patch(
+            url,
+            content=content,
+            data=data,
+            files=files,
+            json=json,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            auth=auth,
+            follow_redirects=follow_redirects,
+            timeout=timeout,
+            extensions=extensions,
+        )
+
+        if response.is_success:
+            return response
+
+        # Handle different status codes differently
+        status_code = response.status_code
+
+        # Try to extract specific error message from response body
+        try:
+            response_data = response.json()
+            if isinstance(response_data, dict) and "detail" in response_data:
+                error_message = response_data["detail"]
+            else:
+                error_message = get_error_message(status_code, url, "PATCH")  # pragma: no cover
+        except Exception:  # pragma: no cover
+            error_message = get_error_message(status_code, url, "PATCH")  # pragma: no cover
+
+        # Log at appropriate level based on status code
+        if 400 <= status_code < 500:
+            # Client errors: log as info except for 429 (Too Many Requests)
+            if status_code == 429:  # pragma: no cover
+                logger.warning(f"Rate limit exceeded: PATCH {url}: {error_message}")
+            else:
+                logger.info(f"Client error: PATCH {url}: {error_message}")
+        else:  # pragma: no cover
+            # Server errors: log as error
+            logger.error(f"Server error: PATCH {url}: {error_message}")  # pragma: no cover
+
+        # Raise a tool error with the friendly message
+        response.raise_for_status()  # Will always raise since we're in the error case
+        return response  # This line will never execute, but it satisfies the type checker  # pragma: no cover
+
+    except HTTPStatusError as e:
+        status_code = e.response.status_code
+
+        # Try to extract specific error message from response body
+        try:
+            response_data = e.response.json()
+            if isinstance(response_data, dict) and "detail" in response_data:
+                error_message = response_data["detail"]
+            else:
+                error_message = get_error_message(status_code, url, "PATCH")  # pragma: no cover
+        except Exception:  # pragma: no cover
+            error_message = get_error_message(status_code, url, "PATCH")  # pragma: no cover
+
+        raise ToolError(error_message) from e
 
 
 async def call_post(
@@ -102,6 +361,32 @@ async def call_post(
     timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
     extensions: RequestExtensions | None = None,
 ) -> Response:
+    """Make a POST request and handle errors appropriately.
+
+    Args:
+        client: The HTTPX AsyncClient to use
+        url: The URL to request
+        content: Request content
+        data: Form data
+        files: Files to upload
+        json: JSON data
+        params: Query parameters
+        headers: HTTP headers
+        cookies: HTTP cookies
+        auth: Authentication
+        follow_redirects: Whether to follow redirects
+        timeout: Request timeout
+        extensions: HTTPX extensions
+
+    Returns:
+        The HTTP response
+
+    Raises:
+        ToolError: If the request fails with an appropriate error message
+    """
+    logger.debug(f"Calling POST '{url}'")
+    error_message = None
+
     try:
         response = await client.post(
             url=url,
@@ -117,11 +402,65 @@ async def call_post(
             timeout=timeout,
             extensions=extensions,
         )
-        response.raise_for_status()
-        return response
+        logger.debug(f"response: {response.json()}")
+
+        if response.is_success:
+            return response
+
+        # Handle different status codes differently
+        status_code = response.status_code
+        # get the message if available
+        response_data = response.json()
+        if isinstance(response_data, dict) and "detail" in response_data:
+            error_message = response_data["detail"]
+        else:
+            error_message = get_error_message(status_code, url, "POST")
+
+        # Log at appropriate level based on status code
+        if 400 <= status_code < 500:
+            # Client errors: log as info except for 429 (Too Many Requests)
+            if status_code == 429:  # pragma: no cover
+                logger.warning(f"Rate limit exceeded: POST {url}: {error_message}")
+            else:  # pragma: no cover
+                logger.info(f"Client error: POST {url}: {error_message}")
+        else:
+            # Server errors: log as error
+            logger.error(f"Server error: POST {url}: {error_message}")
+
+        # Raise a tool error with the friendly message
+        response.raise_for_status()  # Will always raise since we're in the error case
+        return response  # This line will never execute, but it satisfies the type checker  # pragma: no cover
+
+    except HTTPStatusError as e:
+        raise ToolError(error_message) from e
+
+
+async def resolve_entity_id(client: AsyncClient, project_external_id: str, identifier: str) -> str:
+    """Resolve a string identifier to an entity external_id using the v2 API.
+
+    Args:
+        client: HTTP client for API calls
+        project_external_id: Project external ID (UUID)
+        identifier: The identifier to resolve (permalink, title, or path)
+
+    Returns:
+        The resolved entity external_id (UUID)
+
+    Raises:
+        ToolError: If the identifier cannot be resolved
+    """
+    try:
+        response = await call_post(
+            client, f"/v2/projects/{project_external_id}/knowledge/resolve", json={"identifier": identifier}
+        )
+        data = response.json()
+        return data["external_id"]
     except HTTPStatusError as e:
-        logger.error(f"Error calling POST {url}: {e}")
-        raise ToolError(f"Error calling tool: {e}") from e
+        if e.response.status_code == 404:  # pragma: no cover
+            raise ToolError(f"Entity not found: '{identifier}'")  # pragma: no cover
+        raise ToolError(f"Error resolving identifier '{identifier}': {e}")  # pragma: no cover
+    except Exception as e:
+        raise ToolError(f"Unexpected error resolving identifier '{identifier}': {e}")  # pragma: no cover
 
 
 async def call_delete(
@@ -136,6 +475,28 @@ async def call_delete(
     timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
     extensions: RequestExtensions | None = None,
 ) -> Response:
+    """Make a DELETE request and handle errors appropriately.
+
+    Args:
+        client: The HTTPX AsyncClient to use
+        url: The URL to request
+        params: Query parameters
+        headers: HTTP headers
+        cookies: HTTP cookies
+        auth: Authentication
+        follow_redirects: Whether to follow redirects
+        timeout: Request timeout
+        extensions: HTTPX extensions
+
+    Returns:
+        The HTTP response
+
+    Raises:
+        ToolError: If the request fails with an appropriate error message
+    """
+    logger.debug(f"Calling DELETE '{url}'")
+    error_message = None
+
     try:
         response = await client.delete(
             url=url,
@@ -147,8 +508,33 @@ async def call_delete(
             timeout=timeout,
             extensions=extensions,
         )
-        response.raise_for_status()
-        return response
+
+        if response.is_success:
+            return response
+
+        # Handle different status codes differently
+        status_code = response.status_code
+        # get the message if available
+        response_data = response.json()
+        if isinstance(response_data, dict) and "detail" in response_data:
+            error_message = response_data["detail"]  # pragma: no cover
+        else:
+            error_message = get_error_message(status_code, url, "DELETE")
+
+        # Log at appropriate level based on status code
+        if 400 <= status_code < 500:
+            # Client errors: log as info except for 429 (Too Many Requests)
+            if status_code == 429:  # pragma: no cover
+                logger.warning(f"Rate limit exceeded: DELETE {url}: {error_message}")
+            else:
+                logger.info(f"Client error: DELETE {url}: {error_message}")
+        else:  # pragma: no cover
+            # Server errors: log as error
+            logger.error(f"Server error: DELETE {url}: {error_message}")
+
+        # Raise a tool error with the friendly message
+        response.raise_for_status()  # Will always raise since we're in the error case
+        return response  # This line will never execute, but it satisfies the type checker  # pragma: no cover
+
     except HTTPStatusError as e:
-        logger.error(f"Error calling DELETE {url}: {e}")
-        raise ToolError(f"Error calling tool: {e}") from e
+        raise ToolError(error_message) from e

basic_memory/mcp/tools/view_note.py

@@ -0,0 +1,78 @@
+"""View note tool for Basic Memory MCP server."""
+
+from textwrap import dedent
+from typing import Optional
+
+from loguru import logger
+from fastmcp import Context
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.read_note import read_note
+from basic_memory.telemetry import track_mcp_tool
+
+
+@mcp.tool(
+    description="View a note as a formatted artifact for better readability.",
+)
+async def view_note(
+    identifier: str,
+    project: Optional[str] = None,
+    page: int = 1,
+    page_size: int = 10,
+    context: Context | None = None,
+) -> str:
+    """View a markdown note as a formatted artifact.
+
+    This tool reads a note using the same logic as read_note but instructs Claude
+    to display the content as a markdown artifact in the Claude Desktop app.
+    Project parameter optional with server resolution.
+
+    Args:
+        identifier: The title or permalink of the note to view
+        project: Project name to read from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        page: Page number for paginated results (default: 1)
+        page_size: Number of items per page (default: 10)
+        context: Optional FastMCP context for performance caching.
+
+    Returns:
+        Instructions for Claude to create a markdown artifact with the note content.
+
+    Examples:
+        # View a note by title
+        view_note("Meeting Notes")
+
+        # View a note by permalink
+        view_note("meetings/weekly-standup")
+
+        # View with pagination
+        view_note("large-document", page=2, page_size=5)
+
+        # Explicit project specification
+        view_note("Meeting Notes", project="my-project")
+
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If identifier attempts path traversal
+    """
+    track_mcp_tool("view_note")
+    logger.info(f"Viewing note: {identifier} in project: {project}")
+
+    # Call the existing read_note logic
+    content = await read_note.fn(identifier, project, page, page_size, context)
+
+    # Check if this is an error message (note not found)
+    if "# Note Not Found" in content:
+        return content  # Return error message directly
+
+    # Return instructions for Claude to create an artifact
+    return dedent(f"""
+        Note retrieved: "{identifier}"
+        
+        Display this note as a markdown artifact for the user.
+    
+        Content:
+        ---
+        {content}
+        ---
+        """).strip()