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

basic_memory/mcp/tools/__init__.py

@@ -6,31 +6,43 @@ all tools with the MCP server.
 """
 
 # Import tools to register them with MCP
-from basic_memory.mcp.tools.memory import build_context, recent_activity
-
-# from basic_memory.mcp.tools.ai_edit import ai_edit
-from basic_memory.mcp.tools.notes import read_note, write_note
-from basic_memory.mcp.tools.search import search
-
-from basic_memory.mcp.tools.knowledge import (
-    delete_entities,
-    get_entity,
-    get_entities,
+from basic_memory.mcp.tools.delete_note import delete_note
+from basic_memory.mcp.tools.read_content import read_content
+from basic_memory.mcp.tools.build_context import build_context
+from basic_memory.mcp.tools.recent_activity import recent_activity
+from basic_memory.mcp.tools.read_note import read_note
+from basic_memory.mcp.tools.view_note import view_note
+from basic_memory.mcp.tools.write_note import write_note
+from basic_memory.mcp.tools.search import search_notes
+from basic_memory.mcp.tools.canvas import canvas
+from basic_memory.mcp.tools.list_directory import list_directory
+from basic_memory.mcp.tools.edit_note import edit_note
+from basic_memory.mcp.tools.move_note import move_note
+from basic_memory.mcp.tools.project_management import (
+    list_memory_projects,
+    create_memory_project,
+    delete_project,
 )
 
+# ChatGPT-compatible tools
+from basic_memory.mcp.tools.chatgpt_tools import search, fetch
+
 __all__ = [
-    # Knowledge graph tools
-    "delete_entities",
-    "get_entity",
-    "get_entities",
-    # Search tools
-    "search",
-    # memory tools
     "build_context",
-    "recent_activity",
-    # notes
+    "canvas",
+    "create_memory_project",
+    "delete_note",
+    "delete_project",
+    "edit_note",
+    "fetch",
+    "list_directory",
+    "list_memory_projects",
+    "move_note",
+    "read_content",
     "read_note",
+    "recent_activity",
+    "search",
+    "search_notes",
+    "view_note",
     "write_note",
-    # file edit
-    # "ai_edit",
 ]

basic_memory/mcp/tools/build_context.py

@@ -0,0 +1,120 @@
+"""Build context tool for Basic Memory MCP server."""
+
+from typing import Optional
+
+from loguru import logger
+from fastmcp import Context
+
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.project_context import get_active_project
+from basic_memory.mcp.server import mcp
+from basic_memory.telemetry import track_mcp_tool
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import (
+    GraphContext,
+    MemoryUrl,
+    memory_url_path,
+)
+
+
+@mcp.tool(
+    description="""Build context from a memory:// URI to continue conversations naturally.
+
+    Use this to follow up on previous discussions or explore related topics.
+
+    Memory URL Format:
+    - Use paths like "folder/note" or "memory://folder/note"
+    - Pattern matching: "folder/*" matches all notes in folder
+    - Valid characters: letters, numbers, hyphens, underscores, forward slashes
+    - Avoid: double slashes (//), angle brackets (<>), quotes, pipes (|)
+    - Examples: "specs/search", "projects/basic-memory", "notes/*"
+
+    Timeframes support natural language like:
+    - "2 days ago", "last week", "today", "3 months ago"
+    - Or standard formats like "7d", "24h"
+    """,
+)
+async def build_context(
+    url: MemoryUrl,
+    project: Optional[str] = None,
+    depth: str | int | None = 1,
+    timeframe: Optional[TimeFrame] = "7d",
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
+    context: Context | None = None,
+) -> GraphContext:
+    """Get context needed to continue a discussion within a specific project.
+
+    This tool enables natural continuation of discussions by loading relevant context
+    from memory:// URIs. It uses pattern matching to find relevant content and builds
+    a rich context graph of related information.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
+    Args:
+        project: Project name to build context from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        url: memory:// URI pointing to discussion content (e.g. memory://specs/search)
+        depth: How many relation hops to traverse (1-3 recommended for performance)
+        timeframe: How far back to look. Supports natural language like "2 days ago", "last week"
+        page: Page number of results to return (default: 1)
+        page_size: Number of results to return per page (default: 10)
+        max_related: Maximum number of related results to return (default: 10)
+        context: Optional FastMCP context for performance caching.
+
+    Returns:
+        GraphContext containing:
+            - primary_results: Content matching the memory:// URI
+            - related_results: Connected content via relations
+            - metadata: Context building details
+
+    Examples:
+        # Continue a specific discussion
+        build_context("my-project", "memory://specs/search")
+
+        # Get deeper context about a component
+        build_context("work-docs", "memory://components/memory-service", depth=2)
+
+        # Look at recent changes to a specification
+        build_context("research", "memory://specs/document-format", timeframe="today")
+
+        # Research the history of a feature
+        build_context("dev-notes", "memory://features/knowledge-graph", timeframe="3 months ago")
+
+    Raises:
+        ToolError: If project doesn't exist or depth parameter is invalid
+    """
+    track_mcp_tool("build_context")
+    logger.info(f"Building context from {url} in project {project}")
+
+    # Convert string depth to integer if needed
+    if isinstance(depth, str):
+        try:
+            depth = int(depth)
+        except ValueError:
+            from mcp.server.fastmcp.exceptions import ToolError
+
+            raise ToolError(f"Invalid depth parameter: '{depth}' is not a valid integer")
+
+    # URL is already validated and normalized by MemoryUrl type annotation
+
+    async with get_client() as client:
+        # Get the active project using the new stateless approach
+        active_project = await get_active_project(client, project, context)
+
+        # Import here to avoid circular import
+        from basic_memory.mcp.clients import MemoryClient
+
+        # Use typed MemoryClient for API calls
+        memory_client = MemoryClient(client, active_project.external_id)
+        return await memory_client.build_context(
+            memory_url_path(url),
+            depth=depth or 1,
+            timeframe=timeframe,
+            page=page,
+            page_size=page_size,
+            max_related=max_related,
+        )

basic_memory/mcp/tools/canvas.py

@@ -0,0 +1,152 @@
+"""Canvas creation tool for Basic Memory MCP server.
+
+This tool creates Obsidian canvas files (.canvas) using the JSON Canvas 1.0 spec.
+"""
+
+import json
+from typing import Dict, List, Any, Optional
+
+from loguru import logger
+from fastmcp import Context
+
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.project_context import get_active_project
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.utils import call_put, call_post, resolve_entity_id
+from basic_memory.telemetry import track_mcp_tool
+
+
+@mcp.tool(
+    description="Create an Obsidian canvas file to visualize concepts and connections.",
+)
+async def canvas(
+    nodes: List[Dict[str, Any]],
+    edges: List[Dict[str, Any]],
+    title: str,
+    folder: str,
+    project: Optional[str] = None,
+    context: Context | None = None,
+) -> str:
+    """Create an Obsidian canvas file with the provided nodes and edges.
+
+    This tool creates a .canvas file compatible with Obsidian's Canvas feature,
+    allowing visualization of relationships between concepts or documents.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
+    For the full JSON Canvas 1.0 specification, see the 'spec://canvas' resource.
+
+    Args:
+        project: Project name to create canvas in. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        nodes: List of node objects following JSON Canvas 1.0 spec
+        edges: List of edge objects following JSON Canvas 1.0 spec
+        title: The title of the canvas (will be saved as title.canvas)
+        folder: Folder path relative to project root where the canvas should be saved.
+                Use forward slashes (/) as separators. Examples: "diagrams", "projects/2025", "visual/maps"
+        context: Optional FastMCP context for performance caching.
+
+    Returns:
+        A summary of the created canvas file
+
+    Important Notes:
+    - When referencing files, use the exact file path as shown in Obsidian
+      Example: "folder/Document Name.md" (not permalink format)
+    - For file nodes, the "file" attribute must reference an existing file
+    - Nodes require id, type, x, y, width, height properties
+    - Edges require id, fromNode, toNode properties
+    - Position nodes in a logical layout (x,y coordinates in pixels)
+    - Use color attributes ("1"-"6" or hex) for visual organization
+
+    Basic Structure:
+    ```json
+    {
+      "nodes": [
+        {
+          "id": "node1",
+          "type": "file",  // Options: "file", "text", "link", "group"
+          "file": "folder/Document.md",
+          "x": 0,
+          "y": 0,
+          "width": 400,
+          "height": 300
+        }
+      ],
+      "edges": [
+        {
+          "id": "edge1",
+          "fromNode": "node1",
+          "toNode": "node2",
+          "label": "connects to"
+        }
+      ]
+    }
+    ```
+
+    Examples:
+        # Create canvas in project
+        canvas("my-project", nodes=[...], edges=[...], title="My Canvas", folder="diagrams")
+
+        # Create canvas in work project
+        canvas("work-project", nodes=[...], edges=[...], title="Process Flow", folder="visual/maps")
+
+    Raises:
+        ToolError: If project doesn't exist or folder path is invalid
+    """
+    track_mcp_tool("canvas")
+    async with get_client() as client:
+        active_project = await get_active_project(client, project, context)
+
+        # Ensure path has .canvas extension
+        file_title = title if title.endswith(".canvas") else f"{title}.canvas"
+        file_path = f"{folder}/{file_title}"
+
+        # Create canvas data structure
+        canvas_data = {"nodes": nodes, "edges": edges}
+
+        # Convert to JSON
+        canvas_json = json.dumps(canvas_data, indent=2)
+
+        # Try to create the canvas file first (optimistic create)
+        logger.info(f"Creating canvas file: {file_path} in project {project}")
+        try:
+            response = await call_post(
+                client,
+                f"/v2/projects/{active_project.external_id}/resource",
+                json={"file_path": file_path, "content": canvas_json},
+            )
+            action = "Created"
+        except Exception as e:
+            # If creation failed due to conflict (already exists), try to update
+            if (
+                "409" in str(e)
+                or "conflict" in str(e).lower()
+                or "already exists" in str(e).lower()
+            ):
+                logger.info(f"Canvas file exists, updating instead: {file_path}")
+                try:
+                    entity_id = await resolve_entity_id(client, active_project.external_id, file_path)
+                    # For update, send content in JSON body
+                    response = await call_put(
+                        client,
+                        f"/v2/projects/{active_project.external_id}/resource/{entity_id}",
+                        json={"content": canvas_json},
+                    )
+                    action = "Updated"
+                except Exception as update_error:  # pragma: no cover
+                    # Re-raise the original error if update also fails
+                    raise e from update_error  # pragma: no cover
+            else:
+                # Re-raise if it's not a conflict error
+                raise  # pragma: no cover
+
+        # Parse response
+        result = response.json()
+        logger.debug(result)
+
+        # Build summary
+        summary = [f"# {action}: {file_path}", "\nThe canvas is ready to open in Obsidian."]
+
+        return "\n".join(summary)

basic_memory/mcp/tools/chatgpt_tools.py

@@ -0,0 +1,190 @@
+"""ChatGPT-compatible MCP tools for Basic Memory.
+
+These adapters expose Basic Memory's search/fetch functionality using the exact
+tool names and response structure OpenAI's MCP clients expect: each call returns
+a list containing a single `{"type": "text", "text": "{...json...}"}` item.
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+from loguru import logger
+from fastmcp import Context
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.search import search_notes
+from basic_memory.mcp.tools.read_note import read_note
+from basic_memory.schemas.search import SearchResponse
+from basic_memory.config import ConfigManager
+from basic_memory.telemetry import track_mcp_tool
+
+
+def _format_search_results_for_chatgpt(results: SearchResponse) -> List[Dict[str, Any]]:
+    """Format search results according to ChatGPT's expected schema.
+
+    Returns a list of result objects with id, title, and url fields.
+    """
+    formatted_results = []
+
+    for result in results.results:
+        formatted_result = {
+            "id": result.permalink or f"doc-{len(formatted_results)}",
+            "title": result.title if result.title and result.title.strip() else "Untitled",
+            "url": result.permalink or "",
+        }
+        formatted_results.append(formatted_result)
+
+    return formatted_results
+
+
+def _format_document_for_chatgpt(
+    content: str, identifier: str, title: Optional[str] = None
+) -> Dict[str, Any]:
+    """Format document content according to ChatGPT's expected schema.
+
+    Returns a document object with id, title, text, url, and metadata fields.
+    """
+    # Extract title from markdown content if not provided
+    if not title and isinstance(content, str):
+        lines = content.split("\n")
+        if lines and lines[0].startswith("# "):
+            title = lines[0][2:].strip()
+        else:
+            title = identifier.split("/")[-1].replace("-", " ").title()
+
+    # Ensure title is never None
+    if not title:
+        title = "Untitled Document"
+
+    # Handle error cases
+    if isinstance(content, str) and content.lstrip().startswith("# Note Not Found"):
+        return {
+            "id": identifier,
+            "title": title or "Document Not Found",
+            "text": content,
+            "url": identifier,
+            "metadata": {"error": "Document not found"},
+        }
+
+    return {
+        "id": identifier,
+        "title": title or "Untitled Document",
+        "text": content,
+        "url": identifier,
+        "metadata": {"format": "markdown"},
+    }
+
+
+@mcp.tool(description="Search for content across the knowledge base")
+async def search(
+    query: str,
+    context: Context | None = None,
+) -> List[Dict[str, Any]]:
+    """ChatGPT/OpenAI MCP search adapter returning a single text content item.
+
+    Args:
+        query: Search query (full-text syntax supported by `search_notes`)
+        context: Optional FastMCP context passed through for auth/session data
+
+    Returns:
+        List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
+        where the JSON body contains `results`, `total_count`, and echo of `query`.
+    """
+    track_mcp_tool("search")
+    logger.info(f"ChatGPT search request: query='{query}'")
+
+    try:
+        # ChatGPT tools don't expose project parameter, so use default project
+        config = ConfigManager().config
+        default_project = config.default_project
+
+        # Call underlying search_notes with sensible defaults for ChatGPT
+        results = await search_notes.fn(
+            query=query,
+            project=default_project,  # Use default project for ChatGPT
+            page=1,
+            page_size=10,  # Reasonable default for ChatGPT consumption
+            search_type="text",  # Default to full-text search
+            context=context,
+        )
+
+        # Handle string error responses from search_notes
+        if isinstance(results, str):
+            logger.warning(f"Search failed with error: {results[:100]}...")
+            search_results = {
+                "results": [],
+                "error": "Search failed",
+                "error_details": results[:500],  # Truncate long error messages
+            }
+        else:
+            # Format successful results for ChatGPT
+            formatted_results = _format_search_results_for_chatgpt(results)
+            search_results = {
+                "results": formatted_results,
+                "total_count": len(results.results),  # Use actual count from results
+                "query": query,
+            }
+            logger.info(f"Search completed: {len(formatted_results)} results returned")
+
+        # Return in MCP content array format as required by OpenAI
+        return [{"type": "text", "text": json.dumps(search_results, ensure_ascii=False)}]
+
+    except Exception as e:
+        logger.error(f"ChatGPT search failed for query '{query}': {e}")
+        error_results = {
+            "results": [],
+            "error": "Internal search error",
+            "error_message": str(e)[:200],
+        }
+        return [{"type": "text", "text": json.dumps(error_results, ensure_ascii=False)}]
+
+
+@mcp.tool(description="Fetch the full contents of a search result document")
+async def fetch(
+    id: str,
+    context: Context | None = None,
+) -> List[Dict[str, Any]]:
+    """ChatGPT/OpenAI MCP fetch adapter returning a single text content item.
+
+    Args:
+        id: Document identifier (permalink, title, or memory URL)
+        context: Optional FastMCP context passed through for auth/session data
+
+    Returns:
+        List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
+        where the JSON body includes `id`, `title`, `text`, `url`, and metadata.
+    """
+    track_mcp_tool("fetch")
+    logger.info(f"ChatGPT fetch request: id='{id}'")
+
+    try:
+        # ChatGPT tools don't expose project parameter, so use default project
+        config = ConfigManager().config
+        default_project = config.default_project
+
+        # Call underlying read_note function
+        content = await read_note.fn(
+            identifier=id,
+            project=default_project,  # Use default project for ChatGPT
+            page=1,
+            page_size=10,  # Default pagination
+            context=context,
+        )
+
+        # Format the document for ChatGPT
+        document = _format_document_for_chatgpt(content, id)
+
+        logger.info(f"Fetch completed: id='{id}', content_length={len(document.get('text', ''))}")
+
+        # Return in MCP content array format as required by OpenAI
+        return [{"type": "text", "text": json.dumps(document, ensure_ascii=False)}]
+
+    except Exception as e:
+        logger.error(f"ChatGPT fetch failed for id '{id}': {e}")
+        error_document = {
+            "id": id,
+            "title": "Fetch Error",
+            "text": f"Failed to fetch document: {str(e)[:200]}",
+            "url": id,
+            "metadata": {"error": "Fetch failed"},
+        }
+        return [{"type": "text", "text": json.dumps(error_document, ensure_ascii=False)}]