joplin-mcp-server

Instructions

Implementation Reference

• src/lib/tools/create-folder.ts:13-98 (handler)

  The core handler implementation: CreateFolder class with async call() method that validates input, calls Joplin API to create folder, handles parent info, errors, and formats a rich success response.
  class CreateFolder extends BaseTool { async call(options: CreateFolderOptions): Promise<string> { if (!options || typeof options !== "object") { return 'Please provide folder creation options. Example: create_folder {"title": "My Notebook"}' } // Validate required title if (!options.title || typeof options.title !== "string" || options.title.trim() === "") { return 'Please provide a title for the folder/notebook. Example: create_folder {"title": "My Notebook"}' } // Validate parent_id if provided if (options.parent_id && (options.parent_id.length < 10 || !options.parent_id.match(/[a-f0-9]/i))) { return `Error: "${options.parent_id}" does not appear to be a valid parent notebook ID.\n\nNotebook IDs are long alphanumeric strings like "58a0a29f68bc4141b49c99f5d367638a".\n\nUse list_notebooks to see available notebooks and their IDs, or omit parent_id to create a top-level notebook.` } try { // Prepare the request body const requestBody: CreateFolderOptions = { title: options.title.trim(), } if (options.parent_id) { requestBody.parent_id = options.parent_id } // Create the folder const createdFolder = await this.apiClient.post<CreateFolderResponse>("/folders", requestBody) // Validate response if (!createdFolder || typeof createdFolder !== "object" || !createdFolder.id) { return "Error: Unexpected response format from Joplin API when creating folder" } // Get parent notebook info if available let parentInfo = "Top level" if (createdFolder.parent_id) { try { const parentNotebook = await this.apiClient.get(`/folders/${createdFolder.parent_id}`, { query: { fields: "id,title" }, }) if (parentNotebook && parentNotebook.title) { parentInfo = `Inside "${parentNotebook.title}" (notebook_id: "${createdFolder.parent_id}")` } } catch { // Continue even if we can't get parent info parentInfo = `Parent notebook ID: ${createdFolder.parent_id}` } } // Format success response const resultLines: string[] = [] resultLines.push(`✅ Successfully created notebook!`) resultLines.push("") resultLines.push(`📁 Notebook Details:`) resultLines.push(` Title: "${createdFolder.title}"`) resultLines.push(` Notebook ID: ${createdFolder.id}`) resultLines.push(` Location: ${parentInfo}`) const createdDate = this.formatDate(createdFolder.created_time) resultLines.push(` Created: ${createdDate}`) resultLines.push("") resultLines.push(`🔗 Next steps:`) resultLines.push(` - View notebook: read_notebook notebook_id="${createdFolder.id}"`) resultLines.push(` - Create a note in it: create_note {"title": "My Note", "parent_id": "${createdFolder.id}"}`) resultLines.push(` - View all notebooks: list_notebooks`) return resultLines.join("\n") } catch (error: any) { if (error.response) { // Handle specific API errors if (error.response.status === 400) { return `Error creating notebook: Invalid request data.\n\nPlease check your input parameters. ${error.response.data?.error || ""}` } if (error.response.status === 404 && options.parent_id) { return `Error: Parent notebook with ID "${options.parent_id}" not found.\n\nUse list_notebooks to see available notebooks and their IDs, or omit parent_id to create a top-level notebook.` } if (error.response.status === 409) { return `Error: A notebook with the title "${options.title}" might already exist in this location.\n\nTry a different title or check existing notebooks with list_notebooks.` } } return this.formatError(error, "creating notebook") } } }
• src/server-fastmcp.ts:120-131 (registration)

  MCP tool registration in FastMCP server: defines name 'create_folder', description, Zod input schema, and execute handler delegating to JoplinServerManager.createFolder.
  // Add create_folder tool server.addTool({ name: "create_folder", description: "Create a new folder/notebook in Joplin", parameters: z.object({ title: z.string().describe("Notebook title"), parent_id: z.string().optional().describe("ID of parent notebook"), }), execute: async (args) => { return await manager.createFolder(args) }, })
• src/lib/tools/create-folder.ts:3-6 (schema)

  TypeScript interface defining input parameters for the create_folder tool (title required, parent_id optional).
  interface CreateFolderOptions { title: string parent_id?: string | undefined }
• src/server-core.ts:46-58 (registration)

  Instantiation and registration of CreateFolder tool instance within JoplinServerManager's tools object.
  this.tools = { listNotebooks: new ListNotebooks(this.apiClient), searchNotes: new SearchNotes(this.apiClient), readNotebook: new ReadNotebook(this.apiClient), readNote: new ReadNote(this.apiClient), readMultiNote: new ReadMultiNote(this.apiClient), createNote: new CreateNote(this.apiClient), createFolder: new CreateFolder(this.apiClient), editNote: new EditNote(this.apiClient), editFolder: new EditFolder(this.apiClient), deleteNote: new DeleteNote(this.apiClient), deleteFolder: new DeleteFolder(this.apiClient), }
• src/server-core.ts:97-99 (registration)

  JoplinServerManager.createFolder method that delegates execution to the CreateFolder tool's call method.
  async createFolder(params: { title: string; parent_id?: string | undefined }): Promise<string> { return await this.tools.createFolder.call(params) }