Add MCP output_format json mode across memory tools

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

README.md

@@ -418,19 +418,19 @@ basic-memory tool edit-note docs/setup --operation append --content $'\n- Added
 
 **Content Management:**
 ```
-write_note(title, content, folder, tags) - Create or update notes
-read_note(identifier, page, page_size) - Read notes by title or permalink
+write_note(title, content, folder, tags, output_format="text"|"json") - Create or update notes
+read_note(identifier, page, page_size, output_format="text"|"json") - Read notes by title or permalink
 read_content(path) - Read raw file content (text, images, binaries)
 view_note(identifier) - View notes as formatted artifacts
-edit_note(identifier, operation, content) - Edit notes incrementally
-move_note(identifier, destination_path) - Move notes with database consistency
-delete_note(identifier) - Delete notes from knowledge base
+edit_note(identifier, operation, content, output_format="text"|"json") - Edit notes incrementally
+move_note(identifier, destination_path, output_format="text"|"json") - Move notes with database consistency
+delete_note(identifier, output_format="text"|"json") - Delete notes from knowledge base
 ```
 
 **Knowledge Graph Navigation:**
 ```
-build_context(url, depth, timeframe) - Navigate knowledge graph via memory:// URLs
-recent_activity(type, depth, timeframe) - Find recently updated information
+build_context(url, depth, timeframe, output_format="json"|"text") - Navigate knowledge graph via memory:// URLs
+recent_activity(type, depth, timeframe, output_format="text"|"json") - Find recently updated information
 list_directory(dir_name, depth) - Browse directory contents with filtering
 ```
 
@@ -443,12 +443,15 @@ search_by_metadata(filters, limit, offset, project) - Structured frontmatter sea
 
 **Project Management:**
 ```
-list_memory_projects() - List all available projects
-create_memory_project(project_name, project_path) - Create new projects
+list_memory_projects(output_format="text"|"json") - List all available projects
+create_memory_project(project_name, project_path, output_format="text"|"json") - Create new projects
 get_current_project() - Show current project stats
 sync_status() - Check synchronization status
 ```
 
