feat(trash): list_trash/restore/purge_trash MCP tools + register + instructions

src/fabledassistant/mcp/server.py

@@ -53,6 +53,12 @@ title) — that seeds a plan template and returns the project's applicable_rules
 Maintain the plan with the normal task tools (update_task for the body,
 add_task_log for progress); its work-logs are the build record. Build plans in
 Scribe via start_planning, not in local .md files.
+
+Deletes are recoverable: every delete_* tool moves the entity (and its
+descendants) to the trash and returns a deleted_batch_id. Use list_trash() to
+see trashed batches, restore(deleted_batch_id) to undo a deletion, and
+purge_trash(deleted_batch_id, confirmed=True) for a permanent delete. Trash
+auto-purges after the operator's retention window.
 """
 
 

src/fabledassistant/mcp/tools/__init__.py

@@ -5,7 +5,7 @@ to a FastMCP instance. `register_all(mcp)` is the single entry point called
 from `mcp.server.build_mcp_server`.
 """
 from fabledassistant.mcp.tools import (
-    entities, events, milestones, notes, projects, recent, rulebooks, search, tags, tasks,
+    entities, events, milestones, notes, projects, recent, rulebooks, search, tags, tasks, trash,
 )
 
 
@@ -21,3 +21,4 @@ def register_all(mcp) -> None:
     recent.register(mcp)
     entities.register(mcp)
     rulebooks.register(mcp)
+    trash.register(mcp)

src/fabledassistant/mcp/tools/trash.py

@@ -0,0 +1,48 @@
+"""Trash MCP tools — unified, batch-based recovery surface.
+
+Deletes go through the per-type delete_* tools (which soft-delete via the trash
+service). These tools list / restore / permanently-purge trashed content by
+the deleted_batch_id that a delete operation returns.
+"""
+from __future__ import annotations
+
+from fabledassistant.mcp._context import current_user_id
+from fabledassistant.services import trash as trash_svc
+
+
+async def list_trash() -> dict:
+    """List trashed items, grouped by the deletion batch they were removed in.
+
+    Each batch has: batch_id, deleted_at, a summary (the lead item's title),
+    count, and the member items (type + id + title). Restore a batch with
+    restore(deleted_batch_id).
+    """
+    return {"batches": await trash_svc.list_trash(current_user_id())}
+
+
+async def restore(deleted_batch_id: str) -> dict:
+    """Restore a whole deletion batch from the trash (un-delete)."""
+    n = await trash_svc.restore(current_user_id(), deleted_batch_id)
+    return {"restored": n, "batch_id": deleted_batch_id}
+
+
+async def purge_trash(deleted_batch_id: str, confirmed: bool = False) -> dict:
+    """Permanently delete a trashed batch. IRREVERSIBLE — pass confirmed=True.
+
+    This is the only true hard-delete tool; everything else is recoverable.
+    """
+    if not confirmed:
+        return {
+            "warning": (
+                f"Permanently delete batch {deleted_batch_id}? This cannot be "
+                f"undone. Pass confirmed=True to proceed."
+            ),
+            "confirmed_required": True,
+        }
+    n = await trash_svc.purge(current_user_id(), deleted_batch_id)
+    return {"purged": n, "batch_id": deleted_batch_id}
+
+
+def register(mcp) -> None:
+    for fn in (list_trash, restore, purge_trash):
+        mcp.tool(name=fn.__name__)(fn)