list_trash
Display and manage deleted documents in the MCP Outline Server. Use this tool to find, review, and restore documents from the trash or verify deletions before permanent removal.
Instructions
Displays all documents currently in the trash.
Use this tool when you need to:
- Find deleted documents that can be restored
- Review what documents are pending permanent deletion
- Identify documents to restore from trash
- Verify if specific documents were deleted
Returns:
Formatted string containing list of documents in trash
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- The primary handler function for the 'list_trash' MCP tool. It uses the Outline client to list trash documents, formats the output using a helper function, and handles client and unexpected errors gracefully.@mcp.tool( annotations=ToolAnnotations( readOnlyHint=True, destructiveHint=False, idempotentHint=True ) ) async def list_trash() -> str: """ Displays all documents currently in the trash. Use this tool when you need to: - Find deleted documents that can be restored - Review what documents are pending permanent deletion - Identify documents to restore from trash - Verify if specific documents were deleted Returns: Formatted string containing list of documents in trash """ try: client = await get_outline_client() documents = await client.list_trash() from mcp_outline.features.documents.document_search import ( _format_documents_list, ) return _format_documents_list(documents, "Documents in Trash") except OutlineClientError as e: return f"Error listing trash: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}"
- The register_tools function that defines and registers all document lifecycle tools (including list_trash) with the MCP server using decorators. This function is called to set up the tools.def register_tools(mcp) -> None: """ Register document lifecycle tools with the MCP server.
- The OutlineClient.list_trash method, which performs the API call to retrieve documents from the trash. Called by the tool handler.async def list_trash(self, limit: int = 25) -> List[Dict[str, Any]]: """ List documents in the trash. Args: limit: Maximum number of results to return Returns: List of documents in trash """ response = await self.post( "documents.list", {"limit": limit, "deleted": True} ) return response.get("data", [])
- Utility function to format a list of documents (used for trash listing) into a markdown-formatted string with titles, IDs, and update times.def _format_documents_list(documents: List[Dict[str, Any]], title: str) -> str: """Format a list of documents into readable text.""" if not documents: return f"No {title.lower()} found." output = f"# {title}\n\n" for i, document in enumerate(documents, 1): doc_title = document.get("title", "Untitled") doc_id = document.get("id", "") updated_at = document.get("updatedAt", "") output += f"## {i}. {doc_title}\n" output += f"ID: {doc_id}\n" if updated_at: output += f"Last Updated: {updated_at}\n" output += "\n" return output