joplin-mcp-server

Instructions

Implementation Reference

• src/lib/tools/read-multi-note.ts:3-125 (handler)

  The ReadMultiNote class extending BaseTool. The `call` method implements the core tool logic: validates note IDs, fetches each note and its parent notebook from Joplin API, formats metadata (title, location, todo status, timestamps), note body in Markdown, handles not found/errors, and returns a structured summary.
  class ReadMultiNote extends BaseTool { async call(noteIds: string[]): Promise<string> { if (!noteIds || !Array.isArray(noteIds) || noteIds.length === 0) { return 'Please provide an array of note IDs. Example: read_multinote note_ids=["id1", "id2", "id3"]' } // Validate that all IDs look like valid note IDs const invalidIds = noteIds.filter((id) => !id || id.length < 10 || !id.match(/[a-f0-9]/i)) if (invalidIds.length > 0) { return `Error: Some IDs do not appear to be valid note IDs: ${invalidIds.join(", ")}\n\nNote IDs are long alphanumeric strings like "58a0a29f68bc4141b49c99f5d367638a".\n\nUse search_notes to find notes and their IDs.` } const resultLines: string[] = [] const notFound: string[] = [] const errors: string[] = [] const successful: string[] = [] // Add a header resultLines.push(`# Reading ${noteIds.length} notes\n`) // Process each note ID for (let i = 0; i < noteIds.length; i++) { const noteId = noteIds[i] resultLines.push(`## Note ${i + 1} of ${noteIds.length} (ID: ${noteId})\n`) try { // Get the note details with all relevant fields const note = await this.apiClient.get<JoplinNote>(`/notes/${noteId}`, { query: { fields: "id,title,body,parent_id,created_time,updated_time,is_todo,todo_completed,todo_due", }, }) // Validate note response if (!note || typeof note !== "object" || !note.id) { errors.push(noteId) resultLines.push(`Error: Unexpected response format from Joplin API when fetching note ${noteId}\n`) continue } successful.push(noteId) // Get the notebook info to show where this note is located let notebookInfo = "Unknown notebook" if (note.parent_id) { try { const notebook = await this.apiClient.get<JoplinFolder>(`/folders/${note.parent_id}`, { query: { fields: "id,title" }, }) if (notebook && notebook.title) { notebookInfo = `"${notebook.title}" (notebook_id: "${note.parent_id}")` } } catch (err: unknown) { process.stderr.write(`Error fetching notebook info for note ${noteId}: ${err}\n`) // Continue even if we can't get the notebook info } } // Add note metadata resultLines.push(`### Note: "${note.title}"`) resultLines.push(`Notebook: ${notebookInfo}`) // Add todo status if applicable if (note.is_todo) { const status = note.todo_completed ? "Completed" : "Not completed" resultLines.push(`Status: ${status}`) if (note.todo_due) { const dueDate = this.formatDate(note.todo_due) resultLines.push(`Due: ${dueDate}`) } } // Add timestamps const createdDate = this.formatDate(note.created_time) const updatedDate = this.formatDate(note.updated_time) resultLines.push(`Created: ${createdDate}`) resultLines.push(`Updated: ${updatedDate}`) // Add a separator before the note content resultLines.push("\n---\n") // Add the note body if (note.body) { resultLines.push(note.body) } else { resultLines.push("(This note has no content)") } // Add a separator after the note resultLines.push("\n---\n") } catch (error: any) { process.stderr.write(`Error reading note ${noteId}: ${error}\n`) if (error.response && error.response.status === 404) { notFound.push(noteId) resultLines.push(`Note with ID "${noteId}" not found.\n`) } else { errors.push(noteId) resultLines.push(`Error reading note: ${error.message || "Unknown error"}\n`) } } } // Add a summary at the end resultLines.push("# Summary") resultLines.push(`Total notes requested: ${noteIds.length}`) resultLines.push(`Successfully retrieved: ${successful.length}`) if (notFound.length > 0) { resultLines.push(`Notes not found: ${notFound.length}`) resultLines.push(`IDs not found: ${notFound.join(", ")}`) } if (errors.length > 0) { resultLines.push(`Errors encountered: ${errors.length}`) resultLines.push(`IDs with errors: ${errors.join(", ")}`) } return resultLines.join("\n") } } export default ReadMultiNote
• src/server-fastmcp.ts:95-97 (schema)

  Zod input schema for read_multinote tool: requires `note_ids` as array of strings.
  parameters: z.object({ note_ids: z.array(z.string()).describe("Array of note IDs to read"), }),
• src/server-fastmcp.ts:92-101 (registration)

  Registration of the read_multinote tool in the FastMCP server using server.addTool, including name, description, schema, and execute handler delegating to manager.
  server.addTool({ name: "read_multinote", description: "Read the full content of multiple notes at once", parameters: z.object({ note_ids: z.array(z.string()).describe("Array of note IDs to read"), }), execute: async (args) => { return await manager.readMultiNote(args.note_ids) }, })
• src/index.ts:123-129 (schema)

  JSON input schema for read_multinote tool in stdio MCP server listTools response.
  inputSchema: { type: "object", properties: { note_ids: { type: "array", items: { type: "string" }, description: "Array of note IDs to read" }, }, required: ["note_ids"], },
• src/index.ts:245-248 (registration)

  Tool dispatch/registration in stdio server CallToolRequest handler switch statement, delegating to manager.readMultiNote.
  case "read_multinote": { const multiResult = await manager.readMultiNote(args.note_ids as string[]) return { content: [{ type: "text", text: multiResult }], isError: false } }