joplin-mcp-server

Instructions

Implementation Reference

• src/lib/tools/delete-folder.ts:13-165 (handler)

  The DeleteFolder class extending BaseTool contains the core execution logic for the delete_folder tool. It handles input validation, confirmation prompts, checks folder contents, warns about non-empty folders, performs safety checks, and executes the Joplin API deletion (/folders/{id}). Includes force delete option and detailed success/error responses.
  class DeleteFolder extends BaseTool { async call(options: DeleteFolderOptions): Promise<string> { if (!options || typeof options !== "object") { return 'Please provide folder deletion options. Example: delete_folder {"folder_id": "abc123", "confirm": true}' } // Validate required folder_id if (!options.folder_id) { return 'Please provide folder deletion options. Example: delete_folder {"folder_id": "abc123", "confirm": true}' } const folderIdError = this.validateId(options.folder_id, "notebook") if (folderIdError) { return folderIdError.replace("notebook ID", "folder ID").replace("notebook_id", "folder_id") } // Require explicit confirmation for safety if (!options.confirm) { return `⚠️ This will permanently delete the notebook/folder!\n\nTo confirm deletion, use:\ndelete_folder {"folder_id": "${options.folder_id}", "confirm": true}\n\n⚠️ This action cannot be undone!` } try { // First, get the folder details to show what's being deleted const folderToDelete = await this.apiClient.get<JoplinFolder>(`/folders/${options.folder_id}`, { query: { fields: "id,title,parent_id" }, }) if (!folderToDelete || !folderToDelete.id) { return `Folder with ID "${options.folder_id}" not found.\n\nUse list_notebooks to see available folders and their IDs.` } // Check if folder contains notes or subfolders const [notes, subfolders] = await Promise.all([ this.apiClient .get<FolderContents>(`/folders/${options.folder_id}/notes`, { query: { fields: "id,title" }, }) .catch(() => ({ items: [] })), this.apiClient .get<FolderContents>("/folders", { query: { fields: "id,title,parent_id" }, }) .then((response) => ({ items: response.items?.filter((folder: any) => folder.parent_id === options.folder_id) || [], })) .catch(() => ({ items: [] })), ]) const noteCount = notes.items?.length || 0 const subfolderCount = subfolders.items?.length || 0 const totalContent = noteCount + subfolderCount // Warn if folder is not empty and force is not specified if (totalContent > 0 && !options.force) { const resultLines: string[] = [] resultLines.push(`⚠️ Cannot delete non-empty notebook!`) resultLines.push("") resultLines.push(`📁 Notebook: "${folderToDelete.title}"`) resultLines.push(` Contains: ${noteCount} notes and ${subfolderCount} subfolders`) if (noteCount > 0) { resultLines.push("") resultLines.push(`📝 Contains ${noteCount} notes:`) notes.items.slice(0, 5).forEach((note: any) => { resultLines.push(` - ${note.title || "Untitled"}`) }) if (noteCount > 5) { resultLines.push(` ... and ${noteCount - 5} more notes`) } } if (subfolderCount > 0) { resultLines.push("") resultLines.push(`📁 Contains ${subfolderCount} subfolders:`) subfolders.items.slice(0, 5).forEach((folder: any) => { resultLines.push(` - ${folder.title}`) }) if (subfolderCount > 5) { resultLines.push(` ... and ${subfolderCount - 5} more folders`) } } resultLines.push("") resultLines.push(`💡 Options:`) resultLines.push(` 1. Move or delete the contents first, then delete the folder`) resultLines.push(` 2. Force delete (⚠️ DESTROYS ALL CONTENT):`) resultLines.push(` delete_folder {"folder_id": "${options.folder_id}", "confirm": true, "force": true}`) resultLines.push("") resultLines.push(`⚠️ Force delete will permanently delete ALL ${totalContent} items inside!`) return resultLines.join("\n") } // Get parent folder info if available let parentInfo = "Top level" if (folderToDelete.parent_id) { try { const parentFolder = await this.apiClient.get(`/folders/${folderToDelete.parent_id}`, { query: { fields: "title" }, }) if (parentFolder?.title) { parentInfo = `Inside "${parentFolder.title}" (notebook_id: "${folderToDelete.parent_id}")` } } catch { parentInfo = `Parent ID: ${folderToDelete.parent_id}` } } // Delete the folder await this.apiClient.delete(`/folders/${options.folder_id}`) // Format success response const resultLines: string[] = [] resultLines.push(`🗑️ Successfully deleted notebook!`) resultLines.push("") resultLines.push(`📁 Deleted Notebook Details:`) resultLines.push(` Title: "${folderToDelete.title}"`) resultLines.push(` Folder ID: ${folderToDelete.id}`) resultLines.push(` Location: ${parentInfo}`) if (totalContent > 0) { resultLines.push(` Deleted Content: ${noteCount} notes and ${subfolderCount} subfolders`) resultLines.push("") resultLines.push(`⚠️ All ${totalContent} items inside have been permanently deleted!`) } resultLines.push("") resultLines.push(`⚠️ This notebook has been permanently deleted and cannot be recovered.`) if (folderToDelete.parent_id) { resultLines.push("") resultLines.push(`🔗 Related actions:`) resultLines.push(` - View parent notebook: read_notebook notebook_id="${folderToDelete.parent_id}"`) resultLines.push(` - View all notebooks: list_notebooks`) } return resultLines.join("\n") } catch (error: any) { if (error.response) { if (error.response.status === 404) { return `Folder with ID "${options.folder_id}" not found.\n\nUse list_notebooks to see available folders and their IDs.` } if (error.response.status === 403) { return `Permission denied: Cannot delete folder with ID "${options.folder_id}".\n\nThis might be a protected system folder.` } if (error.response.status === 409) { return `Cannot delete folder: It may contain items that prevent deletion.\n\nTry moving or deleting the contents first, or use force option.` } } return this.formatError(error, "deleting folder") } } }
• src/lib/tools/delete-folder.ts:3-7 (schema)

  Interface defining the input schema for the delete_folder tool: required folder_id, optional confirm and force flags.
  interface DeleteFolderOptions { folder_id: string confirm?: boolean | undefined force?: boolean | undefined }
• src/index.ts:202-213 (registration)

  Tool registration in stdio MCP server: schema definition in listTools response.
  name: "delete_folder", description: "Delete a folder/notebook from Joplin (requires confirmation)", inputSchema: { type: "object", properties: { folder_id: { type: "string", description: "ID of the folder to delete" }, confirm: { type: "boolean", description: "Confirmation flag" }, force: { type: "boolean", description: "Force delete even if folder has contents" }, }, required: ["folder_id"], }, },
• src/index.ts:311-319 (registration)

  Dispatch handler in stdio MCP server callToolRequest: routes delete_folder calls to manager.deleteFolder.
  case "delete_folder": { const deleteFolderResult = await manager.deleteFolder( args as { folder_id: string confirm?: boolean | undefined force?: boolean | undefined }, ) return { content: [{ type: "text", text: deleteFolderResult }], isError: false }
• src/server-fastmcp.ts:180-191 (registration)

  Tool registration in FastMCP HTTP server using server.addTool with Zod schema and execute handler.
  server.addTool({ name: "delete_folder", description: "Delete a folder/notebook from Joplin (requires confirmation)", parameters: z.object({ folder_id: z.string().describe("ID of the folder to delete"), confirm: z.boolean().optional().describe("Confirmation flag"), force: z.boolean().optional().describe("Force delete even if folder has contents"), }), execute: async (args) => { return await manager.deleteFolder(args) }, })
• src/server-core.ts:57-57 (registration)

  Instantiation of DeleteFolder tool instance in JoplinServerManager for use by both stdio and HTTP servers.
  deleteFolder: new DeleteFolder(this.apiClient),