joplin-mcp-server

Instructions

Implementation Reference

• src/lib/tools/read-notebook.ts:7-84 (handler)

  The ReadNotebook class extending BaseTool implements the core execution logic for the read_notebook tool. The `call` method fetches notebook details, retrieves its notes, sorts them by update time, and formats a response listing all notes with instructions.

  class ReadNotebook extends BaseTool {
    async call(notebookId: string): Promise<string> {
      const validationError = this.validateId(notebookId, "notebook")
      if (validationError) {
        return validationError
      }
  
      try {
        // First, get the notebook details
        const notebook = await this.apiClient.get<JoplinFolder>(`/folders/${notebookId}`, {
          query: { fields: "id,title,parent_id" },
        })
  
        // Validate notebook response
        if (!notebook || typeof notebook !== "object" || !notebook.id) {
          return `Error: Unexpected response format from Joplin API when fetching notebook`
        }
  
        // Get all notes in this notebook
        const notes = await this.apiClient.get<NotebookNotesResponse>(`/folders/${notebookId}/notes`, {
          query: { fields: "id,title,updated_time,is_todo,todo_completed" },
        })
  
        // Validate notes response
        if (!notes || typeof notes !== "object") {
          return `Error: Unexpected response format from Joplin API when fetching notes`
        }
  
        if (!notes.items || !Array.isArray(notes.items) || notes.items.length === 0) {
          return `Notebook "${notebook.title}" (notebook_id: "${notebook.id}") is empty.\n\nTry another notebook ID or use list_notebooks to see all available notebooks.`
        }
  
        // Format the notebook contents
        const resultLines: string[] = []
        resultLines.push(`# Notebook: "${notebook.title}" (notebook_id: "${notebook.id}")`)
        resultLines.push(`Contains ${notes.items.length} notes:\n`)
        resultLines.push(`NOTE: This is showing the contents of notebook "${notebook.title}", not a specific note.\n`)
  
        // If multiple notes were found, add a hint about read_multinote
        if (notes.items.length > 1) {
          const noteIds = notes.items.map((note) => note.id)
          resultLines.push(`TIP: To read all ${notes.items.length} notes at once, use:\n`)
          resultLines.push(`read_multinote note_ids=${JSON.stringify(noteIds)}\n`)
        }
  
        // Sort notes by updated_time (newest first)
        const sortedNotes = [...notes.items].sort((a, b) => b.updated_time - a.updated_time)
  
        sortedNotes.forEach((note) => {
          const updatedDate = this.formatDate(note.updated_time)
  
          // Add checkbox for todos
          if (note.is_todo) {
            const checkboxStatus = note.todo_completed ? "✅" : "☐"
            resultLines.push(`- ${checkboxStatus} Note: "${note.title}" (note_id: "${note.id}")`)
          } else {
            resultLines.push(`- Note: "${note.title}" (note_id: "${note.id}")`)
          }
  
          resultLines.push(`  Updated: ${updatedDate}`)
          resultLines.push(`  To read this note: read_note note_id="${note.id}"`)
          resultLines.push("") // Empty line between notes
        })
  
        return resultLines.join("\n")
      } catch (error: any) {
        if (error.response && error.response.status === 404) {
          return `Notebook with ID "${notebookId}" not found.\n\nThis might happen if:\n1. The ID is incorrect\n2. You're using a note title instead of a notebook ID\n3. The notebook has been deleted\n\nUse list_notebooks to see all available notebooks with their IDs.`
        }
        return (
          this.formatError(error, "reading notebook") +
          `\n\nMake sure you're using a valid notebook ID, not a note title.\nUse list_notebooks to see all available notebooks with their IDs.`
        )
      }
    }
  }
  
  export default ReadNotebook

• src/index.ts:98-107 (schema)

  Input schema definition for the read_notebook tool in the stdio MCP server list tools response.

  {
    name: "read_notebook",
    description: "Read the contents of a specific notebook",
    inputSchema: {
      type: "object",
      properties: {
        notebook_id: { type: "string", description: "ID of the notebook to read" },
      },
      required: ["notebook_id"],
    },

• src/index.ts:235-238 (registration)

  Tool dispatch handler in stdio MCP server that calls manager.readNotebook for read_notebook.

  case "read_notebook": {
    const notebookResult = await manager.readNotebook(args.notebook_id as string)
    return { content: [{ type: "text", text: notebookResult }], isError: false }
  }

• src/server-fastmcp.ts:68-77 (registration)

  Registration of read_notebook tool in FastMCP server including schema (Zod) and execute handler calling manager.readNotebook.

  server.addTool({
    name: "read_notebook",
    description: "Read the contents of a specific notebook",
    parameters: z.object({
      notebook_id: z.string().describe("ID of the notebook to read"),
    }),
    execute: async (args) => {
      return await manager.readNotebook(args.notebook_id)
    },
  })

• src/server-core.ts:46-58 (helper)

  Instantiation of ReadNotebook tool instance in JoplinServerManager for use by manager.readNotebook method.

  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),
  }