"""Edit note tool for Basic Memory MCP server.""" from typing import Optional from loguru import logger from basic_memory.mcp.async_client import client from basic_memory.mcp.project_session import get_active_project from basic_memory.mcp.server import mcp from basic_memory.mcp.tools.utils import call_patch from basic_memory.schemas import EntityResponse def _format_error_response( error_message: str, operation: str, identifier: str, find_text: Optional[str] = None, expected_replacements: int = 1, ) -> str: """Format helpful error responses for edit_note failures that guide the AI to retry successfully.""" # Entity not found errors if "Entity not found" in error_message or "entity not found" in error_message.lower(): return f"""# Edit Failed - Note Not Found The note with identifier '{identifier}' could not be found. Edit operations require an exact match (no fuzzy matching). ## Suggestions to try: 1. **Search for the note first**: Use `search_notes("{identifier.split("/")[-1]}")` to find similar notes with exact identifiers 2. **Try different exact identifier formats**: - If you used a permalink like "folder/note-title", try the exact title: "{identifier.split("/")[-1].replace("-", " ").title()}" - If you used a title, try the exact permalink format: "{identifier.lower().replace(" ", "-")}" - Use `read_note()` first to verify the note exists and get the exact identifier ## Alternative approach: Use `write_note()` to create the note first, then edit it.""" # Find/replace specific errors if operation == "find_replace": if "Text to replace not found" in error_message: return f"""# Edit Failed - Text Not Found The text '{find_text}' was not found in the note '{identifier}'. ## Suggestions to try: 1. **Read the note first**: Use `read_note("{identifier}")` to see the current content 2. **Check for exact matches**: The search is case-sensitive and must match exactly 3. **Try a broader search**: Search for just part of the text you want to replace 4. **Use expected_replacements=0**: If you want to verify the text doesn't exist ## Alternative approaches: - Use `append` or `prepend` to add new content instead - Use `replace_section` if you're trying to update a specific section""" if "Expected" in error_message and "occurrences" in error_message: # Extract the actual count from error message if possible import re match = re.search(r"found (\d+)", error_message) actual_count = match.group(1) if match else "a different number of" return f"""# Edit Failed - Wrong Replacement Count Expected {expected_replacements} occurrences of '{find_text}' but found {actual_count}. ## How to fix: 1. **Read the note first**: Use `read_note("{identifier}")` to see how many times '{find_text}' appears 2. **Update expected_replacements**: Set expected_replacements={actual_count} in your edit_note call 3. **Be more specific**: If you only want to replace some occurrences, make your find_text more specific ## Example: ``` edit_note("{identifier}", "find_replace", "new_text", find_text="{find_text}", expected_replacements={actual_count}) ```""" # Section replacement errors if operation == "replace_section" and "Multiple sections" in error_message: return f"""# Edit Failed - Duplicate Section Headers Multiple sections found with the same header in note '{identifier}'. ## How to fix: 1. **Read the note first**: Use `read_note("{identifier}")` to see the document structure 2. **Make headers unique**: Add more specific text to distinguish sections 3. **Use append instead**: Add content at the end rather than replacing a specific section ## Alternative approach: Use `find_replace` to update specific text within the duplicate sections.""" # Generic server/request errors if ( "Invalid request" in error_message or "malformed" in error_message.lower() ): # pragma: no cover return f"""# Edit Failed - Request Error There was a problem with the edit request to note '{identifier}': {error_message}. ## Common causes and fixes: 1. **Note doesn't exist**: Use `search_notes()` or `read_note()` to verify the note exists 2. **Invalid identifier format**: Try different identifier formats (title vs permalink) 3. **Empty or invalid content**: Check that your content is properly formatted 4. **Server error**: Try the operation again, or use `read_note()` first to verify the note state ## Troubleshooting steps: 1. Verify the note exists: `read_note("{identifier}")` 2. If not found, search for it: `search_notes("{identifier.split("/")[-1]}")` 3. Try again with the correct identifier from the search results""" # Fallback for other errors return f"""# Edit Failed Error editing note '{identifier}': {error_message} ## General troubleshooting: 1. **Verify the note exists**: Use `read_note("{identifier}")` to check 2. **Check your parameters**: Ensure all required parameters are provided correctly 3. **Read the note content first**: Use `read_note()` to understand the current structure 4. **Try a simpler operation**: Start with `append` if other operations fail ## Need help? - Use `search_notes()` to find notes - Use `read_note()` to examine content before editing - Check that identifiers, section headers, and find_text match exactly""" @mcp.tool( description="Edit an existing markdown note using various operations like append, prepend, find_replace, or replace_section.", ) async def edit_note( identifier: str, operation: str, content: str, section: Optional[str] = None, find_text: Optional[str] = None, expected_replacements: int = 1, project: Optional[str] = None, ) -> str: """Edit an existing markdown note in the knowledge base. This tool allows you to make targeted changes to existing notes without rewriting the entire content. It supports various operations for different editing scenarios. Args: identifier: The exact title, permalink, or memory:// URL of the note to edit. Must be an exact match - fuzzy matching is not supported for edit operations. Use search_notes() or read_note() first to find the correct identifier if uncertain. operation: The editing operation to perform: - "append": Add content to the end of the note - "prepend": Add content to the beginning of the note - "find_replace": Replace occurrences of find_text with content - "replace_section": Replace content under a specific markdown header content: The content to add or use for replacement section: For replace_section operation - the markdown header to replace content under (e.g., "## Notes", "### Implementation") find_text: For find_replace operation - the text to find and replace expected_replacements: For find_replace operation - the expected number of replacements (validation will fail if actual doesn't match) project: Optional project name to delete from. If not provided, uses current active project. Returns: A markdown formatted summary of the edit operation and resulting semantic content Examples: # Add new content to end of note edit_note("project-planning", "append", "\\n## New Requirements\\n- Feature X\\n- Feature Y") # Add timestamp at beginning (frontmatter-aware) edit_note("meeting-notes", "prepend", "## 2025-05-25 Update\\n- Progress update...\\n\\n") # Update version number (single occurrence) edit_note("config-spec", "find_replace", "v0.13.0", find_text="v0.12.0") # Update version in multiple places with validation edit_note("api-docs", "find_replace", "v2.1.0", find_text="v2.0.0", expected_replacements=3) # Replace text that appears multiple times - validate count first edit_note("docs/guide", "find_replace", "new-api", find_text="old-api", expected_replacements=5) # Replace implementation section edit_note("api-spec", "replace_section", "New implementation approach...\\n", section="## Implementation") # Replace subsection with more specific header edit_note("docs/setup", "replace_section", "Updated install steps\\n", section="### Installation") # Using different identifier formats (must be exact matches) edit_note("Meeting Notes", "append", "\\n- Follow up on action items") # exact title edit_note("docs/meeting-notes", "append", "\\n- Follow up tasks") # exact permalink edit_note("docs/Meeting Notes", "append", "\\n- Next steps") # exact folder/title # If uncertain about identifier, search first: # search_notes("meeting") # Find available notes # edit_note("docs/meeting-notes-2025", "append", "content") # Use exact result # Add new section to document edit_note("project-plan", "replace_section", "TBD - needs research\\n", section="## Future Work") # Update status across document (expecting exactly 2 occurrences) edit_note("status-report", "find_replace", "In Progress", find_text="Not Started", expected_replacements=2) # Replace text in a file, specifying project name edit_note("docs/guide", "find_replace", "new-api", find_text="old-api", project="my-project")) """ active_project = get_active_project(project) project_url = active_project.project_url logger.info("MCP tool call", tool="edit_note", identifier=identifier, operation=operation) # Validate operation valid_operations = ["append", "prepend", "find_replace", "replace_section"] if operation not in valid_operations: raise ValueError( f"Invalid operation '{operation}'. Must be one of: {', '.join(valid_operations)}" ) # Validate required parameters for specific operations if operation == "find_replace" and not find_text: raise ValueError("find_text parameter is required for find_replace operation") if operation == "replace_section" and not section: raise ValueError("section parameter is required for replace_section operation") # Use the PATCH endpoint to edit the entity try: # Prepare the edit request data edit_data = { "operation": operation, "content": content, } # Add optional parameters if section: edit_data["section"] = section if find_text: edit_data["find_text"] = find_text if expected_replacements != 1: # Only send if different from default edit_data["expected_replacements"] = str(expected_replacements) # Call the PATCH endpoint url = f"{project_url}/knowledge/entities/{identifier}" response = await call_patch(client, url, json=edit_data) result = EntityResponse.model_validate(response.json()) # Format summary summary = [ f"# Edited note ({operation})", f"project: {active_project.name}", f"file_path: {result.file_path}", f"permalink: {result.permalink}", f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}", ] # Add operation-specific details if operation == "append": lines_added = len(content.split("\n")) summary.append(f"operation: Added {lines_added} lines to end of note") elif operation == "prepend": lines_added = len(content.split("\n")) summary.append(f"operation: Added {lines_added} lines to beginning of note") elif operation == "find_replace": # For find_replace, we can't easily count replacements from here # since we don't have the original content, but the server handled it summary.append("operation: Find and replace operation completed") elif operation == "replace_section": summary.append(f"operation: Replaced content under section '{section}'") # Count observations by category (reuse logic from write_note) categories = {} if result.observations: for obs in result.observations: categories[obs.category] = categories.get(obs.category, 0) + 1 summary.append("\\n## Observations") for category, count in sorted(categories.items()): summary.append(f"- {category}: {count}") # Count resolved/unresolved relations unresolved = 0 resolved = 0 if result.relations: unresolved = sum(1 for r in result.relations if not r.to_id) resolved = len(result.relations) - unresolved summary.append("\\n## Relations") summary.append(f"- Resolved: {resolved}") if unresolved: summary.append(f"- Unresolved: {unresolved}") logger.info( "MCP tool response", tool="edit_note", operation=operation, permalink=result.permalink, observations_count=len(result.observations), relations_count=len(result.relations), status_code=response.status_code, ) return "\n".join(summary) except Exception as e: logger.error(f"Error editing note: {e}") return _format_error_response( str(e), operation, identifier, find_text, expected_replacements )