+`output_format` defaults to `"text"` for these tools, preserving current human-readable responses.
+`build_context` defaults to `"json"` and can be switched to `"text"` when compact markdown output is preferred.
+
 **Cloud Discovery (opt-in):**
 ```
 cloud_info() - Show optional Cloud overview and setup guidance

docs/mcp-ui-bakeoff-instructions.md

@@ -83,18 +83,26 @@ Manual check:
 
 ---
 
-### 2) ASCII / ANSI TUI Output
+### 2) Text / JSON Output Modes
 
 Tools:
-- `search_notes(output_format="ascii" | "ansi")`
-- `read_note(output_format="ascii" | "ansi")`
+- `search_notes(output_format="text" | "json")`
+- `read_note(output_format="text" | "json")`
+- `write_note(output_format="text" | "json")`
+- `edit_note(output_format="text" | "json")`
+- `recent_activity(output_format="text" | "json")`
+- `list_memory_projects(output_format="text" | "json")`
+- `create_memory_project(output_format="text" | "json")`
+- `delete_note(output_format="text" | "json")`
+- `move_note(output_format="text" | "json")`
+- `build_context(output_format="json" | "text")`
 
 Expect:
-- ASCII table for search, header + content preview for note.
-- ANSI variants include color escape codes.
+- `text` mode preserves existing human-readable responses.
+- `json` mode returns structured dict/list payloads for machine-readable clients.
 
 Automated:
-- `uv run pytest test-int/mcp/test_output_format_ascii_integration.py`
+- `uv run pytest test-int/mcp/test_output_format_json_integration.py`
 
 ---
 
@@ -125,6 +133,6 @@ Fill in after running:
 
 - Tool‑UI (React): __
 - MCP‑UI SDK (embedded): __
-- ASCII/ANSI: __
+- Text/JSON modes: __
 
 Decision + rationale: __

docs/post-v0.18.0-test-plan.md

@@ -180,7 +180,7 @@ Key finding: **FastEmbed (384-d local ONNX) matches or exceeds OpenAI (1536-d) q
 ### Existing coverage anchor points
 
 - `tests/mcp/test_tool_contracts.py`
-- `test-int/mcp/test_output_format_ascii_integration.py`
+- `test-int/mcp/test_output_format_json_integration.py`
 - `test-int/mcp/test_ui_sdk_integration.py`
 
 ### Gaps to close — DONE
@@ -288,7 +288,7 @@ Run after automated tests pass.
 - Routing: verify success/failure paths with and without API key.
 - Permalink routing: read/write/search notes across projects with colliding titles.
 - Permalink routing: verify memory URL routing correctness.
-- UI/TUI: call `search_notes` and `read_note` with UI variants and `output_format=ascii|ansi`.
+- UI/TUI: call `search_notes` and `read_note` with UI variants and `output_format=text|json`.
 - UI/TUI: verify payload/resource format and metadata completeness.
 
 ## Implementation Backlog (Ordered)

src/basic_memory/cli/commands/tool.py

@@ -160,11 +160,14 @@ async def _read_note_json(
                 search_type="title",
                 project=project_name,
                 workspace=workspace,
+                output_format="json",
             )
-            if title_results and hasattr(title_results, "results") and title_results.results:
-                result = title_results.results[0]
-                if result.permalink:
-                    entity_id = await knowledge_client.resolve_entity(result.permalink)
+            results = title_results.get("results", []) if isinstance(title_results, dict) else []
+            if results:
+                result = results[0]
+                permalink = result.get("permalink")
+                if permalink:
+                    entity_id = await knowledge_client.resolve_entity(permalink)
 
         if entity_id is None:
             raise ValueError(f"Could not find note matching: {identifier}")
@@ -635,10 +638,13 @@ def build_context(
                     page=page,
                     page_size=page_size,
                     max_related=max_related,
+                    output_format="text" if format == "text" else "json",
                 )
             )
-        # build_context now returns a slimmed dict (already serializable)
-        print(json.dumps(result, indent=2, ensure_ascii=True, default=str))
+        if format == "json":
+            print(json.dumps(result, indent=2, ensure_ascii=True, default=str))
+        else:
+            print(result)
     except ValueError as e:
         typer.echo(f"Error: {e}", err=True)
         raise typer.Exit(1)

src/basic_memory/mcp/tools/build_context.py

@@ -1,6 +1,6 @@
 """Build context tool for Basic Memory MCP server."""
 
-from typing import Optional
+from typing import Optional, Literal
 
 from loguru import logger
 from fastmcp import Context
@@ -190,7 +190,7 @@ def _format_context_markdown(graph: GraphContext, project: str) -> str:
 
     Format options:
     - "json" (default): Slimmed JSON with redundant fields removed
-    - "markdown": Compact markdown text for LLM consumption
+    - "text": Compact markdown text for LLM consumption
     """,
 )
 async def build_context(
@@ -202,7 +202,7 @@ async def build_context(
     page: int = 1,
     page_size: int = 10,
     max_related: int = 10,
-    format: str = "json",
+    output_format: Literal["json", "text"] = "json",
     context: Context | None = None,
 ) -> dict | str:
     """Get context needed to continue a discussion within a specific project.
@@ -225,12 +225,13 @@ async def build_context(
         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)
-        format: Response format - "json" for slimmed JSON dict, "markdown" for compact text
+        output_format: Response format - "json" for slimmed JSON dict,
+            "text" for compact markdown text
         context: Optional FastMCP context for performance caching.
 
     Returns:
-        dict (format="json"): Slimmed JSON with redundant fields removed
-        str (format="markdown"): Compact markdown representation
+        dict (output_format="json"): Slimmed JSON with redundant fields removed
+        str (output_format="text"): Compact markdown representation
 
     Examples:
         # Continue a specific discussion
@@ -239,8 +240,8 @@ async def build_context(
         # Get deeper context about a component
         build_context("work-docs", "memory://components/memory-service", depth=2)
 
-        # Get markdown output for compact context
-        build_context("research", "memory://specs/search", format="markdown")
+        # Get text output for compact context
+        build_context("research", "memory://specs/search", output_format="text")
 
     Raises:
         ToolError: If project doesn't exist or depth parameter is invalid
@@ -276,7 +277,7 @@ async def build_context(
             max_related=max_related,
         )
 
-        if format == "markdown":
+        if output_format == "text":
             return _format_context_markdown(graph, active_project.name)
 
         return _slim_context(graph)

src/basic_memory/mcp/tools/chatgpt_tools.py

@@ -13,22 +13,41 @@
 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.schemas.search import SearchResponse, SearchResult
 
 
-def _format_search_results_for_chatgpt(results: SearchResponse) -> List[Dict[str, Any]]:
+def _format_search_results_for_chatgpt(
+    results: SearchResponse | list[SearchResult] | list[dict[str, Any]] | dict[str, Any],
+) -> 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.
     """
+    if isinstance(results, SearchResponse):
+        raw_results: list[SearchResult] | list[dict[str, Any]] = results.results
+    elif isinstance(results, dict):
+        nested_results = results.get("results")
+        raw_results = nested_results if isinstance(nested_results, list) else []
+    else:
+        raw_results = results
+
     formatted_results = []
 
-    for result in results.results:
+    for result in raw_results:
+        if isinstance(result, SearchResult):
+            title = result.title
+            permalink = result.permalink
+        elif isinstance(result, dict):
+            title = result.get("title")
+            permalink = result.get("permalink")
+        else:
+            raise TypeError(f"Unexpected result type: {type(result).__name__}")
+
         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 "",
+            "id": permalink or f"doc-{len(formatted_results)}",
+            "title": title if isinstance(title, str) and title.strip() else "Untitled",
+            "url": permalink or "",
         }
         formatted_results.append(formatted_result)
 
@@ -102,6 +121,7 @@ async def search(
             page=1,
             page_size=10,  # Reasonable default for ChatGPT consumption
             search_type="text",  # Default to full-text search
+            output_format="json",
             context=context,
         )
 
@@ -115,10 +135,11 @@ async def search(
             }
         else:
             # Format successful results for ChatGPT
-            formatted_results = _format_search_results_for_chatgpt(results)
+            raw_results = results.get("results", []) if isinstance(results, dict) else []
+            formatted_results = _format_search_results_for_chatgpt(raw_results)
             search_results = {
                 "results": formatted_results,
-                "total_count": len(results.results),  # Use actual count from results
+                "total_count": len(raw_results),  # Use actual count from results
                 "query": query,
             }
             logger.info(f"Search completed: {len(formatted_results)} results returned")

src/basic_memory/mcp/tools/delete_note.py

@@ -1,5 +1,5 @@
 from textwrap import dedent
-from typing import Optional
+from typing import Optional, Literal
 
 from loguru import logger
 from fastmcp import Context
@@ -152,8 +152,9 @@ async def delete_note(
     is_directory: bool = False,
     project: Optional[str] = None,
     workspace: Optional[str] = None,
+    output_format: Literal["text", "json"] = "text",
     context: Context | None = None,
-) -> bool | str:
+) -> bool | str | dict:
     """Delete a note or directory from the knowledge base.
 
     Permanently removes a note or directory from the specified project. For single notes,
@@ -174,6 +175,8 @@ async def delete_note(
                      (without file extensions). Defaults to False.
         project: Project name to delete from. Optional - server will resolve using hierarchy.
                 If unknown, use list_memory_projects() to discover available projects.
+        output_format: "text" preserves existing behavior (bool/string). "json"
+            returns machine-readable deletion metadata.
         context: Optional FastMCP context for performance caching.
 
     Returns:
@@ -231,6 +234,15 @@ async def delete_note(
         if is_directory:
             try:
                 result = await knowledge_client.delete_directory(identifier)
+                if output_format == "json":
+                    return {
+                        "deleted": result.failed_deletes == 0,
+                        "is_directory": True,
+                        "identifier": identifier,
+                        "total_files": result.total_files,
+                        "successful_deletes": result.successful_deletes,
+                        "failed_deletes": result.failed_deletes,
+                    }
 
                 # Build success message for directory delete
                 result_lines = [
@@ -288,18 +300,41 @@ async def delete_note(
 ```"""
 
         # Handle single note deletes
+        note_title = None
+        note_permalink = None
+        note_file_path = None
         try:
             # Resolve identifier to entity ID
             entity_id = await knowledge_client.resolve_entity(identifier)
+            if output_format == "json":
+                entity = await knowledge_client.get_entity(entity_id)
+                note_title = entity.title
+                note_permalink = entity.permalink
+                note_file_path = entity.file_path
         except ToolError as e:
             # If entity not found, return False (note doesn't exist)
             if "Entity not found" in str(e) or "not found" in str(e).lower():
                 logger.warning(f"Note not found for deletion: {identifier}")
+                if output_format == "json":
+                    return {
+                        "deleted": False,
+                        "title": None,
+                        "permalink": None,
+                        "file_path": None,
+                    }
                 return False
             # For other resolution errors, return formatted error message
             logger.error(  # pragma: no cover
                 f"Delete failed for '{identifier}': {e}, project: {active_project.name}"
             )
+            if output_format == "json":
+                return {
+                    "deleted": False,
+                    "title": None,
+                    "permalink": None,
+                    "file_path": None,
+                    "error": str(e),
+                }
             return _format_delete_error_response(  # pragma: no cover
                 active_project.name, str(e), identifier
             )
@@ -312,14 +347,36 @@ async def delete_note(
                 logger.info(
                     f"Successfully deleted note: {identifier} in project: {active_project.name}"
                 )
+                if output_format == "json":
+                    return {
+                        "deleted": True,
+                        "title": note_title,
+                        "permalink": note_permalink,
+                        "file_path": note_file_path,
+                    }
                 return True
             else:
                 logger.warning(  # pragma: no cover
                     f"Delete operation completed but note was not deleted: {identifier}"
                 )
+                if output_format == "json":
+                    return {
+                        "deleted": False,
+                        "title": note_title,
+                        "permalink": note_permalink,
+                        "file_path": note_file_path,
+                    }
                 return False  # pragma: no cover
 
         except Exception as e:  # pragma: no cover
             logger.error(f"Delete failed for '{identifier}': {e}, project: {active_project.name}")
+            if output_format == "json":
+                return {
+                    "deleted": False,
+                    "title": note_title,
+                    "permalink": note_permalink,
+                    "file_path": note_file_path,
+                    "error": str(e),
+                }
             # Return formatted error message for better user experience
             return _format_delete_error_response(active_project.name, str(e), identifier)