merge latest from upstream

Author: groksrc

src/basic_memory/mcp/tools/chatgpt_tools.py

@@ -1,14 +1,8 @@
 """ChatGPT-compatible MCP tools for Basic Memory.
 
-This module provides simplified 'search' and 'fetch' tools that adapt Basic Memory's
-rich MCP interface to ChatGPT's expected naming conventions and MCP content array format.
-
-ChatGPT's MCP integration expects:
-- search(query: str) -> MCP content array with JSON-encoded results
-- fetch(id: str) -> MCP content array with JSON-encoded document
-
-These tools wrap our existing search_notes and read_note functions and format
-responses according to OpenAI's MCP specification.
+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
@@ -83,27 +77,15 @@ async def search(
     query: str,
     context: Context | None = None,
 ) -> List[Dict[str, Any]]:
-    """Search for content across the knowledge base.
-
-    This tool provides a simplified search interface optimized for ChatGPT's
-    MCP integration. It returns results in the required MCP content array format.
+    """ChatGPT/OpenAI MCP search adapter returning a single text content item.
 
     Args:
-        query: Search query string (supports boolean operators, phrases)
-        context: MCP context for authentication and routing
+        query: Search query (full-text syntax supported by `search_notes`)
+        context: Optional FastMCP context passed through for auth/session data
 
     Returns:
-        MCP content array with exactly one item containing JSON-encoded search results
-
-    The response follows OpenAI's MCP specification:
-    {
-        "content": [
-            {
-                "type": "text",
-                "text": "{\"results\":[{\"id\":\"doc-1\",\"title\":\"...\",\"url\":\"...\"}]}"
-            }
-        ]
-    }
+        List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
+        where the JSON body contains `results`, `total_count`, and echo of `query`.
     """
     logger.info(f"ChatGPT search request: query='{query}'")
 
@@ -165,27 +147,15 @@ async def fetch(
     id: str,
     context: Context | None = None,
 ) -> List[Dict[str, Any]]:
-    """Fetch the full content of a specific document.
-
-    This tool provides a simplified fetch interface optimized for ChatGPT's
-    MCP integration. It returns document content in the required MCP content array format.
+    """ChatGPT/OpenAI MCP fetch adapter returning a single text content item.
 
     Args:
-        id: Document identifier (permalink, title, or memory:// URL)
-        context: MCP context for authentication and routing
+        id: Document identifier (permalink, title, or memory URL)
+        context: Optional FastMCP context passed through for auth/session data
 
     Returns:
-        MCP content array with exactly one item containing JSON-encoded document
-
-    The response follows OpenAI's MCP specification:
-    {
-        "content": [
-            {
-                "type": "text",
-                "text": "{\"id\":\"doc-1\",\"title\":\"...\",\"text\":\"full text...\",\"url\":\"...\",\"metadata\":{}}"
-            }
-        ]
-    }
+        List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
+        where the JSON body includes `id`, `title`, `text`, `url`, and metadata.
     """
     logger.info(f"ChatGPT fetch request: id='{id}'")
 
@@ -225,4 +195,4 @@ async def fetch(
                 "type": "text",
                 "text": json.dumps(error_document, ensure_ascii=False)
             }
-        ]
+        ]

src/basic_memory/mcp/tools/read_note.py

@@ -25,7 +25,7 @@ async def read_note(
     page_size: int = 10,
     context: Context | None = None,
 ) -> str:
-    """Read a markdown note from the knowledge base.
+    """Return the raw markdown for a note, or guidance text if no match is found.
 
     Finds and retrieves a note by its title, permalink, or content search,
     returning the raw markdown content including observations, relations, and metadata.
@@ -171,25 +171,25 @@ def format_not_found_message(project: str | None, identifier: str) -> str:
     """Format a helpful message when no note was found."""
     return dedent(f"""
         # Note Not Found in {project}: "{identifier}"
-        
+
         I couldn't find any notes matching "{identifier}". Here are some suggestions:
-        
+
         ## Check Identifier Type
         - If you provided a title, try using the exact permalink instead
         - If you provided a permalink, check for typos or try a broader search
-        
+
         ## Search Instead
         Try searching for related content:
         ```
         search_notes(project="{project}", query="{identifier}")
         ```
-        
+
         ## Recent Activity
         Check recently modified notes:
         ```
         recent_activity(timeframe="7d")
         ```
-        
+
         ## Create New Note
         This might be a good opportunity to create a new note on this topic:
         ```
@@ -198,13 +198,13 @@ def format_not_found_message(project: str | None, identifier: str) -> str:
             title="{identifier.capitalize()}",
             content='''
             # {identifier.capitalize()}
-            
+
             ## Overview
             [Your content here]
-            
+
             ## Observations
             - [category] [Observation about {identifier}]
-            
+
             ## Relations
             - relates_to [[Related Topic]]
             ''',
@@ -218,34 +218,34 @@ def format_related_results(project: str | None, identifier: str, results) -> str
     """Format a helpful message with related results when an exact match wasn't found."""
     message = dedent(f"""
         # Note Not Found in {project}: "{identifier}"
-        
+
         I couldn't find an exact match for "{identifier}", but I found some related notes:
-        
+
         """)
 
     for i, result in enumerate(results):
         message += dedent(f"""
             ## {i + 1}. {result.title}
             - **Type**: {result.type.value}
             - **Permalink**: {result.permalink}
-            
+
             You can read this note with:
             ```
             read_note(project="{project}", {result.permalink}")
             ```
-            
+
             """)
 
     message += dedent(f"""
         ## Try More Specific Lookup
         For exact matches, try using the full permalink from one of the results above.
-        
+
         ## Search For More Results
         To see more related content:
         ```
         search_notes(project="{project}", query="{identifier}")
         ```
-        
+
         ## Create New Note
         If none of these match what you're looking for, consider creating a new note:
         ```